Architectural responsibilities and collaborations in one graph - #25
Merged
Merged
Conversation
Recipe 17 now returns null member metadata when a memberOf edge outlives its CodeNode, matching recipe 19, and the catalog test locks that contract. Co-authored-by: Cursor <cursoragent@cursor.com>
Make the authored uses layer and recipes 17–19 match the import graph and the ruling's relations, so agents reading the architecture map see the same dependencies the code has. Uses declarations now track real value and type imports; anchor-machinery imports confer no edge. Bind the remaining public units (reify, carrier, sdp new spec), move the import command onto CLI, and pin the join fields plus dangling-component and unresolved-uses contracts. Co-authored-by: Cursor <cursoragent@cursor.com>
|
Too many files changed for review (161 files, 100 file limit). Bypass the limit by tagging |
darko-mijic
changed the title
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
1 participant
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.
This PR makes the Protocol's software design discoverable through its own graph. It advances the
plan-38 architecture work with component membership, architectural dependencies, shaping decisions,
and executable graph recipes. An agent can follow a responsibility from its intended law to its
implementation, callers, and verifier bindings.
Gen 1 made named responsibilities and forward/reverse dependencies useful in everyday navigation.
This PR carries those strengths into the Protocol's existing model. Specs own intent; source
anchors bind code; graph queries group the results. No role registry or separate architecture
model is added.
A tour of the design
Architectural significance uses the appropriate Spec kind. Runtime responsibilities can be
behaviors, interfaces contracts, and quality bounds constraints. Model Specs explain concepts;
decision Specs record qualifying trade-offs. The
structural model and
self-binding behavior remain stated
defined.One shared delivery-fact policy. The
delivery-facts Spec owns the conferral law used by graph
derivation, validation, and the reader. Its implementation is in the graph component. Unit
usesedges identify all three callers; declared
dependsOnrelations explain the semantic dependence.The Spec has a direct implementation binding and an enabled verifier binding.
The runner and its test-framework adapter. The
example-runner Spec explains the ports-and-adapters
split. The runner owns step execution; the Vitest adapter owns registration and world lifecycle.
Their unit collaboration is visible even though both realize the same Spec.
Architecture queries preserve their evidence. Recipes 17, 18, and 19 provide an architecture
map, decision map, and planning slice. The architecture map includes responsibilities and design
context, retains unit edges and their claims, and exposes the binding behind each realized Spec.
Component fan counts count distinct other components. Missing nodes remain visible as unresolved
entries. The walkthrough demonstrates the shared policy,
adapter boundary, and one-read-model design using these queries.
A census of accepted structural bindings. The self-hosting oracle records the owner-reviewed set of
significant units. Tests check membership and the narrowly declared helper-coverage relationships.
The audit certifies the accepted set; it does not classify architectural significance from imports.
Ratified decisions
Try it
In a checkout of this PR branch, install and build:
Find the shared policy and inspect its intended law:
Inspect the accepted caller bindings:
pnpm --silent sdp:q 'return graph.edges.filter(e => e.type === "uses" && e.to === "impl:protocol.delivery-facts").map(e => ({from:e.from,to:e.to,claim:e.claim}))' --jsonPaste recipe 17 from
docs/agent-surface/recipes.mdintopnpm --silent sdp:q '<body>' --jsonfor the full architecture map. Recipe 3 reads complete law and verifier context; recipe 19 gives
the planning neighborhood. The existing projection publishers remain frozen.
Feedback is wanted on whether the responsibility boundaries and declared dependencies explain
the design, whether the accepted significant-unit set has the right grain, and whether the two
architecture Specs are ready for a human readiness statement.
Validation and review history
The local
npm run checkpassed, including 878 main-suite tests and 80 CLI tests, package installation,self-hosting checks, and preflight. Current measurements and verification are recorded in
the software-design review. Re-run the recipes rather than
inheriting earlier counts. Re-measured before publication, the graph has 164 Specs, 342 nodes, and 768 edges, including
13 components, 76 memberships, and 39 uses declarations. Validation retains the five intentional
self-hosting warnings; the worked example retains its intentional verifier-linkage warning.
The branch's earlier review and remediation records remain in git history. Commit
bbf6869removed the OmO directory, so the description no longer links to those files as current artifacts.
The latest review adds graph-level design demonstrations, recipe regression tests, package
coverage for the guide, and a macOS path correction in the filesystem-boundary test. The owner also
removed the obsolete workstation-specific SSH requirement from
AGENTS.md.Upcoming work
Recipe 1 is the operational backlog and currently returns no implementation work.
spec:consumers.graph-first-planningremains atidea; resume its maturation when its nextscope is selected. The two architecture Specs
remain stated
defineduntil a human reviews them and statesready.The six non-blocking comment-promotion questions remain candidates for individual review.
Promote shared law when it needs its own identity and binding. The projections-model Spec and
the existing readiness-divergence rows retain their current dispositions.
Durable refusals remain: a pattern kind or namespace; new role fields, relation types, query verbs,
or reader methods; manufactured decision replacement or realization edges; architecture-enforcement
validators; significance inferred from imports; exhaustive symbol impact; committed architecture
renderings; comment-prose extraction; and machine-authored readiness or delivery status.
The branch also refuses manufactured anchors on marginal helpers, blocking treatment of the six
comment-promotion questions, restrictions on lawful Spec IDs to avoid JavaScript object inheritance,
and re-tracking the runtime ledger as workflow state.