documentIri pinning causes frontmatter rootEntity override to disagree with promote partitioning

[Jurij89]

Summary

The import-file route handler in packages/cli/src/daemon.ts pins documentIri: assertionUri when calling extractFromMarkdown. This causes all structural content triples (frontmatter properties, H1→schema:name, wikilinks, hashtags, dataview fields, section headings) to be emitted with the assertion UAL as their subject — regardless of whether the user supplied a frontmatter rootEntity override.

The result is a semantic mismatch: _meta row 14 (<assertionUal> dkg:rootEntity <urn:note:parent>) claims the assertion's root entity is urn:note:parent, but the actual content triples partition under <assertionUri> when assertionPromote runs — NOT under <urn:note:parent>. A SPARQL consumer querying "what content belongs to urn:note:parent?" finds nothing in SWM for assertions that were supposed to be about it.

This was flagged by Codex Review as Bug 10 on PR #121 (see #121 (comment) or whichever review link applies). It was deliberately deferred out of the PR #121 Round 4 scope because it's architectural — fixing it requires either:

1. Extractor rewrites content-triple subjects to resolvedRootEntity when frontmatter rootEntity is set. ~20 LOC in extractFromMarkdown, but has semantic hazards: if two assertions both claim rootEntity: urn:note:parent, they'd both write content triples on <urn:note:parent>, re-introducing the cross-assertion contention problem PR feat: source-file linkage triples + devnet hardening (chain onto PR #120) #121 Bug 8 just solved via the assertionPromote filter.

2. Remove the rootEntity override feature entirely. Drop frontmatter rootEntity precedence from buildSourceFileLinkage. Row 3/14 always = reflexive. Deletes a spec-defined feature (§19.10.1:508) but sidesteps the semantic question.

3. Document the current behavior as "rootEntity is a metadata HINT, not a content-retargeting". Row 14 in _meta is an annotation/backlink, not an authoritative partition statement. Zero code change beyond comments.

The Round 4 consensus (parked as a follow-up, not a decision) was that 10C — documenting the current behavior — is the smallest defensible path, and that 10A's semantic hazards around cross-assertion subject contention need a wider architectural discussion before we commit to a retargeting pipeline.

Context

• PR feat: source-file linkage triples + devnet hardening (chain onto PR #120) #121 tip: feat: source-file linkage triples + devnet hardening (chain onto PR #120) #121
• Bug 10 was surfaced in Round 4 of Codex Review alongside Bugs 7, 8, 9, 11, 12, 13. Bugs 7, 8, 9, 11, 12, 13 were fixed in PR feat: source-file linkage triples + devnet hardening (chain onto PR #120) #121 Round 4. Bug 10 was deferred per team-lead's call.
• Related spec section: 19_MARKDOWN_CONTENT_TYPE.md §10.1 rows 3 and 14 (rootEntity); §19.10.1:508 promises the frontmatter override is honored.
• Related code: packages/cli/src/extraction/markdown-extractor.ts resolveSubjectIri (line ~226) + buildSourceFileLinkage (line ~498); packages/cli/src/daemon.ts import-file route handler extractFromMarkdown call site with documentIri: assertionUri.

Acceptance criteria

Whichever option is chosen, the outcome should be that a user who sets frontmatter rootEntity: urn:note:parent on a document and then imports it gets either:

• A consistent graph where content-triple subjects actually match _meta row 14 (Option 10A), or
• Clear documentation that rootEntity is a hint, not a retargeting directive (Option 10C), or
• A spec update that removes the promise in §19.10.1:508 (Option 10B).

Not blocking

This is tracking a known-deferred issue; the current PR #121 ships without fixing it. Users who hit the mismatch today can work around it by leaving rootEntity unset (the reflexive default is correct and consistent), or by accepting that the _meta annotation is informational.

[Jurij89]

Additional context from PR #121 review iteration

Several pieces of architectural context emerged during PR #121's review cycle that are worth archiving here before whoever picks this up has to re-derive them.

1. The mismatch surfaces at three distinct code locations

Codex flagged the same rootEntity override vs promote-partitioning inconsistency at three separate file:line pairs during PR #121:

• packages/cli/src/daemon.ts:2613 — the original Bug 10 finding (extractor call site, documentIri: assertionUri pinning)
• packages/cli/src/extraction/markdown-extractor.ts:529 — the emission point where resolvedRootEntity is plumbed into the linkage quads
• packages/cli/src/daemon.ts:2705 — the _meta row 14 emission (<assertionUri> dkg:rootEntity <resolvedRootEntity>)

This tells us the bug is systemic to the documentIri pinning decision, not a local patch at any one emission point. A future fix that patches only one of these locations will leave the mismatch visible from the other two. The real fix needs to happen at the documentIri resolution level — either make it follow resolvedRootEntity, or enforce that resolvedRootEntity cannot diverge from the document subject that autoPartition sees.

2. Option 10D (reject-with-error) — ready-to-ship interim if the full fix is too expensive

During PR #121's Round 5, spec-engineer produced a detailed alternative design that explicitly wasn't shipped (per project direction to avoid blocking the PR on this issue), but is valuable groundwork for the eventual fix in this issue. Archiving the design here so whoever implements this doesn't have to re-derive it:

Option 10D — reject frontmatter rootEntity override with 400 on the import-file path until the full plumbing lands. Preserves the spec promise in §19.10.1:508 as a deferred implementation (error message literally says "not yet supported, tracking in this issue") rather than a silent acceptance that produces inconsistent state.

Asymmetric handling recommended: reject only the frontmatter-sourced override on the import-file path; allow programmatic rootEntityIri input (from internal callers with their own plumbing) to pass through unchanged. This keeps a forward-compatible escape hatch for test harnesses, batch migration jobs, and any future internal caller that explicitly accepts the current limitation.

Draft error message (adaptable):

Frontmatter 'rootEntity' override is not yet supported on the import-file path and would produce an inconsistent _meta vs promote-partition state. Remove the 'rootEntity' key from frontmatter and re-upload; the override will be honored once #122 lands (tracking §19.10.1:508 plumbing through the promote path). Alternatively, publish directly via assertion.write with the resolved root entity as the subject of your content triples.

6-point implementation sketch:

1. Add a new error class (or reuse an existing extraction error class that surfaces as 400 at the daemon route handler)
2. In buildSourceFileLinkage (or just before it in extractFromMarkdown), detect frontmatter.rootEntity !== undefined and throw when the caller is flagged as the import-file path
3. Gate via an input flag: add source?: 'import-file' | 'internal' (or rejectFrontmatterRootEntity?: boolean) to MarkdownExtractInput. Daemon import-file route sets it; programmatic callers omit
4. Verify the daemon route handler's existing try/catch surfaces the extraction error as 400 (not 500)
5. Tests: unit test rejects frontmatter override with source: 'import-file'; unit test allows programmatic rootEntityIri override still works; integration test POST returns 400 with error message
6. The 400-rejection tests become the canary for this issue — when the full plumbing lands and 10D is removed, the tests fail and trigger re-assertion of the honored-override behavior

Note: 10D is a temporary rejection, not a permanent behavior. The eventual fix this issue tracks is the real plumbing rework so the override is actually honored end-to-end. 10D is available as a cheaper interim if the full fix needs more design time — particularly if someone wants to merge other work that touches the extraction path without inheriting the silent-inconsistency risk.

3. Blank-node subordinate subjects do NOT work — autoPartition caveat

One natural-looking alternative that does not work and isn't worth re-trying: using blank nodes as subjects for subordinate data (file descriptor blocks, dkg:ExtractionProvenance resources, or by extension the content triples under a resolvedRootEntity).

PR #121's Round 3 shipped blank-node subjects for the file descriptor block and the ExtractionProvenance block. The approach was reverted in Round 4 after tracing packages/publisher/src/auto-partition.ts end-to-end against the actual emitted quad set:

• Phase 1 (root entity collection, lines 15-21) correctly excludes blank-node subjects from the root entity set per 03_PROTOCOL_CORE.md §1:99,154,156. ✓
• Phase 2 (blank-node attachment, lines 26-48) seeds blankToRoot only from quads where a root-entity subject has a blank-node object. Propagation in the while (changed) loop requires blankNode subject → blankNode object, so any blank-node subgraph without an incoming edge from a root entity is never attached.
• Phase 3 (partitioning, lines 58-67) drops quads with unattached blank-node subjects.

Concrete impact for PR #121: rows 4-8 (file descriptor block, reachable via <entityUri> dkg:sourceFile _:file1) survived promote via line-28 mapping. But rows 9-13 (ExtractionProvenance, with subject _:prov1) had no incoming edge from a root entity — _:prov1 only appeared as the subject of rows 9-13 and as the object of row 10's _:prov1 dkg:extractedFrom _:file1 (wrong direction for Phase 2 propagation). They were silently dropped from SWM on promote. Unit tests passed because they exercised WM state; integration tests via promote would have caught it had they existed.

Implication for this issue: if someone attempts to solve rootEntity override by moving content triples under a blank-node subordinate resource (same pattern spec-engineer initially proposed for the file descriptor), they will hit the same silent-drop behavior. Any blank-node-based fix needs an explicit incoming edge from the document-entity root, and any propagation chain needs to walk in the subject → object direction that Phase 2 supports. See the auto-partition.ts trace in PR #121's Round 4 discussion for the full analysis.

The final PR #121 solution (Option B: filter urn:dkg:file:* and urn:dkg:extraction:* subjects out of quadsToPromote in assertionPromote before partitioning) sidesteps the whole blank-node attachment question by keeping those resources as URIs in WM and filtering them out before promote ever sees them. That approach worked for the file descriptor case because the descriptor is bookkeeping; it would NOT work for content triples because content triples are the semantic payload that promote needs to promote.

---

Scope recap: this issue tracks the architectural fix for documentIri pinning so the rootEntity frontmatter override is honored end-to-end by assertionPromote. PR #121 ships with three deferred markers (Bugs 10, 16, 18 — the three file:line locations listed above) pointing at this issue. None of them are blocking merge of PR #121.

[Jurij89]

Update — PR #121 now carries 5 deferred markers, not 3

PR #121's review cycle continued through Rounds 5-11 after this issue was opened. Codex re-surfaced the same documentIri pinning vs promote-partitioning root cause at two additional locations, bringing the total deferred-marker count on PR #121 to five.

Deferred markers on PR #121 (all pointing here, all left open as visible markers):

#	Thread ID	Location	Round flagged
Bug 10	PRRT_kwDORwbl8c56TLcv	packages/cli/src/daemon.ts:2645 (was :2613)	Round 4 (original)
Bug 16	PRRT_kwDORwbl8c56TWbZ	packages/cli/src/extraction/markdown-extractor.ts:580 (was :529)	Round 4
Bug 18	PRRT_kwDORwbl8c56Tbh8	packages/cli/src/daemon.ts:2747 (was :2705)	Round 5
Bug 28	PRRT_kwDORwbl8c56T3jv	packages/cli/src/extraction/markdown-extractor.ts:553	Round 10
Bug 32	PRRT_kwDORwbl8c56T7e6	packages/cli/src/daemon.ts:2747 (same line as Bug 18, Codex re-posted with different phrasing, different thread ID)	Round 11

Line numbers shift round-to-round as surrounding code evolves; the thread IDs are the stable references.

Nothing substantively new about the root cause has emerged from Rounds 5-11 — Codex is just flagging the same autoPartition vs dkg:rootEntity divergence at more locations as the PR surface area grows. The architectural analysis in the earlier comment (three-location pattern, Option 10D reject-with-400 design, blank-node attachment caveat) still stands as the authoritative handoff documentation.

Significance of the 5th marker: Bug 32 is on the same line as Bug 18 (daemon.ts:2747) — Codex posted a second review comment at the same spot with slightly different phrasing. This reinforces that the documentIri pinning is systemic to that code path, not a local patch opportunity. Any future fix that targets a single line will leave markers visible from the others. The real fix needs to happen at the documentIri resolution level, as previously noted.

No action needed on this issue yet — PR #121 continues to ship with all five markers deferred. This comment exists purely to keep the deferred-marker count accurate for whoever picks this up.

[Jurij89]

Update — 6th deferred marker added

PR #121 review cycle continued through Round 15. Codex posted a sixth comment on the same documentIri pinning vs promote-partitioning architectural issue tracked here.

New marker (Round 15): PRRT_kwDORwbl8c56UM8J at packages/cli/src/daemon.ts:2791 (same file:line as Bug 18 PRRT_kwDORwbl8c56Tbh8 and Bug 32 PRRT_kwDORwbl8c56T7e6 — Codex has now posted three separate comments with different phrasings at this exact location).

Deferred markers on PR #121 (all open, all pointing here):

#	Thread ID	Location	Round flagged
Bug 10	PRRT_kwDORwbl8c56TLcv	daemon.ts ~2645-2683	Round 4
Bug 16	PRRT_kwDORwbl8c56TWbZ	markdown-extractor.ts ~647	Round 4
Bug 18	PRRT_kwDORwbl8c56Tbh8	daemon.ts:2791	Round 5
Bug 28	PRRT_kwDORwbl8c56T3jv	markdown-extractor.ts ~618	Round 10
Bug 32	PRRT_kwDORwbl8c56T7e6	daemon.ts:2791	Round 11
Bug 44	PRRT_kwDORwbl8c56UM8J	daemon.ts:2791	Round 15

Nothing substantively new — still the same autoPartition vs dkg:rootEntity divergence. Codex has effectively reached the point of repeating itself: three of the six markers are now at daemon.ts:2791, which reinforces the "this is systemic to the documentIri pinning decision, not a local patch opportunity" conclusion from the earlier architectural analysis.

No action needed on this issue. The comment exists to keep the deferred-marker count accurate for whoever picks this up later.