@fourier-labs/harbour-contracts 0.5.0 → 0.6.0

package/dist/gen-ts/ai-governance-decision.d.ts

@@ -42,7 +42,7 @@ export type AiInterceptionPlanEntry = {
      * @minItems 1
      * @maxItems 32
      */
-    allowedSyntaxKinds: [AiDecisionIdentifier, ...AiDecisionIdentifier[]];
+    allowedSyntaxKinds: AiDecisionIdentifier[];
     configurationMappingId?: AiDecisionIdentifier;
     configurationMappingVersion?: string;
     transformId?: AiDecisionIdentifier;
@@ -70,5 +70,5 @@ export interface AiDecisionRuntimeContract {
      * @minItems 1
      * @maxItems 2
      */
-    requiredStrategies: ['deployment_injection' | 'deterministic_adapter'] | ['deployment_injection' | 'deterministic_adapter', 'deployment_injection' | 'deterministic_adapter'];
+    requiredStrategies: ('deployment_injection' | 'deterministic_adapter')[];
 }

package/dist/gen-ts/ai-policy-snapshot.d.ts

@@ -33,7 +33,7 @@ export type AiPolicyEmbeddedJsonSchema = {
      * @minItems 1
      * @maxItems 64
      */
-    enum?: [string | number | number | boolean | null, ...(string | number | number | boolean | null)[]];
+    enum?: (string | number | boolean | null)[];
     minimum?: number;
     maximum?: number;
     minLength?: number;
@@ -93,7 +93,7 @@ export interface AiPolicyModel {
      * @minItems 1
      * @maxItems 2
      */
-    capabilities: ['generation' | 'embeddings'] | ['generation' | 'embeddings', 'generation' | 'embeddings'];
+    capabilities: ('generation' | 'embeddings')[];
     approved: boolean;
     pricing: AiPolicyPricing;
 }
@@ -110,139 +110,7 @@ export interface AiPolicyRoute {
      * @minItems 1
      * @maxItems 16
      */
-    targets: [AiPolicyRouteTarget] | [AiPolicyRouteTarget, AiPolicyRouteTarget] | [AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget] | [AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget] | [AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget, AiPolicyRouteTarget] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ] | [
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget,
-        AiPolicyRouteTarget
-    ];
+    targets: AiPolicyRouteTarget[];
     retryCount: number;
     timeoutMs: number;
 }
@@ -275,7 +143,7 @@ export interface AiPolicyGuardrailParameters {
      * @minItems 1
      * @maxItems 64
      */
-    allowedTools?: [string, ...string[]];
+    allowedTools?: string[];
     jsonSchema?: AiPolicyEmbeddedJsonSchema;
     jsonSchemaRef?: AiPolicyDigest;
 }
@@ -293,137 +161,5 @@ export interface AiPolicyRetention {
     /**
      * @maxItems 16
      */
-    revealRoles: [] | [AiPolicyIdentifier] | [AiPolicyIdentifier, AiPolicyIdentifier] | [AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier] | [AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier] | [AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier, AiPolicyIdentifier] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ] | [
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier,
-        AiPolicyIdentifier
-    ];
+    revealRoles: AiPolicyIdentifier[];
 }

package/dist/gen-ts/ai-runtime-contract.d.ts

@@ -23,5 +23,5 @@ export interface AiRuntimeContract {
      * @minItems 1
      * @maxItems 2
      */
-    requiredStrategies: ['deployment_injection' | 'deterministic_adapter'] | ['deployment_injection' | 'deterministic_adapter', 'deployment_injection' | 'deterministic_adapter'];
+    requiredStrategies: ('deployment_injection' | 'deterministic_adapter')[];
 }

package/dist/gen-ts/ai-transform-event.d.ts

@@ -1,8 +1,6 @@
 export type AiTransformIdentifier = string;
 export type AiTransformDigest = string;
 export type AiTransformPlanEntry = {
-    [k: string]: unknown;
-} & {
     callSiteFingerprint: AiTransformDigest;
     sourcePath: string;
     expectedSourceFileSha256: AiTransformDigest;
@@ -15,24 +13,7 @@ export type AiTransformPlanEntry = {
      * @minItems 1
      * @maxItems 32
      */
-    allowedSyntaxKinds: [AiTransformIdentifier, ...AiTransformIdentifier[]];
-    runtimeShimName?: string;
-    runtimeShimVersion?: string;
-    runtimeShimDigest?: AiTransformDigest;
-} & {
-    callSiteFingerprint: AiTransformDigest;
-    sourcePath: string;
-    expectedSourceFileSha256: AiTransformDigest;
-    strategy: 'deployment_injection' | 'deterministic_adapter';
-    configurationMappingId?: AiTransformIdentifier;
-    configurationMappingVersion?: string;
-    transformId?: AiTransformIdentifier;
-    transformVersion?: string;
-    /**
-     * @minItems 1
-     * @maxItems 32
-     */
-    allowedSyntaxKinds: [AiTransformIdentifier, ...AiTransformIdentifier[]];
+    allowedSyntaxKinds: AiTransformIdentifier[];
     runtimeShimName?: string;
     runtimeShimVersion?: string;
     runtimeShimDigest?: AiTransformDigest;
@@ -56,7 +37,7 @@ export interface AiTransformEvent {
      * @minItems 1
      * @maxItems 1000
      */
-    entries: [AiTransformPlanEntry, ...AiTransformPlanEntry[]];
+    entries: AiTransformPlanEntry[];
 }
 export interface AiTransformWorkspace {
     bucket: string;

package/dist/gen-ts/ai-transform-result.d.ts

@@ -12,7 +12,7 @@ export interface AiTransformResult {
      * @minItems 1
      * @maxItems 1000
      */
-    applied: [AiTransformApplied, ...AiTransformApplied[]];
+    applied: AiTransformApplied[];
 }
 export interface AiTransformResultWorkspace {
     bucket: string;

package/dist/gen-ts/ai-verification-evidence.d.ts

@@ -27,7 +27,7 @@ export interface AiVerificationEvidence {
      * @minItems 1
      * @maxItems 32
      */
-    endpointChecks: [AiVerificationEndpointCheck, ...AiVerificationEndpointCheck[]];
+    endpointChecks: AiVerificationEndpointCheck[];
     providerCredentialsAbsent: true;
     smokeTraceId: string;
     evidenceDigest: AiVerificationDigest;

package/dist/gen-ts/data-grant.d.ts

@@ -27,7 +27,7 @@ export interface DataGrant {
      *
      * @minItems 1
      */
-    scope: [string, ...string[]];
+    scope: string[];
     mode: DataGrantMode;
     identityModel: DataGrantIdentityModel;
     status: DataGrantStatus;

package/dist/gen-ts/error-category-registry.d.ts

@@ -4,6 +4,8 @@ export declare const ErrorCategories: {
     readonly IntakeAttestationMissing: "intake.attestation-missing";
     readonly IntakeMultiAppRepo: "intake.multi-app-repo";
     readonly SecretsUnresolvable: "secrets.unresolvable";
+    readonly SecretsReferenceUnresolvable: "secrets.reference-unresolvable";
+    readonly SecretsPlaceholderUnresolved: "secrets.placeholder-unresolved";
     readonly SecretsLeakedInArtifact: "secrets.leaked-in-artifact";
     readonly StorageSqliteMisclassified: "storage.sqlite-misclassified";
     readonly StorageMappingDrift: "storage.mapping-drift";
@@ -12,6 +14,8 @@ export declare const ErrorCategories: {
     readonly FrontendEnvInlinedUnfixable: "frontend.env-inlined-unfixable";
     readonly BuildRecipeFailed: "build.recipe-failed";
     readonly BuildImageTooLarge: "build.image-too-large";
+    readonly BrowserProbeFailed: "browser.probe-failed";
+    readonly BrowserProbeUnavailable: "browser.probe-unavailable";
     readonly VerifySmokeFailed: "verify.smoke-failed";
     readonly VerifyCharacterizationDiverged: "verify.characterization-diverged";
     readonly VerifyMigrationFromZeroFailed: "verify.migration-from-zero-failed";
@@ -27,6 +31,7 @@ export declare const ErrorCategories: {
     readonly AdmissionAppNotRegistered: "admission.app-not-registered";
     readonly DeployCommitNotOnBranch: "deploy.commit-not-on-branch";
     readonly DeployQueuePublicationFailed: "deploy.queue-publication-failed";
+    readonly SourceBranchMoved: "source.branch-moved";
     readonly PromotionPreviewNotPromotable: "promotion.preview-not-promotable";
     readonly PromotionProductionBranchMoved: "promotion.production-branch-moved";
     readonly PromotionSourceTreeMismatch: "promotion.source-tree-mismatch";

package/dist/gen-ts/error-category-registry.js

@@ -6,6 +6,8 @@ export const ErrorCategories = {
     IntakeAttestationMissing: "intake.attestation-missing",
     IntakeMultiAppRepo: "intake.multi-app-repo",
     SecretsUnresolvable: "secrets.unresolvable",
+    SecretsReferenceUnresolvable: "secrets.reference-unresolvable",
+    SecretsPlaceholderUnresolved: "secrets.placeholder-unresolved",
     SecretsLeakedInArtifact: "secrets.leaked-in-artifact",
     StorageSqliteMisclassified: "storage.sqlite-misclassified",
     StorageMappingDrift: "storage.mapping-drift",
@@ -14,6 +16,8 @@ export const ErrorCategories = {
     FrontendEnvInlinedUnfixable: "frontend.env-inlined-unfixable",
     BuildRecipeFailed: "build.recipe-failed",
     BuildImageTooLarge: "build.image-too-large",
+    BrowserProbeFailed: "browser.probe-failed",
+    BrowserProbeUnavailable: "browser.probe-unavailable",
     VerifySmokeFailed: "verify.smoke-failed",
     VerifyCharacterizationDiverged: "verify.characterization-diverged",
     VerifyMigrationFromZeroFailed: "verify.migration-from-zero-failed",
@@ -29,6 +33,7 @@ export const ErrorCategories = {
     AdmissionAppNotRegistered: "admission.app-not-registered",
     DeployCommitNotOnBranch: "deploy.commit-not-on-branch",
     DeployQueuePublicationFailed: "deploy.queue-publication-failed",
+    SourceBranchMoved: "source.branch-moved",
     PromotionPreviewNotPromotable: "promotion.preview-not-promotable",
     PromotionProductionBranchMoved: "promotion.production-branch-moved",
     PromotionSourceTreeMismatch: "promotion.source-tree-mismatch",
@@ -44,6 +49,8 @@ const retryableExact = {
     "intake.attestation-missing": false,
     "intake.multi-app-repo": false,
     "secrets.unresolvable": false,
+    "secrets.reference-unresolvable": false,
+    "secrets.placeholder-unresolved": false,
     "secrets.leaked-in-artifact": false,
     "storage.sqlite-misclassified": false,
     "storage.mapping-drift": false,
@@ -52,6 +59,8 @@ const retryableExact = {
     "frontend.env-inlined-unfixable": false,
     "build.recipe-failed": false,
     "build.image-too-large": false,
+    "browser.probe-failed": true,
+    "browser.probe-unavailable": false,
     "verify.smoke-failed": false,
     "verify.characterization-diverged": false,
     "verify.migration-from-zero-failed": false,
@@ -67,6 +76,7 @@ const retryableExact = {
     "admission.app-not-registered": false,
     "deploy.commit-not-on-branch": false,
     "deploy.queue-publication-failed": true,
+    "source.branch-moved": false,
     "promotion.preview-not-promotable": false,
     "promotion.production-branch-moved": false,
     "promotion.source-tree-mismatch": false,

package/dist/gen-ts/index.d.ts

@@ -28,5 +28,6 @@ export * from './kvs-routing-entry.js';
 export * from './promotion-request.js';
 export * from './promotion-response.js';
 export * from './secret-reference.js';
+export * from './transform-report.js';
 export * from './version-state-machine.js';
 export * from './version-state.js';

package/dist/gen-ts/index.js

@@ -30,5 +30,6 @@ export * from './kvs-routing-entry.js';
 export * from './promotion-request.js';
 export * from './promotion-response.js';
 export * from './secret-reference.js';
+export * from './transform-report.js';
 export * from './version-state-machine.js';
 export * from './version-state.js';

package/dist/gen-ts/kvs-routing-entry.d.ts

@@ -1,13 +1,27 @@
 /**
- * Value stored in the CloudFront KeyValueStore, keyed by host header `<app>.(beta.)harbour.dev` and read by the CloudFront Function on every request (LLD §8). MVP carries exactly {static, api} and nothing else — quota/kill-switch fields are a deliberate, additive future extension consumed by the same function.
+ * Value stored in the CloudFront KeyValueStore and read by the viewer-request router on EVERY request. Keyed by `<org>.<app>` — the tenant-qualified app identity, not a host header; slugs are lowercase DNS-label-shaped and cannot contain dots, so the single dot is an unambiguous separator. Two constraints cannot be expressed in JSON Schema and are enforced in the router: the TOTAL length of all `staticAssetPrefixes` must not exceed 512 bytes, and the array must be empty when `routeMode` is `static`. Written by cutover; a request whose entry fails any of these rules is refused at the edge rather than routed on a guess.
  */
 export interface KvsRoutingEntry {
     /**
-     * S3 origin path for static assets of the LIVE version, e.g. `builds/<app>/<digest>/` (from the artifact `static.path`, LLD §3).
+     * Immutable prefix of the LIVE version's static output: `builds/<org>/<app>/<64-hex-digest>`, with no trailing slash. The digest is what makes a cutover safe — the router rewrites matching requests to this prefix before the cache lookup, so it is also the edge cache key, and a new version therefore cannot serve the previous version's cached bytes.
      */
-    static: string;
+    staticPath: string;
     /**
-     * Backend target for `/api/*` routes — the Lambda alias reached via API Gateway / Function URL for the LIVE version.
+     * Whether the app has an application runtime. REQUIRED: an entry without it is refused with 503 rather than guessed at. In `server` mode a path under a declared `staticAssetPrefixes` entry is served from S3 and everything else goes to `apiDomain`; in `static` mode every path is served from S3.
      */
-    api: string;
+    routeMode: 'server' | 'static';
+    /**
+     * The version's monotonic sequence number within its lane. Cutover uses it to keep writes one-way: an entry is only replaced by a strictly higher ordinal, so a delayed or replayed write cannot move an app backwards.
+     */
+    ordinal: number;
+    /**
+     * The app runtime's AWS_IAM-protected Lambda Function URL host. Required in `server` mode and omitted entirely for a static-only app. The router refuses any other domain shape, so this cannot be pointed at an arbitrary origin.
+     */
+    apiDomain?: string;
+    /**
+     * Build-derived prefixes that a `server` app serves from its immutable S3 output rather than from its runtime, e.g. `_next/static/`. Derived from verified build output, never from framework names. Must be strictly ascending, must total at most 512 bytes, and must be absent or empty in `static` mode — the last two are enforced in the router because JSON Schema cannot express them. Omitted when empty: a server app with public build output and no prefixes serves every asset from its Lambda, which is a build-plan defect rather than a routing one.
+     *
+     * @maxItems 16
+     */
+    staticAssetPrefixes?: string[];
 }

package/dist/gen-ts/promotion-request.d.ts

@@ -14,4 +14,27 @@ export interface PromotionRequest {
      * 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/dist/gen-ts/transform-report.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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/dist/gen-ts/transform-report.js

@@ -0,0 +1,3 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour-contracts",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Single source of truth for every data shape that crosses a boundary between Harbour components.",
   "license": "UNLICENSED",
   "private": false,

package/schema/error-category.enum.json

@@ -16,7 +16,9 @@
     { "id": "intake.unsupported-runtime", "retryable": false, "description": "Detected runtime has no Harbour build recipe." },
     { "id": "intake.attestation-missing", "retryable": false, "description": "Required auth attestation absent." },
     { "id": "intake.multi-app-repo", "retryable": false, "description": "Repo contains more than one deployable app." },
-    { "id": "secrets.unresolvable", "retryable": false, "description": "A referenced secret has no value (prod promotion blocks at GATING until a human sets it)." },
+    { "id": "secrets.unresolvable", "retryable": false, "retired": true, "description": "RETIRED 2026-08-08 and no longer emittable: the secret-materializer stack, its reconciler and the secret-reference playbook were all removed, so nothing can reach this state. Kept rather than deleted because historical failure records still carry it and a dropped id would decode to nothing. Do not emit in new code." },
+    { "id": "secrets.reference-unresolvable", "retryable": false, "description": "A governance secret reference supplied on the deploy request could not be resolved to a stored value — the secret does not exist, the read was denied, or the secretref:// URI is malformed. Not retryable: no amount of waiting produces the value, a human must set it (or fix the reference) before the deploy can proceed." },
+    { "id": "secrets.placeholder-unresolved", "retryable": false, "description": "The built workspace still contains a ${HARBOUR_REDACTED_<KEY>} substitution placeholder after transformation, meaning the transform never converted it into a runtime secret lookup and the artifact would ship a literal placeholder where a secret belongs. Not retryable: the workspace is already built, so the same input yields the same placeholder until the transform is corrected." },
     { "id": "secrets.leaked-in-artifact", "retryable": false, "description": "Artifact secret scan found a plaintext secret in the built image (belt-and-suspenders)." },
     { "id": "storage.sqlite-misclassified", "retryable": false, "description": "SQLite usage not resolvable to a managed binding." },
     { "id": "storage.unsupported-engine", "retryable": false, "family": true, "description": "Storage engine with no Harbour mapping; concrete token names the engine, e.g. storage.unsupported-engine.mongodb." },
@@ -27,6 +29,8 @@
     { "id": "frontend.env-inlined-unfixable", "retryable": false, "description": "Client code inlined build-time env/self-URLs in a way transformation cannot rewrite." },
     { "id": "build.recipe-failed", "retryable": false, "description": "The Harbour build recipe failed for the detected runtime." },
     { "id": "build.image-too-large", "retryable": false, "description": "Built image exceeded the size limit." },
+    { "id": "browser.probe-failed", "retryable": true, "description": "The app built and produced its declared outputs, but the browser probe found it does not serve them — typically assets emitted at the root instead of under the app base path. Retryable because it is fed back to the transform agent, which is the component that can fix it; the merged job retries in-loop and the state machine retries the job. Distinct from build.recipe-failed, which means the build itself did not succeed: here it did." },
+    { "id": "browser.probe-unavailable", "retryable": false, "description": "The browser probe could not reach a verdict — Chromium crashed or disconnected, or it wrote no result document. Says nothing about the app, so it is NOT fed back to the agent: retrying would spend agent budget on something the agent cannot influence, and that budget is currently the only cost control in the system (control-plane-infra ADR 0007). Replaces the uncategorized.browser-probe token the merged job emitted while this entry did not exist." },
     { "id": "verify.smoke-failed", "retryable": false, "description": "Candidate smoke/health check failed (boot, routes, storage, secret refs, response shape)." },
     { "id": "verify.characterization-diverged", "retryable": false, "description": "Post-MVP: recorded req/res replay diverged beyond thresholds." },
     { "id": "verify.migration-from-zero-failed", "retryable": false, "description": "Post-MVP: from-zero migration chain failed on scratch DB." },
@@ -42,6 +46,7 @@
     { "id": "admission.app-not-registered", "retryable": false, "description": "Admission rejected: the app directory does not know this app, so there is no sourceRef to fetch a commit from. Fails closed rather than creating the app on demand — a deploy request must not become an app-creation side effect, or app naming stops being a reviewed act. Non-retryable: the directory is authoritative, so retrying cannot make an unknown app known." },
     { "id": "deploy.commit-not-on-branch", "retryable": false, "description": "Admission rejected: the deploy request's commit is not reachable from the app's branch." },
     { "id": "deploy.queue-publication-failed", "retryable": true, "description": "The version was created but its version-qualified SQS message definitively could not be published. The lane is released when this version still owns it; submitting a new deployment is safe." },
+    { "id": "source.branch-moved", "retryable": false, "description": "The app branch head moved while the transformed commit was being published, so the publish would have raced another push. Non-retryable at this version: the deploy request named a commit and the branch now points elsewhere, so a retry would deploy something the requester did not ask for. Submitting a new deployment for the new head is the recovery." },
     { "id": "promotion.preview-not-promotable", "retryable": false, "description": "The referenced preview is missing, belongs to another route, is not LIVE, or lacks immutable artifact and source-tree evidence." },
     { "id": "promotion.production-branch-moved", "retryable": false, "description": "The requested production commit is not the current configured production branch head." },
     { "id": "promotion.source-tree-mismatch", "retryable": false, "description": "The production commit root Git tree identity differs from the referenced preview tree identity." },

package/schema/kvs-routing-entry.schema.json

@@ -2,20 +2,40 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.harbour.dev/kvs-routing-entry.schema.json",
   "title": "KvsRoutingEntry",
-  "description": "Value stored in the CloudFront KeyValueStore, keyed by host header `<app>.(beta.)harbour.dev` and read by the CloudFront Function on every request (LLD §8). MVP carries exactly {static, api} and nothing else — quota/kill-switch fields are a deliberate, additive future extension consumed by the same function.",
+  "description": "Value stored in the CloudFront KeyValueStore and read by the viewer-request router on EVERY request. Keyed by `<org>.<app>` — the tenant-qualified app identity, not a host header; slugs are lowercase DNS-label-shaped and cannot contain dots, so the single dot is an unambiguous separator. Two constraints cannot be expressed in JSON Schema and are enforced in the router: the TOTAL length of all `staticAssetPrefixes` must not exceed 512 bytes, and the array must be empty when `routeMode` is `static`. Written by cutover; a request whose entry fails any of these rules is refused at the edge rather than routed on a guess.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["static", "api"],
+  "required": ["staticPath", "routeMode", "ordinal"],
   "properties": {
-    "static": {
+    "staticPath": {
       "type": "string",
-      "minLength": 1,
-      "description": "S3 origin path for static assets of the LIVE version, e.g. `builds/<app>/<digest>/` (from the artifact `static.path`, LLD §3)."
+      "pattern": "^builds/[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?/[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?/[0-9a-f]{64}$",
+      "description": "Immutable prefix of the LIVE version's static output: `builds/<org>/<app>/<64-hex-digest>`, with no trailing slash. The digest is what makes a cutover safe — the router rewrites matching requests to this prefix before the cache lookup, so it is also the edge cache key, and a new version therefore cannot serve the previous version's cached bytes."
     },
-    "api": {
+    "routeMode": {
       "type": "string",
-      "minLength": 1,
-      "description": "Backend target for `/api/*` routes — the Lambda alias reached via API Gateway / Function URL for the LIVE version."
+      "enum": ["server", "static"],
+      "description": "Whether the app has an application runtime. REQUIRED: an entry without it is refused with 503 rather than guessed at. In `server` mode a path under a declared `staticAssetPrefixes` entry is served from S3 and everything else goes to `apiDomain`; in `static` mode every path is served from S3."
+    },
+    "ordinal": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The version's monotonic sequence number within its lane. Cutover uses it to keep writes one-way: an entry is only replaced by a strictly higher ordinal, so a delayed or replayed write cannot move an app backwards."
+    },
+    "apiDomain": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+\\.lambda-url\\.[a-z0-9-]+\\.on\\.aws$",
+      "description": "The app runtime's AWS_IAM-protected Lambda Function URL host. Required in `server` mode and omitted entirely for a static-only app. The router refuses any other domain shape, so this cannot be pointed at an arbitrary origin."
+    },
+    "staticAssetPrefixes": {
+      "type": "array",
+      "maxItems": 16,
+      "uniqueItems": true,
+      "description": "Build-derived prefixes that a `server` app serves from its immutable S3 output rather than from its runtime, e.g. `_next/static/`. Derived from verified build output, never from framework names. Must be strictly ascending, must total at most 512 bytes, and must be absent or empty in `static` mode — the last two are enforced in the router because JSON Schema cannot express them. Omitted when empty: a server app with public build output and no prefixes serves every asset from its Lambda, which is a build-plan defect rather than a routing one.",
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*/$"
+      }
     }
   }
 }

package/schema/promotion-request.schema.json

@@ -21,6 +21,44 @@
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$",
       "description": "Durable caller-generated key. Identical replays return the original production version; reuse with a changed request is rejected."
+    },
+    "environmentBindings": {
+      "$ref": "#/definitions/PromotionRequestEnvironmentBindings"
+    }
+  },
+  "definitions": {
+    "PromotionRequestEnvironmentBindings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["bindings"],
+      "properties": {
+        "bindings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/PromotionRequestSecretBinding"
+          },
+          "description": "Secret bindings for the production version. An empty array is meaningful: it says the caller looked and the app declares no secrets."
+        }
+      },
+      "description": "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."
+    },
+    "PromotionRequestSecretBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "secretRef"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]{0,127}$",
+          "description": "Environment-variable name the app reads."
+        },
+        "secretRef": {
+          "type": "string",
+          "pattern": "^secretref://tenant/[A-Za-z0-9._-]+/app/[A-Za-z0-9._-]+/secret/[A-Z][A-Z0-9_]{0,127}$",
+          "description": "Governance reference the deployment plane resolves. The value never appears in the request, in this schema, or in any record derived from it."
+        }
+      },
+      "description": "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."
     }
   }
 }

package/schema/transform-report.schema.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/transform-report.schema.json",
+  "title": "TransformReport",
+  "description": "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.",
+  "x-go-embed": true,
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "applied_playbooks",
+    "static_rebuild_required",
+    "analysis",
+    "database",
+    "application"
+  ],
+  "properties": {
+    "applied_playbooks": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "static_rebuild_required": { "type": "boolean" },
+    "analysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["deployable", "needsTransformation", "blockers", "surfaces", "evidence"],
+      "properties": {
+        "deployable": { "type": "boolean" },
+        "needsTransformation": { "type": "boolean" },
+        "blockers": {
+          "type": "array",
+          "maxItems": 64,
+          "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+        },
+        "surfaces": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1024,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        },
+        "evidence": {
+          "type": "array",
+          "maxItems": 1024,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "line", "reason"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+              "line": { "type": "integer", "minimum": 1 },
+              "reason": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            }
+          }
+        }
+      }
+    },
+    "database": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode",
+        "changeType",
+        "requiresCodeChanges",
+        "requiresSchemaMigration",
+        "desiredSchemaPath",
+        "migrationPaths",
+        "changedFiles",
+        "evidence",
+        "unsupportedFeatures"
+      ],
+      "properties": {
+        "mode": { "type": "string", "enum": ["none", "sql", "unsupported"] },
+        "changeType": {
+          "type": "string",
+          "enum": ["none", "code_only", "schema_only", "code_and_schema"]
+        },
+        "requiresCodeChanges": { "type": "boolean" },
+        "requiresSchemaMigration": { "type": "boolean" },
+        "desiredSchemaPath": { "type": "string", "maxLength": 512 },
+        "migrationPaths": {
+          "type": "array",
+          "maxItems": 128,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        },
+        "changedFiles": {
+          "type": "array",
+          "maxItems": 512,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        },
+        "evidence": {
+          "type": "array",
+          "maxItems": 128,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "line", "reason"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+              "line": { "type": "integer", "minimum": 1 },
+              "reason": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            }
+          }
+        },
+        "unsupportedFeatures": {
+          "type": "array",
+          "maxItems": 64,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        }
+      }
+    },
+    "application": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runtime",
+        "buildKind",
+        "topology",
+        "entrypoint",
+        "build",
+        "basePath",
+        "evidence",
+        "unsupportedFeatures"
+      ],
+      "properties": {
+        "runtime": {
+          "type": "string",
+          "pattern": "^(?:nodejs|python)[0-9]+(?:\\.[0-9]+)?$"
+        },
+        "buildKind": { "type": "string", "enum": ["container", "static"] },
+        "topology": {
+          "type": "string",
+          "enum": ["static", "backend", "frontend_and_backend"]
+        },
+        "entrypoint": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "build": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["installCommand", "buildCommand", "outputs"],
+          "properties": {
+            "installCommand": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 64,
+              "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            },
+            "buildCommand": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 64,
+              "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            },
+            "outputs": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 16,
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["path", "kind", "route"],
+                "properties": {
+                  "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+                  "kind": { "type": "string", "enum": ["public", "backend"] },
+                  "route": {
+                    "type": "string",
+                    "pattern": "^(?:/\\*|/[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*/\\*)$"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "basePath": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["required", "environmentVariable"],
+          "properties": {
+            "required": { "type": "boolean" },
+            "environmentVariable": { "type": "string", "enum": ["HARBOUR_BASE_PATH"] }
+          }
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["path", "line", "reason"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+              "line": { "type": "integer", "minimum": 1 },
+              "reason": { "type": "string", "minLength": 1, "maxLength": 1024 }
+            }
+          }
+        },
+        "unsupportedFeatures": {
+          "type": "array",
+          "maxItems": 64,
+          "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+        }
+      }
+    }
+  }
+}