Skip to content

The design record states the sealed contract, what it buys, and what it costs - #869

Merged
David-Noble-at-work merged 2 commits into
developfrom
doc/647-sealed-contract-design-record
Sep 8, 2026
Merged

David-Noble-at-work merged 2 commits into
developfrom
doc/647-sealed-contract-design-record

Conversation

@David-Noble-at-work

@David-Noble-at-work David-Noble-at-work commented Sep 8, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Documentation only; no code changes. Closure of the sealed-provider-resources feature (#625 phase 10).

  • Eight provider documents name the shape. json, yaml, function, git, service, appnet, and memory resources each gain one sentence in the same form: the resource is a sealed interface embedding op.Resource, sealed by a method it declares itself, over an unexported struct, with the registration document as the contract. The file provider's document already said it. The pointer prose is gone from prose (*json.Resource and its siblings); Go signatures keep their pointers, since that is what those functions receive.
  • The model says what the seal buys. 4-resource-management.md §2 states the two-level seal, and a new resolved decision (item 19) records that the guarantees — claims true when made, identity as the catalog key, a string as a key and never a constructor, complete intent in the graph — now hold by construction rather than by convention, because nothing outside a provider can build its resource and the announcement refuses any other shape.
  • The cost is recorded beside the guarantee. Reflection prints the implementation while the type id and URI name the interface. The two strings differ deliberately; matching one against the other is wrong by construction.
  • Status files follow, and the feature plan's phase 10 reads complete. All ten phases have landed; the feature's remaining work is Retire the providers' resource Unmarshal* constructors now that slots record catalog ids #854.

Found on the way: the pkg provider has no design document at all, the only provider without one, filed as #868 under the pkg feature rather than written inside a closure pass.

Plan: docs/plans/doc/647-sealed-contract-design-record.md (complete).

Acceptance — #647

  • The 3.5.x per-provider design docs drop any language describing the resource as a struct; each records the sealed shape — eight documents; pkg has no document, filed as The pkg provider has no design document: 3.5.x has an entry for every provider but this one #868
  • 4-resource-management.md records what the seal buys — §2's paragraph and §9 item 19, tied to items 9, 15 and 18
  • Record the accepted cost: %T prints *service.resource while the URI says service.Resource — §9 item 19's second paragraph
  • Status files follow — every touched document, plus the registration document's status

Verification

  • No sealed resource is described as a pointer-to-struct in prose (the plan's own current-state table quotes the old spelling as a record)
  • Eight documents state the shape
  • The tree is otherwise untouched: the full CI gate ran locally, tests and scenarios included

Closes #647.

https://claude.ai/code/session_01SqQVFZz7AdiLZkGoAcUqRW

Time

Marker UTC Elapsed
opened (first commit) 2026-09-08T19:38:41Z —
submitted (PR opened) 2026-09-08T21:38:43Z 2 h after opened
merged 2026-09-08T21:50:39Z 0.2 h after submitted; 2.2 h in all

Computed by the algorithm of noblefactor-ops#188 at merge.

David Noble added 2 commits September 8, 2026 12:38
A draft for review before any edits: six per-provider documents still name a
resource as a pointer-to-struct and none says it is an interface; the
resource-management summary describes the pre-seal shape; the accepted cost is
recorded in one document only. One sentence per provider, the model's paragraph
and a resolved decision for what the seal buys and what it costs, status files
after. Documentation only, no code.

Refs #647.

Claude-Session: https://claude.ai/code/session_01SqQVFZz7AdiLZkGoAcUqRW
…it costs

Eight provider documents name their resource as a sealed interface over an
unexported struct and point at the registration contract; the pointer prose is
gone. The resource-management summary states the two-level seal, and a new
resolved decision records that the model's guarantees now hold by construction
rather than by convention, with the accepted cost that reflection prints the
implementation while identity names the interface. Status files follow, and the
sealed-resources feature's phase 10 reads complete. Found on the way: the pkg
provider has no design document at all, filed as #868.

Refs #647.

Claude-Session: https://claude.ai/code/session_01SqQVFZz7AdiLZkGoAcUqRW
@David-Noble-at-work David-Noble-at-work self-assigned this Sep 8, 2026
@David-Noble-at-work
David-Noble-at-work merged commit c0b6c51 into develop Sep 8, 2026
13 checks passed
@David-Noble-at-work
David-Noble-at-work deleted the doc/647-sealed-contract-design-record branch September 8, 2026 21:50
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.

Closure: the design record states the sealed contract

1 participant