@fourier-labs/harbour 0.1.25 → 0.1.26

package/dist/packages/harbour-cli/src/app-schema.js

@@ -0,0 +1,178 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * One row per application table, as one JSON document. The scoping is the
+ * database gate's own (`relkind` r/p outside pg_catalog, information_schema and
+ * the platform's harbour_runtime), so "an application table" means the same
+ * thing to the generator as it does to the gate that refuses the app.
+ */
+const CATALOG_SQL = String.raw `
+SELECT coalesce(json_agg(t ORDER BY t.name), '[]'::json)::text FROM (
+  SELECT c.relname AS name,
+    (SELECT coalesce(json_agg(json_build_object(
+        'name', a.attname,
+        'type', format_type(a.atttypid, a.atttypmod),
+        'base', y.typname,
+        'category', y.typcategory,
+        'notnull', a.attnotnull,
+        'default', pg_get_expr(d.adbin, d.adrelid),
+        'generated', a.attidentity <> '' OR a.attgenerated <> '' OR coalesce(pg_get_expr(d.adbin, d.adrelid), '') LIKE 'nextval(%',
+        'fk', EXISTS (SELECT 1 FROM pg_constraint f WHERE f.conrelid = a.attrelid AND f.contype = 'f' AND a.attnum = ANY (f.conkey)),
+        'checks', (SELECT coalesce(json_agg(pg_get_constraintdef(k.oid)), '[]'::json) FROM pg_constraint k WHERE k.conrelid = a.attrelid AND k.contype = 'c' AND a.attnum = ANY (k.conkey))
+      ) ORDER BY a.attnum), '[]'::json)
+     FROM pg_attribute a
+     JOIN pg_type y ON y.oid = a.atttypid
+     LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+     WHERE a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped) AS columns,
+    (SELECT coalesce(json_agg(k.attname ORDER BY u.ord), '[]'::json)
+     FROM pg_constraint p
+     CROSS JOIN LATERAL unnest(p.conkey) WITH ORDINALITY AS u(num, ord)
+     JOIN pg_attribute k ON k.attrelid = p.conrelid AND k.attnum = u.num
+     WHERE p.conrelid = c.oid AND p.contype = 'p') AS "primaryKey",
+    (SELECT coalesce(json_agg(concat_ws(' ', pg_get_expr(pol.polqual, pol.polrelid), pg_get_expr(pol.polwithcheck, pol.polrelid))), '[]'::json)
+     FROM pg_policy pol WHERE pol.polrelid = c.oid) AS policies
+  FROM pg_class c
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE c.relkind IN ('r', 'p')
+    AND n.nspname NOT IN ('pg_catalog', 'information_schema', 'harbour_runtime')
+    AND n.nspname NOT LIKE 'pg\_toast%' AND n.nspname NOT LIKE 'pg\_temp%'
+) t;
+`;
+/** A policy that decides rows by the signed-in identity, and the column it decides them on. */
+const OWNER_SCOPE = /([A-Za-z_][A-Za-z0-9_]*)\s*(?:\)|::[a-z ]+)*\s*=\s*current_setting\('harbour\.user_(?:id|email)'/i;
+const IDENTITY = /current_setting\('harbour\.user_(?:id|email)'/i;
+/**
+ * The app's tables as the database holds them, or `undefined` when the database
+ * did not answer. `undefined` is not "no tables": nothing is generated from, or
+ * removed because of, a schema Harbour could not read — deleting an app's
+ * retained checks on a failed query would be the worst possible reading of it.
+ */
+export async function readAppSchema(source, root) {
+    const result = await source.psql(CATALOG_SQL, ["-At"]);
+    const text = result.stdout.trim();
+    if (result.code !== 0 || !text.startsWith("["))
+        return undefined;
+    let catalog;
+    try {
+        catalog = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const migrations = await migrationTexts(root);
+    const schema = new Map();
+    for (const table of catalog) {
+        schema.set(table.name, {
+            columns: table.columns.map(column => ({
+                name: column.name,
+                type: columnType(column.base, column.category),
+                declaredType: column.type,
+                notNull: column.notnull,
+                hasDefault: column.default !== null,
+                generated: column.generated,
+                identityDefault: IDENTITY.test(column.default ?? ""),
+                references: column.fk,
+                checks: column.checks
+            })),
+            primaryKey: table.primaryKey,
+            ownerScoped: table.policies.some(policy => IDENTITY.test(policy)),
+            ownerColumn: table.policies.map(policy => OWNER_SCOPE.exec(policy)?.[1]).find(Boolean),
+            file: createdIn(table.name, migrations)
+        });
+    }
+    return schema;
+}
+/**
+ * Postgres has already reduced every declared spelling to one base type name
+ * (`character varying` to `varchar`, `double precision` to `float8`, `BIGSERIAL`
+ * to `int8` with a nextval default), so this is a lookup rather than a parse.
+ */
+function columnType(base, category) {
+    if (category === "A")
+        return "array";
+    switch (base) {
+        case "text":
+        case "varchar":
+        case "bpchar":
+        case "char":
+        case "citext":
+        case "name": return "text";
+        case "uuid": return "uuid";
+        case "bool": return "boolean";
+        case "int2":
+        case "int4":
+        case "int8": return "integer";
+        case "numeric":
+        case "float4":
+        case "float8":
+        case "money": return "number";
+        case "timestamptz":
+        case "timestamp": return "timestamptz";
+        case "date": return "date";
+        case "time":
+        case "timetz": return "time";
+        case "json":
+        case "jsonb": return "json";
+        default: return "unknown";
+    }
+}
+async function migrationTexts(root) {
+    const directory = join(root, "migrations");
+    const names = (await readdir(directory).catch(() => [])).filter(name => name.endsWith(".sql")).sort();
+    return Promise.all(names.map(async (name) => ({ name: `migrations/${name}`, text: await readFile(join(directory, name), "utf8").catch(() => "") })));
+}
+/** Which file created a table: the only question the catalog cannot answer, so the only one still asked of the SQL text. */
+function createdIn(table, migrations) {
+    const pattern = new RegExp(String.raw `create\s+table\b[^;]*\b${table}\b`, "i");
+    return migrations.find(migration => pattern.test(migration.text))?.name ?? "migrations/";
+}
+// ---- CHECK constraints ----------------------------------------------------------
+//
+// `pg_get_constraintdef` deparses, so these read one normal form rather than
+// everything an author might have typed: `BETWEEN a AND b` has already become
+// `>= a AND <= b`, `IN (…)` has become `= ANY (ARRAY[…])`, and each operand
+// carries its cast. Only the shapes a value has to satisfy to be accepted are
+// read; anything else is left alone, and a value the database rejects surfaces
+// as a failing journey under `harbour check` in seconds rather than in the
+// pipeline minutes later.
+/** `char_length(col) >= n`, `length(col) <= n` — including the `((col)::text)` spelling a deparse gives a varchar. */
+export function textLengthBounds(checks, column) {
+    let min = 1;
+    let max = 500;
+    const pattern = new RegExp(String.raw `(?:char_length|length|octet_length)\([^<>=]*\b${column}\b[^<>=]*(<=|<|>=|>|=)\s*(\d+)`, "gi");
+    for (const check of checks)
+        for (const match of check.matchAll(pattern)) {
+            const value = Number(match[2]);
+            if (match[1] === "<=" || match[1] === "=")
+                max = Math.min(max, value);
+            else if (match[1] === "<")
+                max = Math.min(max, value - 1);
+            else if (match[1] === ">=")
+                min = Math.max(min, value);
+            else
+                min = Math.max(min, value + 1);
+        }
+    return { min, max: Math.max(max, min) };
+}
+/** `col = ANY (ARRAY['a'::text, 'b'::text])`: the closed set a value must come from. */
+export function allowedLiterals(checks, column) {
+    for (const check of checks) {
+        const list = new RegExp(String.raw `\b${column}\b[^=]*=\s*ANY\s*[\s(]*ARRAY\[([^\]]*)\]`, "i").exec(check);
+        const values = [...(list?.[1] ?? "").matchAll(/'((?:[^']|'')*)'/g)].map(match => match[1].replace(/''/g, "'"));
+        if (values.length)
+            return values;
+    }
+    return [];
+}
+/** The smallest number `col > n` / `col >= n` accepts. */
+export function numericMinimum(checks, column) {
+    let minimum = 1;
+    for (const check of checks) {
+        const comparison = new RegExp(String.raw `\b${column}\b[^<>=]*(>=|>)\s*(-?\d+(?:\.\d+)?)`, "i").exec(check);
+        if (!comparison)
+            continue;
+        const value = Number(comparison[2]);
+        minimum = Math.max(minimum, comparison[1] === ">" ? value + 1 : value);
+    }
+    return minimum;
+}

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

@@ -1,7 +1,9 @@
 import { readFile, readdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { readAppSchema } from "./app-schema.js";
 import { loadDatabaseGate } from "./database-gate.js";
 import { CoverageLedger, capabilityCallSurface, createCoverageProxy, declaredCapabilities, flowDetail, missingFlowOperations, orphanedChecks, sourceTableVerbs } from "./flow-coverage.js";
+import { describeRetainedChecks, syncRetainedChecks } from "./retained-checks.js";
 import { CliError } from "./output.js";
 import { DEPENDENT_READ_OPERATIONS, READ_OPERATIONS, kitPaths, readDeclaration, readKitLock, resourceNames, sourceDigest } from "./kit.js";
 import { LOCAL, LocalRuntime, identityEnvironment, runCommand, runningOrigin } from "./local-runtime.js";
@@ -11,10 +13,6 @@ export async function runChecks(root, options) {
     const { output, run, bundle } = options;
     const checks = [];
     const record = (name, status, detail) => { checks.push({ name, status, ...(detail ? { detail } : {}) }); output(`${status === "pass" ? "ok  " : status === "fail" ? "FAIL" : "skip"} ${name}${detail ? ` — ${indentLines(detail)}` : ""}`); };
-    const source = await sourceDigest(root);
-    const previous = await readReport(root);
-    if (previous && previous.sourceDigest !== source.digest)
-        output("Source changed since the last report; the previous report is no longer valid.");
     const declaration = await readDeclaration(root);
     record("declaration", declaration.errors.length ? "fail" : "pass", declaration.errors[0]);
     let lockDetail;
@@ -25,10 +23,16 @@ export async function runChecks(root, options) {
     const build = await run("npm", ["run", "build"], { cwd: root, quiet: true });
     record("build", build.code === 0 ? "pass" : "fail", build.code === 0 ? undefined : lastLines(build.stderr || build.stdout));
     const throwaway = LocalRuntime.forCheck(root, run);
+    let schema;
     try {
         await throwaway.writeCheckFiles(bundle);
         await throwaway.up();
         const applied = await throwaway.migrate();
+        // The app's own tables, as the database holds them once those files have
+        // replayed. This is the only window in which that database exists, and
+        // reading it here is what lets `.harbour/checks/` be generated from the
+        // schema the app will really run against rather than from the SQL text.
+        schema = await readAppSchema(throwaway, root);
         record("migrations", "pass", `${applied.length} file(s) applied to a disposable database`);
         // The pipeline's database gate, on the database those files just built:
         // the same script the in-loop probe runs after its replay, so the defect
@@ -48,6 +52,27 @@ export async function runChecks(root, options) {
     finally {
         await throwaway.down();
     }
+    // `.harbour/checks/` is generated from what the app declares — the tables the
+    // database above holds, the SDK namespaces its own code calls — before
+    // anything reads it, so a check for a feature the app dropped cannot survive a
+    // single `harbour check`, and a feature it added arrives with its journey.
+    // This is not one of the gates: it writes files and reports what it did, and
+    // `flow` below still decides. Files Harbour did not write, and generated files
+    // the builder has edited, are never touched — and when the database did not
+    // answer, nothing is touched at all.
+    if (schema)
+        for (const line of describeRetainedChecks(await syncRetainedChecks(root, schema)))
+            output(line);
+    else
+        output(".harbour/checks/ was left as it is: the app's tables could not be read from the disposable database, so there was nothing to generate from.");
+    // After generation, because `.harbour/checks/*.mjs` is part of the deployed
+    // tree (kit.ts `sourceDigest`): the report has to pin the tree the journeys
+    // below actually run against, or `harbour productionise` would refuse the very
+    // tree this check just passed as CHECKS_STALE.
+    const source = await sourceDigest(root);
+    const previous = await readReport(root);
+    if (previous && previous.sourceDigest !== source.digest)
+        output("Source changed since the last report; the previous report is no longer valid.");
     const origin = await (options.localOrigin ?? (() => runningOrigin(root)))();
     const journeys = (await readdir(kitPaths(root).checks).catch(() => [])).filter(name => /\.(mjs|js|cjs)$/.test(name)).sort();
     if (!journeys.length) {

package/dist/packages/harbour-cli/src/flow-coverage.js

@@ -1,7 +1,7 @@
 import { createServer, request as httpRequest } from "node:http";
 import { connect } from "node:net";
 import { readdir, readFile } from "node:fs/promises";
-import { extname, join } from "node:path";
+import { extname, join, relative, sep } from "node:path";
 /**
  * The pipeline's operation-coverage gate, run locally.
  *
@@ -108,11 +108,15 @@ async function sourceFiles(root) {
     return found.sort();
 }
 /**
- * Every `<table> <verb>` the browser code performs. The verb chain is what
- * follows THIS `.from(...)` up to the end of its statement or the next
- * `.from(` — never a later chain's verbs.
+ * Every `<table> <verb>` the browser code performs, with the files performing
+ * it. The verb chain is what follows THIS `.from(...)` up to the end of its
+ * statement or the next `.from(` — never a later chain's verbs.
+ *
+ * This reading is what the gate demands evidence for, so `retained-checks.ts`
+ * generates from exactly it: a generated journey can then only ever cover what
+ * the gate asks about, in both directions, with no template in between.
  */
-export async function sourceTableVerbs(root) {
+export async function sourceTableUsage(root) {
     const inventory = new Map();
     for (const path of await sourceFiles(root)) {
         const text = await readFile(path, "utf8");
@@ -129,38 +133,58 @@ export async function sourceTableVerbs(root) {
                 tail = tail.slice(0, next);
             tail = tail.slice(0, 200);
             const table = match[1];
-            const verbs = inventory.get(table) ?? new Set();
+            const usage = inventory.get(table) ?? { verbs: new Set(), files: [] };
             for (const verb of tail.matchAll(VERB_CALL))
-                verbs.add(verb[1]);
-            inventory.set(table, verbs);
+                usage.verbs.add(verb[1]);
+            const file = appPath(root, path);
+            if (!usage.files.includes(file))
+                usage.files.push(file);
+            inventory.set(table, usage);
         }
     }
     return inventory;
 }
+/** `<table> <verb>` alone, as the coverage gate compares it. */
+export async function sourceTableVerbs(root) {
+    return new Map([...await sourceTableUsage(root)].map(([table, usage]) => [table, usage.verbs]));
+}
 /**
- * The capabilities the kit lane declares for this app: a namespace called as
- * `<client>.<namespace>.<method>(` on an identifier bound to `createClient()`.
- * TypeScript type arguments may sit between the method and its call.
+ * The capabilities the kit lane declares for this app, with the files declaring
+ * them: a namespace called as `<client>.<namespace>.<method>(` on an identifier
+ * bound to `createClient()`. TypeScript type arguments may sit between the
+ * method and its call.
  */
-export async function declaredCapabilities(root) {
+export async function capabilityUsage(root) {
     const files = await sourceFiles(root);
     const texts = await Promise.all(files.map(path => readFile(path, "utf8").catch(() => "")));
     const clients = new Set();
     for (const text of texts)
         for (const match of text.matchAll(CLIENT_BINDING))
             clients.add(match[1]);
-    const used = new Set();
+    const used = new Map();
     if (!clients.size)
         return used;
     const namespaces = SDK_CAPABILITIES.join("|");
     for (const client of clients) {
         const call = new RegExp(`\\b${client}\\s*\\.\\s*(${namespaces})\\s*\\.\\s*[A-Za-z_$][A-Za-z0-9_$]*\\s*(?:<[^<>()]*>\\s*)?\\(`, "g");
-        for (const text of texts)
-            for (const match of text.matchAll(call))
-                used.add(match[1]);
+        for (const [index, text] of texts.entries()) {
+            const file = appPath(root, files[index]);
+            for (const match of text.matchAll(call)) {
+                const seen = used.get(match[1]) ?? [];
+                if (!seen.includes(file))
+                    seen.push(file);
+                used.set(match[1], seen);
+            }
+        }
     }
     return used;
 }
+/** The capability names alone, as the coverage gate compares them. */
+export async function declaredCapabilities(root) {
+    return new Set((await capabilityUsage(root)).keys());
+}
+/** A source file as the app itself names it: relative to the root, `/`-separated on every platform. */
+const appPath = (root, path) => relative(root, path).split(sep).join("/");
 /**
  * Every capability namespace the app's own source calls a method on, whatever
  * object the call is made on: `harbour.files.list(`, `client().files.list(`,
@@ -184,13 +208,15 @@ export async function declaredCapabilities(root) {
  */
 export async function capabilityCallSurface(root) {
     const surface = new Set();
-    for (const path of await sourceFiles(root)) {
-        const text = await readFile(path, "utf8").catch(() => "");
-        for (const match of text.matchAll(CAPABILITY_CALL))
-            surface.add(match[1]);
-    }
+    for (const path of await sourceFiles(root))
+        for (const capability of capabilitiesCalled(await readFile(path, "utf8").catch(() => "")))
+            surface.add(capability);
     return surface;
 }
+/** The same reading of one piece of text, so a retained check is judged by exactly the rule the app's own source is read with (retained-checks.ts). */
+export function capabilitiesCalled(text) {
+    return new Set([...text.matchAll(CAPABILITY_CALL)].map(match => match[1]));
+}
 /**
  * The gateway's own path -> capability map (appgateway/gateway.go
  * `capabilityForRequest`). Every one of these paths is resolved against the

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

@@ -261,8 +261,9 @@ export class LocalRuntime {
         const result = await this.psql(sql);
         return result.code === 0 ? [] : gateViolations(result.stderr);
     }
-    psql(sql) {
-        return this.compose(["exec", "-T", "postgres", "psql", "-v", "ON_ERROR_STOP=1", "-U", LOCAL.dbUser, "-d", LOCAL.database], { stdin: sql, quiet: true });
+    /** 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 });
     }
     /**
      * Applies the platform's realtime outbox migration the gateway generated

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

@@ -0,0 +1,396 @@
+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 { kitPaths } from "./kit.js";
+/**
+ * Retained checks, generated from what the app declares.
+ *
+ * `.harbour/checks/` used to be shipped by `harbour init` as three fixed files
+ * written for the starter's own notes/files example. The first thing a builder
+ * does is replace that example, and the checks stayed — exercising tables and a
+ * capability the app no longer had, which is exactly what the pipeline's `flow`
+ * gate refuses (`flow.check-failed`). It cost two real builder runs on one day:
+ * a todo app that dropped the files UI and renamed notes to todos failed on
+ * `files-journey.mjs` ("application capability is not enabled") and on
+ * `notes-cross-user.mjs` ("relation … does not exist").
+ *
+ * So there are no templates. The two readings the `flow` gate already makes of
+ * the app's own code — `sourceTableUsage` (every `<table> <verb>` the browser
+ * code performs) and `capabilityUsage` (every SDK namespace it calls) — decide
+ * which checks exist, and the app's own database, the one `harbour check` has
+ * just replayed `migrations/*.sql` into, supplies the row a journey writes. A
+ * check exists for each capability the app actually has and for none it does
+ * not, by construction rather than by guidance.
+ *
+ * Three rules keep that safe:
+ *
+ *   - **Harbour only manages what Harbour wrote.** A generated file carries a
+ *     digest of its own body on its first line. `harbour check` rewrites and
+ *     deletes a file whose digest still matches; the moment a builder edits one
+ *     — or writes their own — it is theirs, and Harbour reports it instead of
+ *     touching it. That was #456's lesson: the remediation we hand out must
+ *     never overwrite the app.
+ *   - **Harbour never writes a check its own gate would refuse.** The `flow`
+ *     gate refuses a retained check exercising a capability no code in the app
+ *     calls (#469), reading that surface with `capabilityCallSurface`; nothing
+ *     is generated for a capability outside it.
+ *   - **The `flow` gate is untouched.** Generation removes the drift; the gate
+ *     still decides. Surface Harbour cannot write a journey for is named with
+ *     the reason, and `flow` fails exactly as it did before.
+ */
+/** 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 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);
+    const created = [];
+    const updated = [];
+    for (const check of plan.write) {
+        const absolute = join(root, check.path);
+        const current = await readFile(absolute, "utf8").catch(() => undefined);
+        if (current === check.content)
+            continue;
+        await mkdir(kitPaths(root).checks, { recursive: true });
+        await writeFile(absolute, check.content);
+        (current === undefined ? created : updated).push(check.path);
+    }
+    for (const path of plan.remove)
+        await rm(join(root, path), { force: true });
+    return { created, updated, removed: [...plan.remove], adopted: plan.adopted, blocked: plan.blocked, orphaned: plan.orphaned };
+}
+/** One line per decision, for `harbour check`'s output. */
+export function describeRetainedChecks(result) {
+    return [
+        ...result.created.map(path => `generated ${path}`),
+        ...result.updated.map(path => `regenerated ${path}`),
+        ...result.removed.map(path => `removed ${path} — the app's code no longer does what it exercised, and the pipeline's flow gate refuses a check that does`),
+        ...result.orphaned.map(detail => `keeping ${detail}`),
+        ...result.blocked.map(detail => `no check generated for ${detail}`)
+    ];
+}
+/** 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)]);
+    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. */
+    const add = (capability, name, content) => {
+        if (!surface.has(capability))
+            return;
+        planned.add(name);
+        plan.write.push({ path: `.harbour/checks/${name}`, content });
+    };
+    for (const [table, usage] of [...tables].sort(([first], [second]) => first.localeCompare(second))) {
+        const verbs = VERB_ORDER.filter(verb => usage.verbs.has(verb));
+        const declared = schema.get(table);
+        // A check the builder owns covering every verb is the coverage, and one acting as the
+        // 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"));
+        if (journeyCovered && (crossUserCovered || !declared?.ownerScoped))
+            continue;
+        const reason = (detail) => plan.blocked.push(`\`${table}\` (${verbs.join(", ")}), which ${usage.files.join(", ")} queries: ${detail}`);
+        if (!declared) {
+            reason("no table of that name exists once the app's migrations have replayed, so Harbour cannot know what a row of it looks like");
+            continue;
+        }
+        const shape = verbs.some(verb => verb !== "select") ? rowShape(declared, verbs.includes("update")) : undefined;
+        if (shape && "blocked" in shape) {
+            reason(shape.blocked);
+            continue;
+        }
+        if (!journeyCovered)
+            add("data", fileName(table, "journey"), dataJourney(table, verbs, declared, usage.files, shape));
+        if (declared.ownerScoped && shape && !crossUserCovered)
+            add("data", fileName(table, "cross-user"), crossUserCheck(table, declared, shape, usage.files));
+    }
+    for (const capability of COVERED_CAPABILITIES) {
+        const files = capabilities.get(capability);
+        if (!files || capability === "data")
+            continue;
+        if (adopted.some(check => capabilitiesCalled(check.text).has(capability)))
+            continue;
+        const generic = capability === "files" ? filesJourney(files) : capability === "telemetry" ? telemetryJourney(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`);
+            continue;
+        }
+        add(capability, `${capability}-journey.mjs`, generic);
+    }
+    for (const check of existing) {
+        if (check.pristine) {
+            if (!planned.has(check.name))
+                plan.remove.push(check.path);
+            continue;
+        }
+        const stale = staleSurface(check.text, tables, capabilities);
+        if (stale)
+            plan.orphaned.push(`${check.path} — Harbour did not write this file, so it is left alone, but it exercises ${stale}; delete it or restore the feature, or the pipeline's flow gate refuses the app`);
+    }
+    plan.write.sort((first, second) => first.path.localeCompare(second.path));
+    plan.remove.sort();
+    return plan;
+}
+// ---- Generated files ------------------------------------------------------------
+/** The paragraph every generated check carries: what wrote it, what maintains it, and what an edit means. */
+function stewardship(sources, uuid = false) {
+    return [
+        "//",
+        `// Generated by Harbour from ${sources.join(" and ")}, and kept in step by`,
+        "// `harbour check`: rewritten when the app's schema or the operations it performs",
+        "// change, and deleted when the app stops performing them. Edit this file and",
+        "// Harbour stops managing it — your version is kept from then on, and keeping it",
+        "// honest becomes yours: the deployment pipeline replays `.harbour/checks/` against",
+        "// a real App Gateway and refuses the app (`flow.check-failed`) when a check",
+        "// exercises something the code no longer does, so DELETE THIS FILE in the same",
+        "// edit that removes the feature it covers.",
+        "",
+        ...(uuid ? ["import { randomUUID } from \"node:crypto\";"] : []),
+        "import assert from \"node:assert/strict\";",
+        "",
+        "const appUrl = process.env.HARBOUR_APP_URL;",
+        "assert.ok(appUrl, \"HARBOUR_APP_URL is required\");",
+        "const sdk = await import(process.env.HARBOUR_SDK_MODULE ?? \"@harbour/app-sdk\");"
+    ];
+}
+/** 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.",
+    "const harbour = sdk.createClient({ baseUrl: appUrl });",
+    "",
+    "const user = await harbour.identity.current();",
+    "assert.ok(user && user.email, \"identity/current must return the signed-in user\");"
+];
+/** A table's journey: the write steps when the app writes to it, a plain read when it only reads. */
+function dataJourney(table, verbs, schema, sources, row) {
+    const body = [
+        `// Retained journey for the \`${table}\` table: the signed-in identity can`,
+        `// ${sentence(verbs)} a row through the running app (HARBOUR_APP_URL) — the operations`,
+        `// ${sources.join(", ")} performs on this table. Runs under \`harbour check\` while`,
+        "// `harbour dev` is up, and in the deployment pipeline's retained-check container.",
+        ...stewardship([schema.file, ...sources], row?.uuid ?? false),
+        ...SIGNED_IN,
+        ...(row ? writeSteps(table, verbs, row) : [
+            "",
+            `const { data: rows } = await harbour.data.from("${table}").select("*").limit(1);`,
+            `assert.ok(Array.isArray(rows), "${table}: the signed-in identity can read the table this app reads");`
+        ])
+    ];
+    return sign(`${body.join("\n")}\n`);
+}
+function writeSteps(table, verbs, row) {
+    const from = `harbour.data.from("${table}")`;
+    const at = `.eq("${row.locator}", row.${row.locator})`;
+    const steps = [
+        "",
+        `const markerValue = ${row.markerExpression};`,
+        `await ${from}.insert({ ${row.values.join(", ")} });`,
+        `const { data: rows } = await ${from}.select("*").eq("${row.marker.name}", markerValue);`,
+        `assert.equal(rows.length, 1, "the inserted ${table} row is readable by its owner");`,
+        "const row = rows[0];"
+    ];
+    if (verbs.includes("upsert"))
+        steps.push("", `await ${from}.upsert({ ...row, ${row.marker.name}: markerValue });`, `const { data: upserted } = await ${from}.select("*").eq("${row.marker.name}", markerValue);`, `assert.ok(upserted.length >= 1, "the upserted ${table} row is readable by its owner");`);
+    if (verbs.includes("update") && row.update)
+        steps.push("", `await ${from}.update({ ${row.update.column.name}: ${row.update.expression} })${at};`, `const { data: updated } = await ${from}.select("*")${at};`, `assert.deepEqual(updated[0].${row.update.column.name}, ${row.update.expression}, "the ${table} row is updated for its owner");`);
+    if (verbs.includes("delete"))
+        steps.push("", `await ${from}.delete()${at};`, `const { data: remaining } = await ${from}.select("*")${at};`, `assert.equal(remaining.length, 0, "the ${table} row is deleted");`);
+    return steps;
+}
+function crossUserCheck(table, schema, row, sources) {
+    const mutated = row.update ? { column: row.update.column.name, value: row.update.expression } : { column: row.marker.name, value: row.markerExpression };
+    const body = [
+        "// Cross-user check: a second signed-in person cannot read, update or delete the first",
+        `// person's \`${table}\` row through the running app (HARBOUR_APP_URL). The deployment`,
+        "// pipeline's write probe makes exactly these three assertions, with a second identity,",
+        `// against every owner-scoped table, and \`${table}\` is one: ${schema.file} scopes its rows`,
+        `// 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.",
+        "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 me = await owner.identity.current();",
+        "const them = await other.identity.current();",
+        "assert.ok(me && them && me.id !== them.id, \"the two signed-in identities must be different people\");",
+        "",
+        `const markerValue = ${row.markerExpression};`,
+        `await owner.data.from("${table}").insert({ ${row.values.join(", ")} });`,
+        `const { data: mine } = await owner.data.from("${table}").select("*").eq("${row.marker.name}", markerValue);`,
+        `assert.equal(mine.length, 1, "the owner reads the ${table} row back");`,
+        "const row = mine[0];",
+        "",
+        "// 1. SELECT by key as the second person: no row.",
+        `const { data: seen } = await other.data.from("${table}").select("*").eq("${row.locator}", row.${row.locator});`,
+        `assert.equal(seen.length, 0, "${table}: a second signed-in user can read another user's row — the owner policy does not isolate users");`,
+        "",
+        "// 2. UPDATE and 3. DELETE by key as the second person: refused (403) or no row affected.",
+        "const denied = async (verb, operation) => {",
+        "  let affected;",
+        "  try { affected = (await operation()).data ?? []; }",
+        "  catch (error) { if (error?.category === \"FORBIDDEN\") return; throw error; }",
+        `  assert.equal(affected.length, 0, \`${table} \${verb}: a second user mutated another user's row despite an owner-scoped source policy\`);`,
+        "};",
+        `await denied("UPDATE", () => other.data.from("${table}").update({ ${mutated.column}: ${mutated.value} }).eq("${row.locator}", row.${row.locator}));`,
+        `await denied("DELETE", () => other.data.from("${table}").delete().eq("${row.locator}", row.${row.locator}));`,
+        `const { data: after } = await owner.data.from("${table}").select("*").eq("${row.locator}", row.${row.locator});`,
+        `assert.equal(after.length, 1, "the owner's ${table} row still exists after the second user's attempts");`,
+        `assert.deepEqual(after[0].${mutated.column}, row.${mutated.column}, "the owner's ${table} row is unchanged after the second user's attempts");`,
+        `await owner.data.from("${table}").delete().eq("${row.locator}", row.${row.locator});`
+    ];
+    return sign(`${body.join("\n")}\n`);
+}
+function filesJourney(sources) {
+    const body = [
+        "// Retained journey for the app's private files: the signed-in identity can upload a",
+        "// file and list it back through the running app (HARBOUR_APP_URL) — the operations",
+        `// ${sources.join(", ")} performs through \`harbour.files.*\`. The deployment pipeline`,
+        "// refuses an app whose checks never exercise a capability its own code uses, so this",
+        "// runs under `harbour check` while `harbour dev` is up, and in the pipeline's container.",
+        ...stewardship(sources),
+        ...SIGNED_IN,
+        "",
+        "const name = `harbour-journey-${Date.now()}.txt`;",
+        "await harbour.files.upload(`private/${name}`, new Blob([\"harbour journey check\\n\"], { type: \"text/plain\" }));",
+        "const listed = await harbour.files.list(\"private/\");",
+        "assert.ok(Array.isArray(listed), \"files.list must return a list\");",
+        "const found = listed.some(entry => String(typeof entry === \"string\" ? entry : entry?.path ?? entry?.name ?? \"\").endsWith(name));",
+        "assert.ok(found, `the uploaded file is listed back to its owner (looking for ${name})`);"
+    ];
+    return sign(`${body.join("\n")}\n`);
+}
+function telemetryJourney(sources) {
+    const body = [
+        "// Retained journey for the app's telemetry: one event reaches the gateway through the",
+        `// running app (HARBOUR_APP_URL) — the capability ${sources.join(", ")} uses through`,
+        "// `harbour.telemetry.*`. The deployment pipeline refuses an app whose checks never",
+        "// exercise a capability its own code uses, so this runs under `harbour check` while",
+        "// `harbour dev` is up, and in the pipeline's retained-check container.",
+        ...stewardship(sources),
+        ...SIGNED_IN,
+        "",
+        "// `track` resolves with nothing and throws on a refusal, so reaching the next line is the assertion.",
+        "await harbour.telemetry.track(\"harbour_retained_check\", { source: \"telemetry-journey\" });"
+    ];
+    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) {
+    const writable = schema.columns.filter(column => !column.generated && !column.identityDefault);
+    const required = writable.filter(column => column.notNull && !column.hasDefault);
+    const unwritable = required.find(column => column.references) ?? required.find(column => !fillExpression(column));
+    if (unwritable)
+        return { blocked: `its \`${unwritable.name} ${unwritable.declaredType}\` column ${unwritable.references ? "references another table, so a row cannot be written without inventing its parent" : "has a type Harbour cannot invent a value for"}` };
+    const marker = writable.find(column => isMarker(column) && column.notNull && !column.hasDefault) ?? writable.find(isMarker);
+    if (!marker)
+        return { blocked: "it has no free text or number column a check could write a unique value into and find the row by" };
+    const markerExpression = marker.type === "text" ? textMarker(marker) : "Date.now() % 2000000000";
+    if (!markerExpression)
+        return { blocked: `\`${marker.name}\` is the only column a check could find a row by, and its CHECK constraint leaves no room for a unique value` };
+    const locator = schema.primaryKey.length === 1 && schema.primaryKey[0] !== marker.name ? schema.primaryKey[0] : marker.name;
+    const fill = required.filter(column => column.name !== marker.name).map(column => `${column.name}: ${fillExpression(column)}`);
+    const update = needsUpdate ? updateStep(writable, marker, locator) : undefined;
+    if (needsUpdate && !update)
+        return { blocked: "the app updates it, but every column Harbour could change is the one the check finds the row by" };
+    return { values: [`${marker.name}: markerValue`, ...fill], marker, markerExpression, locator, uuid: fill.some(value => value.includes("randomUUID(")), update };
+}
+/** The column a journey changes, and what it changes it to: a boolean is flipped, a closed set moves to its other value, free text gets a fixed one. */
+function updateStep(writable, marker, locator) {
+    const candidates = writable.filter(column => column.name !== locator && column.name !== marker.name);
+    const flag = candidates.find(column => column.type === "boolean");
+    if (flag)
+        return { column: flag, expression: `!row.${flag.name}` };
+    for (const column of candidates) {
+        const literals = allowedLiterals(column.checks, column.name);
+        if (literals.length >= 2)
+            return { column, expression: JSON.stringify(literals[1]) };
+        if (column.type !== "text" || literals.length)
+            continue;
+        const { min, max } = textLengthBounds(column.checks, column.name);
+        if (max < 21 || min > 21)
+            continue;
+        return { column, expression: "\"harbour check updated\"" };
+    }
+    return undefined;
+}
+/** A column a check can write a unique value into and then filter on. */
+const isMarker = (column) => (column.type === "text" || column.type === "integer" || column.type === "number") && !column.references && !allowedLiterals(column.checks, column.name).length;
+/** A unique marker satisfying the column's own length constraints, or `undefined` when they leave no room for one. */
+function textMarker(column) {
+    const { min, max } = textLengthBounds(column.checks, column.name);
+    const [expression, length] = max >= 27 ? ["`harbour check ${Date.now()}`", 27] : max >= 13 ? ["String(Date.now())", 13] : max >= 6 ? [`String(Date.now()).slice(-${max})`, max] : [undefined, 0];
+    if (!expression)
+        return undefined;
+    return min > length ? `${expression}.padEnd(${min}, "x")` : expression;
+}
+/** A value for a column a write must supply, or `undefined` when nothing can be invented for its type. */
+function fillExpression(column) {
+    const literals = allowedLiterals(column.checks, column.name);
+    if (literals.length)
+        return JSON.stringify(literals[0]);
+    switch (column.type) {
+        case "text": {
+            const { min, max } = textLengthBounds(column.checks, column.name);
+            return JSON.stringify("harbour check".slice(0, max).padEnd(Math.min(min, max), "x"));
+        }
+        case "uuid": return "randomUUID()";
+        case "integer": return String(Math.ceil(numericMinimum(column.checks, column.name)));
+        case "number": return String(numericMinimum(column.checks, column.name));
+        case "boolean": return "false";
+        case "timestamptz": return "new Date().toISOString()";
+        case "date": return "new Date().toISOString().slice(0, 10)";
+        case "time": return "\"12:00:00\"";
+        case "json": return "{}";
+        case "array": return "[]";
+        default: return undefined;
+    }
+}
+async function readChecks(root) {
+    const directory = kitPaths(root).checks;
+    const names = (await readdir(directory).catch(() => [])).filter(name => /\.(mjs|js|cjs)$/.test(name)).sort();
+    return Promise.all(names.map(async (name) => {
+        const text = await readFile(join(directory, name), "utf8").catch(() => "");
+        return { name, path: `.harbour/checks/${name}`, text, pristine: isPristine(text) };
+    }));
+}
+/** What an adopted check exercises that the app's own code no longer does, in the `flow` gate's terms. */
+function staleSurface(text, tables, capabilities) {
+    for (const match of text.matchAll(/\.from\(\s*["'`]([A-Za-z0-9_]+)["'`]\s*\)/g))
+        if (!tables.has(match[1]))
+            return `the \`${match[1]}\` table, which no source file queries`;
+    for (const capability of capabilitiesCalled(text))
+        if (!capabilities.has(capability))
+            return `the \`${capability}\` capability, which no source file uses`;
+    return undefined;
+}
+/** `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("");
+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`;
+// ---- Ownership ------------------------------------------------------------------
+const digest = (body) => createHash("sha256").update(body).digest("hex").slice(0, 16);
+const sign = (body) => `${GENERATED_PREFIX}${digest(body)}\n${body}`;
+/** True only for a file Harbour wrote and nobody has edited since. */
+export function isPristine(text) {
+    if (!text.startsWith(GENERATED_PREFIX))
+        return false;
+    const end = text.indexOf("\n");
+    return end > 0 && text.slice(0, end).trim() === `${GENERATED_PREFIX}${digest(text.slice(end + 1))}`;
+}

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

@@ -28,8 +28,8 @@ export async function initKit(root, bundle, options = {}) {
         await writeFile(absolute, content);
         result.created.push(path);
     };
-    // The starter (its source, schema and retained checks) is created only when there is
-    // no app here yet; kit infrastructure is written on every path, including `--upgrade`.
+    // The starter (its source and schema) is created only when there is no app here
+    // yet; kit infrastructure is written on every path, including `--upgrade`.
     const appFiles = emptyDir ? starterFiles(bundle) : {};
     for (const [path, content] of Object.entries({ ...appFiles, ...kitFiles() }))
         await write(path, content);
@@ -99,8 +99,8 @@ export function managedBlock() {
         "- Every route needs a signed-in human by default; do not add public routes or wildcard exceptions to make something work.",
         "- No secrets, tokens, `.env` values or fetched company content in source. `.harbour/local/` is ignored and never committed; `.harbour/integrations.json` and `.harbour/kit.lock.json` are committed.",
         "- Schema changes are SQL files in `migrations/`, applied by `harbour dev` and `harbour check`. Every table: ENABLE ROW LEVEL SECURITY + a policy; GRANT every verb a policy allows to `harbour_app_gateway` and to no other role — `harbour check` runs the pipeline's database gate and names any table/policy/grant that breaks this, with the fix.",
-        "- `.harbour/checks/` holds the app's retained journeys: one per capability the app's own code uses (`harbour.data.*`, `harbour.files.*`, actions, realtime, telemetry), plus a cross-user denial per owner-scoped table. The pairing is two-way and the `flow` gate refuses the deploy in both directions, so an edit that changes what the app does changes its checks in the same edit. Start using a capability and it needs its own retained check, written in that edit. Stop using one — a deleted section, a dropped table, a feature the app no longer has — and its retained check must be deleted in that same edit, because `harbour check` and the deployment pipeline replay `.harbour/checks/` against a real App Gateway and refuse the app (`flow.check-failed: the candidate's own retained checks no longer pass`) when a check exercises something the code no longer does.",
-        "- The starter's pairing is: `notes-journey.mjs` + `notes-cross-user.mjs` with the `notes` table and the Notes section of `src/App.tsx`; `files-journey.mjs` with the \"Private files\" section, the only code that calls `harbour.files.*`. Replacing the notes table with the app's own means rewriting both notes checks for that table; removing the \"Private files\" section means deleting `.harbour/checks/files-journey.mjs` in that same edit. An inherited check for a feature the app replaced or dropped is the most common reason a first deploy is refused.",
+        "- `.harbour/checks/` holds the app's retained journeys: one per capability the app's own code uses (`harbour.data.*`, `harbour.files.*`, actions, realtime, telemetry), plus a cross-user denial per owner-scoped table. `harbour check` generates them from `migrations/` and the app's own source and deletes the ones the app no longer needs, so the way to keep them right is to run it in the same edit that changes the app — not to write or remove these files by hand. The pairing is two-way and the `flow` gate refuses the deploy in both directions. Start using a capability and it needs its own retained check: `harbour check` writes it, except for the ones it reports it cannot generate (`actions`, `realtime`), which you write yourself. Stop using one — a deleted section, a dropped table, a feature the app no longer has — and its retained check must be deleted in that same edit: `harbour check` deletes the ones it generated, and one you wrote or edited is yours to delete, because `harbour check` and the deployment pipeline replay `.harbour/checks/` against a real App Gateway and refuse the app (`flow.check-failed: the candidate's own retained checks no longer pass`) when a check exercises something the code no longer does.",
+        "- A generated check starts with a `// harbour:generated` line carrying a digest of its own body; that is how `harbour check` knows the file is still its to rewrite and remove. Edit one and it becomes yours: Harbour keeps your version, stops updating it and never deletes it, and keeping it honest is then your job. The starter's pairing is: `notes-journey.mjs` + `notes-cross-user.mjs` with the `notes` table and the Notes section of `src/App.tsx`; `files-journey.mjs` with the \"Private files\" section, the only code that calls `harbour.files.*`. Replace the notes table with the app's own, or remove the \"Private files\" section, and the next `harbour check` rewrites and deletes to match — `.harbour/checks/files-journey.mjs` goes with that section, and you delete it by hand in that same edit only if you have edited it. An inherited check for a feature the app replaced or dropped is the most common reason a first deploy is refused.",
         "- Commands: `harbour dev --app-root .` (local runtime), `harbour check --app-root .` (declaration, types, build, migrations + the pipeline's database gate, journeys), `harbour integrations request <connection> --reason <text> --app-root .`, `harbour integrations status --app-root .`, `harbour productionise --app-root .`. Company calls in `dev` use the account from `harbour login`; the local fixture user is only the app's identity.",
         "- Codex reads this AGENTS.md block; Claude Code also reads `.claude/skills/harbour-kit/SKILL.md`. The plain-English workflow (what to run when the person says \"run it\", \"check it\", \"ship it\") is in the user-level `isomorph` skill / `~/.codex/AGENTS.md` block installed by `harbour agent-setup`.",
         MANAGED_END
@@ -115,7 +115,7 @@ Follow the "Harbour development kit" block in CLAUDE.md / AGENTS.md. Workflow:
 
 1. \`harbour dev --app-root .\` starts Postgres, storage and one Harbour gateway (session identities, fixtures, realtime) plus Vite behind one loopback origin printed in the banner.
 2. Edit \`src/\` and \`migrations/\`. Use the SDK only. \`.harbour/integrations.json\` starts with no connections and gains one only when the app really calls a company system: declare it with only the operations the app calls, then request access (step 5). A declared connection the app does not call blocks every deploy until IT grants it; an undeclared one cannot be requested, so it never gets a grant. README.md has the worked Slack and warehouse examples — the file itself is strict JSON and cannot hold comments.
-3. Keep \`.harbour/checks/\` paired with the code, in the same edit that changes it: one retained journey per capability the app's own code uses, and none for a capability it no longer uses. A new feature needs a new check; a feature you delete or replace (a dropped table, a removed section) means deleting or rewriting its check right then. \`harbour check\` and the deployment pipeline replay these checks against a real App Gateway and refuse the app (\`flow.check-failed\`) in both directions — a capability no check exercises, and a check that exercises something the code no longer does.
+3. \`.harbour/checks/\` is generated, not written by hand: \`harbour check\` reads \`migrations/\` and \`src/\` and writes one retained journey per capability the app's own code uses (plus a cross-user denial per owner-scoped table), deleting the ones the app no longer needs — so run it in the same edit that changes the app instead of adding or deleting these files yourself. It reports anything it cannot generate (\`actions\`, \`realtime\`, a table with no migration) for you to write. Edit a generated check and it becomes yours: Harbour keeps it, stops managing it and never removes it, so deleting it when the feature goes is then your job. \`harbour check\` and the deployment pipeline replay these checks against a real App Gateway and refuse the app (\`flow.check-failed\`) in both directions — a capability no check exercises, and a check that exercises something the code no longer does.
 4. \`harbour check --app-root .\` before every hand-off; read \`.harbour/local/check-report.json\`. Real integrations are reported as not tested unless \`--integrations\` is passed (read operations only).
 5. \`harbour integrations request <connection> --reason "<why>" --app-root .\` asks IT for development access; pending is not ready.
 6. \`harbour productionise --app-root .\` saves and deploys the preview; \`harbour promote\` after the person has tested it.
@@ -141,28 +141,23 @@ function kitFiles() {
 }
 /**
  * The starter app itself: written only when `init` is creating one in an empty
- * directory. This includes the notes migration and the three retained checks —
- * they are the starter's own schema and journeys, not kit infrastructure, and
- * they exist so a fresh starter passes the pipeline's `flow` gate (one journey
- * per capability its UI declares, plus the cross-user denial). Writing them into
- * an app that has its own schema recreates a `notes` table it never had, and the
- * checks that query it then fail `flow` on the next deploy.
+ * directory. This includes the notes migration — the starter's own schema, not
+ * kit infrastructure. Writing it into an app that has its own schema recreates a
+ * `notes` table it never had, and a check that queries it then fails `flow` on
+ * the next deploy (#456).
+ *
+ * The retained checks are deliberately not here, and not written by `init` at
+ * all. `harbour check` generates them from this schema — read back out of the
+ * database it replays the migrations into — and from this source, so "one
+ * journey per capability the UI declares, plus the cross-user denial per
+ * owner-scoped table" is a property of the generator rather than three files
+ * that have to be kept in step with `src/App.tsx` by hand. `init` has no
+ * database and so invents nothing: `.harbour/checks/` arrives with the first
+ * `harbour check`, which is also the command that keeps it right afterwards.
  */
 function starterFiles(bundle) {
     return {
         "migrations/0001_notes.sql": MIGRATION,
-        // Exactly one retained check per capability the starter's UI uses, and none for a
-        // capability it does not: the flow gate runs both ways — it refuses an app whose
-        // checks never exercise a declared capability, and it refuses an app whose checks
-        // no longer pass because the code behind them is gone. The starter's own UI still
-        // calls `harbour.files.*` in its "Private files" section, so `files-journey.mjs`
-        // belongs here; an app that drops that section deletes the check with it (the
-        // pairing is stated in the generated App.tsx, README.md and the CLAUDE.md block).
-        ".harbour/checks/notes-journey.mjs": JOURNEY_CHECK,
-        ".harbour/checks/files-journey.mjs": FILES_JOURNEY_CHECK,
-        // The pipeline's cross-user denial, run locally: the last gate class that
-        // used to exist only in CodeBuild.
-        ".harbour/checks/notes-cross-user.mjs": CROSS_USER_CHECK,
         "package.json": `${JSON.stringify({
             name: "harbour-app", private: true, version: "0.1.0", type: "module",
             scripts: { dev: "vite", build: "tsc --noEmit && vite build", preview: "vite preview" },
@@ -188,10 +183,12 @@ Created by \`harbour init\`. Run \`harbour dev --app-root .\` and open the print
 
 \`.harbour/checks/\` holds one journey per capability the app uses (\`notes-journey.mjs\` for data, \`files-journey.mjs\` for files) and \`notes-cross-user.mjs\`, which proves a second signed-in person cannot read, update or delete another person's note — the same denial the deployment pipeline's write probe asserts.
 
+The directory is empty until the first \`harbour check\`, which writes those three: it replays \`migrations/\` into a disposable database, reads this app's own tables back out of it, and generates a journey for each table and capability \`src/App.tsx\` uses. Every later \`harbour check\` keeps them in step — adding a journey when the app starts using a table or capability, removing one when the app stops. Each begins with a \`// harbour:generated\` line carrying a digest of its own body — edit a check and Harbour keeps your version, stops updating it and never removes it, and it is yours to maintain from then on.
+
 The checks and the code are one pair, and \`harbour check\` and the deployment pipeline's \`flow\` gate enforce the pair in both directions against a real App Gateway. Both directions refuse the deploy:
 
 - **A capability with no check.** They refuse an app whose checks never exercise an operation its own code performs, so a new feature needs its own retained check.
-- **A check with no capability.** They refuse an app whose retained checks no longer pass against its own code, so a feature you delete or replace means deleting or rewriting its check in the same edit. Replacing the starter's \`notes\` table with your own means rewriting \`notes-journey.mjs\` and \`notes-cross-user.mjs\` for that table. Removing the "Private files" section — the only code here that calls \`harbour.files.*\` — means \`rm .harbour/checks/files-journey.mjs\` right then; left behind, it exercises a capability the app no longer has and the deploy is refused with \`flow.check-failed: files-journey.mjs: exit status 1\`.
+- **A check with no capability.** They refuse an app whose retained checks no longer pass against its own code, so a feature you delete or replace means deleting or rewriting its check in the same edit. Running \`harbour check\` is that edit for a generated check: replace the \`notes\` table with your own and it rewrites both notes checks for the new table; remove the "Private files" section — the only code here that calls \`harbour.files.*\` — and it deletes \`.harbour/checks/files-journey.mjs\` for you. A check you have edited is not Harbour's to remove, so \`rm .harbour/checks/files-journey.mjs\` right then yourself; left behind, it exercises a capability the app no longer has and the deploy is refused with \`flow.check-failed: files-journey.mjs: exit status 1\`.
 
 ## Adding a company system (Slack, Gmail, a warehouse view)
 
@@ -339,8 +336,9 @@ export function App() {
       {error && <p role="alert" style={{ color: "crimson" }}>{error}</p>}
 
       {/* Notes — paired with .harbour/checks/notes-journey.mjs (data) and
-          .harbour/checks/notes-cross-user.mjs. Replacing this table with the app's own
-          means rewriting both checks for that table in the same edit. */}
+          .harbour/checks/notes-cross-user.mjs, both generated from this section and
+          migrations/0001_notes.sql. Replace this table with the app's own and run
+          \`harbour check\`: it rewrites both checks for the new table in that same edit. */}
       <section>
         <h2>Notes</h2>
         <form onSubmit={event => { event.preventDefault(); void addNote(); }}>
@@ -358,10 +356,11 @@ export function App() {
       </section>
 
       {/* Private files — the only code in this app that calls harbour.files.*, and so the
-          only reason .harbour/checks/files-journey.mjs exists. Delete this section and delete
-          that check in the same edit: the deploy's flow gate replays .harbour/checks/ against a
-          real App Gateway and refuses an app whose checks exercise a capability its code no
-          longer has ("flow.check-failed: files-journey.mjs: exit status 1"). */}
+          only reason .harbour/checks/files-journey.mjs exists. Delete this section and the next
+          \`harbour check\` deletes that check with it; delete it by hand in the same edit if you
+          have edited it, because the deploy's flow gate replays .harbour/checks/ against a real
+          App Gateway and refuses an app whose checks exercise a capability its code no longer
+          has ("flow.check-failed: files-journey.mjs: exit status 1"). */}
       <section>
         <h2>Private files</h2>
         <input type="file" aria-label="Upload file" onChange={event => { const file = event.target.files?.[0]; if (file) void upload(file); }} />
@@ -388,118 +387,3 @@ CREATE POLICY notes_owner ON notes
 GRANT SELECT, INSERT, UPDATE, DELETE ON notes TO harbour_app_gateway;
 GRANT USAGE, SELECT ON SEQUENCE notes_id_seq TO harbour_app_gateway;
 `;
-const JOURNEY_CHECK = `// Journey check: the signed-in identity can create, read, tick and delete a note through
-// the running app (HARBOUR_APP_URL). Runs under \`harbour check\` while \`harbour dev\`
-// is up, and in the deployment pipeline's retained-check container.
-//
-// Paired with the \`notes\` table (migrations/0001_notes.sql) and the Notes section of
-// src/App.tsx. Replace that table with the app's own and this check is rewritten for the
-// new table in the same edit; drop the feature entirely and this file is deleted. A check
-// left behind for code the app no longer has fails the deploy's flow gate.
-import assert from "node:assert/strict";
-
-const appUrl = process.env.HARBOUR_APP_URL;
-assert.ok(appUrl, "HARBOUR_APP_URL is required");
-const sdk = await import(process.env.HARBOUR_SDK_MODULE ?? "@harbour/app-sdk");
-// 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.
-const harbour = sdk.createClient({ baseUrl: appUrl });
-
-const user = await harbour.identity.current();
-assert.ok(user && user.email, "identity/current must return the signed-in user");
-const title = \`journey \${Date.now()}\`;
-await harbour.data.from("notes").insert({ title });
-const { data: notes } = await harbour.data.from("notes").select("*").eq("title", title);
-assert.equal(notes.length, 1, "the inserted note is readable by its owner");
-// The tick box in src/App.tsx is an UPDATE. The deployment pipeline refuses an
-// app whose checks never exercise an operation its own code performs, so the
-// journey toggles the note and reads the new value back.
-await harbour.data.from("notes").update({ done: true }).eq("id", notes[0].id);
-const { data: toggled } = await harbour.data.from("notes").select("*").eq("id", notes[0].id);
-assert.equal(toggled[0].done, true, "the note is marked done for its owner");
-await harbour.data.from("notes").delete().eq("id", notes[0].id);
-const { data: remaining } = await harbour.data.from("notes").select("id").eq("title", title);
-assert.equal(remaining.length, 0, "the note is deleted");
-`;
-const CROSS_USER_CHECK = `// Cross-user check: a second signed-in person cannot read, update or delete the first
-// person's note through the running app (HARBOUR_APP_URL). The deployment pipeline's
-// write probe makes exactly these three assertions, with a second identity, against every
-// owner-scoped table; this is the same check run locally, so user isolation can no longer
-// be green under \`harbour check\` and red in CodeBuild. Runs while \`harbour dev\` is up,
-// and in the pipeline's retained-check container.
-//
-// Paired with the \`notes\` table: an app that replaces \`notes\` with its own owner-scoped
-// table rewrites this check for that table in the same edit, and one that drops the table
-// deletes this file. A check left behind for code the app no longer has fails the flow gate.
-import assert from "node:assert/strict";
-
-const appUrl = process.env.HARBOUR_APP_URL;
-assert.ok(appUrl, "HARBOUR_APP_URL is required");
-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)");
-const sdk = await import(process.env.HARBOUR_SDK_MODULE ?? "@harbour/app-sdk");
-// The first person: the SDK attaches HARBOUR_IDENTITY_CONTEXT itself.
-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 me = await owner.identity.current();
-const them = await other.identity.current();
-assert.ok(me && them && me.id !== them.id, "the two signed-in identities must be different people");
-
-const title = \`cross-user \${Date.now()}\`;
-await owner.data.from("notes").insert({ title });
-const { data: mine } = await owner.data.from("notes").select("*").eq("title", title);
-assert.equal(mine.length, 1, "the owner reads the note back");
-const id = mine[0].id;
-
-// 1. SELECT by id as the second person: no row.
-const { data: seen } = await other.data.from("notes").select("*").eq("id", id);
-assert.equal(seen.length, 0, "notes: a second signed-in user can read another user's row — the owner policy does not isolate users");
-
-// 2. UPDATE and 3. DELETE by id as the second person: refused (403) or no row affected.
-const denied = async (verb, operation) => {
-  let affected;
-  try { affected = (await operation()).data ?? []; }
-  catch (error) { if (error?.category === "FORBIDDEN") return; throw error; }
-  assert.equal(affected.length, 0, \`notes \${verb}: a second user mutated another user's row despite an owner-scoped source policy\`);
-};
-await denied("UPDATE", () => other.data.from("notes").update({ done: true }).eq("id", id));
-await denied("DELETE", () => other.data.from("notes").delete().eq("id", id));
-const { data: after } = await owner.data.from("notes").select("*").eq("id", id);
-assert.equal(after.length, 1, "the owner's note still exists after the second user's attempts");
-assert.equal(after[0].done, false, "the owner's note is unchanged after the second user's attempts");
-await owner.data.from("notes").delete().eq("id", id);
-`;
-const FILES_JOURNEY_CHECK = `// Journey check: the signed-in identity can upload a private file and list it back
-// through the running app (HARBOUR_APP_URL) — the two operations the "Private
-// files" section of src/App.tsx performs (\`harbour.files.upload\` / \`harbour.files.list\`).
-// The deployment pipeline refuses an app whose checks never exercise a capability
-// its own code uses, so this runs under \`harbour check\` while \`harbour dev\` is up,
-// and in the pipeline's retained-check container.
-//
-// This file exists only for that "Private files" section — the only code in the app that
-// calls \`harbour.files.*\`. If the app stops offering file upload, DELETE THIS FILE in the
-// same edit that removes the section: the gate runs both ways, and a retained check for a
-// capability the code no longer has refuses the deploy with
-// "flow.check-failed: files-journey.mjs: exit status 1".
-import assert from "node:assert/strict";
-
-const appUrl = process.env.HARBOUR_APP_URL;
-assert.ok(appUrl, "HARBOUR_APP_URL is required");
-const sdk = await import(process.env.HARBOUR_SDK_MODULE ?? "@harbour/app-sdk");
-// 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.
-const harbour = sdk.createClient({ baseUrl: appUrl });
-
-const user = await harbour.identity.current();
-assert.ok(user && user.email, "identity/current must return the signed-in user");
-const name = \`journey-\${Date.now()}.txt\`;
-await harbour.files.upload(\`private/\${name}\`, new Blob(["harbour journey check\\n"], { type: "text/plain" }));
-const listed = await harbour.files.list("private/");
-assert.ok(Array.isArray(listed), "files.list must return a list");
-const found = listed.some(entry => String(typeof entry === "string" ? entry : entry?.path ?? entry?.name ?? "").endsWith(name));
-assert.ok(found, \`the uploaded file is listed back to its owner (looking for \${name})\`);
-`;

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

@@ -1 +1 @@
-export const CLI_VERSION = "0.1.25";
+export const CLI_VERSION = "0.1.26";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fourier-labs/harbour",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Harbour productionisation helper",
   "type": "module",
   "bin": {