run402 4.27.0 → 4.29.0

package/lib/command-manifest.mjs

@@ -202,6 +202,8 @@ export const COMMAND_MANIFEST = [
   { path: ["org", "use"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["11111111-2222-3333-4444-555555555555"] },
   { path: ["org", "current"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "clear"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
+  { path: ["org", "bind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--org", "11111111-2222-3333-4444-555555555555"] },
+  { path: ["org", "unbind"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
   { path: ["org", "member", "list"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1"] },
   { path: ["org", "member", "add"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--wallet", "0x1111111111111111111111111111111111111111"] },
   { path: ["org", "member", "role"], positionals: [p("org_id")], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["org_gate1", "--principal", "prn_gate1", "--role", "viewer"] },

package/lib/deploy-v2.mjs

@@ -25,6 +25,7 @@
 import { existsSync, fstatSync, readFileSync } from "node:fs";
 import { resolve, dirname, extname, isAbsolute } from "node:path";
 import {
+  applyWithGitvault,
   buildDeployResolveSummary,
   githubActionsCredentials,
   loadDeployManifest,
@@ -1241,17 +1242,52 @@ async function applyCmd(args) {
     const requiredPlan = opts.mode && opts.mode.kind === "applyReviewed"
       ? { planId: opts.mode.planId, ...(opts.mode.planFingerprint ? { planFingerprint: opts.mode.planFingerprint } : {}) }
       : undefined;
-    const result = await withAutoApprove(() =>
-      getSdk(sdkOpts)._applyEngine.apply(releaseSpec, {
-        onEvent: makeStderrEventWriter(opts.quiet),
-        idempotencyKey,
-        allowWarnings: opts.allowWarnings,
-        allowWarningCodes: opts.allowWarningCodes,
-        ...(requiredPlan ? { requiredPlan } : {}),
+    // A thin shim over the SDK lane (add-gitvault 5.0). `applyWithGitvault`
+    // takes the project's `gitvault_policy` into account: a project that is
+    // not `required` runs the same `apply()` this line always ran, with the
+    // same options object; a `required` one captures, publishes, mints an
+    // activation token, and commits with it.
+    const outcome = await withAutoApprove(() =>
+      applyWithGitvault({
+        sdk: getSdk(sdkOpts),
+        spec: releaseSpec,
+        apply: {
+          onEvent: makeStderrEventWriter(opts.quiet),
+          idempotencyKey,
+          allowWarnings: opts.allowWarnings,
+          allowWarningCodes: opts.allowWarningCodes,
+          ...(requiredPlan ? { requiredPlan } : {}),
+        },
         target: isCoreApiTarget() ? "core" : "cloud",
+        // The `gitvault_commit` line is printed ALWAYS, and to stderr, so
+        // `run402 deploy apply | jq` stays clean (the pipe contract).
+        onCommitLine: (line) => { if (!opts.quiet) process.stderr.write(`${line}\n`); },
       }),
     );
-    console.log(JSON.stringify(result, null, 2));
+    if (!outcome.gitvault) {
+      console.log(JSON.stringify(outcome.deploy, null, 2));
+      return;
+    }
+    const vaulted = outcome.gitvault;
+    // Both `DEPLOYED_*` outcomes activated a release; the override one just
+    // did it without a vaulted capture and carries a draining advisory.
+    const activated = vaulted.outcome === "DEPLOYED_AND_VAULTED" || vaulted.outcome === "DEPLOYED_UNVAULTED_OVERRIDE";
+    console.log(JSON.stringify({
+      ok: activated,
+      outcome: vaulted.outcome,
+      gitvault_commit: vaulted.gitvault_commit,
+      capture_id: vaulted.capture_id,
+      operation_id: vaulted.operation_id,
+      ...("generation" in vaulted ? { generation: vaulted.generation } : {}),
+      ...("push_error" in vaulted ? { push_error: vaulted.push_error } : {}),
+      ...("deploy_error" in vaulted ? { deploy_error: vaulted.deploy_error } : {}),
+      next_actions: vaulted.next_actions,
+      deploy: outcome.deploy,
+    }, null, 2));
+    // A non-activating outcome is a failed deploy even though it resolved
+    // rather than threw: the five outcomes are a result type, not an error
+    // channel, so the exit code has to carry the verdict.
+    if (!activated) process.exit(1);
   } catch (err) {
     reportDeployApplyError(err, useGithubActionsOidc);
   }
@@ -1348,89 +1384,24 @@ const CI_DEPLOY_ERROR_GUIDANCE = {
   },
 };
 
+/**
+ * The gitvault advisory rewrite is RETIRED (change `gitvault-deploy-lane`,
+ * design D4). `GITVAULT_DEPLOY_LANE = "unsupported"` and the client-side
+ * rewrite of `GITVAULT_CLIENT_UPGRADE_REQUIRED` existed only for as long as no
+ * published client could satisfy `gitvault_policy: required`. This one can:
+ * `applyCmd` deploys through `applyWithGitvault`, which declares
+ * `{capture_id, snapshot_oid_hmac}` at plan time and presents an activation
+ * token at commit. The gateway's envelope — `upgrade_client` first, then
+ * `grandfather_policy` — is now TRUE as written, so it is relayed untouched;
+ * re-authoring it here would be the client lying in the opposite direction.
+ * `cli-deploy-gitvault-lane.test.mjs` is the successor gate.
+ */
 function reportDeployApplyError(err, useGithubActionsOidc) {
-  const warningEnhanced = enhanceGitvaultDeployError(enhanceDeployWarningError(err));
+  const warningEnhanced = enhanceDeployWarningError(err);
   if (!useGithubActionsOidc) return reportSdkError(warningEnhanced);
   return reportSdkError(enhanceCiDeployError(warningEnhanced));
 }
 
-/**
- * Whether THIS client's deploy lane speaks the gitvault protocol.
- *
- * `"unsupported"` is a statement of fact about the code in this file: it
- * declares no capture at plan time and sends no gitvault block on commit, so a
- * project with `gitvault_policy: required` refuses its commits. The vault
- * itself works — `run402 gitvault push` and `git push run402` publish captures
- * — it is the DEPLOY lane that has no capture wiring.
- *
- * RETIREMENT CONDITION: flip this to `"supported"` in the same change that
- * makes `applyCmd` declare `{capture_id, snapshot_oid_hmac}` on
- * `POST /apply/v1/plans` and present an activation token on
- * `POST /apply/v1/plans/:id/commit` (protocol §6.5). Doing that faithfully also
- * means building the deploy artifacts from an isolated materialization of the
- * snapshot commit, which is why it is a design change and not a wiring one:
- * build output is normally gitignored, so it is not in the snapshot at all.
- * `cli-deploy-gitvault-advisory.test.mjs` fails if the flag and the advisory
- * ever disagree.
- */
-export const GITVAULT_DEPLOY_LANE = "unsupported";
-
-/**
- * Tell the truth about a deploy the vault gate refused.
- *
- * The gateway's `GITVAULT_CLIENT_UPGRADE_REQUIRED` envelope leads with
- * `upgrade_client` / `npm i -g run402@latest`, which is correct in principle
- * and WRONG right now: no published `run402` has a gitvault-capable deploy
- * lane, so upgrading changes nothing about this refusal (dogfood #1, finding
- * C). Relaying it unedited sends an agent into an upgrade loop. The gateway's
- * SECOND action — grandfather the policy — is real and reachable, and this
- * client now has the verb for it.
- *
- * The gateway's own actions are PRESERVED, never dropped: they are re-ordered
- * behind an honest one, and the upgrade action keeps its place with its
- * promise corrected. When the lane ships, the flag above retires this whole
- * function's rewrite and the envelope passes through untouched.
- */
-export function enhanceGitvaultDeployError(err) {
-  const body = err?.body && typeof err.body === "object" && !Array.isArray(err.body) ? err.body : {};
-  const code = body.code || err?.code || null;
-  if (code !== "GITVAULT_CLIENT_UPGRADE_REQUIRED") return err;
-  if (GITVAULT_DEPLOY_LANE === "supported") return err;
-
-  const gatewayActions = Array.isArray(body.next_actions) ? body.next_actions : [];
-  const enhanced = Object.assign(new Error(err?.message || body.message || code), err);
-  enhanced.body = {
-    ...body,
-    hint:
-      "This project requires a vaulted capture on deploy, and this run402 CLI's deploy lane does not produce one — " +
-      "upgrading the CLI does not currently fix it. Either grandfather the policy (owner + step-up) and deploy, or " +
-      "keep the project vaulted and deploy later. Your source can still be vaulted today: `run402 gitvault push` and " +
-      "`git push run402 <branch>` are not gated on a deploy.",
-    next_actions: [
-      editRequestAction(
-        "run402 gitvault policy grandfathered --reason \"<why>\"",
-        "Un-gate this project so deploys activate without a vaulted capture. Owner + step-up, audited, and it leaves a doctor-persistent warning until you return the project to `required`.",
-      ),
-      editRequestAction(
-        "run402 gitvault push",
-        "Capture and publish your source into the vault. Independent of deploy — a vault-only project pushes for months without one.",
-      ),
-      editRequestAction(
-        "run402 gitvault policy required",
-        "Restore the gate once a gitvault-capable deploy lane is available.",
-      ),
-      // Preserved verbatim in shape, with the promise corrected: the gateway
-      // is describing the eventual client, not one you can install today.
-      ...gatewayActions.map((action) =>
-        action?.type === "upgrade_client"
-          ? { ...action, why: "Tracks the eventual gitvault-capable deploy lane. No published run402 has one yet, so this does not resolve the refusal today." }
-          : action,
-      ),
-    ],
-  };
-  return enhanced;
-}
-
 function enhanceDeployWarningError(err) {
   const existingBody = err?.body && typeof err.body === "object" && !Array.isArray(err.body)
     ? err.body

package/lib/init.mjs

@@ -627,6 +627,29 @@ export async function run(args = []) {
     }
   }
 
+  // 5b. The org. `init` already materializes it (the tier read above
+  // authenticates, which provisions the wallet's org-of-one), so NOT reporting
+  // it forced every agent that wanted to coordinate to go find it with a second
+  // command and copy a UUID by hand. It is an identifier, not a credential.
+  try {
+    const orgs = await getSdk().orgs.list();
+    const rows = Array.isArray(orgs) ? orgs : (orgs?.orgs ?? []);
+    summary.orgs = rows.map((o) => ({
+      org_id: o.org_id,
+      display_name: o.display_name ?? null,
+      role: o.role ?? null,
+    }));
+    if (rows.length === 1) {
+      line("Org", `${rows[0].org_id}${rows[0].display_name ? ` (${rows[0].display_name})` : ""}`);
+    } else if (rows.length > 1) {
+      line("Org", `${rows.length} organizations — run402 org list`);
+    }
+  } catch {
+    // Best-effort, exactly like the billing read: a listing failure must never
+    // fail setup.
+    summary.orgs = null;
+  }
+
   // 6. Next step — canonical typed action(s); `next_step` is the back-compat
   // string mirror of the first action's command (one spelling, surface-wide).
   write("");

package/lib/org-context.mjs

@@ -258,6 +258,11 @@ export async function resolveOrgId(a, opts = {}) {
   return resolved ? resolved.orgId : null;
 }
 
+/** Validate an org id supplied by a human, naming the origin. Throws via fail(). */
+export function requireOrgIdShape(orgId, origin = "--org") {
+  return assertOrgIdShape(orgId, origin);
+}
+
 /** The profile's selected organization, without running the chain. */
 export function getSelectedOrgId() {
   return trimmed(coreGetActiveOrgId());

package/lib/org.mjs

@@ -1,6 +1,9 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
+import { readBindingFile, updateBindingFile } from "./wallet-context.mjs";
+import { nextAction } from "./next-actions.mjs";
 import {
+  requireOrgIdShape,
   resolveOrg,
   orgProvenance,
   getSelectedOrgId,
@@ -31,6 +34,8 @@ Usage:
   run402 org use     <org_id>
   run402 org current
   run402 org clear
+  run402 org bind   [--org <org_id>] [--room <key>]
+  run402 org unbind
   run402 org audit  <org_id> [--limit N] [--after <cursor>] [--before <cursor>]
   run402 org member list <org_id>
   run402 org member add  <org_id> --wallet <wallet_address> [--role <role>]
@@ -51,6 +56,8 @@ Subcommands:
   use         Select the current org for this wallet profile
   current     Report the resolved current org and where it came from
   clear       Clear this wallet profile's org selection
+  bind        Write this checkout's org (+room) into .run402.json — commit it
+  unbind      Remove the org/room keys from .run402.json
   payout-wallet  Set or clear the tenant route payout wallet (admin+)
   whoami      Resolved principal + org memberships (GET /agent/v1/whoami)
   member      Manage members (list, add, role, rm) — mutations require owner
@@ -239,6 +246,99 @@ async function clear(args) {
   console.log(JSON.stringify({ org_id: null, selected: false, previous_org_id: previous ?? null }, null, 2));
 }
 
+/**
+ * Slugify a directory name into a legal room key.
+ * Room keys match /^[a-z0-9][a-z0-9._-]{0,63}$/ (the DB CHECK on every
+ * agent-messaging table), so the repo's own name has to be coerced, not trusted.
+ */
+function roomKeyFromDir(dir) {
+  const base = dir.split("/").filter(Boolean).pop() ?? "";
+  const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+/, "").slice(0, 64);
+  return /^[a-z0-9]/.test(slug) ? slug : null;
+}
+
+/**
+ * Write this checkout's org (and room) into `.run402.json`.
+ *
+ * WHY THIS PICKS FOR YOU WHEN YOU OWN EXACTLY ONE ORG, while the resolution
+ * chain never does: they are different acts. The chain runs on EVERY command
+ * and must not change meaning the day you are invited to a second org — so it
+ * refuses to infer. This runs ONCE, because you asked it to, and it WRITES THE
+ * ANSWER DOWN. Nothing is inferred afterwards; the file is read verbatim
+ * forever after. An explicit act with a recorded result is not a heuristic.
+ *
+ * With two or more orgs there is nothing to pick, so it lists them and stops.
+ */
+async function bind(args) {
+  const a = normalizeArgv(args);
+  const valueFlags = ["--org", "--room"];
+  assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
+  requirePositionalCount(a, valueFlags, { min: 0, max: 0, command: "run402 org bind [--org <org_id>] [--room <key>]" });
+
+  let orgId = flagValue(a, "--org");
+  let picked = "flag";
+  if (!orgId) {
+    let orgs;
+    try {
+      orgs = await getSdk().orgs.list();
+    } catch (err) {
+      reportSdkError(err);
+      return;
+    }
+    const rows = Array.isArray(orgs) ? orgs : (orgs?.orgs ?? []);
+    if (rows.length === 0) {
+      fail({
+        code: "NO_ORGS",
+        message: "This wallet is a member of no organization yet.",
+        hint: "Run 'run402 init' to provision one, or ask an owner to add you with 'run402 org member add'.",
+        next_actions: [nextAction("initialize_wallet", { command: "run402 init", why: "Provision this wallet's organization, then retry." })],
+      });
+    }
+    if (rows.length > 1) {
+      fail({
+        code: "AMBIGUOUS_ORG",
+        message: `This wallet belongs to ${rows.length} organizations — name the one to bind.`,
+        hint: "run402 org bind --org <org_id>",
+        details: { orgs: rows.map((o) => ({ org_id: o.org_id, display_name: o.display_name ?? null, role: o.role ?? null })) },
+        next_actions: [nextAction("edit_request", { command: "run402 org bind --org <org_id>", why: "Name which organization this checkout coordinates in." })],
+      });
+    }
+    orgId = rows[0].org_id;
+    picked = "sole_membership";
+  }
+
+  const room = flagValue(a, "--room") ?? roomKeyFromDir(process.cwd());
+  const { contents, file } = updateBindingFile(process.cwd(), {
+    org: requireOrgIdShape(orgId, picked === "flag" ? "--org" : "org list"),
+    ...(room ? { room } : {}),
+  });
+  console.log(JSON.stringify({
+    org_id: orgId,
+    room_key: room ?? null,
+    org_source: picked,
+    file: ".run402.json",
+    path: file,
+    bound: true,
+    safe_to_commit: true,
+    note: "Safe to commit — an org id is an identifier, not a credential; authorization stays server-side.",
+    binding: contents,
+  }, null, 2));
+}
+
+async function unbind(args) {
+  const a = normalizeArgv(args);
+  assertKnownFlags(a, ["--help", "-h"]);
+  requirePositionalCount(a, [], { min: 0, max: 0, command: "run402 org unbind" });
+  const previous = readBindingFile(process.cwd());
+  const { contents, removed } = updateBindingFile(process.cwd(), { org: null, room: null });
+  console.log(JSON.stringify({
+    file: ".run402.json",
+    unbound: previous.org !== undefined || previous.room !== undefined,
+    removed,
+    binding: contents,
+  }, null, 2));
+}
+
 async function current(args) {
   const a = normalizeArgv(args);
   assertKnownFlags(a, ["--help", "-h"]);
@@ -534,6 +634,8 @@ export async function run(sub, args) {
     case "use": await use(args); break;
     case "current": await current(args); break;
     case "clear": await clear(args); break;
+    case "bind": await bind(args); break;
+    case "unbind": await unbind(args); break;
     case "audit": await audit(args); break;
     default:
       failUnknownSubcommand("org", sub);

package/lib/wallet-context.mjs

@@ -19,7 +19,7 @@
  * wallets and no flag is given, that is a hard error (not a silent pick).
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fail } from "./sdk-errors.mjs";
 import { isValidProfileName } from "../core-dist/config.js";
@@ -27,6 +27,7 @@ import { getDefaultWallet, profileExists, readMeta, profileDir } from "../core-d
 import { readAllowance } from "../core-dist/allowance.js";
 
 const DEFAULT = "default";
+const BINDING_FILE = ".run402.json";
 const GLOBAL_FLAGS = new Set(["--wallet", "--profile"]);
 // The `wallets` group is the management + escape surface — it must work even
 // when selection is ambiguous (so you can `wallets unbind`), and it validates
@@ -84,6 +85,45 @@ function readBindingKeyFrom(dir, key) {
   return null;
 }
 
+/** Path of the committed binding file for a directory. */
+export function bindingFilePath(dir = process.cwd()) {
+  return join(dir, BINDING_FILE);
+}
+
+/** Parse a directory's committed binding file, or `{}` when absent/unreadable. */
+export function readBindingFile(dir = process.cwd()) {
+  try {
+    const parsed = JSON.parse(readFileSync(bindingFilePath(dir), "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * MERGE keys into a directory's binding file. A `null` value removes its key;
+ * a file left with no keys is deleted rather than committed empty.
+ *
+ * The file is shared by tiers (`wallet` from `wallets bind`, `org`/`room` from
+ * `org bind`) and unknown keys are preserved, so one tier can never clobber
+ * another's binding — which a whole-file write did until this existed.
+ */
+export function updateBindingFile(dir, patch) {
+  const file = bindingFilePath(dir);
+  const next = { ...readBindingFile(dir) };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === null || v === undefined) delete next[k];
+    else next[k] = v;
+  }
+  if (Object.keys(next).length === 0) {
+    const existed = existsSync(file);
+    if (existed) rmSync(file, { force: true });
+    return { file, contents: null, removed: existed };
+  }
+  writeFileSync(file, JSON.stringify(next, null, 2) + "\n");
+  return { file, contents: next, removed: false };
+}
+
 /**
  * Nearest binding carrying `key`, walking up from `startDir` to the root.
  *

package/lib/wallets.mjs

@@ -32,6 +32,7 @@ import {
 } from "../core-dist/profiles.js";
 import { readAllowance, saveAllowance } from "../core-dist/allowance.js";
 import { getSdk } from "./sdk.mjs";
+import { readBindingFile, updateBindingFile } from "./wallet-context.mjs";
 
 const DEFAULT = "default";
 const PRIVATE_KEY_RE = /^0x[0-9a-fA-F]{64}$/;
@@ -208,14 +209,15 @@ async function cmdRename(args) {
 function cmdBind(args) {
   let name = args.find((a) => a && !a.startsWith("-"));
   name = name ? requireName(name) : getActiveProfile();
-  const file = join(process.cwd(), ".run402.json");
-  writeFileSync(file, JSON.stringify({ wallet: name }, null, 2) + "\n");
+  // MERGE, never clobber: the same file carries `org`/`room` from `org bind`.
+  const { contents } = updateBindingFile(process.cwd(), { wallet: name });
   const result = {
     wallet: name,
     file: ".run402.json",
     bound: true,
     safe_to_commit: true,
     note: "Safe to commit — contains no secrets, only the wallet name.",
+    binding: contents,
   };
   if (name !== DEFAULT && !profileExists(name)) {
     result.warning = `No local wallet named '${name}' yet — create it with 'run402 wallets new ${name}'.`;
@@ -224,10 +226,12 @@ function cmdBind(args) {
 }
 
 function cmdUnbind() {
-  const file = join(process.cwd(), ".run402.json");
-  const existed = existsSync(file);
-  if (existed) rmSync(file, { force: true });
-  out({ file: ".run402.json", unbound: existed });
+  // Removes only the WALLET key. An `org`/`room` binding in the same file
+  // belongs to another tier and must survive; the file is deleted only when
+  // unbinding leaves nothing behind.
+  const had = readBindingFile(process.cwd()).wallet !== undefined;
+  const { contents, removed } = updateBindingFile(process.cwd(), { wallet: null });
+  out({ file: ".run402.json", unbound: had, removed, binding: contents });
 }
 
 async function cmdImport(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.27.0",
+  "version": "4.29.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {

package/sdk/dist/namespaces/deploy.d.ts

@@ -19,7 +19,7 @@
  * behavior; this file is the implementation.
  */
 import type { Client } from "../kernel.js";
-import type { ApplyOptions, ActiveReleaseInventory, DeployEvent, DeployEventsResponse, DeployListOptions, DeployListResponse, DeployOperation, DeployResult, DeployResolveOptions, DeployResolveResponse, EdgeCoherenceReport, EdgeCoherenceWaitOptions, EdgeCoherenceWaitResult, OperationSnapshot, PlanResponse, PromoteOptions, PromoteResult, ReleaseDiffOptions, ReleaseInventory, ReleaseInventoryByIdOptions, ReleaseInventoryOptions, ReleaseSpec, ReleaseToReleaseDiff, RehearsePlanOptions, RehearsePlanResult, StartOptions } from "./deploy.types.js";
+import type { ApplyOptions, ActiveReleaseInventory, DeployEvent, DeployEventsResponse, DeployListOptions, DeployListResponse, DeployOperation, DeployResult, DeployResolveOptions, DeployResolveResponse, EdgeCoherenceReport, EdgeCoherenceWaitOptions, EdgeCoherenceWaitResult, GitvaultCommitDeclaration, GitvaultPlanDeclaration, OperationSnapshot, PlanResponse, PromoteOptions, PromoteResult, ReleaseDiffOptions, ReleaseInventory, ReleaseInventoryByIdOptions, ReleaseInventoryOptions, ReleaseSpec, ReleaseToReleaseDiff, RehearsePlanOptions, RehearsePlanResult, StartOptions } from "./deploy.types.js";
 export declare class Deploy {
     private readonly client;
     constructor(client: Client);
@@ -47,6 +47,8 @@ export declare class Deploy {
             planId: string;
             planFingerprint?: string;
         };
+        /** gitvault §6.5: bind this plan to a capture (see `runGitvaultDeploy`). */
+        gitvault?: GitvaultPlanDeclaration;
     }): Promise<{
         plan: PlanResponse;
         byteReaders: Map<string, ByteReader>;
@@ -76,6 +78,12 @@ export declare class Deploy {
             planId: string;
             planFingerprint?: string;
         };
+        /**
+         * gitvault §6.5: present the activation token minted for this operation,
+         * or the audited unvaulted override. A `required` project refuses a
+         * commit that carries neither.
+         */
+        gitvault?: GitvaultCommitDeclaration;
     }): Promise<DeployResult>;
     rehearse(planId: string, opts?: RehearsePlanOptions): Promise<RehearsePlanResult>;
     /**

package/sdk/dist/namespaces/deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/namespaces/deploy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/namespaces/deploy.ts"],"names":[],"mappings":"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"}

package/sdk/dist/namespaces/deploy.js

@@ -93,7 +93,12 @@ export class Deploy {
      * {@link Run402DeployError} on any state-machine failure.
      */
     async apply(spec, opts = {}) {
-        const maxRetries = normalizeApplyMaxRetries(opts.maxRetries);
+        // A gitvault-bound apply never auto-retries: each attempt plans a NEW
+        // operation, and an activation token is minted for exactly one. Retrying
+        // would either present a token bound elsewhere (the platform refuses, as
+        // it should) or demand a fresh capture, which is the caller's deliberate
+        // re-run — not something the client does behind their back.
+        const maxRetries = opts.gitvault ? 0 : normalizeApplyMaxRetries(opts.maxRetries);
         const maxAttempts = maxRetries + 1;
         const emit = makeEmitter(opts.onEvent);
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -153,6 +158,7 @@ export class Deploy {
             dryRun: opts.dryRun ?? opts.mode === "legacyDryRun",
             reviewedPlan: opts.mode === "reviewedPlan",
             requiredPlan: opts.requiredPlan,
+            ...(opts.gitvault ? { gitvault: opts.gitvault } : {}),
         });
     }
     /**
@@ -173,7 +179,7 @@ export class Deploy {
      */
     async commit(planId, opts = {}) {
         const emit = makeEmitter(opts.onEvent);
-        const commit = requireCloudCommitResponse(await commitInternal(this.client, planId, opts.idempotencyKey, opts.project, opts.requiredPlan), "committing deploy");
+        const commit = requireCloudCommitResponse(await commitInternal(this.client, planId, opts.idempotencyKey, opts.project, opts.requiredPlan, opts.gitvault), "committing deploy");
         return await pollUntilReady(this.client, commit, {}, [], emit, opts.project);
     }
     async rehearse(planId, opts = {}) {
@@ -543,11 +549,17 @@ function deriveSliceKinds(spec) {
 async function applyOnce(client, spec, opts, emit) {
     const allowWarningCodes = normalizeAllowWarningCodes(opts.allowWarningCodes);
     const target = opts.target === "core" ? "core" : "cloud";
+    if (opts.gitvault && target === "core") {
+        // Refuse rather than drop the hooks: silently committing without the
+        // activation block would activate a `required` project unvaulted.
+        throw new Run402DeployError("gitvault-bound deploys are not supported against a self-hosted Core gateway; the vault gate is a Cloud control-plane capability.", { code: "GITVAULT_UNSUPPORTED_TARGET", phase: "validate", retryable: false, context: "applying deploy" });
+    }
     const sliceKinds = deriveSliceKinds(spec);
     emit({ type: "plan.started" });
     const { plan, byteReaders } = await planInternal(client, spec, opts.idempotencyKey, {
         target,
         requiredPlan: opts.requiredPlan,
+        ...(opts.gitvault ? { gitvault: opts.gitvault.declaration } : {}),
     });
     emit({ type: "plan.diff", diff: plan.diff });
     emitPlanWarnings(plan, emit);
@@ -588,8 +600,20 @@ async function applyOnce(client, spec, opts, emit) {
         status: "started",
         ...(sliceKinds.length > 0 ? { slice_kinds: sliceKinds } : {}),
     });
-    const { planId } = requirePersistedPlan(plan, "applying deploy");
-    const commit = requireCloudCommitResponse(await commitInternal(client, planId, opts.idempotencyKey, spec.project, opts.requiredPlan), "applying deploy");
+    const { planId, operationId } = requirePersistedPlan(plan, "applying deploy");
+    // gitvault §6.5 — the handshake. Content is uploaded, so the artifacts this
+    // release ships are fixed; `authorize` verifies snapshot correspondence,
+    // mints the activation token, and hands back the commit block. It throws
+    // rather than returning when the deploy must not proceed, and nothing has
+    // been committed at that point.
+    const gitvaultCommit = opts.gitvault
+        ? await opts.gitvault.authorize({
+            plan_id: planId,
+            operation_id: operationId,
+            apply_plan_sha256: plan.gitvault?.apply_plan_sha256 ?? null,
+        })
+        : undefined;
+    const commit = requireCloudCommitResponse(await commitInternal(client, planId, opts.idempotencyKey, spec.project, opts.requiredPlan, gitvaultCommit), "applying deploy");
     const result = await pollUntilReady(client, commit, plan.diff, plan.warnings, emit, spec.project, sliceKinds);
     // v1.48 unified-apply: thread the plan response's `asset_entries[]` back
     // into DeployResult.assets so callers reading `result.assets.byKey[key]`
@@ -1013,6 +1037,11 @@ async function planInternal(client, spec, idempotencyKey, opts = {}) {
         inlineBody.mode = "reviewed_plan";
     if (opts.requiredPlan)
         inlineBody.required_plan = requiredPlanToWire(opts.requiredPlan);
+    // gitvault §6.5: the capture declaration must ride the SAME plan the gateway
+    // digests, so it is set before the inline/manifest_ref size decision below
+    // and re-attached to the manifest_ref body too.
+    if (opts.gitvault)
+        inlineBody.gitvault = opts.gitvault;
     const inlineBytes = new TextEncoder().encode(JSON.stringify(inlineBody)).byteLength;
     let body;
     if (inlineBytes <= PLAN_BODY_LIMIT_BYTES) {
@@ -1054,6 +1083,8 @@ async function planInternal(client, spec, idempotencyKey, opts = {}) {
         body = { spec: { project_id: spec.project }, manifest_ref: contentRefToWire(ref) };
         if (idempotencyKey)
             body.idempotency_key = idempotencyKey;
+        if (opts.gitvault)
+            body.gitvault = opts.gitvault;
     }
     let plan;
     try {
@@ -1431,13 +1462,15 @@ function expandCronNumberPart(part, min, max) {
     }
     return values;
 }
-async function commitInternal(client, planId, idempotencyKey, project, requiredPlan) {
+async function commitInternal(client, planId, idempotencyKey, project, requiredPlan, gitvault) {
     try {
         const body = {};
         if (idempotencyKey)
             body.idempotency_key = idempotencyKey;
         if (requiredPlan)
             body.required_plan = requiredPlanToWire(requiredPlan);
+        if (gitvault)
+            body.gitvault = gitvault;
         return await client.request(`/apply/v1/plans/${encodeURIComponent(planId)}/commit`, {
             method: "POST",
             body,