FE-1056: Move the handle integration guide into the architecture docs

[kube]

🌟 What is the purpose of this PR?

Gives a host application a documented path to implementing its own PetrinautDocHandle, which is what TOPOS needs to embed Petrinaut in CatCollab (FE-1056). The integration guide moves into the Petrinaut architecture docs, where the build checks its links and layer references. On the code side, SDCPNInput lets hosts author documents without spelling out every extension field.

🔗 Related links

• FE-1056: Handle creation documentation for TOPOS/CatCollab (internal)

🔍 What does this change?

@hashintel/petrinaut-core

• New types/sdcpn-input.ts: SDCPNInput is a loose authoring variant of SDCPN, and normalizeSDCPN() fills plain-net defaults. Arcs accept the placeId shorthand or an explicit endpoint (including component ports); subnets, componentInstances, and place isPort pass through. A complete SDCPN remains a valid SDCPNInput, asserted at compile time in the test.
• createJsonDocHandle accepts SDCPNInput and normalizes internally.
• Both are exported from the package root; changeset included (patch).

Architecture docs (@local/petrinaut-arch-docs)

• content/handle/host-integration.mdx, attached to the core.handle layer: the contract, a per-member table of what the editor does with each handle member, the invariants a custom handle must keep (synchronous atomic change(), referentially stable doc(), emit-per-change, stable id), the model-mapping recipe, a worked adapter, the <Petrinaut /> prop table, and capabilities (now five extensions, including subnets). Two diagrams: a sequence of the local/remote event flows and a pipeline of the adapter's write paths.
• content/handle/contract-gaps.mdx: where the contract under-specifies or misbehaves today (implicit invariants, readiness and lifecycle, local vs remote changes, validation and versioning, history under collaboration), each with the enhancement it calls for, and a sequencing note. Every claim was checked against the current code.
• Both pages are linked from the docs index and appear under the core.handle layer's Guides section.

Removals

• libs/@hashintel/petrinaut/INTEGRATION.md is deleted; its content was rewritten into the two pages above. The package READMEs keep a short embedding section and link to the new guide.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies an npm-publishable library and I have added a changeset file(s)
  • @hashintel/petrinaut-core: patch. The @hashintel/petrinaut change is README and files only, no changeset.

📜 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

⚠️ Known issues

• The handle interface is experimental. The contract-gaps page documents its current weaknesses; this PR does not fix them.

🐾 Next steps

The enhancements listed in contract-gaps.mdx, cheapest first: TSDoc for the implicit invariants plus a conformance test kit for third-party handles, an error channel and specified readiness semantics, validation shared between file import and handle construction, then local/remote and history semantics alongside the first collaborative backend.

🛡 What tests cover this?

• types/sdcpn-input.test.ts: default filling, endpoint and subnet passthrough, absent-key preservation for structural equality, idempotence on a complete document, and the compile-time SDCPN-to-SDCPNInput assignability assertion.
• lint:arch-docs fails the build on unresolved doc:/layer: links, unknown attachTo targets, and missing @diagrams/ components in the new pages.

❓ How to test this?

1. turbo run test:unit --filter @hashintel/petrinaut-core
2. yarn workspace @local/petrinaut-arch-docs lint:arch-docs
3. turbo run dev --filter @apps/petrinaut-docs, then open Architecture → core → handle: both guides appear under "Guides", with the diagrams rendered.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 16, 2026 3:11am
petrinaut	Ready	Preview	Aug 16, 2026 3:11am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 16, 2026 3:11am

[semgrep-code-hashintel]

Semgrep found 4 path-join-resolve-traversal findings:

• .claude/setup.mjs
  • L223 - Triage
  • L223 - Triage
  • L257 - Triage
  • L257 - Triage

Detected possible user input going into a path.join or path.resolve function. This could possibly lead to a path traversal vulnerability, where the attacker can access arbitrary files stored in the file system. Instead, be sure to sanitize or validate user input first.

View Dataflow Graph

flowchart LR
    classDef invis fill:white, stroke: none
    classDef default fill:#e7f5ff, color:#1c7fd6, stroke: none

    subgraph File0["<b>.claude/setup.mjs</b>"]
        direction LR
        %% Source

        subgraph Source
            direction LR

            v0["<a href=https://github.com/hashintel/hash/blob/3c80fef937ed2cd8869428222504b8915ebc22eb/.claude/setup.mjs#L226 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 226] _0x2912ea</a>"]
        end
        %% Intermediate

        subgraph Traces0[Traces]
            direction TB

            v2["<a href=https://github.com/hashintel/hash/blob/3c80fef937ed2cd8869428222504b8915ebc22eb/.claude/setup.mjs#L226 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 226] _0x2912ea</a>"]
        end
        %% Sink

        subgraph Sink
            direction LR

            v1["<a href=https://github.com/hashintel/hash/blob/3c80fef937ed2cd8869428222504b8915ebc22eb/.claude/setup.mjs#L257 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 257] _0x2912ea</a>"]
        end
    end
    %% Class Assignment
    Source:::invis
    Sink:::invis

    Traces0:::invis
    File0:::invis

    %% Connections

    Source --> Traces0
    Traces0 --> Sink

Loading