Correct public attachment documentation and publish executable capability examples #904

1. Background Context

Source: git-warp #904. Audited against main 94b40dac64034cd8caab9bb05efe14a0c22bd735. Template: feature; work type: type:docs.

Current scope and disposition: Mixed timing: current honesty corrections can land immediately, but completion includes real restored examples and agreed structural-ownership distinctions. This is a completion blocker, not a ban on starting docs.

Discussion evidence, including corrections:

• Comment ABYi6LPQ

2. Problem Description

Mixed timing: current honesty corrections can land immediately, but completion includes real restored examples and agreed structural-ownership distinctions. This is a completion blocker, not a ban on starting docs.

Historical source report; the current disposition above supersedes obsolete claims:
docs/topics/content-and-cas.md directs consumers to public content read surfaces, while the v19 intent API has no content attachment operations (#901). Internal implementation capability is being presented without an executable supported-package route.

2b. Proposed Solution

Mixed timing: current honesty corrections can land immediately, but completion includes real restored examples and agreed structural-ownership distinctions. This is a completion blocker, not a ban on starting docs.

2c. Alternatives considered and rejected

No additional alternatives are recorded as decided. Reject duplicate ownership, private-import escape hatches and a broken intermediate mainline; retain original alternatives below when present.

2d. Acceptance Criteria

• Describe current public capabilities honestly until Restore public node and edge content attachments after the v19 API migration #901 lands; distinguish node properties from managed node/edge byte assets.
• Distinguish byte assets, external graph references, and finite recursive structural attachments from Paper I.
• Provide executable supported-package examples for node and edge attach, replace, clear, metadata, and stream read once available.
• Explain migration from the retired PatchBuilder surface without private-import workarounds.
• Document atomicity, history, concurrency, retention, limits, cancellation, and failure behavior established by tests.
• Link the recursive implementation work in Add typed recursive WARP graph attachment references #819, Traverse recursive WARP graphs with cycle-safe bounded receipts #820, and Retain and diagnose recursive graph references across CAS boundaries #821 without claiming unfinished Paper II semantics.
• Run examples as consumer tests; documentation and code must describe the same runtime truth.

Use current topic and migration documentation. Do not revive retired design packets or duplicate the API implementation in #901.

2e. Test Plan

Golden: Attach, replace, clear and stream node/edge content through supported package imports.

Edges: Missing owners/handles, size boundaries, history and concurrent updates.

Known failure modes: Staging failure, missing capability, truncation and cancellation publish no partial result.

Fuzz and stress: Generated large payloads, slow consumers and recursive cycles where in scope, under a Docker heap cap.

All tests and benchmarks execute in COPY-based Docker containers without host repository or Git-directory mounts. This planning audit does not claim those checks were run.

3. Prerequisites

Completion prerequisites; preparatory work may start earlier.

• #901: The complete documentation card requires executable supported-package attach/replace/clear/stream examples. Honesty corrections can start now, but the card cannot finish while those operations are missing.
• #903: The documentation must distinguish finite structural ownership from byte assets and external/live references using the agreed ownership and descendant-mutation contract. Current-capability corrections can land early.
• #902: Assign reusable installed-package attachment operation examples and their execution harness to Prove node and edge attachments through installed-package public APIs #902. Correct public attachment documentation and publish executable capability examples #904 publishes and runs those examples with the documented history, cancellation and retention behavior; it does not create a second unverified consumer recipe. Review basis: accepted-ownership.

4. Scope

In: Mixed timing: current honesty corrections can land immediately, but completion includes real restored examples and agreed structural-ownership distinctions. This is a completion blocker, not a ban on starting docs.

Out: unrelated domain work and any expansion beyond the issue’s stated observable outcome.

Safe intermediate state: the PR builds and passes relevant checks after its listed prerequisites; existing supported behavior remains usable. Any preparatory step must be independently mergeable.

Domain review, 2026-10-01 — accepted ownership / scope correction:

Publish and execute the supported-package examples owned by #902. Current-capability honesty corrections may land immediately; full completion includes the verified restored examples and #903 structural-ownership distinctions.

5. Why now

Maintainer ordering: memory correctness first, supported attachments next, then land eligible PRs. Preserve this card’s existing priority unless a separately recorded scope decision changes it.

6. Risks

Main risk: implementing the historical description instead of the current runtime contract. Preserve compatibility, causal/ownership invariants and bounded behavior relevant to attachments.

7. Definition of Done

The issue-specific acceptance checks pass, relevant validation evidence is attached, and the issue links the coherent PR and resulting mainline integration commit. No open item is hidden in a later repair PR.

8. Stakeholders

James Ross: maintainer, assignee and acceptance owner. Public API consumers rely on reachable node/edge attachment operations and honest ownership.

9. Related Issues

No additional downstream blocker is established. Shared domain membership alone is not a prerequisite.

Historical paths, counts, release names and shell examples in source material are evidence to reconcile, not authority to restore retired documentation or run host tests.