ADR-0037: OKF is the knowledge layer's interchange — an Index-class export and a gated import
- Status: accepted
- Date: 2026-09-24
- Deciders: Theurian maintainers
- Requirements: FR-I3, FR-V4, SEC-11, INV-6, INV-8, T-3
- Resolves
docs/roadmap.md§9 ADR candidate 8 — the governance of a derived context package (#279) — by fixing it as Index-class and naming the format, which is what #705 asks for - Situates against ADR-0010 (the three layers this adapter sits between), ADR-0005 (the migration format it does not touch), ADR-0019 (front matter is data, never governance), ADR-0013 (the approval gate the import preserves), ADR-0035 (the on-ramp shape it reuses), ADR-0009 (vendor neutrality), ADR-0027 (the digest pin) and ADR-0032 / ADR-0033 (the write path the import terminates in)
- Specification: OKF v0.2,
https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md,
read 2026-09-24. Every
§reference below is a section of that document.
This ADR records a design and ships no code. No command grows an option, no
schema changes, no enum moves; the diff is confined to docs/. It is slice S1 of
the OKF campaign: slice S2 builds the export command against it and slice S3 the
import, so the decisions below are written to be implemented rather than
revisited.
Every repository fact below was measured on 2026-09-24 against origin/main at
39ad65d1, and each carries the path that settles it.
Context
#705 proposes adopting Google Cloud's Open Knowledge Format as the concrete interchange for Theurian's knowledge layer, in two directions: an OKF-target export for the roadmap's Phase F ② context package, and a gated OKF import.
OKF is a small, open specification. A bundle is a directory tree of Markdown
files with YAML front matter (§3); one concept per file; type is the only
required key (§4.1); index.md and log.md are reserved names (§3.1); links
between concepts are ordinary Markdown links (§6.1); and conformance is
deliberately permissive — a consumer MUST NOT reject a bundle for unknown type
values, unknown additional front-matter keys, missing optional fields, broken
cross-links or a missing index.md (§11). There is no schema registry and no
required tooling.
Two premises in the proposal have to be corrected before a design can rest on them, and both corrections make the design better rather than worse.
The first correction is the one #705 makes itself, and it is right. OKF
represents knowledge state; Theurian's migration YAML is an operation log
(ADR-0005), and the entire Phase B
governance surface is bound to that log — the accept-time secret scan (SEC-11),
schema validation of MCP input (SEC-12), the committed-at-HEAD check
(ADR-0034), the write-intent tools
and their v1 operation gate. Making the migration format "OKF-compatible" would
be a layer mismatch, and it is out of scope here.
The second correction is to a premise #705 states as an alignment. It says
Theurian's canonical knowledge "is already .theurian/knowledge/**/*.md —
markdown with YAML frontmatter". That is not what the canonical format is. The
canonical form is a two-file split:
- Governance lives only in the migration.
schemas/migrations/migration.schema.json's$defs/revisionMetadatarequirestitle,contentType,kind,namespace,statusandowner, and carriestrustLevel(defaultunverified),sensitivity(defaultinternal),tenantId(defaultlocal),aclGroup(defaultdefault),validFrom,validTo,labels,scope.pathsandsourceAnchors. - The body file holds the body, at
.theurian/knowledge/<namespace…>/<leaf>.<revisionId>.md(domain/proposal.py::body_relative_path), pinned bycontentSha256and re-hashed on every load (ADR-0027;domain/knowledge.pylines 201–206 raise on a mismatch). - SQLite is derived from both (ADR-0004).
Front matter in a body is not a third home for governance:
ADR-0019 makes it data, and
infrastructure/filesystem/parsers/markdown.py's GOVERNED_FIELDS warns and
ignores status, trustlevel/trust_level, sensitivity, owner,
validfrom/valid_from, validto/valid_to, kind, namespace, acl* and
tenant*.
So the alignment with OKF is narrower than "we already are OKF": the body layer aligns, and the governance metadata is derivable from the canonical store into OKF's front-matter families. That is enough to build an adapter on, and it is not enough to call the two formats the same thing. It also decides the direction of every rule below — an exporter may synthesize front matter, and an importer may never read front matter as governance.
Two of #705's further framings are refined rather than followed, and the
arguments for both live below rather than here, so that a reader of the
proposal can see where it was corrected instead of finding an ADR that quietly
diverged from it. The proposal routes the import "through the external-source
ingestion family (#223)" and
sketches it as "OKF bundle → source → KnowledgeCandidate → proposal". Decision
6 takes the first — the import is an on-ramp to the write path that already
exists, not a #223-class connector, and the boundary that keeps those apart is
stated there — and the alternatives table takes the second, with the measurement
that KnowledgeCandidate is a review-shaped type an OKF bundle cannot satisfy.
Counting the front-matter premise above, this ADR corrects #705 in three
places and agrees with it everywhere else, its layer correction included.
Decision
1. OKF is an adapter at the knowledge layer, in both directions
OKF import and export are adapters over the knowledge/state layer. The migration format is untouched and is not made OKF-compatible; no operation kind, no schema field and no closed enum moves for either direction.
The consequence of the second premise correction, stated as the rule the two slices follow:
Export MAY synthesize OKF front matter. Import MUST NEVER read OKF front matter as governance.
The asymmetry is ADR-0019's, read
at its own boundary. ADR-0019 governs ingestion — what a Markdown file's front
matter is allowed to mean when Theurian reads it — and its answer is data,
never governance. Export is outside that scope: writing status: stable into a
file Theurian produced from a migration is a projection of governance, not a
second source of it. Import is squarely inside it: a bundle's
status: stable, its verified: list and any theurian_* key it carries are
the same untrusted front matter ADR-0019 refuses to let govern, and the importer
refuses in exactly the same way — it emits a proposal, and a human sets
governance by merging a migration.
2. The export is Index-class, and every byte of the bundle is a function of the exported population
The exported bundle is an Index-class derivative under ADR-0010's authority rules: never a record of truth, never cited as team knowledge, losable without loss, never promoted to approved knowledge. This is roadmap §9 ADR candidate 8's proposal, accepted, with OKF as the concrete format.
The artifact says so about itself, at two levels:
- Every concept document projected from a knowledge row carries OKF
generated: { by: theurian/<version>, at: <the revision's own instant> }(§5.2, §7),theurian_export_version: 1and thetheurian_content_typeof decision 7. A file that escapes the bundle still names what produced it. These are per-row rules and the manifest is not a row, so they do not reach it. - A bundle-root manifest concept,
theurian-bundle.mdwithtype: Theurian Bundle, carriestheurian_export_version,theurian_bundle_digestand the holder notice below — and nogeneratedblock at all. It has no revision, so it has no revision instant to carry, and export time is forbidden by the invariant below; ageneratedwith abyand no honestatwould be worse than none. For the same reason it carries notheurian_content_type: it projects no body.
theurian_bundle_digest is a digest over every file the export writes —
concept documents, index files and the body sidecars of decision 7 alike —
with the manifest excluded since it is where the digest sits. Its inputs are
the bundle and nothing else, which is the property that makes it publishable.
The manifest carries a holder-facing notice, and it is mandatory rather than courteous. In plain prose in its body: this bundle is a point-in-time, Index-class copy of approved knowledge; no later withdrawal, correction or secret removal reaches it; regenerate from the source deployment rather than trusting it as current. It is fixed text and names no deployment. An earlier draft allowed the exporting deployment's identity "if deterministic", offering a project id as qualifying; it does not. A project id is neither served row data nor a constant of the exporter, so admitting it would be a sixth widening owing its own justification — and the notice does its whole job without it, since whoever holds the bundle knows where they got it. Fixed text also needs no argument about what varies between runs. This is the one control in the whole residual that travels with the artifact; the three in What this does not close item 1 all act on the operator's side, where the copy is not.
generated.by names the exporter, not an author, because the document is a
projection: §5.2 defines by as the actor that produced the current content, and
the content of this file is Theurian's rendering. generated.at is the
revision's own created_at (domain/knowledge.py's KnowledgeRevision),
not the time the export ran — §5.2 defines at as "the content's last meaningful
change", and a revision is immutable, so the row's content last changed when the
revision landed.
The relation projection is deliberately outside that "meaningful change", and
saying so is the honest form of this rule. addRelation and removeRelation
mint no revision, so the ## Relations section and theurian_relations can
differ between two exports whose generated.at is identical. The section
describes the graph as of export, and the alternative — taking at as the
maximum over the row's relation instants — is rejected on a measured property of
the store: removeRelation deletes the knowledge_relations row rather than
tombstoning it (infrastructure/sqlite/store.py::remove_relation, a bare
DELETE FROM knowledge_relations), so that maximum is non-monotonic and removing
an edge would move generated.at backwards. A timestamp that can run backwards
is worse than one with a stated scope.
The actor form is §7's tool form, theurian/<version>, not process:. §7
gives three spellings — <producer>/<version> for agents and tools, human:<id>
for a person, process:<id> for an automated process — and an earlier draft here
hybridised the first two into process:theurian/<version>, which is none of
them. The export is a tool a person runs, so the tool form is the accurate one;
what matters for a consumer either way is that it is not human:, which is what
§5.3's trust tiers key on.
The manifest is a concept document rather than front matter on the root
index.md because §8 permits index files no front matter at all, with one
exception: a bundle-root index.md MAY carry an okf_version key. So the root
index.md carries okf_version: "0.2" (§12) and nothing else in its front
matter, and the producer extension permission that makes the theurian_* keys
conformant (§4.1) applies to concept documents, which is where they go.
The index files, fixed here because §8 leaves their shape to the producer and
an unfixed shape is a byte nobody bounded. §8 says an index.md MAY appear in
any directory and gives its body as sections of bulleted entries, each a
bracketed title linking its target.
- One index in every directory the bundle contains, not only in those
holding a concept. The narrower rule breaks the walk it exists to support: an
item id of
architecture.auth.session.policyputs its concept atarchitecture/auth/session/policy.md, andarchitecture/then holds nothing but a subdirectory. Skipping its index leaves it unlisted by the root, and everything beneath it unreachable by following indexes — which is the progressive disclosure §8 is for. Every directory exists only because a concept sits somewhere beneath it, so "every directory" is the rule that matches the shape. - One section per index, headed
#plus the directory's own path component. The root has no path component, so its heading is the exporter constant# Theurian Bundle, matching the manifest'stype. - Entries are the directory's own concept documents — the manifest included,
at the root — each a bracketed title linking its bundle-absolute path, and
one entry per immediate subdirectory, titled by its path component and
linking to it with a trailing slash, the form §8's own example uses. The
manifest's own entry is titled
Theurian Bundle, a fixed string like the root heading rather than a walked one: the manifest projects no row, so it carries notitlefor an entry to draw on, and leaving it unsaid is a byte nobody bounded. - All entries in one list, ordered bytewise by their bundle-absolute path. One total order over both kinds rather than two rules, which is what the determinism pin needs.
- No description. Entries SHOULD carry one (§8) and Theurian holds no counterpart, as decision 7 records.
The export writes no log.md. §9 makes it a chronological history of
updates, which needs a per-change instant; the invariant below forbids any value
that varies with when the export ran, and a revision's own instant is not a
record of this bundle's updates. A bundle that needs history is regenerated,
and the deployment it came from has the real one.
The invariant that makes the bundle safe to hand to someone. Nothing measures it today — no export command exists — so it is S2's to pin, and Compliance carries it as owed:
Every byte the export writes is a function of the exported population and the exporter's own version, and of nothing else. No byte varies with a canonical row the bundle does not contain, and none varies with when the export ran.
The subject is the bytes of the files. Filesystem metadata — mtimes, directory enumeration order, permissions — is outside it and deliberately so: a copy, a tarball or a clone rewrites all three, and a battery that compared them would fail for reasons that have nothing to do with the projection. The batteries compare file contents.
A function of a set is not yet a sequence, so every ordering the bundle contains is fixed here. Without this the determinism pin has nothing to hold: two runs over one state could emit the same values in a different order and both satisfy the sentence above.
- The digest is over
(relative POSIX path, sha256 of the file)pairs, sorted bytewise by path. index.mdentries are ordered bytewise by their bundle-absolute path, one list over concepts and subdirectories alike — the index rule above states it once, and this is the same rule, not a second one.theurian_relationsand the## Relationssection are ordered by(relation type, target item id). Neither is a stored order:list_relationsanswers a query, and the section groups by type in any case.sources[]andtagskeep their in-row order, and that order is a property of the row rather than of the query. Measured:labelsis a JSON array column round-tripped byjson.dumps/json.loads(knowledge_revisions.labels), so the sequence the migration recorded is the sequence read back; anchors come backORDER BY anchor_id, anINTEGER PRIMARY KEY AUTOINCREMENT, so the read is a total order that reproduces the order the revision recorded them in. Neither reaches the export through a query with noORDER BY.
Both of the properties this ADR is asked for fall out of that one sentence
rather than out of a checklist of excluded fields: the two-corpora equality of
decision 3, and the regeneration determinism the roadmap's Phase F ② exit
criterion names. It also settles a value the roadmap's Phase F ② row and
#279 had both specified the
other way — the stamp the whole-tree stateHash row of the alternatives table
carries the reasoning and the measurement.
Amended in slice S2 (2026-09-26): the export target is decision 2's other half, and this ADR said nothing about it. The invariant above bounds what the bytes may be a function of; implementing it needed a second rule about where they land, and four rounds of findings is what it took to state. The target is canonicalized in two phases and the operator's leaf never enters
resolve: the parent resolves, the raw leaf is joined back on, so a link planted at the target is refused instead of followed, while a final..— which names a directory by traversal and has no leaf for a plant to sit on — resolves whole. Containment is then at or under that canonical target, and ancestors above it are the operator's own path, followed as the filesystem resolves them; a dangling ancestor link is followed and its chain created, which is accepted and bounded to name occupation. And the bundle reaches the target by exactly one rename — every byte is built in a staging directory beside it — so no failure leaves a partial bundle at the target and two concurrent exports cannot merge: the loser meets a non-empty directory and takes the same refusal the probe publishes, whichtests/integration/test_okf_export.py::test_two_concurrent_exports_into_one_target_publish_one_whole_bundleholds by releasing two exports of two different corpora through athreading.Barrier. The residuals and the reasoning for each choice are T-27; what is recorded here is that the rule belongs to this decision rather than to an implementation note.
The bundle's byte sources, enumerated
A universal is only as good as the enumeration under it, and twice now this one was not. The first draft of decision 7's disclosure bound was refuted by fields outside the table it walked; the sidecar rule was then refuted by a byte source — an author-written filename suffix — outside the front-matter keys entirely. Both were true-sounding closure arguments over a population nobody had listed. So the invariant above is closed the only way that survives: every byte of the bundle belongs to exactly one family below, and each family states its bound and what checks it.
| Family | Bound | Check |
|---|---|---|
| Paths and names | The stem from the item id's own dotted segments — never the namespace field, which decision 7's containment argument bars from paths — a sidecar's extension from contentType, bounded to {.json, .yaml, .txt}, and where the positional reserved-name escape fires |
For the stem and the sidecar extension, the emission walk, since both derive from walked emissions (itemId, contentType); the structural names they are spelled with — a concept document's own .md, the three reserved names, the _item suffix — are the seventh family's. S2's collision and escape pins |
| Concept front matter | The measured served union plus the recorded widenings (decision 7), plus the two exporter constants: theurian_export_version, the mapping version of decision 7's table, and generated.by, the tool actor of §7 — both admitted by the invariant's own and the exporter's own version clause. This bounds the family's front-matter keys, not every constant spelling in the bundle: the document's structure around them is the seventh family's |
The inventory walk pin, landing with this pull request |
| Concept body | When contentType is text/markdown, the canonical body; otherwise the generated sidecar-link paragraph, whose link text and target are both the sidecar's own derived filename — theurian_body_file's derivation and not a second one, the stem from the item id and the extension from contentType, both served (decision 7). Either way, plus the generated ## Relations section, which renders only the served relation triple {type, target, note} of relations visible at both endpoints — link text included, being the triple's target (decision 4) — in the stated (type, target) order. The frame around both — the heading, and the fixed wording the link sits in — is the seventh family's |
Prose here; S2's bytes battery |
| Sidecar bytes | The snapshot's body column, byte for byte |
S2's bytes-equal pin |
| Index files | Per decision 2 above: one per directory, a single section headed by the directory's path component, entries of title and bundle-absolute path drawn from walked emissions — a subdirectory entry's title being that path component, derived from item ids rather than from any walked title — path-ordered, no description |
Prose here; S2's determinism battery |
| The manifest | Fixed text (type, the holder notice), theurian_export_version as a constant, and theurian_bundle_digest as a function of the bundle's own files in the stated path order |
The manifest field-set paragraph above; S2's determinism battery |
| Bundle-structural constants | Every byte the exporter renders that projects no row value. The class bound is that each is a constant of the exporter version: its spelling is fixed before any row is read, so no member varies with a corpus or with a run. Enumerated — the concept skeleton (the front-matter fences, the front-matter key order and the serializer that renders it, the ## Relations heading, the fixed wording the sidecar link sits in); a concept document's own .md extension; the reserved names index.md, log.md and theurian-bundle.md, and the _item escape suffix; the index entry syntax — the list marker *, then the bracketed title, then the parenthesized bundle-absolute path, §8's own form — and a subdirectory entry's trailing slash; the relations section's own list marker and the heading level its per-type sub-headings sit at; every index heading's # marker, the root's whole heading # Theurian Bundle and the manifest's index entry title of the same fixed string; okf_version: "0.2" on the root index.md, fixed by this ADR from the spec version it targets; and the absence the no-log.md rule names. The quoting a particular value draws from the serializer is that value's; which serializer runs, and in what key order, is not |
Prose here; S2's determinism battery and decision 3's two-corpora battery, which quantify over every byte of the bundle and so redden on a member of this family that varied. Neither can see a member missing from the enumeration — the paragraph below says why |
What the batteries close, and what only the enumeration closes. S2's
determinism battery and decision 3's two-corpora battery quantify over every byte
of the bundle, so they hold the invariant itself in the two directions it names:
no byte varies with a withheld row, and none varies with when the export ran.
That is what checks the seventh family's class bound, and it is not a proof
of the partition. A byte belonging to no family at all is still corpus-invariant
and still deterministic — which is exactly what the concept document's .md
extension, the index entry's list marker and okf_version were, sitting outside
every bound, and neither battery would have said anything about any of them once
S2 lands it. The partition is closed by reading this table; what the pins hold
is the enumeration's shape — the seven family names, and every row stating both
a bound and a check — and the ratchet below is what keeps the reading current.
Row text rendered into structural syntax is escaped, at both site kinds, and
the exact rule is S2's. The strings that reach those positions are bounded by
length alone: schemas/migrations/migration.schema.json gives title a
maxLength of 300, owner 200, each labels item 64 and an addRelation
note 1000, and none of the four carries namespace's control-character
pattern ^[^\u0000-\u001f\u007f]*$. A newline is therefore a spellable
character in an approved row's title, and it lands in two different kinds of
position:
- YAML front matter. Every front-matter value is emitted through a YAML
serializer that quotes and escapes, so a newline inside a title terminates no
value and opens no key. The concrete failure without it: a title ending in a
line break followed by
theurian_sensitivity: publicforges a governance key in a distributed bundle, and the row asserts its own sensitivity label to every consumer that reads front matter. - Markdown. An index entry's title and a relation line's
noteland where Markdown means something: a title carrying a bracket followed by a parenthesis closes the entry's link early, and a note beginning with a run of#reads as a heading and splits the## Relationssection. Both are rendered with Markdown-syntax escaping.
Neither site may be forged from row text. What each escape covers, and the pin that drives both, are S2's — Compliance carries it as owed.
The ratchet, in prose, so the next design change cannot repeat the last two:
a new byte source takes a row in this table first. Not a bound widened to
admit it, not a sentence elsewhere describing it — a row, with its own bound and
its own check. The seventh family is what that discipline produced on its first
run: enumerating the six that were drafted turned up okf_version and the root
heading sitting in no family at all, benign constants that no bound reached.
Finding them is the exercise working; a bound quietly stretched to cover them
would have been the same defect a third time.
3. The exported population is exactly the rows the default channel serves
The bundle contains one concept document per knowledge item this deployment
serves under the default channel: approved status and a sensitivity the
deployment's grant permits. The two predicates are
domain/enums.py::may_surface (with include_unapproved=False, which admits
APPROVED alone out of SURFACEABLE_STATUSES = {APPROVED, DRAFT, PROPOSED}) and
domain/enums.py::may_disclose, against the set
application/authorization.py::DISCLOSURE_ORDER expands from the operator's
declared ceiling — internal when none is declared.
The disclosure invariant, in the form this project has found actually closes such a class — one export against two corpora, not a field-by-field argument:
An index that holds withheld documents and an index that never held them must produce the byte-identical bundle.
There is no --include-unapproved bundle and no flag that widens this
population. A caller that may not read a row through search or knowledge.get
may not read it through a bundle either, and the bundle is the easier artifact to
forward.
The export reads one canonical snapshot, a single connection and transaction
over the active state, and every row, relation and body in a bundle comes from
that one read. The invariant in decision 2 does not reach this: it bounds what a
byte may be a function of, and says nothing about a withdrawal landing between
the twentieth row and the fortieth. Without the rule, a migrate apply running
during a long export could leave a bundle straddling two states — a withdrawn
row present as a concept, absent from the index file, and pointed at by a
relation whose other end was gated under the newer state. That is the state and
lifecycle family, and it is the family a published index build already answers
with a pointer swap (ADR-0024); the export answers
it by reading once. S2 owes the pin.
"Every row, relation and body" is exact, and bodies are the part worth
checking. A body is not fetched from .theurian/knowledge/ at export time: it
is the body column of knowledge_revisions, beside content_type, and the
store reconstructs a whole KnowledgeRevision from those columns. So the
transaction covers the bundle's contents entirely, with no filesystem read
running beside it and no second consistency rule to state. The file on disk is
tied to that column by the contentSha256 re-check at load
(domain/knowledge.py lines 201–206), which belongs to the path that built the
snapshot.
4. Relations export twice — as prose links, and as one namespaced typed key
Theurian's relations are typed: a closed 14-member RelationType
(domain/enums.py lines 73–89, mirrored by $defs/relationType in the migration
schema), of which INVERSE_RELATIONS maps two pairs and ACYCLIC_RELATIONS
names {SUPERSEDES, SUPERSEDED_BY, DEPENDS_ON} — INV-6's supersedes and two
more. OKF's
links are untyped by design: §6.1 says the kind of relationship "is conveyed by
the surrounding prose, not by the link itself". Projecting typed edges onto
untyped links loses the type; inventing an OKF link syntax for it would not be
OKF. So each visible relation is exported through both channels:
- A Markdown link in a generated
## Relationsbody section, grouped under a heading naming the relation type — the type conveyed in prose, which is exactly what §6.1 asks for, and readable by any OKF consumer with no Theurian knowledge. Links are bundle-absolute (a leading/), §6.1's recommended form. The link's text is the target's item id — thetargetof the same triple — so the whole section renders from{type, target, note}and nothing else. The alternative was the target's title, which is served and would read better; it is rejected because it couples this section's bytes to a second row's field for a cosmetic gain, and widening a bound for cosmetics is how the bound stops being checkable. A consumer wanting the title follows the link and reads the concept's own front matter. - A
theurian_relationsfront-matter key, a list of{ type, target, note }— the typed edge, machine-readable, lossless. Conformant because a consumer MUST NOT reject unknown additional front-matter keys (§11) and producers MAY add them (§4.1).
The same dual-channel principle governs anchors, one decision lower: OKF's own slot carries what fits, and a namespaced carrier holds what OKF drops (decision 7).
Visibility inherits the both-endpoints gate. A relation is exported only when
both of its endpoints clear the gate of decision 3, each read by the id it
literally names rather than through an alias — the rule
mcp/tools.py::_relation_is_visible records, including the two corrections its
docstring carries: gating the target alone published an incoming edge's note on
a visible item's response (measured: a rejected item's rejection rationale
reached an approved item), and resolving an alias at the gate let a rejected
item that was also an alias key clear as the item the alias pointed at (T-21). A
missing endpoint fails closed. One consequence worth naming: since both endpoints
must be in the exported population, no exported link is broken within the
bundle — a property of the gate, not of a link check.
The rule already has an application-layer twin, which is the layer an export
command sits in: application/index_builder.py::_both_ends_visible asks it of
the set the build's own walk produced. What makes that form safe is where its
set comes from — the walk's own visible set, built from rows read by the id
each literally names — so it inherits the alias property rather than restating
it. An export that rebuilt the same shape over an alias-resolving lookup would
reintroduce T-21 while looking identical on the page, which is why the source of
the set is stated here and not left for S2 to infer.
Amended in slice S2 (2026-09-26): that paragraph told half the truth, and the missing half was a live defect. It names where the set comes from as what makes the application-layer form safe, and the set was never the problem: the gate set is the walk's own literal-id set, exactly as written.
One name in the sentence above has moved, and correcting it here rather than in place is what an accepted ADR allows: the function is
application/index_builder.py::both_ends_visible, public since this slice becauseokf_export.pyimports it rather than restating it (git grep -n 'def both_ends_visible' -- packages/theurian-core/srcnames one definition, 2026-09-26). The paragraph above spells it_both_ends_visible, which was its name when this ADR was written and is a name nothing defines now.The alias reached the export through the query key instead.
store.list_relationsresolves an alias before it queries (_resolve_alias), and the export was the first consumer to hand it an id it had read literally out of a row. An approved, in-ceiling item whose own id is also anaddAliaskey was therefore answered from the target's edges — every returned row naming the target as itssource_item_id, so the walk's own source filter discarded all of them and the item shippedtheurian_relations: []and an empty## Relationswhileknowledge.getpublished the edge (PR #809 round one, security HIGH).So the rule is the store's own T-21 precedent, one read wider. The export calls
list_relations_by_literal_id, the relation-shaped member of the familyget_item_exactandget_item_exact_metadataalready record: reachability may resolve an alias; authority — and, here, authorship — must read the row the id literally names. The inverse mapping is keyed on the same literal id, or an incoming invertible edge comes back in the stored orientation. Two pins hold it, intests/integration/test_okf_export_batteries.py:::test_an_aliased_items_own_edges_reach_both_channels_and_its_target_reaches_neitherbuilds anaddAliaswhose key equals a served item's id and whose target is aconfidentialrow, then asserts the aliased item'stheurian_relationsentries and its whole rendered## Relationssection by equality — both channels, because they are two renderings of one tuple — and that none of the alias target's four marker strings appears in any byte of the bundle;::test_the_alias_row_really_redirects_the_read_the_export_no_longer_makesis the control, asking the store directly and asserting that the resolving read answers with the target's edge while the literal read answers with the item's own two.What the original paragraph got wrong is the population of "the same shape": it checked the set and not the key, so it read as closed while one caller could still reintroduce T-21 by asking the wrong question. The sentence stands above because it is still true of the set.
The relation note is included. Two SEC-11 controls already read it, and
they are not the same kind of thing: propose accept enforces — it scans
each operation's free text before a migration lands and refuses under the default
block policy — while the index build detects, scanning the notes this
deployment would publish (application/index_builder.py::_relation_secrets) and
reporting rather than refusing, because by then the content is already served.
The enforcement is the accept gate; the index build is the second look. And, as
that function's own docstring records, knowledge.get already serves the note
verbatim to this same population. Withholding it from the bundle would protect
nothing that is not already published, while dropping the sentence that says
why the edge exists.
5. The import never manufactures a typed relation
A vanilla OKF bundle's body links are untrusted prose pointing at a closed enum.
The importer never synthesizes a RelationType from a bare Markdown link.
§6.1 is explicit that the kind lives in the surrounding prose; deriving
supersedes from a sentence is a judgement, and a wrong one lands an edge that a
human then has to find and remove.
Where a bundle carries a theurian_relations key — a bundle Theurian itself
exported, or one a producer chose to write in this vocabulary — those edges MAY
be offered as addRelation operations inside the drafted migration, reviewed by
a human like every other operation in it. A type outside the 14 is refused by the
published schema ($defs/relationType) before any of this, so a bundle cannot
widen the enum by asserting a new value.
This keeps two pressures at zero: no garbage edges, and no pressure to extend
RelationType, whose compatibility policy is roadmap §9 ADR candidate 3 and is not
decided here.
6. The import is an on-ramp to the existing write path, not a new source class
The import's whole output is a proposal draft through the existing
ProposalService — draft for a concept's body and revision,
draft_from_document for the operations decision 5 admits
(application/proposal_service.py). It adds no write primitive, which is
ADR-0035 decision 2's
invariant applied to a second on-ramp, and nothing about it enters the source
layer. How many proposals one bundle becomes is slice S3's question, not this
ADR's — answered in slice S3, and recorded under Compliance.
The input is a local directory the operator names, and the importer fetches
nothing. No URL, no network call, no credential: the bundle is already on disk
when the import runs, put there by whoever cloned, unpacked or copied it. A
remote OKF fetch — pulling a bundle from a URL or a registry — is out of scope
and is #223-class, because
fetching is what makes something a connector: it would carry
T-7's fetch-control family (SEC-10's repository
allowlist, the scheme allowlist and private-network rejection — the last two
owed on the non-gh path to
#429) on top of #223's
trust-model gate, and neither obligation is discharged by anything here.
This boundary is what keeps decision 6's classification stable rather than rhetorical. An on-ramp that fetches is a connector wearing the wrong name: the word "on-ramp" would quietly absorb a network surface, and the controls that surface owes would be owed by an ADR that never mentioned them. A local directory has no such obligations, which is exactly why the line is drawn at the filesystem and stated here rather than left to S3.
Everything downstream is unchanged and is the point of choosing this terminus:
- The approval gate. proposal → PR → human review → merge →
migrate apply(ADR-0013), the only way anything lands. FR-I3 routes the write to a proposal file; FR-V4 keeps approval a human act recorded as a migration. - The accept-time secret scan. SEC-11's six inputs are scanned at
ProposalService.accept— each body's content, the migration document's own author-written fields, the migration file's bytes, its filename, each body's landed path and the evidence record's text —blockby default. Every string an untrusted bundle contributes passes through it, synthesized source anchors included. - A trust ceiling of
INFERRED. An imported concept is never proposed atREVIEWED, which is the tier a human reviewer grants by merging. The precedent isdomain/review.py'sKnowledgeCandidate, whosetrust_levelis aninit=Falsefield fixed atTrustLevel.INFERREDso the generator cannot raise it, beside aCandidateStatuswith noauto_approvedmember. - INV-8 holds by construction. The bundle's own identity is always recorded
as a source anchor, so a proposal from an import is never unattributed
(
domain/knowledge.pylines 208–215). An OKFsources[]entry becomes an additional anchor when itsresourceis syntactically a URI or a relative path; §5.1 allowsresourceto be a scope descriptor instead ("all queries in BigQuery project X"), and a scope descriptor is not asourceUri— the schema would accept the string, and recording it as a source URI would misstate what it is. The test is syntactic and nothing more: the importer does not follow the reference, and performs no reachability check on it — that would be the fetch the boundary above forbids, and §6.1 in any case tells consumers to tolerate a reference that resolves to nothing.
Every path a bundle names is resolved and contained before it is read.
theurian_body_file, and any §6.2 or §10.2 file reference the importer chooses
to read, must resolve under the bundle root after symlink resolution, or
that reference is refused — the reference, not the import, so a bundle with one
bad path still yields a proposal for everything else. The root is resolved
first, not only the reference: a bundle unpacked under a symlinked directory
— /tmp on macOS is one — would otherwise fail every containment check it
should pass. This is security/paths.py::resolve_within_root, which already
resolves both sides and compares them with is_relative_to, with
assert_no_symlink_escape beside it; S3 calls those rather than rebuilding the
comparison. The bundle is untrusted input that arrived as a directory someone
unpacked, which makes it exactly the shape SEC-7 and T-4/T-5 already name: a
../ in a front-matter value, or a symlink inside the tree pointing at
~/.ssh/id_rsa, would otherwise read a file outside the bundle and land its
contents in a proposal a human is about to approve. S3 owes both pins — the
escape and the symlink. Both landed in slice S3; Compliance names the
tests.
A refused reference is recorded as it was written — the front-matter key and the literal string the bundle carried — and never as the path it resolved to. The resolved form names directories on the machine that ran the import, and the record of a refusal ends up in a proposal draft that is committed and pushed for review: printing the target would carry the operator's filesystem layout into a public pull request, which is the disclosure T-25 closed on the MCP surface and which has no reason to reopen here. S3 owes this pin beside the other two. Landed in slice S3; Compliance names the tests, and the sweep is over every byte the run writes rather than over one field.
T-3 — an agent acting on instructions injected into indexed content — is the live threat on this direction, and it is guarded by exactly the controls ADR-0035 decision 5 names: the source anchors are visible on the draft, the raw bundle stays viewable beside it, and the final artifact is a reviewable pull request.
7. The governance projection is lossy, one-way, and enumerated
| Theurian | OKF slot | Notes |
|---|---|---|
kind |
type (§4.1, required) |
Exported verbatim: architecture, decision, … Type values are not centrally registered and consumers MUST NOT reject unknown ones (§4.1, §11). |
title |
title (§4.1) |
|
contentType |
theurian_content_type, always |
On every concept, markdown included, so the body's type is stated rather than inferred from whether a sidecar is present. It discloses nothing new: result_payload publishes contentType (see below). It also decides where the body goes — the next block. |
| item id | the concept's path in the bundle (§2 Concept ID) | Derived from the item id, never from namespace — see below. |
| item id | theurian_item_id |
So a consumer cites the id rather than reconstructing it from a path. |
namespace |
theurian_namespace |
Governed metadata, and not a path component. |
status |
status (§5.4) |
Only approved is exportable (decision 3), so stable is the only value emitted. |
status |
theurian_status |
The canonical value, uncollapsed. |
labels |
tags (§4.1) |
A direct fit: short strings for cross-cutting categorization. |
owner |
theurian_owner |
|
sourceAnchors[] |
sources[] (§5.1) |
sourceUri → the entry's required resource; the remaining served anchor fields ride the same entry as theurian_anchor: { provider, repository, commit_sha, file_path, line_start, line_end }. blobSha and externalId are not exported — see below. |
validTo |
stale_after (§5.5) |
Emitted only when the revision records one. |
created_at |
generated.at (§5.2) |
Decision 2. |
trustLevel |
theurian_trust_level |
Not verified — see below. |
sensitivity |
theurian_sensitivity |
The label travels with the document. |
| relations | body links + theurian_relations |
Decision 4. |
revisionId |
theurian_revision_id |
So a reader can cite the exact revision back. |
Two OKF recommended keys are deliberately absent: resource, which §4.1 says is
"absent for concepts that describe abstract ideas rather than physical
resources", and description, for which Theurian holds no counterpart — so
index.md entries carry title and link without the description §8 says they
SHOULD include, which is the last bullet of decision 2's index rule seen from
this end.
stable is the only OKF status the export can emit today, and the rest of
the mapping is reserved rather than live. deprecated and superseded are not
in SURFACEABLE_STATUSES at all, so decision 3's population never contains one;
whether they become historically disclosable is roadmap §9 ADR candidate 2, which
changes that constant and is a Phase D decision. The mapping is recorded here so
that the slice which takes it has nothing to re-derive — deprecated and
superseded both project to OKF deprecated (§5.4), collapsing a distinction
theurian_status keeps — and S2 implements the approved → stable row alone. An
export that emitted a deprecated concept today would be a disclosure defect,
not a mapping gap.
The path is derived from the item id, and namespace is never a path
component. domain/proposal.py::body_relative_path already refuses to use
namespace for this, and its reason transfers unchanged to a bundle: namespace
is free text bounded only by a control-character exclusion, so ../ is a
spellable value in a field nothing treats as a path, while an ItemId is dotted
lowercase kebab-case and cannot express a traversal at all. A bundle is a
directory tree, so this is the difference between a contained export and one that
writes outside its own root.
Three filenames are reserved against derived concept paths, and a collision
takes a documented escape rather than a refusal or a silent overwrite.
The reservation is positional — it holds at the level where the name means
something, not everywhere. index.md and log.md are OKF's and are reserved
at every level, because §3.1 gives them meaning "at any level of the
hierarchy"; theurian-bundle.md is this ADR's and is reserved at the bundle
root only, so a nested architecture/theurian-bundle.md collides with nothing
and does not escape — there is no manifest at that level for it to displace.
Reserving it everywhere would rename a row for no reason, and a rename with no
collision behind it is the kind of rule a later reader deletes because it looks
arbitrary. Nothing stops an item id from deriving onto one: ItemId('index'),
ItemId('log'),
ItemId('theurian-bundle') and ItemId('architecture.index') are all valid —
the id grammar is lowercase alphanumerics with hyphens and dotted namespaces, and
none of those names is special to it. Left unhandled, a concept would displace
the directory listing or the manifest, or be dropped in favour of them. It is a
function of the row's own id, so the two-corpora battery cannot see it: both
corpora hold that row, so both bundles are equally wrong.
The rule: a derived leaf equal to a reserved name is written with an _item
suffix on its stem — index.md → index_item.md, and its sidecar follows the
same stem. The escape cannot collide with anything, and that is a property of
the grammar rather than a hope: ItemId('index_item') raises
InvalidIdentifierError, because the underscore is outside the id alphabet
entirely, so no item id can derive onto an escaped name. theurian_item_id on
the concept still names the unescaped id, so nothing is lost in the projection.
A refusal was the alternative and is rejected for the reason the sidecar rule
rejects it: a gate-cleared row is never refused, and one item called index
would otherwise deny the whole corpus its bundle. S2 owes the pin.
A markdown body embeds in its concept document; a non-markdown body is written
as a sidecar file beside it, byte for byte. contentType is a free media type
in the published schema, whose own description states the rule this follows —
"Media type of the body. Preserved rather than converted, so a structured source
stays structured (ADR-0010)" — and ADR-0010's
rule 5 says the same from the other end: Markdown is the recommended authoring
format for human prose and is never the canonical form of something that was
born structured. A bundle that flattened an OpenAPI document into prose would
destroy exactly what that rule protects, and would do it in the artifact most
likely to be read by a tool rather than a person.
So the split is by media type:
text/markdown— the overwhelming case — is the concept document's body, as everywhere else in this ADR.- Anything else is written beside its concept document, at the concept's own
path with the body's own extension, and the concept's body carries an ordinary
Markdown link to it — its link text is that same derived filename, never
the canonical body file's author-written name — plus a
theurian_body_filekey holding the same path. The dual-channel shape of decision 4 again: OKF's own channel for a consumer that reads links, a namespaced key for one that reads front matter. A sidecar is not a concept document (§3.1) and carries no front matter: its concept document holds the whole governance projection for the row.
A gate-cleared row is never refused, and the sidecar extension is a total
function of contentType alone. The whole mapping, and there is no other
input — written as rules rather than as a table, because decision 7's tables are
projections of governance and this is a derivation of a filename:
application/json, or anything ending+json→.jsonapplication/yaml,text/x-yaml, or anything ending+yaml→.yaml- everything else →
.txt
text/x-yaml is named explicitly because it is the one member of
domain/values.py::_STRUCTURED_MEDIA_TYPES no other arm reaches with the right
extension: the suffix rule cannot see it — x-yaml is a hyphen, not a +yaml
suffix — and the exact spellings beside it carry application/json and
application/yaml only, so a rule without it spells a YAML body as text.
"The one member matching neither endswith arm" is not that criterion, and an
earlier draft of this sentence said it was. Measured 2026-09-24: five of the
seven match neither — application/json, application/vnd.aai.asyncapi,
application/vnd.oai.openapi, application/yaml and text/x-yaml — and two of
those five take .txt by design. application/vnd.aai.asyncapi and
application/vnd.oai.openapi are API-description formats with no canonical
serialization: the same document is written as JSON or as YAML, so there is no
correct structured extension to send them to, and .txt is the honest answer
rather than a gap the rule failed to close. Compliance carries the pin over
that constant, landing with this pull request. The two endswith arms are
MediaType.is_structured's own rule, reused so the bundle spells a type the way
the domain recognises it.
Four properties, and each is load-bearing rather than pleasant:
- The range is
{.json, .yaml, .txt}— bounded, filesystem-safe, and short. No path built from it can overrun a filename limit. - It is never
.md. Markdown embeds in its concept document and never reaches this rule, so a sidecar can never be written at a concept document's own path. contentTypeis inside the disclosure bound (result_payloadpublishes it), sotheurian_body_fileis a function of served data end to end: the stem from the item id, the extension fromcontentType, anditemIdis served too. It is a derived key defined in prose rather than a projection-table row, and the walk's population is the emission inventory for exactly that reason — a key documented outside the table was how an unbounded input reached a filename for a round, and widening the instrument is what stops the next one rather than relocating this one.contentTypeis in the one-snapshot read, as a column of the revision row decision 3's single transaction already reads.
The canonical body file's own suffix is dropped as an input, and this is a
correction. An earlier draft made it step one — "the recorded suffix when it
has one" — and it was wrong twice over. It is not in the snapshot:
knowledge_revisions has no path column and KnowledgeRevision has no path
field, so reading it means a second read outside the transaction decision 3
commits to. And it is unconstrained author text: $defs/contentFile bounds
length at 1024 and refuses an absolute path, and says nothing whatever about the
suffix. The alternatives table carries the three faces that fell out of it.
The sidecar's bytes are the snapshot's, not the filesystem's. "Preserved
byte for byte" means the canonical body the revision row holds — body is a
column of knowledge_revisions beside content_type, and the store
reconstructs a KnowledgeRevision from those columns — so writing a sidecar
needs no second read of .theurian/knowledge/ and stays inside decision 3's one
transaction. What pins that body to the file the author wrote is the
contentSha256 check at load (domain/knowledge.py lines 201–206), on the path
that built the snapshot rather than on the export.
The OKF spec settles that a non-markdown member is legal, and does not merely
tolerate it. §3 characterises a bundle as a directory tree of markdown files,
but every rule that classifies or constrains a member is keyed on the .md
suffix: §3.1 reserves two filenames and says "all other .md files are concept
documents", and §11's three conformance clauses each range over .md files, so a
non-.md member cannot make a bundle non-conformant. The spec then uses such
members itself. §6.3's references/ convention mirrors "external material, run
instructions, or code as first-class concepts within the bundle", its own example
being references/attesters/revenue.py; §10.2 gives computation as "a path
(§6.2) to a file holding the computation"; and §10.3 offers precisely this
ADR's choice — inline a fenced block in the body, or file, the latter "best
for a long or generated computation, or one already kept as a real file shared
with non-OKF tooling", with references/computations/lib/revenue.sql as the
example. A structured knowledge body is that case exactly.
Decision 3's population is untouched by any of this. A non-markdown row is
exported like every other row the default channel serves; the media type
decides where its bytes go and what its sidecar is called, never whether it
goes — which is a property of the contentType mapping above being total, not
an aspiration. The alternatives table carries the rejected reading, and it is
worth saying why it is a trap rather than merely wrong: excluding non-markdown
rows would leave the two-corpora battery green — the filter is a function of
the row itself, not of any withheld row — while the bundle silently omitted
governed knowledge. A passing battery would have said nothing about it.
OKF verified is not emitted, and that is a decision rather than an
omission. §5.3 derives a consumer's trust tier from verified alone: no key
means unverified, a non-human: actor means machine-confirmed, and a
human:<id> actor means human-reviewed. Theurian's approval is a pull-request
merge, and the canonical store does not hold the approving identity —
recording the merge commit at migrate apply is roadmap §9 ADR candidate 10, not
yet taken. KnowledgeRevision.author is the authoring identity, self-declared
in the migration and not authenticated; emitting it as a verifier would launder
authorship into review, and routing it through process: would claim a machine
confirmation that never ran. Both would move a consumer's trust tier on a fact
Theurian cannot supply. The honest value is no value, and OKF is explicitly built
to be read that way: absence means unverified, and a consumer MUST NOT reject a
concept for it (§5.3, §11).
What the projection may publish is bounded by two measured instruments, and
five deliberate widenings are recorded against that bound. An earlier draft of
this paragraph said the projection publishes nothing the serve path withholds and
cited result_payload alone. That was false of its own table — five of the rows
above are not in that payload at all — and it named the wrong instrument for the
body, which the export carries whole while result_payload carries an excerpt.
Both halves are corrected here rather than softened.
The bound is the union of two payloads, measured on 2026-09-24:
mcp/results.py::result_payload(the payload it builds, L88–120) is the shape underneath every result — a floor rather than a ceiling, since a tool may add to it — and it emitsitemId,revisionId,title,excerpt,contentType,status,trustLevel(fromrevision.metadata.trust_level),sensitivity(the item's current one, threaded in rather than read off the revision),freshness.revisionCreatedAtand asourceAnchors[]of exactlyprovider,sourceUri,repository,commitSha,filePath,lineStartandlineEnd. Beside that instant the samefreshnessobject holdsisWithinValidityandageDays, and the payload carries the threeSAFETYlabels andraptorPathwhen a forest was walked — named here because a bound has to be the whole payload, where the enumeration before it is the part this projection draws from.knowledge.get's additions (mcp/tools.pyL2430–2442), which are exactly four:body— the whole body, not the excerpt —relations, each{relationType, targetItemId, note}and each gated by_relation_is_visible,structured, and a conditionalintegrity.
That union is what covers the parts of this projection that carry the most: the
full body in the concept document or its sidecar, and theurian_relations with
the ## Relations section, whose triple is knowledge.get's triple.
The union is the two tools this projection draws from, and it is deliberately
not every served key. knowledge.search adds fusedScore and foundBy on top
of the same base shape (mcp/search.py L789–790); neither is row metadata, and
neither is in the union above, so the bound stays where the projection can
actually reach. Counting them would widen the bound without widening what the
bundle may say — the wrong direction for a claim whose whole job is to be
conservative.
Five things decision 7 emits sit outside the union, and each is a recorded widening rather than an oversight:
| Widened | The justification, one line each |
|---|---|
type ← kind |
OKF's one required key (§4.1): a bundle cannot exist without it. It states the governance class of a row the recipient is already reading. |
theurian_namespace ← namespace |
One of the six required fields, so a faithful re-proposal of an exported row needs it. It names internal structure — the same kind of exposure owner carries, and it is recorded here for the same reason. |
tags ← labels |
Unserved, so this is a recorded exposure like owner's, not a safe projection. No result_payload key carries labels, no search parameter filters on them, and the FTS5 table indexes heading and text only (infrastructure/sqlite/index_schema.py's chunks_fts) — a label reaches no reader today. What makes emitting them acceptable is the gate, not the intent: metadata.labels is scanned element by element at accept, under the default block policy (application/proposal_service.py::_metadata_strings → _list_strings, L4245). |
stale_after ← validTo |
The serve path publishes freshness.isWithinValidity, a boolean this instant produces; the bundle publishes the instant, which is strictly more than the boolean. Emitted because a bundle is read asynchronously, where a boolean computed at export time would be wrong by the time it is read. |
theurian_owner ← owner |
Already carried as a residual under Negative — the recorded owner string travels, and a team that set it to a person's handle is exporting that handle. |
So the universal is: the projection publishes nothing outside that union except the five widenings above. It is a statement a check can walk, which is the point of writing it this way; a pin walking decision 7's table against the union plus this table lands with this pull request, and Compliance carries it.
The two anchor fields that payload does not carry, blobSha and externalId,
are therefore not exported either — and neither of knowledge.get's four
additions carries them, so widening there was available and was not taken. The
two-corpora battery of decision 3 holds the other half: withheld rows cannot
perturb any of these values, because they cannot reach the bundle at all.
Dropped without a slot, enumerated so that "lossy" is a list rather than an adjective:
| Dropped | Why it has no home |
|---|---|
| The immutable revision history | The bundle carries the current revision only; theurian_revision_id names which. |
The supersedes chain |
A superseded item is outside decision 3's population, so a SUPERSEDES edge never clears decision 4's both-endpoints gate. Nothing of the chain survives but the exported row's own theurian_status — which is approved for every exported row today, so in practice no trace of supersession leaves the bundle at all. |
blobSha, externalId |
The two sourceAnchor fields neither served payload publishes (see the bound above). Exporting them would put provenance in a portable artifact that the serve path withholds from the same rows. |
contentSha256 |
The exported body is a projection — it gains the generated ## Relations section — so a digest of the canonical body sitting beside it would be unverifiable against the file it is on. A sidecar body is byte-identical, so the digest would be checkable there; it is still not emitted, so that one rule holds for every concept rather than for most of them. Available to a later mapping version if a consumer asks for it. |
tenantId, aclGroup |
Fixed today and unenforceable otherwise: application/migration_engine.py refuses a revision naming a tenant other than local or an ACL group other than default. Exporting a field that carries no information invites a consumer to route on it. |
| Evidence records | The evidence plane has no OKF counterpart; as prose it would read as content. |
scope.paths |
Glob patterns over a repository the bundle's recipient may not have. |
validFrom |
OKF's stale_after has no opening twin (§5.5). |
author |
OKF's only actor slots are generated.by and verified[].by; decision 2 gives the first to the exporter, and the second is the field above. |
One-way, and stated as a rule: nothing reads this projection back as governance. An import of a bundle Theurian exported is decision 6's path like any other — a proposal a human reviews.
Consequences
Positive
- Theurian's governed knowledge becomes portable into an ecosystem, in a format whose consumers are obliged to tolerate the optional families Theurian does not supply and the extension keys it adds (§11), so the lossy projection is a conformant bundle rather than a degraded one.
- The Phase F ② governance question is settled with a format attached. ADR candidate 8 asked whether a derived context package needs a new classification. It does not: Index-class, losable, asserting no truth — and now with the concrete artifact named, so S2 implements rather than re-decides.
- The disclosure story is one sentence, not a field audit. Decision 2's invariant covers a published field, which rows reach the bundle, a statistic over rows the recipient may not read, and a duration-shaped value like a wall-clock stamp — in one statement a test can drive.
- No vendor dependency is taken on. OKF has no registry, no central authority and no required tooling, so adopting it adds no hosted service and no vendor name in domain or application code — ADR-0009's rules 5 and 6 hold. Its rules are about model and infrastructure providers rather than interchange formats, so what carries over is the principle, and the Index-class framing is what makes it airtight: the bundle is losable, so nothing of the canonical record depends on OKF at all.
- Enum pressure stays at zero. Decision 5 means the 14-member
RelationTypeis neither widened nor filled with guesses, so roadmap §9 ADR candidate 3 stays unforced.
Negative
- The bundle is a second copy of approved knowledge that no withdrawal can reach. A secret-removal withdrawal propagates to every index build on the machine and to no distributed copy. That is a disclosure residual rather than a staleness one, it is the price of the artifact being portable at all, and the first residual below states it in full — including the threat-model entry it owes.
- A recipient cannot reconstruct governance, by design. The projection is lossy and one-way; the dropped list above is the price, stated in full so that nobody discovers it later by needing one of the rows.
- The recorded
ownerstring travels with the bundle. It is the accountable party the governance record names, which is what makes it worth exporting — and a team that has set it to a person's handle is exporting that handle. An operator handing a bundle outside the organisation should know this. - Regeneration is how staleness is detected, because decision 2 keeps the
whole-tree
stateHashout of the bundle. Comparing one stamped value would have been cheaper than regenerating and comparing digests. Regeneration is deterministic and local, so the cost is small and it is paid by the operator, never by the recipient. - A mapping change is a visible break. Any later change to decision 7's table
bumps
theurian_export_versionand changes every exported byte, so a consumer readingtheurian_*keys must follow. That is the point of the key existing.
Neutral
- Nothing ships here. No schema, no enum, no operation kind, no MCP tool;
knowledge.getContextstaysPlannedindocs/protocol/mcp-tools.md, andknowledge.tracewith it. - The export command's surface is S2's. This ADR fixes the artifact and the population, not the flags, the help text or the output format — those are a wire contract reviewed in their own slice.
- The
theurian_*key spellings are fixed here so S2 has nothing to invent:theurian_export_version,theurian_bundle_digest,theurian_item_id,theurian_revision_id,theurian_status,theurian_namespace,theurian_owner,theurian_trust_level,theurian_sensitivity,theurian_content_type,theurian_body_file,theurian_relations,theurian_anchor. Snake case, matching OKF's own key style (okf_version,stale_after,last_modified).
What this does not close
- The purge gap. It is a disclosure residual, not a freshness caveat, and it
is accepted as one. A withdrawal publishes a purged index build
synchronously and swaps the pointer
(ADR-0024,
application/withdrawal_purge.py); an exported bundle has no equivalent, and the withdrawal does not propagate to copies already distributed. The case that fixes the severity is the one the purge machinery exists for: a secret-removal withdrawal. A credential withdrawn from every index build on this machine survives in every distributed bundle until that bundle is regenerated and redistributed, and redistribution is outside Theurian's reach entirely — there is no list of who holds a copy, and no mechanism that could reach them if there were. The same holds for a row withdrawn because it should never have been approved.
This is the distributed-artifact shape: an artifact in someone else's hands
holds records the live state has since withdrawn. It is not in the threat
model today. Grepped on 2026-09-24: entries run T-1 through T-26, and the
withdrawal→purge treatment there (T-17, T-17a, and T-15's remediation clause)
is entirely about the locally published index build; T-24 is a different
shape — a repository shipping its own .theurian/review/ — and does not
cover this. So a threat-model entry is owed by slice S2, when the export
mechanism lands, alongside the T-3 entry S3 owes for the import; Compliance
carries both.
Four things bound the residual and none removes it. Three are
operator-side, where the distributed copy is not: the bundle is
Index-class, so deleting a copy loses nothing; theurian_bundle_digest makes
staleness detectable by regenerating and comparing; and the guidance the
export ships with is to regenerate rather than to edit. One travels with the
artifact — the manifest's holder notice (decision 2), which is why that
notice is a mandatory obligation on S2 rather than a nicety: it is the only
thing that reaches the person holding the copy. An operator choosing to
distribute a bundle is choosing this residual, which is the reason it is
written here in those words rather than as a note about freshness.
Amended in slice S2 (2026-09-26): written, and the clause about S3's half is discharged too. The export mechanism landed, so the entry is written — as a new numbered entry, T-27, because no entry above covers the distributed-artifact shape and the grep recorded above is the measurement that says so. It is graded High, accepted: the recipient cleared the serve gate for every byte at the moment the copy was made, so what is lost is the reach of remediation rather than the gate, and the secret-removal case is what sets the grade. The four bounds above are its controls table, each named with what drives it, and the entry carries three further export-side surfaces this item did not anticipate: no bundle file carries SEC-15's safety triple, a body's rendered sections are not authenticated against its front matter (#814), and the export target's containment scope has its own accepted residual (decision 2's amendment B).
"alongside the T-3 entry S3 owes" is discharged on that side as well: S3's half landed as T-3's third arrival route in #811, merged at
8d659e9b, and item 4 below carries its own amendment saying so. Compliance carries T-27 under Landed in slice S2. 2. Round-trip is not identity. Export followed by import produces a proposal, never a restoration: new revision ids, a trust ceiling ofINFERRED, and a human merge in between. Anyone reading the two directions as a backup mechanism is reading them wrong, and decision 6 is why. 3. OKF is at v0.2 and may move. The bundle root declares the version it targets (§12), and a spec bump is a new decision — a minor bump is additive by §12's own rule, and a major one may rename required fields or reserved filenames, which would change decision 7's table andtheurian_export_versionwith it. 4. The T-3 threat-model entry for the import path, owed by slice S3 when the mechanism lands, alongside ADR-0033's and ADR-0035's owed entries. A prose obligation with no test today, recorded here rather than dressed as discharged.Amended in slice S3 (2026-09-25): written, and one clause above was already wrong. The mechanism landed, so the entry is written — as T-3's third arrival route, after the retrieval route and ADR-0033's candidate route, rather than as a new numbered entry: the root cause is T-3's own, which decision 6 states, and naming a class by the shape of what it emits is what this repository forbids. Each control is named with the test that drives it, the grade stays High, and the threat summary row does not move. Compliance carries it under Landed in slice S3.
The wrong clause is "alongside ADR-0033's and ADR-0035's owed entries": ADR-0033's entry was not owed when this ADR was written. It landed in Phase B slice B5 on 2026-09-19 and ADR-0033's own Compliance records it as written; the candidate path is T-3's second route, which is why the import is its third rather than its second. ADR-0035's entry is genuinely still owed — it comes due when the interactive-curation mechanism lands, and that mechanism has not — so the only mention of ADR-0035 in
docs/security/threat-model.mdis the one this slice's own T-3 route makes of its decision-5 controls (git grep -n 0035 -- docs/security/threat-model.md, one hit, 2026-09-25). The sentence is left standing above rather than edited, because what it got wrong is the record it read, not the obligation it recorded. 5. Whether an imported concept is a fair reading of its bundle. That is FR-V4's human at the pull request, the same authority ADR-0033 and ADR-0035 give the question. Nothing here proposes a machine that would replace them.
Alternatives considered
| Alternative | Why rejected |
|---|---|
| Make the migration YAML OKF-compatible | A layer mismatch: OKF is state, the migration is an operation log (ADR-0005), and the whole Phase B governance surface — SEC-11's accept scan, SEC-12's input validation, the committed-at-HEAD check, the v1 operation gate — is bound to that log. #705 names this as the tempting framing and rules it out; this ADR agrees. |
Export an ad-hoc AGENTS.md-style summary, as Phase F ② originally worded it |
An ad-hoc format has no consumers, no conformance rules, and no obligation on a reader to tolerate what we cannot supply. OKF costs nothing extra — the artifact is Markdown with front matter either way — and §11's permissive conformance is precisely what a lossy projection needs. |
Stamp the whole-tree stateHash in the bundle, as Phase F ② and #279 both say |
domain/state.py's StateInputs covers every migration in the working tree plus every referenced body checksum (ADR-0016), so the value moves when a rejected, draft or above-ceiling row moves. Putting it in a shippable artifact would carry a statistic over rows the recipient may not read, and would falsify decision 3's two-corpora equality by construction — the bundle would differ across the two corpora in exactly one field. The staleness need it served is met by a digest over the bundle's own files. Whether the command reports the state hash locally, to its operator, is S2's and is untouched by this. |
Emit OKF verified from Theurian's approval |
§5.3 keys the trust tier off this field, and the approving identity is not in the canonical store (roadmap §9 candidate 10). A human:<id> built from KnowledgeRevision.author launders authorship into review; a process: actor claims a machine confirmation that never ran. Absence is a meaning OKF defines, and it is the true one. |
| Synthesize typed relations from OKF body links on import | §6.1 puts the relationship kind in the surrounding prose, so filling a closed 14-member enum from a bare link is guesswork, and every wrong guess is an edge a human must find and remove. Untyped links do not need a new type; they need a human. |
| Treat OKF import as #223-class external-source ingestion, gated on the trust model | #223 governs connectors that snapshot external systems into the source layer without passing a pull request; its gate exists because that path bypasses review. This import produces only a reviewable proposal and reaches approved state through the same merge as everything else, so it inherits ADR-0013's gate rather than needing #223's. The boundary that makes the distinction hold is the one decision 6 states: the input is a local directory and the importer fetches nothing. A remote fetch would put this back in #223's class and owe T-7's fetch controls with it; ingesting a bundle as a governed source is #223's either way, and remains out of scope. |
Reuse KnowledgeCandidate for imported concepts, as #705's "bundle → source → KnowledgeCandidate → proposal" sketch has it |
domain/review.py's PromotionGate requires seven review-shaped signals — pull_request_merged, thread_resolved, fix_commit_present, not_dismissed_or_outdated, ci_successful, generalizable, has_evidence — and KnowledgeCandidate.__post_init__ raises when the gate is unsatisfied. An OKF bundle satisfies none of them, so reuse means fabricating review facts or weakening the gate for every candidate, review-derived ones included. What the type is kept for is its precedent: the INFERRED ceiling of decision 6. |
Extend RelationType so OKF's untyped links have a home |
Enum extension is roadmap §9 ADR candidate 3, which owes a compatibility policy first; and the problem is not a missing member. An untyped link is untyped, and decision 5 is the answer to it. |
| Export only the markdown-bodied rows, leaving structured knowledge out of the bundle | It breaks decision 3's population rule — the bundle would no longer be the rows this deployment serves — and it drops governed knowledge from an artifact that says it carries the approved corpus. The trap is that nothing would catch it: the filter is a function of the row's own media type, not of any withheld row, so the two-corpora battery stays green while the bundle omits every OpenAPI document and JSON Schema in the corpus. A green battery would have asserted nothing about the omission. |
| Derive the sidecar extension from the canonical body file's suffix | This was step one of the accepted rule for one round, and it failed in three independent ways. (a) It is outside the disclosure bound. The suffix is an author-written string that neither served payload publishes, so theurian_body_file — itself defined in prose outside the projection table, and so outside the walk's population — carried unserved data into the bundle: round 1's under-enumerated universal, one key over. (b) It admits .md. A row with contentType: application/yaml and a contentFile ending .md — a plausible hand-authored mistake, and nothing refuses it — writes the sidecar at the concept document's own path, silently losing whichever of the two is written first: governance front matter, or the body bytes. Both owed batteries are blind to it by construction, since it is a function of the row's own data and both corpora hold the row. (c) It is not in the snapshot and can be unbounded. knowledge_revisions has no path column and KnowledgeRevision no path field, so reading it breaks decision 3's one-transaction rule; and $defs/contentFile permits 1024 characters with no suffix constraint, so a long tail becomes ENAMETOOLONG and denies the whole corpus its export. The accepted rule takes contentType alone, whose range is {.json, .yaml, .txt}. |
Take the sidecar extension from body_extension, refusing an unmapped media type |
The first draft of the sidecar rule did this and called the refusal a virtue. Measured 2026-09-24: _EXTENSIONS holds three media types against _STRUCTURED_MEDIA_TYPES' seven-plus, so five of the seven structured types and text/plain would refuse — including application/vnd.oai.openapi, the rule's own motivating example. Worse, the refusal is not per-row: one hand-authored row denies the whole corpus its export. A gate-cleared row must never be refused, which is why the three-step derivation above is total. |
| Fence a non-markdown body inside its concept document instead of writing a sidecar | It converts what ADR-0010 rule 5 and the schema's own contentType description say to preserve, and it does so silently: a consumer gets YAML wrapped in Markdown, no longer byte-identical to the canonical body and no longer parseable without unwrapping it first. The spec makes the choice unnecessary — §10.3 offers the file form for content "already kept as a real file shared with non-OKF tooling", which is this case. It stays the fallback only if a future spec revision forbids non-.md members, and it would then be recorded as a conversion, not presented as a projection. |
Derive the bundle path from namespace |
namespace is free text where ../ is spellable; domain/proposal.py::body_relative_path already refuses it for exactly this reason, and a bundle is a directory tree, so the failure is writing outside the bundle root. |
Compliance
This ADR ships no behaviour, so it names no test of its own. What follows separates the enforcement that already exists from what slices S2 and S3 owe.
Rests on enforcement that already holds:
- The serve gate of decision 3 is the shipped predicate pair.
domain/enums.py::may_surfaceadmitsAPPROVEDalone wheninclude_unapproved=False, andmay_discloseanswers the sensitivity axis against the expanded ceiling inapplication/authorization.py. The export does not define a population; it reuses this one. - The both-endpoints relation gate exists and carries its own history.
mcp/tools.py::_relation_is_visiblegates both ends, reads each by the id it literally names, and fails closed on a missing endpoint. - A fabricated relation type cannot land.
$defs/relationTypeinschemas/migrations/migration.schema.jsonenumerates the 14 members, so an imported operation naming anything else is refused at validation, before any human sees it. - An unattributed revision cannot be constructed.
domain/knowledge.pylines 208–215 raise unless a revision has a source anchor or theauthored-in-theurianlabel (INV-8). - An unenforceable tenant or ACL group is refused.
application/migration_engine.pyrefuses a revision naming a tenant other thanlocalor an ACL group other thandefault, which is why decision 7 drops both. - The approval gate the import terminates in is
ADR-0013's, unchanged, with SEC-11's
six-input scan at
ProposalService.acceptand ADR-0034's committed check beyond it.
Landing with this pull request:
- A walk of everything this ADR emits against the disclosure bound — the
union of
result_payloadandknowledge.get's four additions, plus the five recorded widenings. Its subject is the whole emission inventory, not one table: all thirteentheurian_*keys (Neutral, third bullet) and the OKF-side emissions —type,title,tags,status,stale_after,generated,sources[]and the body. Scoping it to the projection table is the defect it exists to catch:theurian_body_filelived in prose outside that table for a round, and an unserved input reached a filename through it. It goes RED when anything emitted is in neither the union nor the widenings. - The sidecar extension rule, walked over the media types it ranges on.
domain/values.py::_STRUCTURED_MEDIA_TYPEShas seven members; decision 7's three arms —application/jsonand anything ending+jsonto.json;application/yaml,text/x-yamland anything ending+yamlto.yaml; everything else to.txt— assign each of them the extension recorded above. It goes RED when a member arrives whose extension those arms get wrong, and when the paragraph's five-of-seven measurement — the members matching neitherendswitharm — stops being five.
Landed in slice S3 (the gated import). Each item's reach is stated as its body holds it — the fixtures it builds and the assertions it makes — rather than as its name or its docstring reads:
- How many proposals one bundle becomes, the value decision 6 left to this
slice: one per admitted concept, plus at most one relations document, with the
whole import capped at
MAX_UPSERT_OPERATIONSoperations across both kinds. A concept goes throughProposalService.draft, contributing two operations (create and revise); everytheurian_relationsentry in the bundle goes into onedraft_from_documentmigration, contributing one each. One document for the whole import is not a rejected preference but an impossibility:_REFUSED_TO_CONTENT_PATHrefusescreateItemandupsertRevisioninsidedraft_from_documentunconditionally — ADR-0027's two-procedures-disagree control — so no content operation can ride a hand-authored document.tests/integration/test_okf_import.py::test_theurian_relations_land_as_one_additional_proposalasserts the relations document'soperationslist equals exactly oneaddRelationmapping, and::test_a_bundle_with_no_relations_drafts_no_relations_proposalthatrelations_proposalisNonewhen no concept carries the key. The cap's scope is driven rather than asserted:tests/integration/test_okf_import_deepening.py::test_251_relations_on_one_concept_refuse_the_whole_import_not_only_the_relations_documentbuilds one concept with 251 entries and asserts the refusal names 253 — the whole-import total — andMAX_UPSERT_OPERATIONSitself, and that no proposal directory was written.
Amended in slice S3, review round two: the cap is checked incrementally, and the number in the refusal is a running total. The row above reads the pinned
253as the whole-import total, which is what the check computed while it ran once after the whole bundle had been read. It now runs after each concept is admitted, inside_admit_concepts, so the walk stops at the crossing and never reads the rest of the bundle. The recorded reason is memory rather than time, and_admit_concepts's docstring carries the measurement it rests on: a 209 MB bundle whose 251st concept already crosses the cap peaked at 211 MB reading the other several hundred anyway.So the refusal names the running total at the crossing and the concepts it was computed within, never what the bundle holds: This bundle passes {count} operations within its first {n} concepts, more than the 250 a single import will draft. Both cap tests now assert that whole message by string equality rather than by substring — the test named above on
253within its first1concepts, where one concept is the whole bundle and the two readings of 253 coincide, and::test_a_300_concept_bundle_refuses_fast_rather_than_drafting_unboundedlyon252within its first126, which additionally asserts that600, the bundle's own total, appears nowhere in the message.The stop is pinned by a read counter, not inferred from that arithmetic.
tests/integration/test_okf_import_deepening.py::test_the_incremental_cap_stops_reading_before_the_rest_of_the_bundlereplacesread_source_fileinokf_import's own namespace with a recording wrapper, builds 300 concepts, and asserts the recorded call list has length exactly 126 — the 126th concept's own two operations are what cross 250. The boundary's other side is::test_a_bundle_computing_exactly_the_cap_admits_and_drafts_every_concept, which buildsMAX_UPSERT_OPERATIONS // 2concepts and asserts every one is admitted with no refusal, so the comparison is>and not>=.One narrowing to the sentence above the amendment. Every
theurian_relationsentry in the bundle is now every entry of a concept that actually drafted:_collect_relation_operationsdrops the edges of a concept whose own.draft()refused, each with its own refusal record, because anaddRelationnaming asourceItemIdno proposal accompanies is unreviewable. Driven bytests/integration/test_okf_import.py::test_a_relation_from_a_concept_that_refused_at_draft_never_lands, which seeds the item first so its re-import refuses at.draft(), then assertsrelations_proposalisNone, that the refusals carry both adraftand arelationskind keyed on that item id, and that no migration file under.theurian/proposals/mentions the dropped edge's target. The charge against the cap is unchanged and deliberately so: it is counted at admission, before any draft runs. - A bundle carrying only bare Markdown links yields a drafted migration with noaddRelationoperation (decision 5).tests/integration/test_okf_import.py::test_a_bare_markdown_link_never_synthesizes_a_relationimports a concept whose body carries one bundle-absolute Markdown link and asserts that no relations proposal is drafted at all, which is stronger than the absence of an operation inside one. Decision 5's other half — that a bundle cannot widen the enum by asserting a value — is driven bytests/integration/test_okf_import_deepening.py::test_an_out_of_enum_relation_type_is_refused_by_the_schema_while_the_concept_still_drafts: atheurian_relationsentry namingmade_up_relation_typeleaves the concept admitted,relations_proposalNone, and one refusal keyedaddRelation. - The proposed trust level is capped atINFERRED, and the two halves are pinned separately because they can fail separately.tests/unit/test_okf_import_trust_ceiling.py::test_no_caller_can_pass_a_trust_level_to_an_imported_conceptconstructsImportedConceptwithtrust_level=TrustLevel.REVIEWEDand assertsTypeError, with::test_an_imported_concept_defaults_to_inferred_trustasserting the constructed default; both are assertions about the type.tests/integration/test_okf_import.py::test_a_theurian_exported_and_a_vanilla_concept_both_draft_at_inferred_trustis the one about the artifact: it imports a bundle whose concept front matter saystheurian_trust_level: reviewed, readstrustLevelout of each written migration's second operation, and assertsinferred. - An import lands under a proposal directory and reaches no approved state (decision 6).OkfImportServiceis constructed with aDraftOnlyProposalsand calls only its two draft entries;cli/okf_commands.py::_serviceis where that facade is built. The facade itself is pinned bytests/unit/test_draft_only_proposals.py::test_no_reachable_attribute_of_the_facade_is_named_for_an_approved_state_mover, which asserts a facade's non-dunder attributes equal{_draft, _draft_from_document, draft, draft_from_document}, and by::test_the_facade_does_not_expose_an_approved_state_mover, parametrized overaccept,_commitand_service. Both build the facade over a spy service, so their subject is the facade's surface rather than this import's writes. The import side is held where the proposal directories are read: every assertion above reads a migration out of the drafted proposal's own directory, andtests/integration/test_okf_import.py::test_too_many_admitted_operations_refuses_the_whole_import_before_draftingassertspaths.proposalsholds no directory at all after a cap refusal. The residue is named under Still owed rather than counted here. - INV-8's floor is the bundle's own identity anchor, present whatever the bundle'ssources[]says:_source_anchorsputsokf-bundle:<bundle-relative path>first and appends an entry only when_is_uri_or_relative_pathadmits itsresource.tests/integration/test_okf_import_deepening.py::test_a_uri_and_a_relative_path_become_anchors_a_scope_descriptor_does_notbuilds one concept with threesourcesentries — a URL, a relative path and the scope descriptorall queries in BigQuery project X— and asserts the written migration carries exactly threesourceAnchors, the firstokf-bundle:sources-test.md, with none namingBigQuery. What no fixture builds is a bundle whose only entry is a scope descriptor; the concepts carrying nosourceskey at all are admitted and drafted throughout these files, which is the same zero-usable-entries case arriving by absence instead of by exclusion. - The three containment pins of decision 6.tests/integration/test_okf_import_path_containment.pydrives an absolutetheurian_body_file, a symlinked concept file inside the bundle, and a sidecar reached through an in-bundle symlink; each case asserts exactly one refusal, the bundle's other concept still admitted, and the outside file's sentinel bytes absent from every byte written under.theurian/proposals/. The../form istests/integration/test_okf_import.py::test_a_bad_body_file_reference_is_refused_without_the_resolved_path_or_the_bundle, which asserts the refusal'sliteralis../../../../etc/passwdverbatim. The third pin — a refusal records the reference as written, never the resolved target — istests/integration/test_okf_import_path_containment.py::test_no_refusal_or_drafted_file_carries_the_operator_filesystem_layout, which sweeps every refusal'sliteraland every byte under.theurian/proposals/for the run's own temporary-directory string, andtests/integration/test_okf_cli.py::test_okf_import_reports_a_refusal_by_kind_key_and_literal_never_a_resolved_path, which asserts the same over the CLI's whole JSON payload. Beside them,tests/integration/test_okf_import_path_containment.py::test_a_bundle_root_under_a_symlinked_parent_directory_still_admits_in_bundle_referencesholds the other direction: a bundle under a symlinked parent is not refused. - The round-trip's content-type boundary: export is total, import narrows to three literal media types, and — for a concept that names a sidecar — nothing outside them is silently dropped. Decision 7's export is total over content types (sidecar_extensionmapsapplication/jsonand any+json-suffixed type to.json,application/yaml,text/x-yamland any+yaml-suffixed type to.yaml, and everything else —text/plainandapplication/vnd.oai.openapiincluded — to.txt). Import re-admits onlydomain/proposal.py::body_extension's own three literal keys —text/markdown,application/json,application/yaml, the proposal-body domain — never the format classes export accepts: an alias export sidecars under the same extension (application/schema+jsonto.json,text/x-yamlto.yaml) still refuses on import despite its body genuinely being JSON or YAML. A content type outside the three literals, on a concept that names atheurian_body_file, is never a silent drop: it is a surfaced, typed per-reference refusal (kind="reference", keyedtheurian_content_type) whose literal states the three-member set and the alias caveat by name. When a concept names notheurian_body_fileat all, this check never runs:_resolve_bodyreturns the inline body astext/markdownon its very first line, beforetheurian_content_typeis read at all — a concept declaring, say,theurian_content_type: application/jsonwith no sidecar therefore admits with zero refusals, its declared type silently unread rather than enforced. Pre-existing behaviour, recorded here rather than fixed: unpinned, recorded from the release-cut round's measurement, and its handling is owed to a filed backlog issue rather than to a named milestone. Alias normalization — widening import to export's format-class rule — is a deliberate non-goal here, owed to a filed backlog issue rather than to a named milestone, because it widens the admitted set rather than fixing a defect in the boundary just stated.tests/integration/test_okf_roundtrip.py::test_every_position_and_content_type_round_trips_as_the_matrix_saysdrives this: twelve concepts over {root, namespaced} x {markdown, json, yaml, text/plain, openapi}, plusapplication/schema+jsonat the root andtext/x-yamlnamespaced, through the real write path (init,migrate apply,okf export) and back throughOkfImportService.import_bundleinto a second, independent project. It asserts the six markdown/json/yaml cells at both positions are exactly the admitted set, that each admitted sidecar body equals its source byte for byte, that each admitted markdown body's decoded content contains its (stripped) source text, and that each of the other six cells produces exactly one"reference"refusal whose literal is the boundary sentence above — counted per content type, so the twotext/plaincells and the twoapplication/vnd.oai.openapicells are each held to two matching refusals and the two alias cells to one each. -theurian_body_fileresolves against the concept's own directory (H-1), and containment stays scoped to the bundle root regardless of that base — decision 6's own wording. A namespaced concept's sidecar sits beside its own document (decisions 2 and 7's document-relative filename); resolving the reference against the bundle root instead silently lost every namespaced non-markdown concept on re-import before this fix. The two outcomes decision 6's containment rule — "resolve under the bundle root after symlink resolution" — draws are each pinned:tests/integration/test_okf_import_path_containment.py::test_a_namespaced_concepts_body_file_that_truly_escapes_the_bundle_is_still_refusedbuilds a namespaced concept (backend/deep.md) whosetheurian_body_fileis../../outside-sidecar.jsonand asserts exactly one refusal keyedtheurian_body_filewith the literal verbatim, that only the bundle's other, untouched concept admits, and that the outside file's sentinel bytes reach no written byte;::test_a_body_file_crossing_into_a_sibling_namespace_inside_the_bundle_is_admittedgives the same concept atheurian_body_fileof../sibling/data.json— crossing into a sibling namespace while staying inside the bundle root — and asserts no refusal, the concept admitted with its sidecar's bytes read back byte for byte, and its drafted migration'ssourceAnchorsholdingokf-bundle:backend/deep.mdfirst andokf-bundle:sibling/data.jsonpresent. The second anchor is MEDIUM-1's fix: without it, an admitted cross-namespace body'ssourceAnchorsnamed only the concept document it did not come from. - The T-3 threat-model entry for the import path, named in What this does not close item 4. It is written as the third arrival route inside T-3 rather than as a new entry, because the root cause is T-3's own and decision 6 says so; the grade stays High and no control is added, so the threat summary row does not move.
Landed in slice S2 (the export). It merged after slice S3 and is written below
it for that reason rather than by slice number. Each item's reach is stated as its
body holds it — the fixtures it builds and the assertions it makes. Three files
carry them: tests/integration/test_okf_export_batteries.py holds the four
batteries and the assembler-side pins beside them, each zero-assertion with its
own positive control; tests/integration/test_okf_export.py holds the shape of
each rule, one rule per test; tests/integration/test_okf_commands.py holds the
command's own surface through the real CLI.
- Decision 3's two-corpora equality.
test_okf_export_batteries.py::test_a_corpus_holding_withheld_rows_exports_the_bundle_of_one_that_never_didbuilds two state databases — one holding two served rows plus adraft, arejected, adeprecatedand aconfidentialrow with five edges into them, one holding the served rows and their one served edge — exports both, and asserts the file names and then the file contents are equal and that the two reports are equal withbundlePathreplaced. Its own controls are in the same body: the two databases' row counts differ, and so do the two state hashes. The belt beside it is::test_no_byte_of_the_bundle_carries_a_withheld_rows_id_title_body_or_note, which sweeps every id, title, body and relation note those four rows and five edges own against the concatenated bytes of every bundle file and asserts none is found, with the served edge's note asserted present; and its positive control::test_the_marker_sweep_finds_a_withheld_row_once_the_gate_admits_itlowers one row's sensitivity into the served ceiling, nothing else changed, and asserts that row's id, title, body and both of its edge notes then do appear. - Decision 2's determinism, which is Phase F ②'s exit criterion.
::test_two_exports_of_one_canonical_state_write_byte_identical_treesexports one database twice and asserts the file contents, thebundleDigestvalues and the reports are equal. The corpus is held to reaching all four ordering rules by::test_the_determinism_corpus_reaches_every_ordering_rule_it_claims_to, which assertstagsandsources[]in row order; an invertible pair stored both ways, whose two entries share a type and a target and differ only by their notes, rendering in the exact order each channel produces — the front matter's normalised order and the body'slist_relationsorder, which is where the two stop agreeing; the fiveindex.mdpaths a nested namespace produces; a sidecar; and a reserved leaf escaped.::test_two_exports_under_different_hash_seeds_agree_byte_for_byteruns the export in two child processes underPYTHONHASHSEED1and4294967295and asserts each child's digest and per-filesha256map equal the in-process run's, with ahash()probe differing between the children as the control that the seeds took. And::test_the_rendered_bundle_does_not_depend_on_the_order_the_walk_returnedrenders the walk's own concepts forwards and reversed and asserts equal files and equal digests, having first asserted the two orders differ and that the concepts carry at least five relations — so the permutation reaches the relation-derived bytes. - The bundle path is derived from the item id, so a crafted
namespacereaches no path component.test_okf_export.py::test_the_path_comes_from_the_item_id_and_never_from_the_namespaceexports one row whosenamespaceis../../../etc/passwdand asserts the concept is atarchitecture/auth/policy.md, that the crafted string is published astheurian_namespacedata, and that no bundle filename containsetc. The rendered channels are held separately, because a filename check cannot see them:test_okf_export_batteries.py::test_every_link_the_exporter_generates_resolves_inside_the_bundleasserts every link target the exporter writes — front matter, the generated## Relationssection, the index files, the manifest and the sidecar paragraph — resolves to a bundle member, over a corpus whose every row carries that same crafted namespace, with the authored body excluded from the population by a recorded decision (ADR-0010 rule 5). - A non-markdown row exports as a sidecar, and the row is present either way.
test_okf_export.py::test_a_non_markdown_body_becomes_a_sidecar_rather_than_a_refusalis parametrized overapplication/json,application/schema+json,application/yaml,text/x-yaml,application/vnd.oai.openapiandtext/plain, asserting per case the sidecar's contents,theurian_body_file,theurian_content_type, that the generated link's text and target are both the derived filename, andsidecars == 1.::test_a_sidecar_holds_the_body_column_byte_for_bytereads thebodycolumn out of the database and asserts the sidecar's bytes equal it encoded — the bytes-equal half — and::test_a_markdown_body_is_embedded_and_no_sidecar_is_writtenis the complementary arm. - A media type outside
_EXTENSIONSexports rather than refusing, which is where the rejected first draft would have denied the whole corpus its bundle.test_okf_export_batteries.py::test_a_media_type_outside_the_proposal_map_exports_rather_than_refusingbuilds one served markdown row beside anapplication/vnd.oai.openapirow and asserts the whole file set is exactly five names, that the sidecar holds the body's bytes, andsidecars == 1— the whole set, so the row is present and nothing else was dropped to accommodate it. - The suffix rule's collision face, closed at two layers.
::test_a_sidecar_and_its_concept_document_are_two_files_neither_overwriting_the_otherasserts the sidecar's bytes,theurian_body_file,theurian_item_id, that the concept document does not also carry the body, and that the sidecar carries no front matter. ThecontentFile-ending-.mdcase is driven through the real CLI, because acontentFileexists only in a migration:::test_a_yaml_row_whose_body_file_ends_md_still_exports_two_distinct_filesrunstheurian init, writes a migration whosecontentFileends.mdundercontentType: application/yaml, runstheurian migrate apply, thentheurian okf export, and asserts the exported file set is exactly five names —api/orders-spec.mdandapi/orders-spec.yamlamong them — that the sidecar's bytes are the body's, and that the concept carries its item id. The third reason decision 7 takescontentTypealone is held against the schema by::test_the_snapshot_holds_no_body_file_path_for_a_suffix_rule_to_read, which asksPRAGMA table_info(knowledge_revisions)and asserts no path-shaped column is there whilecontent_typeis. - The export reads one canonical snapshot (decision 3).
::test_a_withdrawal_landing_mid_walk_leaves_the_bundle_wholly_before_itwraps the store in a session that, immediately after the walk's firstlist_itemsreturns, lands a real withdrawal and a new edge through a second connection in onewrite_transaction— the waymigrate applywrites. It asserts a fresh reader sees both statements committed, that a relation read followed the write, that the contended export's files and report equal a quiet export's, and that the late edge's note is in no bundle byte. Its control::test_the_same_interleaved_write_does_change_a_later_exportasserts each statement changes a later bundle on its own, so the equality above is the snapshot holding rather than a write that would have changed nothing. - The reserved-name rule is positional, in all six of its faces.
test_okf_export.py::test_a_reserved_leaf_escapes_exactly_where_the_name_means_somethingis parametrized over the six ids and asserts per case the escaped path, thatindex.mdand the manifest both survive, and that the id round-trips intotheurian_item_id.test_okf_export_batteries.py::test_every_reserved_name_escapes_where_it_means_something_and_nowhere_elseputs all six in one corpus and asserts the exact file set of nine names — includingarchitecture/theurian-bundle.mdunescaped, which is the root-only rule — plus that the nested manifest-named concept carries notheurian_bundle_digestand the real manifest carries notheurian_item_id. Beside them:::test_the_index_at_each_level_lists_the_escaped_concept_beside_itselffor the nested index entries the parametrisation cannot see,::test_a_reserved_leafs_sidecar_follows_the_escaped_stem, and::test_no_item_id_can_be_spelled_as_an_escaped_name, which rests the no-collision claim onItemIdrefusing the escaped spellings. - The escaping rule of decision 2, at both site kinds and at the export level.
::test_one_row_cannot_forge_structure_at_either_site_of_the_full_exportis the assembler-level discharge — the codec's own primitives closed in #810, and what a bundle's safety rests on is that the exporter applies each escape at the site whose grammar it was written for. One row'stitlecarries a newline followed bytheurian_sensitivity: public, a label-closing](/x)with an attacker-chosen destination, raw inline HTML and a code span; one edge'snotecarries a## Relationsline, a forged relation row, a second link and a### forgedheading. It asserts exactly onetitle:and onetheurian_sensitivity:line in the concept, that the published sensitivity is the item's own while the title round-trips whole, that the root index holds three*entries with the subject's target genuine and no live inline construct in its label, that the concept's only#-opening lines are## Relationsand### related_to, and that every rendered line of the note opens no block construct and holds no live inline member. Its control::test_the_hostile_row_would_forge_structure_if_it_were_not_escapedasserts the raw payloads do open those constructs and that both values reach the bundle intact, so the escapes are what made them inert. - The manifest's holder notice and its digest.
::test_the_holder_notice_is_the_same_fixed_text_for_every_corpuscompares the manifest body's paragraphs against a committed four-element constant and asserts the same body bytes across a populated corpus, a reserved-name corpus and the empty one, where the whole bundle is the rootindex.mdand the manifest.::test_the_manifest_names_no_deployment_no_target_and_no_stateasserts the project id, the target path, the database path and its filename, and the state hash the database records, are each absent from the manifest.::test_the_bundle_digest_recomputes_from_the_bytes_on_diskrebuilds the digest from the bytes on disk in the stated path order and asserts the manifest's own front-matter value and the report'sbundleDigestboth equal it. - No option widens the population (decision 3), asked twice because the two
instruments differ.
test_okf_commands.py::test_the_export_takes_no_option_that_widens_the_populationreads the rendered--helpand asserts the options are--helpand--jsonalone, with the usage line ending[OPTIONS] {directory};test_okf_export_batteries.py::test_the_export_command_registers_exactly_one_argument_and_one_optionreads the registered command object instead — so ahidden=Trueoption, which appears in neither the options list nor the usage line, is in scope — and asserts the param list equals the requireddirectoryargument and the--jsonflag, with no hidden param. - The threat-model entry for the distributed-bundle residual, named in What this does not close item 1 and owed by this slice. Written as a new numbered entry, T-27, graded High and accepted, with the item's four bounds as its controls table and three further export-side surfaces recorded beside them. The threat summary gains its row; item 1 carries the amendment that says so.
Landed after slice S3, in #962:
- Slice S3's residue: a structural pin that the import's own composition root
is handed the draft-only facade, which is what the discharged item above
stops short of.
application/okf_import.pynamesacceptnowhere —git grep -n accept -- packages/theurian-core/src/theurian/application/okf_import.pyexited 1 with no output (rotted: at6c3c2827it exits 0 on two content-type hits,:341and:371) — andOkfImportService.__init__annotates its collaborator asDraftOnlyProposals, so what carried the property was mypy plus the facade's own in-isolation pins, neither of which readscli/okf_commands.py::_service. The shape to copy is ADR-0032's, which has landed for the MCP server:tests/integration/test_mcp_tools.py::test_the_object_a_write_intent_tool_is_handed_is_the_draft_only_facadebuilds the server, reaches the object each write-intent tool closes over, and asserts its type isDraftOnlyProposals, that it is not aProposalService, and that it exposes no approved-state mover. Owed with no owner until #708 took it. The owed-item cross-reference this bullet replaces read the same shape ADR-0032 and ADR-0035 owe; ADR-0032's half is the landed test just named, and ADR-0035's items come due when its interactive-curation mechanism lands. Landed in #962. The re-check istests/integration/test_okf_cli.py::test_the_import_service_is_handed_the_draft_only_facade_and_not_the_service, RED when_servicehands over the rawProposalService, andtests/integration/test_write_intent_facade_population.py::test_every_facade_surface_is_one_a_wiring_test_drivesholds the facade surfaces at 2 construction sites, 0 subclasses and 2drafts=consumers (measured at6c3c2827; its docstring carries the keys for the sites and the consumers, and the 0 subclasses is keyed only by its"subclasses": {}assertion).
Still owed, with the slice that will satisfy it:
- Slice S3's residue moved to Landed after slice S3 above.
- Nothing else. Slice S2's items moved to Landed in slice S2 above, including the prose one — the threat-model entry for the distributed-bundle residual, which landed as T-27 rather than as an amendment to an existing entry, exactly as this bullet predicted it would have to.