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

package/dist/commands/instructions.js

@@ -1,9 +1,17 @@
-import { PROTOCOLS, WORKFLOWS, protocolFor } from "../core/agent.js";
-import { emitJson, fail } from "../core/json.js";
-import { LOAM_VERSION } from "../core/version.js";
+import { PROTOCOLS, REFERENCE_PAGES, SUPPORT_PAGES, WORKFLOWS, placeholderProblems, protocolFor, } from "../core/agent/protocol.js";
+import { emitJson, fail } from "../core/envelope/json.js";
+import { LOAM_VERSION } from "../core/envelope/version.js";
+import { withoutFixTables } from "../core/explain/fix-tables.js";
 /**
- * The workflow protocols, from the binary rather than from a file somebody
- * generated once.
+ * The workflow protocols and the reference pages, from the binary rather than
+ * from a file somebody generated once.
+ *
+ * The pages are the newer half and the reason this command now has two lists.
+ * They are the sections that left the scaffolded AGENTS.md — a file every
+ * agents.md-aware host auto-loads on every session, which two hosts truncate
+ * silently — and they are printed here instead. That trade only works if they
+ * can be FOUND, so the bare menu names them; `core/agent/workflows/reference/
+ * reference.ts` carries the rest of the argument.
  *
  * This is the only command in loam that reads nothing: no `loam.json`, no docs
  * repo, no service. That is deliberate and it is the point — an agent runs this
@@ -16,10 +24,25 @@ import { LOAM_VERSION } from "../core/version.js";
 export function registerInstructions(program) {
     program
         .command("instructions")
-        .argument("[workflow]", "workflow name (loam-adopt, loam-feature, …); omit to list them")
+        // Still spelled `workflow`, not `page`: the positional is in every
+        // generated command file loam has ever written (`loam instructions
+        // loam-adopt $1`) and in `--help` output people have copied. Renaming it
+        // buys a more accurate word in one usage line and costs nothing anywhere
+        // the rename would be visible, so the accuracy goes in the menu text instead.
+        .argument("[workflow]", "workflow or reference page (loam-adopt, loam-codes, …); omit to list them")
         .argument("[args...]", "values substituted for the protocol's $1, $2, … placeholders")
-        .description("Print a workflow protocol, version-matched to this binary")
+        .description("Print a workflow protocol or reference page, version-matched to this binary")
         .option("--json", "emit the machine contract instead of the human view")
+        // Opt-in, and off by default, so the default page of every lifecycle protocol
+        // stays byte-identical: this narrows what an agent CAN ask for, it does not
+        // change what it gets when it asks for nothing. The one protocol this is
+        // about is /loam-check, whose fix tables are 83 KB of the 84 it prints —
+        // about a fifth of a 100k-token window spent before the first check has
+        // run — while `loam explain <code>` answers any one of those rows in under
+        // 500 bytes. The narrowed page keeps every paragraph that INTRODUCES a
+        // table, because that sentence is what says which scope a code was graded
+        // in; only the rows go.
+        .option("--no-fix-tables", "drop the per-code fix tables; `loam explain <code>` answers any code a run reports")
         // Every positional here is DATA — a feature id, a service id, a validate
         // target — and one of those targets is spelled `--all`. Without this,
         // commander reads a leading-dash argument as an option it does not have and
@@ -31,32 +54,77 @@ export function registerInstructions(program) {
         const json = opts.json === true;
         if (workflow === undefined) {
             if (json) {
-                emitJson({ command: "instructions", version: LOAM_VERSION, workflows: WORKFLOWS });
+                // `support` and `references` are ADDITIVE beside the `workflows` key
+                // a consumer already reads. Appending either kind to `workflows`
+                // would have been the smaller diff and the wrong one: a caller
+                // iterating that array to drive the cycle would start running
+                // diagnostics or documentation as steps.
+                emitJson({
+                    command: "instructions",
+                    version: LOAM_VERSION,
+                    workflows: WORKFLOWS,
+                    support: SUPPORT_PAGES,
+                    references: REFERENCE_PAGES,
+                });
                 return;
             }
+            // One column width across all three lists, so the blocks line up as one
+            // menu — they are separate KINDS, not separate tables.
+            const width = Math.max(...[...WORKFLOWS, ...SUPPORT_PAGES, ...REFERENCE_PAGES].map((w) => w.name.length));
             console.log(`loam ${LOAM_VERSION} — workflows\n`);
-            const width = Math.max(...WORKFLOWS.map((w) => w.name.length));
             for (const w of WORKFLOWS) {
                 console.log(`  ${w.name.padEnd(width)}  ${w.description}`);
             }
-            console.log(`\nloam instructions <workflow> [args...] prints one, placeholders filled in.`);
+            console.log(`\nsupport — use when a run or agent integration behaves unexpectedly\n`);
+            for (const s of SUPPORT_PAGES) {
+                console.log(`  ${s.name.padEnd(width)}  ${s.description}`);
+            }
+            // Under their own heading, and never merged into the six above. A page
+            // has no steps and is not part of the cycle; a flat list of ten would
+            // read as a ten-step process, which is the one thing the cycle must not
+            // be confused with. The sentence says what they are FOR, because a name
+            // alone does not distinguish "reference" from "seventh step".
+            console.log(`\nreference pages — printed whole, no arguments\n`);
+            for (const r of REFERENCE_PAGES) {
+                console.log(`  ${r.name.padEnd(width)}  ${r.description}`);
+            }
+            console.log(`\nloam instructions <workflow> [args...] prints one, placeholders filled in.` +
+                `\nloam instructions loam-report prints the local incident-reporting protocol.` +
+                `\nloam instructions <page> prints a reference page. The pages carry what AGENTS.md` +
+                `\nleaves out; \`loam explain <code>\` answers a single code without opening one.`);
+            return;
+        }
+        // Before the substitution, not after: a rendered protocol is a page of
+        // instructions an agent acts on, and a `$1` that cannot be a service id
+        // makes every command on that page unrunnable. The refusal reaches the
+        // caller in the same shape a mistyped workflow name does.
+        const problems = placeholderProblems(workflow, args);
+        if (problems !== null) {
+            fail(json, "invalid-option", `${problems.join(" ")} Nothing was printed: every command in the ${workflow} protocol ` +
+                "interpolates that value, so the page would name a target no loam command can accept.");
             return;
         }
         const body = protocolFor(workflow, args);
         if (body === null) {
             // `unknown-target`, the same code `show` uses for a name that resolves
             // to nothing. The known set is small and closed, so it is listed rather
-            // than described: a caller that mistyped one of six names should not
-            // have to run a second command to see them.
+            // than described: a caller that mistyped a known name should not have
+            // to run a second command to see the choices.
             fail(json, "unknown-target", `No workflow '${workflow}'. Known: ${Object.keys(PROTOCOLS).join(", ")}.`);
             return;
         }
+        // The narrowing composes with `--json` rather than forking the envelope:
+        // the shorter page rides in the same `body` field, so no key is added or
+        // renamed and a consumer that never passes the flag cannot tell the
+        // difference. `--json` is the larger of the two views (the whole table is
+        // one JSON string), which is exactly why it needs this too.
+        const page = opts.fixTables === false ? withoutFixTables(body) : body;
         if (json) {
             // `body` is the substituted text, not the template: a consumer that
             // asked for `loam instructions loam-adopt payment-service --json` wants
             // the protocol it is about to follow, and re-implementing the
             // substitution on the other side is a second copy of the rule.
-            emitJson({ command: "instructions", version: LOAM_VERSION, workflow, args, body });
+            emitJson({ command: "instructions", version: LOAM_VERSION, workflow, args, body: page });
             return;
         }
         // `console.log`, like every other command, rather than a raw stdout
@@ -64,7 +132,7 @@ export function registerInstructions(program) {
         // invisible to it — an untestable print is how a protocol nobody notices
         // went missing would ship. The body already ends in a newline, so the
         // one console.log adds is trimmed rather than doubled.
-        console.log(body.replace(/\n+$/, ""));
+        console.log(page.replace(/\n+$/, ""));
     });
 }
 //# sourceMappingURL=instructions.js.map

package/dist/commands/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/commands/instructions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMlD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,OAAO;SACJ,OAAO,CAAC,cAAc,CAAC;SACvB,QAAQ,CAAC,YAAY,EAAE,gEAAgE,CAAC;SACxF,QAAQ,CAAC,WAAW,EAAE,8DAA8D,CAAC;SACrF,WAAW,CAAC,2DAA2D,CAAC;SACxE,MAAM,CAAC,QAAQ,EAAE,qDAAqD,CAAC;QACxE,yEAAyE;QACzE,sEAAsE;QACtE,4EAA4E;QAC5E,2EAA2E;QAC3E,4EAA4E;QAC5E,6EAA6E;SAC5E,kBAAkB,EAAE;SACpB,MAAM,CAAC,CAAC,QAA4B,EAAE,IAAc,EAAE,IAAyB,EAAE,EAAE;QAClF,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC;QAEhC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,IAAI,EAAE,CAAC;gBACT,QAAQ,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;gBACnF,OAAO;YACT,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,QAAQ,YAAY,gBAAgB,CAAC,CAAC;YAClD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YAC/D,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;gBAC1B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YAC7D,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,8EAA8E,CAAC,CAAC;YAC5F,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACzC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,uEAAuE;YACvE,wEAAwE;YACxE,qEAAqE;YACrE,4CAA4C;YAC5C,IAAI,CACF,IAAI,EACJ,gBAAgB,EAChB,gBAAgB,QAAQ,aAAa,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC1E,CAAC;YACF,OAAO;QACT,CAAC;QAED,IAAI,IAAI,EAAE,CAAC;YACT,oEAAoE;YACpE,wEAAwE;YACxE,8DAA8D;YAC9D,+DAA+D;YAC/D,QAAQ,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACnF,OAAO;QACT,CAAC;QACD,oEAAoE;QACpE,qEAAqE;QACrE,yEAAyE;QACzE,sEAAsE;QACtE,uDAAuD;QACvD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;AACP,CAAC","sourcesContent":["import type { Command } from \"commander\";\nimport { PROTOCOLS, WORKFLOWS, protocolFor } from \"../core/agent.js\";\nimport { emitJson, fail } from \"../core/json.js\";\nimport { LOAM_VERSION } from \"../core/version.js\";\n\ninterface InstructionsOptions {\n  json?: boolean;\n}\n\n/**\n * The workflow protocols, from the binary rather than from a file somebody\n * generated once.\n *\n * This is the only command in loam that reads nothing: no `loam.json`, no docs\n * repo, no service. That is deliberate and it is the point — an agent runs this\n * BEFORE the repository is wired, and a protocol that refused with `no-config`\n * would be unreachable exactly when it is most needed, which is the first\n * minute in an unfamiliar repository. `loam-adopt`'s own first step is to run\n * `loam init` when there is no config, and it cannot be the step that requires\n * one.\n */\nexport function registerInstructions(program: Command): void {\n  program\n    .command(\"instructions\")\n    .argument(\"[workflow]\", \"workflow name (loam-adopt, loam-feature, …); omit to list them\")\n    .argument(\"[args...]\", \"values substituted for the protocol's $1, $2, … placeholders\")\n    .description(\"Print a workflow protocol, version-matched to this binary\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    // Every positional here is DATA — a feature id, a service id, a validate\n    // target — and one of those targets is spelled `--all`. Without this,\n    // commander reads a leading-dash argument as an option it does not have and\n    // refuses the whole invocation, so `/loam-check --all` (the first form the\n    // command file's own argument hint offers) got a usage error instead of the\n    // protocol. `--json` still parses as the flag it is, because it is declared.\n    .allowUnknownOption()\n    .action((workflow: string | undefined, args: string[], opts: InstructionsOptions) => {\n      const json = opts.json === true;\n\n      if (workflow === undefined) {\n        if (json) {\n          emitJson({ command: \"instructions\", version: LOAM_VERSION, workflows: WORKFLOWS });\n          return;\n        }\n        console.log(`loam ${LOAM_VERSION} — workflows\\n`);\n        const width = Math.max(...WORKFLOWS.map((w) => w.name.length));\n        for (const w of WORKFLOWS) {\n          console.log(`  ${w.name.padEnd(width)}  ${w.description}`);\n        }\n        console.log(`\\nloam instructions <workflow> [args...] prints one, placeholders filled in.`);\n        return;\n      }\n\n      const body = protocolFor(workflow, args);\n      if (body === null) {\n        // `unknown-target`, the same code `show` uses for a name that resolves\n        // to nothing. The known set is small and closed, so it is listed rather\n        // than described: a caller that mistyped one of six names should not\n        // have to run a second command to see them.\n        fail(\n          json,\n          \"unknown-target\",\n          `No workflow '${workflow}'. Known: ${Object.keys(PROTOCOLS).join(\", \")}.`,\n        );\n        return;\n      }\n\n      if (json) {\n        // `body` is the substituted text, not the template: a consumer that\n        // asked for `loam instructions loam-adopt payment-service --json` wants\n        // the protocol it is about to follow, and re-implementing the\n        // substitution on the other side is a second copy of the rule.\n        emitJson({ command: \"instructions\", version: LOAM_VERSION, workflow, args, body });\n        return;\n      }\n      // `console.log`, like every other command, rather than a raw stdout\n      // write: the test harness captures the console and a direct write is\n      // invisible to it — an untestable print is how a protocol nobody notices\n      // went missing would ship. The body already ends in a newline, so the\n      // one console.log adds is trimmed rather than doubled.\n      console.log(body.replace(/\\n+$/, \"\"));\n    });\n}\n"]}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/commands/instructions.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport {\n  PROTOCOLS,\n  REFERENCE_PAGES,\n  SUPPORT_PAGES,\n  WORKFLOWS,\n  placeholderProblems,\n  protocolFor,\n} from \"../core/agent/protocol.js\";\nimport { emitJson, fail } from \"../core/envelope/json.js\";\nimport { LOAM_VERSION } from \"../core/envelope/version.js\";\nimport { withoutFixTables } from \"../core/explain/fix-tables.js\";\n\ninterface InstructionsOptions {\n  json?: boolean;\n  /**\n   * Commander's negated-boolean shape: absent means `true`, and only\n   * `--no-fix-tables` on the command line makes it `false`. Read as\n   * `=== false` at the call site so an undefined — a caller constructing the\n   * options object itself, in a test — keeps the default page.\n   */\n  fixTables?: boolean;\n}\n\n/**\n * The workflow protocols and the reference pages, from the binary rather than\n * from a file somebody generated once.\n *\n * The pages are the newer half and the reason this command now has two lists.\n * They are the sections that left the scaffolded AGENTS.md — a file every\n * agents.md-aware host auto-loads on every session, which two hosts truncate\n * silently — and they are printed here instead. That trade only works if they\n * can be FOUND, so the bare menu names them; `core/agent/workflows/reference/\n * reference.ts` carries the rest of the argument.\n *\n * This is the only command in loam that reads nothing: no `loam.json`, no docs\n * repo, no service. That is deliberate and it is the point — an agent runs this\n * BEFORE the repository is wired, and a protocol that refused with `no-config`\n * would be unreachable exactly when it is most needed, which is the first\n * minute in an unfamiliar repository. `loam-adopt`'s own first step is to run\n * `loam init` when there is no config, and it cannot be the step that requires\n * one.\n */\nexport function registerInstructions(program: Command): void {\n  program\n    .command(\"instructions\")\n    // Still spelled `workflow`, not `page`: the positional is in every\n    // generated command file loam has ever written (`loam instructions\n    // loam-adopt $1`) and in `--help` output people have copied. Renaming it\n    // buys a more accurate word in one usage line and costs nothing anywhere\n    // the rename would be visible, so the accuracy goes in the menu text instead.\n    .argument(\"[workflow]\", \"workflow or reference page (loam-adopt, loam-codes, …); omit to list them\")\n    .argument(\"[args...]\", \"values substituted for the protocol's $1, $2, … placeholders\")\n    .description(\"Print a workflow protocol or reference page, version-matched to this binary\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    // Opt-in, and off by default, so the default page of every lifecycle protocol\n    // stays byte-identical: this narrows what an agent CAN ask for, it does not\n    // change what it gets when it asks for nothing. The one protocol this is\n    // about is /loam-check, whose fix tables are 83 KB of the 84 it prints —\n    // about a fifth of a 100k-token window spent before the first check has\n    // run — while `loam explain <code>` answers any one of those rows in under\n    // 500 bytes. The narrowed page keeps every paragraph that INTRODUCES a\n    // table, because that sentence is what says which scope a code was graded\n    // in; only the rows go.\n    .option(\n      \"--no-fix-tables\",\n      \"drop the per-code fix tables; `loam explain <code>` answers any code a run reports\",\n    )\n    // Every positional here is DATA — a feature id, a service id, a validate\n    // target — and one of those targets is spelled `--all`. Without this,\n    // commander reads a leading-dash argument as an option it does not have and\n    // refuses the whole invocation, so `/loam-check --all` (the first form the\n    // command file's own argument hint offers) got a usage error instead of the\n    // protocol. `--json` still parses as the flag it is, because it is declared.\n    .allowUnknownOption()\n    .action((workflow: string | undefined, args: string[], opts: InstructionsOptions) => {\n      const json = opts.json === true;\n\n      if (workflow === undefined) {\n        if (json) {\n          // `support` and `references` are ADDITIVE beside the `workflows` key\n          // a consumer already reads. Appending either kind to `workflows`\n          // would have been the smaller diff and the wrong one: a caller\n          // iterating that array to drive the cycle would start running\n          // diagnostics or documentation as steps.\n          emitJson({\n            command: \"instructions\",\n            version: LOAM_VERSION,\n            workflows: WORKFLOWS,\n            support: SUPPORT_PAGES,\n            references: REFERENCE_PAGES,\n          });\n          return;\n        }\n        // One column width across all three lists, so the blocks line up as one\n        // menu — they are separate KINDS, not separate tables.\n        const width = Math.max(\n          ...[...WORKFLOWS, ...SUPPORT_PAGES, ...REFERENCE_PAGES].map((w) => w.name.length),\n        );\n        console.log(`loam ${LOAM_VERSION} — workflows\\n`);\n        for (const w of WORKFLOWS) {\n          console.log(`  ${w.name.padEnd(width)}  ${w.description}`);\n        }\n        console.log(`\\nsupport — use when a run or agent integration behaves unexpectedly\\n`);\n        for (const s of SUPPORT_PAGES) {\n          console.log(`  ${s.name.padEnd(width)}  ${s.description}`);\n        }\n        // Under their own heading, and never merged into the six above. A page\n        // has no steps and is not part of the cycle; a flat list of ten would\n        // read as a ten-step process, which is the one thing the cycle must not\n        // be confused with. The sentence says what they are FOR, because a name\n        // alone does not distinguish \"reference\" from \"seventh step\".\n        console.log(`\\nreference pages — printed whole, no arguments\\n`);\n        for (const r of REFERENCE_PAGES) {\n          console.log(`  ${r.name.padEnd(width)}  ${r.description}`);\n        }\n        console.log(\n          `\\nloam instructions <workflow> [args...] prints one, placeholders filled in.` +\n            `\\nloam instructions loam-report prints the local incident-reporting protocol.` +\n            `\\nloam instructions <page> prints a reference page. The pages carry what AGENTS.md` +\n            `\\nleaves out; \\`loam explain <code>\\` answers a single code without opening one.`,\n        );\n        return;\n      }\n\n      // Before the substitution, not after: a rendered protocol is a page of\n      // instructions an agent acts on, and a `$1` that cannot be a service id\n      // makes every command on that page unrunnable. The refusal reaches the\n      // caller in the same shape a mistyped workflow name does.\n      const problems = placeholderProblems(workflow, args);\n      if (problems !== null) {\n        fail(\n          json,\n          \"invalid-option\",\n          `${problems.join(\" \")} Nothing was printed: every command in the ${workflow} protocol ` +\n            \"interpolates that value, so the page would name a target no loam command can accept.\",\n        );\n        return;\n      }\n\n      const body = protocolFor(workflow, args);\n      if (body === null) {\n        // `unknown-target`, the same code `show` uses for a name that resolves\n        // to nothing. The known set is small and closed, so it is listed rather\n        // than described: a caller that mistyped a known name should not have\n        // to run a second command to see the choices.\n        fail(\n          json,\n          \"unknown-target\",\n          `No workflow '${workflow}'. Known: ${Object.keys(PROTOCOLS).join(\", \")}.`,\n        );\n        return;\n      }\n\n      // The narrowing composes with `--json` rather than forking the envelope:\n      // the shorter page rides in the same `body` field, so no key is added or\n      // renamed and a consumer that never passes the flag cannot tell the\n      // difference. `--json` is the larger of the two views (the whole table is\n      // one JSON string), which is exactly why it needs this too.\n      const page = opts.fixTables === false ? withoutFixTables(body) : body;\n\n      if (json) {\n        // `body` is the substituted text, not the template: a consumer that\n        // asked for `loam instructions loam-adopt payment-service --json` wants\n        // the protocol it is about to follow, and re-implementing the\n        // substitution on the other side is a second copy of the rule.\n        emitJson({ command: \"instructions\", version: LOAM_VERSION, workflow, args, body: page });\n        return;\n      }\n      // `console.log`, like every other command, rather than a raw stdout\n      // write: the test harness captures the console and a direct write is\n      // invisible to it — an untestable print is how a protocol nobody notices\n      // went missing would ship. The body already ends in a newline, so the\n      // one console.log adds is trimmed rather than doubled.\n      console.log(page.replace(/\\n+$/, \"\"));\n    });\n}\n"]}

package/dist/commands/list/campaign/campaign.js

@@ -0,0 +1,65 @@
+/**
+ * The `--subsystem` slice behind `loam list`: what the flag's name denotes,
+ * and which services the filter keeps. A sub-package of list/ because the
+ * list package proper stands at its five-file limit (review.ts records
+ * that), and the adoption-campaign flag surface is its own subject beside
+ * the section renderers. The dependency direction is list → list/campaign,
+ * never back — this package imports core only, the same rule repo → repo/tree
+ * already keeps.
+ *
+ * Resolution reuses the tree machinery verbatim (`findInTree`,
+ * `servicesUnder`, `nearestTreeNames`), so `list --subsystem` and every
+ * `loam subsystem` verb read the flat namespace the same way — two spellings
+ * of "what does this name mean" would drift.
+ */
+import { fail } from "../../../core/envelope/json.js";
+import { findInTree, nearestTreeNames, servicesUnder, subsystemsUnder } from "../../../core/repo/tree/find.js";
+/**
+ * Resolve `--subsystem <name>` against the flat namespace, or report the
+ * refusal and return null. The reserved name `unfiled` selects the services
+ * filed under no subsystem — the tree's own concept, otherwise unreachable —
+ * but only while nothing in the tree claims that name: a REAL subsystem or
+ * service spelled `unfiled` wins, the same concrete-name-wins precedence
+ * `findInTree` already applies to service/subsystem ties. An unknown name
+ * refuses `unknown-target` with close-name hints rather than succeeding
+ * emptily — an empty table over a typo would read as a finished campaign —
+ * and a service name refuses `invalid-option` exactly as `loam adopt
+ * --subsystem` does: a service never contains other services.
+ */
+export function resolveSubsystemSlice(tree, name, json) {
+    const hit = findInTree(tree, name);
+    if (hit === null && name === "unfiled") {
+        return {
+            members: new Set(tree.services.filter((s) => s.subsystem.length === 0).map((s) => s.dir)),
+            subsystems: [],
+            label: "unfiled services (directly under services/)",
+        };
+    }
+    if (hit === null) {
+        // The Set: a real subsystem named 'unfiled' would otherwise sit in the
+        // hint pool twice and could be offered twice in one hint.
+        const close = nearestTreeNames(name, [...new Set([...tree.subsystems.map((s) => s.name), "unfiled"])]);
+        fail(json, "unknown-target", `No subsystem '${name}' in the tree.` +
+            (close.length > 0
+                ? ` Close names: ${close.join(", ")}.`
+                : " `loam subsystem list` shows what exists; `unfiled` selects the services filed under none."));
+        return null;
+    }
+    if (hit.kind === "service") {
+        // With a SERVICE claiming the name 'unfiled' the reserved reading has no
+        // spelling at all, so the refusal must say what is shadowed — otherwise
+        // the message reads as loam misunderstanding the request.
+        const shadowed = name === "unfiled"
+            ? " While a service claims this name, the reserved unfiled-services reading is shadowed; rename the service to reach it."
+            : "";
+        fail(json, "invalid-option", `--subsystem names the service '${name}' — a service never contains other services.${shadowed}`);
+        return null;
+    }
+    const sub = hit.subsystem;
+    return {
+        members: new Set(servicesUnder(tree, sub).map((s) => s.dir)),
+        subsystems: [sub, ...subsystemsUnder(tree, sub)],
+        label: `subsystem '${sub.name}' (services/${sub.path.join("/")}/)`,
+    };
+}
+//# sourceMappingURL=campaign.js.map

package/dist/commands/list/campaign/campaign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"campaign.js","sourceRoot":"","sources":["../../../../src/commands/list/campaign/campaign.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,gCAAgC,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAqB/G;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAe,EAAE,IAAY,EAAE,IAAa;IAChF,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,IAAI,GAAG,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO;YACL,OAAO,EAAE,IAAI,GAAG,CAAS,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACjG,UAAU,EAAE,EAAE;YACd,KAAK,EAAE,6CAA6C;SACrD,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,uEAAuE;QACvE,0DAA0D;QAC1D,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACvG,IAAI,CACF,IAAI,EACJ,gBAAgB,EAChB,iBAAiB,IAAI,gBAAgB;YACnC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBACf,CAAC,CAAC,iBAAiB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACtC,CAAC,CAAC,4FAA4F,CAAC,CACpG,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3B,yEAAyE;QACzE,wEAAwE;QACxE,0DAA0D;QAC1D,MAAM,QAAQ,GACZ,IAAI,KAAK,SAAS;YAChB,CAAC,CAAC,uHAAuH;YACzH,CAAC,CAAC,EAAE,CAAC;QACT,IAAI,CACF,IAAI,EACJ,gBAAgB,EAChB,kCAAkC,IAAI,+CAA+C,QAAQ,EAAE,CAChG,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC;IAC1B,OAAO;QACL,OAAO,EAAE,IAAI,GAAG,CAAS,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACpE,UAAU,EAAE,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAChD,KAAK,EAAE,cAAc,GAAG,CAAC,IAAI,eAAe,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI;KACnE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The `--subsystem` slice behind `loam list`: what the flag's name denotes,\n * and which services the filter keeps. A sub-package of list/ because the\n * list package proper stands at its five-file limit (review.ts records\n * that), and the adoption-campaign flag surface is its own subject beside\n * the section renderers. The dependency direction is list → list/campaign,\n * never back — this package imports core only, the same rule repo → repo/tree\n * already keeps.\n *\n * Resolution reuses the tree machinery verbatim (`findInTree`,\n * `servicesUnder`, `nearestTreeNames`), so `list --subsystem` and every\n * `loam subsystem` verb read the flat namespace the same way — two spellings\n * of \"what does this name mean\" would drift.\n */\nimport { fail } from \"../../../core/envelope/json.js\";\nimport { findInTree, nearestTreeNames, servicesUnder, subsystemsUnder } from \"../../../core/repo/tree/find.js\";\nimport type { FleetTree, SubsystemEntry } from \"../../../core/repo/tree/walk.js\";\n\nexport interface SubsystemSlice {\n  /**\n   * DIRECTORIES of the member services, at any depth beneath the filter\n   * target — the directory, not the id, because the id is a leaf name the\n   * fleet does not guarantee unique: a `subsystem.name-collision` tree still\n   * enumerates both claimants on purpose, and an id-keyed slice would let\n   * each of two disjoint slices claim the other's service.\n   */\n  readonly members: ReadonlySet<string>;\n  /**\n   * The subsystem rows the filtered payload shows — the named subsystem and\n   * its descendants; `[]` for the unfiled slice, which sits under no group.\n   */\n  readonly subsystems: SubsystemEntry[];\n  /** The human filter line's description of what the slice is. */\n  readonly label: string;\n}\n\n/**\n * Resolve `--subsystem <name>` against the flat namespace, or report the\n * refusal and return null. The reserved name `unfiled` selects the services\n * filed under no subsystem — the tree's own concept, otherwise unreachable —\n * but only while nothing in the tree claims that name: a REAL subsystem or\n * service spelled `unfiled` wins, the same concrete-name-wins precedence\n * `findInTree` already applies to service/subsystem ties. An unknown name\n * refuses `unknown-target` with close-name hints rather than succeeding\n * emptily — an empty table over a typo would read as a finished campaign —\n * and a service name refuses `invalid-option` exactly as `loam adopt\n * --subsystem` does: a service never contains other services.\n */\nexport function resolveSubsystemSlice(tree: FleetTree, name: string, json: boolean): SubsystemSlice | null {\n  const hit = findInTree(tree, name);\n  if (hit === null && name === \"unfiled\") {\n    return {\n      members: new Set<string>(tree.services.filter((s) => s.subsystem.length === 0).map((s) => s.dir)),\n      subsystems: [],\n      label: \"unfiled services (directly under services/)\",\n    };\n  }\n  if (hit === null) {\n    // The Set: a real subsystem named 'unfiled' would otherwise sit in the\n    // hint pool twice and could be offered twice in one hint.\n    const close = nearestTreeNames(name, [...new Set([...tree.subsystems.map((s) => s.name), \"unfiled\"])]);\n    fail(\n      json,\n      \"unknown-target\",\n      `No subsystem '${name}' in the tree.` +\n        (close.length > 0\n          ? ` Close names: ${close.join(\", \")}.`\n          : \" `loam subsystem list` shows what exists; `unfiled` selects the services filed under none.\"),\n    );\n    return null;\n  }\n  if (hit.kind === \"service\") {\n    // With a SERVICE claiming the name 'unfiled' the reserved reading has no\n    // spelling at all, so the refusal must say what is shadowed — otherwise\n    // the message reads as loam misunderstanding the request.\n    const shadowed =\n      name === \"unfiled\"\n        ? \" While a service claims this name, the reserved unfiled-services reading is shadowed; rename the service to reach it.\"\n        : \"\";\n    fail(\n      json,\n      \"invalid-option\",\n      `--subsystem names the service '${name}' — a service never contains other services.${shadowed}`,\n    );\n    return null;\n  }\n  const sub = hit.subsystem;\n  return {\n    members: new Set<string>(servicesUnder(tree, sub).map((s) => s.dir)),\n    subsystems: [sub, ...subsystemsUnder(tree, sub)],\n    label: `subsystem '${sub.name}' (services/${sub.path.join(\"/\")}/)`,\n  };\n}\n"]}

package/dist/commands/list/campaign/owners.js

@@ -0,0 +1,65 @@
+/**
+ * The `--owners` join behind `loam list`: read the user-named CODEOWNERS
+ * file, bucket the CURRENT listing's rows under the teams it names, and
+ * refuse — `owners-unreadable` — when the file cannot be read or a line in
+ * it cannot be parsed as `pattern owner…`. The parse and the matching are
+ * `core/owners/codeowners.ts`'s (pure; its header records the implemented
+ * subset and the skip-don't-guess rule); this module owns the filesystem
+ * read and the refusal, because core never prints.
+ *
+ * The join runs over the rows the listing is about to show, in the order it
+ * will show them — after `--subsystem`/`--needs-work` filtering and any
+ * `--review-order` ranking — so each team's array IS that team's campaign
+ * worklist, not a second, differently-ordered opinion of the fleet.
+ */
+import { readFile } from "node:fs/promises";
+import { fail } from "../../../core/envelope/json.js";
+import { ownersFor, parseCodeowners } from "../../../core/owners/codeowners.js";
+/**
+ * Read, parse and join, or report the refusal and return null. An empty or
+ * all-skipped file is NOT a refusal: every row lands in `unowned`, honestly —
+ * the file said nothing, and saying so is the answer.
+ */
+export async function ownersJoin(req) {
+    let content;
+    try {
+        content = await readFile(req.path, "utf8");
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        fail(req.json, "owners-unreadable", `Cannot read the CODEOWNERS file at ${req.path}: ${detail}. Nothing was joined; re-run with the path of the file the forge actually uses.`);
+        return null;
+    }
+    const parsed = parseCodeowners(content);
+    if (!parsed.ok) {
+        fail(req.json, "owners-unreadable", `${req.path}:${parsed.line}: ${parsed.problem}. A rule loam cannot read is never guessed at or silently skipped — fix the line, then re-run.`);
+        return null;
+    }
+    const byOwner = new Map();
+    const unowned = [];
+    for (const row of req.rows) {
+        const owners = ownersFor(row.repoDir.split("/"), parsed.rules);
+        if (owners.length === 0) {
+            unowned.push(row);
+            continue;
+        }
+        // A rule may name several owners; the service files under EACH — a shared
+        // directory is two teams' work, not half of either's. The Set: a rule
+        // repeating one owner (`@a @a`) must not list the service twice.
+        for (const owner of new Set(owners)) {
+            byOwner.set(owner, [...(byOwner.get(owner) ?? []), row]);
+        }
+    }
+    return {
+        path: req.path,
+        // Plain lexicographic on the owner string: deterministic across machines,
+        // and owner handles are not ids, so compareIds' numeric tokenizing has
+        // nothing to add.
+        teams: [...byOwner.entries()]
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([owner, services]) => ({ owner, services })),
+        unowned,
+        skipped: parsed.skipped,
+    };
+}
+//# sourceMappingURL=owners.js.map

package/dist/commands/list/campaign/owners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owners.js","sourceRoot":"","sources":["../../../../src/commands/list/campaign/owners.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,gCAAgC,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAoB,MAAM,oCAAoC,CAAC;AA4BlG;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAIhC;IACC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,IAAI,CACF,GAAG,CAAC,IAAI,EACR,mBAAmB,EACnB,sCAAsC,GAAG,CAAC,IAAI,KAAK,MAAM,iFAAiF,CAC3I,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,IAAI,CACF,GAAG,CAAC,IAAI,EACR,mBAAmB,EACnB,GAAG,GAAG,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,OAAO,gGAAgG,CAC9I,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC9C,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClB,SAAS;QACX,CAAC;QACD,0EAA0E;QAC1E,sEAAsE;QACtE,iEAAiE;QACjE,KAAK,MAAM,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,0EAA0E;QAC1E,uEAAuE;QACvE,kBAAkB;QAClB,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;aAC1B,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aACpC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpD,OAAO;QACP,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The `--owners` join behind `loam list`: read the user-named CODEOWNERS\n * file, bucket the CURRENT listing's rows under the teams it names, and\n * refuse — `owners-unreadable` — when the file cannot be read or a line in\n * it cannot be parsed as `pattern owner…`. The parse and the matching are\n * `core/owners/codeowners.ts`'s (pure; its header records the implemented\n * subset and the skip-don't-guess rule); this module owns the filesystem\n * read and the refusal, because core never prints.\n *\n * The join runs over the rows the listing is about to show, in the order it\n * will show them — after `--subsystem`/`--needs-work` filtering and any\n * `--review-order` ranking — so each team's array IS that team's campaign\n * worklist, not a second, differently-ordered opinion of the fleet.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { fail } from \"../../../core/envelope/json.js\";\nimport { ownersFor, parseCodeowners, type SkippedRule } from \"../../../core/owners/codeowners.js\";\n\n/** One row of the listing, reduced to what the join reads. */\nexport interface OwnedRow {\n  readonly id: string;\n  /** The service's docs-repo-relative directory, forward slashes (`repoPath`). */\n  readonly repoDir: string;\n}\n\nexport interface OwnersJoin {\n  /** The path exactly as the user named it — the file is theirs, not loam's. */\n  readonly path: string;\n  /**\n   * One bucket per owning team, sorted by owner; rows in row order. The full\n   * row, not the id: leaf ids can collide across a broken tree, and the\n   * renderers join back to their views by `repoDir` — the row's identity.\n   */\n  readonly teams: { readonly owner: string; readonly services: readonly OwnedRow[] }[];\n  /**\n   * Rows no rule matched, or whose LAST matching rule named no owner —\n   * GitHub's ownership-clearing form. Listed explicitly, because a service\n   * silently absent from every team's queue reads as somebody else's work.\n   */\n  readonly unowned: readonly OwnedRow[];\n  /** Recognised rules outside the implemented subset — reported, never guessed. */\n  readonly skipped: readonly SkippedRule[];\n}\n\n/**\n * Read, parse and join, or report the refusal and return null. An empty or\n * all-skipped file is NOT a refusal: every row lands in `unowned`, honestly —\n * the file said nothing, and saying so is the answer.\n */\nexport async function ownersJoin(req: {\n  path: string;\n  rows: readonly OwnedRow[];\n  json: boolean;\n}): Promise<OwnersJoin | null> {\n  let content: string;\n  try {\n    content = await readFile(req.path, \"utf8\");\n  } catch (err) {\n    const detail = err instanceof Error ? err.message : String(err);\n    fail(\n      req.json,\n      \"owners-unreadable\",\n      `Cannot read the CODEOWNERS file at ${req.path}: ${detail}. Nothing was joined; re-run with the path of the file the forge actually uses.`,\n    );\n    return null;\n  }\n  const parsed = parseCodeowners(content);\n  if (!parsed.ok) {\n    fail(\n      req.json,\n      \"owners-unreadable\",\n      `${req.path}:${parsed.line}: ${parsed.problem}. A rule loam cannot read is never guessed at or silently skipped — fix the line, then re-run.`,\n    );\n    return null;\n  }\n  const byOwner = new Map<string, OwnedRow[]>();\n  const unowned: OwnedRow[] = [];\n  for (const row of req.rows) {\n    const owners = ownersFor(row.repoDir.split(\"/\"), parsed.rules);\n    if (owners.length === 0) {\n      unowned.push(row);\n      continue;\n    }\n    // A rule may name several owners; the service files under EACH — a shared\n    // directory is two teams' work, not half of either's. The Set: a rule\n    // repeating one owner (`@a @a`) must not list the service twice.\n    for (const owner of new Set(owners)) {\n      byOwner.set(owner, [...(byOwner.get(owner) ?? []), row]);\n    }\n  }\n  return {\n    path: req.path,\n    // Plain lexicographic on the owner string: deterministic across machines,\n    // and owner handles are not ids, so compareIds' numeric tokenizing has\n    // nothing to add.\n    teams: [...byOwner.entries()]\n      .sort(([a], [b]) => (a < b ? -1 : 1))\n      .map(([owner, services]) => ({ owner, services })),\n    unowned,\n    skipped: parsed.skipped,\n  };\n}\n"]}

package/dist/commands/list/json.js

@@ -0,0 +1,157 @@
+/**
+ * The `--json` rows. Separate from `./print.ts` because only this side is a
+ * contract: the payload keys are frozen, the columns beside them are not.
+ */
+import { repoPath } from "../../core/envelope/json.js";
+import {} from "../../core/capabilities/rollup.js";
+import {} from "../../core/repo/entries.js";
+import { servicesUnder } from "../../core/repo/tree/find.js";
+import {} from "./views.js";
+/**
+ * The `services[]` rows: ranked and decorated under `--review-order`, plain
+ * otherwise — as a VARIANT, so a call carrying both a plain list and a ranked
+ * queue is unrepresentable rather than resolved by precedence. `fanIn`/
+ * `reviewRank` are ADDITIVE and appear ONLY under the flag — bare
+ * `loam list --json` and `--needs-work --json` stay byte-identical and
+ * cost-identical, the frozen-default doctrine the explicit-only capabilities
+ * section also follows. The spread keeps serviceJson at its two-param
+ * contract; `reviewRank` is 1-based and equals the row's position, so the
+ * array order IS the queue.
+ */
+export function serviceRows(docsDir, rows) {
+    if (Array.isArray(rows))
+        return rows.map((v) => serviceJson(docsDir, v));
+    return rows.queue.map((v, i) => ({
+        ...serviceJson(docsDir, v),
+        fanIn: rows.fanIn.get(v.entry.id) ?? 0,
+        reviewRank: i + 1,
+    }));
+}
+export function serviceJson(docsDir, v) {
+    const s = v.entry;
+    return {
+        id: s.id,
+        path: repoPath(docsDir, s.dir),
+        // Names from services/ down, outermost first; [] = unfiled. `path` above
+        // already truthfully reflects placement — this is the same fact as data
+        // instead of a string to split.
+        subsystem: s.subsystem,
+        has: { ...s.has, archSpec: v.archSpec },
+        adrs: s.adrs,
+        status: s.status,
+        maturity: v.maturity,
+        missing: v.missing,
+        apiExpected: v.apiExpected,
+        // Never omitted when true: a consumer that filters this table into a
+        // worklist has to be able to tell "checked and fine" from "not checkable
+        // from here", and absence reads as the first one.
+        ...(v.unverifiableFromHere ? { provenance: "unverifiable-from-here" } : {}),
+        // Additive, and only when there IS a scope — omission is the fine case
+        // here, exactly as it is for `provenance` above, and `maturity` stays the
+        // frozen `vouched` beside it. A dashboard counting `maturity: "vouched"`
+        // rows keeps counting them; one that cares whether a person read the
+        // document subtracts these.
+        ...(s.vouchScope === "sampled" ? { vouchScope: "sampled" } : {}),
+    };
+}
+/**
+ * The subsystem rows beside the service table, sorted by path. `memberCount`
+ * is TRANSITIVE — every service beneath, at any depth — matching the
+ * generated views file's membership, so the two numbers a consumer can
+ * cross-check never disagree about what "in this group" means.
+ */
+export function subsystemsJson(docsDir, tree) {
+    return [...tree.subsystems]
+        .sort((a, b) => (a.path.join("/") < b.path.join("/") ? -1 : 1))
+        .map((sub) => ({
+        name: sub.name,
+        path: repoPath(docsDir, sub.dir),
+        title: sub.meta.title ?? null,
+        memberCount: servicesUnder(tree, sub).length,
+    }));
+}
+/**
+ * The additive `owners` payload key under `--owners` — the join result as a
+ * contract: `path` (the file exactly as the user named it), `teams[]` (owner
+ * plus that team's services, in the LISTING's own filtered-and-ordered row
+ * order, so each array is that team's campaign worklist), `unowned[]` (rows
+ * no rule matched — explicit, because absence would read as owned-somewhere),
+ * and `skippedRules[]` (recognised rules outside the implemented CODEOWNERS
+ * subset, each with its line — reported, never guessed at). Key spellings
+ * frozen once shipped; the join itself lives in campaign/owners.ts.
+ *
+ * The service arrays carry IDS. On a `subsystem.name-collision` fleet —
+ * already an error finding — two rows can share an id, so a consumer cannot
+ * tell them apart here; if that ever needs disambiguating, the fix is a new
+ * ADDITIVE key carrying paths, never a change to these.
+ */
+export function ownersJson(join) {
+    return {
+        path: join.path,
+        teams: join.teams.map((team) => ({ owner: team.owner, services: team.services.map((row) => row.id) })),
+        unowned: join.unowned.map((row) => row.id),
+        skippedRules: join.skipped.map((rule) => ({ line: rule.line, pattern: rule.pattern })),
+    };
+}
+/**
+ * One `capabilities[]` row — additive payload, explicit `loam list
+ * capabilities` only, and diff-stable: the rollup already sorts rows,
+ * realizedBy and statuses' keys deterministically, and this projection adds
+ * nothing that could vary between machines. Optional keys are omitted rather
+ * than nulled so a declaration that never carried a description does not grow
+ * one in the diff.
+ */
+export function capabilityJson(row) {
+    return {
+        id: row.id,
+        ...(row.description !== undefined ? { description: row.description } : {}),
+        ...(row.owner !== undefined ? { owner: row.owner } : {}),
+        realizedBy: row.realizedBy,
+        services: row.services,
+        statuses: row.statuses,
+        // Present only for a capability that HAS a document, and absent rather than
+        // `[]` for one that does not — the same optional-key rule the two fields
+        // above follow, and here it carries a distinction a reader needs: an empty
+        // array means the document declares no requirements, while no key at all
+        // means there is no document to declare any.
+        //
+        // Each row inside carries `realizedBy` (the service requirements whose
+        // `Realizes:` line names it) and `keptBy` (the flows whose `#cap-`/`#req-`
+        // tags resolve to it) — two independent corpora, NEITHER derived from the
+        // other, because a cross-service promise can only be kept by a flow and a
+        // per-service one is normally kept by a requirement. `keptBy` follows the
+        // same three-state rule one level down and `rollup.ts` states it: absent
+        // means nobody looked, `[]` means loam looked and no flow keeps it. The
+        // payload's own `useCases.unreadable` says which of the two absences it is.
+        ...(row.requirements === undefined ? {} : { requirements: row.requirements }),
+    };
+}
+export function featureJson(docsDir, f, verification) {
+    return {
+        id: f.id,
+        dirName: f.dirName,
+        path: repoPath(docsDir, f.dir),
+        archived: f.archived,
+        services: f.services,
+        has: f.has,
+        verification,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Verification                                                        */
+/* ------------------------------------------------------------------ */
+/** What the features table says about verification without N `loam verify` runs. */
+/**
+ * One `glossary[]` row — additive payload, explicit `loam list glossary` only.
+ *
+ * `linkedBy` is the whole reason the section exists: "which documents use this
+ * term" is a grep today and a join here, and it is the same answer
+ * `glossary.unlinked` grades. Repo-relative and sorted by the index itself, so
+ * the payload is diff-stable across machines. Empty means loam read every
+ * authored document and none of them cites the term — never "nobody looked",
+ * which is what the sibling `links.unreadable` list is for.
+ */
+export function glossaryJson(term, linkedBy, docsDir) {
+    return { id: term.id, path: repoPath(docsDir, term.path), linkedBy };
+}
+//# sourceMappingURL=json.js.map

package/dist/commands/list/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../../src/commands/list/json.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `--json` rows. Separate from `./print.ts` because only this side is a\n * contract: the payload keys are frozen, the columns beside them are not.\n */\nimport { repoPath } from \"../../core/envelope/json.js\";\nimport { type CapabilityRow } from \"../../core/capabilities/rollup.js\";\nimport { type FeatureEntry } from \"../../core/repo/entries.js\";\nimport { servicesUnder } from \"../../core/repo/tree/find.js\";\nimport type { FleetTree } from \"../../core/repo/tree/walk.js\";\nimport type { OwnersJoin } from \"./campaign/owners.js\";\nimport { type ServiceView, type VerificationCell } from \"./views.js\";\n\n/**\n * The `services[]` rows: ranked and decorated under `--review-order`, plain\n * otherwise — as a VARIANT, so a call carrying both a plain list and a ranked\n * queue is unrepresentable rather than resolved by precedence. `fanIn`/\n * `reviewRank` are ADDITIVE and appear ONLY under the flag — bare\n * `loam list --json` and `--needs-work --json` stay byte-identical and\n * cost-identical, the frozen-default doctrine the explicit-only capabilities\n * section also follows. The spread keeps serviceJson at its two-param\n * contract; `reviewRank` is 1-based and equals the row's position, so the\n * array order IS the queue.\n */\nexport function serviceRows(\n  docsDir: string,\n  rows: ServiceView[] | { queue: ServiceView[]; fanIn: ReadonlyMap<string, number> },\n): Record<string, unknown>[] {\n  if (Array.isArray(rows)) return rows.map((v) => serviceJson(docsDir, v));\n  return rows.queue.map((v, i) => ({\n    ...serviceJson(docsDir, v),\n    fanIn: rows.fanIn.get(v.entry.id) ?? 0,\n    reviewRank: i + 1,\n  }));\n}\n\nexport function serviceJson(docsDir: string, v: ServiceView): Record<string, unknown> {\n  const s = v.entry;\n  return {\n    id: s.id,\n    path: repoPath(docsDir, s.dir),\n    // Names from services/ down, outermost first; [] = unfiled. `path` above\n    // already truthfully reflects placement — this is the same fact as data\n    // instead of a string to split.\n    subsystem: s.subsystem,\n    has: { ...s.has, archSpec: v.archSpec },\n    adrs: s.adrs,\n    status: s.status,\n    maturity: v.maturity,\n    missing: v.missing,\n    apiExpected: v.apiExpected,\n    // Never omitted when true: a consumer that filters this table into a\n    // worklist has to be able to tell \"checked and fine\" from \"not checkable\n    // from here\", and absence reads as the first one.\n    ...(v.unverifiableFromHere ? { provenance: \"unverifiable-from-here\" } : {}),\n    // Additive, and only when there IS a scope — omission is the fine case\n    // here, exactly as it is for `provenance` above, and `maturity` stays the\n    // frozen `vouched` beside it. A dashboard counting `maturity: \"vouched\"`\n    // rows keeps counting them; one that cares whether a person read the\n    // document subtracts these.\n    ...(s.vouchScope === \"sampled\" ? { vouchScope: \"sampled\" } : {}),\n  };\n}\n\n/**\n * The subsystem rows beside the service table, sorted by path. `memberCount`\n * is TRANSITIVE — every service beneath, at any depth — matching the\n * generated views file's membership, so the two numbers a consumer can\n * cross-check never disagree about what \"in this group\" means.\n */\nexport function subsystemsJson(docsDir: string, tree: FleetTree): Record<string, unknown>[] {\n  return [...tree.subsystems]\n    .sort((a, b) => (a.path.join(\"/\") < b.path.join(\"/\") ? -1 : 1))\n    .map((sub) => ({\n      name: sub.name,\n      path: repoPath(docsDir, sub.dir),\n      title: sub.meta.title ?? null,\n      memberCount: servicesUnder(tree, sub).length,\n    }));\n}\n\n/**\n * The additive `owners` payload key under `--owners` — the join result as a\n * contract: `path` (the file exactly as the user named it), `teams[]` (owner\n * plus that team's services, in the LISTING's own filtered-and-ordered row\n * order, so each array is that team's campaign worklist), `unowned[]` (rows\n * no rule matched — explicit, because absence would read as owned-somewhere),\n * and `skippedRules[]` (recognised rules outside the implemented CODEOWNERS\n * subset, each with its line — reported, never guessed at). Key spellings\n * frozen once shipped; the join itself lives in campaign/owners.ts.\n *\n * The service arrays carry IDS. On a `subsystem.name-collision` fleet —\n * already an error finding — two rows can share an id, so a consumer cannot\n * tell them apart here; if that ever needs disambiguating, the fix is a new\n * ADDITIVE key carrying paths, never a change to these.\n */\nexport function ownersJson(join: OwnersJoin): Record<string, unknown> {\n  return {\n    path: join.path,\n    teams: join.teams.map((team) => ({ owner: team.owner, services: team.services.map((row) => row.id) })),\n    unowned: join.unowned.map((row) => row.id),\n    skippedRules: join.skipped.map((rule) => ({ line: rule.line, pattern: rule.pattern })),\n  };\n}\n\n/**\n * One `capabilities[]` row — additive payload, explicit `loam list\n * capabilities` only, and diff-stable: the rollup already sorts rows,\n * realizedBy and statuses' keys deterministically, and this projection adds\n * nothing that could vary between machines. Optional keys are omitted rather\n * than nulled so a declaration that never carried a description does not grow\n * one in the diff.\n */\nexport function capabilityJson(row: CapabilityRow): Record<string, unknown> {\n  return {\n    id: row.id,\n    ...(row.description !== undefined ? { description: row.description } : {}),\n    ...(row.owner !== undefined ? { owner: row.owner } : {}),\n    realizedBy: row.realizedBy,\n    services: row.services,\n    statuses: row.statuses,\n    // Present only for a capability that HAS a document, and absent rather than\n    // `[]` for one that does not — the same optional-key rule the two fields\n    // above follow, and here it carries a distinction a reader needs: an empty\n    // array means the document declares no requirements, while no key at all\n    // means there is no document to declare any.\n    //\n    // Each row inside carries `realizedBy` (the service requirements whose\n    // `Realizes:` line names it) and `keptBy` (the flows whose `#cap-`/`#req-`\n    // tags resolve to it) — two independent corpora, NEITHER derived from the\n    // other, because a cross-service promise can only be kept by a flow and a\n    // per-service one is normally kept by a requirement. `keptBy` follows the\n    // same three-state rule one level down and `rollup.ts` states it: absent\n    // means nobody looked, `[]` means loam looked and no flow keeps it. The\n    // payload's own `useCases.unreadable` says which of the two absences it is.\n    ...(row.requirements === undefined ? {} : { requirements: row.requirements }),\n  };\n}\n\nexport function featureJson(\n  docsDir: string,\n  f: FeatureEntry,\n  verification: VerificationCell | null,\n): Record<string, unknown> {\n  return {\n    id: f.id,\n    dirName: f.dirName,\n    path: repoPath(docsDir, f.dir),\n    archived: f.archived,\n    services: f.services,\n    has: f.has,\n    verification,\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* Verification                                                        */\n/* ------------------------------------------------------------------ */\n\n/** What the features table says about verification without N `loam verify` runs. */\n\n/**\n * One `glossary[]` row — additive payload, explicit `loam list glossary` only.\n *\n * `linkedBy` is the whole reason the section exists: \"which documents use this\n * term\" is a grep today and a join here, and it is the same answer\n * `glossary.unlinked` grades. Repo-relative and sorted by the index itself, so\n * the payload is diff-stable across machines. Empty means loam read every\n * authored document and none of them cites the term — never \"nobody looked\",\n * which is what the sibling `links.unreadable` list is for.\n */\nexport function glossaryJson(term: { id: string; path: string }, linkedBy: string[], docsDir: string): Record<string, unknown> {\n  return { id: term.id, path: repoPath(docsDir, term.path), linkedBy };\n}\n"]}