@archstone/cli 0.13.0 → 0.15.0

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { writeFileSync as writeFileSync2 } from "fs";
-import { resolve as resolve2 } from "path";
+import { writeFileSync as writeFileSync3 } from "fs";
+import { resolve as resolve3 } from "path";
 import { createRequire } from "module";
 import { createServer } from "http";
-import { load } from "@archstone/schema";
-import { validateSemantics, compile } from "@archstone/compiler";
-import { Registry, buildRegistry, serveStdio, runVerify } from "@archstone/runtime";
+import { load as load2 } from "@archstone/schema";
+import { validateSemantics as validateSemantics2, compile as compile2 } from "@archstone/compiler";
+import { Registry as Registry2, buildRegistry, serveStdio, runVerify } from "@archstone/runtime";
 import { createHttpHandler } from "@archstone/runtime/http";
 
 // src/init.ts
@@ -596,6 +596,451 @@ function runAuditCmd(argv) {
   return 0;
 }
 
+// src/doctor.ts
+import { readFileSync as readFileSync3, existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
+var ENV_INTERP = /\$\{[A-Za-z_][A-Za-z0-9_]*\}/;
+var CALLER_INTERP = /\$\{caller\./;
+function baseUrlOf(tool) {
+  return tool.connector?.rest?.baseUrl;
+}
+function diagnose(ir, manifestDir, opts = {}) {
+  const findings = [];
+  const add = (f) => findings.push(f);
+  for (const tool of ir.tools) {
+    const bound = tool.connector !== void 0;
+    if (!bound && tool.lifecycle !== "retired") {
+      add({
+        severity: "warning",
+        code: "unbound-capability",
+        capability: tool.id,
+        message: "declared but has no binding, so it is not invocable",
+        because: "A capability with no binding compiles and then does nothing. That is fine while you are drafting and a defect at go-live."
+      });
+    }
+    if (bound && !tool.contract && tool.effect === "read") {
+      add({
+        severity: "warning",
+        code: "no-contract",
+        capability: tool.id,
+        message: "bound, but records no contract fixture",
+        because: "`archstone verify` replays a recorded fixture against the live backend. With no fixture there is nothing to replay, so backend drift is found by an agent, in front of a customer, instead of by CI."
+      });
+    }
+    if (bound && !tool.contract && tool.effect !== "read") {
+      add({
+        // `advisory`, not `warning`: on a `write`/`irreversible` capability, having no contract
+        // fixture is now the CORRECT state, not a gap to close. `warning` would keep asking for
+        // the thing this advisory exists to stop recommending.
+        severity: "advisory",
+        code: "no-contract-non-read",
+        capability: tool.id,
+        message: `bound and \`${tool.effect}\`, so it records no contract fixture \u2014 and should not`,
+        because: "`archstone verify` replays a recorded fixture as a real invocation, so a fixture here would repeat this capability's effect against the live backend on every CI run. `verify` skips it by default for that reason. Where this capability has a `read` counterpart, cover the drift with that instead \u2014 the quote half of a quote \u2192 commit pair hits the same host, auth and serialization at zero risk. Not every write has one, and Archstone cannot tell you which capability it is: nothing in CDL declares that relationship. Only if this binding's `${VAR}` genuinely resolves to a sandbox tenant is recording one worthwhile, replayed with `archstone verify --sandbox`: the flag re-includes the binding, it does not make the backend safe."
+      });
+    }
+    if (tool.contract?.probeFixture) {
+      const fixture = join2(manifestDir, tool.contract.probeFixture);
+      if (!existsSync2(fixture)) {
+        add({
+          severity: "error",
+          code: "missing-fixture-file",
+          capability: tool.id,
+          message: `contract names a fixture that is not on disk: ${tool.contract.probeFixture}`,
+          because: "The contract points at a file that does not exist, so `verify` cannot run at all \u2014 a green pipeline that never checked anything."
+        });
+      }
+    }
+    if (tool.lifecycle === "retired" && tool.contract) {
+      add({
+        severity: "advisory",
+        code: "retired-with-contract",
+        capability: tool.id,
+        message: "is retired but still carries a contract fixture",
+        because: "Retired capabilities are blocked on every surface, so the fixture is dead weight \u2014 harmless, but it makes the manifest read as though the capability is still live."
+      });
+    }
+    const baseUrl = baseUrlOf(tool);
+    if (baseUrl && CALLER_INTERP.test(baseUrl)) {
+      add({
+        severity: "error",
+        code: "caller-influenced-baseurl",
+        capability: tool.id,
+        message: "baseUrl interpolates caller-supplied data",
+        because: "This is the SSRF shape: a caller who chooses part of the URL chooses where the request goes. Set `allowedHosts` on the provider, which constrains the resolved host to an allowlist."
+      });
+    } else if (baseUrl && ENV_INTERP.test(baseUrl)) {
+      add({
+        severity: "advisory",
+        code: "env-baseurl",
+        capability: tool.id,
+        message: `baseUrl comes from the environment (${baseUrl})`,
+        because: "Nothing wrong with it \u2014 but the deployment, not the manifest, decides where this capability points. Confirm the variable is set to the intended backend in every environment that runs it."
+      });
+    }
+    if (tool.effect === "irreversible") {
+      add({
+        severity: "advisory",
+        code: "irreversible-effect",
+        capability: tool.id,
+        message: "is declared `irreversible`",
+        because: (
+          // #125 (ADD-124 D-12) appends the last sentence — code and severity unchanged. Without
+          // it, this advisory and the contract advisory above land on the same capability saying
+          // opposite things ("never auto-retry" vs "wire it into CI"). Naming `verify`'s default
+          // here is what makes the two agree wherever a reader starts.
+          "No API description states this, so it was a human judgement: an agent must confirm explicitly and must never auto-retry. Re-read it before go-live \u2014 `irreversible` is the difference between looking up a price and charging a card. `archstone verify` applies the same judgement: it will not replay this capability's fixture against the live backend unless you assert a sandbox with --sandbox."
+        )
+      });
+    }
+    if (tool.policyRules?.some((r) => r.rateLimit !== void 0)) {
+      add({
+        severity: "advisory",
+        code: "ratelimit-needs-counter",
+        capability: tool.id,
+        message: "declares a rate limit, which needs a counter supplied at runtime",
+        because: "With no counter the call is denied, fail-closed, at the first invocation. On more than one instance the counter must be shared, or a declared 100/min becomes 100/min per instance."
+      });
+    }
+    if (tool.policies?.includes("authenticated")) {
+      add({
+        severity: "advisory",
+        code: "authenticated-needs-principal",
+        capability: tool.id,
+        message: "requires an authenticated caller",
+        because: "The surface serving it must carry a per-request principal \u2014 `resolveCaller` on HTTP or the embedded SDK. `archstone serve` (stdio) has one static caller for the whole process, so it cannot serve this capability to more than one identity."
+      });
+    }
+    if (tool.lifecycle === "experimental") {
+      add({
+        severity: "advisory",
+        code: "experimental-capability",
+        capability: tool.id,
+        message: "is `experimental`: hidden from tool listings but still invocable by id",
+        because: "Deliberate behaviour, and easy to forget: an agent that knows the id can still call it. Confirm that is what you want in production."
+      });
+    }
+  }
+  if (opts.builtIr !== void 0) {
+    const committed = join2(manifestDir, "archstone.ir.json");
+    if (existsSync2(committed)) {
+      const onDisk = readFileSync3(committed, "utf8");
+      if (onDisk.trim() !== opts.builtIr.trim()) {
+        add({
+          severity: "error",
+          code: "ir-drift",
+          message: "the committed archstone.ir.json does not match a fresh build of this manifest",
+          because: "The artifact is what runs. A stale one enforces stale policy and exposes stale tools, silently \u2014 rebuild it and commit the result."
+        });
+      }
+    }
+  }
+  return {
+    findings,
+    checked: ir.tools.length,
+    ok: !findings.some((f) => f.severity === "error")
+  };
+}
+var ICON = { error: "\u{1F534}", warning: "\u{1F7E1}", advisory: "\u{1F535}" };
+function formatReport2(report, dir) {
+  const lines = [`
+archstone doctor ${dir}
+`];
+  if (report.findings.length === 0) {
+    lines.push(`\u{1F7E2} ${report.checked} capabilities checked \u2014 nothing to flag.
+`);
+    return lines.join("\n");
+  }
+  const order = ["error", "warning", "advisory"];
+  for (const sev of order) {
+    for (const f of report.findings.filter((x) => x.severity === sev)) {
+      lines.push(`${ICON[sev]} ${f.capability ? `${f.capability} \u2014 ` : ""}${f.message}`);
+      lines.push(`   ${f.because}`);
+      lines.push(`   (${f.code})
+`);
+    }
+  }
+  const counts = order.map((s) => `${report.findings.filter((f) => f.severity === s).length} ${s}`).join(" \xB7 ");
+  lines.push(`${report.checked} capabilities checked \u2014 ${counts}.
+`);
+  return lines.join("\n");
+}
+
+// src/adopt.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, mkdtempSync, cpSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join as join3, resolve as resolve2 } from "path";
+import { createInterface as createInterface2 } from "readline/promises";
+import { load } from "@archstone/schema";
+import { compile, diffShape, validateSemantics } from "@archstone/compiler";
+import { Registry } from "@archstone/emitter-support";
+import { recordContract, adoptable, planAdoption } from "@archstone/runtime";
+
+// src/adopt-edit.ts
+import { yamlKey, yamlScalar } from "@archstone/init";
+function indentOf(line) {
+  return line.length - line.trimStart().length;
+}
+function locate(lines, from, to, key) {
+  const header = new RegExp(`^(\\s*)${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:\\s*(#.*)?$`);
+  const hits = [];
+  for (let i = from; i < to; i++) if (header.test(lines[i])) hits.push(i);
+  if (hits.length === 0) return { problem: `could not find a '${key}:' block to append to` };
+  if (hits.length > 1) return { problem: `found ${hits.length} '${key}:' blocks; refusing to guess which one to extend` };
+  const start = hits[0];
+  const own = indentOf(lines[start]);
+  let end = to;
+  for (let i = start + 1; i < to; i++) {
+    if (lines[i].trim() === "") continue;
+    if (indentOf(lines[i]) <= own) {
+      end = i;
+      break;
+    }
+  }
+  while (end > start + 1 && lines[end - 1].trim() === "") end--;
+  let indent = " ".repeat(own + 2);
+  for (let i = start + 1; i < end; i++) {
+    if (lines[i].trim() === "") continue;
+    indent = lines[i].slice(0, indentOf(lines[i]));
+    break;
+  }
+  return { end, indent };
+}
+function nest(lines, path) {
+  let from = 0;
+  let to = lines.length;
+  let block = { problem: "empty path" };
+  for (const key of path) {
+    block = locate(lines, from, to, key);
+    if ("problem" in block) return block;
+    to = block.end;
+    for (let i = from; i < to; i++) {
+      const header = new RegExp(`^\\s*${key}:\\s*(#.*)?$`);
+      if (header.test(lines[i])) {
+        from = i + 1;
+        break;
+      }
+    }
+  }
+  return block;
+}
+function insert(lines, at, added) {
+  return [...lines.slice(0, at), ...added, ...lines.slice(at)];
+}
+function applyAdoption(resourceYaml, bindingYaml, edits) {
+  if (edits.length === 0) return { ok: true, resource: resourceYaml, binding: bindingYaml };
+  let resourceLines = resourceYaml.split("\n");
+  const fields = nest(resourceLines, ["resource", "fields"]);
+  if ("problem" in fields) return { ok: false, problem: `resource: ${fields.problem}` };
+  const added = [];
+  for (const e of edits) {
+    added.push(
+      `${fields.indent}${yamlKey(e.field)}:`,
+      `${fields.indent}  type: ${yamlScalar(e.semantic)}`,
+      `${fields.indent}  required: false`,
+      `${fields.indent}  description: ${yamlScalar(e.description)}`
+    );
+  }
+  resourceLines = insert(resourceLines, fields.end, added);
+  let bindingLines = bindingYaml.split("\n");
+  const map = nest(bindingLines, ["binding", "response", "map"]);
+  if ("problem" in map) return { ok: false, problem: `binding: ${map.problem}` };
+  bindingLines = insert(
+    bindingLines,
+    map.end,
+    edits.map((e) => `${map.indent}${yamlKey(e.field)}: ${yamlScalar(e.itemPath)}`)
+  );
+  return { ok: true, resource: resourceLines.join("\n"), binding: bindingLines.join("\n") };
+}
+function applyContractRecording(bindingYaml, fingerprint, shape) {
+  const lines = bindingYaml.split("\n");
+  const fpIdx = lines.findIndex((l) => /^\s*fingerprint:\s/.test(l));
+  if (fpIdx === -1) return { ok: false, problem: "binding: no contract fingerprint to update" };
+  const indent = lines[fpIdx].slice(0, indentOf(lines[fpIdx]));
+  const rendered = [
+    `${indent}fingerprint: ${yamlScalar(fingerprint)}`,
+    `${indent}shape:`,
+    // Sorted, so re-adopting against an unchanged backend is a no-op diff rather than a
+    // reshuffle a reviewer has to read.
+    ...Object.keys(shape).sort().map((k) => `${indent}  ${yamlKey(k)}: ${yamlScalar(shape[k])}`)
+  ];
+  const removeFrom = fpIdx;
+  let removeTo = fpIdx + 1;
+  const shapeIdx = lines.findIndex((l, i) => i > fpIdx && /^\s*shape:\s*$/.test(l));
+  if (shapeIdx !== -1 && lines.slice(fpIdx + 1, shapeIdx).every((l) => l.trim() === "" || l.trim().startsWith("#"))) {
+    removeTo = shapeIdx + 1;
+    const own = indentOf(lines[shapeIdx]);
+    while (removeTo < lines.length && (lines[removeTo].trim() === "" || indentOf(lines[removeTo]) > own)) removeTo++;
+    const preserved = lines.slice(fpIdx + 1, shapeIdx);
+    return {
+      ok: true,
+      binding: [...lines.slice(0, removeFrom), rendered[0], ...preserved, ...rendered.slice(1), ...lines.slice(removeTo)].join("\n")
+    };
+  }
+  return { ok: true, binding: [...lines.slice(0, fpIdx), ...rendered, ...lines.slice(fpIdx + 1)].join("\n") };
+}
+
+// src/adopt.ts
+function locateFiles(dir, tool) {
+  const res = load(dir);
+  const wanted = tool.response?.resource;
+  if (!wanted) return { problem: `${tool.id}: no response mapping \u2014 nothing to adopt into` };
+  const bare = wanted.includes(".") ? wanted.slice(wanted.lastIndexOf(".") + 1) : wanted;
+  const doc = res.resourceDocs.find((d) => d.resource.name === wanted || d.resource.name.endsWith(`.${bare}`) || d.resource.name === bare);
+  if (!doc) return { problem: `${tool.id}: could not find the file declaring resource '${wanted}'` };
+  const binding = res.bindings.find((b) => b.binding.capabilityId === tool.id);
+  if (!binding) return { problem: `${tool.id}: could not find its binding file` };
+  return { tool, resourceFile: join3(dir, doc.file), bindingFile: join3(dir, binding.file) };
+}
+function readFixture(dir, path) {
+  try {
+    return JSON.parse(readFileSync4(resolve2(dir, path), "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function confirm2(ask, question) {
+  const answer = (await ask.question(`${question} [y/N] `)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+function compilesClean(dir, resourceFile, resourceYaml, bindingFile, bindingYaml) {
+  const scratch = mkdtempSync(join3(tmpdir(), "archstone-adopt-"));
+  try {
+    cpSync(dir, scratch, { recursive: true });
+    writeFileSync2(join3(scratch, resourceFile.slice(dir.length + 1)), resourceYaml);
+    writeFileSync2(join3(scratch, bindingFile.slice(dir.length + 1)), bindingYaml);
+    const res = load(scratch);
+    if (!res.ok) return res.issues.map((i) => `${i.file}: ${i.message}`).join("; ");
+    const errors = validateSemantics(res).filter((d) => d.severity === "error");
+    if (errors.length > 0) return errors.map((e) => e.message).join("; ");
+    compile(res);
+    return void 0;
+  } catch (err) {
+    return err.message;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+async function adoptOne(dir, target, contractShape, ask) {
+  const { tool } = target;
+  const fixture = readFixture(dir, tool.contract.probeFixture);
+  if (!fixture) {
+    console.error(`  ${tool.id}: fixture not found or unreadable \u2014 nothing to replay`);
+    return 1;
+  }
+  const recording = await recordContract(tool, fixture.request, {}, {});
+  if (recording.outcome !== "green" && recording.outcome !== "yellow") {
+    console.error(`  ${tool.id}: ${recording.detail}`);
+    return 1;
+  }
+  const liveShape = recording.shape ?? {};
+  const drift = diffShape(contractShape ?? {}, liveShape);
+  const plan = planAdoption(tool, drift, new Registry(compile(load(dir))).ir.resources);
+  const offers = adoptable(plan);
+  const refused = plan.candidates.filter((c) => !c.adoptable);
+  if (refused.length > 0) {
+    console.log(`
+  ${tool.id} \u2014 not adoptable:`);
+    for (const c of refused) if (!c.adoptable) console.log(`    \xB7 ${c.path} (${c.observed}) \u2014 ${c.detail}`);
+  }
+  if (offers.length === 0) {
+    console.log(`
+  ${tool.id} \u2014 nothing to adopt.`);
+    return 0;
+  }
+  console.log(`
+  ${tool.id} \u2014 ${offers.length} field(s) the backend returns and the manifest does not declare:`);
+  for (const o of offers) console.log(`    \xB7 ${o.path} (${o.observed}) \u2192 ${o.field}: ${o.semantic}`);
+  console.log("");
+  const edits = [];
+  for (const o of offers) {
+    if (!await confirm2(ask, `  Declare ${o.field} (${o.semantic})?`)) continue;
+    const description = (await ask.question(`  Describe ${o.field} \u2014 an agent reads this to decide whether to use it:
+  > `)).trim();
+    if (description === "") {
+      console.log(`  ${o.field}: no description given \u2014 not adopted.`);
+      continue;
+    }
+    edits.push({ field: o.field, itemPath: o.itemPath, semantic: o.semantic, description });
+  }
+  if (edits.length === 0) {
+    console.log(`
+  ${tool.id} \u2014 nothing adopted.`);
+    return 0;
+  }
+  const resourceYaml = readFileSync4(target.resourceFile, "utf8");
+  const bindingYaml = readFileSync4(target.bindingFile, "utf8");
+  const applied = applyAdoption(resourceYaml, bindingYaml, edits);
+  if (!applied.ok) {
+    console.error(`  ${tool.id}: ${applied.problem}`);
+    return 1;
+  }
+  const rewritten = applyContractRecording(applied.binding, recording.fingerprint, liveShape);
+  if (!rewritten.ok) {
+    console.error(`  ${tool.id}: ${rewritten.problem}`);
+    return 1;
+  }
+  const problem = compilesClean(dir, target.resourceFile, applied.resource, target.bindingFile, rewritten.binding);
+  if (problem) {
+    console.error(`
+  ${tool.id}: the edit does not compile \u2014 nothing written.
+    ${problem}`);
+    return 1;
+  }
+  writeFileSync2(target.resourceFile, applied.resource);
+  writeFileSync2(target.bindingFile, rewritten.binding);
+  console.log(`
+  ${tool.id} \u2014 declared ${edits.map((e) => e.field).join(", ")}; contract re-recorded.`);
+  return 0;
+}
+async function runAdoptCmd(argv) {
+  const dir = argv.find((a, i) => i > 0 && !a.startsWith("-"));
+  if (!dir) {
+    console.error("usage: archstone adopt <manifest-dir>");
+    return 2;
+  }
+  const res = load(dir);
+  const errors = validateSemantics(res).filter((d) => d.severity === "error");
+  if (!res.ok || errors.length > 0) {
+    console.error(`archstone adopt ${dir}: manifest invalid \u2014 run 'archstone apply ${dir}' for details`);
+    return 2;
+  }
+  const registry = new Registry(compile(res));
+  const targets = registry.listCapabilities().filter((t) => t.contract);
+  if (targets.length === 0) {
+    console.log(`
+archstone adopt ${dir}
+
+  (no bindings declare a contract: \u2014 nothing to probe)
+`);
+    return 0;
+  }
+  console.log(`
+archstone adopt ${dir}`);
+  const rl = createInterface2({ input: process.stdin, output: process.stdout });
+  const ask = terminalAsk(rl);
+  let worst = 0;
+  try {
+    for (const tool of targets) {
+      const located = locateFiles(dir, tool);
+      if ("problem" in located) {
+        console.error(`  ${located.problem}`);
+        worst = Math.max(worst, 1);
+        continue;
+      }
+      worst = Math.max(worst, await adoptOne(dir, located, tool.contract.shape, ask));
+    }
+  } catch (err) {
+    console.error(`
+archstone adopt: no more input \u2014 nothing written. Adoption needs a person (${err.name}).`);
+    return 1;
+  } finally {
+    rl.close();
+  }
+  console.log("");
+  return worst;
+}
+
 // src/index.ts
 function cliVersion() {
   try {
@@ -610,11 +1055,11 @@ function printUsage(opts) {
     // `init` is named HERE, in the verb list, and not only in the block below it. It takes a
     // spec file rather than a manifest directory, so it cannot share the first line's shape —
     // which is exactly how it came to be missing from the one line a user actually scans.
-    "usage: archstone <apply|serve|verify|build|init|audit>\n\n       archstone <apply|serve|verify|build> <manifest-dir> [--json] [--out path]\n       archstone serve --http <manifest-dir> [--port <n>] [--token <value>]\n         bearer token: --token <value>, or the ARCHSTONE_HTTP_TOKEN env var (required \u2014 never serves open)\n       archstone init <spec-file> --out <dir>   \u2014 start here if you have no manifest yet\n       archstone audit <file...> [--since <date>] [--format summary|jsonl|csv]\n         read your own Execution audit records; nothing is uploaded (audit --help for filters)\n\n       archstone --version | --help\n\n" + INIT_USAGE
+    "usage: archstone <apply|serve|verify|build|doctor|init|adopt|audit>\n\n       archstone <apply|serve|verify|build> <manifest-dir> [--json] [--out path]\n       archstone verify <manifest-dir> [--json] [--sandbox]\n         --sandbox: also replay `write`/`irreversible` fixtures \u2014 they are skipped by default,\n         because a replay is a real invocation. Only for a backend you know is a sandbox tenant.\n       archstone serve --http <manifest-dir> [--port <n>] [--token <value>]\n         bearer token: --token <value>, or the ARCHSTONE_HTTP_TOKEN env var (required \u2014 never serves open)\n       archstone doctor <manifest-dir> [--json]  \u2014 pre-production checks, offline\n       archstone init <spec-file> --out <dir>   \u2014 start here if you have no manifest yet\n       archstone adopt <manifest-dir>\n         declare a field the backend started returning; asks before writing, needs a person\n\n       archstone audit <file...> [--since <date>] [--format summary|jsonl|csv]\n         read your own Execution audit records; nothing is uploaded (audit --help for filters)\n\n       archstone --version | --help\n\n" + INIT_USAGE
   );
 }
 function runApply(dir) {
-  const res = load(dir);
+  const res = load2(dir);
   console.log(`
 archstone apply ${dir}
 `);
@@ -643,14 +1088,14 @@ archstone apply ${dir}
     console.log(`
   \u2713 shapes valid`);
   }
-  const diags = validateSemantics(res);
+  const diags = validateSemantics2(res);
   const errors = diags.filter((d) => d.severity === "error");
   const warnings = diags.filter((d) => d.severity === "warning");
   console.log(`  semantic   ${errors.length} error(s), ${warnings.length} warning(s)`);
   for (const d of errors) console.log(`    \u2717 ${d.message}`);
   for (const d of warnings) console.log(`    \u26A0 ${d.message}`);
   const shapesAndSemanticsOk = res.ok && errors.length === 0;
-  const registry = shapesAndSemanticsOk ? new Registry(compile(res)) : void 0;
+  const registry = shapesAndSemanticsOk ? new Registry2(compile2(res)) : void 0;
   const collisions = registry?.toolNameCollisions ?? [];
   if (collisions.length > 0) {
     console.log(`
@@ -670,8 +1115,8 @@ archstone apply ${dir}
   process.exit(ok ? 0 : 1);
 }
 function runBuild(dir, outPath) {
-  const res = load(dir);
-  const diags = validateSemantics(res);
+  const res = load2(dir);
+  const diags = validateSemantics2(res);
   const errors = diags.filter((d) => d.severity === "error");
   const ok = res.ok && errors.length === 0;
   if (!ok) {
@@ -680,8 +1125,8 @@ function runBuild(dir, outPath) {
     for (const d of errors) console.error(`  - ${d.message}`);
     process.exit(1);
   }
-  const ir = compile(res);
-  const registry = new Registry(ir);
+  const ir = compile2(res);
+  const registry = new Registry2(ir);
   if (registry.toolNameCollisions.length > 0) {
     console.error(`archstone build ${dir}: refusing to write artifact \u2014 tool-name collision(s):`);
     for (const c of registry.toolNameCollisions) {
@@ -690,8 +1135,8 @@ function runBuild(dir, outPath) {
     process.exit(1);
   }
   const stripped = { ...ir, tools: ir.tools.map(({ contract: _contract, ...t }) => t) };
-  const outFile = resolve2(process.cwd(), outPath ?? "archstone.ir.json");
-  writeFileSync2(outFile, `${JSON.stringify(stripped, null, 2)}
+  const outFile = resolve3(process.cwd(), outPath ?? "archstone.ir.json");
+  writeFileSync3(outFile, `${JSON.stringify(stripped, null, 2)}
 `);
   console.log(`archstone build ${dir} \u2192 ${outFile} (${stripped.tools.length} tool(s))`);
   process.exit(0);
@@ -782,9 +1227,11 @@ async function handleHttpRequest(handler, req, res) {
   }
 }
 var HEALTH_ICON = { green: "\u{1F7E2}", yellow: "\u{1F7E1}", red: "\u{1F534}" };
-async function runVerifyCmd(dir, json) {
-  const res = load(dir);
-  const diags = validateSemantics(res);
+var SKIP_ICON = "\u23ED";
+var READ_TWIN_TIP = "  Where one of these has a `read` capability against the same backend \u2014 the quote half of a\n  quote \u2192 commit pair \u2014 verifying that instead hits the same host, auth and serialization,\n  catching most infrastructure and schema drift at zero risk. Not every write has one, and\n  Archstone cannot tell you which capability it is: nothing in CDL declares that relationship.\n  If this backend really is a sandbox tenant, pass --sandbox.";
+async function runVerifyCmd(dir, json, sandbox) {
+  const res = load2(dir);
+  const diags = validateSemantics2(res);
   const errors = diags.filter((d) => d.severity === "error");
   const ok = res.ok && errors.length === 0;
   if (!ok) {
@@ -795,29 +1242,53 @@ async function runVerifyCmd(dir, json) {
     }
     process.exit(2);
   }
-  const registry = new Registry(compile(res));
-  const reports = await runVerify(registry.listCapabilities(), dir, registry.ir.resources);
+  const registry = new Registry2(compile2(res));
+  const { results, skipped } = sandbox ? await runVerify(registry.listCapabilities(), dir, registry.ir.resources, void 0, { includeNonRead: true }) : await runVerify(registry.listCapabilities(), dir, registry.ir.resources);
+  const exitCode = results.some((r) => r.status === "red") ? 1 : 0;
   if (json) {
-    console.log(JSON.stringify({ results: reports }));
-    process.exit(reports.some((r) => r.status === "red") ? 1 : 0);
+    console.log(JSON.stringify({ results, skipped, sandbox }));
+    process.exit(exitCode);
   }
   console.log(`
 archstone verify ${dir}
 `);
-  if (reports.length === 0) {
+  if (results.length === 0 && skipped.length === 0) {
     console.log("  (no bindings declare a contract: \u2014 nothing to verify)\n");
     process.exit(0);
   }
-  for (const r of reports) {
+  for (const r of results) {
     console.log(`  ${HEALTH_ICON[r.status]} ${r.capabilityId} \u2014 ${r.detail}`);
   }
+  for (const s of skipped) {
+    console.log(`  ${SKIP_ICON} ${s.capabilityId} \u2014 ${s.detail}`);
+  }
+  if (skipped.length > 0) {
+    console.log(`
+  ${skipped.length} binding(s) were NOT verified against the backend.`);
+    console.log(READ_TWIN_TIP);
+  }
   console.log("");
-  process.exit(reports.some((r) => r.status === "red") ? 1 : 0);
+  process.exit(exitCode);
 }
 function flagArg(argv, name) {
   const idx = argv.indexOf(name);
   return { value: idx !== -1 ? argv[idx + 1] : void 0, idx };
 }
+function runDoctor(dir, json) {
+  const res = load2(dir);
+  const diags = validateSemantics2(res);
+  const errors = diags.filter((d) => d.severity === "error");
+  if (!res.ok || errors.length > 0) {
+    console.error(`archstone doctor ${dir}: manifest invalid \u2014 run 'archstone apply ${dir}' for details`);
+    process.exit(1);
+  }
+  const ir = compile2(res);
+  const stripped = { ...ir, tools: ir.tools.map(({ contract: _contract, ...t }) => t) };
+  const report = diagnose(ir, dir, { builtIr: `${JSON.stringify(stripped, null, 2)}
+` });
+  console.log(json ? JSON.stringify(report, null, 2) : formatReport2(report, dir));
+  process.exit(report.ok ? 0 : 1);
+}
 async function main() {
   const argv = process.argv.slice(2);
   if (argv.includes("--version") || argv.includes("-V")) {
@@ -830,6 +1301,7 @@ async function main() {
   }
   const json = argv.includes("--json");
   const http = argv.includes("--http");
+  const sandbox = argv.includes("--sandbox");
   const out = flagArg(argv, "--out");
   const port = flagArg(argv, "--port");
   const token = flagArg(argv, "--token");
@@ -840,7 +1312,7 @@ async function main() {
       consumed.add(f.idx + 1);
     }
   }
-  const positional = argv.filter((a, i) => !consumed.has(i) && a !== "--json" && a !== "--http");
+  const positional = argv.filter((a, i) => !consumed.has(i) && a !== "--json" && a !== "--http" && a !== "--sandbox");
   const [cmd, dir] = positional;
   if (cmd === "apply" && dir) {
     runApply(dir);
@@ -855,13 +1327,20 @@ async function main() {
     return;
   }
   if (cmd === "verify" && dir) {
-    await runVerifyCmd(dir, json);
+    await runVerifyCmd(dir, json, sandbox);
     return;
   }
   if (cmd === "build" && dir) {
     runBuild(dir, out.value);
     return;
   }
+  if (cmd === "doctor" && dir) {
+    runDoctor(dir, json);
+    return;
+  }
+  if (cmd === "adopt") {
+    process.exit(await runAdoptCmd(argv));
+  }
   if (cmd === "audit") {
     process.exit(runAuditCmd(argv));
   }