@fourier-labs/harbour-contracts 0.5.0 → 0.9.0

package/gen-ts/promotion-request.ts

@@ -0,0 +1,43 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * JSON body for POST /v1/tenants/{tenant}/apps/{app}/promotions. Repository identity is loaded from stored application and preview records, not supplied by the caller.
+ */
+export interface PromotionRequest {
+  /**
+   * Immutable preview version selected by the caller. The API also verifies that its tenant and app match the route.
+   */
+  previewVersionId: string;
+  /**
+   * Current commit at the configured production branch head. Its root Git tree must equal the preview tree.
+   */
+  commit: string;
+  /**
+   * Durable caller-generated key. Identical replays return the original production version; reuse with a changed request is rejected.
+   */
+  idempotencyKey: string;
+  environmentBindings?: PromotionRequestEnvironmentBindings;
+}
+/**
+ * Optional secret bindings for the production version. Additive: promotions without it remain valid, and a deployment plane that ignores the field behaves exactly as before. Named environmentBindings to match deploy-request.schema.json, whose preview counterpart this mirrors.
+ */
+export interface PromotionRequestEnvironmentBindings {
+  /**
+   * Secret bindings for the production version. An empty array is meaningful: it says the caller looked and the app declares no secrets.
+   */
+  bindings: PromotionRequestSecretBinding[];
+}
+/**
+ * One secret binding. Unlike the preview counterpart there is no `value` member and `secretRef` is required, so a plain literal is unrepresentable on the promotion path rather than merely refused by the handler. The secretRef pattern admits only the app-secret shape, which is what keeps a promotion from naming a tenant integration credential.
+ */
+export interface PromotionRequestSecretBinding {
+  /**
+   * Environment-variable name the app reads.
+   */
+  name: string;
+  /**
+   * Governance reference the deployment plane resolves. The value never appears in the request, in this schema, or in any record derived from it.
+   */
+  secretRef: string;
+}

package/gen-ts/promotion-response.ts

@@ -0,0 +1,20 @@
+/* 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';
+  acceptedAt: string;
+  statusUrl: string;
+}

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.5.0",
+  "version": "0.9.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"]
 }

package/schema/ai-metering-policy.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-metering-policy.schema.json",
+  "title": "AiMeteringPolicy",
+  "description": "Additive v2 metering-policy binding. It binds a composite policy to immutable pricing revisions without changing the v1 policy snapshot.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "policyDigest", "pricingRevisionDigests", "reservationMode", "policyDigestV2", "publishedAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-metering-policy/2.0" },
+    "policyDigest": { "$ref": "#/definitions/AiMeteringPolicyDigest" },
+    "pricingRevisionDigests": { "type": "array", "minItems": 1, "maxItems": 512, "uniqueItems": true, "items": { "$ref": "#/definitions/AiMeteringPolicyDigest" } },
+    "reservationMode": { "type": "string", "const": "committed_exposure" },
+    "policyDigestV2": { "$ref": "#/definitions/AiMeteringPolicyDigest" },
+    "publishedAt": { "type": "string", "format": "date-time" }
+  },
+  "definitions": { "AiMeteringPolicyDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" } }
+}

package/schema/ai-pricing-revision.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-pricing-revision.schema.json",
+  "title": "AiPricingRevision",
+  "description": "Immutable v2 line-item pricing revision. A correction is a new revision; published records are never edited.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "revisionId", "provider", "providerModel", "currency", "dimensions", "revisionDigest", "effectiveAt", "publishedAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-pricing-revision/2.0" },
+    "revisionId": { "$ref": "#/definitions/AiPricingIdentifier" },
+    "provider": { "type": "string", "enum": ["openai", "anthropic", "gemini", "openrouter"] },
+    "providerModel": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "region": { "$ref": "#/definitions/AiPricingIdentifier" },
+    "currency": { "type": "string", "const": "USD" },
+    "dimensions": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/definitions/PriceDimension" } },
+    "supersedesRevisionId": { "$ref": "#/definitions/AiPricingIdentifier" },
+    "revisionDigest": { "$ref": "#/definitions/AiPricingDigest" },
+    "effectiveAt": { "type": "string", "format": "date-time" },
+    "publishedAt": { "type": "string", "format": "date-time" }
+  },
+  "definitions": {
+    "AiPricingIdentifier": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+    "AiPricingDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "PriceDimension": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dimension", "direction", "unit", "scale", "microUsdPerScale"],
+      "properties": {
+        "dimension": { "$ref": "#/definitions/AiPricingIdentifier" },
+        "direction": { "type": "string", "enum": ["input", "output"] },
+        "unit": { "$ref": "#/definitions/AiPricingIdentifier" },
+        "scale": { "type": "integer", "minimum": 1 },
+        "microUsdPerScale": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}