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 |
| Audience | Who consumes a [[TM-0035-capability|capability]]: user for a person using the product, system for other parts of the system. system is the default. | |
| Backplane | The coordination layer the CLI and the [[TM-0031-engine|engine]] claim and record through. Git refs today. | N-41AZ-vision, D-VSLI-distributed-work-runner-architecture |
| Bundle (OKF bundle) | A directory tree of markdown that conforms to the Open Knowledge Format: every file carries frontmatter with a type, and the root index.md carries okf_version. In this repository the bundle is docs/. | |
| 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 |
| Capability | A unit of functionality the system provides: an observable ability, described independently of the code that realizes it. It is the node of the capability graph, graded by [[TM-0042-grain|grain]] and [[TM-0041-audience|audience]]. | C-0050, N-YQVC-master-consolidation |
| Capability root (root) | A [[TM-0035-capability|capability]] of grain system with no parent, standing for a whole system whose parts nest beneath it. | C-0050 |
| 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 |
| Containment (nesting) | One node of a graph being part of another: a [[TM-0028-module|module]] inside a module in the structural graph, or a [[TM-0035-capability|capability]] inside a capability in the capability graph. It gives a graph levels of depth, so each level is small enough to hold in mind. | N-YQVC-master-consolidation, M-YX34, TM-0028-module, TM-0035-capability |
| Control plane | Ontological as deployed: the thing that adopts projects and runs their work. | N-41AZ-vision, PR-0001-sdlc |
| Control unit | A chosen set of [[TM-0028-module|modules]] managed as one thing: one planning directory, one outside view, one set of rollups. | N-41AZ-vision, D-XCXA-module-graph, D-SK9G-cross-project-addressing |
| 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 |
| Engine | Foreman: the domain-blind work runner. It schedules, claims, executes, and contains [[TM-0032-work-order|work orders]] as [[TM-0033-run|runs]], over the [[TM-0030-backplane|backplane]]. | N-41AZ-vision, PR-FRMN-foreman, D-VSLI-distributed-work-runner-architecture |
| 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 |
| Feature | A [[TM-0035-capability|capability]] whose [[TM-0041-audience|audience]] is user: something a person using the product can see or do. | C-0050 |
| 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 |
| Function (control-plane function) | One of the eight things the [[TM-0027-control-plane|control plane]] does: adopt, model, observe, decide, act, steer, coordinate, record. Each is one named capability directly under the control-plane [[TM-0037-capability-root|root]]. | TM-0027-control-plane, N-RP6P-the-control-plane, C-0050 |
| Grain (kind, capability kind) | The kind of structure a [[TM-0035-capability|capability]] names, stored as kind: system, subsystem, service, workflow, component, datastore, external, module, adapter, generated or page. Every capability can have one. | |
| Harness | An agent runner that consumes the substrate. Claude Code today; the skills layer is the harness adapter. | D-0001-project-structure, D-HRNS-harness-model-and-exporters, N-41AZ-vision |
| 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 |
| Location (code anchor) | A code anchor on a [[TM-0035-capability|capability]]: a path, package or symbol that realizes it, listed in locations. | |
| 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 |
| Module | A node in the structural graph: a repo, solution, product, app, package, crate, or skill pack, with the relationships derived from its manifests. | N-41AZ-vision, D-XCXA-module-graph |
| Note | A freeform document kept as an entity: a plan, research, analysis, strategy, proposal, survey, retro or checklist, with an N- identifier, a genre and a free body. | N-YQVC-master-consolidation, N-FS9S-ontological-strategy |
| Ontological | The product. | N-41AZ-vision, PR-0001-sdlc |
| 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 |
| Release | A tagged version of sdlc. On the sdlc 1.0 roadmap each milestone is its own release, so a version number names exactly one milestone. | RM-DO9Z, N-6DUQ-sdlc-1-0-release-plan |
| 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 |
| Run | One execution of a [[TM-0032-work-order|work order]] by a registered process, claimed under a lease, journaled, isolated. | N-41AZ-vision, D-VSLI-distributed-work-runner-architecture, D-WK7T-agent-git-writes-worktree-isolated |
| 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 |
| Starter data | Files placed in a [[TM-0046-test-repository|test repository]] in the formats the backend really stores, so a screen has something to show through the real API from its first day. | M-V9RR, N-6DUQ-sdlc-1-0-release-plan |
| 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 |
| Test repository | A small generated git repository that SDF and sdlc are run against in place of fake services. It is registered and read like any real project. | M-V9RR, N-6DUQ-sdlc-1-0-release-plan |
| Unnested capability | A [[TM-0035-capability|capability]] with no parent that is not a [[TM-0037-capability-root|root]]: nothing in its definition makes it part of another capability. | N-YQVC-master-consolidation |
| 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 |
| Work order | A unit of work handed to the [[TM-0031-engine|engine]] through the source port; for Ontological, a task. | N-41AZ-vision, PR-FRMN-foreman |
| 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 |