@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

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>;

package/src/ontology/operations/index.ts

@@ -1 +1,187 @@
-export * from "@warpgogol/werkstatt-engine/schemas";
+/*
+<MODULE_CONTRACT>
+<purpose>
+Barrel export for @warpgogol/werkstatt-shared/ontology/operations sub-path.
+Re-exports platform operations schemas: handoff, sternsystem, werkstatt,
+mission, release, leitstand, notausgang, materialization, artifact-store,
+naming-policy, dht. These schemas have no relationship to UI structural
+vocabulary and are consumed primarily by @warpgogol/werkstatt-engine and
+site handoff tooling. Sunk from @warpgogol/werkstatt-engine/schemas per
+RFC-1104.
+</purpose>
+<non-goals>
+  <item>Do not re-export UI ontology schemas (constellation, biome, page-entry, etc.) — those live in @warpgogol/werkstatt-shared/ontology/schemas.</item>
+  <item>Do not re-export diagnostic schemas — those live in @warpgogol/werkstatt-shared/kernel (RFC-1104).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1104: retargeted barrel — platform operations schemas sunk from werkstatt-engine/schemas; diagnostic schemas moved to werkstatt-shared/kernel.</item>
+</CHANGE_SUMMARY>
+*/
+
+// RFC-0221: site handoff bundle (lock + authored/derived manifest).
+export {
+  handoffCapabilitySchema,
+  handoffEcosystemSchema,
+  handoffBuildSchema,
+  handoffLockSchema,
+  handoffManifestEntrySchema,
+  handoffManifestSchema,
+} from "./handoff.ts";
+export type {
+  HandoffCapability,
+  HandoffEcosystem,
+  HandoffBuild,
+  HandoffLock,
+  HandoffManifestEntry,
+  HandoffManifest,
+} from "./handoff.ts";
+
+// RFC-0354: Sternsystem bundle contract schemas.
+export {
+  systemPinSchema,
+  mirrorStorageTypeSchema,
+  mirrorEntrySchema,
+  serviceSubdomainSchema,
+  serviceEntrySchema,
+  systemConfigSchema,
+  systemStateSchema,
+  servicesRegistrySchema,
+} from "./sternsystem.ts";
+export type {
+  SystemPin,
+  MirrorStorageType,
+  MirrorEntry,
+  ServiceSubdomain,
+  ServiceEntry,
+  SystemConfig,
+  SystemState,
+  ServicesRegistry,
+} from "./sternsystem.ts";
+
+// RFC-0362: Werkstatt consistency primitive schemas.
+export { werkstattLockSchema, werkstattOperationRecordSchema } from "./werkstatt.ts";
+export type { WerkstattLock, WerkstattOperationRecord } from "./werkstatt.ts";
+
+// RFC-0355: Mission lifecycle and Bordbuch schemas.
+export {
+  missionStateSchema,
+  missionManifestSchema,
+  bordbuchEntryKindSchema,
+  bordbuchEntryStatusSchema,
+  bordbuchEntrySchema,
+} from "./mission.ts";
+export type {
+  MissionState,
+  MissionManifest,
+  BordbuchEntryKind,
+  BordbuchEntryStatus,
+  BordbuchEntry,
+} from "./mission.ts";
+
+// RFC-0361: Centralized naming policy regexes and descriptors.
+export {
+  STERNSYSTEM_ID_REGEX,
+  MISSION_ID_REGEX,
+  RELEASE_ID_REGEX,
+  BORDBUCH_EVENT_ID_REGEX,
+  NON_ASCII_REGEX,
+  KNOWN_TLDS,
+  STERNSYSTEM_ID_POLICY,
+  MISSION_ID_POLICY,
+  RELEASE_ID_POLICY,
+  BORDBUCH_EVENT_ID_POLICY,
+  isLatinOnly,
+  hasTldSuffix,
+} from "./naming-policy.ts";
+
+// RFC-0356: Materialization report schemas.
+export {
+  materializationReportSchema,
+  validationReportSchema,
+  authoredDiffSchema,
+} from "./materialization.ts";
+export type { MaterializationReport, ValidationReport, AuthoredDiff } from "./materialization.ts";
+
+// RFC-0363: Release artifact store schemas.
+export { releaseArtifactManifestSchema, releaseArtifactRefSchema } from "./artifact-store.ts";
+export type { ReleaseArtifactManifest, ReleaseArtifactRef } from "./artifact-store.ts";
+
+// RFC-0357/RFC-0851: Release discipline and behavior snapshot schemas.
+export {
+  releaseArtifactStateSchema,
+  releaseStateSchema,
+  legacyReleaseStateSchema,
+  legacyReleaseDiagnosticSchema,
+  releaseManifestSchema,
+  releaseArtifactRefSchema as releaseArtifactRefSchemaV2,
+  behaviorSnapshotDifferenceSchema,
+  behaviorSnapshotDiffSchema,
+  buildIdentitySchema,
+} from "./release.ts";
+export type {
+  ReleaseArtifactState,
+  ReleaseState,
+  LegacyReleaseState,
+  LegacyReleaseDiagnostic,
+  ReleaseManifest,
+  BuildIdentity,
+  BehaviorSnapshotDifference,
+  BehaviorSnapshotDiff,
+} from "./release.ts";
+
+// RFC-0358/RFC-0379: Leitstand fleet propagation schemas.
+export {
+  deploymentAdapterNameSchema,
+  deploymentChannelSchema,
+  lastPropagatedChannelSchema,
+  purgeResultSchema,
+  deploymentStaticConfigSchema,
+  healthCheckSchema,
+  propagationResultSchema,
+  routeFactSchema,
+} from "./leitstand.ts";
+export type {
+  DeploymentAdapterName,
+  DeploymentChannel,
+  LastPropagatedChannel,
+  PurgeResult,
+  DeploymentStaticConfig,
+  HealthCheck,
+  PropagationResult,
+  RouteFact,
+} from "./leitstand.ts";
+
+// RFC-0359: Notausgang export schemas.
+export {
+  integrationSecretLocationSchema,
+  integrationManifestSchema,
+  integrationNullingSchema,
+  notausgangManifestSchema,
+} from "./notausgang.ts";
+export type {
+  IntegrationSecretLocation,
+  IntegrationManifest,
+  IntegrationNulling,
+  NotausgangManifest,
+} from "./notausgang.ts";
+
+// RFC-0565: DHT site registry and content placement schemas.
+export {
+  dhtSiteEntrySchema,
+  dhtConfigSchema,
+  dhtLookupResultSchema,
+  dhtPlacementReasonSchema,
+  workshopCapacitySchema,
+  dhtPlacementResultSchema,
+  dhtCacheEntrySchema,
+} from "./dht.ts";
+export type {
+  DHTSiteEntry,
+  DHTConfig,
+  DHTLookupResult,
+  DHTPlacementReason,
+  WorkshopCapacity,
+  DHTPlacementResult,
+  DHTCacheEntry,
+} from "./dht.ts";

package/src/ontology/operations/leitstand.ts

@@ -0,0 +1,99 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0358/RFC-0379/RFC-0666: Zod schemas for deployment config, channel model, and propagation results. secretsFile field kept as z.string().optional() for detection (sternsystem.validate rejects any value); secretRefSchema removed as dead code.</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-0790: add deploymentStaticConfigSchema (adapter + channels only, no lastPropagated) for system-config.yaml.</item>
+  <item>RFC-0926: add optional workerVersionId to propagationResultSchema and lastPropagatedChannelSchema for release-aware rollback.</item>
+  <item>RFC-1091: add github-pages to deploymentAdapterNameSchema enum.</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>
+  <history>RFC-0358, RFC-0379, RFC-0595, RFC-0624, RFC-0627, RFC-0666</history>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const deploymentAdapterNameSchema = z.enum([
+  "cloudflare-workers",
+  "github-pages",
+  "netlify",
+  "null",
+]);
+
+export const deploymentChannelSchema = z.object({
+  workerName: z.string(),
+  url: z.string().url(),
+  // RFC-0666: secretsFile kept as z.string().optional() for detection — sternsystem.validate rejects any value.
+  // secretRefSchema removed (dead code — env vars were never set).
+  secretsFile: z.string().optional(),
+});
+
+export const purgeResultSchema = z.object({
+  success: z.boolean(),
+  purgedUrls: z.number(),
+  error: z.string().optional(),
+});
+
+export const lastPropagatedChannelSchema = z.object({
+  releaseId: z.string(),
+  at: z.string().datetime(),
+  healthy: z.boolean(),
+  state: z.enum(["succeeded", "failed", "failed-stale", "in-progress"]),
+  operationId: z.string(),
+  leaseExpiresAt: z.string().datetime().nullable(),
+  purgeResult: purgeResultSchema.optional(),
+  workerVersionId: z.string().optional(),
+});
+
+export const healthCheckSchema = z.object({
+  name: z.string(),
+  url: z.string(),
+  status: z.number().int(),
+  passed: z.boolean(),
+  detail: z.string(),
+  expectedHash: z.string().optional(),
+  actualHash: z.string().optional(),
+});
+
+export const propagationResultSchema = z.object({
+  systemId: z.string(),
+  releaseId: z.string(),
+  state: z.enum(["succeeded", "failed", "failed-stale", "in-progress"]),
+  deploymentUrl: z.string(),
+  workerVersionId: z.string().optional(),
+  startedAt: z.string().datetime(),
+  completedAt: z.string().datetime().nullable(),
+  healthChecks: z.array(healthCheckSchema),
+});
+
+export const routeFactSchema = z.object({
+  path: z.string(),
+  contentHash: z.string().nullable(),
+  redirectTarget: z.string().optional(),
+});
+
+export type DeploymentAdapterName = z.infer<typeof deploymentAdapterNameSchema>;
+export type DeploymentChannel = z.infer<typeof deploymentChannelSchema>;
+export type LastPropagatedChannel = z.infer<typeof lastPropagatedChannelSchema>;
+export type PurgeResult = z.infer<typeof purgeResultSchema>;
+export const deploymentStaticConfigSchema = z.object({
+  adapter: deploymentAdapterNameSchema,
+  channels: z.object({
+    dev: deploymentChannelSchema,
+    alt: deploymentChannelSchema,
+    main: deploymentChannelSchema,
+  }),
+});
+
+export type DeploymentStaticConfig = z.infer<typeof deploymentStaticConfigSchema>;
+export type HealthCheck = z.infer<typeof healthCheckSchema>;
+export type PropagationResult = z.infer<typeof propagationResultSchema>;
+export type RouteFact = z.infer<typeof routeFactSchema>;

package/src/ontology/operations/materialization.ts

@@ -0,0 +1,90 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/ontology/src/operations/materialization.ts as an authored ontology authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Does not define mission lifecycle — that is RFC-0355.</item>
+  <item>Does not define release discipline — that is RFC-0357.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0356: initial materialization report schemas.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const materializationReportSchema = z.object({
+  schemaVersion: z.string().min(1),
+  missionId: z.string().min(1),
+  systemId: z.string().min(1),
+  versionComparison: z.object({
+    verdict: z.enum(["in-sync", "catch-up", "refuse-downgrade"]),
+    pinVersion: z.string(),
+    platformVersion: z.string(),
+    packagesDrift: z.boolean(),
+    message: z.string(),
+  }),
+  migratorChain: z.array(
+    z.object({
+      fromVersion: z.string(),
+      toVersion: z.string(),
+      rfc: z.string(),
+      applied: z.boolean(),
+    }),
+  ),
+  capabilityDiff: z.object({
+    tier: z.enum(["green", "yellow", "red"]),
+    items: z.array(
+      z.object({
+        semanticId: z.string(),
+        status: z.enum(["unchanged", "additive", "renamed-or-bumped", "removed"]),
+        tier: z.enum(["green", "yellow", "red"]),
+        resolution: z.string().nullable(),
+      }),
+    ),
+  }),
+  regeneration: z.object({
+    regeneratedFiles: z.array(z.string()),
+    success: z.boolean(),
+  }),
+  materializedAt: z.string().datetime(),
+});
+
+export const validationReportSchema = z.object({
+  schemaVersion: z.string().min(1),
+  missionId: z.string().min(1),
+  contractFull: z.object({
+    passed: z.boolean(),
+    validators: z.array(
+      z.object({
+        name: z.string(),
+        status: z.enum(["pass", "fail"]),
+        diagnostics: z.array(
+          z.object({
+            ruleId: z.string(),
+            severity: z.string(),
+            message: z.string(),
+          }),
+        ),
+      }),
+    ),
+  }),
+  build: z.object({
+    succeeded: z.boolean(),
+    routeCount: z.number(),
+    sitemapHash: z.string(),
+  }),
+  validatedAt: z.string().datetime(),
+});
+
+export const authoredDiffSchema = z.object({
+  schemaVersion: z.string().min(1),
+  missionId: z.string().min(1),
+  added: z.array(z.string()),
+  modified: z.array(z.string()),
+  removed: z.array(z.string()),
+});
+
+export type MaterializationReport = z.infer<typeof materializationReportSchema>;
+export type ValidationReport = z.infer<typeof validationReportSchema>;
+export type AuthoredDiff = z.infer<typeof authoredDiffSchema>;

package/src/ontology/operations/mission.ts

@@ -0,0 +1,111 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0355: Zod schemas for Mission lifecycle and Bordbuch (hash-chain logbook).</purpose>
+<non-goals>
+  <item>Does not define materialization — that is RFC-0356.</item>
+  <item>Does not define release discipline — that is RFC-0357.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0517: add preflight-skipped kind for preflight gate bypass audit trail.</item>
+  <item>RFC-0706: add nachweis-record and nachweis-consent kinds for Nachweisregister trust lifecycle (ADR-0028).</item>
+  <item>RFC-0715: add nachweis-signed and nachweis-timestamped kinds for N3 cryptographic verification.</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>
+  <history>RFC-0355, RFC-0473, RFC-0479, RFC-0480</history>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+const missionIdRegex = /^[a-z0-9]+(-[a-z0-9]+)*-m\d{6}$/;
+const systemIdRegex = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const eventIdRegex = /^event-\d{6}$/;
+
+export const missionStateSchema = z.enum(["open", "closed", "aborted"]);
+
+export const missionManifestSchema = z.object({
+  schemaVersion: z.string().min(1),
+  missionId: z.string().regex(missionIdRegex),
+  systemId: z.string().regex(systemIdRegex),
+  state: missionStateSchema,
+  brief: z.string().min(1),
+  openedAt: z.string().datetime(),
+  openedBy: z.string().min(1),
+  closedAt: z.string().datetime().nullable(),
+  closedBy: z.string().nullable(),
+  pinAtOpen: z.string().min(1),
+  materializedAt: z.string().datetime().nullable(),
+  reconciledAt: z.string().datetime().nullable(),
+  migratedAt: z.string().datetime().nullable(),
+  releaseId: z.string().nullable(),
+  rfcId: z.string().nullable().default(null),
+  operationId: z.string().min(1),
+});
+
+// When renaming or removing a value from this enum, add the old value to
+// DEPRECATED_KIND_MIGRATIONS in packages/os/site-kernel-handoff/src/bordbuch/bordbuch-io.ts
+// so that existing bordbuch entries on disk are normalized during readBordbuch.
+export const bordbuchEntryKindSchema = z.enum([
+  "mission-open",
+  "mission-close",
+  "mission-abort",
+  "mission-open-rolled-back",
+  "release-ready",
+  "release-rolled-back",
+  "pin-update",
+  "deployment",
+  "notausgang-export",
+  "operator-note",
+  "erratum",
+  "mirror-sync",
+  "pseo",
+  "indexnow.submit",
+  "mission-migrate",
+  "preflight-skipped",
+  // RFC-0706 / ADR-0028: Nachweisregister trust lifecycle
+  "nachweis-record",
+  "nachweis-consent",
+  // RFC-0715: N3 cryptographic verification (operator signature + RFC 3161 timestamp)
+  "nachweis-signed",
+  "nachweis-timestamped",
+  // RFC-0888: Sichtpass lifecycle audit trail
+  "sichtpass",
+  // RFC-0968: Sternsystem handover protocol
+  "handover",
+  // RFC-1031: Evolution controller candidate lifecycle
+  "candidate",
+  // RFC-1037: External-effect compensation verification
+  "effect",
+  // RFC-1035: Isolation controller sandbox lifecycle events
+  "isolation",
+]);
+
+export const bordbuchEntryStatusSchema = z.enum(["done", "failed", "waiting", "escalated"]);
+
+export const bordbuchEntrySchema = z.object({
+  schemaVersion: z.literal("1.0.0"),
+  id: z.string().regex(eventIdRegex),
+  systemId: z.string().min(1),
+  occurredAt: z.string().datetime(),
+  kind: bordbuchEntryKindSchema,
+  status: bordbuchEntryStatusSchema,
+  missionId: z.string().nullable(),
+  releaseId: z.string().nullable(),
+  actor: z.string().min(1),
+  summary: z.string().min(1),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  previousHash: z.string().nullable(),
+  hash: z.string().min(1),
+  erratumOf: z.string().optional(),
+});
+
+export type MissionState = z.infer<typeof missionStateSchema>;
+export type MissionManifest = z.infer<typeof missionManifestSchema>;
+export type BordbuchEntryKind = z.infer<typeof bordbuchEntryKindSchema>;
+export type BordbuchEntryStatus = z.infer<typeof bordbuchEntryStatusSchema>;
+export type BordbuchEntry = z.infer<typeof bordbuchEntrySchema>;