@fourier-labs/harbour-contracts 0.3.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Single source of truth for every data shape that crosses a boundary between Harbour components.",
   "license": "UNLICENSED",
   "private": false,
@@ -13,12 +13,22 @@
     "dist",
     "schema"
   ],
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "dist/gen-ts/index.js",
+  "types": "dist/gen-ts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/gen-ts/index.d.ts",
+      "default": "./dist/gen-ts/index.js"
+    },
+    "./resolver": {
+      "types": "./dist/resolver/index.d.ts",
+      "default": "./dist/resolver/index.js"
+    }
+  },
   "scripts": {
     "gen": "node tools/gen/gen.mjs",
     "build": "tsc -p tsconfig.json",
-    "test": "node --test tools/gen/*.test.mjs",
+    "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; }; }"
   },
   "devDependencies": {

package/schema/ai-callsite-inventory.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-callsite-inventory.schema.json",
+  "title": "AiCallsiteInventory",
+  "description": "Immutable, sanitized AI call-site discovery for one exact Harbour deployment version. Inventory records detection only; planning, transformation, and verification outcomes are separate append-only records.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "tenantId",
+    "appId",
+    "environment",
+    "versionId",
+    "sourceRevision",
+    "analyzerVersion",
+    "coverage",
+    "scanStatus",
+    "callsites"
+  ],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-callsite-inventory/1.0" },
+    "tenantId": { "$ref": "#/definitions/AiInventoryIdentifier" },
+    "appId": { "$ref": "#/definitions/AiInventoryIdentifier" },
+    "environment": { "$ref": "#/definitions/AiInventoryIdentifier" },
+    "versionId": {
+      "type": "string",
+      "minLength": 7,
+      "maxLength": 320,
+      "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$"
+    },
+    "sourceRevision": { "type": "string", "minLength": 7, "maxLength": 128 },
+    "analyzerVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "coverage": {
+      "type": "string",
+      "enum": ["complete_for_supported_sdks", "partial"]
+    },
+    "scanStatus": {
+      "type": "string",
+      "enum": ["completed", "cybersecurity_scan_unavailable"],
+      "description": "Required and never defaulted. Unavailable security evidence is not represented as a clean scan."
+    },
+    "callsites": {
+      "type": "array",
+      "maxItems": 1000,
+      "description": "Canonical order is ascending by fingerprint, then path, then line. Producers MUST serialize this order before digesting or publishing the inventory.",
+      "items": { "$ref": "#/definitions/AiInventoryCallsite" }
+    }
+  },
+  "definitions": {
+    "AiInventoryIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$"
+    },
+    "AiInventoryDigest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "AiInventoryEvidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fingerprint", "excerpt"],
+      "properties": {
+        "fingerprint": { "$ref": "#/definitions/AiInventoryDigest" },
+        "excerpt": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 240,
+          "pattern": "^[^\\r\\n]*$",
+          "description": "Sanitized single-line evidence; never raw source or a prompt."
+        }
+      }
+    },
+    "AiInventoryCallsite": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "fingerprint",
+        "path",
+        "sourceFileSha256",
+        "line",
+        "language",
+        "sdk",
+        "method",
+        "strategy",
+        "status",
+        "securityFindingIds",
+        "evidence"
+      ],
+      "properties": {
+        "fingerprint": { "$ref": "#/definitions/AiInventoryDigest" },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[^\\u0000]+$"
+        },
+        "sourceFileSha256": { "$ref": "#/definitions/AiInventoryDigest" },
+        "line": { "type": "integer", "minimum": 1 },
+        "language": {
+          "type": "string",
+          "enum": ["javascript", "typescript", "python", "go", "unknown"]
+        },
+        "sdk": {
+          "type": "string",
+          "enum": [
+            "openai",
+            "openai-compatible",
+            "anthropic",
+            "google-genai",
+            "mistral",
+            "bedrock",
+            "cohere",
+            "ollama",
+            "legacy-gemini",
+            "direct-provider-rest",
+            "unknown"
+          ]
+        },
+        "method": { "type": "string", "minLength": 1, "maxLength": 160 },
+        "requestedModel": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "strategy": {
+          "type": "string",
+          "enum": ["deployment_injection", "deterministic_adapter", "unsupported"]
+        },
+        "status": { "type": "string", "const": "detected" },
+        "securityFindingIds": {
+          "type": "array",
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 160 }
+        },
+        "evidence": { "$ref": "#/definitions/AiInventoryEvidence" }
+      }
+    }
+  }
+}

package/schema/ai-gateway-key-lookup.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-gateway-key-lookup.schema.json",
+  "title": "AiGatewayKeyLookup",
+  "description": "Value-free Gateway authentication metadata for one version-scoped Harbour key.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "keyId", "tenantId", "appId", "environment", "versionId", "tokenPrefix", "status", "createdAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-gateway-key-lookup/1.0" },
+    "keyId": { "type": "string", "pattern": "^[0-9a-f]{32}$" },
+    "tenantId": { "$ref": "#/definitions/AiGatewayKeyIdentifier" },
+    "appId": { "$ref": "#/definitions/AiGatewayKeyIdentifier" },
+    "environment": { "$ref": "#/definitions/AiGatewayKeyIdentifier" },
+    "versionId": { "type": "string", "minLength": 7, "maxLength": 320, "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$" },
+    "tokenPrefix": { "type": "string", "enum": ["hbr_live_", "hbr_test_"] },
+    "status": { "type": "string", "enum": ["PENDING", "ACTIVE", "REVOKED"] },
+    "keyMac": { "type": "string", "pattern": "^[A-Za-z0-9+/]{43}=$" },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "activatedAt": { "type": "string", "format": "date-time" },
+    "expiresAt": { "type": "string", "format": "date-time" },
+    "overlapExpiresAt": { "type": "string", "format": "date-time" },
+    "revokedAt": { "type": "string", "format": "date-time" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "tokenPrefix": { "const": "hbr_live_" } }, "required": ["tokenPrefix"] },
+      "then": { "properties": { "environment": { "const": "production" } } },
+      "else": { "properties": { "environment": { "not": { "const": "production" } } } }
+    },
+    {
+      "if": { "properties": { "status": { "enum": ["ACTIVE", "REVOKED"] } }, "required": ["status"] },
+      "then": { "required": ["keyMac", "activatedAt"] }
+    },
+    {
+      "if": { "properties": { "status": { "const": "REVOKED" } }, "required": ["status"] },
+      "then": { "required": ["revokedAt"] }
+    }
+  ],
+  "definitions": {
+    "AiGatewayKeyIdentifier": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]*$"
+    }
+  },
+  "x-key-token": {
+    "productionPrefix": "hbr_live_",
+    "nonProductionPrefix": "hbr_test_",
+    "pattern": "^hbr_(live|test)_([0-9a-f]{32})\\.([A-Za-z0-9_-]{43})$"
+  }
+}

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

@@ -0,0 +1,105 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/ai-governance-decision.schema.json",
+  "title": "AiGovernanceDecision",
+  "description": "Digest-bound PLAN or VERIFY decision returned to the deployment control plane.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "phase", "tenantId", "appId", "environment", "versionId", "sourceRevision", "decision", "interceptionPath", "reasonCodes", "uncoveredCallsiteFingerprints", "inventoryDigest", "policyDigest", "interceptionPlan", "interceptionPlanDigest", "decidedAt"],
+  "properties": {
+    "schema": { "type": "string", "const": "harbour.ai-governance-decision/1.0" },
+    "phase": { "type": "string", "enum": ["PLAN", "VERIFY"] },
+    "tenantId": { "$ref": "#/definitions/AiDecisionIdentifier" },
+    "appId": { "$ref": "#/definitions/AiDecisionIdentifier" },
+    "environment": { "$ref": "#/definitions/AiDecisionIdentifier" },
+    "versionId": { "type": "string", "minLength": 7, "maxLength": 320, "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$" },
+    "sourceRevision": { "type": "string", "minLength": 7, "maxLength": 128 },
+    "decision": { "type": "string", "enum": ["PASS", "BLOCKED"] },
+    "interceptionPath": { "type": "string", "enum": ["NO_AI_CALLS", "DEPLOYMENT_INJECTION", "DETERMINISTIC_ADAPTER", "BLOCKED"] },
+    "reasonCodes": { "type": "array", "maxItems": 64, "uniqueItems": true, "items": { "$ref": "#/definitions/AiDecisionIdentifier" } },
+    "uncoveredCallsiteFingerprints": { "type": "array", "maxItems": 1000, "uniqueItems": true, "items": { "$ref": "#/definitions/AiDecisionDigest" } },
+    "inventoryDigest": { "$ref": "#/definitions/AiDecisionDigest" },
+    "policyDigest": { "$ref": "#/definitions/AiDecisionDigest" },
+    "runtimeContractDigest": { "$ref": "#/definitions/AiDecisionDigest" },
+    "interceptionPlan": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/definitions/AiInterceptionPlanEntry" } },
+    "interceptionPlanDigest": { "$ref": "#/definitions/AiDecisionDigest" },
+    "evidenceDigest": { "$ref": "#/definitions/AiDecisionDigest" },
+    "runtimeContract": { "$ref": "#/definitions/AiDecisionRuntimeContract" },
+    "decidedAt": { "type": "string", "format": "date-time" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "decision": { "const": "BLOCKED" } }, "required": ["decision"] },
+      "then": { "properties": { "interceptionPath": { "const": "BLOCKED" } } },
+      "else": { "properties": { "interceptionPath": { "enum": ["NO_AI_CALLS", "DEPLOYMENT_INJECTION", "DETERMINISTIC_ADAPTER"] } } }
+    },
+    {
+      "if": { "properties": { "interceptionPath": { "enum": ["DEPLOYMENT_INJECTION", "DETERMINISTIC_ADAPTER"] } }, "required": ["interceptionPath"] },
+      "then": { "required": ["runtimeContract", "runtimeContractDigest"] }
+    },
+    {
+      "if": { "properties": { "interceptionPath": { "const": "NO_AI_CALLS" } }, "required": ["interceptionPath"] },
+      "then": { "properties": { "interceptionPlan": { "maxItems": 0 } }, "not": { "anyOf": [{ "required": ["runtimeContract"] }, { "required": ["runtimeContractDigest"] }] } }
+    }
+  ],
+  "definitions": {
+    "AiDecisionIdentifier": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+    "AiDecisionDigest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "AiDecisionRuntimeContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "tenantId", "appId", "environment", "versionId", "sourceRevision", "mode", "gatewayBaseUrl", "gatewayKeySecretRef", "modelAliases", "policyDigest", "requiredStrategies"],
+      "properties": {
+        "schema": { "type": "string", "const": "harbour.ai-runtime-contract/1.0" },
+        "tenantId": { "$ref": "#/definitions/AiDecisionIdentifier" },
+        "appId": { "$ref": "#/definitions/AiDecisionIdentifier" },
+        "environment": { "$ref": "#/definitions/AiDecisionIdentifier" },
+        "versionId": { "type": "string", "minLength": 7, "maxLength": 320, "pattern": "^[^#]+#[^#]+#[^#]+#[0-9]{6,}$" },
+        "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/_+=.@-]+$" },
+        "modelAliases": {
+          "type": "object",
+          "additionalProperties": false,
+          "minProperties": 1,
+          "properties": {
+            "generation": { "type": "string", "minLength": 3, "maxLength": 160 },
+            "embeddings": { "type": "string", "minLength": 3, "maxLength": 160 }
+          }
+        },
+        "policyDigest": { "$ref": "#/definitions/AiDecisionDigest" },
+        "requiredStrategies": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": ["deployment_injection", "deterministic_adapter"] } }
+      }
+    },
+    "AiInterceptionPlanEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["callSiteFingerprint", "sourcePath", "expectedSourceFileSha256", "strategy", "allowedSyntaxKinds"],
+      "properties": {
+        "callSiteFingerprint": { "$ref": "#/definitions/AiDecisionDigest" },
+        "sourcePath": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))[^\\u0000]+$" },
+        "expectedSourceFileSha256": { "$ref": "#/definitions/AiDecisionDigest" },
+        "strategy": { "type": "string", "enum": ["deployment_injection", "deterministic_adapter"] },
+        "allowedSyntaxKinds": { "type": "array", "minItems": 1, "maxItems": 32, "uniqueItems": true, "items": { "$ref": "#/definitions/AiDecisionIdentifier" } },
+        "configurationMappingId": { "$ref": "#/definitions/AiDecisionIdentifier" },
+        "configurationMappingVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "transformId": { "$ref": "#/definitions/AiDecisionIdentifier" },
+        "transformVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "runtimeShimName": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^@?[A-Za-z0-9][A-Za-z0-9_.@/-]*$" },
+        "runtimeShimVersion": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "runtimeShimDigest": { "$ref": "#/definitions/AiDecisionDigest" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "strategy": { "const": "deployment_injection" } }, "required": ["strategy"] },
+          "then": { "required": ["configurationMappingId", "configurationMappingVersion"] }
+        },
+        {
+          "if": { "properties": { "strategy": { "const": "deterministic_adapter" } }, "required": ["strategy"] },
+          "then": { "required": ["transformId", "transformVersion", "runtimeShimName", "runtimeShimVersion", "runtimeShimDigest"] }
+        }
+      ]
+    }
+  }
+}