Skip to content

docs: plan — resource construction: the catalog mediates everything - #588

Merged
David-Noble-at-work merged 2 commits into
developfrom
resource-construction
Aug 20, 2026
Merged

David-Noble-at-work merged 2 commits into
developfrom
resource-construction

Conversation

@David-Noble-at-work

Copy link
Copy Markdown
Contributor

The approved plan for the resource-construction feature work — the graph's resource catalog represents
input intent: what must exist when the graph runs.

The rulings (2026-08-20)

  1. Intent-only catalog. Resource-typed parameter + string value → pending entry at plan time, no
    existence check. Promise value → the promise binding, no entry. Products are runtime facts — no
    plan-time presence, no output declarations; Appendix A is rejected.
  2. Mandatory section, hard pre-flight. The catalog serializes with the graph, present even when empty; a
    document without it does not load; a catalog-less graph fails pre-flight. Schema stays 1 — existing
    documents die and are re-planned.
  3. Identity is rel; the fsroot binds at run. Git-model plan-space paths: a leading slash anchors at the
    fsroot; machine-absoluteness is inexpressible in a plan (home scope binds per account, system scope per
    host). Volumes, drive letters, and ../ escapes are plan-time refusals.

Index

Epic #444 · Feature #581 "The catalog travels with the graph" · Tasks #582 (design integration), #583
(serialize + enforce), #584 (rel identity, under #546 — closes the #547 family: the last 3 Windows
known-failures), #585 (plan-time claiming), #586 (run time consumes the catalog), #587 (closure).

Acceptance: the two red demonstration pins (catalog_contract_test.go,
test_graph_catalog_contract.star) flip green with the ruled assertions — source pending present,
destination absent.

Refs #444, #581, #546, #547.

The graph's resource catalog represents input intent — what must exist when the graph runs. Ruled 2026-08-20
and planned in six phases under epic #444: at plan time a resource-typed parameter's string value mints a
pending entry with no existence check, a promise value records the promise and nothing else, and a product is
a runtime fact with no plan-time presence; the catalog serializes with the graph as a mandatory section that
is present even when empty, a document without it does not load, and a catalog-less graph fails pre-flight
hard; identity is the slash-canonical root-relative path under git-model plan-space semantics -- a leading
slash anchors at the fsroot -- and the fsroot is a run parameter unknown until execution, binding per account
for home scope and per host for system scope; schema stays 1 and existing documents are rewritten by
re-planning.

The plan converges the record to the design as authored: docs/sketches/resource-construction.md is the
source, 4-resource-management.md absorbs it as body (Appendix A deleted as rejected; its output-shadowing
variant superseded by the products-are-runtime-facts ruling), 4.1's file-URI ruling amends to rel identity,
and the sketches retire when integration is complete. Acceptance is the pair of demonstration pins that
forced the rulings, corrected to assert the source pending and the destination absent.

Feature #581 with tasks #582-#587 (phase 2 under the existing #546, closing the #547 family and with it the
last three Windows known-failures).

Refs #444, #581, #546, #547.
@David-Noble-at-work David-Noble-at-work self-assigned this Aug 20, 2026
… named resource

The scenarios the feature is judged by: authored as predictions before implementation, graduating to
devlore-test cases, correct when the harness observes exactly the prediction. Scenario 1: two operations on
one named resource -- delete, then copy from it. The graph catalog holds exactly one pending entry (the same
string dedups to one identity; the copy's destination is a product and therefore absent); pre-flight passes
because intent was satisfied at the starting line; the run fails at the copy node and the delete compensates;
the trace records pending to Active with captured content identity to Gone, and no product. The graph says
what must be true; the trace says what happened; the gap between them is the run's story.

Refs #581.
@David-Noble-at-work
David-Noble-at-work merged commit d03ee66 into develop Aug 20, 2026
7 of 8 checks passed
@David-Noble-at-work
David-Noble-at-work deleted the resource-construction branch August 20, 2026 22:34
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