FE-1443: Declare protocol edges for import-invisible boundaries

[kube]

🌟 What is the purpose of this PR?

Proposal for FE-1443: the architecture graph derives every edge from imports, so couplings that cross a process or thread boundary are invisible. The Python bindings spawn the CLI and speak JSON lines with no import in either direction, so the cli layer shows no consumers.

This adds one annotation. In the boundary file's doc comment or docstring:

@talksTo cli via JSON lines over stdio (spawned subprocess)

The declaring file's own layer is the edge source. The edge renders dashed with the protocol as its label, and layer pages list it under a separate "Declared" block.

Sits on top of stack #9226: the seed declaration lives in the Python bindings package, which FE-1414 below made scannable.

🔗 Related links

• FE-1443 (internal): this PR
• FE-1415 (internal): complementary, Python import edges. No Python import crosses the subprocess boundary either, so both are needed.

🔍 What does this change?

libs/@local/petrinaut-arch-docs:

• Tag (tags.ts): @talksTo <layer-id> via <protocol> collected by the same TS-comment and Python-docstring scan as @layerRoot/@role. Repeatable; malformed tags are diagnostics.
• Model (model.ts): Edge becomes a discriminated union on provenance ("imports" | "declared"); declared edges carry protocol.
• Graph (graph.ts): declared edges append after import aggregation. Build errors on an unknown target, on a pair the imports already prove, and on a duplicate declaration.
• Diagrams (d2.ts): declared edges render dashed with the protocol label in all three diagram kinds; a declared neighbour bypasses the 12-neighbour cap so it cannot be elided.
• Pages (mdx.ts): a "Declared" table (Layer | Protocol) under "Depends on" and "Depended on by", separate from the import tables.
• Rules (check.ts): forbidden-edge rules apply to import edges only.
• Seed: the bindings package declares its edge to cli; the bundle gains exactly one edge (197 → 198).
• Docs: "Declaring a protocol edge" sections in the maintaining guide and the package README; the root AGENTS.md vocabulary claim updated from two tags to three.

Open question for review: ARCHITECTURE_MODEL_VERSION stays at 1. The only in-repo consumer reads manifest.json, not edges; bump it if you consider the edge shape part of the bundle contract.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a workspace but not a publishable library

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• tags.test.ts: parsing in TS comments and Python docstrings, malformed tags, miscasing suggestion.
• graph.test.ts (new): resolution, unknown target, duplicate-of-import, duplicate declaration.
• d2.test.ts / mdx.test.ts: dashed edge with protocol label; the Declared block, both directions.

❓ How to test this?

1. yarn workspace @local/petrinaut-arch-docs lint:arch-docs — reports 198 edges, one declared.
2. turbo run dev --filter @apps/petrinaut-docs — the python-bindings and cli layer pages show the declared edge dashed in their neighbourhood diagrams and in a "Declared" table.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 20, 2026 10:52am
petrinaut	Ready	Preview	Aug 20, 2026 10:52am
petrinaut-docs	Ready	Preview	Aug 20, 2026 10:52am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 20, 2026 10:52am