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 27, 2026 3:29pm
petrinaut	Ready	Preview	Aug 27, 2026 3:29pm
petrinaut-docs	Ready	Preview	Aug 27, 2026 3:29pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 27, 2026 3:29pm

[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

[kube]

Restacked and revised, per request:

• Rebased onto claude/fe-1514-arch-docs-diff-highlighting (PR FE-1514: Highlight arch-docs changes against a base ref on preview builds #9366, the arch-docs diff mode) and retargeted the PR there, so this now sits at the top of that stack. The five original commits are squashed into one.
• Re-verified the guide's claims against current main: the PetrinautDocHandle interface, the full <Petrinaut> prop table, the SDCPN optional-field list, the export list, and the four reference-implementation paths are all still accurate. No handle-relevant code changed in the 71 commits the branch was behind. One row updated: aiAssistant also carries interactive tools since FE-1448.
• Prose pass per the house technical-writing rules: "gate" → check, "surfaces" → shows, "invariants" → requirements (headings, anchors and cross-links updated), one duplicated-fact sentence removed.
• Gates on the restacked branch: petrinaut-core 943 tests + tsc, lint:arch-docs, formatting, and the docs-site build (60 pages) all pass.

A nice side effect of the stacking: this branch's own diff build flags exactly its footprint — the two guides as new, the handle layer page and core.types (which gains sdcpn-input.ts) as changed — so the preview deployment will show reviewers precisely these pages.

🤖 Generated with Claude Code

[cursor]

PR Summary

Low Risk
Backward-compatible API widening plus documentation; no changes to auth, persistence, or editor mutation paths beyond normalizing handle initial input.

Overview
Moves Petrinaut host embedding documentation into the architecture docs (host-integration.mdx, contract-gaps.mdx) under the core.handle layer, with index links and short embedding sections in the @hashintel/petrinaut and @hashintel/petrinaut-core READMEs (replacing the old package-level integration write-up).

In @hashintel/petrinaut-core, adds SDCPNInput and normalizeSDCPN() so hosts can seed documents without every extension field; createJsonDocHandle now takes SDCPNInput and normalizes before existing extension sanitization. Types and the normalizer are exported from the package root, with unit tests and a patch changeset.

^{Reviewed by Cursor Bugbot for commit b8740a9. Bugbot is set up for automated code reviews on this repo. Configure here.}