Skip to content

feat(file): identity is the rel — the mint flips, and the trace records the binding - #596

Merged
David-Noble-at-work merged 3 commits into
developfrom
rel-file-identity
Aug 21, 2026
Merged

David-Noble-at-work merged 3 commits into
developfrom
rel-file-identity

Conversation

@David-Noble-at-work

Copy link
Copy Markdown
Contributor

Phase 2, PR 1 of resource-construction (#584).

The mint

File identity mints from SourcePath.Rel() in the ruled opaque form — "file:" + rel, slash-canonical on
every platform (4.1's amended row and sketch). The fsroot is a run parameter, so the rel half is what
serializes and one graph relocates across prefixes. The native form is access, not identity: consumers use
SourcePath.Abs(), never URI parsing (the #547 rule). Escaping rels (../…) still mint until PR 2's
grammar refuses authoring them.

The binding

The 2026-08-18 revert's "four consumers" resolved empirically to one seam: writ's readback parsed the
URI's embedded absolute path and keyed drift attribution by it. Design-true fix: ResourceLedgerSnapshot
gains Root — the run's bound fsroot, stamped by the executor at capture — and recordedIdentity joins
the recorded root with each entry's rel to derive its native keys. §5.5 records the doctrine: the graph
stays root-free (intent); the trace records the binding (observation).

Windows expectation: 3 → 2

TestDiscoverRegular_ForeignSchemeString_IsAPath pins the rel form (file:https:/example.com/x), which is
platform-neutral — expected to clear. The remaining two (TestSourceFile_StarlarkIntegration,
TestWriteOnboardManifest…) are path-as-text at their authoring/narration surfaces — PR 2's work, per the
review diagnosis now recorded in the plan.

Verified

  • make check — 103 ok, 0 failures (the full suite, writ drift attribution included)
  • make vet GOOS=windows
  • gofmt clean

Refs #584, #547, #546.

…rds the binding

Phase 2, PR 1 of the resource-construction plan (#584). File identity mints from SourcePath.Rel() in the
ruled opaque form: "file:" + rel, slash-canonical on every platform (4.1's amended file-scheme row and
sketch, landed in phase 0). The fsroot is a run parameter, so the rel half is what serializes and the same
graph relocates across prefixes; no volume, home layout, or separator variance enters identity. The
native form is access, not identity -- consumers reach it through SourcePath.Abs(), never by parsing the
URI (the #547 rule). Escaping rels ("../...") still mint until PR 2's plan-space grammar refuses authoring
them.

The 2026-08-18 revert's consumer hunt resolved empirically to ONE seam, not four: writ's readback parsed
the URI's embedded machine-absolute path and keyed drift attribution by it. The design-true fix: the
trace's ledger snapshot gains Root -- the run's bound fsroot, stamped by the executor at capture (both
capture sites route through the extracted captureLedgerSnapshot) -- and recordedIdentity derives its
native keys by joining the recorded root with each entry's rel payload. Section 5.5 records the doctrine:
the graph stays root-free (intent); the trace records the binding (observation), because a recorded rel is
interpretable only against the root that ran it.

The foreign-scheme pin re-asserts against the rel form (file:https:/example.com/x), which is
platform-neutral -- this is one of the three Windows baseline failures and is expected to clear. The plan
carries the phase-2 review findings (failure diagnosis from the live CI logs, the grammar/harness
co-landing constraint, the three-PR slicing) and this PR's record.

Verified with make check (103 packages ok, 0 failures) and make vet under GOOS windows. Windows baseline
expectation: 3 -> 2 (the remaining two are path-as-text at their authoring/narration surfaces, PR 2's
work).

Refs #584, #547, #546.
@David-Noble-at-work David-Noble-at-work self-assigned this Aug 21, 2026
…led form

The Windows re-diagnosis of PR 1's first CI run: the expected 3 -> 2 came back as 3 with a NEW name --
TestDiscoverRegular_PathAndOwnSpecific_SameIdentity panicked in fsroot.makePath, because the test hardcoded
the retired emitted form ("file://" + abs). Stripping the new "file:" prefix from that spelling leaves
"//C:\..." on Windows, which reads as UNC and cannot be made root-relative. On unix the same spelling
survives by accident (the extra slashes clean away), which is why only Windows caught it.

The pin now asks the resource for its own specific (ReachabilityURI()) instead of spelling one, so the
round trip follows the mint permanently. The foreign-scheme pin cleared as predicted, so the Windows
expectation for this branch remains 3 -> 2.

The plan also records the run-from-elsewhere caveat (USER ruling, 2026-08-21): the existence check reads
the CONSTRUCTION environment's root and feeds the construction-time absolute, so a graph saved and run
later from elsewhere verifies against the wrong root -- plan-and-run-in-one-session flows merely hide it.
PR 3's rel-first activation binding at the run boundary is therefore load-bearing for relocation, not
closure hygiene.

Verified with make check (103 packages ok, 0 failures) and gofmt clean.

Refs #584, #547.
The second Windows re-diagnosis of PR 1: the foreign-scheme identity pin failed with
file:./https:/example.com/x -- Windows filepath.Clean guards a first segment containing a colon with a
leading "./" (the CVE-2022-41722 drive-relative disambiguation), and the guard rode through ToSlash into
the rel, so the same input minted different identities per platform. Exactly the class #547 predicted
("the sixth is waiting"), and exactly where its rule says to fix it: in the type, not at a call site.

fsroot.canonicalRel (slash-path Clean after separator normalization) now renders every rel -- both
makePath branches and fsroot.NewPath -- so OS guards, duplicate slashes, and dot segments alike collapse
to one neutral form. A platform-neutrality pin (TestRoot_NewPath_ColonSegmentRelIsPlatformNeutral) runs
the colon-segment case across every root variant on all three CI platforms. Recorded on #547 as the
sixth-discovery table row.

The plan carries the sixth-discovery record and PR 2's new obligation: the plan-space grammar reserves
the root-qualification spelling for #597 (the named multi-root design question, filed under #546), so the
little language does not break when (root-name, rel) identity lands.

Verified with make check (103 packages ok, 0 failures), make vet under GOOS windows, gofmt clean. Windows
expectation for this branch: 3 -> 2.

Refs #584, #547, #597.
@David-Noble-at-work
David-Noble-at-work merged commit 92c18eb into develop Aug 21, 2026
7 of 8 checks passed
@David-Noble-at-work
David-Noble-at-work deleted the rel-file-identity branch August 21, 2026 07:06
David-Noble-at-work added a commit that referenced this pull request Aug 21, 2026
…se 2 closes (#601)

Phase 2, PR 3 of the resource-construction plan (#584) -- the activation binding the run-from-elsewhere
ruling made load-bearing: a graph is planned or loaded in whatever environment happened to construct its
resource objects, but every location fact about them belongs to the root the RUN binds.

The executor's pre-flight resolve pass now re-bases every pending entry onto the run's environment and
re-binds root-relative schemes rel-first through the new op.RootBinder seam: identity (the rel) is
unchanged, the root becomes the run's, the native form derives. file.Resource implements BindRoot, and
Resolve's abs-first rebind -- the documented inverse, which preserved the construction-time machine
location -- flips rel-first. The verification consequence stays mark-don't-fail; phase 3 owns the
transition-failure semantics.

Pinned in both directions: a graph planned under root A and executed under root B verifies and observes
under B. The trace records B as the binding; the claimed rel is Active when the file exists only under B
(the plan root never held it), and Gone when it exists only under A (with the dispatch failing to find
it). PR 1 made the identity payload relocatable; this PR makes the verification relocatable -- the two
halves of "one graph, any machine."

Phase 2 is complete: rel identity (#596), the plan-space grammar and authoring migration (#600), and the
binding (this PR). The Windows CI leg went 28 known failures to zero during this phase and #547 closed;
step 4's consumer sweep finished across the three PRs (readback in PR 1, providers already on the
accessor, Resolve's rebind here). Closes #584.

Verified with make check (103 packages ok, 0 failures) and make vet under GOOS windows. Windows
expectation: green stays green.

Refs #546, #585.

Co-authored-by: David Noble <[email protected]>
David-Noble-at-work added a commit that referenced this pull request Aug 22, 2026
…ion (#607)

The plan and design documents catch up with the campaign through phase 3 (#582-#585 delivered; #586-#587
remain).

The plan (resource-construction.md): status in-progress; the phase-2/3 headings carry the merged PR
numbers (#596/#600/#601; #602-#606); delivered markers on the docket's items 4/5, judgment scenario 1,
and the fail-fast scenario; the directive-inventory rulings gain an execution-status note (the wire
rename ran; the planner/struct_param/lifetime removals are chartered, not executed); the divergence table
records which rows phases 0-3 resolved and which are phase 4's subject; phase 5's already-satisfied items
are marked.

4-resource-management.md: the header's staging note now says phases 0-3 are in the tree; SS2's
execution-time summary reflects bind-then-scoped-verify; SS3's delivered note extends to C2 (#606) --
every file-scheme mutator is a resource-typed consumer; SS5.4 marks the {id, uri} intent row delivered
(#602); SS9 gains rulings 12-14 (claims taxonomy with Skip dropped, scoped verification, resource-typed
mutation targets). The status companion records the landed phases and narrows outstanding work to
#586 + #587.

4.1-resource-identity.md: identity never changes after construction -- the three "Resolve updates the
cached URI" passages are replaced, the interface sketch corrects to Resolve() error with the RootBinder
seam named, and file's opaque catalog identity (file:<rel>) is disambiguated from the rendered
hierarchical form in SS2 and SS6. The status companion gains the rel-identity completion row.

3.5.4-file-provider.md: the mutator table carries the landed signatures (typed targets, on_missing
defaults), a consumption-model paragraph ties the mutators to the claims taxonomy, and the SymbolicLink
row records lstat existence. 2-execution-graph.md: Run's description includes the pre-flight binding
pass and per-scope claim verification.

Refs #581.

Co-authored-by: David Noble <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant