Define structural ownership and document supported attachments (#903, #904)

[flyingrobots]

Closes #903. Define the finite structural ownership and mutation contract from pinned author Paper I/II sources, with executable test-only witnesses. The contract distinguishes owned graph occurrences from opaque bytes and external/live references; it covers node/edge symmetry, well-founded admission, descendant preservation, injective transport, deterministic conflicts, captured bases, truthful receipts, and atomic rollback.

The package still exposes opaque byte attachment operations. This PR adds no recursive Runtime capability and makes no claim of production Paper II compliance. Reference encoding (#819), bounded traversal (#820), and retention/doctor enforcement (#821) consume these laws in their own slices.

Validation at bc7d3b98197b3b43b753b65a035f33d94daeaa28:

• 14 reference witnesses pass in COPY-only Docker and are selected by the existing stable unit shard.
• Four deliberate mutations fail at the expected assertions: cycle admission, descendant protection, partial publication, and ancestor delete/use footprints. Each calibration selects its relevant witness; the other 13 cases are intentionally unrun in that mutated image.
• Complete normal pre-push passes through a Docker npm proxy: lint, source/test/policy/consumer types, declaration surface, Markdown and Mermaid rendering, documentation topology, and stable units. Units: 8,298 passed, two existing skips; 761 passed files, one existing skipped file. No new positive-suite skips.
• Manual SSJS checks are green: immutable validated concepts, boundary admission, behavior on owning modules, no error-message branching, domain host I/O/time/entropy, casts, or fake shape trust introduced.

An initial full-suite image lacked container-local Git and failed existing repository-inventory tests; the corrected COPY image includes a new local Git index and passes the complete gate. Earlier host Markdown output is superseded by the Docker replay and is not acceptance evidence. No host repository or Git directory was mounted.

Independent source review and current-head hosted CI remain required before merge. The PR stays draft while the ownership contract is reviewed.

Integrated top-first dependency

Closes #904. PR #938 merged into this branch at f340fc07a42eea67ee92cc80aaf0533af60d4b3e. This PR now includes the supported byte attachment guide and migration alongside its normative structural ownership prerequisite. Full independent reviews are posted for both slices and the integration; the merge tree is identical to the independently tested top branch. Fresh merge-head checks gate delivery to main.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 26 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 4ad965ad-e6a6-474d-a476-598bf5812ec0

📥 Commits

Reviewing files that changed from the base of the PR and between a6a395e and f340fc0.

📒 Files selected for processing (13)

• CHANGELOG.md
• docs/migrations/v19/README.md
• docs/topics/README.md
• docs/topics/content-and-cas.md
• docs/topics/structural-attachments.md
• test/helpers/structuralAttachments/AttachmentAtom.ts
• test/helpers/structuralAttachments/AttachmentContractTick.ts
• test/helpers/structuralAttachments/AttachmentUpdate.ts
• test/helpers/structuralAttachments/OwnedAttachment.ts
• test/helpers/structuralAttachments/OwnershipPosition.ts
• test/helpers/structuralAttachments/SkeletonRewrite.ts
• test/helpers/structuralAttachments/StructuralAttachmentState.ts
• test/unit/specs/StructuralAttachments.test.ts

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Release Preflight

Head: f340fc07a42eea67ee92cc80aaf0533af60d4b3e · Workflow and complete bundle evidence

• package version: 19.1.0
• prerelease: false
• npm dist-tag on release: latest
• preflight: success
• npm package payload: success
• jsr publish dry-run: success

npm bundle analysis

Metric	Measured	Limit	Usage	Remaining	Assessment
Compressed bytes	742654	760000	97.7%	17346	⚠️ Critical headroom
Unpacked bytes	3245331	3300000	98.3%	54669	⚠️ Critical headroom
Files	968	1050	92.2%	82	⚠️ Approaching limit

Warnings begin at 85% of a limit; critical headroom begins at 95%. Exceeding a limit fails the existing payload gate.

Payload group	Unpacked bytes
Declarations	228179
JavaScript	2895695
Metadata, documentation, and assets	121457

Findings (0)

No static inspection findings.

Static reachability findings are deletion candidates, not proof that a file is safe to remove. Dependency checks cover imports and manifest declarations; they are not a vulnerability audit.

Largest files (unpacked)

File	Bytes	Share
dist/src/domain/RuntimeHost.js	35335	1.1%
README.md	31900	1.0%
docs/migrations/v19/README.md	30752	0.9%
dist/src/domain/orset/trie/TrieCursor.js	24348	0.8%
docs/READINGS_AND_OPTICS.md	23600	0.7%
dist/src/domain/services/controllers/CheckpointController.js	17842	0.5%
dist/src/domain/services/JoinReducerSession.js	17742	0.5%
dist/src/domain/services/PatchBuilder.js	16761	0.5%
dist/src/domain/services/controllers/SyncController.js	16219	0.5%
dist/src/domain/services/optic/CheckpointBasisManifest.js	15503	0.5%

A release-branch merge still requires final preflight and the normal release workflow.

[flyingrobots]

Independent Codex review — PR #932

Head: bc7d3b98197b3b43b753b65a035f33d94daeaa28
Target: main, base a6a395eaecf2c9a0f644d32f89fd67930b975004.

No verified blocking defect found in this contract-and-reference-witness scope. This approval does not certify a production recursive ownership engine or satisfy pending CI.

Verification Checklist

Area	Paths and verification
Admission and identity	OwnershipPosition.ts:8, OwnedAttachment.ts:8, AttachmentAtom.ts:8 under test/helpers/structuralAttachments/ validate/freeze identities. StructuralAttachmentState.ts:28 copies inputs; :97 checks closure, unique owner/child identities, explicit roots and atom ownership; :123 rejects cycles. Tests at StructuralAttachments.test.ts:36, :53, :64 cover these laws.
Mutation and paths	StructuralAttachmentState.ts:51, :63, :73, :81, :131 trace path disclosure, atomic edit/detach, tracking transport, same-kind/same-occurrence images, injectivity and descendant guards. Tests :91, :105, :122, :142 cover empty owned children, node/edge symmetry, permitted nested atomic deletion, and commutation.
Scheduling and failure	AttachmentUpdate.ts:19 includes ancestor uses. SkeletonRewrite.ts:21–:25 declares uses/deletes/writes and transport. AttachmentContractTick.ts:21, :30, :51, :56 sort candidate identifiers, reject conflicts, detect stale basis, privately apply selected transitions, roll back on refusal and freeze receipts. Tests :152–:235 cover both independent serializations, conflicts, ancestor deletion, rollback and stale basis.
Production boundary	No src/, package export or workflow changes. Existing byte capability was traced through src/domain/api/Lane.ts:98, ContentIntentRuntime.ts:29/:52, content observers and Runtime content composition. Documentation explicitly does not promote byte identity, CRDT convergence or these test helpers into recursive production compliance.
Paper requirements	Pinned Paper I 977efe6a61b13df3e3c1ef84cf8e78a4e469ca09, paper/main.tex:211–:231 establishes finite inductive node/edge attachments; :316–:323 establishes atom depth zero and empty-skeleton depth one. Pinned Paper II aced1597b28cee137fe7a898870cf5b694534eaf, paper/main.tex:287, :316, :363, :428, :505 support attachment-plane preservation, atomic abort, delete/use independence, greedy total-order scheduling and unique preserved images under descent. Single-parent occurrences and structural detach/replace refusal are correctly labeled git-warp operational choices.
Scope completeness	Current #903 acceptance is contract plus executable witnesses. Encoding (#819), traversal (#820), retention (#821), full DPOI matching/gluing, persistence and recovery are expressly excluded and not claimed completed.
Merges	git rev-list --merges origin/main..HEAD is empty. Both commits' aggregate diff inspected; there is no merge resolution to audit.
Numbers/constants	Fourteen focused witnesses independently rerun and passed. Four deliberate controls independently rerun: cycle, descendant, atomicity and ancestor-footprint variants each fail its intended assertion. UTF-16 lexical scheduling is an explicit policy, not locale order. No measured runtime performance or production depth bound is claimed. Author raw normal-gate evidence reports 8,298 passing tests and two existing skips; this full gate was inspected, not rerun by reviewer.
Standards and review state	Read binding repository policy and complete diff; new concepts are runtime-backed immutable test classes, no cast or adapter leakage introduced. This adds a contract/model rather than refactoring production code; no whole-module coverage percentage is claimed. Paginated GraphQL discovery at this head found no unresolved review threads or submitted change requests.

Executed: COPY-only Docker reference witnesses and all four calibrated broken controls, without host repository/Git mounts. Inspected: full normal Docker push log, paper sources, declarations, source boundary, complete diff and review conversation. Not executed: a production recursive engine (not implemented by this PR), package release, crash/power-loss testing, or a second full unit suite. Earlier author host Markdown execution and the image lacking a Git index are superseded failed/ineligible evidence; the corrected Docker gate is the acceptance run.

APPROVE

[flyingrobots]

Independent integration review — top-first documentation stack

Current head f340fc07a42eea67ee92cc80aaf0533af60d4b3e; target main a6a395eaecf2c9a0f644d32f89fd67930b975004.

Verification Checklist

• Audited both parents: first bc7d3b98197b3b43b753b65a035f33d94daeaa28 is the independently approved Define recursive attachment ownership and descendant-preserving mutation semantics #903 ownership contract/model; second a8a81d6f7587f8136a63bc3e9c75b0ffa07f0158 is the independently approved Correct public attachment documentation and publish executable capability examples #904 guide/migration. The second parent descends from the first; no unrelated incoming work or conflict resolution exists.
• Merge tree 82811c294162b1060de293264b0cee707a7f8cf5 equals the second parent's tree exactly. Diff against the second parent is empty; diff against the first is exactly the four reviewed documentation paths. No implementation, runtime path, test oracle, numeric constant or package manifest changed during integration.
• The complete independent Define structural ownership and document supported attachments (#903, #904) #932 and Document the supported byte attachment lifecycle and migration (#904) #938 checklists remain the source/path/error/number/evidence coverage for this identical tree. Both authors are separate from this reviewing root agent. The earlier contract review executed 14 witnesses and four meaningful mutation controls; the guide review independently executed full installed-package acceptance including64MiB streaming, retention and negative outcomes. Those executions are not represented as newly rerun against a different tree.
• Main-targeted CI passed all checks on the identical source tree before the top-first merge, including Node22/Bun/Deno/coverage/preflight. The new merge commit correctly triggers fresh hosted checks; those are pending and still gate the main merge.
• Structural ownership remains test-only normative contract; public restored byte attachment API is already in main. The incoming guide respects that distinction, references the contract and preserves Add typed recursive WARP graph attachment references #819/Traverse recursive WARP graphs with cycle-safe bounded receipts #820/Retain and diagnose recursive graph references across CAS boundaries #821 as separate work. No prerequisite disappears through integration.
• GitHub Correct public attachment documentation and publish executable capability examples #904 remains open because merging into the prerequisite branch is not mainline delivery. Both Define recursive attachment ownership and descendant-preserving mutation semantics #903 and Correct public attachment documentation and publish executable capability examples #904 must link the eventual mainline integration commit before tracker completion. No release was performed.

Executed: Git parent/tree/diff comparison and live head/state checks. Inspected: the complete already-published independent review checklists and identical-tree acceptance/CI receipts. Fresh new-commit CI remains pending; review approval is not a claim of completed mainline integration.

APPROVE