@isomorph.ai/cli 0.6.0 → 0.7.1

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

@@ -2,7 +2,7 @@ import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { CliError } from "./output.js";
 import { DEPENDENT_READ_OPERATIONS, READ_OPERATIONS, kitPaths, readDeclaration, readKitLock, resourceNames, sourceDigest } from "./kit.js";
-import { LocalRuntime, allocatePorts, ensureSdk, freePort, nodePackageCommand, readDevLock, runningOrigin } from "./local-runtime.js";
+import { LocalRuntime, allocatePorts, freePort, installDependencies, nodePackageCommand, readDevLock, runningOrigin } from "./local-runtime.js";
 import { CLI_VERSION } from "./version.js";
 /**
  * What actually failed, in the refusal itself.
@@ -45,17 +45,15 @@ export async function runChecks(root, options) {
     const previous = await readReport(root);
     if (previous && previous.sourceDigest !== (await sourceDigest(root)).digest)
         output("Source changed since the last report; the previous report is no longer valid.");
+    // A fresh clone has no node_modules: install once, and say so, before the typecheck needs the SDK's types.
+    await installDependencies(root, bundle, run, output);
     const npx = nodePackageCommand("npx", ["tsc", "--noEmit"]);
     const typecheck = await run(npx.command, npx.args, { cwd: root, quiet: true });
     record({ name: "typecheck", status: typecheck.code === 0 ? "pass" : "fail", ...(typecheck.code === 0 ? {} : { detail: lastLines(typecheck.stdout || typecheck.stderr) }) });
     const npm = nodePackageCommand("npm", ["run", "build"]);
     const build = await run(npm.command, npm.args, { cwd: root, quiet: true });
     record({ name: "build", status: build.code === 0 ? "pass" : "fail", ...(build.code === 0 ? {} : { detail: lastLines(build.stderr || build.stdout) }) });
-    // The gate runs the journeys with this node and the app's own SDK: the SDK
-    // the bundle pins, installed now if node_modules holds an older copy.
-    const sdk = await ensureSdk(root, bundle, options.env ?? process.env, run, output).catch(error => { output(error instanceof Error ? error.message : String(error)); return "missing"; });
-    if (sdk === "missing")
-        output(`The kit SDK is not installed: set ISOMORPH_KIT_SDK_TARBALL to the bundle's ${bundle.sdk.package} tarball (or use a bundle with sdk.url).`);
+    // The gate runs the journeys with this node and the SDK the app's own install put in node_modules.
     const gate = await runKitGate(root, { run, bundle, output, ...(options.fetch ? { fetch: options.fetch } : {}), ...(options.runtime ? { runtime: options.runtime } : {}), ...(options.pollMs ? { pollMs: options.pollMs } : {}) });
     for (const check of gate.checks)
         record(check);
@@ -94,7 +92,7 @@ export async function runChecks(root, options) {
         createdAt: new Date().toISOString(),
         sourceDigest: source.digest,
         sourceFiles: source.entries,
-        toolchain: { node: process.version, cliVersion: CLI_VERSION, bundle: { kitVersion: bundle.kitVersion, sdkTarballSha256: bundle.sdk.tarballSha256, briefFingerprint: bundle.brief.fingerprint } },
+        toolchain: { node: process.version, cliVersion: CLI_VERSION, bundle: { kitVersion: bundle.kitVersion, sdkVersion: bundle.sdk.version, briefFingerprint: bundle.brief.fingerprint } },
         checks,
         gate,
         integrations,

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

@@ -6,12 +6,12 @@ import { CLI_VERSION } from "./version.js";
 import { connectedAccount, login, logout, refreshStoredToken } from "./auth.js";
 import { assertCliCurrent, companyLabel, connect, loadConfig, resolveConfig } from "./config.js";
 import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
-import { appRoot, readAppProfile, readKitLock, requestResourceName } from "./kit.js";
+import { appRoot, assertLockCompany, readAppProfile, readKitLock, requestResourceName } from "./kit.js";
 import { initKit } from "./starter.js";
 import { packageApp } from "./package.js";
 import { agentPaths, agentSetup } from "./agent-setup.js";
 import { detachDev, startDev } from "./dev.js";
-import { endProcess, ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
+import { endProcess, installDependencies, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
 import { CHECKS_FAILED_HINT, checksFailedMessage, runChecks } from "./check.js";
 import { assertDeployReady, companySystemsLine, GovernanceClient, groupGrants, IDENTITY_WORDS, integrationsCatalog, integrationsStatus, renderGrantGroup, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
 import { runJob } from "./jobs.js";
@@ -87,7 +87,7 @@ const emit = (value, line) => { process.stdout.write(json ? `${JSON.stringify(va
  */
 const exitAfterWriting = (code, out, err = "") => { process.stderr.write(err, () => process.stdout.write(out, () => process.exit(code))); };
 /** Exit 2, like a usage error: nothing started and the fix is a command the maker runs (or a file the maker edits). */
-const USAGE_REFUSALS = ["APP_EXISTS", "APP_UNSUPPORTED", "KIT_APP", "DEPLOY_BLOCKED", "INTEGRATIONS_NOT_READY", "AI_NOT_READY", "CLI_UPGRADE_REQUIRED", "NOT_A_MEMBER", "TENANT_AMBIGUOUS", "NOT_A_START_LINK", "PLATFORM_UNREACHABLE", "DEPLOY_IN_FLIGHT", "OPERATION_REQUIRED"];
+const USAGE_REFUSALS = ["APP_EXISTS", "APP_UNSUPPORTED", "KIT_APP", "DEPLOY_BLOCKED", "INTEGRATIONS_NOT_READY", "AI_NOT_READY", "CLI_UPGRADE_REQUIRED", "KIT_BUNDLE_STALE", "NOT_A_MEMBER", "TENANT_AMBIGUOUS", "NOT_A_START_LINK", "PLATFORM_UNREACHABLE", "DEPLOY_IN_FLIGHT", "OPERATION_REQUIRED"];
 if (command === "--version" || command === "version") {
     process.stdout.write(`${CLI_VERSION}\n`);
     // `-h` was matched anywhere in argv while `--help` was only recognised as the
@@ -138,10 +138,8 @@ else {
                 const result = await initKit(target, bundle, { upgrade, adopt, tenantId: config?.tenantId, env: process.env, displayRoot: root });
                 for (const line of [...result.created.map(path => `created ${path}`), ...result.updated.map(path => `updated ${path}`), ...result.kept.map(path => `kept    ${path}`), ...result.bundleChanges.map(change => `bundle  ${change}`), ...["created", "updated"].flatMap(state => result.agents[state].map(path => `${state} ${path} (agent guide)`))])
                     progress(line);
-                // The SDK is not on the public registry: init installs the pinned tarball (and the app's other dependencies) itself.
-                const sdk = await ensureSdk(target, bundle, process.env, runCommand, progress);
-                if (sdk === "missing")
-                    progress(`The kit SDK was not installed: set ISOMORPH_KIT_SDK_TARBALL to the bundle's ${bundle.sdk.package} tarball (or use a bundle with sdk.url), then rerun \`isomorph init\`.`);
+                // The SDK is a normal dependency: one plain `npm install` when node_modules lacks it or holds one outside the range init wrote.
+                await installDependencies(target, bundle, runCommand, progress);
                 progress(result.mode === "starter" ? "Starter created. Next: `isomorph dev --app-root <path>`. Both agents read the Isomorph block in CLAUDE.md / AGENTS.md and the `isomorph` skill installed by agent-setup."
                     : upgrade ? (result.bundleChanges.length ? "Kit bundle upgraded; running checks." : "Kit bundle already current; running checks.")
                         : result.mode === "kit" ? `This folder is already an Isomorph kit app (any missing kit file was added; nothing else was changed). Next: \`isomorph dev --app-root ${root}\`, \`isomorph check --app-root ${root}\`, \`isomorph deploy --app-root ${root}\`.`
@@ -254,7 +252,9 @@ else {
                     // from the folder (the current one unless --app-root says otherwise) and,
                     // without --operation, follow the deployment last started from it.
                     const target = appRoot(root ?? ".");
-                    const appId = (await readKitLock(target))?.appId;
+                    const lock = await readKitLock(target);
+                    assertLockCompany(lock, tenant);
+                    const appId = lock?.appId;
                     if (!appId)
                         throw new CliError("KIT_REQUIRED", `${root ? "That folder" : "The current folder"} is not a deployed Isomorph app: it has no .isomorph/kit.lock.json with an app identity.`, undefined, "Run this from the app's folder, or pass --app-root <path>.");
                     const ref = operationRef ?? (await readDeployNote(target, tenant))?.operationRef;

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

@@ -22,14 +22,15 @@ export function assertCliCurrent(config, running = CLI_VERSION) {
         return;
     throw new CliError("CLI_UPGRADE_REQUIRED", `This CLI is ${running}; the company's Isomorph platform needs ${minimum} or newer.`, undefined, `Run \`${CLI_INSTALL_COMMAND}\`, then run this again.`);
 }
+/** The numeric core and prerelease of a version string (`v1.2.3-rc.1` → `[1, 2, 3]`, `rc.1`), or `undefined` for one with no numeric core. */
+export function parseVersion(value) {
+    const match = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(value);
+    return match ? { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] } : undefined;
+}
 /** Numeric-core semver order; a prerelease sorts before its release. An unparseable version compares equal, so nothing is called stale on a guess. */
 export function compareCliVersions(left, right) {
-    const parse = (value) => {
-        const match = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(value);
-        return match ? { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] } : undefined;
-    };
-    const a = parse(left);
-    const b = parse(right);
+    const a = parseVersion(left);
+    const b = parseVersion(right);
     if (!a || !b)
         return 0;
     for (let index = 0; index < 3; index += 1)

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

@@ -6,8 +6,8 @@ import { CliError } from "./output.js";
 import { continueCommand, follow, outcomeFor, pickSourceFailure, recordedRefusal, runningLine, statusFetch, summarize } from "./operations.js";
 import { CLI_VERSION } from "./version.js";
 import { assertSafeAppRoot, readAppTree } from "./package.js";
-import { deployBlocked, ensureLinkedApp } from "./integrations.js";
-import { describeSourceChange, kitPaths, readAppProfile, readDeclaration, readKitLock, sourceDigest } from "./kit.js";
+import { deployBlocked, ensureLinkedApp, kitLockBody } from "./integrations.js";
+import { assertLockCompany, describeSourceChange, kitPaths, readAppProfile, readDeclaration, readKitLock, sourceDigest } from "./kit.js";
 import { CHECKS_FAILED_HINT, checksFailedMessage, FLOW_CHECK, readReport, runChecks } from "./check.js";
 import { runCommand } from "./local-runtime.js";
 import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
@@ -50,8 +50,10 @@ async function runDeploy(rootArg, governance, output, tenantId, options) {
     assertSafeAppRoot(root);
     // Only a kit app deploys from here: the checks, the gate and the profile all
     // live in `.isomorph/`. Anything else deploys from the console.
-    if (!(await readKitLock(root)))
+    const lock = await readKitLock(root);
+    if (!lock)
         throw new CliError("KIT_REQUIRED", "This folder is not an Isomorph app: it has no .isomorph/kit.lock.json.", undefined, "Run `isomorph init --app-root .` first.");
+    assertLockCompany(lock, tenantId);
     // The three values the person confirmed, printed so the transcript shows what
     // was recorded; recorded on the operation before anything is uploaded.
     const profile = await readAppProfile(root);
@@ -91,15 +93,16 @@ async function runDeploy(rootArg, governance, output, tenantId, options) {
         output(`Isomorph is continuing operation ${note.operationRef}; no new deployment was started.`);
     // One call opens the operation — or resumes it — and runs the deploy
     // pre-flight first: a declared connection IT has not approved, a company
-    // whose AI setup is not ready for an app that calls it, or a CLI the platform
-    // no longer accepts would only park the deployment after the save, so
-    // governance refuses here, with every blocker at once, before any operation
-    // exists. The reviewed profile rides on the same call.
+    // whose AI setup is not ready for an app that calls it, a CLI the platform
+    // no longer accepts, or a kit older than the one Isomorph publishes would
+    // only park the deployment after the save, so governance refuses here, with
+    // every blocker at once, before any operation exists. The reviewed profile
+    // and the kit lock's bundle ride on the same call.
     const body = {
         environment: "preview",
         app: { name: profile.name, description: profile.description, audience: profile.audience },
         package: { sha256: archive.digest, bytes: archive.body.byteLength, manifest: { schema: "isomorph.source-package-manifest/1.0", files: manifest.files.map(file => ({ path: file.path, size: file.bytes, sha256: file.sha256 })) } },
-        graph, cliVersion: CLI_VERSION, kitBundleVersion: bundle.kitVersion, declaration, callsAi: await appCallsAi(root)
+        graph, cliVersion: CLI_VERSION, kitBundleVersion: bundle.kitVersion, declaration, callsAi: await appCallsAi(root), kitLock: kitLockBody(lock.bundle)
     };
     let opened;
     try {

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

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { createForwarder } from "./forwarder.js";
 import { readKitLock } from "./kit.js";
 import { GovernanceClient, ensureLinkedApp, fileDeclaredRequests, IDENTITY_WORDS, renderGrantGroup } from "./integrations.js";
-import { acquireDevLock, allocatePorts, ensureSdk, LocalRuntime, nodePackageCommand, pidAlive, readDevLock, recordDevChildren, releaseDevLock, runCommand } from "./local-runtime.js";
+import { acquireDevLock, allocatePorts, assertMigrationNames, installDependencies, LocalRuntime, nodePackageCommand, pidAlive, readDevLock, recordDevChildren, releaseDevLock, runCommand } from "./local-runtime.js";
 import { kitPaths } from "./kit.js";
 import { CliError, safeError } from "./output.js";
 /**
@@ -40,6 +40,7 @@ export async function startDev(root, options) {
     const run = options.run ?? runCommand;
     const env = options.env ?? process.env;
     const runtime = new LocalRuntime(root, run);
+    await assertMigrationNames(root);
     if (options.reset)
         await runtime.reset(options.output);
     const ports = await allocatePorts();
@@ -53,9 +54,7 @@ export async function startDev(root, options) {
         await releaseDevLock(root);
     };
     try {
-        const sdk = await ensureSdk(root, options.bundle, env, run, options.output);
-        if (sdk === "missing")
-            options.output(`The kit SDK is not installed: set ISOMORPH_KIT_SDK_TARBALL to the bundle's ${options.bundle.sdk.package} tarball (or use a bundle with sdk.url).`);
+        await installDependencies(root, options.bundle, run, options.output);
         await runtime.writeFiles(options.bundle, ports);
         options.output("Preparing the kit-managed native runtime (public registry, no login).");
         await runtime.pull(options.bundle);
@@ -163,6 +162,10 @@ export async function detachDev(root, options) {
         const linked = await appId();
         return { origin: running.origin, pid: running.pid, ...(linked ? { appId: linked } : {}) };
     }
+    // Refused here, not in the child: the child's refusal would come back as
+    // "dev stopped before the app answered … read dev.log", one wrap away from
+    // the reason. `--detach` is the shape every agent runs.
+    await assertMigrationNames(root);
     await mkdir(kitPaths(root).local, { recursive: true });
     const logFd = openSync(devLogPath(root), "w");
     let exited;

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

@@ -21,7 +21,7 @@ Isomorph SSO signs everyone in: no login forms, browser-trusted roles or public
 
 ## Data
 
-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):
+SQL files \`migrations/NNNN_name.sql\` (four digits, lowercase); 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):
 
 \`\`\`sql
 ALTER TABLE notes ENABLE ROW LEVEL SECURITY;
@@ -50,7 +50,7 @@ Shared-read, owner-write: the same, plus \`CREATE POLICY posts_read ON posts FOR
 - \`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.`,
+- \`APP_NOT_FOUND\`: set \`appId\` and \`tenantId\` to \`""\` in \`.isomorph/kit.lock.json\` to relink.`,
     integrations: `# Company systems (Slack, Gmail, warehouse)
 
 ## Call shape

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

@@ -2,6 +2,8 @@ import { basename } from "node:path";
 import { linkIdempotencyKey, readDeclaration, readKitLock, requestResourceName, requestResources, writeKitLock, newKitLock } from "./kit.js";
 import { CliError } from "./output.js";
 import { CLI_VERSION } from "./version.js";
+/** The lock's bundle as the preflight body carries it. */
+export const kitLockBody = (bundle) => ({ kitVersion: bundle.kitVersion, sdk: { version: bundle.sdk.version } });
 export class GovernanceClient {
     apiUrl;
     tenantId;
@@ -334,12 +336,14 @@ export function renderGrantGroup(group, nowMs = Date.now()) {
  * 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
+ * governed AI, a CLI older than the platform's minimum, and a kit older than
+ * the one Isomorph publishes. 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`).
+ * kind (`INTEGRATIONS_NOT_READY`, `AI_NOT_READY`, `CLI_UPGRADE_REQUIRED`,
+ * `KIT_BUNDLE_STALE` — the code intake records for the same refusal).
  * 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.
@@ -347,7 +351,8 @@ export function renderGrantGroup(group, nowMs = Date.now()) {
 export async function assertDeployReady(root, client, tenantId, bundle, environment, output, callsAi) {
     const declaration = await readDeclaration(root);
     const appId = await ensureLinkedApp(root, client, tenantId, bundle);
-    const preflight = await client.deployPreflight(appId, { environment, callsAi, declaration, cliVersion: CLI_VERSION });
+    const lock = await readKitLock(root);
+    const preflight = await client.deployPreflight(appId, { environment, callsAi, declaration, cliVersion: CLI_VERSION, ...(lock ? { kitLock: kitLockBody(lock.bundle) } : {}) });
     if (preflight.ready && !blockersOf(preflight.blockers).length) {
         output(`Isomorph confirmed the app can deploy to ${environment}.`);
         return appId;
@@ -375,7 +380,7 @@ export function deployBlocked(value, environment, output) {
     return 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" };
+const BLOCKER_CODES = { integration: "INTEGRATIONS_NOT_READY", ai: "AI_NOT_READY", cli: "CLI_UPGRADE_REQUIRED", kit: "KIT_BUNDLE_STALE" };
 /**
  * Splits the operations the app calls on one connection by identity mode — the
  * derived declaration's own `identity` (the gate derived it from the call's

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

@@ -1,4 +1,5 @@
 import { PUBLISHED_KIT_BUNDLE } from "./kit-bundle.manifest.js";
+import { parseVersion } from "./config.js";
 /**
  * The local stack's supporting services. Not part of the published bundle: they run only under `isomorph dev`.
  * MinIO is the exact image the pipeline's validation cell runs (data plane `transformbuild.validationMinIOImage`),
@@ -14,24 +15,35 @@ export const LOCAL_SERVICE_IMAGES = {
  * The bundle this CLI was built with: `manifest.json` of the
  * harbour-deployment-data-plane `publish-kit-bundle` artifact for the kit
  * version pinned in package.json `harbour.kitBundle`, fetched at build time
- * into `kit-bundle.manifest.ts` (the images and the tarball live in the kit's
- * public registry, `public.ecr.aws/<alias>/`, pinned by digest so no login
- * and no tag can substitute other bytes). `isomorph init` records it in the
- * app's kit.lock; `isomorph init --upgrade` shows the digest diff against it;
- * the hosted pipeline compares `sdk.tarballSha256` with the SDK it bakes.
+ * into `kit-bundle.manifest.ts` (the native runtime lives in the kit's public
+ * registry, `public.ecr.aws/<alias>/`, pinned by digest so no login and no
+ * tag can substitute other bytes; the SDK is `@isomorph.ai/app-sdk` on npm at
+ * `sdk.version`). `isomorph init` records it in the app's kit.lock and writes
+ * the SDK dependency; `isomorph init --upgrade` shows what moved and bumps the
+ * dependency range; the hosted pipeline refuses a kit.lock whose
+ * `sdk.version` is older than the SDK surface its gate drives.
  */
-export const EMBEDDED_KIT_BUNDLE = { ...PUBLISHED_KIT_BUNDLE, images: { ...LOCAL_SERVICE_IMAGES, ...PUBLISHED_KIT_BUNDLE.images } };
+export const EMBEDDED_KIT_BUNDLE = { ...PUBLISHED_KIT_BUNDLE, sdk: { package: PUBLISHED_KIT_BUNDLE.sdk.package, version: publishedSdkVersion() }, images: { ...LOCAL_SERVICE_IMAGES, ...PUBLISHED_KIT_BUNDLE.images } };
+/** The contracts type still allows a manifest without `sdk.version`; the generator refuses one, so a build that reaches here without it is a stale sync. */
+function publishedSdkVersion() {
+    const version = PUBLISHED_KIT_BUNDLE.sdk.version;
+    if (!version || !parseVersion(version))
+        throw new Error("kit-bundle.manifest.ts names no sdk.version; run `npm run kit-bundle:sync` in packages/harbour-cli");
+    return version;
+}
+/** `"^<sdk.version>"`: the dependency range `init` writes and `init --upgrade` moves. */
+export const sdkDependencyRange = (bundle) => `^${bundle.sdk.version}`;
 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.sdk && typeof record.sdk.package === "string" && typeof record.sdk.version === "string" && parseVersion(record.sdk.version) !== undefined
         && 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`. */
+/** Lines naming every version and digest that differs between two manifests, for `init --upgrade`. */
 export function bundleDiff(before, after) {
     const fields = [
         ["kitVersion", before.kitVersion, after.kitVersion],
-        ["sdk.tarballSha256", before.sdk.tarballSha256, after.sdk.tarballSha256],
+        ["sdk.version", before.sdk.version, after.sdk.version],
         ["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,28 +1,28 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "isomorph.kit-bundle/1.0",
-    "kitVersion": "0.6.0",
+    "kitVersion": "0.7.1",
     "sdk": {
         "package": "@isomorph.ai/app-sdk",
-        "version": "1.2.1",
-        "tarballSha256": "607e3896aa4116d82d0473677d38a68fecd4855a250cd44e038780290c335c67",
-        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:607e3896aa4116d82d0473677d38a68fecd4855a250cd44e038780290c335c67"
+        "version": "1.2.2",
+        "tarballSha256": "8953bb7eb6846bcddf48fd5407c098a13c8ad2cf249d702c35b5666d5af0ad53",
+        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:8953bb7eb6846bcddf48fd5407c098a13c8ad2cf249d702c35b5666d5af0ad53"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:7f7ae24c24d81cf2951ce8ae9033e252373c17f3a31299e05714103068273232",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:14803bd23b64c0ba5aa68022716c339a772ce0664c739dabda3457ec27978bb2"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:9d5510db8396cc27c509047f668b63a85ec3892db83cb658c045b2db2d7bddeb",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:aec4aa7dfc5128e31448f50088f15550846836ec7ef920368ca2d82b31dbf486"
     },
     "nativeRuntime": {
         "darwinArm64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:42705c1b74d45f08b4f926e98b7ae15bcc8688d26d1424a74cf2d03472c9b332",
-            "sha256": "42705c1b74d45f08b4f926e98b7ae15bcc8688d26d1424a74cf2d03472c9b332"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:3f4bbf08b814888f7ff64ff968362a944dfba742668927f04a331f8c4850da21",
+            "sha256": "3f4bbf08b814888f7ff64ff968362a944dfba742668927f04a331f8c4850da21"
         },
         "linuxX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:853563fb277f49eb8862ee06227d5faba8c82cb8de304357083c19d9f616fa81",
-            "sha256": "853563fb277f49eb8862ee06227d5faba8c82cb8de304357083c19d9f616fa81"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:eea2faf265666cfe46c168d42b60cd0fc5431b43a72b3f409aa63dab7fee8524",
+            "sha256": "eea2faf265666cfe46c168d42b60cd0fc5431b43a72b3f409aa63dab7fee8524"
         },
         "windowsX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:8709b4922c8c5e3ba19662999df4beb97d01fe8a8a85b32d6025088234714a50",
-            "sha256": "8709b4922c8c5e3ba19662999df4beb97d01fe8a8a85b32d6025088234714a50"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:3e1876f0ba701b838a707aa45e6cf4620e06f40aa8c855ce2a65437c752c369a",
+            "sha256": "3e1876f0ba701b838a707aa45e6cf4620e06f40aa8c855ce2a65437c752c369a"
         }
     },
     "brief": {

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

@@ -46,8 +46,29 @@ export async function readDeclaration(root) {
     return { schema: record.schema, connections };
 }
 export function isKitLock(value) {
+    return kitLockProblem(value) === undefined;
+}
+/**
+ * The first thing wrong with a lock, named, or undefined for a valid one. A
+ * builder told to relink by clearing `appId` and `tenantId` wrote `null`, then
+ * deleted the keys, and got "does not match isomorph.kit-lock/1.0" twice
+ * (bench, 2026-09-16); the refusal now says which field and what it takes.
+ */
+export function kitLockProblem(value) {
     const record = value;
-    return Boolean(record && typeof record === "object" && record.schema === "isomorph.kit-lock/1.0" && typeof record.appId === "string" && typeof record.tenantId === "string" && isKitBundle(record.bundle) && typeof record.createdAt === "string" && typeof record.updatedAt === "string");
+    if (!record || typeof record !== "object")
+        return "it is not a JSON object";
+    if (record.schema !== "isomorph.kit-lock/1.0")
+        return "`schema` must be \"isomorph.kit-lock/1.0\"";
+    for (const field of ["appId", "tenantId"])
+        if (typeof record[field] !== "string")
+            return `\`${field}\` must be a string (\"\" to relink the app, never null or absent)`;
+    if (!isKitBundle(record.bundle))
+        return "`bundle` is not a kit bundle manifest";
+    for (const field of ["createdAt", "updatedAt"])
+        if (typeof record[field] !== "string")
+            return `\`${field}\` must be a string`;
+    return undefined;
 }
 export async function readKitLock(root) {
     let raw;
@@ -64,10 +85,22 @@ export async function readKitLock(root) {
     catch {
         throw new CliError("KIT_LOCK_INVALID", ".isomorph/kit.lock.json is not valid JSON.");
     }
-    if (!isKitLock(parsed))
-        throw new CliError("KIT_LOCK_INVALID", ".isomorph/kit.lock.json does not match isomorph.kit-lock/1.0.");
+    const problem = kitLockProblem(parsed);
+    if (problem !== undefined)
+        throw new CliError("KIT_LOCK_INVALID", `.isomorph/kit.lock.json does not match isomorph.kit-lock/1.0: ${problem}.`, undefined, "Fix that field, or delete the file and run `isomorph init --app-root .` to write a fresh one.");
     return parsed;
 }
+/**
+ * A lock naming another company is refused before any request is made:
+ * governance would answer `APP_NOT_FOUND` for an app it never registered, and
+ * that reads as a lost app when it is a person connected to the wrong one of
+ * their companies (`isomorph connect` lists them as `TENANT_AMBIGUOUS`).
+ */
+export function assertLockCompany(lock, tenantId) {
+    if (!lock?.appId || !lock.tenantId || lock.tenantId === tenantId)
+        return;
+    throw new CliError("APP_NOT_FOUND", `This app is linked to company "${lock.tenantId}" (.isomorph/kit.lock.json), but you are connected to "${tenantId}".`, undefined, `Run \`isomorph connect\` for "${lock.tenantId}" to work on the app there, or set "appId" and "tenantId" to "" in .isomorph/kit.lock.json to link it to "${tenantId}" as a new app.`, undefined, { paths: [".isomorph/kit.lock.json"] });
+}
 export async function writeKitLock(root, lock) {
     const next = { ...lock, updatedAt: new Date().toISOString() };
     await mkdir(dirname(kitPaths(root).lock), { recursive: true });

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

@@ -2,8 +2,10 @@ import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { copyFile, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:net";
-import { dirname, join, relative, win32 } from "node:path";
+import { dirname, join, win32 } from "node:path";
 import { fileURLToPath } from "node:url";
+import { sdkDependencyRange } from "./kit-bundle.js";
+import { parseVersion } from "./config.js";
 import { kitPaths, projectName } from "./kit.js";
 import { CliError } from "./output.js";
 export function nodePackageCommand(tool, args, platform = process.platform, execPath = process.execPath) {
@@ -100,6 +102,21 @@ export function nativeGatewayConfig(project, ports, stateDir) {
 async function migrationNames(root) {
     return (await readdir(join(root, "migrations")).catch(() => [])).filter(name => name.endsWith(".sql")).sort();
 }
+/** The kit gate's rule for a migration file name (data plane kit_lane.go migrationNameRE), enforced here so `dev` and `check` agree. */
+const MIGRATION_NAME = /^\d{4}_[a-z0-9][a-z0-9_-]{0,95}\.sql$/;
+/**
+ * Refuses a migration the gate would refuse, before anything starts. `dev`
+ * used to apply `001_init.sql` happily and `check` then refused the same
+ * file (bench 2026-09-16, two imported prototypes): the rule is the gate's,
+ * stated in its words, at the first command that reads the folder.
+ */
+export async function assertMigrationNames(root) {
+    for (const name of await migrationNames(root)) {
+        if (MIGRATION_NAME.test(name))
+            continue;
+        throw new CliError("DEV_FAILED", `migrations/${name} must be a regular file named NNNN_name.sql (four digits, then lowercase letters, digits, _ or -).`, undefined, "Rename the file, then run this again.", undefined, { paths: [`migrations/${name}`] });
+    }
+}
 export function internalDatabaseUrl(user = LOCAL.dbUser) { return `postgresql://${user}:${LOCAL.dbPassword}@127.0.0.1/${LOCAL.database}?sslmode=disable`; }
 function uploadKey(project) { return createHash("sha256").update(`upload-key:${project}`).digest("base64"); }
 // ---- Ports and lock ------------------------------------------------------------------
@@ -467,7 +484,7 @@ async function ensureNativeGateway(root, bundle) {
     const directory = join(kitPaths(root).local, "runtime");
     const target = join(directory, `isomorph-app-gateway-${runtime.sha256.slice(0, 12)}${process.platform === "win32" ? ".exe" : ""}`);
     if (!(await exists(target))) {
-        const bytes = await downloadSdk(runtime.url);
+        const bytes = await downloadBundleBlob(runtime.url);
         const digest = createHash("sha256").update(bytes).digest("hex");
         if (digest !== runtime.sha256)
             throw new CliError("KIT_BUNDLE_INCOMPATIBLE", `The native runtime digest ${digest} does not match the kit bundle ${runtime.sha256}.`);
@@ -497,59 +514,61 @@ export function parseSessionEnv(text) {
     }
     return env;
 }
-// ---- SDK tarball ---------------------------------------------------------------------------
+// ---- Dependencies and kit bundle blobs ----------------------------------------------------
 /**
- * The SDK ships in the kit bundle, not the public registry. Stages the tarball
- * named by ISOMORPH_KIT_SDK_TARBALL or downloaded from the manifest's sdk.url under
- * `.isomorph/local/sdk/` (so package.json gets a relative `file:` dependency), checks
- * its sha256 against the bundle and installs it with the app's other dependencies.
- * Returns "present" when the staged tarball is already installed, "missing" when
- * no tarball is available and node_modules lacks the package.
+ * The app's dependencies, `@isomorph.ai/app-sdk` among them, come from the public
+ * npm registry like any package (data plane ADR 0017): one plain `npm install`,
+ * nothing staged or pinned by the kit. One rule for `init`, `dev` and `check`:
+ * install when node_modules lacks the SDK (a fresh init or clone) or holds one
+ * outside the bundle's range (`init --upgrade` moved it); otherwise nothing runs.
  */
-export async function ensureSdk(root, bundle, env, run, output, fetchImpl = fetch) {
-    const installed = await readFile(join(root, "node_modules", ...bundle.sdk.package.split("/"), "package.json")).then(() => true, () => false);
-    const stageDir = join(kitPaths(root).local, "sdk");
-    const staged = join(stageDir, `isomorph-app-sdk-${bundle.sdk.tarballSha256.slice(0, 12)}.tgz`);
-    const source = env.ISOMORPH_KIT_SDK_TARBALL?.trim();
-    if (!(await exists(staged))) {
-        let bytes;
-        if (source)
-            bytes = await readFile(source).catch(() => { throw new CliError("SDK_UNAVAILABLE", `ISOMORPH_KIT_SDK_TARBALL is not readable: ${source}`); });
-        else if (bundle.sdk.url) {
-            output(`Downloading ${bundle.sdk.package} from the kit bundle (sha256 ${bundle.sdk.tarballSha256.slice(0, 12)}…).`);
-            bytes = await downloadSdk(bundle.sdk.url, fetchImpl);
-        }
-        if (!bytes)
-            return installed ? "present" : "missing";
-        const digest = createHash("sha256").update(bytes).digest("hex");
-        if (bundle.sdk.tarballSha256 !== "unknown" && digest !== bundle.sdk.tarballSha256)
-            throw new CliError("KIT_BUNDLE_INCOMPATIBLE", `The SDK tarball digest ${digest} does not match the kit bundle ${bundle.sdk.tarballSha256}. Run \`isomorph init --upgrade\` or use the matching tarball.`);
-        await mkdir(stageDir, { recursive: true });
-        await writeFile(staged, bytes);
-    }
-    else if (installed && (await readFile(join(root, "package.json"), "utf8").catch(() => "")).includes(relative(root, staged)))
+export async function installDependencies(root, bundle, run, output) {
+    if (await sdkInstalled(root, bundle))
         return "present";
-    output(`Installing ${bundle.sdk.package} from the kit bundle.`);
-    const npm = nodePackageCommand("npm", ["install", "--no-audit", "--no-fund", relative(root, staged)]);
+    output(`Installing the app's dependencies, ${bundle.sdk.package} ${sdkDependencyRange(bundle)} among them (npm install).`);
+    const npm = nodePackageCommand("npm", ["install", "--no-audit", "--no-fund"]);
     const result = await run(npm.command, npm.args, { cwd: root, quiet: true });
     if (result.code !== 0)
-        throw new CliError("SDK_INSTALL_FAILED", `npm could not install the kit SDK tarball: ${result.stderr.trim().split("\n").at(-1) ?? "npm error"}`);
+        throw new CliError("NPM_INSTALL_FAILED", `npm install failed: ${result.stderr.trim().split("\n").at(-1) ?? "npm error"}`, undefined, "Fix the dependency problem npm names (package.json, the lockfile or the registry), then run this again.");
     return "installed";
 }
+/** Whether node_modules holds the SDK at a version inside `^<bundle.sdk.version>`: same major (0.x: same minor) and not older. */
+async function sdkInstalled(root, bundle) {
+    const manifest = await readFile(join(root, "node_modules", ...bundle.sdk.package.split("/"), "package.json"), "utf8").catch(() => undefined);
+    if (manifest === undefined)
+        return false;
+    let installed;
+    try {
+        installed = parseVersion(String(JSON.parse(manifest).version ?? ""))?.core;
+    }
+    catch {
+        return false;
+    }
+    const wanted = parseVersion(bundle.sdk.version)?.core;
+    if (!installed || !wanted)
+        return false;
+    if (installed[0] !== wanted[0] || (wanted[0] === 0 && installed[1] !== wanted[1]))
+        return false;
+    for (let index = 0; index < 3; index += 1)
+        if (installed[index] !== wanted[index])
+            return installed[index] > wanted[index];
+    return true;
+}
 /**
- * Fetches the SDK tarball from the bundle's `sdk.url`. The published bundle
- * stores it as a content-addressed OCI blob on a public registry, which answers
- * an anonymous GET with a Bearer challenge naming a token endpoint that hands
- * out pull tokens without credentials; the challenge is followed once and the
- * request repeated. Redirects (a blob served from object storage) are followed;
- * the bearer token is not forwarded across origins by fetch itself. The caller
- * verifies the bytes against `sdk.tarballSha256` — a token or a redirect can
- * change where the bytes come from, never which bytes are accepted.
+ * Fetches one of the kit bundle's blobs — the native runtime binary for this
+ * platform. The published bundle stores it as a content-addressed OCI blob on a
+ * public registry, which answers an anonymous GET with a Bearer challenge naming
+ * a token endpoint that hands out pull tokens without credentials; the challenge
+ * is followed once and the request repeated. Redirects (a blob served from
+ * object storage) are followed; the bearer token is not forwarded across origins
+ * by fetch itself. The caller verifies the bytes against the manifest's sha256 —
+ * a token or a redirect can change where the bytes come from, never which bytes
+ * are accepted.
  */
-export async function downloadSdk(url, fetchImpl = fetch) {
+export async function downloadBundleBlob(url, fetchImpl = fetch) {
     if (!/^https:\/\//.test(url))
-        throw new CliError("SDK_UNAVAILABLE", `The kit bundle's sdk.url must be https: ${url}`);
-    const attempt = (headers = {}) => fetchImpl(url, { redirect: "follow", headers }).catch(error => { throw new CliError("SDK_UNAVAILABLE", `The kit SDK tarball could not be downloaded from ${url}: ${error instanceof Error ? error.message : String(error)}`); });
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", `The kit bundle's blob URL must be https: ${url}`);
+    const attempt = (headers = {}) => fetchImpl(url, { redirect: "follow", headers }).catch(error => { throw new CliError("KIT_RUNTIME_UNAVAILABLE", `The kit runtime could not be downloaded from ${url}: ${error instanceof Error ? error.message : String(error)}`); });
     let response = await attempt();
     if (response.status === 401) {
         const challenge = parseBearerChallenge(response.headers.get("www-authenticate"));
@@ -567,7 +586,7 @@ export async function downloadSdk(url, fetchImpl = fetch) {
         }
     }
     if (!response.ok)
-        throw new CliError("SDK_UNAVAILABLE", `The kit SDK tarball could not be downloaded from ${url} (HTTP ${response.status}).`);
+        throw new CliError("KIT_RUNTIME_UNAVAILABLE", `The kit runtime could not be downloaded from ${url} (HTTP ${response.status}).`);
     return new Uint8Array(await response.arrayBuffer());
 }
 /** `Bearer realm="…",service="…",scope="…"` (RFC 6750 / distribution token auth); anything else is no challenge. */

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

@@ -1,6 +1,6 @@
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { bundleDiff } from "./kit-bundle.js";
+import { bundleDiff, sdkDependencyRange } from "./kit-bundle.js";
 import { agentSetup, MANAGED_END, MANAGED_START, upsertManagedBlock } from "./agent-setup.js";
 import { defaultAppProfile, emptyDeclaration, newKitLock, readKitLock, renderAppProfile, writeKitLock } from "./kit.js";
 import { CliError } from "./output.js";
@@ -80,8 +80,26 @@ export async function initKit(root, bundle, options = {}) {
     }
     else
         result.kept.push(".isomorph/kit.lock.json");
+    // The SDK is a normal dependency of the app's own package.json: added when an
+    // existing app lacks it (adopt), moved to the bundle's range on --upgrade,
+    // otherwise left as the app has it. The CLI runs `npm install` afterwards.
+    if (existingPackage && await ensureSdkDependency(root, existingPackage, bundle, Boolean(options.upgrade)))
+        result.updated.push("package.json");
     return result;
 }
+/** Writes `"<sdk package>": "^<sdk.version>"` into an existing package.json when it is missing, or when `move` is set and it differs; reports whether the file changed. */
+async function ensureSdkDependency(root, pkg, bundle, move) {
+    const { package: name } = bundle.sdk;
+    const range = sdkDependencyRange(bundle);
+    const current = pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+    if (current === range || (current !== undefined && !move))
+        return false;
+    if (pkg.devDependencies)
+        delete pkg.devDependencies[name];
+    pkg.dependencies = { ...pkg.dependencies, [name]: range };
+    await writeFile(join(root, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
+    return true;
+}
 function isSupportedApp(pkg) {
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     return Boolean(deps.vite && deps.react);
@@ -162,10 +180,9 @@ function starterFiles(bundle) {
         "package.json": `${JSON.stringify({
             name: "isomorph-app", private: true, version: "0.1.0", type: "module",
             scripts: { dev: "vite", build: "tsc --noEmit && vite build", preview: "vite preview" },
-            // The SDK is distributed as a tarball in the kit bundle, not from the public registry:
-            // `isomorph dev` installs it from ISOMORPH_KIT_SDK_TARBALL or the manifest's sdk.url and
-            // verifies its sha256 against .isomorph/kit.lock.json before use.
-            dependencies: { [bundle.sdk.package]: bundle.sdk.version ?? "1.0.0", react: "^18.3.1", "react-dom": "^18.3.1" },
+            // The SDK is a public npm package like the rest: `init` runs `npm install` and
+            // `.isomorph/kit.lock.json` records the bundle's SDK version for the pipeline's floor.
+            dependencies: { [bundle.sdk.package]: sdkDependencyRange(bundle), react: "^18.3.1", "react-dom": "^18.3.1" },
             devDependencies: { "@types/react": "^18.3.12", "@types/react-dom": "^18.3.1", "@vitejs/plugin-react": "^4.3.4", typescript: "^5.6.3", vite: "^5.4.11" }
         }, null, 2)}\n`,
         "tsconfig.json": `${JSON.stringify({ compilerOptions: { target: "ES2022", lib: ["ES2022", "DOM", "DOM.Iterable"], module: "ESNext", moduleResolution: "Bundler", jsx: "react-jsx", strict: true, noEmit: true, skipLibCheck: true, isolatedModules: true }, include: ["src"] }, null, 2)}\n`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Isomorph development kit CLI",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   "harbour": {
     "kitBundle": {
       "repository": "public.ecr.aws/y6t4p3i8/harbour-kit-bundle",
-      "version": "0.6.0"
+      "version": "0.7.1"
     }
   }
 }