Define a versioned CircuitDocument and PDK package schema with round-trip tests

[DennisWayo]

Problem Statement

Studio can save .pdk, .json, and .pdf, but .pdk and .json currently serialize the same JSON snapshot payload. For SchroSIM to become a design tool, the design artifact needs a stable schema that can carry nodes, edges, foundry references, policy selections, provenance, display layout, and future design-kit assets.

Proposed Solution

Create a versioned CircuitDocument/PDK schema:

• top-level document_type, schema_version, and compatibility policy,
• graph nodes and explicit edges,
• foundry profile reference and profile hash,
• backend/runtime defaults,
• KPI policy reference,
• canvas layout state,
• provenance and audit metadata,
• optional packaged assets or future design-kit references.

Add load/save migrations and strict round-trip tests.

Acceptance Criteria

• .pdk has a documented schema distinct from a loose snapshot.
• Loading an older document either migrates or returns a clear compatibility error.
• Save/load round-trip preserves node ids, params, edges, config, policy, and context.
• Invalid documents produce actionable errors.
• Docs include one minimal and one full example PDK payload.

Validation

bash scripts/swift-test.sh
swift run schrosim-cli run docs/examples/runtime_default_foundry.json --backend hybrid

Evidence

• core-swift/Sources/schrosim-studio/CLIService.swift
• core-swift/Sources/schrosim-studio/AppModels.swift
• docs/04-circuit-ir-and-schema.md