Repository navigation
docs: plan — resource construction: the catalog mediates everything - #588
Merged
Merged
Conversation
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.
… 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)
existence check. Promise value → the promise binding, no entry. Products are runtime facts — no
plan-time presence, no output declarations; Appendix A is rejected.
document without it does not load; a catalog-less graph fails pre-flight. Schema stays 1 — existing
documents die and are re-planned.
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.