@warpgogol/werkstatt-shared 0.14.1 → 0.15.0

package/src/onboarding/index.ts

@@ -18,3 +18,4 @@ export {
   parseMarkdownAsYaml,
 } from "./brief.ts";
 export type { Brief } from "./brief.ts";
+export * from "./yaml.ts";

package/src/{share → onboarding}/tests/onboarding-yaml.test.ts

@@ -23,7 +23,7 @@ import {
   parseOnboardingArtifactHeader,
   parseOnboardingArtifactPayload,
   RFC_METADATA_KEYS,
-} from "../onboarding-yaml/index.ts";
+} from "../yaml.ts";
 
 const HEADER_FIXTURE = `phase: 04-author
 derivedFromInputHash: sha256:deadbeef

package/src/ontology/archetype-registry.ts

@@ -14,7 +14,12 @@ fast instead of producing silently empty maps.
 <CHANGE_SUMMARY>
   <item>RFC-0091: Initial creation — typed re-export of derived archetype registry maps.</item>
   <item>RFC-0263: also re-export roleByCosmicName (manifest-authored role, derived) — replaces name-keyed dispatch literals in packages/share.</item>
-  <item>Architecture review 2026-07-10: validate index.json with Zod instead of unchecked cast — fail-fast on registry shape drift.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/ontology/archetypes/index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "totalCount": 59,
+  "totalCount": 61,
   "entries": [
     {
       "id": "approach",
@@ -182,6 +182,30 @@
       "sourceFile": "packages/werkstatt-site/src/domain/ontology/archetypes/sections/dynamic-status-block.yaml",
       "layer": "section"
     },
+    {
+      "id": "entity-grid",
+      "displayName": "Engineering entity grid",
+      "semanticRole": "entity-composition-grid",
+      "version": "1.0.0",
+      "layoutHint": "card-grid",
+      "acceptedCosmicNames": [
+        "Ixion"
+      ],
+      "sourceFile": "packages/werkstatt-site/src/domain/ontology/archetypes/sections/entity-grid.yaml",
+      "layer": "section"
+    },
+    {
+      "id": "exit-diagram",
+      "displayName": "Exit-process diagram",
+      "semanticRole": "exit-flow-visualization",
+      "version": "1.0.0",
+      "layoutHint": "single-column",
+      "acceptedCosmicNames": [
+        "Haumea"
+      ],
+      "sourceFile": "packages/werkstatt-site/src/domain/ontology/archetypes/sections/exit-diagram.yaml",
+      "layer": "section"
+    },
     {
       "id": "faq-list",
       "displayName": "Faq List",
@@ -723,7 +747,9 @@
     "data-driven-status-indicator",
     "donation-card",
     "donation-use",
+    "entity-composition-grid",
     "exit-clause-disclosure",
+    "exit-flow-visualization",
     "faq-list",
     "final-cta",
     "hero",
@@ -788,6 +814,8 @@
     "Pandora": "@warpgogol/werkstatt-site/ui/sections/donation-card",
     "Rhea": "@warpgogol/werkstatt-site/ui/sections/donation-use",
     "Elara": "@warpgogol/werkstatt-site/ui/sections/dynamic-status-block",
+    "Ixion": "@warpgogol/werkstatt-site/ui/sections/entity-grid",
+    "Haumea": "@warpgogol/werkstatt-site/ui/sections/exit-diagram",
     "Atlas": "@warpgogol/werkstatt-site/ui/sections/faq-list",
     "Dione": "@warpgogol/werkstatt-site/ui/sections/final-cta",
     "Gonggong": "@warpgogol/werkstatt-site/ui/sections/gratitude",
@@ -867,6 +895,8 @@
     "donation-card": "Pandora",
     "donation-use": "Rhea",
     "dynamic-status-block": "Elara",
+    "entity-grid": "Ixion",
+    "exit-diagram": "Haumea",
     "faq-list": "Atlas",
     "final-cta": "Dione",
     "gratitude": "Gonggong",
@@ -950,6 +980,8 @@
     "Pandora": "donation-use",
     "Rhea": "donation-use",
     "Elara": "data-driven-status-indicator",
+    "Ixion": "entity-composition-grid",
+    "Haumea": "exit-flow-visualization",
     "Atlas": "approach",
     "Dione": "final-cta",
     "Gonggong": "client-gratitude",

package/src/ontology/archetypes/index.yaml

@@ -1,5 +1,5 @@
 schemaVersion: 1.0.0
-totalCount: 59
+totalCount: 61
 entries:
   - id: approach
     displayName: Approach
@@ -136,6 +136,24 @@ entries:
       - Elara
     sourceFile: packages/werkstatt-site/src/domain/ontology/archetypes/sections/dynamic-status-block.yaml
     layer: section
+  - id: entity-grid
+    displayName: Engineering entity grid
+    semanticRole: entity-composition-grid
+    version: 1.0.0
+    layoutHint: card-grid
+    acceptedCosmicNames:
+      - Ixion
+    sourceFile: packages/werkstatt-site/src/domain/ontology/archetypes/sections/entity-grid.yaml
+    layer: section
+  - id: exit-diagram
+    displayName: Exit-process diagram
+    semanticRole: exit-flow-visualization
+    version: 1.0.0
+    layoutHint: single-column
+    acceptedCosmicNames:
+      - Haumea
+    sourceFile: packages/werkstatt-site/src/domain/ontology/archetypes/sections/exit-diagram.yaml
+    layer: section
   - id: faq-list
     displayName: Faq List
     semanticRole: faq-list
@@ -544,7 +562,9 @@ sectionRoles:
   - data-driven-status-indicator
   - donation-card
   - donation-use
+  - entity-composition-grid
   - exit-clause-disclosure
+  - exit-flow-visualization
   - faq-list
   - final-cta
   - hero
@@ -607,6 +627,8 @@ planetImportPaths:
   Pandora: "@warpgogol/werkstatt-site/ui/sections/donation-card"
   Rhea: "@warpgogol/werkstatt-site/ui/sections/donation-use"
   Elara: "@warpgogol/werkstatt-site/ui/sections/dynamic-status-block"
+  Ixion: "@warpgogol/werkstatt-site/ui/sections/entity-grid"
+  Haumea: "@warpgogol/werkstatt-site/ui/sections/exit-diagram"
   Atlas: "@warpgogol/werkstatt-site/ui/sections/faq-list"
   Dione: "@warpgogol/werkstatt-site/ui/sections/final-cta"
   Gonggong: "@warpgogol/werkstatt-site/ui/sections/gratitude"
@@ -685,6 +707,8 @@ blockTypeToCosmicName:
   donation-card: Pandora
   donation-use: Rhea
   dynamic-status-block: Elara
+  entity-grid: Ixion
+  exit-diagram: Haumea
   faq-list: Atlas
   final-cta: Dione
   gratitude: Gonggong
@@ -766,6 +790,8 @@ roleByCosmicName:
   Pandora: donation-use
   Rhea: donation-use
   Elara: data-driven-status-indicator
+  Ixion: entity-composition-grid
+  Haumea: exit-flow-visualization
   Atlas: approach
   Dione: final-cta
   Gonggong: client-gratitude

package/src/ontology/archetypes/sections/entity-grid.yaml

@@ -0,0 +1,46 @@
+id: entity-grid
+displayName: Engineering entity grid
+version: 1.0.0
+semanticRole: entity-composition-grid
+description: |
+  Engineering-style entity composition grid with numbered markers and
+  boundaries. No glass effects. RFC-1062.
+expectedIntents:
+  - trust
+  - legal-clarity
+  - de-risk
+expectedIndustryFit:
+  - trades-and-construction
+  - consulting-and-coaching
+  - legal-services
+layoutHint: card-grid
+bodyKind: composite
+recommendedItemCount:
+  min: 2
+  max: 8
+propsSchema:
+  $shape: zod
+  compose:
+    - section-header
+  shape: |
+    z.object({
+      background: z.object({
+        kind: z.enum(["transparent", "solid"]),
+      }).optional(),
+      density: z.enum(["compact", "normal"]).optional(),
+      body: z.object({
+        kind: z.literal("grid"),
+        columns: z.union([z.literal(2), z.literal(3), z.literal(4)]),
+        items: z.array(z.object({
+          number: z.string().min(1),
+          title: z.string().min(1),
+          description: z.string().min(1),
+        })).min(2).max(8),
+      }),
+    }).strict()
+acceptedCosmicNames:
+  - Ixion
+constraints:
+  forbidPhrases:
+    - alle Branchen
+    - jeder Kunde

package/src/ontology/archetypes/sections/exit-diagram.yaml

@@ -0,0 +1,43 @@
+id: exit-diagram
+displayName: Exit-process diagram
+version: 1.0.0
+semanticRole: exit-flow-visualization
+description: |
+  Static SVG exit-process flow diagram. Renders stages as a visual flow
+  (linear or loop) with numbered markers. RFC-1062.
+expectedIntents:
+  - trust
+  - legal-clarity
+  - de-risk
+expectedIndustryFit:
+  - trades-and-construction
+  - consulting-and-coaching
+  - legal-services
+layoutHint: single-column
+bodyKind: composite
+recommendedItemCount:
+  min: 2
+  max: 6
+propsSchema:
+  $shape: zod
+  compose:
+    - section-visual
+    - section-header
+  shape: |
+    z.object({
+      ariaLabel: z.string().min(1).optional(),
+      stages: z.array(z.object({
+        number: z.string().min(1),
+        title: z.string().min(1),
+        description: z.string().min(1),
+      })).min(2).max(6),
+      variant: z.enum(["linear", "loop"]),
+    }).strict()
+acceptedCosmicNames:
+  - Haumea
+constraints:
+  forbidPhrases:
+    - Evakuierung
+    - Notfall
+  mandatoryConcepts:
+    - Notausgang

package/src/ontology/biome-token-projection.ts

@@ -12,7 +12,12 @@ divergent copies of the same mapping.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial: consolidated BIOME_TO_TOKEN_MAP, BIOME_TO_CSS_VAR, and buildExpectedBiomeCss into one projection.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/ontology/cosmic/index.ts

@@ -11,7 +11,12 @@ so consumers can import from a single entry point (DNA-23, RFC-0025).
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Wave 1 (RFC-0025): Initial creation — cosmic barrel with cross-catalog union.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/ontology/cosmic/moon-catalog.ts

@@ -17,7 +17,12 @@ The inner/classical Jupiter and Saturn moons are in PlanetCatalog (section arche
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Wave 1 (RFC-0025): Initial creation — Uranus/Neptune/Pluto + irregular moon catalog for component-layer cosmicName.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/ontology/cosmic/planet-catalog.ts

@@ -17,7 +17,12 @@ are in MoonCatalog (component archetypes).
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Wave 1 (RFC-0025): Initial creation — Jupiter/Saturn/Mars/dwarf-planet catalog for section-layer cosmicName.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/ontology/cosmic/star-catalog.ts

@@ -11,7 +11,12 @@ Each entry is a valid cosmicName for manifests with layer="page" (DNA-23, RFC-00
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Wave 1 (RFC-0025): Initial creation — IAU named-star catalog for page-layer cosmicName.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/ontology/enums.ts

@@ -14,7 +14,12 @@ enums (for runtime validation) and TypeScript types (for static typing).
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial creation as part of Wave 1 (RFC-0023 rollout).</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/ontology/external-surfaces/index.ts

@@ -3,7 +3,7 @@
 <purpose>
 RFC-0480: Declarative Layer C external-surface contracts — URL schema,
 JSON-LD types, and sitemap shape. Consumed by `surface.contract.validate`
-in @warpgogol/site-kernel-handoff and by contract tests in @warpgogol/werkstatt-shared/share.
+in @warpgogol/site-kernel-handoff and by contract tests in @warpgogol/werkstatt-shared.
 </purpose>
 <non-goals>
   <item>Do not generate C-surfaces here — this module only declares the contract.</item>

package/src/ontology/index.ts

@@ -11,8 +11,12 @@ package root or sub-paths.
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial barrel created as part of Wave 1 (RFC-0023 rollout).</item>
-  <item>Wave 1 (RFC-0025): Added cosmic catalog re-exports (DNA-23).</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/ontology/manifest.ts

@@ -16,9 +16,12 @@ Exports a discriminated union on `layer` so TypeScript narrows the `role` and
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial creation as part of Wave 1 (RFC-0023 rollout).</item>
-  <item>Wave 1 (RFC-0025): Added required cosmicName per layer — StarName for pages,
-        PlanetName for sections, MoonName for components (DNA-23).</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -157,7 +160,7 @@ const manifestBaseSchema = z.object({
 
   /**
    * Key of the Zod content schema this component consumes.
-   * Must match an export of @warpgogol/werkstatt-shared/share or the app-local content/schemas/.
+   * Must match an export of @warpgogol/werkstatt-shared or the app-local content/schemas/.
    * Set to null for structural components that consume no content schema
    * (e.g. breadcrumbs, lang-switcher).
    */

package/src/ontology/operations/artifact-store.ts

@@ -0,0 +1,45 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/ontology/src/operations/artifact-store.ts as an authored ontology authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0363: initial artifact manifest schema.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const releaseArtifactManifestSchema = z.object({
+  schemaVersion: z.literal("1.0.0"),
+  artifactKind: z.literal("release-dist"),
+  systemId: z.string().min(1),
+  releaseId: z.string().min(1),
+  missionId: z.string().min(1),
+  platformVersion: z.string(),
+  sternsystemCommitSha: z.string().nullable(),
+  createdAt: z.string().datetime(),
+  siteContentHash: z.string(),
+  distTreeHash: z.string(),
+  distArtifactHash: z.string(),
+  behaviorSnapshotHash: z.string().nullable(),
+  readableSnapshotHash: z.string().nullable(),
+  snapshotDiffHash: z.string().nullable(),
+  byteSize: z.number().nonnegative(),
+  fileCount: z.number().nonnegative(),
+});
+
+export const releaseArtifactRefSchema = z.object({
+  uri: z.string().min(1),
+  provider: z.enum(["local", "r2", "s3"]),
+  distArtifactHash: z.string(),
+  distTreeHash: z.string(),
+  siteContentHash: z.string(),
+  byteSize: z.number().nonnegative(),
+  fileCount: z.number().nonnegative(),
+});
+
+export type ReleaseArtifactManifest = z.infer<typeof releaseArtifactManifestSchema>;
+export type ReleaseArtifactRef = z.infer<typeof releaseArtifactRefSchema>;

package/src/ontology/operations/dht.ts

@@ -0,0 +1,98 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0565: Zod schemas for the S/Kademlia-hardened DHT site registry and content
+placement subsystem. Defines machine-checkable contracts for DHT site entries,
+config, lookup results, placement results, and workshop capacity. These schemas
+are the operations-layer contract consumed by @warpgogol/site-kernel DHT commands.
+</purpose>
+<non-goals>
+  <item>Do not perform file IO or network operations — pure shape only.</item>
+  <item>Do not define DHT routing protocol logic — that lives in site-kernel.</item>
+  <item>Do not define Ed25519 signing logic — that lives in @warpgogol/werkstatt-shared/passport/dht-sign.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0565: initial DHT schemas (DHTSiteEntry, DHTConfig, DHTLookupResult, DHTPlacementResult, WorkshopCapacity).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+const kebabRe = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const didWebRe = /^did:web:[a-z0-9.-]+#.+$/;
+const endpointRe = /^.+:\d+$/;
+
+export const dhtSiteEntrySchema = z.object({
+  siteId: z.string().regex(kebabRe, "siteId must be kebab-case, lowercase, latin-only"),
+  owner: z
+    .string()
+    .regex(didWebRe, "owner must be a did:web identifier (did:web:<domain>#<key-version>)")
+    .describe("VC subject id of the site owner (RFC-0558, RFC-0561)"),
+  workshopEndpoint: z.string().regex(endpointRe, "workshopEndpoint must be host:port format"),
+  mirrors: z.array(z.string().url()).default([]),
+  registeredAt: z.string().datetime(),
+  lastUpdated: z.string().datetime(),
+  signature: z.string().min(1, "signature must be a non-empty Ed25519 multibase signature"),
+});
+
+export const dhtConfigSchema = z.object({
+  bindAddr: z.string().regex(endpointRe, "bindAddr must be host:port format"),
+  bootstrapNodes: z
+    .array(z.string().regex(endpointRe, "each bootstrapNode must be host:port format"))
+    .default([]),
+  replicationFactor: z.number().int().min(1).max(20).default(5),
+  lookupTimeoutMs: z.number().int().min(100).default(5000),
+  cacheTtlMs: z.number().int().min(1000).default(300000),
+});
+
+export const dhtLookupResultSchema = z.object({
+  found: z.boolean(),
+  entry: dhtSiteEntrySchema.nullable(),
+  hops: z.number().int().min(0),
+  latencyMs: z.number().int().min(0),
+  cached: z.boolean().default(false),
+  signatureValid: z.boolean().default(true),
+  diagnostics: z.array(z.string()).optional(),
+});
+
+export const dhtPlacementReasonSchema = z.enum([
+  "least-loaded",
+  "nearest",
+  "owner-preference",
+  "local-fallback",
+]);
+
+export const workshopCapacitySchema = z.object({
+  workshopId: z.string().min(1),
+  endpoint: z.string().regex(endpointRe, "endpoint must be host:port format"),
+  availableSlots: z.number().int().min(0),
+  storageLimitMb: z.number().int().min(0).default(0),
+  bandwidthLimitMbps: z.number().int().min(0).default(0),
+  activeMissions: z.number().int().min(0).default(0),
+  maxMissions: z.number().int().min(1).default(1),
+  cpuLoad: z.number().min(0).max(1).default(0),
+  diskFree: z.number().int().min(0).default(0),
+  updatedAt: z.string().datetime(),
+  signature: z.string().min(1),
+});
+
+export const dhtPlacementResultSchema = z.object({
+  siteId: z.string().regex(kebabRe, "siteId must be kebab-case"),
+  assignedWorkshop: z.string().min(1),
+  reason: dhtPlacementReasonSchema,
+  capacity: workshopCapacitySchema.nullable(),
+});
+
+export const dhtCacheEntrySchema = dhtSiteEntrySchema.extend({
+  cachedAt: z.string().datetime(),
+  expiresAt: z.string().datetime(),
+});
+
+export type DHTSiteEntry = z.infer<typeof dhtSiteEntrySchema>;
+export type DHTConfig = z.infer<typeof dhtConfigSchema>;
+export type DHTLookupResult = z.infer<typeof dhtLookupResultSchema>;
+export type DHTPlacementReason = z.infer<typeof dhtPlacementReasonSchema>;
+export type WorkshopCapacity = z.infer<typeof workshopCapacitySchema>;
+export type DHTPlacementResult = z.infer<typeof dhtPlacementResultSchema>;
+export type DHTCacheEntry = z.infer<typeof dhtCacheEntrySchema>;

package/src/ontology/operations/handoff.ts

@@ -0,0 +1,92 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0221: Zod schemas for the internal site handoff bundle — the version-stamped
+lock that makes ingest version-aware, and the authored/derived manifest partition.
+</purpose>
+<non-goals>
+  <item>Do not perform file IO, hashing, or version comparison — pure shape only.</item>
+  <item>Do not define migrator logic — that lives in @warpgogol/site-kernel-handoff.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0221: initial schemas for the site handoff bundle.</item>
+  <item>RFC-0479: migratorCursor changed from SemVer string to string[] (migrator-id list).</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+const semverRe = /^\d+\.\d+\.\d+$/;
+const sha256Re = /^sha256:[0-9a-f]{64}$/;
+
+/** A single consumed capability, snapshotted from uni.registry.yaml at pack time. */
+export const handoffCapabilitySchema = z.object({
+  /** Unique uni.registry entry id (e.g. "breadcrumbs-component") — the diff key. */
+  id: z.string().min(1),
+  /** Role/semanticId — NOT unique across layers; used for intent grouping and display. */
+  semanticId: z.string().min(1),
+  /** Capability version consumed (uni.registry entry version). */
+  version: z.string().min(1),
+  /** Carried so red-tier removals can be remapped by intent rather than by name. */
+  intent: z.array(z.string()).default([]),
+});
+
+/** Ecosystem stamp: which studio monorepo state the bundle was packed against. */
+export const handoffEcosystemSchema = z.object({
+  /** Root package.json version at pack time, e.g. "4.5.0". */
+  version: z.string().regex(semverRe, "ecosystem.version must be x.y.z"),
+  /** git SHA of the studio monorepo at pack time. */
+  commit: z.string().min(7),
+  /** Highest `implemented` RFC id at pack time, e.g. "RFC-0220". */
+  rfcHead: z.string().regex(/^RFC-\d{4}$/),
+  /** Semantic fingerprint of the packages/ tree at pack time (RFC-0364). */
+  platformSemanticHash: z.string().regex(sha256Re),
+  /** Legacy byte hash of packages/ — read-only during migration, removed in RFC-0364 step 7. */
+  packagesHash: z.string().regex(sha256Re).optional(),
+});
+
+/** Passport-derived build provenance carried with the bundle. */
+export const handoffBuildSchema = z.object({
+  /** sha256 of system.yaml at last build. */
+  systemHash: z.string().regex(sha256Re),
+  commitSha: z.string().min(7),
+});
+
+/** handoff-lock.json — the artifact that makes ingest version-aware (RFC-0221 §2). */
+export const handoffLockSchema = z.object({
+  /** Lock format version, independent of the ecosystem version. */
+  schemaVersion: z.string().regex(semverRe),
+  app: z.string().min(1),
+  packedAt: z.string().datetime(),
+  ecosystem: handoffEcosystemSchema,
+  /** Ecosystem version this site is "synced to" — equals ecosystem.version at pack. */
+  migratorCursor: z.array(z.string()),
+  /** The CONSUMED subset of uni.registry.yaml (not the whole registry). */
+  capabilities: z.array(handoffCapabilitySchema).default([]),
+  build: handoffBuildSchema,
+});
+
+/** One path entry in the bundle manifest: is it source of truth, or regenerated? */
+export const handoffManifestEntrySchema = z.object({
+  /** Bundle-relative POSIX path. */
+  path: z.string().min(1),
+  /** authored = round-trips, source of truth. derived = disposable, regenerated. */
+  kind: z.enum(["authored", "derived"]),
+  /** sha256 of the file contents at pack time (integrity + derived-edit detection). */
+  hash: z.string().regex(sha256Re),
+});
+
+/** handoff-manifest.json — authored/derived partition + integrity (RFC-0221 §5). */
+export const handoffManifestSchema = z.object({
+  schemaVersion: z.string().regex(semverRe),
+  app: z.string().min(1),
+  entries: z.array(handoffManifestEntrySchema).default([]),
+});
+
+export type HandoffCapability = z.infer<typeof handoffCapabilitySchema>;
+export type HandoffEcosystem = z.infer<typeof handoffEcosystemSchema>;
+export type HandoffBuild = z.infer<typeof handoffBuildSchema>;
+export type HandoffLock = z.infer<typeof handoffLockSchema>;
+export type HandoffManifestEntry = z.infer<typeof handoffManifestEntrySchema>;
+export type HandoffManifest = z.infer<typeof handoffManifestSchema>;