@fourier-labs/harbour 0.1.27 → 0.1.28

package/dist/packages/harbour-cli/src/kit-bundle.js

@@ -1,8 +1,14 @@
 import { PUBLISHED_KIT_BUNDLE } from "./kit-bundle.manifest.js";
-/** The local stack's supporting services. Not part of the published bundle: they run only under `harbour dev`. */
-const LOCAL_SERVICE_IMAGES = {
+/**
+ * The local stack's supporting services. Not part of the published bundle: they run only under `harbour dev`.
+ * MinIO is the exact image the pipeline's validation cell runs (data plane `transformbuild.validationMinIOImage`),
+ * from MinIO's own registry by digest: Docker Hub's `minio/minio` repository disappeared on 2026-09-11
+ * (404, "pull access denied"), and `harbour dev`/`check` pull before every start, so a tag there took the
+ * whole local kit down. A digest cannot be moved or removed from under an app.
+ */
+export const LOCAL_SERVICE_IMAGES = {
     postgres: "postgres:16-alpine",
-    minio: "minio/minio:RELEASE.2025-07-23T15-54-02Z"
+    minio: "quay.io/minio/minio@sha256:d249d1fb6966de4d8ad26c04754b545205ff15a62e4fd19ebd0f26fa5baacbc0"
 };
 /**
  * The bundle this CLI was built with: `manifest.json` of the

package/dist/packages/harbour-cli/src/kit-bundle.manifest.js

@@ -1,18 +1,18 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "harbour.kit-bundle/1.0",
-    "kitVersion": "0.1.21",
+    "kitVersion": "0.1.28",
     "sdk": {
         "package": "@harbour/app-sdk",
-        "version": "1.0.0",
-        "tarballSha256": "561297368f61eb3a81ca64d8d360a353746d059547a2d01cfcc3ad6e3ff7dd84",
-        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:561297368f61eb3a81ca64d8d360a353746d059547a2d01cfcc3ad6e3ff7dd84"
+        "version": "1.1.0",
+        "tarballSha256": "998102545ba9b0eec3687d8ded2609a16dbb1d3254b006401155106bf8b80355",
+        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:998102545ba9b0eec3687d8ded2609a16dbb1d3254b006401155106bf8b80355"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:8a838e05694da93a84def78898807dea177b0cd7bab60697b365151be511f47c",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:6f7142d34ba3f8d7879a71658555c38eaf2f416bb9580461cb74b47a627d16e9"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:1effa54091b76c5668193618f1a781be7157fdd5ad49da831ded354b9e4162ac",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:47b305a2a3234c66702aebccfe53d3929d91556dde29b3c27128e2d18e3f1977"
     },
     "brief": {
-        "fingerprint": "3b9d305bf6eedad1f48f704d3f29c33fcbc3e746bae395b41a3f71b3a809ab8f"
+        "fingerprint": "2efee82148238282a9aae255d071395dfdba69b68b398208cc0b8ea1d5b9a3b0"
     },
     "declarationSchema": "harbour.app-integrations/2.0"
 };

package/dist/packages/harbour-cli/src/kit.js

@@ -18,61 +18,12 @@ export const OPERATIONS = {
 export const READ_OPERATIONS = ["slack.channel.history", "gmail.thread.list", "warehouse.view.read"];
 /** Reads whose input needs an identifier from a prior read (a message id): listed as reads, exercised only through the list. */
 export const DEPENDENT_READ_OPERATIONS = ["gmail.message.read"];
-const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
-/** Validates the committed declaration; every error names the path that broke the closed rules. */
-export function validateDeclaration(value) {
-    const errors = [];
-    const record = (value ?? {});
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return { declaration: emptyDeclaration(), errors: ["declaration must be a JSON object"] };
-    if (record.schema !== "harbour.app-integrations/2.0")
-        errors.push("schema must be harbour.app-integrations/2.0");
-    const connections = record.connections && typeof record.connections === "object" && !Array.isArray(record.connections) ? record.connections : undefined;
-    if (!connections)
-        errors.push("connections must be an object keyed by connection alias");
-    for (const [alias, connection] of Object.entries(connections ?? {})) {
-        if (!LOGICAL_NAME.test(alias))
-            errors.push(`connections.${alias}: alias must be a lowercase logical name`);
-        if (!connection || typeof connection !== "object") {
-            errors.push(`connections.${alias}: must be an object`);
-            continue;
-        }
-        if (connection.kind !== "saas" && connection.kind !== "database")
-            errors.push(`connections.${alias}.kind: must be saas or database`);
-        const operations = connection.operations && typeof connection.operations === "object" ? connection.operations : undefined;
-        if (!operations || !Object.keys(operations).length) {
-            errors.push(`connections.${alias}.operations: at least one operation is required`);
-            continue;
-        }
-        for (const [name, operation] of Object.entries(operations)) {
-            const path = `connections.${alias}.operations.${name}`;
-            const rule = OPERATIONS[name];
-            if (!rule) {
-                errors.push(`${path}: unsupported operation (allowed: ${Object.keys(OPERATIONS).join(", ")})`);
-                continue;
-            }
-            if (rule.kind !== connection.kind)
-                errors.push(`${path}: ${name} belongs to a ${rule.kind} connection`);
-            if (operation?.identity !== rule.identity)
-                errors.push(`${path}.identity: ${name} is always ${rule.identity}`);
-            const resources = operation?.resources;
-            if (name === "warehouse.view.read") {
-                if (!resources || Array.isArray(resources) || typeof resources !== "object" || !Object.keys(resources).length)
-                    errors.push(`${path}.resources: must map view names to {columns}`);
-                else
-                    for (const [view, spec] of Object.entries(resources)) {
-                        if (!LOGICAL_NAME.test(view))
-                            errors.push(`${path}.resources.${view}: view name must be a logical name`);
-                        if (!spec || !Array.isArray(spec.columns) || !spec.columns.length || spec.columns.length > 32 || spec.columns.some(column => typeof column !== "string" || !LOGICAL_NAME.test(column)))
-                            errors.push(`${path}.resources.${view}.columns: 1..32 column names are required`);
-                    }
-            }
-            else if (!Array.isArray(resources) || !resources.length || resources.some(resource => typeof resource !== "string" || !LOGICAL_NAME.test(resource)))
-                errors.push(`${path}.resources: must be a non-empty list of logical resource names (no IDs, tokens or URLs)`);
-        }
-    }
-    return { declaration: record, errors };
-}
+/**
+ * Reads the committed declaration as JSON. The closed rules (schema, connection
+ * kinds, the operation set, identity modes, logical resource names) are the
+ * kit gate's `declaration` check — the pipeline's own — so a defect is named
+ * once, in the same words, by `harbour check` and by CodeBuild.
+ */
 export function emptyDeclaration() { return { schema: "harbour.app-integrations/2.0", connections: {} }; }
 export function resourceNames(operation) { return Array.isArray(operation.resources) ? operation.resources : Object.keys(operation.resources); }
 export function requestResources(operation) {
@@ -86,12 +37,18 @@ export async function readDeclaration(root) {
     catch {
         return { declaration: emptyDeclaration(), errors: [".harbour/integrations.json is missing (run `harbour init`)"] };
     }
+    let parsed;
     try {
-        return validateDeclaration(JSON.parse(raw));
+        parsed = JSON.parse(raw);
     }
     catch {
         return { declaration: emptyDeclaration(), errors: [".harbour/integrations.json is not valid JSON"] };
     }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return { declaration: emptyDeclaration(), errors: [".harbour/integrations.json must be a JSON object"] };
+    const record = parsed;
+    const connections = record.connections && typeof record.connections === "object" && !Array.isArray(record.connections) ? record.connections : {};
+    return { declaration: { schema: record.schema, connections }, errors: [] };
 }
 export function isKitLock(value) {
     const record = value;

package/dist/packages/harbour-cli/src/local-runtime.js

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { copyFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:net";
 import { join, relative } from "node:path";
-import { gateViolations } from "./database-gate.js";
+import { LOCAL_SERVICE_IMAGES } from "./kit-bundle.js";
 import { kitPaths, projectName } from "./kit.js";
 import { CliError } from "./output.js";
 export const runCommand = (command, args, options = {}) => new Promise(resolve => {
@@ -54,13 +54,13 @@ export function composeFile(project, bundle, ports, stateDir) {
         `name: ${project}`,
         "services:",
         "  postgres:",
-        `    image: ${images.postgres ?? "postgres:16-alpine"}`,
+        `    image: ${images.postgres ?? LOCAL_SERVICE_IMAGES.postgres}`,
         `    environment: { POSTGRES_USER: ${LOCAL.dbUser}, POSTGRES_PASSWORD: ${LOCAL.dbPassword}, POSTGRES_DB: ${LOCAL.database} }`,
         `    ports: ["127.0.0.1:${ports.postgres}:5432"]`,
         "    volumes: [postgres-data:/var/lib/postgresql/data]",
         `    healthcheck: { test: ["CMD-SHELL", "pg_isready -U ${LOCAL.dbUser} -d ${LOCAL.database}"], interval: 2s, timeout: 3s, retries: 30 }`,
         "  minio:",
-        `    image: ${images.minio ?? "minio/minio:RELEASE.2025-07-23T15-54-02Z"}`,
+        `    image: ${images.minio ?? LOCAL_SERVICE_IMAGES.minio}`,
         "    command: server /data",
         `    environment: { MINIO_ROOT_USER: ${LOCAL.s3Key}, MINIO_ROOT_PASSWORD: ${LOCAL.s3Secret} }`,
         `    ports: ["127.0.0.1:${ports.minio}:9000"]`,
@@ -123,7 +123,7 @@ export function gatewayConfig(project, ports, stateDir) {
 async function migrationNames(root) {
     return (await readdir(join(root, "migrations")).catch(() => [])).filter(name => name.endsWith(".sql")).sort();
 }
-function internalDatabaseUrl(user = LOCAL.dbUser) { return `postgresql://${user}:${LOCAL.dbPassword}@postgres:5432/${LOCAL.database}?sslmode=disable`; }
+export function internalDatabaseUrl(user = LOCAL.dbUser) { return `postgresql://${user}:${LOCAL.dbPassword}@postgres:5432/${LOCAL.database}?sslmode=disable`; }
 function uploadKey(project) { return createHash("sha256").update(`upload-key:${project}`).digest("base64"); }
 // ---- Ports and lock ------------------------------------------------------------------
 export async function freePort() {
@@ -180,19 +180,9 @@ export class LocalRuntime {
         this.project = project;
         this.composePath = composePath;
     }
-    /** Disposable postgres-only project for `harbour check` migrations: separate name, separate volume, torn down after. */
-    static forCheck(root, run = runCommand) {
-        return new LocalRuntime(root, run, projectName(root, "-check"), join(kitPaths(root).local, "check-compose.yml"));
-    }
     compose(args, options = {}) {
         return this.run("docker", ["compose", "-p", this.project, "-f", this.composePath, ...args], { cwd: this.root, ...options });
     }
-    async writeCheckFiles(bundle) {
-        await mkdir(kitPaths(this.root).local, { recursive: true });
-        await writeFile(this.composePath, [`name: ${this.project}`, "services:", "  postgres:", `    image: ${bundle.images.postgres ?? "postgres:16-alpine"}`, `    environment: { POSTGRES_USER: ${LOCAL.dbUser}, POSTGRES_PASSWORD: ${LOCAL.dbPassword}, POSTGRES_DB: ${LOCAL.database} }`, "    volumes: [postgres-data:/var/lib/postgresql/data]", `    healthcheck: { test: ["CMD-SHELL", "pg_isready -U ${LOCAL.dbUser} -d ${LOCAL.database}"], interval: 1s, timeout: 3s, retries: 30 }`, "volumes:", `  postgres-data: { name: ${this.project}-postgres }`, ""].join("\n"));
-    }
-    /** Removes this project's containers and volumes without the reset banner (check teardown). */
-    async down() { await this.compose(["down", "-v", "--remove-orphans"], { quiet: true }); }
     async writeFiles(bundle, ports) {
         const paths = kitPaths(this.root);
         await mkdir(paths.state, { recursive: true });
@@ -229,6 +219,14 @@ export class LocalRuntime {
         const result = await this.compose(["stop"], { quiet: true });
         return { stopped: result.code === 0 };
     }
+    /**
+     * Removes this project's containers and network, keeping its named volumes
+     * (the app's local data). What the kit gate uses for a session it started
+     * itself: `stop` would leave one Docker network per checked app behind,
+     * and Docker's address pools run out after a dozen or so ("all predefined
+     * address pools have been fully subnetted").
+     */
+    async down() { await this.compose(["down", "--remove-orphans"], { quiet: true }); }
     /** Removes this project's containers and named volumes only. */
     async reset(output) {
         output(`Deleting local data for this app only: compose project ${this.project}, volumes ${this.project}-postgres and ${this.project}-minio.`);
@@ -252,18 +250,40 @@ export class LocalRuntime {
         }
         return names;
     }
+    psql(sql) {
+        return this.compose(["exec", "-T", "postgres", "psql", "-v", "ON_ERROR_STOP=1", "-U", LOCAL.dbUser, "-d", LOCAL.database], { stdin: sql, quiet: true });
+    }
     /**
-     * Runs the kit database gate (one psql script, see database-gate.ts) against
-     * this project's database after `migrate()`. Resolves to the violation lines,
-     * empty when the schema satisfies the App Gateway role's contract.
+     * Starts the kit gate: the pinned gateway image's `gate` subcommand as a
+     * one-shot service of this project (`docker compose run`), the app mounted
+     * read-only at /workspace, its control listener published on `port`, the
+     * session's PostgreSQL and bucket named for its scratch database and files.
+     * Resolves to the container id; the caller drives the control API
+     * (check.ts) and stops it with stopGate.
      */
-    async databaseGate(sql) {
-        const result = await this.psql(sql);
-        return result.code === 0 ? [] : gateViolations(result.stderr);
+    async startGate(bundle, port, publicUrl) {
+        const result = await this.compose([
+            "run", "--detach", "--no-deps", "--rm", "--publish", `127.0.0.1:${port}:${port}`,
+            "--volume", `${this.root}:/workspace:ro`,
+            "--env", "HARBOUR_GATE_WORKSPACE=/workspace", "--env", `HARBOUR_GATE_LISTEN=:${port}`, "--env", `HARBOUR_GATE_PUBLIC_URL=${publicUrl}`,
+            "--env", `HARBOUR_GATE_DATABASE_URL=${internalDatabaseUrl()}`, "--env", `HARBOUR_GATE_S3_BUCKET=${LOCAL.bucket}`,
+            "gateway", "gate"
+        ], { quiet: true });
+        const id = result.code === 0 ? result.stdout.trim().split("\n").at(-1)?.trim() ?? "" : "";
+        if (!id)
+            throw new CliError("LOCAL_RUNTIME_FAILED", `Docker could not start the kit gate (${bundle.images.appGateway}): ${result.stderr.trim().split("\n").at(-1) ?? "docker error"}.`);
+        return id;
+    }
+    async gateRunning(container) {
+        const result = await this.run("docker", ["inspect", "--format", "{{.State.Running}}", container], { quiet: true });
+        return result.code === 0 && result.stdout.trim() === "true";
+    }
+    async gateLogs(container) {
+        const result = await this.run("docker", ["logs", "--tail", "20", container], { quiet: true });
+        return `${result.stdout}${result.stderr}`.trim().split("\n").slice(-5).join(" | ").slice(0, 800);
     }
-    /** One psql run inside this project's postgres container; `flags` is how a caller asks for machine-readable output (`-At`). */
-    psql(sql, flags = []) {
-        return this.compose(["exec", "-T", "postgres", "psql", "-v", "ON_ERROR_STOP=1", ...flags, "-U", LOCAL.dbUser, "-d", LOCAL.database], { stdin: sql, quiet: true });
+    async stopGate(container) {
+        await this.run("docker", ["rm", "-f", container], { quiet: true });
     }
     /**
      * Applies the platform's realtime outbox migration the gateway generated

package/dist/packages/harbour-cli/src/productionise.js

@@ -11,7 +11,7 @@ import { CLI_VERSION } from "./version.js";
 import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
 import { assertPreviewIntegrationsReady } from "./integrations.js";
 import { kitPaths, recordKitAppId, sourceDigest } from "./kit.js";
-import { preflightDatabaseGate, readReport } from "./check.js";
+import { FLOW_CHECK, preflightKitGate, readReport } from "./check.js";
 export async function productionise(rootArg, client, output, tenantId, includePaths = [], options = {}) {
     const root = resolve(rootArg);
     output(`Harbour is checking ${basename(root)}.`);
@@ -35,12 +35,12 @@ export async function productionise(rootArg, client, output, tenantId, includePa
     // A declared connection without its preview grant would only park the
     // deployment after the save; refuse here, before any operation exists.
     const kitAppId = options.integrations ? await assertPreviewIntegrationsReady(root, options.integrations.governance, tenantId, options.integrations.bundle, output) : options.appId;
-    // A kit migration set the pipeline's database gate would refuse (a table
-    // without RLS, a policy verb never granted, a grant to a role the platform
-    // never creates) is refused here, before the save, with the same wording.
-    const gate = options.databaseGate === false ? undefined : options.databaseGate ?? (options.integrations ? { bundle: options.integrations.bundle } : undefined);
+    // A kit app the pipeline's gate would refuse (a table without RLS, an
+    // operation no journey exercises, a cross-user leak) is refused here,
+    // before the save, by the same gate with the same wording.
+    const gate = options.kitGate === false ? undefined : options.kitGate ?? (options.integrations ? { bundle: options.integrations.bundle } : undefined);
     if (gate)
-        await preflightDatabaseGate(root, gate.bundle, output, gate.run);
+        await preflightKitGate(root, gate.bundle, output, gate.run);
     try {
         await client.initialize();
     }
@@ -140,18 +140,17 @@ export async function productionise(rootArg, client, output, tenantId, includePa
  * against the running app, so both commands are named: the app has to be up
  * before the checks that matter can run at all.
  */
-const RUN_THE_CHECKS = "Start the app with `harbour dev --app-root .`, then run `harbour check --app-root .` in a second terminal. Fix whatever it reports, then run this again.";
-const FIX_THE_CHECKS = "Fix what the checks reported (the detail is in .harbour/local/check-report.json), then run `harbour check --app-root .` again with `harbour dev --app-root .` running.";
+const RUN_THE_CHECKS = "Run `harbour check --app-root .` (it starts the local Harbour services itself when `harbour dev` is not running). Fix whatever it reports, then run this again.";
+const FIX_THE_CHECKS = "Fix what the checks reported (the detail is in .harbour/local/check-report.json), then run `harbour check --app-root .` again.";
 /**
- * The checks the deployment pipeline replays in the cloud, and the only ones
- * `harbour check` cannot run without `harbour dev` up. They are recorded as
- * `not_run` — not as a pass — when the app was not running, which is exactly
- * the state that used to reach the pipeline and fail there. `journeys` is the
- * placeholder name the report uses when none of them ran; each journey that did
- * run is recorded under its own `journey:<file>` name.
+ * The checks the deployment pipeline replays in the cloud: each retained
+ * journey under its own `journey:<file>` name and the operation-coverage gate
+ * under the pipeline's rule for it. The kit gate records them as `not_run` —
+ * not as a pass — when an earlier check stopped the run, which is exactly the
+ * state that used to reach the pipeline and fail there.
  */
 function isReplayedGate(name) {
-    return name === "flow" || name === "journeys" || name.startsWith("journey:");
+    return name === FLOW_CHECK || name.startsWith("journey:");
 }
 /** The retained checks this app keeps, enumerated exactly as `harbour check` and the pipeline enumerate them. */
 async function retainedChecks(root) {
@@ -193,18 +192,18 @@ async function assertChecksPassedForTree(root, output) {
     if (report.sourceDigest !== tree.digest)
         throw new CliError("CHECKS_STALE", "The app's code has changed since its checks last ran, so that result no longer describes what would be deployed. Harbour does not deploy an app whose own checks have not passed for this exact code.", undefined, RUN_THE_CHECKS);
     const checks = Array.isArray(report.checks) ? report.checks : [];
+    const failed = checks.filter(check => check.status === "fail").map(check => check.name);
+    if (failed.length || report.passed !== true)
+        throw new CliError("CHECKS_FAILED", `The app's own checks last ran and did not pass${failed.length ? ` (${nameList(failed)})` : ""}. Harbour does not deploy an app whose checks are failing; the deployment pipeline would refuse it too.`, undefined, FIX_THE_CHECKS);
     // "Skipped" is not "passed". A report whose journeys and coverage gate never
     // ran says nothing about whether the app works, and accepting it would hand
     // the discovery straight back to the pipeline.
-    const notRun = checks.filter(check => isReplayedGate(check.name) && check.status !== "pass" && check.status !== "fail").map(check => check.name);
-    const flowRan = checks.some(check => check.name === "flow" && (check.status === "pass" || check.status === "fail"));
+    const notRun = checks.filter(check => isReplayedGate(check.name) && check.status !== "pass").map(check => check.name);
+    const flowRan = checks.some(check => check.name === FLOW_CHECK && check.status === "pass");
     if (notRun.length || !flowRan) {
-        const names = notRun.length ? notRun : ["flow"];
-        throw new CliError("CHECKS_NOT_RUN", `The last check run skipped ${nameList(names)} instead of passing ${names.length === 1 ? "it" : "them"}: ${names.length === 1 ? "that check needs" : "those checks need"} the app running. The deployment pipeline runs the same ones in the cloud, so skipping them here only moves the failure.`, undefined, RUN_THE_CHECKS);
+        const names = notRun.length ? notRun : [FLOW_CHECK];
+        throw new CliError("CHECKS_NOT_RUN", `The last check run skipped ${nameList(names)} instead of passing ${names.length === 1 ? "it" : "them"}. The deployment pipeline runs the same ones in the cloud, so skipping them here only moves the failure.`, undefined, RUN_THE_CHECKS);
     }
-    const failed = checks.filter(check => check.status === "fail").map(check => check.name);
-    if (failed.length || report.passed !== true)
-        throw new CliError("CHECKS_FAILED", `The app's own checks last ran and did not pass${failed.length ? ` (${nameList(failed)})` : ""}. Harbour does not deploy an app whose checks are failing; the deployment pipeline would refuse it too.`, undefined, FIX_THE_CHECKS);
     output(`The app's own checks passed for this exact code (${retained.length} retained check${plural}, last run ${report.createdAt}).`);
 }
 async function waitForIntake(client, operationRef) {

package/dist/packages/harbour-cli/src/retained-checks.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { allowedLiterals, numericMinimum, textLengthBounds } from "./app-schema.js";
-import { COVERED_CAPABILITIES, capabilitiesCalled, capabilityCallSurface, capabilityUsage, sourceTableUsage } from "./flow-coverage.js";
+import { COVERED_CAPABILITIES, capabilitiesCalled, capabilityCallSurface, capabilityUsage, sourceTableUsage } from "./source-inventory.js";
 import { kitPaths } from "./kit.js";
 /**
  * Retained checks, generated from what the app declares.
@@ -43,12 +43,21 @@ import { kitPaths } from "./kit.js";
 /** First line of every file Harbour wrote, carrying the digest of the body below it. */
 const GENERATED_PREFIX = "// harbour:generated sha256:";
 /** Capability names that own a fixed file name, so a table of the same name does not shadow one. */
-const RESERVED_NAMES = new Set(["files", "telemetry", "actions", "realtime"]);
-/** The data verbs a generated journey performs, in the order it performs them — the set `flow-coverage.ts` inventories. */
+const RESERVED_NAMES = new Set(["files", "telemetry", "actions", "realtime", "ai"]);
+/** The data verbs a generated journey performs, in the order it performs them — the set `source-inventory.ts` inventories. */
 const VERB_ORDER = ["insert", "upsert", "select", "update", "delete"];
-/** Regenerates `.harbour/checks/` in place from the app's code and its own database, and reports every decision. */
-export async function syncRetainedChecks(root, schema) {
-    const plan = await planRetainedChecks(root, schema);
+/**
+ * Regenerates `.harbour/checks/` in place from the app's code and its own
+ * database, and reports every decision. `declared`, when given, is the
+ * capability set the kit gate derived from the source — the set its coverage
+ * gate will demand evidence for — and it is the authority: the kit lane traces
+ * a namespace wrapper (`export function ai() { return harbour.ai }`) to the
+ * capability it wraps whether or not anything calls it, which a call-site
+ * reading of the source never sees. Without it (tests, no gate) the source
+ * reading decides.
+ */
+export async function syncRetainedChecks(root, schema, declared) {
+    const plan = await planRetainedChecks(root, schema, declared);
     const created = [];
     const updated = [];
     for (const check of plan.write) {
@@ -75,14 +84,26 @@ export function describeRetainedChecks(result) {
     ];
 }
 /** Reads the app and decides what `.harbour/checks/` should hold, writing nothing. */
-export async function planRetainedChecks(root, schema) {
-    const [tables, capabilities, surface, existing] = await Promise.all([sourceTableUsage(root), capabilityUsage(root), capabilityCallSurface(root), readChecks(root)]);
+export async function planRetainedChecks(root, schema, declared) {
+    const [tables, used, surface, existing] = await Promise.all([sourceTableUsage(root), capabilityUsage(root), capabilityCallSurface(root), readChecks(root)]);
+    // The gate's derivation, when it spoke, names the capabilities; the source
+    // reading keeps the file attribution where it has one.
+    const capabilities = declared ? new Map(declared.map(capability => [capability, used.get(capability) ?? ["the app's source, as the kit lane derives it"]])) : used;
+    const gateDeclared = (capability) => declared !== undefined && declared.includes(capability);
     const adopted = existing.filter(check => !check.pristine);
     const plan = { write: [], remove: [], adopted: adopted.map(check => check.path), blocked: [], orphaned: [] };
     const planned = new Set();
-    /** A planned check, named by the one capability it exercises: outside the `flow` gate's own surface, Harbour writes nothing. */
+    /**
+     * A planned check, named by the one capability it exercises: outside the
+     * `flow` gate's own surface, Harbour writes nothing. And never over a file
+     * the builder owns: an adopted check under the name Harbour would use is
+     * theirs, however little of the table it still exercises — the gate says
+     * what it misses, and only its author decides.
+     */
     const add = (capability, name, content) => {
-        if (!surface.has(capability))
+        if (!surface.has(capability) && !gateDeclared(capability))
+            return;
+        if (adopted.some(check => check.name === name))
             return;
         planned.add(name);
         plan.write.push({ path: `.harbour/checks/${name}`, content });
@@ -94,7 +115,7 @@ export async function planRetainedChecks(root, schema) {
         // second person is the cross-user coverage. The two are decided separately: editing a
         // journey must not take its table's cross-user denial down with it.
         const journeyCovered = verbs.length > 0 && verbs.every(verb => adopted.some(check => coversTableVerb(check.text, table, verb)));
-        const crossUserCovered = adopted.some(check => check.text.includes("HARBOUR_IDENTITY_CONTEXT_SECOND_USER") && coversTableVerb(check.text, table, "select"));
+        const crossUserCovered = adopted.some(check => actsAsSecondUser(check.text) && coversTableVerb(check.text, table, "select"));
         if (journeyCovered && (crossUserCovered || !declared?.ownerScoped))
             continue;
         const reason = (detail) => plan.blocked.push(`\`${table}\` (${verbs.join(", ")}), which ${usage.files.join(", ")} queries: ${detail}`);
@@ -118,9 +139,9 @@ export async function planRetainedChecks(root, schema) {
             continue;
         if (adopted.some(check => capabilitiesCalled(check.text).has(capability)))
             continue;
-        const generic = capability === "files" ? filesJourney(files) : capability === "telemetry" ? telemetryJourney(files) : undefined;
+        const generic = capability === "files" ? filesJourney(files) : capability === "telemetry" ? telemetryJourney(files) : capability === "ai" ? aiJourney(files) : undefined;
         if (!generic) {
-            plan.blocked.push(`the \`${capability}\` capability ${files.join(", ")} uses: Harbour writes journeys for data, files and telemetry only — write \`.harbour/checks/${capability}-journey.mjs\` yourself`);
+            plan.blocked.push(`the \`${capability}\` capability ${files.join(", ")} uses: Harbour writes journeys for data, files, telemetry and ai only — write \`.harbour/checks/${capability}-journey.mjs\` yourself`);
             continue;
         }
         add(capability, `${capability}-journey.mjs`, generic);
@@ -163,8 +184,8 @@ function stewardship(sources, uuid = false) {
 }
 /** The single signed-in identity every journey but the cross-user one runs as. */
 const SIGNED_IN = [
-    "// The signed-in identity is attached by the SDK itself (HARBOUR_IDENTITY_CONTEXT",
-    "// from `harbour check` and from the pipeline's runner): one injector per request.",
+    "// The signed-in identity is attached by the SDK itself, from the kit gate's",
+    "// runner (the same under `harbour check` and in the pipeline): one injector per request.",
     "const harbour = sdk.createClient({ baseUrl: appUrl });",
     "",
     "const user = await harbour.identity.current();",
@@ -216,14 +237,11 @@ function crossUserCheck(table, schema, row, sources) {
         `// with current_setting('harbour.user_id')${schema.ownerColumn ? ` on \`${schema.ownerColumn}\`` : ""}. Running it here means user isolation can`,
         "// no longer be green under `harbour check` and red in CodeBuild.",
         ...stewardship([schema.file, ...sources], row.uuid),
-        "const secondUser = process.env.HARBOUR_IDENTITY_CONTEXT_SECOND_USER;",
-        "assert.ok(secondUser, \"HARBOUR_IDENTITY_CONTEXT_SECOND_USER is required (set by harbour check and by the pipeline)\");",
-        "// The first person: the SDK attaches HARBOUR_IDENTITY_CONTEXT itself.",
+        "// Both people come from the SDK itself: the kit gate's runner signs two",
+        "// identities and the SDK attaches the first to every request by default and",
+        "// the second when asked. A check never reads a token name.",
         "const owner = sdk.createClient({ baseUrl: appUrl });",
-        "// The second person: the same SDK, with that person's signed identity replacing the first on every request.",
-        "const header = (process.env.HARBOUR_IDENTITY_CONTEXT_HEADER ?? \"X-Harbour-Identity-Context\").toLowerCase();",
-        "const asSecondUser = (input, init = {}) => fetch(input, { ...init, headers: { ...(init.headers ?? {}), [header]: secondUser } });",
-        "const other = sdk.createClient({ baseUrl: appUrl, fetch: asSecondUser });",
+        "const other = sdk.createClient({ baseUrl: appUrl, identity: \"second-user\" });",
         "",
         "const me = await owner.identity.current();",
         "const them = await other.identity.current();",
@@ -289,6 +307,24 @@ function telemetryJourney(sources) {
     ];
     return sign(`${body.join("\n")}\n`);
 }
+function aiJourney(sources) {
+    const body = [
+        "// Retained journey for the app's governed AI: one chat completion reaches the gateway",
+        `// through the running app (HARBOUR_APP_URL) — the capability ${sources.join(", ")} uses`,
+        "// through `harbour.ai.chat`. Locally this is a real governed call through the Harbour",
+        "// development route (your `harbour login`; IT must have enabled an AI provider). In the",
+        "// deployment pipeline it is answered by a canned completion and reported as not tested.",
+        "// The pipeline refuses an app whose checks never exercise a capability its code uses.",
+        ...stewardship(sources),
+        ...SIGNED_IN,
+        "",
+        "const reply = await harbour.ai.chat({ messages: [{ role: \"user\", content: \"Reply with one word: ready\" }], maxTokens: 16 });",
+        "assert.equal(typeof reply.content, \"string\", \"ai.chat must answer with content\");",
+        "assert.ok(reply.content.length > 0, \"the governed completion is not empty\");",
+        "assert.equal(typeof reply.model, \"string\", \"the answer names the governed model alias\");"
+    ];
+    return sign(`${body.join("\n")}\n`);
+}
 // ---- Reading the app ------------------------------------------------------------
 /** How a generated journey writes one row: the values to insert, the column it finds the row by, and the column it changes. */
 function rowShape(schema, needsUpdate) {
@@ -381,6 +417,8 @@ function staleSurface(text, tables, capabilities) {
 }
 /** `insert, update and delete`, for a generated check's opening line. */
 const sentence = (verbs) => verbs.length > 1 ? `${verbs.slice(0, -1).join(", ")} and ${verbs.at(-1)}` : verbs.join("");
+/** A check that acts as the runner's second person, in the SDK's form or the older header form. */
+const actsAsSecondUser = (text) => /identity:\s*["'`]second-user["'`]/.test(text) || text.includes("HARBOUR_IDENTITY_CONTEXT_SECOND_USER");
 const coversTableVerb = (text, table, verb) => new RegExp(`\\.from\\(\\s*["'\`]${table}["'\`]\\s*\\)`).test(text) && new RegExp(`\\.${verb}\\s*\\(`).test(text);
 /** `notes` gets `notes-journey.mjs`; a table sharing a capability's name does not shadow it. */
 const fileName = (table, kind) => `${table}${RESERVED_NAMES.has(table) ? "-table" : ""}-${kind}.mjs`;