@isomorph.ai/cli 0.3.4 → 0.4.0-rc.1

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

@@ -9,82 +9,70 @@
  * no-duplication rule are enforced by tests/cli-guide-budget.test.ts.
  */
 export const GUIDE_MODULES = {
-    core: `# Isomorph kit — core rules
+    core: `# Isomorph kit rules
 
 ## The SDK is the only door
 
-\`@isomorph.ai/app-sdk\`, on the client \`src/isomorph.client.ts\` exports, is the whole path: \`isomorph.identity.current()\`, \`isomorph.data.from(table)\`, \`isomorph.files.*\`, \`isomorph.realtime.*\`, \`isomorph.integrations.execute\` (integrations.md), \`isomorph.ai.chat\` (ai.md). Never open a database, bucket or company URL from browser code; never add a backend, auth library, deployment config, provider key or SDK. No secrets, tokens, \`.env\` values or fetched company content in source. Commit \`.isomorph/integrations.json\` and \`.isomorph/kit.lock.json\`, never \`.isomorph/local/\`.
+\`@isomorph.ai/app-sdk\` (exported by \`src/isomorph.client.ts\`) is the whole path: \`isomorph.identity.current()\`, \`isomorph.data.from(table)\`, \`isomorph.files.*\`, \`isomorph.realtime.*\`, \`isomorph.integrations.execute\` (integrations.md), \`isomorph.ai.chat\` (ai.md). No database, bucket or company URL from browser code; no backend, auth library, deployment config, provider key or other SDK; no secrets, tokens, \`.env\` values or fetched company content in source. Commit \`.isomorph/\`, never \`.isomorph/local/\`.
 
 ## Identity
 
-Isomorph SSO signs everyone in: no login forms, no browser-trusted roles or ids, no public routes. \`isomorph.identity.current()\` answers \`{ id, email }\` only; derive a display name from the address.
+Isomorph SSO signs everyone in: no login forms, browser-trusted roles or public routes. \`isomorph.identity.current()\` answers \`{ id, email }\` only.
 
-## Data (\`core.rls-owner-scoped\`)
+## Data
 
-Schema changes are SQL files in \`migrations/\`. Every table: \`ENABLE ROW LEVEL SECURITY\`, a policy, and \`GRANT\` of every verb it allows to \`harbour_app_gateway\` and no other role. Row ownership is decided in SQL through \`current_setting('harbour.user_id', true)\` (set by the gateway per request, with \`harbour.user_email\`), never in the browser. Two patterns:
+SQL files in \`migrations/\`; applied migrations are frozen after the first deploy (add the next file). Every table: RLS on, one policy; ownership decided in SQL (the gate names any privilege a table still lacks):
 
-- **Private table** — every policy scoped to that setting; the gate asserts another signed-in person cannot read, update or delete the row.
-- **Shared-read, owner-write** — \`USING (true)\` for SELECT; INSERT, UPDATE and DELETE scoped to that setting.
-
-The gate treats a table as private when any of its policies mentions \`harbour.user_id\` (or \`harbour.user_email\`), so a shared-read table must keep that setting out of its SELECT policy, or its cross-user read check fails.
-
-Iterating on the schema needs no restart: every \`isomorph check\` replays \`migrations/*.sql\` into a fresh, empty scratch database. \`isomorph dev --reset\` only refreshes the running app's own data, so its UI shows the new schema; stopping, resetting and waiting before each check costs minutes and changes nothing.
-
-## Files
-
-\`isomorph.files.upload(path, file)\`, \`list(prefix)\` and \`remove([path])\`.
+\`\`\`sql
+ALTER TABLE notes ENABLE ROW LEVEL SECURITY;
+CREATE POLICY notes_owner ON notes
+  USING (owner_subject = current_setting('harbour.user_id', true))
+  WITH CHECK (owner_subject = current_setting('harbour.user_id', true));
+\`\`\`
 
-## Realtime
+Shared-read, owner-write: the same, plus \`CREATE POLICY posts_read ON posts FOR SELECT USING (true);\`.
 
-\`isomorph.realtime.channel(name).on("postgres_changes", { event: "*" | "INSERT" | "UPDATE" | "DELETE", schema: "public", table }, payload => …).subscribe()\`; the payload carries \`eventType\`, \`new\` and \`old\`.
+\`.isomorph/checks/\` is generated by \`isomorph check\`, which adds and deletes files as the app changes; never write or edit it by hand.
 
-## Retained checks (\`core.journey-fk\`)
+## Files and realtime
 
-\`.isomorph/checks/\` holds one journey per capability the app uses, plus a cross-user denial per private table. \`isomorph check\` generates them from \`migrations/\` and \`src/\` and deletes what the app dropped, so run it in the edit that changes the app; never write or remove them by hand. A generated check starts with \`// isomorph:generated\` and a digest of its body; edit one and it is yours: kept, never updated or deleted, so delete it in the same edit that drops the feature. Two-way (\`flow.check-failed\`): the \`flow\` gate refuses a capability no check exercises, and a check exercising what the code dropped — the most common first-deploy refusal. What cannot be generated (\`actions\`, \`realtime\`, a table with no migration) is named for you to write. No journey is generated for a table whose row needs a parent (a foreign key): write that table's journey yourself.
+\`isomorph.files.upload(path, file)\`, \`list(prefix)\`, \`remove([path])\`.
 
-A journey failing on a CHECK constraint: generation marks the row by the first free text or number column with no foreign key, no allowed-values CHECK and no ceiling on a number, so that column's other CHECKs must admit an arbitrary unique value. Only the generated file names the column.
+\`isomorph.realtime.channel(name).on("postgres_changes", { event: "*" | "INSERT" | "UPDATE" | "DELETE", schema: "public", table }, payload => …).subscribe()\` (payload: \`eventType\`, \`new\`, \`old\`).
 
 ## Commands
 
-- \`isomorph dev --app-root .\` — local Postgres, storage, gateway and Vite on one origin; company calls use the \`isomorph login\` account.
-- \`isomorph check --app-root . --json\` — types, build, then the pipeline's kit gate locally (declaration, database, write probe, journeys, coverage).
-- \`isomorph productionise --app-root . …\` — private preview; \`isomorph promote\` makes it live.
+\`isomorph dev --app-root . --detach --json\` (run), \`isomorph check --app-root . --json\` (check), \`isomorph deploy --app-root . --json\` (private preview; \`isomorph promote\` makes it live).
 
 ## Error codes
 
 - \`CONFIG_REQUIRED\`: \`isomorph connect <work-email>\`; \`AUTH_REQUIRED\`: \`isomorph login\`.
-- \`NOT_A_MEMBER\` / \`TENANT_AMBIGUOUS\`: use the command it printed or IT's link.
-- \`CHECKS_FAILED\` / \`CHECKS_STALE\`: fix what \`isomorph check\` reports, then rerun on this code.
-- \`APP_NOT_FOUND\`: the app is linked to another company — connect back to it with its start link, or clear \`appId\` and \`tenantId\` in \`.isomorph/kit.lock.json\` to relink.
-- \`INTEGRATIONS_NOT_READY\` / \`AI_NOT_READY\`: IT has not approved the connection (integrations.md) or enabled AI (ai.md).`,
+- \`CHECKS_FAILED\`: fix what \`isomorph check\` reports, then rerun.
+- \`DEPLOY_BLOCKED\`, \`INTEGRATIONS_NOT_READY\`, \`AI_NOT_READY\`: IT's step is in the refusal; the app works meanwhile.
+- \`CLI_UPGRADE_REQUIRED\`: \`npm i -g @isomorph.ai/cli\`.
+- \`APP_NOT_FOUND\`: clear \`appId\` and \`tenantId\` in \`.isomorph/kit.lock.json\` to relink.`,
     integrations: `# Company systems (Slack, Gmail, warehouse)
 
 ## Declare
 
-Reach company systems only through \`isomorph.integrations.execute(connection, { operation, resource, input })\`, declared in \`.isomorph/integrations.json\`. Operations, a closed set: \`slack.channel.history\` (user identity), \`slack.message.post\` (app or user identity, declared per app), \`gmail.thread.list\`, \`gmail.message.read\` and \`gmail.message.send\` (user identity, resource \`inbox\`, plain-text send), \`warehouse.view.read\` (app identity). Resources are logical names, never IDs, URLs or tokens. The file starts as \`"connections": {}\`: declare one only when the app calls it, by the catalog's identifier, with only the operations it calls — each declared connection blocks the deploy until IT grants it; an undeclared one cannot be requested (\`CONNECTION_NOT_DECLARED\`). Strict JSON, no comments.
+Company systems are reached through \`isomorph.integrations.execute(connection, { operation, resource, input })\`, declared in \`.isomorph/integrations.json\` by catalog identifier, with only the operations called. Closed set: \`slack.channel.history\` (user), \`slack.message.post\` (app or user), \`gmail.thread.list\`, \`gmail.message.read\`, \`gmail.message.send\` (user, \`inbox\`), \`warehouse.view.read\` (app). Resources are logical names, never IDs. Strict JSON.
 
 \`\`\`json
 "company-slack": { "kind": "saas", "operations": { "slack.message.post": { "identity": "app", "resources": ["team-updates"] } } },
 "sales-warehouse": { "kind": "database", "operations": { "warehouse.view.read": { "identity": "app", "resources": { "weekly_sales": { "columns": ["week", "total"] } } } } }
 \`\`\`
 
-A connection that was READY reporting PENDING again: widening an approved declaration (another column on a declared resource, or another operation) re-files the request, and a database connection's development lane re-enters provisioning while access is re-minted, so the widened read fails until it republishes. Nothing is revoked: the record stays GRANTED with the resources it had, and the window closes on its own — re-check the status rather than treat it as a blocker.
-
 ## Catalog
 
-Never guess a connection, channel, table, view, mailbox or warehouse column — a guessed name is refused before IT's queue ever sees it. Before writing a warehouse query or mapping response fields, run \`isomorph integrations catalog --app-root . --json\`, select a listed table or view, and copy its listed column names exactly; if either is absent, report that catalog gap instead of substituting a plausible name. A resource whose catalog columns are \`["*"]\` is declared and read with \`["*"]\`: inspect the returned row keys; never invent a schema.
+Never guess a connection, channel, table, view, mailbox or column: a guess is refused before IT sees it. Before a warehouse query or field mapping, run \`isomorph integrations catalog --app-root . --json\`, pick a listed table or view and copy its column names exactly; report a gap rather than invent a name. Columns \`["*"]\`: read \`["*"]\` and inspect the row keys.
 
 ## Request
 
-One request per connection; IT approves it once for every environment. \`isomorph dev\` and \`isomorph productionise\` file it for you; \`isomorph integrations request <connection> --reason "<why the app needs it>" --app-root . --json\` files it now — submit the request yourself in the same turn, and never tell the person to ask IT before you have submitted the request.
-
-## Status
-
-READY: use it now. PENDING: say "IT has to approve this; the app works without it until then" and check later with \`isomorph integrations status --app-root . --json\`. Before a real integration test read that status: show pending approval and missing consent separately. Retained checks calling \`isomorph.integrations.execute\` get the gate's fixture, locally and in the pipeline (nothing sent or read); only \`isomorph check --integrations\` (reads) exercises real access.
+\`isomorph integrations request <connection> --reason "<why>" --app-root . --json\` files the one request IT approves once for every environment (\`isomorph dev\` and \`isomorph deploy\` file it too); submit it yourself, in the same turn. \`isomorph integrations status --app-root . --json\`: READY, use it; PENDING, say "IT has to approve this; the app works meanwhile". \`RESOURCE_NOT_APPROVED\`: IT adds the channel, view or mailbox in the console (Controls & integrations); then run the same request again.
 
 ## Call shape
 
-On the exported client (\`src/isomorph.client.ts\`), always this exact shape and never a wrapper function (nor a generic string/unknown wrapper): the kit gate derives what the app uses from the direct call.
+Always this exact shape, never a wrapper function: the kit gate reads the direct call.
 
 \`\`\`ts
 const report = await isomorph.integrations.execute("sales-warehouse", {
@@ -92,19 +80,17 @@ const report = await isomorph.integrations.execute("sales-warehouse", {
 });
 \`\`\`
 
-Input bounds: \`slack.channel.history\` \`input.limit\` 1..15, \`gmail.thread.list\` \`input.limit\` 1..15, \`warehouse.view.read\` \`input.limit\` 1..1000 (\`VIEW_READ_MAX_LIMIT\`); larger is refused with \`INPUT_INVALID\`, so page instead.
-
-## Slack modes
-
-\`"identity": "app"\` posts as the company's Slack bot, Isomorph AI, under the connection's IT-approved \`presentation.displayName\` (optional \`iconEmoji\`); omit it to post as Isomorph AI itself. \`"identity": "user"\` posts as the person after their consent; an older consent answers \`USER_RECONNECT_REQUIRED\`: offer Connect again. Never pretend one is the other. The call names the approved mode it runs under (\`mode: "app"\` or \`"user"\`): optional with one approved mode, required with both (\`MODE_REQUIRED\`); an unapproved mode is \`MODE_NOT_GRANTED\`, never swapped. \`RESOURCE_NOT_APPROVED\` on a post: the bot is not in the channel — say "IT (or anyone in the channel) runs \`/invite @Isomorph AI\` in #<channel>". On a request: the resource is not on the connection yet — IT adds it in the console under Controls & integrations, then run the same request again.
-
 ## Consent
 
-Only user-identity operations (\`slack.channel.history\`, \`gmail.thread.list\`, \`gmail.message.read\`, \`gmail.message.send\`, and \`slack.message.post\` declared \`"identity": "user"\`) need it; build the flow in unasked, during the original implementation: the operation's control calls \`isomorph.integrations.connect(connection)\`, follows \`authorizationUrl\` when the result is \`consent_required\`, returns to a clear connected state and lets the person continue. Consent starts from that control, never on page load; missing consent never falls back to another account. App-identity operations (\`slack.message.post\` declared \`"identity": "app"\`, \`warehouse.view.read\`) never call connect — it is refused and puts nothing in IT's queue.
+Only user-identity operations need it, built in unasked: the control calls \`isomorph.integrations.connect(connection)\`, follows \`authorizationUrl\` on \`consent_required\`, and returns to a connected state. Never on page load; app-identity operations never call connect.
 
 ## Sends
 
-A send (\`slack.message.post\`, \`gmail.message.send\`) runs only from an explicit Send control — pressed by the person, or by you for an explicitly authorized test — with a fresh UUID \`idempotencyKey\` per press (reused only to retry it); never from an effect, a browser timer or a check. After a partial send, retry only the failed destination with its original key. Scheduled sends: jobs.md.`,
+A send (\`slack.message.post\`, \`gmail.message.send\`) runs only from an explicit Send control the person presses, with a fresh UUID \`idempotencyKey\` per press (reused only to retry); never from an effect, a timer or a check. Scheduled sends: jobs.md.
+
+## Slack modes
+
+\`"identity": "app"\` posts as the company's bot under IT's approved \`presentation.displayName\`; \`"identity": "user"\` posts as the person after consent (\`USER_RECONNECT_REQUIRED\`: offer Connect again). Name the \`mode\` when both are approved (\`MODE_REQUIRED\`); an unapproved mode is \`MODE_NOT_GRANTED\`, never swapped. \`RESOURCE_NOT_APPROVED\` on a post: the bot is not in the channel; anyone there runs \`/invite @Isomorph AI\`.`,
     ai: `# Governed AI
 
 AI goes through \`isomorph.ai\` only: one \`isomorph.ai.chat({ messages, maxTokens })\` call on the app's one client (\`src/isomorph.client.ts\`), never through a wrapper function (the gate reads only the direct call), behind a control the person presses — never on load, in an effect or a timer. Never add an OpenAI/Anthropic/Gemini key, SDK or URL: the governed AI gateway holds the key and IT sees every call. Send \`messages\` and \`maxTokens\` and nothing else; a refusal with \`unsupported_request_capability\` names a field the company's AI route does not accept — remove that field. A refusal with \`AI_NOT_ENABLED\` means IT has not enabled an AI provider yet: say so in one line and keep the app working without AI.

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

@@ -1,6 +1,7 @@
 import { basename } from "node:path";
 import { linkIdempotencyKey, OPERATIONS, readDeclaration, readKitLock, requestResourceName, requestResources, writeKitLock, newKitLock } from "./kit.js";
 import { CliError } from "./output.js";
+import { CLI_VERSION } from "./version.js";
 export class GovernanceClient {
     apiUrl;
     token;
@@ -29,9 +30,14 @@ export class GovernanceClient {
     execute(appId, body) {
         return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/integrations/execute`, body);
     }
-    /** Would this app's deployment PLAN pass for the environment? Read-only; governance answers from the company's AI setup. */
-    aiReadiness(appId, environment) {
-        return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/ai/readiness`, { environment });
+    /**
+     * Every blocker of a deploy at once: the grants the declaration needs on the
+     * environment's lane (governance files the requests itself), the company's AI
+     * setup when the app calls governed AI, and the CLI version. One call, one
+     * refusal shape, instead of the sequential integrations → AI → pipeline cycles.
+     */
+    deployPreflight(appId, body) {
+        return this.call("POST", `/v1/development/apps/${encodeURIComponent(appId)}/deploy-preflight`, body);
     }
     /**
      * What the building agent says cost it time in Isomorph itself. Never blocks a
@@ -46,9 +52,9 @@ export class GovernanceClient {
             .catch((error) => { throw new CliError("GOVERNANCE_UNREACHABLE", `Isomorph governance at ${new URL(url).host} could not be reached: ${transportFailure(error)}.`); });
         const parsed = await response.json().catch(() => ({}));
         if (response.status === 401)
-            throw new CliError("AUTH_REQUIRED", "Please sign in to Isomorph with `isomorph login`.");
+            throw new CliError("AUTH_REQUIRED", "Please sign in to Isomorph with `isomorph login`.", undefined, undefined, undefined, { layer: "governance" });
         if (!response.ok)
-            throw new CliError(parsed.error?.details?.code ?? parsed.error?.category ?? `HTTP_${response.status}`, parsed.error?.message ?? "Isomorph governance rejected the request.");
+            throw new CliError(parsed.error?.details?.code ?? parsed.error?.category ?? `HTTP_${response.status}`, parsed.error?.message ?? "Isomorph governance rejected the request.", undefined, undefined, undefined, { layer: "governance" });
         return (parsed.data ?? parsed);
     }
 }
@@ -105,7 +111,7 @@ function settled(requests) {
 }
 /**
  * Files the app-wide request for every connection the app declares, one per
- * identity mode — what `isomorph dev` (signed in) and `productionise` do before
+ * identity mode — what `isomorph dev` (signed in) and `deploy` do before
  * anything else, so IT's queue holds the ask from the first run and no command
  * stands between a builder and an approval. Idempotent: governance answers
  * READY for a scope IT has approved and PENDING with the existing request for
@@ -189,7 +195,7 @@ export function unregisteredResourceGuidance(error, declaration, connection, roo
     const place = declared?.kind === "database"
         ? `Controls & integrations → Databases → ${connection} → Data resources`
         : `Controls & integrations → API integrations → ${provider} → Configure → ${provider === "Gmail" ? "the mailbox" : "Channels"}`;
-    return new CliError(error.code, `IT has to add ${resource} to the ${connection} connection first (in the Isomorph console: ${place}); the app works without it until then, and once it is added run \`isomorph integrations request ${connection} --app-root ${root}\` again (\`isomorph dev\` and \`isomorph productionise\` file the request too).`, error.operationRef);
+    return new CliError(error.code, `IT has to add ${resource} to the ${connection} connection first (in the Isomorph console: ${place}); the app works without it until then, and once it is added run \`isomorph integrations request ${connection} --app-root ${root}\` again (\`isomorph dev\` and \`isomorph deploy\` file the request too).`, error.operationRef, undefined, undefined, { layer: "governance" });
 }
 export function groupGrants(grants) {
     const groups = new Map();
@@ -222,17 +228,9 @@ const expired = (grant, nowMs) => grant.status === "GRANTED" && Boolean(grant.ex
  * reading that as IT's sent a builder off to report a permanently broken development lane.
  */
 const minting = (grant) => grant.readiness === "pending" && grant.provisioning === "PENDING";
-/**
- * Which readiness values can carry a deploy, as a total map so `npm run check` refuses a new
- * readiness value until this question has been answered for it. A person's consent is asked
- * inside the running app, so a consent lane deploys.
- */
-const DEPLOYABLE = { ready: true, consent_required: true, reconnect_required: true, pending: false, failed: false };
-/** A lane a deploy can run on: granted, unexpired, on a readiness that can carry one, and not still being minted — implied by `pending` today, and asked anyway so the gate fails closed if that map ever changes. */
-const laneReady = (grant, nowMs) => grant.status === "GRANTED" && !expired(grant, nowMs) && DEPLOYABLE[grant.readiness] && !minting(grant);
 /** Builder-safe failure guidance as one sentence: what failed, then what to do. */
 export const failureSentence = (failure) => `${failure.message} ${failure.remediation}`;
-const failureError = (failure) => new CliError(failure.code, failureSentence(failure));
+const failureError = (failure) => new CliError(failure.code, failureSentence(failure), undefined, undefined, undefined, { layer: "governance" });
 /**
  * One sentence for the three lanes: `ready in development, preview, production`
  * when they agree, otherwise the lanes that differ — `development ready
@@ -295,67 +293,42 @@ export function renderGrantGroup(group, nowMs = Date.now()) {
     return lines;
 }
 /**
- * `productionise` pre-check. Files the app-wide request for every declared
- * connection (idempotent: READY comes straight back once IT has approved), then
- * reads the preview lane — the one this deploy runs in — and refuses before any
- * operation exists, naming exactly what is still waiting. Links the app when
- * needed (the same key as `integrations request`) so both share one appId.
- * Returns the kit appId, or undefined for a non-kit app.
- */
-export async function assertPreviewIntegrationsReady(root, client, tenantId, bundle, output) {
-    const filed = await fileDeclaredRequests(root, client, tenantId, bundle);
-    if (!filed)
-        return (await readKitLock(root))?.appId || undefined;
-    const nowMs = Date.now();
-    // `awaitsDecision` separates the refusals a person has to act on from a preview lane the worker is
-    // simply still minting: that one refuses too (there are no credentials to deploy against yet), but
-    // saying "Waiting for IT" over it is the same false blocker the minting predicate exists to end.
-    const waiting = [];
-    for (const item of settled(filed.requests)) {
-        const group = findGroup(filed.groups, item.connection, item.identityMode);
-        const preview = group.lanes.preview;
-        // Guidance also rides on a lane that is still being retried; only a failed readiness is a refusal in its own words.
-        if (preview?.failure && preview.readiness === "failed")
-            throw failureError(preview.failure);
-        if (preview && laneReady(preview, nowMs))
-            continue;
-        if (preview && minting(preview)) {
-            waiting.push({ awaitsDecision: false, line: `${item.connection} ${IDENTITY_WORDS[item.identityMode]} is being set up for the preview; nobody has to approve anything and it finishes on its own.` });
-            continue;
-        }
-        const requestId = item.outcome.requestId ?? openRequestId(group.lanes);
-        waiting.push({ awaitsDecision: true, line: requestId
-                ? `Waiting for IT: ${item.connection} ${IDENTITY_WORDS[item.identityMode]} (request ${requestId}).`
-                : `${item.connection} ${IDENTITY_WORDS[item.identityMode]} is not ready for the preview (${laneSummary(group, undefined, nowMs)}); ask IT to review this app's access in the Isomorph console.` });
-    }
-    if (!waiting.length)
-        return filed.appId;
-    output("Isomorph cannot deploy the preview yet:");
-    for (const { line } of waiting)
-        output(`  ${line}`);
-    const next = waiting.some(item => item.awaitsDecision)
-        ? "IT approves a request once, for every environment; rerun productionise when it is approved."
-        : "Run productionise again in a minute.";
-    throw new CliError("INTEGRATIONS_NOT_READY", `${waiting.map(item => item.line).join(" ")} ${next}`);
-}
-/**
- * `productionise` / `promote` pre-check for an app that calls governed AI
- * (the local gate's inventory lists `ai` among its capabilities): the
- * pipeline will ask governance for a PLAN over the inventory the kit shipped,
- * and that PLAN blocks on the company's AI setup — no provider, no route, no
- * budget, observe mode before production. Ask the same question here, before
- * any build, and refuse with the one IT step, the way a missing grant is
- * refused. Observed without it (fourier app-f578bfc2, 2026-09-12): a green
- * check, a live preview, and a button that answered AI_UNAVAILABLE.
+ * `deploy` / `promote` pre-flight, one call. Links the app when needed (the
+ * same key as `integrations request`) so both share one appId, then asks
+ * governance whether this app can deploy to the environment: it files the
+ * declared access requests itself and answers with every blocker at once —
+ * the lanes IT still has to approve, the company's AI setup when the app calls
+ * governed AI, and a CLI older than the platform's minimum. Prints each
+ * blocker's sentence and refuses once, before any operation exists.
+ *
+ * The code is `DEPLOY_BLOCKED` when the blockers are of more than one kind;
+ * when they are all of one kind it is the code readers already know for that
+ * kind (`INTEGRATIONS_NOT_READY`, `AI_NOT_READY`, `CLI_UPGRADE_REQUIRED`).
+ * Observed before this: a builder was refused `INTEGRATIONS_NOT_READY`, fixed
+ * that, then `AI_NOT_READY`, then the pipeline refused `kit_bundle_incompatible`,
+ * each a separate cycle.
  */
-export async function assertAiReady(appId, environment, client, output) {
-    const readiness = await client.aiReadiness(appId, environment);
-    if (readiness.ready) {
-        output(`Isomorph confirmed the company's AI setup for ${environment}.`);
-        return;
+export async function assertDeployReady(root, client, tenantId, bundle, environment, output, callsAi) {
+    const { declaration, errors } = await readDeclaration(root);
+    if (errors.length && !errors[0].startsWith(".isomorph/integrations.json is missing"))
+        throw new CliError("DECLARATION_INVALID", `.isomorph/integrations.json is invalid: ${errors[0]}`);
+    const appId = await ensureLinkedApp(root, client, tenantId, bundle);
+    const preflight = await client.deployPreflight(appId, { environment, callsAi, declaration, cliVersion: CLI_VERSION });
+    const blockers = Array.isArray(preflight.blockers) ? preflight.blockers.filter(blocker => blocker && typeof blocker.sentence === "string") : [];
+    if (preflight.ready && !blockers.length) {
+        output(`Isomorph confirmed the app can deploy to ${environment}.`);
+        return appId;
     }
-    throw new CliError("AI_NOT_READY", readiness.plainEnglish);
+    output(`Isomorph cannot deploy to ${environment} yet:`);
+    for (const blocker of blockers)
+        output(`  ${blocker.sentence}`);
+    const kinds = new Set(blockers.map(blocker => blocker.kind));
+    const code = kinds.size === 1 ? BLOCKER_CODES[[...kinds][0]] ?? "DEPLOY_BLOCKED" : "DEPLOY_BLOCKED";
+    const fixes = [...new Set(blockers.map(blocker => blocker.fix).filter(Boolean))].join(" ");
+    throw new CliError(code, blockers.map(blocker => blocker.sentence).join(" ") || `Isomorph cannot deploy this app to ${environment} yet.`, undefined, fixes || undefined, undefined, { layer: "governance" });
 }
+/** The code readers already know for a refusal that is all of one kind. */
+const BLOCKER_CODES = { integration: "INTEGRATIONS_NOT_READY", ai: "AI_NOT_READY", cli: "CLI_UPGRADE_REQUIRED" };
 /**
  * Splits the declared operations of one connection by identity mode — the
  * declaration's own `identity` (the gate has checked it against the closed

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

@@ -25,7 +25,6 @@ export function isKitBundle(value) {
     const record = value;
     return Boolean(record && typeof record === "object" && record.schema === "isomorph.kit-bundle/1.0" && typeof record.kitVersion === "string"
         && record.sdk && typeof record.sdk.package === "string" && typeof record.sdk.tarballSha256 === "string"
-        && record.images && typeof record.images.appGateway === "string" && typeof record.images.sessionFixture === "string"
         && record.brief && typeof record.brief.fingerprint === "string" && record.declarationSchema === "isomorph.app-integrations/2.0");
 }
 /** Lines naming every digest that differs between two manifests, for `init --upgrade`. */
@@ -33,8 +32,6 @@ export function bundleDiff(before, after) {
     const fields = [
         ["kitVersion", before.kitVersion, after.kitVersion],
         ["sdk.tarballSha256", before.sdk.tarballSha256, after.sdk.tarballSha256],
-        ["images.appGateway", before.images.appGateway, after.images.appGateway],
-        ["images.sessionFixture", before.images.sessionFixture, after.images.sessionFixture],
         ["brief.fingerprint", before.brief.fingerprint, after.brief.fingerprint]
     ];
     return fields.filter(([, a, b]) => a !== b).map(([name, a, b]) => `${name}: ${a ?? "(none)"} -> ${b ?? "(none)"}`);

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

@@ -1,6 +1,6 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "isomorph.kit-bundle/1.0",
-    "kitVersion": "0.3.1",
+    "kitVersion": "0.4.0",
     "sdk": {
         "package": "@isomorph.ai/app-sdk",
         "version": "1.2.0",
@@ -8,21 +8,21 @@ export const PUBLISHED_KIT_BUNDLE = {
         "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:6b41494883215527a73e05a1e07d022552dfe3402915e23950e357e5e9381c49"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:af841461de984099c202b5d0c86321c5e5f51713f3bcd487f0fc904b17a30d3a",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:fe94fb879357520bc9b34db590a64b6c82cb63e59b97ca76d1cde470e84f7df3"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:9c7750897be5ed44af332069f463f0cfe9ca94694450b49ab469c019c97d7757",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:52bfe8ca4e40fd38e662ab13c32cc842721f0d48b494561e99ac1607e49e8c74"
     },
     "nativeRuntime": {
         "darwinArm64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:56db6d0080e0f38401d8a4a6cba0dfd44fd66878d574e88df8b6ffe63551fa4e",
-            "sha256": "56db6d0080e0f38401d8a4a6cba0dfd44fd66878d574e88df8b6ffe63551fa4e"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:7f6377c465b46cfb45402ae12c3f05063bae7c780c1c2be3aab5bd75614e809a",
+            "sha256": "7f6377c465b46cfb45402ae12c3f05063bae7c780c1c2be3aab5bd75614e809a"
         },
         "linuxX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:082272dd1823d51e05d5f9497c5644dd62dd3996ffe83ae69f357471d7d492a0",
-            "sha256": "082272dd1823d51e05d5f9497c5644dd62dd3996ffe83ae69f357471d7d492a0"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:ea9fc7cab8b2ebf27fb39a59699cd3d76117d0f8fc00346f7d85cc1bab84778d",
+            "sha256": "ea9fc7cab8b2ebf27fb39a59699cd3d76117d0f8fc00346f7d85cc1bab84778d"
         },
         "windowsX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:5341eab77337713255fa3175f14038d702b07332bb0073b5bba333ba5adf5bf1",
-            "sha256": "5341eab77337713255fa3175f14038d702b07332bb0073b5bba333ba5adf5bf1"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:0e1ef627daae405f1043b4b434a446e3cee937c370cb64ea49d84dc07c484d21",
+            "sha256": "0e1ef627daae405f1043b4b434a446e3cee937c370cb64ea49d84dc07c484d21"
         }
     },
     "brief": {

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

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join, parse, resolve } from "node:path";
+import { basename, dirname, join, parse, resolve } from "node:path";
 import { scanWorkspace } from "../../../src/analyzer.js";
 import { isKitBundle } from "./kit-bundle.js";
 import { CliError } from "./output.js";
@@ -111,23 +111,50 @@ export function appRoot(rootArg) {
 export function kitPaths(root) {
     const kit = join(root, KIT_DIRECTORY);
     const local = join(kit, "local");
-    return { kit, local, declaration: join(kit, "integrations.json"), lock: join(kit, "kit.lock.json"), checks: join(kit, "checks"), devLock: join(local, "dev.lock"), state: join(local, "state"), report: join(local, "check-report.json") };
+    return { kit, local, declaration: join(kit, "integrations.json"), app: join(kit, "app.json"), lock: join(kit, "kit.lock.json"), checks: join(kit, "checks"), devLock: join(local, "dev.lock"), state: join(local, "state"), report: join(local, "check-report.json") };
 }
-/** The kit directory of an app set up by a CLI older than 0.2.0; `isomorph init --upgrade` moves it to `.isomorph/`. */
-export const LEGACY_KIT_DIRECTORY = ".harbour";
+export function defaultAppProfile(root) {
+    return { schema: "isomorph.app/1.0", name: basename(resolve(root)), description: "", audience: [] };
+}
+/** `.isomorph/app.json` as `init` writes it. */
+export function renderAppProfile(profile) {
+    return `${JSON.stringify(profile, null, 2)}\n`;
+}
+const EMAIL_SHAPE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 /**
- * Refuses an app that still carries the old kit directory and not the current
- * one. Nothing reads the old layout — not `dev`, not `check`, not the
- * deployment pipeline — so the one command that moves it is named here rather
- * than discovered as a missing declaration, a missing lock and an app deployed
- * without its kit.
+ * Reads the profile, refusing what `deploy` could not record: a missing file
+ * (an app set up before the file existed — `init` adds it), invalid JSON, a
+ * blank name, or an audience entry that is not an email address.
  */
-export async function assertKitCurrent(root) {
-    const [legacy, current] = await Promise.all([isDirectory(join(root, LEGACY_KIT_DIRECTORY)), isDirectory(kitPaths(root).kit)]);
-    if (legacy && !current)
-        throw new CliError("KIT_UPGRADE_REQUIRED", "This app was set up by an older CLI and has not been moved to the current kit yet. Run `isomorph init --upgrade --app-root .` once, then run this again.");
+export async function readAppProfile(root) {
+    let raw;
+    try {
+        raw = await readFile(kitPaths(root).app, "utf8");
+    }
+    catch {
+        throw new CliError("APP_PROFILE_REQUIRED", "This app has no .isomorph/app.json (its name, description and audience).", undefined, "Run `isomorph init --app-root .` to add it, then edit the three values and run this again.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CliError("APP_PROFILE_INVALID", ".isomorph/app.json is not valid JSON.", undefined, "Fix the file, then run this again.");
+    }
+    const record = (parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {});
+    const problems = [];
+    if (record.schema !== "isomorph.app/1.0")
+        problems.push("schema must be \"isomorph.app/1.0\"");
+    if (typeof record.name !== "string" || !record.name.trim())
+        problems.push("name must be a non-empty string");
+    if (record.description !== undefined && typeof record.description !== "string")
+        problems.push("description must be a string");
+    if (!Array.isArray(record.audience) || record.audience.some(entry => typeof entry !== "string" || !EMAIL_SHAPE.test(entry.trim())))
+        problems.push("audience must be a list of email addresses (an empty list means only you)");
+    if (problems.length)
+        throw new CliError("APP_PROFILE_INVALID", `.isomorph/app.json is invalid: ${problems.join("; ")}.`, undefined, "Fix the file, then run this again.");
+    return { schema: "isomorph.app/1.0", name: record.name.trim(), description: (record.description ?? "").trim(), audience: record.audience.map(entry => entry.trim()) };
 }
-const isDirectory = (path) => stat(path).then(info => info.isDirectory(), () => false);
 /** Stable per-project identity for the kit-managed local state. */
 export function projectName(root, suffix = "") {
     return `isomorph-${createHash("sha256").update(resolve(root)).digest("hex").slice(0, 12)}${suffix}`;
@@ -137,7 +164,7 @@ export function linkIdempotencyKey(tenantId, root) {
     return createHash("sha256").update(`${tenantId}${resolve(root)}`).digest("hex");
 }
 /**
- * sha256 over the tracked app files (same boundary as productionise), so any
+ * sha256 over the tracked app files (same boundary as deploy), so any
  * edit changes it — and, per file, the hash of its contents, so a stale check
  * can say WHICH path moved rather than only that something did.
  */

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

@@ -43,6 +43,11 @@ export const LOCAL = {
     bucket: "harbour-local",
     gatewayRole: "harbour_app_gateway"
 };
+/** What the gateway role may do with every table and sequence a migration creates, set once per session (see `migrate`). */
+export const DEFAULT_PRIVILEGES = [
+    `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${LOCAL.gatewayRole};`,
+    `ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ${LOCAL.gatewayRole};`
+];
 /**
  * App Gateway configuration in the shape cmd/appgateway/main.go decodes (unknown fields are rejected there).
  * `localSession` is what makes the gateway the whole local runtime: issuer = its own published origin (the
@@ -279,7 +284,19 @@ export class LocalRuntime {
         await this.down();
         await rm(kitPaths(this.root).state, { recursive: true, force: true });
     }
-    /** Applies `migrations/*.sql` in name order through psql inside the postgres container, after ensuring the runtime role. */
+    /**
+     * Applies `migrations/*.sql` in name order as the session superuser, after
+     * ensuring the runtime role and its default privileges.
+     *
+     * The gateway logs in as `harbour_app_gateway`; before data plane 0.79.2.0
+     * every migration had to `GRANT` it every verb on every table and sequence
+     * by hand — two lines per table that said nothing about the app. The gate's
+     * replay and the hosted path now set default privileges once (#365), and this
+     * is the one remaining site: the same statements, in this session, so a table
+     * a migration creates is readable by the gateway with no GRANT of its own.
+     * Idempotent (default privileges are a set), no `FOR ROLE`: the replay and
+     * this step run as the same role, so the default applies to what they create.
+     */
     async migrate() {
         const dir = join(this.root, "migrations");
         const names = await migrationNames(this.root);
@@ -287,6 +304,11 @@ export class LocalRuntime {
         const role = await psql(`DO $$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = '${LOCAL.gatewayRole}') THEN CREATE ROLE ${LOCAL.gatewayRole} LOGIN PASSWORD '${LOCAL.dbPassword}'; END IF; END $$;`);
         if (role.code !== 0)
             throw new CliError("MIGRATION_FAILED", "Could not prepare the local database role.");
+        for (const statement of DEFAULT_PRIVILEGES) {
+            const granted = await psql(statement);
+            if (granted.code !== 0)
+                throw new CliError("MIGRATION_FAILED", `Could not set the local database's default privileges: ${granted.stderr.trim().split("\n").at(-1) ?? "psql error"}`);
+        }
         for (const name of names) {
             const result = await psql(await readFile(join(dir, name), "utf8"));
             if (result.code !== 0)