@fourier-labs/harbour-contracts 0.4.0 → 0.6.0

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

@@ -0,0 +1,74 @@
+/**
+ * Closed connector set for the Data-Access MVP.
+ */
+export type DataSourceConnector = 'postgres' | 'redshift' | 'bigquery' | 'databricks';
+/**
+ * byo = admin brought existing infrastructure; harbour_managed = Harbour provisioned it.
+ */
+export type DataSourceProvisioningMode = 'byo' | 'harbour_managed';
+/**
+ * DISABLED sources reject new grants and suspend existing access.
+ */
+export type DataSourceStatus = 'ACTIVE' | 'DISABLED';
+/**
+ * An admin-registered external data source (Data-Access MVP). The credential the platform holds for the source never crosses this boundary — credentialRef is a secretref URI resolved internally. allowedScope is the admin-declared selector allowlist grants are checked against; observedScope is what discovery actually saw and is informational only.
+ */
+export interface DataSource {
+    /**
+     * Owning tenant (org) identifier.
+     */
+    tenantId: string;
+    /**
+     * Tenant-unique data-source identifier.
+     */
+    sourceId: string;
+    connector: DataSourceConnector;
+    /**
+     * Human-readable name shown to admins and builders.
+     */
+    displayName: string;
+    endpoint: DataSourceEndpoint;
+    /**
+     * secretref URI naming the platform-held credential for this source. The referenced value never crosses this boundary.
+     */
+    credentialRef: string;
+    provisioningMode: DataSourceProvisioningMode;
+    /**
+     * Admin-declared selector allowlist (e.g. schema.table patterns) that grant scopes are validated against.
+     */
+    allowedScope: string[];
+    /**
+     * Selectors discovery actually observed on the source. Informational; never widens allowedScope.
+     */
+    observedScope?: string[];
+    /**
+     * Whether builders may request grants against this source.
+     */
+    requestableByBuilders: boolean;
+    status: DataSourceStatus;
+}
+/**
+ * Connector endpoint coordinates. host is always present; database vs project/workspace depends on the connector family.
+ */
+export interface DataSourceEndpoint {
+    /**
+     * Network host (or warehouse endpoint) of the source.
+     */
+    host: string;
+    /**
+     * TCP port; absent where the connector implies it.
+     */
+    port?: number;
+    /**
+     * Database name (postgres/redshift-style connectors).
+     */
+    database?: string;
+    /**
+     * Project identifier (bigquery-style connectors).
+     */
+    project?: string;
+    /**
+     * Workspace identifier (databricks-style connectors).
+     */
+    workspace?: string;
+}

package/dist/{deploy-request.d.ts → gen-ts/deploy-request.d.ts}

@@ -1,3 +1,23 @@
+/**
+ * One environment-variable binding: exactly one of secretRef (secret, resolved at runtime) or value (plain literal).
+ */
+export type DeployRequestEnvironmentBinding = {
+    /**
+     * Environment-variable name the app reads.
+     */
+    name: string;
+    /**
+     * secretref URI resolved at runtime; the value never appears in the request.
+     */
+    secretRef?: string;
+    /**
+     * Plain (non-secret) literal value.
+     */
+    value?: string;
+} & DeployRequestEnvironmentBinding1;
+export type DeployRequestEnvironmentBinding1 = {
+    [k: string]: unknown;
+};
 /**
  * JSON body for POST /v1/tenants/{tenant}/apps/{app}/deployments. tenant and app come from path parameters and are not body fields. The preview MVP requires environment=preview. Every accepted POST is a new deployment intent; idempotencyKey is retained only as request correlation.
  */
@@ -19,6 +39,7 @@ export interface DeployRequest {
      * Optional legacy request-correlation value returned as requestId. It does not make repeated HTTP POSTs idempotent; versionId is the deployment identity and SQS deduplication key.
      */
     idempotencyKey?: string;
+    environmentBindings?: DeployRequestEnvironmentBindings;
 }
 export interface DeployRequestSource {
     /**
@@ -30,3 +51,12 @@ export interface DeployRequestSource {
      */
     repositoryUrl: string;
 }
+/**
+ * Optional runtime environment configuration (Secret-Manager MVP). Named environmentBindings, not environment — the existing required `environment` property is the deployment-target token and predates this object. Additive: requests without it remain valid.
+ */
+export interface DeployRequestEnvironmentBindings {
+    /**
+     * Environment-variable bindings for this deployment.
+     */
+    bindings: DeployRequestEnvironmentBinding[];
+}

package/dist/gen-ts/deployment-source.js

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

package/dist/gen-ts/deployment-status-failure.js

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

package/dist/gen-ts/deployment-status-request.js

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

package/dist/gen-ts/deployment-status-response.js

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

package/dist/gen-ts/env-bindings.js

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

package/dist/{error-category-registry.d.ts → 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/{error-category-registry.js → 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/error-category.js

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

package/dist/gen-ts/error-envelope.js

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

package/dist/{index.d.ts → gen-ts/index.d.ts}

@@ -1,5 +1,18 @@
+export * from './ai-callsite-inventory.js';
+export * from './ai-gateway-key-lookup.js';
+export * from './ai-gateway-key-token.js';
+export * from './ai-governance-decision.js';
+export * from './ai-policy-snapshot.js';
+export * from './ai-runtime-contract.js';
+export * from './ai-trace-event.js';
+export * from './ai-transform-event.js';
+export * from './ai-transform-result.js';
+export * from './ai-verification-evidence.js';
 export * from './api-error-response.js';
 export * from './artifact-contract.js';
+export * from './data-dependency.js';
+export * from './data-grant.js';
+export * from './data-source.js';
 export * from './deploy-request.js';
 export * from './deploy-response.js';
 export * from './deployment-environment.js';
@@ -14,5 +27,7 @@ export * from './error-envelope.js';
 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/{index.js → gen-ts/index.js}

@@ -1,7 +1,20 @@
 /* eslint-disable */
 // Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export * from './ai-callsite-inventory.js';
+export * from './ai-gateway-key-lookup.js';
+export * from './ai-gateway-key-token.js';
+export * from './ai-governance-decision.js';
+export * from './ai-policy-snapshot.js';
+export * from './ai-runtime-contract.js';
+export * from './ai-trace-event.js';
+export * from './ai-transform-event.js';
+export * from './ai-transform-result.js';
+export * from './ai-verification-evidence.js';
 export * from './api-error-response.js';
 export * from './artifact-contract.js';
+export * from './data-dependency.js';
+export * from './data-grant.js';
+export * from './data-source.js';
 export * from './deploy-request.js';
 export * from './deploy-response.js';
 export * from './deployment-environment.js';
@@ -16,5 +29,7 @@ export * from './error-envelope.js';
 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

@@ -0,0 +1,27 @@
+/**
+ * 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 {
+    /**
+     * 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.
+     */
+    staticPath: string;
+    /**
+     * 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.
+     */
+    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/kvs-routing-entry.js

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

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

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

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

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

package/dist/gen-ts/promotion-response.js

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

package/dist/gen-ts/secret-reference.d.ts

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

package/dist/gen-ts/secret-reference.js

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

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/dist/gen-ts/version-state.js

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