@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.2

package/dist/commands/dependencies.js.map

@@ -1 +1 @@
-{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../../src/commands/dependencies.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { loadConfig } from \"../core/config.js\";\nimport {\n  analyzeDependencies,\n  type DependencyGraph,\n  type DependencyReason,\n} from \"../core/dependencies.js\";\nimport { FleetContext } from \"../core/fleet-context.js\";\nimport { emitJson, fail, reportNoConfig } from \"../core/json.js\";\nimport { missingFeatureMessage, resolveFeature } from \"../core/repo.js\";\n\ninterface DependenciesOptions {\n  json?: boolean;\n}\n\nexport function registerDependencies(program: Command): void {\n  program\n    .command(\"dependencies\")\n    .argument(\"[featureId]\", \"active feature id; omit for the whole in-flight graph\")\n    .description(\"Show dependencies and conflicts derived from active feature artifacts\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureArg: string | undefined, opts: DependenciesOptions) => {\n      const json = opts.json === true;\n      const config = await loadConfig();\n      if (!config) {\n        reportNoConfig(json);\n        return;\n      }\n\n      const context = new FleetContext();\n      const feature = featureArg === undefined\n        ? null\n        : await resolveFeature(config.docsDir, featureArg, \"exclude\", context);\n      if (featureArg !== undefined && feature === null) {\n        // The shared miss message rather than a local one: this command resolves\n        // in `exclude` mode, so the commonest miss is an id that HAS shipped, and\n        // \"no active feature\" leaves the reader to discover that themselves. The\n        // helper reuses the context already built above, so saying so costs one\n        // enumeration this invocation has already paid for.\n        fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureArg, context));\n        return;\n      }\n\n      const graph = await analyzeDependencies(config.docsDir, feature?.id, context);\n      if (json) {\n        emitJson({\n          command: \"dependencies\",\n          docsDir: config.docsDir,\n          feature: feature?.id ?? null,\n          ...graph,\n        });\n        return;\n      }\n      printGraph(graph, feature?.id);\n    });\n}\n\nfunction reasonText(reason: DependencyReason): string {\n  return reason.kind === \"operation\"\n    ? `${reason.service} operation ${reason.operationId}`\n    : `${reason.service}/${reason.axis} ${reason.identity}`;\n}\n\nfunction printGraph(graph: DependencyGraph, featureId?: string): void {\n  const scope = featureId === undefined ? \"active features\" : `${featureId} and prerequisites`;\n  console.log(`dependencies — ${scope} (${graph.nodes.length})`);\n  console.log(`  order: ${graph.order.length === 0 ? \"(none)\" : graph.order.join(\" → \")}`);\n\n  for (const node of graph.nodes) {\n    console.log(`\\n  ${node.id}${node.dependsOn.length === 0 ? \"  (independent)\" : \"\"}`);\n    for (const edge of graph.edges.filter((candidate) => candidate.from === node.id)) {\n      console.log(`    depends on ${edge.to}`);\n      for (const reason of edge.reasons) console.log(`      - ${reasonText(reason)}`);\n    }\n  }\n\n  if (graph.conflicts.length > 0) {\n    console.log(\"\\n  conflicts\");\n    for (const conflict of graph.conflicts) {\n      const where = conflict.kind === \"requirement\"\n        ? `${conflict.service}/${conflict.axis}`\n        : conflict.service;\n      // \"added by\" vs \"changed by\": the two collisions want different fixes.\n      // Two features ADDING the same identity is usually duplicated work that\n      // should become one feature; two features CHANGING it is usually genuine\n      // parallel work whose second archive would silently overwrite the first's\n      // full text, so the losers need to be re-based, not merged.\n      const how = conflict.change === \"added\" ? \"added by\" : \"changed by\";\n      console.log(`    ! ${where} ${conflict.identity} — ${how} ${conflict.features.join(\", \")}`);\n    }\n  }\n\n  if (graph.cycles.length > 0) {\n    console.log(\"\\n  cycles\");\n    for (const cycle of graph.cycles) console.log(`    ! ${cycle.join(\" ↔ \")}`);\n  }\n}\n"]}
+{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../../src/commands/dependencies.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { loadConfig } from \"../core/envelope/config.js\";\nimport { analyzeDependencies } from \"../core/dependencies/dependencies.js\";\nimport { type DependencyGraph, type DependencyReason } from \"../core/dependencies/facts.js\";\nimport { FleetContext } from \"../core/fleet-context.js\";\nimport { emitJson, fail, reportNoConfig } from \"../core/envelope/json.js\";\nimport { missingFeatureMessage, resolveFeature } from \"../core/repo/repo.js\";\n\ninterface DependenciesOptions {\n  json?: boolean;\n}\n\nexport function registerDependencies(program: Command): void {\n  program\n    .command(\"dependencies\")\n    .argument(\"[featureId]\", \"active feature id; omit for the whole in-flight graph\")\n    .description(\"Show dependencies and conflicts derived from active feature artifacts\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureArg: string | undefined, opts: DependenciesOptions) => {\n      const json = opts.json === true;\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n\n      const context = new FleetContext();\n      const feature = featureArg === undefined\n        ? null\n        : await resolveFeature(config.docsDir, featureArg, \"exclude\", context);\n      if (featureArg !== undefined && feature === null) {\n        // The shared miss message rather than a local one: this command resolves\n        // in `exclude` mode, so the commonest miss is an id that HAS shipped, and\n        // \"no active feature\" leaves the reader to discover that themselves. The\n        // helper reuses the context already built above, so saying so costs one\n        // enumeration this invocation has already paid for.\n        fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureArg, context));\n        return;\n      }\n\n      const graph = await analyzeDependencies(config.docsDir, feature?.id, context);\n      if (json) {\n        emitJson({\n          command: \"dependencies\",\n          docsDir: config.docsDir,\n          feature: feature?.id ?? null,\n          ...graph,\n        });\n        return;\n      }\n      printGraph(graph, feature?.id);\n    });\n}\n\nfunction reasonText(reason: DependencyReason): string {\n  return reason.kind === \"operation\"\n    ? `${reason.service} operation ${reason.operationId}`\n    : `${reason.service}/${reason.axis} ${reason.identity}`;\n}\n\nfunction printGraph(graph: DependencyGraph, featureId?: string): void {\n  const scope = featureId === undefined ? \"active features\" : `${featureId} and prerequisites`;\n  console.log(`dependencies — ${scope} (${graph.nodes.length})`);\n  console.log(`  order: ${graph.order.length === 0 ? \"(none)\" : graph.order.join(\" → \")}`);\n\n  for (const node of graph.nodes) {\n    console.log(`\\n  ${node.id}${node.dependsOn.length === 0 ? \"  (independent)\" : \"\"}`);\n    for (const edge of graph.edges.filter((candidate) => candidate.from === node.id)) {\n      console.log(`    depends on ${edge.to}`);\n      for (const reason of edge.reasons) console.log(`      - ${reasonText(reason)}`);\n    }\n  }\n\n  if (graph.conflicts.length > 0) {\n    console.log(\"\\n  conflicts\");\n    for (const conflict of graph.conflicts) {\n      const where = conflict.kind === \"requirement\"\n        ? `${conflict.service}/${conflict.axis}`\n        : conflict.service;\n      // \"added by\" vs \"changed by\": the two collisions want different fixes.\n      // Two features ADDING the same identity is usually duplicated work that\n      // should become one feature; two features CHANGING it is usually genuine\n      // parallel work whose second archive would silently overwrite the first's\n      // full text, so the losers need to be re-based, not merged.\n      const how = conflict.change === \"added\" ? \"added by\" : \"changed by\";\n      console.log(`    ! ${where} ${conflict.identity} — ${how} ${conflict.features.join(\", \")}`);\n    }\n  }\n\n  if (graph.cycles.length > 0) {\n    console.log(\"\\n  cycles\");\n    for (const cycle of graph.cycles) console.log(`    ! ${cycle.join(\" ↔ \")}`);\n  }\n}\n"]}

package/dist/commands/diff/diff.js

@@ -0,0 +1,93 @@
+import { loadConfig } from "../../core/envelope/config.js";
+import { emitJson, fail, reportNoConfig } from "../../core/envelope/json.js";
+import { findingJson } from "../../core/vocabulary/report.js";
+import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "../policy/gate.js";
+import { DocsRepoUnavailableError } from "../../core/repo/state.js";
+import { FleetContext } from "../../core/fleet-context.js";
+import { resolveBase } from "../../core/diff/base-git.js";
+import { readBaseFleet } from "../../core/diff/base-state.js";
+import { readCurrentFleet } from "../../core/diff/current-state.js";
+import { victimIndex } from "../../core/diff/victims.js";
+import { computeDiff } from "../../core/diff/semantic.js";
+import { printDiff } from "./print.js";
+export function registerDiff(program) {
+    program
+        .command("diff")
+        .description("Semantic diff of the living docs against a base git ref of the docs repo — fleet-meaningful changes, with the joined victims of every removal named")
+        .requiredOption("--base <ref>", "base git ref of the docs repo (e.g. main, origin/main, a commit sha)")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (opts) => {
+        const json = opts.json === true;
+        const loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
+            return;
+        }
+        const { docsDir } = loaded.config;
+        // "services" on purpose: both sides of the diff are enumerations of the
+        // fleet, and a docsDir with no services/ has no fleet to diff.
+        if (!docsRepoReady(json, docsDir, "services"))
+            return;
+        const base = await resolveBase(docsDir, opts.base);
+        // Unlike provenance's "git will not say", diff REFUSES when git cannot
+        // answer: without the base there is no honest diff, and a silently
+        // empty base would report the whole fleet as added.
+        if (base.kind === "no-git") {
+            fail(json, "repository-unavailable", `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +
+                `loam diff reads the base state with read-only git questions (rev-parse/ls-tree/show), so it needs the docs repo ` +
+                `to be a git checkout with the base ref present. Clone the docs repo with its history, then re-run.`);
+            return;
+        }
+        if (base.kind === "no-ref") {
+            fail(json, "unknown-target", `--base ${opts.base} does not resolve to a commit in the docs repo at ${docsDir}` +
+                `${base.detail === "" ? "" : ` (${base.detail})`}. ` +
+                `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`);
+            return;
+        }
+        const context = new FleetContext();
+        let diff;
+        try {
+            const baseFleet = await readBaseFleet({ docsDir, commit: base.commit, prefix: base.prefix });
+            if (baseFleet.kind === "failed") {
+                fail(json, "repository-unavailable", `git could not list services/ at ${opts.base} in the docs repo at ${docsDir} (${baseFleet.detail}) — ` +
+                    `without the base tree there is no honest diff. Re-run once git can answer.`);
+                return;
+            }
+            const current = await readCurrentFleet(docsDir, context);
+            const victims = victimIndex({ docsDir, context, current: current.services, ambiguous: current.ambiguous });
+            diff = await computeDiff({ base: baseFleet.fleet, current, victims });
+        }
+        catch (err) {
+            if (err instanceof DocsRepoUnavailableError) {
+                reportDocsRepoError(json, err);
+                return;
+            }
+            reportRepositoryUnavailable(json, err, "the fleet could not be diffed", docsDir);
+            return;
+        }
+        // Error findings gate (the validate convention); suspended axes gate too,
+        // because an exit 0 over a diff nobody could fully read would be the
+        // "green over zero services" failure one step later.
+        if (diff.breaking || diff.summary.unreadable > 0)
+            process.exitCode = 1;
+        if (json) {
+            emitJson({
+                command: "diff",
+                docsDir,
+                base: { ref: opts.base, commit: base.commit },
+                services: diff.services.map((s) => ({
+                    id: s.id,
+                    change: s.change,
+                    findings: s.findings.map((finding) => findingJson(finding, { path: `services/${s.id}`, role: "scope" })),
+                    unreadable: s.unreadable,
+                    ...(s.ambiguous === undefined ? {} : { ambiguous: s.ambiguous }),
+                })),
+                breaking: diff.breaking,
+                summary: diff.summary,
+            });
+            return;
+        }
+        printDiff(diff, { ref: opts.base, commit: base.commit });
+    });
+}
+//# sourceMappingURL=diff.js.map

package/dist/commands/diff/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../../src/commands/diff/diff.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam diff --base <ref>` — the review lens over a docs-repo branch: what\n * changed in fleet-meaningful terms since a base git ref of the DOCS repo,\n * with the current consumers of every removal named. Read-only by\n * construction: the base state comes out of git's object store\n * (`core/diff/base-git.ts`), the current state off the working tree, and\n * nothing is written anywhere.\n *\n * Exit semantics: 0 when the diff was computed and nothing is breaking AND\n * every artifact on both sides could be read; 1 for a refusal, for any\n * error-severity finding (a removal the fleet still consumes — which is what\n * makes this a free gate on a docs-repo PR), and for a diff with suspended\n * axes — \"nobody could look\" must not exit as \"nothing changed\"\n * (`loam context` set that precedent for silent holes).\n */\nimport type { Command } from \"commander\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { emitJson, fail, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { findingJson } from \"../../core/vocabulary/report.js\";\nimport { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from \"../policy/gate.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { FleetContext } from \"../../core/fleet-context.js\";\nimport { resolveBase } from \"../../core/diff/base-git.js\";\nimport { readBaseFleet } from \"../../core/diff/base-state.js\";\nimport { readCurrentFleet } from \"../../core/diff/current-state.js\";\nimport { victimIndex } from \"../../core/diff/victims.js\";\nimport { computeDiff, type FleetDiff } from \"../../core/diff/semantic.js\";\nimport { printDiff } from \"./print.js\";\n\ninterface DiffOptions {\n  base: string;\n  json?: boolean;\n}\n\nexport function registerDiff(program: Command): void {\n  program\n    .command(\"diff\")\n    .description(\"Semantic diff of the living docs against a base git ref of the docs repo — fleet-meaningful changes, with the joined victims of every removal named\")\n    .requiredOption(\"--base <ref>\", \"base git ref of the docs repo (e.g. main, origin/main, a commit sha)\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: DiffOptions) => {\n      const json = opts.json === true;\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const { docsDir } = loaded.config;\n      // \"services\" on purpose: both sides of the diff are enumerations of the\n      // fleet, and a docsDir with no services/ has no fleet to diff.\n      if (!docsRepoReady(json, docsDir, \"services\")) return;\n\n      const base = await resolveBase(docsDir, opts.base);\n      // Unlike provenance's \"git will not say\", diff REFUSES when git cannot\n      // answer: without the base there is no honest diff, and a silently\n      // empty base would report the whole fleet as added.\n      if (base.kind === \"no-git\") {\n        fail(\n          json,\n          \"repository-unavailable\",\n          `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +\n            `loam diff reads the base state with read-only git questions (rev-parse/ls-tree/show), so it needs the docs repo ` +\n            `to be a git checkout with the base ref present. Clone the docs repo with its history, then re-run.`,\n        );\n        return;\n      }\n      if (base.kind === \"no-ref\") {\n        fail(\n          json,\n          \"unknown-target\",\n          `--base ${opts.base} does not resolve to a commit in the docs repo at ${docsDir}` +\n            `${base.detail === \"\" ? \"\" : ` (${base.detail})`}. ` +\n            `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`,\n        );\n        return;\n      }\n\n      const context = new FleetContext();\n      let diff: FleetDiff;\n      try {\n        const baseFleet = await readBaseFleet({ docsDir, commit: base.commit, prefix: base.prefix });\n        if (baseFleet.kind === \"failed\") {\n          fail(\n            json,\n            \"repository-unavailable\",\n            `git could not list services/ at ${opts.base} in the docs repo at ${docsDir} (${baseFleet.detail}) — ` +\n              `without the base tree there is no honest diff. Re-run once git can answer.`,\n          );\n          return;\n        }\n        const current = await readCurrentFleet(docsDir, context);\n        const victims = victimIndex({ docsDir, context, current: current.services, ambiguous: current.ambiguous });\n        diff = await computeDiff({ base: baseFleet.fleet, current, victims });\n      } catch (err) {\n        if (err instanceof DocsRepoUnavailableError) {\n          reportDocsRepoError(json, err);\n          return;\n        }\n        reportRepositoryUnavailable(json, err, \"the fleet could not be diffed\", docsDir);\n        return;\n      }\n\n      // Error findings gate (the validate convention); suspended axes gate too,\n      // because an exit 0 over a diff nobody could fully read would be the\n      // \"green over zero services\" failure one step later.\n      if (diff.breaking || diff.summary.unreadable > 0) process.exitCode = 1;\n      if (json) {\n        emitJson({\n          command: \"diff\",\n          docsDir,\n          base: { ref: opts.base, commit: base.commit },\n          services: diff.services.map((s) => ({\n            id: s.id,\n            change: s.change,\n            findings: s.findings.map((finding) =>\n              findingJson(finding, { path: `services/${s.id}`, role: \"scope\" }),\n            ),\n            unreadable: s.unreadable,\n            ...(s.ambiguous === undefined ? {} : { ambiguous: s.ambiguous }),\n          })),\n          breaking: diff.breaking,\n          summary: diff.summary,\n        });\n        return;\n      }\n      printDiff(diff, { ref: opts.base, commit: base.commit });\n    });\n}\n"]}

package/dist/commands/diff/print.js

@@ -0,0 +1,38 @@
+/**
+ * Human rendering for `loam diff` — per-service blocks with the shared
+ * severity glyphs, victims as detail lines, one summary line. The JSON side
+ * lives in `diff.ts` beside the envelope; this module owns only the text.
+ */
+import { SEVERITY_MARK } from "../../core/vocabulary/report.js";
+function printService(s) {
+    console.log(`\n${s.id} — ${s.change}`);
+    if (s.ambiguous !== undefined) {
+        console.log(`  ⚠ service identity ambiguous — claimed by ${s.ambiguous.join(" and ")}; ` +
+            `findings for this service are suspended, not empty`);
+    }
+    for (const u of s.unreadable) {
+        // Suspension is not silence: the reader must see that this axis was not
+        // graded, or an unreadable file reads as "nothing changed here".
+        console.log(`  ⚠ ${u.side}: ${u.path} could not be read — ${u.error}; findings on this axis are suspended, not empty`);
+    }
+    for (const f of s.findings) {
+        console.log(`  ${SEVERITY_MARK[f.severity]} ${f.code}: ${f.message}`);
+        for (const d of f.details ?? [])
+            console.log(`    - ${d}`);
+    }
+}
+export function printDiff(diff, base) {
+    console.log(`diff vs ${base.ref} (${base.commit.slice(0, 12)})`);
+    const changed = diff.services.filter((s) => s.change !== "unchanged");
+    if (changed.length === 0) {
+        console.log("  no fleet-meaningful changes");
+        return;
+    }
+    for (const s of changed)
+        printService(s);
+    const sum = diff.summary;
+    console.log(`\n${sum.added} added · ${sum.removed} removed · ${sum.modified} modified · ${sum.deprecated} deprecated` +
+        (sum.unreadable > 0 ? ` · ${sum.unreadable} unreadable` : "") +
+        (diff.breaking ? " · BREAKING" : ""));
+}
+//# sourceMappingURL=print.js.map

package/dist/commands/diff/print.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"print.js","sourceRoot":"","sources":["../../../src/commands/diff/print.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAGhE,SAAS,YAAY,CAAC,CAAc;IAClC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,CAAC,GAAG,CACT,+CAA+C,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI;YAC1E,oDAAoD,CACvD,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;QAC7B,wEAAwE;QACxE,iEAAiE;QACjE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,wBAAwB,CAAC,CAAC,KAAK,kDAAkD,CAAC,CAAC;IACzH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACtE,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,EAAE;YAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,IAAqC;IAC9E,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC;IACtE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;QAC7C,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,GAAG,CACT,KAAK,GAAG,CAAC,KAAK,YAAY,GAAG,CAAC,OAAO,cAAc,GAAG,CAAC,QAAQ,eAAe,GAAG,CAAC,UAAU,aAAa;QACvG,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,UAAU,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CACvC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Human rendering for `loam diff` — per-service blocks with the shared\n * severity glyphs, victims as detail lines, one summary line. The JSON side\n * lives in `diff.ts` beside the envelope; this module owns only the text.\n */\nimport { SEVERITY_MARK } from \"../../core/vocabulary/report.js\";\nimport type { FleetDiff, ServiceDiff } from \"../../core/diff/semantic.js\";\n\nfunction printService(s: ServiceDiff): void {\n  console.log(`\\n${s.id} — ${s.change}`);\n  if (s.ambiguous !== undefined) {\n    console.log(\n      `  ⚠ service identity ambiguous — claimed by ${s.ambiguous.join(\" and \")}; ` +\n        `findings for this service are suspended, not empty`,\n    );\n  }\n  for (const u of s.unreadable) {\n    // Suspension is not silence: the reader must see that this axis was not\n    // graded, or an unreadable file reads as \"nothing changed here\".\n    console.log(`  ⚠ ${u.side}: ${u.path} could not be read — ${u.error}; findings on this axis are suspended, not empty`);\n  }\n  for (const f of s.findings) {\n    console.log(`  ${SEVERITY_MARK[f.severity]} ${f.code}: ${f.message}`);\n    for (const d of f.details ?? []) console.log(`    - ${d}`);\n  }\n}\n\nexport function printDiff(diff: FleetDiff, base: { ref: string; commit: string }): void {\n  console.log(`diff vs ${base.ref} (${base.commit.slice(0, 12)})`);\n  const changed = diff.services.filter((s) => s.change !== \"unchanged\");\n  if (changed.length === 0) {\n    console.log(\"  no fleet-meaningful changes\");\n    return;\n  }\n  for (const s of changed) printService(s);\n  const sum = diff.summary;\n  console.log(\n    `\\n${sum.added} added · ${sum.removed} removed · ${sum.modified} modified · ${sum.deprecated} deprecated` +\n      (sum.unreadable > 0 ? ` · ${sum.unreadable} unreadable` : \"\") +\n      (diff.breaking ? \" · BREAKING\" : \"\"),\n  );\n}\n"]}

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
-import { diagnose } from "../core/doctor.js";
-import { emitJson } from "../core/json.js";
+import { diagnose } from "../core/doctor/doctor.js";
+import {} from "../core/doctor/report.js";
+import { emitJson } from "../core/envelope/json.js";
 export function registerDoctor(program) {
     program
         .command("doctor")
@@ -44,7 +45,7 @@ function writePathLabel(residue) {
             ? ["interrupted commit (unreadable)"]
             : residue.intent === null
                 ? []
-                : [`interrupted ${residue.intent.command} of ${residue.intent.feature}`]),
+                : [`interrupted ${residue.intent.command} of ${"feature" in residue.intent ? residue.intent.feature : residue.intent.target}`]),
         ...(residue.temps.length === 0 ? [] : [`${residue.temps.length} orphaned temp file(s)`]),
     ];
     return parts.length === 0 ? "clean" : parts.join(" · ");
@@ -64,7 +65,7 @@ function printDoctor(report) {
     // line above it, this is state, not a complaint. Only the findings block is
     // silent when there is nothing to say.
     const agents = report.agents;
-    console.log(`  agents        ${agents.tools.length === 0 ? "(none)" : agents.tools.join(", ")}`
+    console.log(`  agents        ${agents.tools.length === 0 ? "(none)" : agents.tools.join(", ")} · ${agents.profile}`
         + ` (${agents.toolsSource}) · ${agents.plannedFiles} files · ${agents.missingFiles.length} missing`
         + ` · ${agents.staleFiles.length} stale · AGENTS.md ${stampLabel(agents.stamp)}`);
     // The write path is state too, and its clean answer is the one worth printing

package/dist/commands/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAqB,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAM3C,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,+EAA+E,CAAC;SAC5F,MAAM,CAAC,QAAQ,EAAE,qDAAqD,CAAC;SACvE,MAAM,CAAC,KAAK,EAAE,IAAmB,EAAE,EAAE;QACpC,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;YAAE,QAAQ,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;;YAC9D,WAAW,CAAC,MAAM,CAAC,CAAC;QACzB,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;AACP,CAAC;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,KAAsC;IACxD,IAAI,CAAC,KAAK,CAAC,OAAO;QAAE,OAAO,QAAQ,CAAC;IACpC,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IAC/C,OAAO,IAAI,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,OAAkC;IACxD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,cAAc,CAAC;IAC5C,MAAM,KAAK,GAAG;QACZ,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtF,GAAG,CAAC,OAAO,CAAC,gBAAgB;YAC1B,CAAC,CAAC,CAAC,iCAAiC,CAAC;YACrC,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI;gBACvB,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,eAAe,OAAO,CAAC,MAAM,CAAC,OAAO,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7E,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,wBAAwB,CAAC,CAAC;KACzF,CAAC;IACF,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,WAAW,CAAC,MAAoB;IACvC,OAAO,CAAC,GAAG,CAAC,iBAAiB,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;IACvE,OAAO,CAAC,GAAG,CAAC,mBAAmB,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IACnF,OAAO,CAAC,GAAG,CAAC,mBAAmB,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACxG,OAAO,CAAC,GAAG,CAAC,mBAAmB,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9E,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IACxF,OAAO,CAAC,GAAG,CAAC,mBAAmB,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,CACT,0BAA0B,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CACnI,CAAC;IACF,OAAO,CAAC,GAAG,CACT,6BAA6B,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,gBAAgB,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,eAAe,MAAM,CAAC,MAAM,CAAC,cAAc,kBAAkB,CACjM,CAAC;IACF,OAAO,CAAC,GAAG,CACT,mBAAmB,MAAM,CAAC,cAAc,CAAC,UAAU,IAAI,QAAQ,MAAM,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,CACpG,CAAC;IACF,2EAA2E;IAC3E,4EAA4E;IAC5E,uCAAuC;IACvC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,OAAO,CAAC,GAAG,CACT,mBAAmB,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;UACjF,KAAK,MAAM,CAAC,WAAW,OAAO,MAAM,CAAC,YAAY,YAAY,MAAM,CAAC,YAAY,CAAC,MAAM,UAAU;UACjG,MAAM,MAAM,CAAC,UAAU,CAAC,MAAM,sBAAsB,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACjF,CAAC;IACF,8EAA8E;IAC9E,8EAA8E;IAC9E,qBAAqB;IACrB,OAAO,CAAC,GAAG,CAAC,mBAAmB,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACnE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAC5B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,OAAO,CAAC,GAAG,CAAC,OAAO,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YACrG,0EAA0E;YAC1E,uEAAuE;YACvE,oEAAoE;YACpE,OAAO,CAAC,GAAG,CAAC,cAAc,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import type { Command } from \"commander\";\nimport { diagnose, type DoctorReport } from \"../core/doctor.js\";\nimport { emitJson } from \"../core/json.js\";\n\ninterface DoctorOptions {\n  json?: boolean;\n}\n\nexport function registerDoctor(program: Command): void {\n  program\n    .command(\"doctor\")\n    .description(\"Diagnose local loam configuration and docs-repo accessibility without writing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: DoctorOptions) => {\n      const report = await diagnose();\n      if (opts.json === true) emitJson({ command: \"doctor\", ...report });\n      else printDoctor(report);\n      if (!report.healthy) process.exitCode = 1;\n    });\n}\n\nfunction yesNo(value: boolean): string {\n  return value ? \"yes\" : \"no\";\n}\n\n/**\n * The stamp as one readable token. \"absent\" and \"unstamped\" are kept apart\n * because they are different repos: the first has no AGENTS.md at all, the\n * second has one nobody has claimed a version for.\n */\nfunction stampLabel(stamp: DoctorReport[\"agents\"][\"stamp\"]): string {\n  if (!stamp.present) return \"absent\";\n  if (stamp.version === null) return \"unstamped\";\n  return `v${stamp.version}${stamp.stale ? \" (stale)\" : \"\"}`;\n}\n\n/**\n * What a killed writer left in the docs repo, as one line. \"clean\" is the\n * answer on every healthy repo, and \"(unresolved)\" keeps it apart from clean:\n * a docsDir that never resolved was never looked at.\n */\nfunction writePathLabel(residue: DoctorReport[\"writePath\"]): string {\n  if (residue === null) return \"(unresolved)\";\n  const parts = [\n    ...(residue.lock === null ? [] : [`lock held${residue.lock.stale ? \" (stale)\" : \"\"}`]),\n    ...(residue.intentUnreadable\n      ? [\"interrupted commit (unreadable)\"]\n      : residue.intent === null\n        ? []\n        : [`interrupted ${residue.intent.command} of ${residue.intent.feature}`]),\n    ...(residue.temps.length === 0 ? [] : [`${residue.temps.length} orphaned temp file(s)`]),\n  ];\n  return parts.length === 0 ? \"clean\" : parts.join(\" · \");\n}\n\nfunction printDoctor(report: DoctorReport): void {\n  console.log(`loam doctor — ${report.healthy ? \"healthy\" : \"blocked\"}`);\n  console.log(`  runtime       ${report.runtime.package}@${report.runtime.version}`);\n  console.log(`  node          ${report.runtime.node} ${report.runtime.platform}/${report.runtime.arch}`);\n  console.log(`  config        ${report.config.status}  ${report.config.path}`);\n  if (report.config.error !== null) console.log(`                ${report.config.error}`);\n  console.log(`  docsDir       ${report.docs.path ?? \"(unresolved)\"}`);\n  console.log(\n    `  access        exists ${yesNo(report.docs.exists)} · read ${yesNo(report.docs.readable)} · write ${yesNo(report.docs.writable)}`,\n  );\n  console.log(\n    `  fleet         services/ ${yesNo(report.docs.servicesDir)} · landscape ${yesNo(report.docs.landscape)} · ${report.counts.services} services · ${report.counts.activeFeatures} active features`,\n  );\n  console.log(\n    `  binding       ${report.currentService.configured ?? \"(none)\"} · ${report.currentService.status}`,\n  );\n  // The agent surface is reported whether or not it has drifted — like every\n  // line above it, this is state, not a complaint. Only the findings block is\n  // silent when there is nothing to say.\n  const agents = report.agents;\n  console.log(\n    `  agents        ${agents.tools.length === 0 ? \"(none)\" : agents.tools.join(\", \")}`\n    + ` (${agents.toolsSource}) · ${agents.plannedFiles} files · ${agents.missingFiles.length} missing`\n    + ` · ${agents.staleFiles.length} stale · AGENTS.md ${stampLabel(agents.stamp)}`,\n  );\n  // The write path is state too, and its clean answer is the one worth printing\n  // most often: a reader who has just been told the docs are half-written needs\n  // to see it go away.\n  console.log(`  write path    ${writePathLabel(report.writePath)}`);\n  if (report.findings.length > 0) {\n    console.log(\"\\n  findings\");\n    for (const finding of report.findings) {\n      console.log(`    ${finding.severity === \"blocker\" ? \"✗\" : \"⚠\"} ${finding.code}: ${finding.message}`);\n      // The fix is printed on its own indented line rather than appended to the\n      // message: what is wrong and what to type are two different sentences,\n      // and someone scanning a blocked repo reads down the `fix:` column.\n      console.log(`      fix: ${finding.fix}`);\n    }\n  }\n}\n"]}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { diagnose } from \"../core/doctor/doctor.js\";\nimport { type DoctorReport } from \"../core/doctor/report.js\";\nimport { emitJson } from \"../core/envelope/json.js\";\n\ninterface DoctorOptions {\n  json?: boolean;\n}\n\nexport function registerDoctor(program: Command): void {\n  program\n    .command(\"doctor\")\n    .description(\"Diagnose local loam configuration and docs-repo accessibility without writing\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: DoctorOptions) => {\n      const report = await diagnose();\n      if (opts.json === true) emitJson({ command: \"doctor\", ...report });\n      else printDoctor(report);\n      if (!report.healthy) process.exitCode = 1;\n    });\n}\n\nfunction yesNo(value: boolean): string {\n  return value ? \"yes\" : \"no\";\n}\n\n/**\n * The stamp as one readable token. \"absent\" and \"unstamped\" are kept apart\n * because they are different repos: the first has no AGENTS.md at all, the\n * second has one nobody has claimed a version for.\n */\nfunction stampLabel(stamp: DoctorReport[\"agents\"][\"stamp\"]): string {\n  if (!stamp.present) return \"absent\";\n  if (stamp.version === null) return \"unstamped\";\n  return `v${stamp.version}${stamp.stale ? \" (stale)\" : \"\"}`;\n}\n\n/**\n * What a killed writer left in the docs repo, as one line. \"clean\" is the\n * answer on every healthy repo, and \"(unresolved)\" keeps it apart from clean:\n * a docsDir that never resolved was never looked at.\n */\nfunction writePathLabel(residue: DoctorReport[\"writePath\"]): string {\n  if (residue === null) return \"(unresolved)\";\n  const parts = [\n    ...(residue.lock === null ? [] : [`lock held${residue.lock.stale ? \" (stale)\" : \"\"}`]),\n    ...(residue.intentUnreadable\n      ? [\"interrupted commit (unreadable)\"]\n      : residue.intent === null\n        ? []\n        : [`interrupted ${residue.intent.command} of ${\"feature\" in residue.intent ? residue.intent.feature : residue.intent.target}`]),\n    ...(residue.temps.length === 0 ? [] : [`${residue.temps.length} orphaned temp file(s)`]),\n  ];\n  return parts.length === 0 ? \"clean\" : parts.join(\" · \");\n}\n\nfunction printDoctor(report: DoctorReport): void {\n  console.log(`loam doctor — ${report.healthy ? \"healthy\" : \"blocked\"}`);\n  console.log(`  runtime       ${report.runtime.package}@${report.runtime.version}`);\n  console.log(`  node          ${report.runtime.node} ${report.runtime.platform}/${report.runtime.arch}`);\n  console.log(`  config        ${report.config.status}  ${report.config.path}`);\n  if (report.config.error !== null) console.log(`                ${report.config.error}`);\n  console.log(`  docsDir       ${report.docs.path ?? \"(unresolved)\"}`);\n  console.log(\n    `  access        exists ${yesNo(report.docs.exists)} · read ${yesNo(report.docs.readable)} · write ${yesNo(report.docs.writable)}`,\n  );\n  console.log(\n    `  fleet         services/ ${yesNo(report.docs.servicesDir)} · landscape ${yesNo(report.docs.landscape)} · ${report.counts.services} services · ${report.counts.activeFeatures} active features`,\n  );\n  console.log(\n    `  binding       ${report.currentService.configured ?? \"(none)\"} · ${report.currentService.status}`,\n  );\n  // The agent surface is reported whether or not it has drifted — like every\n  // line above it, this is state, not a complaint. Only the findings block is\n  // silent when there is nothing to say.\n  const agents = report.agents;\n  console.log(\n    `  agents        ${agents.tools.length === 0 ? \"(none)\" : agents.tools.join(\", \")} · ${agents.profile}`\n    + ` (${agents.toolsSource}) · ${agents.plannedFiles} files · ${agents.missingFiles.length} missing`\n    + ` · ${agents.staleFiles.length} stale · AGENTS.md ${stampLabel(agents.stamp)}`,\n  );\n  // The write path is state too, and its clean answer is the one worth printing\n  // most often: a reader who has just been told the docs are half-written needs\n  // to see it go away.\n  console.log(`  write path    ${writePathLabel(report.writePath)}`);\n  if (report.findings.length > 0) {\n    console.log(\"\\n  findings\");\n    for (const finding of report.findings) {\n      console.log(`    ${finding.severity === \"blocker\" ? \"✗\" : \"⚠\"} ${finding.code}: ${finding.message}`);\n      // The fix is printed on its own indented line rather than appended to the\n      // message: what is wrong and what to type are two different sentences,\n      // and someone scanning a blocked repo reads down the `fix:` column.\n      console.log(`      fix: ${finding.fix}`);\n    }\n  }\n}\n"]}

package/dist/commands/explain/explain.js

@@ -0,0 +1,151 @@
+import { emitJson, fail } from "../../core/envelope/json.js";
+import { LOAM_VERSION } from "../../core/envelope/version.js";
+import { explainSubject, firstSentence, knownSubjects, listCodes, listTerms, } from "../../core/explain/lookup.js";
+import { nearestIds } from "../../core/repo/entries.js";
+// Interpolated from the registry that owns the terms, never hand-listed: a
+// copied list beside TERMS is a list that silently trails it.
+const TERM_LIST = listTerms()
+    .map(({ term }) => term)
+    .join(", ");
+/** The listing printed when no subject is asked for — also where codes are said to come from. */
+function printTermListing(json) {
+    const terms = listTerms();
+    if (json) {
+        emitJson({ command: "explain", version: LOAM_VERSION, terms: terms.map(({ term, summary }) => ({ term, description: summary })) });
+        return;
+    }
+    console.log(`loam ${LOAM_VERSION} — the vocabulary\n`);
+    const width = Math.max(...terms.map(({ term }) => term.length));
+    for (const { term, summary } of terms)
+        console.log(`  ${term.padEnd(width)}  ${summary}`);
+    console.log("\nFinding codes come from `loam validate` and `loam verify` output; refusal codes arrive as error.code" +
+        "\nin any --json envelope. `loam explain <subject>` explains one.");
+}
+/**
+ * How much of a code's meaning the inventory shows before it stops.
+ *
+ * The term listing prints whole first sentences because there are six of them
+ * and each is under 200 characters. The code listing prints 270-odd rows whose
+ * first sentences run to 377 characters, and a row that wraps four times is a
+ * paragraph, not a line of a table — it destroys the one thing this listing is
+ * for, which is scanning names. Nothing is lost: the sentence is verbatim in
+ * `--json`, and `loam explain <code>` prints the whole entry.
+ */
+const SUMMARY_WIDTH = 72;
+/** The listing's one-line gloss: the first sentence of the meaning, cut at a word boundary if it runs long. */
+function summarize(listing) {
+    // A code graded in two tables is glossed by the FIRST table's meaning — the
+    // listing answers "what is this about", and the per-scope difference (which
+    // `explain <code>` prints in full, one block per table) is exactly the
+    // detail a one-line row cannot carry honestly.
+    const sentence = firstSentence(listing.kind === "finding" ? listing.entries[0].meaning : listing.meaning);
+    if (sentence.length <= SUMMARY_WIDTH)
+        return sentence;
+    const cut = sentence.lastIndexOf(" ", SUMMARY_WIDTH);
+    return `${sentence.slice(0, cut === -1 ? SUMMARY_WIDTH : cut)}…`;
+}
+/**
+ * `--codes`: the whole code vocabulary, the inventory that was previously
+ * enumerable only out of TypeScript unions or the 83 KB /loam-check prose.
+ * The JSON rows are the per-code answers verbatim (core/explain/lookup.ts
+ * derives `CodeListing` from `Explanation`), so a consumer can build a
+ * code-to-fix cache from one call instead of one call per code.
+ */
+function printCodeListing(json) {
+    const codes = listCodes();
+    if (json) {
+        emitJson({ command: "explain", version: LOAM_VERSION, codes });
+        return;
+    }
+    const findings = codes.filter((listing) => listing.kind === "finding");
+    const refusals = codes.filter((listing) => listing.kind === "refusal");
+    const width = Math.max(...codes.map(({ code }) => code.length));
+    const print = (group) => {
+        for (const listing of group)
+            console.log(`  ${listing.code.padEnd(width)}  ${summarize(listing)}`);
+    };
+    console.log(`loam ${LOAM_VERSION} — the code vocabulary (${findings.length} finding, ${refusals.length} refusal)\n`);
+    console.log("finding codes — graded by `loam validate` and `loam verify`, in their findings[]");
+    print(findings);
+    console.log("\nrefusal codes — the `error.code` of a --json envelope, exit 1");
+    print(refusals);
+    console.log("\n`loam explain <code>` prints one in full; `loam explain` with no argument lists the concept terms.");
+}
+function printText(subject, explanation) {
+    if (explanation.kind === "term") {
+        console.log(`${explanation.term}\n\n${explanation.paragraph}`);
+        return;
+    }
+    if (explanation.kind === "refusal") {
+        console.log(`${subject} — a refusal code (error.code in the --json envelope, exit 1)\n\n${explanation.meaning}`);
+        return;
+    }
+    // A finding: one block per table the code appears in, under the table's own
+    // column names, so the page reads as the /loam-check row it is. The
+    // severity note repeats on each scope block because it is a PER-TABLE fact:
+    // `openapi.ref-unresolved` is a warn under `--service` and an error at
+    // archive plan time, and a reader asking "does this block my archive?" must
+    // not have to guess which note belongs to which context.
+    const severities = [...new Set(explanation.entries.map((entry) => entry.severityNote))];
+    console.log(`${subject} (${severities.join("; ")})${explanation.via === undefined ? "" : ` — surfaced by \`${explanation.via}\``}`);
+    for (const entry of explanation.entries) {
+        console.log(`\n[${entry.scope}] (${entry.severityNote})`);
+        console.log(`  what it means: ${entry.meaning}`);
+        if (entry.fix !== "")
+            console.log(`  what to do: ${entry.fix}`);
+    }
+}
+export function registerExplain(program) {
+    program
+        .command("explain")
+        .argument("[subject]", `a finding code (spine.op-undefined), a refusal code (docs-busy), or a concept term (${TERM_LIST}); omit to list the terms`)
+        .description("Explain a finding code, refusal code or concept term, version-matched to this binary")
+        .option("--json", "emit the machine contract instead of the human view")
+        .option("--codes", "list every finding and refusal code this binary can explain")
+        .action((subject, opts) => {
+        const json = opts.json === true;
+        if (opts.codes === true) {
+            // Refused rather than quietly preferring one: `loam explain
+            // spine.op-undefined --codes` asks two different questions, and a
+            // caller who typed both wanted whichever one this run did NOT pick.
+            if (subject !== undefined) {
+                fail(json, "invalid-option", `--codes lists the whole vocabulary and takes no subject — drop '${subject}' for the inventory, or drop --codes to explain that one.`);
+                return;
+            }
+            printCodeListing(json);
+            return;
+        }
+        if (subject === undefined) {
+            printTermListing(json);
+            return;
+        }
+        const explanation = explainSubject(subject);
+        if (explanation === null) {
+            // The same code `show` and `instructions` use for a name that resolves
+            // to nothing, with `nearestIds` suggestions because the known set here
+            // is ~200 strings — a caller one typo away should not have to diff the
+            // whole vocabulary to find it.
+            const near = nearestIds(subject, knownSubjects());
+            fail(json, "unknown-target", `Nothing named '${subject}' — not a finding code, a refusal code, or a concept term.` +
+                (near.length > 0 ? ` Close: ${near.join(", ")}.` : "") +
+                " Run `loam explain` with no argument for the concept list; finding codes appear in `loam validate` and `loam verify` output.");
+            return;
+        }
+        if (json) {
+            emitJson({
+                command: "explain",
+                version: LOAM_VERSION,
+                subject,
+                kind: explanation.kind,
+                ...(explanation.kind === "finding"
+                    ? { entries: explanation.entries, ...(explanation.via === undefined ? {} : { via: explanation.via }) }
+                    : explanation.kind === "refusal"
+                        ? { meaning: explanation.meaning }
+                        : { term: explanation.term, paragraph: explanation.paragraph }),
+            });
+            return;
+        }
+        printText(subject, explanation);
+    });
+}
+//# sourceMappingURL=explain.js.map

package/dist/commands/explain/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/commands/explain/explain.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam explain <code|term>` — what a finding code, a refusal code or a loam\n * concept means, from the binary that emits it.\n *\n * Like `loam instructions` — and for the same reason — this command reads\n * NOTHING: no `loam.json`, no docs repo, no service, and deliberately no\n * docs-repo gate (add-command invariant 3). The vocabulary wall is hit in the\n * first minute in an unfamiliar repository, before or without wiring, and an\n * explanation that refused with `no-config` would be unreachable exactly when\n * a code is first met. The content is version-matched by construction: the\n * finding prose is parsed at runtime out of the same workflow bodies this\n * binary ships (core/explain/fix-tables.ts), so what `explain` says and what\n * /loam-check teaches cannot disagree.\n *\n * `--codes` adds the missing half: per-code lookup was always cheap, but\n * nothing could discover WHICH codes exist — the ~230 finding codes and 46\n * refusal codes were enumerable only from erased TypeScript unions or by\n * parsing the 83 KB prose body of `loam instructions loam-check`. It is opt-in\n * and off by default precisely so the term listing and every per-code page\n * stay byte-for-byte what they were: this is an addition to the contract, not\n * a change to it, and the term listing's own footer is left alone for the same\n * reason.\n */\nimport type { Command } from \"commander\";\nimport { emitJson, fail } from \"../../core/envelope/json.js\";\nimport { LOAM_VERSION } from \"../../core/envelope/version.js\";\nimport {\n  explainSubject,\n  firstSentence,\n  knownSubjects,\n  listCodes,\n  listTerms,\n  type CodeListing,\n  type Explanation,\n} from \"../../core/explain/lookup.js\";\nimport { nearestIds } from \"../../core/repo/entries.js\";\n\ninterface ExplainOptions {\n  json?: boolean;\n  codes?: boolean;\n}\n\n// Interpolated from the registry that owns the terms, never hand-listed: a\n// copied list beside TERMS is a list that silently trails it.\nconst TERM_LIST = listTerms()\n  .map(({ term }) => term)\n  .join(\", \");\n\n/** The listing printed when no subject is asked for — also where codes are said to come from. */\nfunction printTermListing(json: boolean): void {\n  const terms = listTerms();\n  if (json) {\n    emitJson({ command: \"explain\", version: LOAM_VERSION, terms: terms.map(({ term, summary }) => ({ term, description: summary })) });\n    return;\n  }\n  console.log(`loam ${LOAM_VERSION} — the vocabulary\\n`);\n  const width = Math.max(...terms.map(({ term }) => term.length));\n  for (const { term, summary } of terms) console.log(`  ${term.padEnd(width)}  ${summary}`);\n  console.log(\n    \"\\nFinding codes come from `loam validate` and `loam verify` output; refusal codes arrive as error.code\" +\n      \"\\nin any --json envelope. `loam explain <subject>` explains one.\",\n  );\n}\n\n/**\n * How much of a code's meaning the inventory shows before it stops.\n *\n * The term listing prints whole first sentences because there are six of them\n * and each is under 200 characters. The code listing prints 270-odd rows whose\n * first sentences run to 377 characters, and a row that wraps four times is a\n * paragraph, not a line of a table — it destroys the one thing this listing is\n * for, which is scanning names. Nothing is lost: the sentence is verbatim in\n * `--json`, and `loam explain <code>` prints the whole entry.\n */\nconst SUMMARY_WIDTH = 72;\n\n/** The listing's one-line gloss: the first sentence of the meaning, cut at a word boundary if it runs long. */\nfunction summarize(listing: CodeListing): string {\n  // A code graded in two tables is glossed by the FIRST table's meaning — the\n  // listing answers \"what is this about\", and the per-scope difference (which\n  // `explain <code>` prints in full, one block per table) is exactly the\n  // detail a one-line row cannot carry honestly.\n  const sentence = firstSentence(listing.kind === \"finding\" ? listing.entries[0]!.meaning : listing.meaning);\n  if (sentence.length <= SUMMARY_WIDTH) return sentence;\n  const cut = sentence.lastIndexOf(\" \", SUMMARY_WIDTH);\n  return `${sentence.slice(0, cut === -1 ? SUMMARY_WIDTH : cut)}…`;\n}\n\n/**\n * `--codes`: the whole code vocabulary, the inventory that was previously\n * enumerable only out of TypeScript unions or the 83 KB /loam-check prose.\n * The JSON rows are the per-code answers verbatim (core/explain/lookup.ts\n * derives `CodeListing` from `Explanation`), so a consumer can build a\n * code-to-fix cache from one call instead of one call per code.\n */\nfunction printCodeListing(json: boolean): void {\n  const codes = listCodes();\n  if (json) {\n    emitJson({ command: \"explain\", version: LOAM_VERSION, codes });\n    return;\n  }\n  const findings = codes.filter((listing) => listing.kind === \"finding\");\n  const refusals = codes.filter((listing) => listing.kind === \"refusal\");\n  const width = Math.max(...codes.map(({ code }) => code.length));\n  const print = (group: CodeListing[]): void => {\n    for (const listing of group) console.log(`  ${listing.code.padEnd(width)}  ${summarize(listing)}`);\n  };\n  console.log(`loam ${LOAM_VERSION} — the code vocabulary (${findings.length} finding, ${refusals.length} refusal)\\n`);\n  console.log(\"finding codes — graded by `loam validate` and `loam verify`, in their findings[]\");\n  print(findings);\n  console.log(\"\\nrefusal codes — the `error.code` of a --json envelope, exit 1\");\n  print(refusals);\n  console.log(\"\\n`loam explain <code>` prints one in full; `loam explain` with no argument lists the concept terms.\");\n}\n\nfunction printText(subject: string, explanation: Explanation): void {\n  if (explanation.kind === \"term\") {\n    console.log(`${explanation.term}\\n\\n${explanation.paragraph}`);\n    return;\n  }\n  if (explanation.kind === \"refusal\") {\n    console.log(`${subject} — a refusal code (error.code in the --json envelope, exit 1)\\n\\n${explanation.meaning}`);\n    return;\n  }\n  // A finding: one block per table the code appears in, under the table's own\n  // column names, so the page reads as the /loam-check row it is. The\n  // severity note repeats on each scope block because it is a PER-TABLE fact:\n  // `openapi.ref-unresolved` is a warn under `--service` and an error at\n  // archive plan time, and a reader asking \"does this block my archive?\" must\n  // not have to guess which note belongs to which context.\n  const severities = [...new Set(explanation.entries.map((entry) => entry.severityNote))];\n  console.log(`${subject} (${severities.join(\"; \")})${explanation.via === undefined ? \"\" : ` — surfaced by \\`${explanation.via}\\``}`);\n  for (const entry of explanation.entries) {\n    console.log(`\\n[${entry.scope}] (${entry.severityNote})`);\n    console.log(`  what it means: ${entry.meaning}`);\n    if (entry.fix !== \"\") console.log(`  what to do: ${entry.fix}`);\n  }\n}\n\nexport function registerExplain(program: Command): void {\n  program\n    .command(\"explain\")\n    .argument(\n      \"[subject]\",\n      `a finding code (spine.op-undefined), a refusal code (docs-busy), or a concept term (${TERM_LIST}); omit to list the terms`,\n    )\n    .description(\"Explain a finding code, refusal code or concept term, version-matched to this binary\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .option(\"--codes\", \"list every finding and refusal code this binary can explain\")\n    .action((subject: string | undefined, opts: ExplainOptions) => {\n      const json = opts.json === true;\n      if (opts.codes === true) {\n        // Refused rather than quietly preferring one: `loam explain\n        // spine.op-undefined --codes` asks two different questions, and a\n        // caller who typed both wanted whichever one this run did NOT pick.\n        if (subject !== undefined) {\n          fail(\n            json,\n            \"invalid-option\",\n            `--codes lists the whole vocabulary and takes no subject — drop '${subject}' for the inventory, or drop --codes to explain that one.`,\n          );\n          return;\n        }\n        printCodeListing(json);\n        return;\n      }\n      if (subject === undefined) {\n        printTermListing(json);\n        return;\n      }\n      const explanation = explainSubject(subject);\n      if (explanation === null) {\n        // The same code `show` and `instructions` use for a name that resolves\n        // to nothing, with `nearestIds` suggestions because the known set here\n        // is ~200 strings — a caller one typo away should not have to diff the\n        // whole vocabulary to find it.\n        const near = nearestIds(subject, knownSubjects());\n        fail(\n          json,\n          \"unknown-target\",\n          `Nothing named '${subject}' — not a finding code, a refusal code, or a concept term.` +\n            (near.length > 0 ? ` Close: ${near.join(\", \")}.` : \"\") +\n            \" Run `loam explain` with no argument for the concept list; finding codes appear in `loam validate` and `loam verify` output.\",\n        );\n        return;\n      }\n      if (json) {\n        emitJson({\n          command: \"explain\",\n          version: LOAM_VERSION,\n          subject,\n          kind: explanation.kind,\n          ...(explanation.kind === \"finding\"\n            ? { entries: explanation.entries, ...(explanation.via === undefined ? {} : { via: explanation.via }) }\n            : explanation.kind === \"refusal\"\n              ? { meaning: explanation.meaning }\n              : { term: explanation.term, paragraph: explanation.paragraph }),\n        });\n        return;\n      }\n      printText(subject, explanation);\n    });\n}\n"]}

package/dist/commands/explore.js

@@ -1,11 +1,12 @@
-import { loadConfig } from "../core/config.js";
-import { explore } from "../core/explore.js";
+import { loadConfig } from "../core/envelope/config.js";
+import { explore } from "../core/explore/explore.js";
 import { FleetContext } from "../core/fleet-context.js";
-import { emitJson, fail, reportNoConfig } from "../core/json.js";
-import { assertServiceId, featureIdProblem, InvalidIdError } from "../core/ids.js";
-import { DocsRepoUnavailableError } from "../core/repo.js";
-import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "./docs-repo-gate.js";
-import { plural } from "./format.js";
+import { emitJson, fail, reportNoConfig } from "../core/envelope/json.js";
+import { featureIdProblem } from "../core/kernel/ids/feature.js";
+import { parseServiceIds } from "../core/kernel/ids/service.js";
+import { DocsRepoUnavailableError } from "../core/repo/state.js";
+import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "./policy/gate.js";
+import { plural } from "./policy/format.js";
 /**
  * The feature id in the suggested command line when `--as` did not say.
  *
@@ -28,11 +29,13 @@ export function registerExplore(program) {
         .description("Read the fleet around a change nobody has written down yet — writes nothing")
         .option("--json", "emit the machine contract instead of the human view")
         .option("--op <operationId>", "seed from an operation instead of a service; repeatable", (value, prev = []) => [...prev, value])
+        .option("--capability <id>", "seed from a declared capability's realizing services; repeatable", (value, prev = []) => [...prev, value])
         .option("--as <FEAT>", `feature id for the suggested command line (default: ${PLACEHOLDER})`)
         .action(async (serviceArgs, opts) => {
         const json = opts.json === true;
         const services = serviceArgs ?? [];
         const operations = opts.op ?? [];
+        const capabilities = opts.capability ?? [];
         // `--as` is interpolated into the `loam new` line this command prints
         // under `next:` and returns as `scaffold`, and `loam-feature` teaches an
         // agent to pass `$1` straight into it. Unchecked, `explore` hands back a
@@ -40,7 +43,7 @@ export function registerExplore(program) {
         // something loam rejects, which is the one thing the printed-command
         // guard exists to prevent and the one shape it cannot see, because it
         // reads literal source strings and this line is assembled from argv.
-        // Same grammar as `new`'s, from core/ids.ts, so the two cannot disagree.
+        // Same grammar as `new`'s, from core/kernel/ids/feature.ts, so the two cannot disagree.
         if (opts.as !== undefined) {
             const problem = featureIdProblem(opts.as, "feature id for --as");
             if (problem !== null) {
@@ -48,13 +51,14 @@ export function registerExplore(program) {
                 return;
             }
         }
-        if (services.length === 0 && operations.length === 0) {
-            fail(json, "invalid-option", "Nothing to explore from. Name at least one service, or pass --op <operationId>. " +
-                "`loam list services` is the fleet; `loam show <service>` is one of them.");
+        if (services.length === 0 && operations.length === 0 && capabilities.length === 0) {
+            fail(json, "invalid-option", "Nothing to explore from. Name at least one service, or pass --op <operationId> or --capability <id>. " +
+                "`loam list services` is the fleet; `loam show <service>` is one of them; " +
+                "`loam list capabilities` is what the fleet promises.");
             return;
         }
         // Rule 6 in docs/DESIGN.md: a raw argv string that reaches a path join is
-        // guarded at the command boundary. Every id here reaches `servicePaths`.
+        // guarded at the command boundary. Every id here reaches the service path builders.
         // Before `loadConfig`, exactly as `loam new` guards its `--touches` list:
         // the grammar is a fact about the argument, not about the repository, so
         // an unusable id should answer the same whether or not you are standing
@@ -63,21 +67,17 @@ export function registerExplore(program) {
         // A seed naming a service that does not EXIST is fine and reported as
         // `unknown` — the feature may be introducing it — but one that could not
         // be a service directory at all is a typo, not an intention.
-        try {
-            for (const id of services)
-                assertServiceId(id, "service");
-        }
-        catch (err) {
-            if (!(err instanceof InvalidIdError))
-                throw err;
-            fail(json, "invalid-option", err.message);
+        const seeds = parseServiceIds(services, "service");
+        if (!seeds.ok) {
+            fail(json, "invalid-option", seeds.problem);
             return;
         }
-        const config = await loadConfig();
-        if (!config) {
-            reportNoConfig(json);
+        const loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
             return;
         }
+        const config = loaded.config;
         const { docsDir } = config;
         // `services`, not `docs`: every answer here is a statement about the
         // fleet, and an empty ring read out of a directory that is not a docs
@@ -87,8 +87,9 @@ export function registerExplore(program) {
         try {
             const result = await explore({
                 docsDir,
-                services,
+                services: seeds.ids,
                 operations,
+                capabilities,
                 featureId: opts.as ?? PLACEHOLDER,
                 context: new FleetContext(),
             });
@@ -164,6 +165,10 @@ function print(r) {
         console.log(`! no living contract defines ${r.unresolvedOperations.join(", ")} — ` +
             `the feature is adding ${r.unresolvedOperations.length === 1 ? "it" : "them"}, or the id is wrong\n`);
     }
+    if (r.unresolvedCapabilities.length > 0) {
+        console.log(`! no realizing service seeds ${r.unresolvedCapabilities.join(", ")} — ` +
+            `not declared in architecture/capabilities.yaml, or declared and realized by nothing\n`);
+    }
     if (r.neighbours.length > 0) {
         // The whole point of the command, so it is stated as a question rather than
         // a list: these are candidates for --touches, and loam does not know which