outl shared-primitives.instructions.md

Shared primitives catalog

The catalog is indexed at docs/shared-primitives.md. Its rows live in primitives-core.md, primitives-markdown.md and primitives-actions.md; the index says which part owns what. Before approving a helper, grep all four (docs/shared-primitives.md docs/primitives-*.md) and scan the relevant sub-table. If the diff adds a primitive that overlaps with a catalog entry, it is a duplicate — block the PR and point at the existing function with file:line.

Review checklist on every PR that adds a helper:

• Does the new function name / signature describe something already in the catalog? If yes → blocker, point at the existing one.
• Does the PR add a normalize, coerce, strip, slugify, hash, derive, or extract helper without grepping the catalog first? Ask: "did you check <catalog entry> before writing this?"
• Does the new code create a page / write .md / mint a NodeId / build a LogOp outside the catalog primitives? Block — that's how invariants drift.
• Does the PR add a new pub fn|struct|enum|const in crates/outl-{core,md,actions}/src/? The new symbol must appear in the Shared primitives catalog (the local doc-sync-guard.sh + catalog-sync-guard.sh hooks enforce this pre-merge; the same rule applies in review).

Recently added — durability primitives. Block any PR that reads a file it is about to write back with read_to_string(..).unwrap_or_default(). That is the silent-page-wipe bug: a failed read parses as an empty AST, gets rendered, and atomically replaces a full page with nothing.

Intent	Use this	File
Read a .md you are about to mutate and write back — missing file → empty, every other I/O error propagates	outl_md::atomic::read_for_rewrite	crates/outl-md/src/atomic.rs
Build one sidecar block entry — the only way to build one unless you're preserving an expanded ref_handle; keeps content_hash, ref_handle and the level-2 text derived from the same revision. A hand-rolled literal is how they end up describing different revisions	outl_md::sidecar::SidecarBlock::from_text(id, line, indent, text)	crates/outl-md/src/sidecar.rs
Sidecar format version — currently 2. Block any PR that bumps it for an additive field. Feature detection is by field presence, never by version number; an already-shipped binary rejects a higher version, rebuilds the sidecar from scratch, and duplicates every block. Bump only when an existing field changes meaning or encoding. Never hardcode the integer in a Sidecar literal	outl_md::sidecar::SIDECAR_VERSION / MIN_READABLE_SIDECAR_VERSION	crates/outl-md/src/sidecar.rs
Low-level crash-safe write (prefer the journal::write_md_atomic wrapper)	outl_md::atomic::write_atomic	crates/outl-md/src/atomic.rs
Path of a workspace's orphan log — every reconcile_md call must pass this, never None. One owner: outl_ws's Paths::at derives from it	outl_actions::sync::orphans_log_path / SyncEngine::orphans_log	crates/outl-actions/src/sync.rs

Recently added — device identity. Block any PR that reads the write actor from <workspace>/.outl/config.toml. That file rides the file-sync surface (Syncthing / Dropbox / NFS / git all replicate .outl/), flock(2) is machine-local, so two devices reading one actor_id both append to one ops-<actor>.jsonl and lose ops with no error.

Intent	Use this	File
Resolve which actor this device writes as for a workspace (migration-safe; the only supported entry point for CLI / TUI / MCP / embedders)	outl_ws::actor::resolve_device_actor	crates/outl-ws/src/actor.rs
Device-local actor store — per workspace instance (actor_for_instance, keyed by WorkspaceId plus the canonical root path, so a copied directory forks instead of sharing an op log, while a moved one keeps its actor) and device-wide (device_actor, the Tauri clients' <dir>/actor)	outl_core::DeviceStore (errors: outl_core::DeviceError)	crates/outl-core/src/device/mod.rs
Stable fingerprint of one physical device — the claim marker that lets exactly one device adopt a legacy config.toml actor	outl_core::MachineId (via DeviceStore::machine_id)	crates/outl-core/src/device/mod.rs
Directory holding this device's identity files ($OUTL_DEVICE_DIR, else $XDG_CONFIG_HOME/outl, else ~/.config/outl) — never inside a workspace	outl_core::device_dir	crates/outl-core/src/device/mod.rs
Whether an actor binding may be dropped — the single owner of that verdict, so a listing and a prune cannot disagree (root gone and its parent present and past the TTL; anything unreadable keeps the binding)	outl_core::BindingVerdict, outl_core::ActorBinding, outl_core::STALE_BINDING_TTL (via DeviceStore::actor_bindings / stale_actor_bindings / prune_binding)	crates/outl-core/src/device/gc.rs
Device-store scratch files a killed writer left half-published (never bindings, never backed up)	outl_core::STALE_SCRATCH_TTL (via DeviceStore::stale_scratch / prune_scratch)	crates/outl-core/src/device/gc.rs