@fourier-labs/harbour-contracts 0.6.0 → 0.9.0

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.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 }
+      }
+    }
+  }
+}

package/schema/ai-runtime-binding.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-runtime-binding.schema.json",
+  "title": "AiRuntimeBinding",
+  "description": "Platform-neutral, value-free binding of one workload identity to one version-scoped Harbour Gateway secret. Platform adapters may add implementation details internally; they never enter this contract.",
+  "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/AiRuntimeSafeReference" },
+    "secretRef": { "$ref": "#/definitions/AiRuntimeSafeReference" },
+    "runtimeBindingDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  },
+  "definitions": {
+    "AiRuntimeSafeReference": {
+      "description": "A value-free hierarchical identifier. Schemes are an additive reviewed registry; userinfo, ports, percent encoding, query strings, fragments and empty path segments are unrepresentable.",
+      "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})*$"
+    }
+  },
+  "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-runtime-contract.schema.json

@@ -41,7 +41,7 @@
     "gatewayKeySecretRef": {
       "type": "string",
       "maxLength": 512,
-      "pattern": "^aws-sm://[A-Za-z0-9/_+=.@-]+$"
+      "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",
@@ -53,6 +53,7 @@
       }
     },
     "policyDigest": { "$ref": "#/definitions/AiRuntimeDigest" },
+    "runtimeBinding": { "$ref": "#/definitions/AiRuntimeContractBinding" },
     "requiredStrategies": {
       "type": "array",
       "minItems": 1,
@@ -80,6 +81,27 @@
       "minLength": 3,
       "maxLength": 160,
       "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*/[A-Za-z0-9][A-Za-z0-9_./-]*$"
+    },
+    "AiRuntimeContractBinding": {
+      "description": "Optional additive platform-neutral binding. Existing 1.0 records without it remain valid.",
+      "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/AiRuntimeContractSafeReference" },
+        "secretRef": { "$ref": "#/definitions/AiRuntimeContractSafeReference" },
+        "runtimeBindingDigest": { "$ref": "#/definitions/AiRuntimeDigest" }
+      }
+    },
+    "AiRuntimeContractSafeReference": {
+      "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})*$"
     }
-  }
+  },
+  "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-trace-event-v2.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-trace-event-v2.schema.json",
+  "title": "AiTraceEventV2",
+  "description": "Additive metering projection linked to a readable v1 trace. It carries dimension-level reported or estimated usage without changing the v1 event.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "traceId", "requestId", "policyDigest", "outcome", "usageLineItems", "totalCostMicroUsd", "meteringStatus", "occurredAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-trace-event/2.0" },
+    "traceId": { "type": "string", "pattern": "^trc_[A-Za-z0-9_-]+$", "maxLength": 160 },
+    "requestId": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]+$", "maxLength": 160 },
+    "policyDigest": { "$ref": "#/definitions/AiTraceV2Digest" },
+    "outcome": { "type": "string", "enum": ["succeeded", "blocked", "failed", "cancelled"] },
+    "usageLineItems": { "type": "array", "maxItems": 256, "items": { "$ref": "#/definitions/UsageLineItem" } },
+    "totalCostMicroUsd": { "type": "integer", "minimum": 0 },
+    "reservationId": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "meteringStatus": { "type": "string", "enum": ["settled", "reserved", "unknown", "repaired"] },
+    "occurredAt": { "type": "string", "format": "date-time" }
+  },
+  "definitions": {
+    "AiTraceV2Identifier": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+    "AiTraceV2Digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "UsageLineItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["attempt", "dimension", "direction", "quantity", "unit", "priceRevisionDigest", "scale", "costMicroUsd", "provenance"],
+      "properties": {
+        "attempt": { "type": "integer", "minimum": 1, "maximum": 32 },
+        "dimension": { "$ref": "#/definitions/AiTraceV2Identifier" },
+        "direction": { "type": "string", "enum": ["input", "output"] },
+        "quantity": { "type": "integer", "minimum": 0 },
+        "unit": { "$ref": "#/definitions/AiTraceV2Identifier" },
+        "priceRevisionDigest": { "$ref": "#/definitions/AiTraceV2Digest" },
+        "scale": { "type": "integer", "minimum": 1 },
+        "costMicroUsd": { "type": "integer", "minimum": 0 },
+        "provenance": { "type": "string", "enum": ["reported", "estimated"] }
+      }
+    }
+  }
+}

package/schema/ai-verification-evidence.schema.json

@@ -17,6 +17,7 @@
     "interceptionPlanDigest": { "$ref": "#/definitions/AiVerificationDigest" },
     "runtimeContractDigest": { "$ref": "#/definitions/AiVerificationDigest" },
     "policyDigest": { "$ref": "#/definitions/AiVerificationDigest" },
+    "runtimeBindingDigest": { "$ref": "#/definitions/AiVerificationDigest" },
     "finalWorkspaceDigest": { "$ref": "#/definitions/AiVerificationDigest" },
     "verifiedCallsiteFingerprints": { "type": "array", "maxItems": 1000, "uniqueItems": true, "items": { "$ref": "#/definitions/AiVerificationDigest" } },
     "appliedTransforms": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/definitions/AiVerificationTransform" } },