Under the hood

Shared primitives catalog

Shared primitives catalog

Before writing any helper, scan these tables first. Most “I need a small string transform / id helper / md coercion / tree walk” needs already have an owner here — the cost of finding the existing one is a grep; the cost of missing it shows up later as drift between two parallel implementations (the user is the one who hits the divergence).

This page is the index. The tables live in three parts, split by responsibility. Grep all four files together — they are one catalog:

grep -n 'the_symbol' docs/shared-primitives.md docs/primitives-*.md

The catalog is mirrored (in condensed, review-checklist form) at .github/instructions/shared-primitives.instructions.md, a path-scoped Copilot instruction file (applyTo: crates/**). When you edit any part, sync that mirror — a PostToolUse hook flags drift, but the discipline starts before the hook fires.

For the reuse-first rule (why this matters, past drift incidents, what to do when a primitive doesn’t exist yet), see Contributing → Reuse-first.

The three parts

PartCoversRead it when
Core state, sync, and durabilityop log, CRDT tree, HLC, ids, sync engine + transports, locks, Storage trait, local backupsyou’re about to mutate or read converged workspace state
Markdown pipelineparse, render, external coercion + ingest, reconcile / matching / diff, sidecar, outline AST helpers, indices, inline tokenizers, assetsyou’re about to read or write .md / .outl
Editing actions and client featuresblock mutations, pages + journals, backlinks, code execution, undo/redo, templates, reminders, @outl/sharedyou’re wiring a client gesture to a workspace change

Full section index

Core state, sync, and durability

  1. Workspace lifecycle, op log, and HLC (outl-core)
  2. Tree reads (outl-core + outl-actions::tree)
  3. Sync engine, locks, storage trait
  4. Local backups (outl-actions::backup)

Markdown pipeline

  1. Parse / render (outl-md::parse + render)
  2. External markdown coercion & ingest (outl-md::frontmatter + wikilink, outl-actions::paste + ingest)
  3. Reconcile & matching (outl-md::reconcile + matching + diff)
  4. Sidecar (outl-md::sidecar + atomic)
  5. In-flight outline AST helpers (outl-md::outline_ops)
  6. Indices and search (outl-md::index + block_index)
  7. View helpers for editors (outl-md::view + inline)
  8. Asset links (outl-md::asset + outl-actions::asset)

Editing actions and client features

  1. Block mutations (outl-actions::block + collapsed + todo + quote)
  2. Pages and journals (outl-actions::page + journal)
  3. Backlinks (outl-actions::backlinks)
  4. Code-block execution (outl-actions::exec)
  5. Undo / redo history (outl-actions::history)
  6. Templates
  7. Reminders (remind::)
  8. Frontend shared primitives (@outl/shared)

When your need isn’t in this catalog

If you’ve grepped honestly and the primitive doesn’t exist, that’s a fair sign — add it in the upstream crate that owns the concept:

  • outl-md for parse / render / sidecar / inline / tokenizers
  • outl-actions for workspace mutations, ingest, page/journal helpers
  • outl-core for op-log / tree / HLC / storage trait

Then add its row to the matching part in the same commit, and sync the mirror at .github/instructions/shared-primitives.instructions.md. The PostToolUse hook will flag drift, but the discipline starts before the hook fires.

For the broader reuse-first rule and past drift incidents that justify this catalog, see Contributing → Reuse-first.