Glossary
SDLC architecture vocabulary, defined once. Edit a term entity (or run sdlc term create) and regenerate.
| Term | Definition | Source |
|---|---|---|
| Adapter (protocol adapter, op adapter) | A protocol surface over the substrate’s op registry — CLI, MCP, HTTP. Harness-agnostic and generated from the registry. | D-0007-deterministic-op-substrate, TM-0026-surface |
| Byte-accurate parser | A parser whose reported spans are exactly right: every node knows precisely which bytes it owns, every byte belongs to some token, and nothing is normalized away during lexing. Most parsers report approximate or post-normalization positions — fine for rendering, fatal for editing. Exact spans are what make [[TM-0020-splice-write]] safe, make validation findings land on the right line and column, and let the corpus gate prove nothing was dropped (spans that tile the file reproduce it). markdown-rs’s “every byte accounted for” design is the reference. | TM-0020-splice-write, TM-0019-corpus-gate, D-7VMX-markdown-ecosystem-strategy |
| Canonical write | Full regeneration of a file from a model, formatter-stable, legal only for machine-owned files (generated rosters, indexes, build artifacts). Never interchangeable with [[TM-0020-splice-write]] — determined-vault enforces the split with a regression test, and the ecosystem inherits it as API law. CAS-guarded and validation-gated like any programmatic write. | TM-0020-splice-write, TM-0021-swap-write, TM-0023-external-change |
| Concrete syntax tree (CST) (CST, lossless CST) | A parse tree that keeps every token from the source — whitespace, markers, escapes, comments — not just semantic structure (an AST keeps only meaning). The full source is recoverable by concatenating the tree’s leaves in order, so a parse→serialize cycle with no edits is byte-identical. Losslessness is a property of the tree, not the parser: it cannot be retrofitted onto an AST that discarded the bytes. | D-7VMX-markdown-ecosystem-strategy, TM-0017-red-green-tree, C-N6RH-lossless-roundtrip-io |
| Corpus gate (byte-identity gate) | An empirical CI release gate for fidelity claims: a large body of real files that every build must round-trip byte-identically — parse, serialize with no edits, byte-compare; any single-byte diff fails. No-op-edit variants (apply an edit and its inverse, require zero diff) extend it to writers. Losslessness is unprovable in general — edge cases are unbounded — but it is testable against the files you own, so the gate, not spec-completeness, defines done. Precedent: rumdl’s 660-file byte-identical corpus from [[D-0011-markdown-formatting-tool]]. | D-0011-markdown-formatting-tool, S-0007-markdown-formatting, M-C6XN-lossless-cst-core |
| Deterministic composition | A composition layer with no LLM — a composite op, or a multi-step workflow definition. Reproducible, stays in the substrate, and is adapter-exposable. The counterpart to a head. | D-0007-deterministic-op-substrate, P-0001-prefer-deterministic-over-llm |
| Entity | A project domain object with a schema, templates, and behavior — backlog, decision, milestone, principle, standard, task, term. Declared under plugin/lib/model/entities/<type>/. | D-0004-entity-definition-architecture |
| External change | A write the system observes rather than performs: another process — Obsidian, a git checkout, a sync client — changed a file on disk. The fourth peer of the write operations, distinguished structurally: no CAS guard is possible because the system learns after the fact; it gets reconciliation instead. Requires self-echo classification (a journal of the system’s own last-write hashes distinguishes its own writes landing from foreign ones) and a bulk form (a git checkout is thousands of external changes → vault-wide invalidation). All four operations converge on one pipeline: new content → invalidate → reparse → revalidate → reindex. | TM-0021-swap-write, TM-0020-splice-write, TM-0022-canonical-write |
| Fencing (lease fencing, fence token, fencing check) | A read-only check that a lease holder is still the legitimate owner before it acts. The holder presents the lease_id it believes it holds; the check compares that against the current lease on the task ref. A match means proceed; a mismatch means a newer holder has the lease and the caller has been fenced out and must stop. It stops two workers from acting on the same task at once. | github-ref-leases/README, D-0007-deterministic-op-substrate |
| Harness | An agent runner that consumes the substrate — Claude Code today, Gemini or others later. Harness-specific packaging (skills + plugin manifest) lives under plugin/{skills,.claude-plugin}/ today and harnesses/<name>/ at end-state. | D-0001-project-structure |
| Head | An LLM-driven composition layer: prose and judgment interleaved with op calls (a skill, or an external agent). Lives outside the substrate. A spectrum from thin (interpret → call one op) to procedural (many ops with judgment between them). | S-0004-sdlc-cli-llm-head-deterministic-tail, D-0007-deterministic-op-substrate |
| mdast (unist) | The markdown AST specification of the unified/remark ecosystem — the de-facto TypeScript-side standard, extending unist (every node optionally carries position: {start, end} as {line, column, offset}). The ecosystem’s WASM surface projects a read-only mdast-compatible JSON view from the internal CST so remark-era tooling and mental models transfer for free, without constraining the internal lossless representation. markdown-rs mirrors the same shape in Rust. | TM-0016-concrete-syntax-tree, C-X2PB-wasm-ts-surface |
| Op (operation) | A deterministic unit of work — typically a method on an entity (task.create), declared once in the registry. The atom that compositions sequence. | D-0007-deterministic-op-substrate |
| OpError | The canonical typed error taxonomy an op returns. Each adapter maps a code to its native failure — CLI exit code, MCP error, HTTP status. | D-0007-deterministic-op-substrate |
| Red-green tree (rowan, green tree) | The two-layer CST implementation pattern from Roslyn, carried into Rust by rowan (rust-analyzer, taplo). The green tree is immutable and position-free — nodes know kind, text, and children; identical subtrees are shared — so an edit rebuilds only the spine to the root and everything else is the same memory. The red tree is a lazy view adding parent pointers and absolute offsets for navigation. Serialization concatenates leaves, so untouched regions come out byte-identical by construction. | TM-0016-concrete-syntax-tree, D-7VMX-markdown-ecosystem-strategy |
| Registry | The single declaration point (defineOp) for every deterministic op, carrying typed I/O, CLI hints, the error taxonomy, and the handler. The source of truth; adapters are generated from it. | D-0007-deterministic-op-substrate |
| Reoccurring workflow | A workflow that will occur again in a different work session, with some parameterization — as opposed to a task repeated within one session as part of a one-time transition (like a migration). | P-0002-operationalize-activity, P-0001-prefer-deterministic-over-llm |
| Service | A capability that spans entities or is not about a single entity — cleanup, quality, dashboard, inflight, lint, lease. Composes entity ops; lives under lib/services/. | D-0007-deterministic-op-substrate |
| Solution | A cluster of apps and packages that belong to one solution and are shared only within it — typically a nested {apps/, packages/{ts,rust}} under solutions/<name>/. A sharing scope narrower than repo-wide packages/ and wider than a single app. The tell: a solution carries multiple deployables (CLI, desktop, web, workers) that share solution-local packages — the packages exist precisely because several deployables need them. First occupant: solutions/augmented/. | D-0001-project-structure |
| Splice write (span-level write) | A surgical, programmatic write: replace exactly the byte span of the edited node and never touch any other byte, so fidelity of untouched content is guaranteed by construction rather than by careful re-serialization. Span-level, not line-level — a wikilink or table cell is a mid-line span. Requires a [[TM-0018-byte-accurate-parser]] and fresh-parse addressing (never stored line numbers). The only legal programmatic write to human-edited files; CAS-guarded and validation-gated. | TM-0021-swap-write, TM-0022-canonical-write, TM-0023-external-change, TM-0018-byte-accurate-parser |
| Substrate | The harness-agnostic deterministic core: the registry, ops, entity model, utilities, config, and services under plugin/lib/. Runs without any specific harness and is portable across LLM providers. | P-0008-harness-agnostic-substrate, D-0001-project-structure |
| Surface (published surface) | What a component exposes for others to use: its CLI verbs, HTTP routes, or library exports. A published surface is one that outside code depends on, so changing it requires coordinating with its consumers ([[S-0008]]). | S-0008, D-0001-project-structure |
| Swap write (full-content replacement) | The human-edit write path: replace the whole file with the editor buffer, taken as-is. There is nothing to preserve because the human authored every byte — fidelity is only a concept when someone else edits around content the human owns. CAS-guarded against concurrent programmatic writes (the human had the file open for minutes); validation is advisory only — a human save is never blocked, findings surface afterwards. The Obsidian editing model. | TM-0020-splice-write, TM-0022-canonical-write, TM-0023-external-change |
| Tail (deterministic tail) | The deterministic op a head calls to perform the effect: structured params, LLM-free, unit-testable. The unit under test. | S-0004-sdlc-cli-llm-head-deterministic-tail |
| Vault reshape (vault transform) | Projecting source vault(s) into a target vault of a different shape: declarative glob map.rules[] compile to a collision-resolved PathMap (the single source of truth for link rewriting), a pluggable per-note transform stage reshapes content, and execution is plan-first (inspectable dry-run, then the only writer). In-place rename/move/restructure are degenerate reshapes — “rename is just one shape of map.” Declared between contract pairs, sources validating against contract A and output against contract B, a reshape is a checked vault migration. Design source: the vault-transform dossier migrated from rust-markdown PR #43. | C-T9GW-vault-model-and-transforms, M-J9TB-vault-kernel-and-transforms, D-7VMX-markdown-ecosystem-strategy |
| Workflow | A planned deterministic-composition artifact: a declared multi-step sequence/DAG of ops with deterministic control flow. Consumes the substrate; not a parallel system. | D-0007-deterministic-op-substrate |