@ybotok/loam 0.1.0-beta.1 → 0.1.0-beta.3

package/dist/core/status.js

@@ -105,7 +105,7 @@ import { FleetContext } from "./fleet-context.js";
 import { gatesArchive } from "./issue.js";
 import { repoPath } from "./json.js";
 import { featureProvenance } from "./provenance.js";
-import { compareIds, featurePaths, featureSpecPaths, featureSpecServices, listFeatures, listServices, servicePaths, } from "./repo.js";
+import { compareIds, featurePaths, featureSpecPaths, featureSpecServices, listFeatures, listServices, servicePaths, SPEC_AXES, } from "./repo.js";
 import { requirementsMissingScenarios } from "./spec.js";
 import { COMMIT_INTENT, readCommitIntent } from "./staging.js";
 import { attestedNotice, featureChecklist, readVerificationState, tallyRecord, verificationPath, verificationVerdict, } from "./verify.js";
@@ -155,9 +155,21 @@ async function readInterruptedCommit(docsDir) {
     return {
         command: intent.command,
         feature: intent.feature,
-        host: intent.host,
-        pid: intent.pid,
-        at: intent.at,
+        // Coerced here rather than trusted. `readCommitIntent` validates exactly the
+        // fields a REPAIR needs — the version, the command, the restore direction,
+        // the feature, the two move paths and the file digests — so `host`, `pid`
+        // and `at` arrive as whatever the journal happened to hold, `undefined`
+        // included. That is worse than null in both renderings: `JSON.stringify`
+        // drops an undefined value's key entirely, so `--json` loses the field
+        // instead of reporting it empty, and the two human lines print
+        // "(undefined, pid undefined, undefined)". These three are the label a
+        // person places the crash against and nothing branches on them, so the
+        // coercion belongs at this boundary — widening the validator would change
+        // which journals `archive` and `unarchive` agree to repair, which is a
+        // decision about somebody's half-written docs, not about a label.
+        host: typeof intent.host === "string" ? intent.host : null,
+        pid: typeof intent.pid === "number" ? intent.pid : null,
+        at: typeof intent.at === "string" ? intent.at : null,
         files: intent.files.map((f) => f.path),
         unreadable: false,
         // The recovering command is the interrupted one re-run: it repairs first,
@@ -222,7 +234,7 @@ export async function featureStatus(docsDir, feature, opts = {}) {
     // way round. `--service` is a lens on the table and the steps; a rollup that
     // moved with it would report a feature `ready` because the one service you
     // asked about happens to be written, while three others have nothing.
-    const graded = featureArtifacts(docsDir, feature, services, blocking, verification, await contractsInFlight(docsDir, feature.id, context), governs);
+    const graded = featureArtifacts(docsDir, feature, services, blocking, verification, contractsHeldElsewhere(await contractOwners(docsDir, context), feature.id), governs);
     const artifacts = narrowed === undefined ? graded : graded.filter((a) => a.service === null || a.service === narrowed);
     // The dependency index rather than the `*-pending` issue codes: those name the
     // other feature in prose, and prose is not an API — dependencies.ts opens with
@@ -452,11 +464,20 @@ function fileState(id, service, path, exists, required, faulted) {
  * docs already carry the contract, or another feature in flight brings it — the
  * same softening coherence applies with its `*-pending` codes, where an
  * operation "defined by another feature still in flight" is an ordering fact
- * and not a hole. And one way to owe nothing at all: a service with no living
- * contract that this feature sends no operation to. A UI or a worker nobody
- * calls has no API to write down, which is the reading `validate` and `list`
- * already take — demanding one from a brand-new one of those would be loam
- * telling an author to invent a contract.
+ * and not a hole. And one way to owe nothing at all: a service that ALREADY
+ * EXISTS under `services/`, has no living contract, and that this feature sends
+ * no operation to. A UI or a worker nobody calls has no API to write down,
+ * which is the reading `validate` and `list` already take — demanding one from
+ * an adopted service of that shape would be loam telling an author to invent a
+ * contract.
+ *
+ * That last exemption is deliberately withheld from a service the living docs
+ * have never heard of. A feature that introduces a service and sends it no
+ * operation still owes the file, because nothing else in the repository will
+ * ever describe its surface, and `c4-api.op-undefined` fires on an op-tagged
+ * delta edge whether or not any `Operations:` line was written — so answering
+ * "none owed" there printed `(not written — none owed)` in the same payload as
+ * an error about that very file.
  */
 function owesContract(docsDir, svc, contracted, governsOperations) {
     if (existsSync(servicePaths(docsDir, svc).openapi))
@@ -466,18 +487,49 @@ function owesContract(docsDir, svc, contracted, governsOperations) {
     return !existsSync(servicePaths(docsDir, svc).dir) || governsOperations;
 }
 /**
- * Services some OTHER active feature already carries an `openapi.yaml` for.
+ * Which features in flight carry an `openapi.yaml` for which service — one
+ * enumeration of the whole index, service by service.
+ *
+ * The owners are recorded as feature IDS rather than directories because that
+ * is the comparison {@link contractsHeldElsewhere} makes: two directories that
+ * spell the same id are one feature as far as this question goes, and an index
+ * keyed by directory would let a duplicated id answer "somebody else has it"
+ * about its own twin.
+ *
  * Enumeration only — the feature list and its `specs/` subdirectories are
  * already in the request-scoped index by the time anything asks.
  */
-async function contractsInFlight(docsDir, self, context) {
-    const out = new Set();
+async function contractOwners(docsDir, context) {
+    const out = new Map();
     for (const f of await listFeatures(docsDir, {}, context)) {
-        if (f.id === self)
-            continue;
         for (const svc of f.services) {
-            if (existsSync(featureSpecPaths(f.dir, svc).openapi))
+            if (!existsSync(featureSpecPaths(f.dir, svc).openapi))
+                continue;
+            const owners = out.get(svc);
+            if (owners === undefined)
+                out.set(svc, new Set([f.id]));
+            else
+                owners.add(f.id);
+        }
+    }
+    return out;
+}
+/**
+ * Services some OTHER active feature already carries an `openapi.yaml` for.
+ *
+ * Derived from the shared index rather than re-walked, because the answer for
+ * feature A and the answer for feature B are two readings of one enumeration:
+ * asking it once per feature made the fleet form pay F²·S `existsSync` calls
+ * over the two quantities that actually grow.
+ */
+function contractsHeldElsewhere(owners, self) {
+    const out = new Set();
+    for (const [svc, ids] of owners) {
+        for (const id of ids) {
+            if (id !== self) {
                 out.add(svc);
+                break;
+            }
         }
     }
     return out;
@@ -486,13 +538,22 @@ async function contractsInFlight(docsDir, self, context) {
  * The record's own rung. `stale` and `unreadable` are `draft` because both mean
  * the file on disk is the thing to fix; unconfirmed claims are `ready` because
  * the file is fine and the answer lives in the code.
+ *
+ * All four states are spelled, `recorded` included, so the `never` below fails
+ * the build rather than the reader: a fifth record state added to
+ * {@link VerificationState} would otherwise fall through into the last branch
+ * and be graded by `fullyVerified` alone — silently answering `ready` about a
+ * record whose new state nobody here has decided a rung for.
  */
 function verificationStatus(v) {
     if (v.state === "absent")
         return "missing";
     if (v.state === "unreadable" || v.state === "stale")
         return "draft";
-    return fullyVerified(v) ? "done" : "ready";
+    if (v.state === "recorded")
+        return fullyVerified(v) ? "done" : "ready";
+    const unreachable = v.state;
+    throw new Error(`verificationStatus: no rung for verification state '${String(unreachable)}'`);
 }
 /**
  * Read the record and, only when there is one, ask whether it still answers
@@ -602,8 +663,12 @@ function featureNext(feature, services, artifacts, findings, blockedBy, verifica
                 code: "next.author-openapi",
                 // Not "the service is not in the living docs": a service adopted
                 // without a contract is the commoner case, and that wording sent a
-                // reader looking for a directory that was right there.
-                statement: `Write ${api.path} — nothing gives ${svc} a living openapi.yaml, so this feature is the only thing that can define the operations it governs.`,
+                // reader looking for a directory that was right there. And not "the
+                // operations it governs" either — this step also fires for a service
+                // the feature INTRODUCES, where owesContract asks nothing about
+                // operations and the delta may tag none, so naming them promised the
+                // author a list they would go looking for and not find.
+                statement: `Write ${api.path} — nothing gives ${svc} a living openapi.yaml, so this feature is the only thing that can write down its API surface.`,
                 command: `loam delta ${id} --service ${svc} --json`,
                 artifact: "openapi",
                 service: svc,
@@ -798,10 +863,11 @@ async function scanDeltas(docsDir, feature, services, context) {
     const out = [];
     for (const svc of services) {
         const p = featureSpecPaths(feature.dir, svc);
-        for (const [file, label] of [
-            [p.spec, `${svc}: requirements`],
-            [p.archSpec, `${svc}: arch requirements`],
-        ]) {
+        // SPEC_AXES already carries the prose name of each axis — "requirements"
+        // and "arch requirements" are its `label`s verbatim — so the pair is read
+        // from there rather than spelled again, and a service's status can never
+        // walk a different set of spec files than its validation does.
+        for (const [file, label] of SPEC_AXES.map((axis) => [p[axis.key], `${svc}: ${axis.label}`])) {
             if (!existsSync(file))
                 continue;
             const reqs = await context.readRequirements(file);
@@ -839,10 +905,20 @@ export async function fleetStatus(docsDir, opts = {}) {
     const narrowed = opts.service;
     const all = await listServices(docsDir, context);
     const services = narrowed === undefined ? all : all.filter((s) => s.id === narrowed);
+    // The service this repository says it IS, when the fleet has never heard of
+    // it. Asked against the UNNARROWED list, because "is it adopted" is a question
+    // about the fleet and not about the view.
+    const unadopted = opts.bound !== undefined && !all.some((s) => s.id === opts.bound) ? opts.bound : null;
     const graph = await analyzeDependencies(docsDir, undefined, context);
     const entries = await listFeatures(docsDir, {}, context);
     const inScope = narrowed === undefined ? entries : entries.filter((f) => f.services.includes(narrowed));
-    const features = await Promise.all(inScope.map(async (f) => fleetFeature(docsDir, f, graph, await contractsInFlight(docsDir, f.id, context), context)));
+    // Once for the fleet, not once per feature: which features hold a contract
+    // for which service is one fact about the repository, and every feature below
+    // reads its own row out of it. Built over the UNNARROWED list on purpose — a
+    // `--service` view still has to know that a feature outside it discharges the
+    // contract, or the narrowing would invent an obligation.
+    const owners = await contractOwners(docsDir, context);
+    const features = await Promise.all(inScope.map((f) => fleetFeature(docsDir, f, graph, contractsHeldElsewhere(owners, f.id), context, interrupted)));
     features.sort((a, b) => compareIds(a.id, b.id));
     return {
         interrupted,
@@ -855,7 +931,11 @@ export async function fleetStatus(docsDir, opts = {}) {
         features,
         order: graph.order.filter((id) => features.some((f) => f.id === id)),
         service: narrowed ?? null,
-        next: fleetNext(services, features, graph, interrupted),
+        // The binding is passed only when this run was NOT narrowed. `--service X`
+        // is an explicit question about X, and answering it with a step about
+        // whichever service loam.json happens to name would be a different
+        // question's answer at the top of the list.
+        next: fleetNext(services, features, graph, interrupted, narrowed === undefined ? unadopted : null),
     };
 }
 /** Nothing is written down: no living spec at all. Every other absence is partial adoption. */
@@ -866,7 +946,7 @@ function undocumented(s) {
 function vouched(s) {
     return s.status === "verified" && s.sources.stamped;
 }
-async function fleetFeature(docsDir, feature, graph, contracted, context) {
+async function fleetFeature(docsDir, feature, graph, contracted, context, interrupted) {
     const paths = featurePaths(feature.dir);
     const missing = [];
     if (!existsSync(paths.intent))
@@ -893,13 +973,23 @@ async function fleetFeature(docsDir, feature, graph, contracted, context) {
     // No `draft` here, ever: that verdict needs the coherence run this form
     // refuses to pay for, and inferring it from presence alone would be a second
     // opinion about validity — the one thing status must never invent.
-    const stage = missing.length > 0
-        ? "missing"
-        : blockedBy.length > 0
-            ? "blocked"
-            : fullyVerified(verification)
-                ? "done"
-                : "ready";
+    //
+    // The interrupted commit leads, exactly as it does in the feature form: every
+    // presence test below is a question about files a killed `archive` may have
+    // half-written, so answering `done` from them is a claim about bytes nobody
+    // has established. Without this the two forms contradicted each other over
+    // one repository — `loam status --json` said `done` and offered "ship it"
+    // while `loam status <FEAT>` said `blocked` — and the module header's rule is
+    // that this projection is never greener than the gates.
+    const stage = interrupted !== null
+        ? "blocked"
+        : missing.length > 0
+            ? "missing"
+            : blockedBy.length > 0
+                ? "blocked"
+                : fullyVerified(verification)
+                    ? "done"
+                    : "ready";
     return {
         id: feature.id,
         dirName: feature.dirName,
@@ -945,8 +1035,28 @@ export const FLEET_NEXT_LIMIT = 10;
  * once named the command CI runs. This form grades nothing; the least it can do
  * is say where grading happens.
  */
-function fleetNext(services, features, graph, interrupted) {
+function fleetNext(services, features, graph, interrupted, unadoptedBinding) {
     const steps = [];
+    // The repository this command is standing in names a service the fleet has no
+    // directory for. First, ahead of every other service's partial adoption,
+    // because it is the only step that is about HERE.
+    //
+    // This form used to count the fleet and ignore the binding entirely, so in a
+    // service repo bound to an unadopted service — a freshly wired one, the most
+    // common repo there is — an empty fleet made "every service is written down"
+    // vacuously true and `next.fleet-clean` came out top. `loam doctor` had the
+    // right answer (`doctor.service-unknown`) at the same moment, and the
+    // documented agent loop reads `status`: an agent following it was sent to
+    // start a feature instead of adopting the service under its feet.
+    if (unadoptedBinding !== null) {
+        steps.push({
+            code: "next.adopt-bound",
+            statement: `This repository's loam.json says it is '${unadoptedBinding}', and the fleet has no ` +
+                `services/${unadoptedBinding}/ — nothing about the service you are standing in is written down yet.`,
+            command: `loam adopt --service ${unadoptedBinding} --json`,
+            service: unadoptedBinding,
+        });
+    }
     for (const s of services.filter(undocumented)) {
         steps.push({
             code: "next.adopt",
@@ -981,7 +1091,14 @@ function fleetNext(services, features, graph, interrupted) {
         }
         steps.push({
             code: "next.feature",
-            statement: f.stage === "blocked"
+            statement: 
+            // The list, not the stage, is what this sentence names. `blocked` has
+            // two causes now — another feature in flight, and an interrupted commit
+            // that stalls the whole repository — and the second one names no
+            // feature, so keying off the stage alone printed "FEAT-1 is waiting
+            // on ." The recover step above already says what the repository is
+            // waiting on.
+            f.stage === "blocked" && f.blockedBy.length > 0
                 ? `${f.id} is waiting on ${f.blockedBy.join(", ")}.`
                 : `${f.id} is at '${f.stage}'${f.missing.length > 0 ? ` — missing ${f.missing.join(", ")}` : ""}.`,
             command: `loam status ${f.id} --json`,