@fourier-labs/harbour-contracts 0.6.0 → 0.10.0

package/gen-ts/promotion-response.ts

@@ -0,0 +1,28 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * 202 Accepted body returned after the production version and its durable idempotency binding exist.
+ */
+export interface PromotionResponse {
+  idempotencyKey: string;
+  /**
+   * Immutable identity of the admitted production version.
+   */
+  versionId: string;
+  previewVersionId: string;
+  tenant: string;
+  app: string;
+  environment: 'prod';
+  status: 'QUEUED';
+  /**
+   * Digest of the validated production BindingClassificationSubject.
+   */
+  classificationDigest: string;
+  /**
+   * Digest of the exact production-version SanitizedBindingEvidence persisted atomically before this response.
+   */
+  sanitizedBindingDigest: string;
+  acceptedAt: string;
+  statusUrl: string;
+}

package/gen-ts/sanitized-binding-digest-helper.ts

@@ -0,0 +1,33 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+import { createHash } from 'node:crypto';
+import type { BindingClassificationSubject } from './binding-classification-subject.js';
+import type { SanitizedBindingEvidence } from './sanitized-binding-evidence.js';
+
+const domain = 'harbour.sanitized-binding-evidence/1.0';
+const token = (value: string): string => Buffer.byteLength(value, 'utf8') + ':' + value;
+const record = (tag: string, values: string[]): string => tag + values.map(token).join('');
+
+function classificationDigestForReceipt(input: BindingClassificationSubject): string { const sourcePreimage = [record('D', ['harbour.source-revision/1.0']), record('S', [input.sourceRef, input.sourceRevision])].join('\n'); if (input.sourceRevisionDigest !== 'sha256:' + createHash('sha256').update(sourcePreimage, 'utf8').digest('hex')) throw new Error('sourceRevisionDigest mismatch'); const rows = [record('D', ['harbour.binding-classification-subject/1.0']), record('H', [input.schema, input.status, input.tenantId, input.appId, input.environment, input.sourceRef, input.sourceRevision, input.sourceRevisionDigest, input.classifierRevision])]; for (const name of Object.keys(input.classifications).sort()) { const entry = input.classifications[name]!; const mapping = entry.requestedAiMappingId ? input.requestedAiMappings[entry.requestedAiMappingId] : undefined; if (entry.kind === 'provider_credential' && (!mapping || mapping.providerId !== entry.providerId)) throw new Error('requested AI mapping mismatch for ' + name); rows.push(record('C', [name, entry.kind, entry.confidence, entry.providerId ?? '', entry.category ?? '', entry.requestedAiMappingId ?? ''])); } for (const mappingId of Object.keys(input.requestedAiMappings).sort()) { const mapping = input.requestedAiMappings[mappingId]!; rows.push(record('M', [mappingId, mapping.mappingVersion, mapping.providerId])); } return 'sha256:' + createHash('sha256').update(rows.join('\n'), 'utf8').digest('hex'); }
+
+/** Exact UTF-8 length-prefixed preimage. Maps are sorted by key; sanitizedBindingDigest is excluded. */
+export function sanitizedBindingPreimage(input: SanitizedBindingEvidence): string {
+  const rows = [record('D', [domain]), record('H', [input.schema, input.tenantId, input.appId, input.environment, input.versionId, input.sourceRef, input.sourceRevision, input.sourceRevisionDigest, input.classificationDigest])];
+  for (const name of Object.keys(input.bindings).sort()) { const binding = input.bindings[name]!; if (binding.kind === 'configuration' && binding.value === undefined) throw new Error('configuration value missing for ' + name); if (binding.kind === 'secret' && binding.secretRef === undefined) throw new Error('secretRef missing for ' + name); rows.push(record('B', [name, binding.kind, binding.value ?? '', binding.secretRef ?? ''])); }
+  for (const mappingId of Object.keys(input.requiredAiMappings).sort()) { const mapping = input.requiredAiMappings[mappingId]!; rows.push(record('M', [mappingId, mapping.mappingVersion, mapping.providerId])); }
+  return rows.join('\n');
+}
+
+export function computeSanitizedBindingDigest(input: SanitizedBindingEvidence): string { return 'sha256:' + createHash('sha256').update(sanitizedBindingPreimage(input), 'utf8').digest('hex'); }
+
+/** Verifies the atomic allocation receipt cannot relabel source/classification/mappings or retain a provider credential. */
+export function assertSanitizedBindingEvidence(subject: BindingClassificationSubject, evidence: SanitizedBindingEvidence, allocatedVersionId: string): void {
+  for (const field of ['tenantId', 'appId', 'environment', 'sourceRef', 'sourceRevision', 'sourceRevisionDigest'] as const) if (subject[field] !== evidence[field]) throw new Error(field + ' mismatch');
+  if (evidence.versionId !== allocatedVersionId) throw new Error('versionId mismatch');
+  if (subject.classificationDigest !== classificationDigestForReceipt(subject) || evidence.classificationDigest !== subject.classificationDigest) throw new Error('classificationDigest mismatch');
+  const requested = Object.keys(subject.requestedAiMappings).sort(); const required = Object.keys(evidence.requiredAiMappings).sort(); if (requested.length !== required.length || requested.some((id, index) => { const a = subject.requestedAiMappings[id]!; const b = evidence.requiredAiMappings[id]; return id !== required[index] || !b || a.mappingVersion !== b.mappingVersion || a.providerId !== b.providerId; })) throw new Error('requiredAiMappings mismatch');
+  const expectedNames = Object.keys(subject.classifications).filter(name => subject.classifications[name]!.kind !== 'provider_credential').sort(); const actualNames = Object.keys(evidence.bindings).sort(); if (expectedNames.length !== actualNames.length || expectedNames.some((name, index) => name !== actualNames[index])) throw new Error('sanitized binding coverage mismatch');
+  for (const name of expectedNames) if (subject.classifications[name]!.kind !== evidence.bindings[name]!.kind) throw new Error('sanitized binding kind mismatch for ' + name);
+  if (evidence.sanitizedBindingDigest !== computeSanitizedBindingDigest(evidence)) throw new Error('sanitizedBindingDigest mismatch');
+}

package/gen-ts/sanitized-binding-evidence.ts

@@ -0,0 +1,51 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export type SanitizedBindingIdentifier = string;
+export type SanitizedBindingSourceRef = string;
+export type SanitizedBindingSourceRevision = string;
+export type SanitizedBindingDigest = string;
+export type SanitizedRuntimeBinding = {
+  kind: 'configuration' | 'secret';
+  /**
+   * Approved non-secret configuration literal. Provider-credential values are never approved or persisted here.
+   */
+  value?: string;
+  /**
+   * Value-free app-secret reference; tenant integration and provider credential references are outside this contract.
+   */
+  secretRef?: string;
+};
+export type SanitizedBindingProviderId = 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+
+/**
+ * Immutable DCP allocation receipt and sanitized runtime-binding set for one exact allocated version and normalized source revision. DCP persists this evidence atomically with version admission before publish or provisioning. classificationDigest chains to the caller's pre-allocation BindingClassificationSubject; bindings contain only approved configuration or app-secret bindings and never an AI-mapping-owned provider credential.
+ */
+export interface SanitizedBindingEvidence {
+  schema: 'harbour.sanitized-binding-evidence/1.0';
+  tenantId: SanitizedBindingIdentifier;
+  appId: SanitizedBindingIdentifier;
+  environment: 'preview' | 'prod';
+  versionId: string;
+  sourceRef: SanitizedBindingSourceRef;
+  sourceRevision: SanitizedBindingSourceRevision;
+  sourceRevisionDigest: SanitizedBindingDigest;
+  classificationDigest: SanitizedBindingDigest;
+  /**
+   * Exact approved runtime-binding set keyed by environment name. Object keys make duplicate bindings unrepresentable. A provider_credential kind and rejected binding metadata/value are unrepresentable.
+   */
+  bindings: {
+    [k: string]: SanitizedRuntimeBinding;
+  };
+  /**
+   * DCP-validated supported AI mapping requirements keyed by mapping ID. This records what later PLAN/provisioning milestones must enforce; it does not claim those later controls are already active.
+   */
+  requiredAiMappings: {
+    [k: string]: SanitizedBindingAiMapping;
+  };
+  sanitizedBindingDigest: SanitizedBindingDigest;
+}
+export interface SanitizedBindingAiMapping {
+  mappingVersion: string;
+  providerId: SanitizedBindingProviderId;
+}

package/gen-ts/secret-reference.ts

@@ -0,0 +1,40 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * app = shared by the whole app; personal = owned by a single builder (ownerBuilderId).
+ */
+export type SecretReferenceScope = 'app' | 'personal';
+/**
+ * UNSET slots block promotion until a human sets a value (secrets.unresolvable).
+ */
+export type SecretReferenceStatus = 'SET' | 'UNSET';
+/**
+ * builder = created by a builder; minted = created by the platform (e.g. a data-grant credential).
+ */
+export type SecretReferenceOrigin = 'builder' | 'minted';
+
+/**
+ * Secret-Manager MVP: a named secret slot an app depends on. Only the reference and its lifecycle cross this boundary — the secret VALUE never appears in any contract. scope=app secrets are shared by the app; scope=personal secrets belong to one builder (ownerBuilderId). origin records whether a builder created the slot or the platform minted it (e.g. for a data grant).
+ */
+export interface SecretReference {
+  /**
+   * App the secret slot belongs to.
+   */
+  appId: string;
+  /**
+   * Slot name as the app references it (typically the environment-variable name).
+   */
+  name: string;
+  scope: SecretReferenceScope;
+  /**
+   * Owning builder; present only when scope is personal.
+   */
+  ownerBuilderId?: string;
+  /**
+   * secretref URI of the stored value. The value itself never crosses this boundary.
+   */
+  secretRef: string;
+  status: SecretReferenceStatus;
+  origin: SecretReferenceOrigin;
+}

package/gen-ts/transform-report.ts

@@ -0,0 +1,105 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Structured output an agent must return from one Harbour transformation attempt. Handed to the agent as its output schema, then decoded and semantically re-validated by the control plane, which remains the authority. The enum on applied_playbooks.items is the one dynamic part: the adapter injects the names of the playbooks supplied for that invocation before writing the document, so the model is structurally prevented from naming a playbook it was not given. Application-secret handling was removed platform-wide, so this document carries no redactions and no secrets fields.
+ */
+export interface TransformReport {
+  /**
+   * @minItems 1
+   */
+  applied_playbooks: string[];
+  static_rebuild_required: boolean;
+  analysis: {
+    deployable: boolean;
+    needsTransformation: boolean;
+    /**
+     * @maxItems 64
+     */
+    blockers: string[];
+    /**
+     * @minItems 1
+     * @maxItems 1024
+     */
+    surfaces: string[];
+    /**
+     * @maxItems 1024
+     */
+    evidence: {
+      path: string;
+      line: number;
+      reason: string;
+    }[];
+  };
+  database: {
+    mode: 'none' | 'sql' | 'unsupported';
+    changeType: 'none' | 'code_only' | 'schema_only' | 'code_and_schema';
+    requiresCodeChanges: boolean;
+    requiresSchemaMigration: boolean;
+    desiredSchemaPath: string;
+    /**
+     * @maxItems 128
+     */
+    migrationPaths: string[];
+    /**
+     * @maxItems 512
+     */
+    changedFiles: string[];
+    /**
+     * @maxItems 128
+     */
+    evidence: {
+      path: string;
+      line: number;
+      reason: string;
+    }[];
+    /**
+     * @maxItems 64
+     */
+    unsupportedFeatures: string[];
+  };
+  application: {
+    runtime: string;
+    buildKind: 'container' | 'static';
+    topology: 'static' | 'backend' | 'frontend_and_backend';
+    entrypoint: string;
+    build: {
+      /**
+       * @minItems 1
+       * @maxItems 64
+       */
+      installCommand: string[];
+      /**
+       * @minItems 1
+       * @maxItems 64
+       */
+      buildCommand: string[];
+      /**
+       * @minItems 1
+       * @maxItems 16
+       */
+      outputs: {
+        path: string;
+        kind: 'public' | 'backend';
+        route: string;
+      }[];
+    };
+    basePath: {
+      required: boolean;
+      environmentVariable: 'HARBOUR_BASE_PATH';
+    };
+    /**
+     * @minItems 1
+     * @maxItems 64
+     */
+    evidence: {
+      path: string;
+      line: number;
+      reason: string;
+    }[];
+    /**
+     * @maxItems 64
+     */
+    unsupportedFeatures: string[];
+  };
+}

package/gen-ts/version-state-machine.ts

@@ -0,0 +1,52 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export const States = {
+  QUEUED: "QUEUED",
+  ANALYZING: "ANALYZING",
+  TRANSFORMING: "TRANSFORMING",
+  VALIDATING: "VALIDATING",
+  BUILDING: "BUILDING",
+  VERIFYING: "VERIFYING",
+  GATING: "GATING",
+  LIVE: "LIVE",
+  AWAITINGPROMOTION: "AWAITING-PROMOTION",
+  PROMOTING: "PROMOTING",
+  FAILED: "FAILED",
+  STALE: "STALE",
+} as const;
+export type StateName = (typeof States)[keyof typeof States];
+
+export const Environments = {
+  Preview: "preview",
+  Prod: "prod",
+} as const;
+export type EnvironmentName = (typeof Environments)[keyof typeof Environments];
+
+const legalTransitions: Record<string, Record<string, Record<string, true>>> = {
+  "preview": {
+    "QUEUED": { "ANALYZING": true, "FAILED": true, "STALE": true },
+    "ANALYZING": { "BUILDING": true, "TRANSFORMING": true, "FAILED": true, "STALE": true },
+    "TRANSFORMING": { "VALIDATING": true, "FAILED": true, "STALE": true },
+    "VALIDATING": { "BUILDING": true, "TRANSFORMING": true, "FAILED": true, "STALE": true },
+    "BUILDING": { "VERIFYING": true, "FAILED": true, "STALE": true },
+    "VERIFYING": { "GATING": true, "FAILED": true, "STALE": true },
+    "GATING": { "LIVE": true, "FAILED": true, "STALE": true },
+    "LIVE": { "AWAITING-PROMOTION": true },
+    "AWAITING-PROMOTION": { "PROMOTING": true },
+    "PROMOTING": { "LIVE": true, "FAILED": true },
+  },
+  "prod": {
+    "QUEUED": { "PROMOTING": true, "FAILED": true },
+    "PROMOTING": { "LIVE": true, "FAILED": true },
+  },
+};
+const terminalStates = new Set<string>(["FAILED", "STALE"]);
+
+/** True iff from→to is a legal edge for environment in the T1a state machine. */
+export function canTransition(environment: string, from: string, to: string): boolean {
+  return Boolean(legalTransitions[environment]?.[from]?.[to]);
+}
+
+/** True iff the state is terminal (FAILED, STALE). */
+export function isTerminal(state: string): boolean { return terminalStates.has(state); }

package/gen-ts/version-state.ts

@@ -0,0 +1,19 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * The app-version state machine T1a (LLD §1). Root type is the state token itself. `FAILED` carries a separate error category (see error-category.enum.json); the state token is the bare word `FAILED`. Legal edges live in x-transitions; codegen turns them into a shared transition-validation table so control-plane and any consumer agree on legality.
+ */
+export type VersionState =
+  | 'QUEUED'
+  | 'ANALYZING'
+  | 'TRANSFORMING'
+  | 'VALIDATING'
+  | 'BUILDING'
+  | 'VERIFYING'
+  | 'GATING'
+  | 'LIVE'
+  | 'AWAITING-PROMOTION'
+  | 'PROMOTING'
+  | 'FAILED'
+  | 'STALE';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.6.0",
+  "version": "0.10.0",
   "description": "Single source of truth for every data shape that crosses a boundary between Harbour components.",
   "license": "UNLICENSED",
   "private": false,
@@ -11,7 +11,10 @@
   "type": "module",
   "files": [
     "dist",
-    "schema"
+    "schema",
+    "fixtures/ai",
+    "gen-ts",
+    "contract-release.json"
   ],
   "main": "dist/gen-ts/index.js",
   "types": "dist/gen-ts/index.d.ts",
@@ -28,12 +31,13 @@
   "scripts": {
     "gen": "node tools/gen/gen.mjs",
     "build": "tsc -p tsconfig.json",
-    "test": "node --test tools/gen/*.test.mjs resolver/*.test.mjs",
-    "verify": "node tools/gen/gen.mjs && { [ -z \"$(git status --porcelain -- gen-ts gen-go)\" ] || { echo 'STALE: generated code out of date or uncommitted — run make gen and commit'; exit 1; }; }"
+    "test": "node --experimental-strip-types --test tools/gen/*.test.mjs resolver/*.test.mjs",
+    "verify": "node tools/release/verify-release.mjs && node tools/gen/gen.mjs && { [ -z \"$(git status --porcelain -- gen-ts gen-go contract-release.json)\" ] || { echo 'STALE: generated code or release manifest out of date or uncommitted — run make gen and commit'; exit 1; }; }"
   },
   "devDependencies": {
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
+    "@types/node": "^22.10.2",
     "json-schema-to-typescript": "^15.0.4",
     "typescript": "^5.7.2"
   }

package/schema/ai-budget-ledger-event.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-budget-ledger-event.schema.json",
+  "title": "AiBudgetLedgerEvent",
+  "description": "Append-only v2 committed-exposure ledger event. Amounts are integer micro-USD and replay is identified by idempotencyKey.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "eventId", "idempotencyKey", "budgetScope", "period", "eventType", "reservationId", "amountMicroUsd", "committedMicroUsdAfter", "eventDigest", "occurredAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-budget-ledger-event/2.0" },
+    "eventId": { "$ref": "#/definitions/AiBudgetIdentifier" },
+    "idempotencyKey": { "$ref": "#/definitions/AiBudgetIdentifier" },
+    "budgetScope": { "$ref": "#/definitions/AiBudgetIdentifier" },
+    "period": { "$ref": "#/definitions/AiBudgetIdentifier" },
+    "eventType": { "type": "string", "enum": ["RESERVED", "SETTLED", "REPAIRED", "ADJUSTED"] },
+    "reservationId": { "$ref": "#/definitions/AiBudgetIdentifier" },
+    "requestId": { "$ref": "#/definitions/AiBudgetIdentifier" },
+    "amountMicroUsd": { "type": "integer" },
+    "committedMicroUsdAfter": { "type": "integer", "minimum": 0 },
+    "pricingRevisionDigest": { "$ref": "#/definitions/AiBudgetDigest" },
+    "supersedesEventId": { "$ref": "#/definitions/AiBudgetIdentifier" },
+    "eventDigest": { "$ref": "#/definitions/AiBudgetDigest" },
+    "occurredAt": { "type": "string", "format": "date-time" }
+  },
+  "definitions": {
+    "AiBudgetIdentifier": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/#-]*$" },
+    "AiBudgetDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/schema/ai-classification-stamp.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-classification-stamp.schema.json",
+  "title": "AiClassificationStamp",
+  "description": "Immutable, value-free classification evidence for one exact version and source revision. Unavailable evidence is explicit and never interpreted as clean.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "stampId", "tenantId", "appId", "environment", "versionId", "sourceRevision", "status", "classifierId", "classifierVersion", "sourceDigest", "evidenceDigest", "stampDigest", "stampedAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-classification-stamp/1.0" },
+    "stampId": { "$ref": "#/definitions/AiClassificationIdentifier" },
+    "tenantId": { "$ref": "#/definitions/AiClassificationIdentifier" },
+    "appId": { "$ref": "#/definitions/AiClassificationIdentifier" },
+    "environment": { "$ref": "#/definitions/AiClassificationIdentifier" },
+    "versionId": { "type": "string", "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$", "maxLength": 320 },
+    "sourceRevision": { "type": "string", "minLength": 7, "maxLength": 128 },
+    "status": { "type": "string", "enum": ["AVAILABLE", "UNAVAILABLE"] },
+    "classification": { "type": "string", "enum": ["Green", "Yellow", "Orange", "Red"] },
+    "classifierId": { "$ref": "#/definitions/AiClassificationIdentifier" },
+    "classifierVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "sourceDigest": { "$ref": "#/definitions/AiClassificationDigest" },
+    "inventoryDigest": { "$ref": "#/definitions/AiClassificationDigest" },
+    "securityEvidenceDigest": { "$ref": "#/definitions/AiClassificationDigest" },
+    "evidenceDigest": { "$ref": "#/definitions/AiClassificationDigest" },
+    "stampDigest": { "$ref": "#/definitions/AiClassificationDigest" },
+    "unavailableReason": { "$ref": "#/definitions/AiClassificationIdentifier" },
+    "stampedAt": { "type": "string", "format": "date-time" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "AVAILABLE" } }, "required": ["status"] },
+      "then": { "required": ["classification", "inventoryDigest", "securityEvidenceDigest"], "not": { "required": ["unavailableReason"] } },
+      "else": { "required": ["unavailableReason"], "not": { "anyOf": [{ "required": ["classification"] }, { "required": ["inventoryDigest"] }, { "required": ["securityEvidenceDigest"] }] } }
+    }
+  ],
+  "definitions": {
+    "AiClassificationIdentifier": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+    "AiClassificationDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/schema/ai-composite-policy-digest.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-composite-policy-digest.schema.json",
+  "title": "AiCompositePolicyDigestInput",
+  "description": "The complete ordered identity input for one composite policy digest. The digest is SHA-256 over the UTF-8 preimage specified by x-digest; missing optional layer digests use the literal hyphen sentinel.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "baselineDigest", "classificationStampDigest"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-composite-policy-digest/1.0" },
+    "baselineDigest": { "$ref": "#/definitions/AiCompositePolicyDigest" },
+    "classificationStampDigest": { "$ref": "#/definitions/AiCompositePolicyDigest" },
+    "tenantPolicyDigest": { "$ref": "#/definitions/AiCompositePolicyDigest" },
+    "applicationPolicyDigest": { "$ref": "#/definitions/AiCompositePolicyDigest" },
+    "versionOverrideDigest": { "$ref": "#/definitions/AiCompositePolicyDigest" }
+  },
+  "definitions": {
+    "AiCompositePolicyDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  },
+  "x-digest": {
+    "algorithm": "sha256",
+    "encoding": "utf8",
+    "domain": "harbour.ai-composite-policy-digest/1",
+    "absent": "-",
+    "order": ["baselineDigest", "classificationStampDigest", "tenantPolicyDigest", "applicationPolicyDigest", "versionOverrideDigest"]
+  }
+}

package/schema/ai-deployment-gate-decision.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-deployment-gate-decision.schema.json",
+  "title": "AiDeploymentGateDecision",
+  "description": "One append-only deployment gate decision. Corrections are new records linked by supersedesDecisionId; existing records are never overwritten.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "decisionId", "sequence", "tenantId", "appId", "environment", "versionId", "sourceRevision", "decision", "reasonCodes", "classificationStampDigest", "planDigest", "policyDigest", "evidenceDigest", "decisionDigest", "decidedAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-deployment-gate-decision/1.0" },
+    "decisionId": { "$ref": "#/definitions/AiGateIdentifier" },
+    "sequence": { "type": "integer", "minimum": 1 },
+    "supersedesDecisionId": { "$ref": "#/definitions/AiGateIdentifier" },
+    "tenantId": { "$ref": "#/definitions/AiGateIdentifier" },
+    "appId": { "$ref": "#/definitions/AiGateIdentifier" },
+    "environment": { "$ref": "#/definitions/AiGateIdentifier" },
+    "versionId": { "type": "string", "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$", "maxLength": 320 },
+    "sourceRevision": { "type": "string", "minLength": 7, "maxLength": 128 },
+    "decision": { "type": "string", "enum": ["PASS", "BLOCKED"] },
+    "reasonCodes": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "$ref": "#/definitions/AiGateIdentifier" } },
+    "classificationStampDigest": { "$ref": "#/definitions/AiGateDigest" },
+    "planDigest": { "$ref": "#/definitions/AiGateDigest" },
+    "policyDigest": { "$ref": "#/definitions/AiGateDigest" },
+    "evidenceDigest": { "$ref": "#/definitions/AiGateDigest" },
+    "decisionDigest": { "$ref": "#/definitions/AiGateDigest" },
+    "decidedAt": { "type": "string", "format": "date-time" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "decision": { "const": "BLOCKED" } }, "required": ["decision"] },
+      "then": { "properties": { "reasonCodes": { "minItems": 1 } } }
+    }
+  ],
+  "definitions": {
+    "AiGateIdentifier": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+    "AiGateDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/schema/ai-gateway-key-lifecycle-event.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-gateway-key-lifecycle-event.schema.json",
+  "title": "AiGatewayKeyLifecycleEvent",
+  "description": "Append-only, value-free lifecycle evidence for one version-scoped Gateway key.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "eventId", "sequence", "keyId", "tenantId", "appId", "environment", "versionId", "fromStatus", "toStatus", "cause", "eventDigest", "occurredAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-gateway-key-lifecycle-event/1.0" },
+    "eventId": { "$ref": "#/definitions/AiKeyLifecycleIdentifier" },
+    "sequence": { "type": "integer", "minimum": 1 },
+    "keyId": { "type": "string", "pattern": "^[0-9a-f]{32}$" },
+    "tenantId": { "$ref": "#/definitions/AiKeyLifecycleIdentifier" },
+    "appId": { "$ref": "#/definitions/AiKeyLifecycleIdentifier" },
+    "environment": { "$ref": "#/definitions/AiKeyLifecycleIdentifier" },
+    "versionId": { "type": "string", "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$", "maxLength": 320 },
+    "fromStatus": { "$ref": "#/definitions/AiKeyLifecycleStatus" },
+    "toStatus": { "$ref": "#/definitions/AiKeyLifecycleStatus" },
+    "cause": { "type": "string", "enum": ["PLAN", "ACTIVATION", "FAILED", "STALE", "SUPERSEDED", "VERSION_DELETED", "MANUAL_REVOKE", "OVERLAP_EXPIRED", "RECONCILIATION"] },
+    "secretRef": { "$ref": "#/definitions/AiKeyLifecycleSafeReference" },
+    "overlapExpiresAt": { "type": "string", "format": "date-time" },
+    "eventDigest": { "$ref": "#/definitions/AiKeyLifecycleDigest" },
+    "occurredAt": { "type": "string", "format": "date-time" }
+  },
+  "definitions": {
+    "AiKeyLifecycleIdentifier": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+    "AiKeyLifecycleDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "AiKeyLifecycleStatus": { "type": "string", "enum": ["NONE", "PENDING", "ACTIVE", "REVOKED", "DELETION_SCHEDULED", "DELETED"] },
+    "AiKeyLifecycleSafeReference": {
+      "description": "Value-free hierarchical secret reference using the additive reviewed scheme registry; no userinfo, query, fragment, port or percent encoding.",
+      "type": "string",
+      "maxLength": 1024,
+      "pattern": "^(?:aws-sm|iam-role|k8s-sa|secretref|spiffe|vault|vault-v2)://[A-Za-z0-9][A-Za-z0-9._-]{0,127}(?:/[A-Za-z0-9][A-Za-z0-9._~+=-]{0,255})*$"
+    }
+  },
+  "allOf": [
+    {
+      "oneOf": [
+        { "properties": { "fromStatus": { "const": "NONE" }, "toStatus": { "const": "PENDING" } } },
+        { "properties": { "fromStatus": { "const": "PENDING" }, "toStatus": { "const": "ACTIVE" } } },
+        { "properties": { "fromStatus": { "const": "PENDING" }, "toStatus": { "const": "REVOKED" } } },
+        { "properties": { "fromStatus": { "const": "ACTIVE" }, "toStatus": { "const": "REVOKED" } } },
+        { "properties": { "fromStatus": { "const": "REVOKED" }, "toStatus": { "const": "DELETION_SCHEDULED" } } },
+        { "properties": { "fromStatus": { "const": "DELETION_SCHEDULED" }, "toStatus": { "const": "DELETED" } } }
+      ]
+    }
+  ],
+  "x-safe-reference-pattern": "^(?:aws-sm|iam-role|k8s-sa|secretref|spiffe|vault|vault-v2)://[A-Za-z0-9][A-Za-z0-9._-]{0,127}(?:/[A-Za-z0-9][A-Za-z0-9._~+=-]{0,255})*$",
+  "x-approved-reference-schemes": ["aws-sm", "iam-role", "k8s-sa", "secretref", "spiffe", "vault", "vault-v2"],
+  "x-status-definition": "AiKeyLifecycleStatus",
+  "x-terminal": ["DELETED"],
+  "x-transitions": [
+    { "from": "NONE", "to": "PENDING" },
+    { "from": "PENDING", "to": "ACTIVE" },
+    { "from": "PENDING", "to": "REVOKED" },
+    { "from": "ACTIVE", "to": "REVOKED" },
+    { "from": "REVOKED", "to": "DELETION_SCHEDULED" },
+    { "from": "DELETION_SCHEDULED", "to": "DELETED" }
+  ]
+}

package/schema/ai-governance-decision.schema.json

@@ -58,7 +58,7 @@
         "sourceRevision": { "type": "string", "minLength": 7, "maxLength": 128 },
         "mode": { "type": "string", "enum": ["observe", "enforce"] },
         "gatewayBaseUrl": { "type": "string", "format": "uri", "maxLength": 512, "pattern": "^https://[^?#]+/v1$" },
-        "gatewayKeySecretRef": { "type": "string", "maxLength": 512, "pattern": "^aws-sm://[A-Za-z0-9/_+=.@-]+$" },
+        "gatewayKeySecretRef": { "type": "string", "maxLength": 512, "pattern": "^aws-sm://[A-Za-z0-9][A-Za-z0-9._-]{0,127}(?:/[A-Za-z0-9][A-Za-z0-9._~+=-]{0,255})*$" },
         "modelAliases": {
           "type": "object",
           "additionalProperties": false,
@@ -69,9 +69,28 @@
           }
         },
         "policyDigest": { "$ref": "#/definitions/AiDecisionDigest" },
+        "runtimeBinding": { "$ref": "#/definitions/AiDecisionRuntimeBinding" },
         "requiredStrategies": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": ["deployment_injection", "deterministic_adapter"] } }
       }
     },
+    "AiDecisionRuntimeBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "platform", "workloadIdentityRef", "secretRef", "runtimeBindingDigest"],
+      "properties": {
+        "schema": { "type": "string", "const": "harbour.ai-runtime-binding/1.0" },
+        "platform": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_.-]*$" },
+        "workloadIdentityRef": { "$ref": "#/definitions/AiDecisionSafeReference" },
+        "secretRef": { "$ref": "#/definitions/AiDecisionSafeReference" },
+        "runtimeBindingDigest": { "$ref": "#/definitions/AiDecisionDigest" }
+      }
+    },
+    "AiDecisionSafeReference": {
+      "description": "Platform-neutral value-free hierarchical reference using the additive reviewed scheme registry; no userinfo, query, fragment, port or percent encoding.",
+      "type": "string",
+      "maxLength": 1024,
+      "pattern": "^(?:aws-sm|iam-role|k8s-sa|secretref|spiffe|vault|vault-v2)://[A-Za-z0-9][A-Za-z0-9._-]{0,127}(?:/[A-Za-z0-9][A-Za-z0-9._~+=-]{0,255})*$"
+    },
     "AiInterceptionPlanEntry": {
       "type": "object",
       "additionalProperties": false,
@@ -101,5 +120,7 @@
         }
       ]
     }
-  }
+  },
+  "x-safe-reference-pattern": "^(?:aws-sm|iam-role|k8s-sa|secretref|spiffe|vault|vault-v2)://[A-Za-z0-9][A-Za-z0-9._-]{0,127}(?:/[A-Za-z0-9][A-Za-z0-9._~+=-]{0,255})*$",
+  "x-approved-reference-schemes": ["aws-sm", "iam-role", "k8s-sa", "secretref", "spiffe", "vault", "vault-v2"]
 }