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

package/dist/core/repo/tree/walk.js

@@ -0,0 +1,255 @@
+/**
+ * The tree read model: three-way classification of everything under
+ * `services/`, in one walk.
+ *
+ * A directory holding `subsystem.yaml` is a SUBSYSTEM and is walked; one
+ * holding any service artifact is a SERVICE and is not walked deeper — unless
+ * a marker sits BESIDE the artifacts, where the walk descends anyway (the
+ * marker says a group was here, and its members must not vanish); one holding
+ * neither while containing subdirectories is an ERROR that still names every
+ * service found beneath it. The third branch is the whole point:
+ * two-way classification loses a service silently on an ordinary clean merge —
+ * one branch deletes an emptied subsystem's marker while another moves a
+ * service into it, and the group directory is then read as a service whose
+ * real services vanish from the fleet with no finding. No directory under
+ * `services/` may ever be reinterpreted as a different kind without saying so,
+ * and the fleet is never reported smaller: the walk descends into the broken
+ * group precisely so the stranded services stay enumerated and named.
+ *
+ * The package direction is `repo → repo/tree`, never back. That is why the
+ * artifact-name question arrives INJECTED (`TreeWalkRequest.isServiceArtifact`
+ * — `repo/paths.ts` owns the spellings and `repo/repo.ts` builds the request):
+ * importing `paths.ts` from here while `repo.ts` delegates its enumeration to
+ * this walk would close the exact package cycle `scripts/package-graph.mjs`
+ * exists to refuse.
+ *
+ * A SERVICE'S OWN SUBDIRECTORIES ARE NEVER CLASSIFIED (`RESERVED_INTERIOR`).
+ * That is a different question from `isServiceArtifact`, which asks whether a
+ * name makes the directory holding it a service; this asks whether a child
+ * directory may be READ as one at all, and the two answers diverged the moment
+ * SCHEMA's service layout grew a slot the artifact table does not carry. A
+ * `services/<svc>/` holding only the documented `usecases/` flow directory was
+ * classified as a group: the walk descended, filed `usecases` as a service, and
+ * one `loam validate --all` reported `subsystem.unmarked`,
+ * `landscape.service-unmodelled` for `services/<svc>/usecases/` and
+ * `landscape.binding-unknown` for the real service — three errors whose text
+ * says the fleet is losing services, earned by following the instruction `loam
+ * init` had just scaffolded (verification 2026-09-04). The names are SCHEMA's
+ * service layout, and a directory named for one is service interior wherever it
+ * sits, so no branch of the classification descends into one.
+ *
+ * Cost: exactly one readdir per directory walked, service directories included
+ * (their own listing is what classifies them), plus one realpath per directory
+ * for the symlink-cycle guard — `entryIs` follows symlinks on purpose, and a
+ * followed cycle without the visited-set is an unbounded recursion.
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { serviceDirOf, serviceTreePath } from "../../kernel/ids/dirs.js";
+import { rawServiceId } from "../../kernel/ids/service.js";
+import { subsystemNameProblem } from "../../kernel/ids/subsystem.js";
+import { entryIs, markDescended, subdirNames } from "./fs.js";
+import { readSubsystemMarker, SUBSYSTEM_MARKER } from "./marker.js";
+/**
+ * The subdirectory names SCHEMA's service layout reserves for a service's own
+ * interior (`SCHEMA.md`, "services/<svc>/"): `adrs/` the decisions, `usecases/`
+ * the flows drawn over its containers, `ui/` the page-specs. A directory with
+ * one of these names is never a service and never a subsystem — it is inside
+ * one — so the walk neither classifies it nor counts it as a subdirectory that
+ * makes its parent a group.
+ *
+ * Kept here rather than folded into `isServiceArtifact` because the two
+ * questions are not the same one: `adrs/` answers both (it is an artifact AND
+ * interior) and `usecases/` answers only this one today. Widening the injected
+ * artifact table instead would also make a lone `usecases/` classify its parent
+ * as a service by ARTIFACT, which hides a real service filed beside it — the
+ * silent shrink this module refuses.
+ *
+ * Exported for the one other reader of this rule: `core/diff/base-state.ts`
+ * classifies a base git ref's tree listing, which no walk can readdir, and its
+ * banner already commits it to restating this module's branches rather than
+ * inventing its own. It shares the SET for the reason it shares the artifact
+ * table — a name respelled there is the drift both modules are written to
+ * avoid.
+ */
+export const RESERVED_INTERIOR = new Set(["adrs", "usecases", "ui"]);
+export async function walkServicesTree(request) {
+    const ctx = {
+        request,
+        tree: { services: [], subsystems: [], findings: [] },
+        visited: new Set(),
+        names: new Map(),
+    };
+    const root = join(request.docsDir, "services");
+    markDescended(root, ctx.visited);
+    for (const name of await subdirNames(root)) {
+        await visitDir({ dir: join(root, name), name, chain: [] }, ctx);
+    }
+    namespaceFindings(ctx);
+    return ctx.tree;
+}
+/** Classify one directory and, for the group kinds, walk what is inside it. */
+async function visitDir(spot, ctx) {
+    const rel = ["services", ...spot.chain, spot.name].join("/");
+    const entries = (await readdir(spot.dir, { withFileTypes: true })).filter((e) => !e.name.startsWith("."));
+    const files = entries.filter((e) => entryIs(spot.dir, e, "file")).map((e) => e.name);
+    const all = entries.filter((e) => entryIs(spot.dir, e, "dir")).map((e) => e.name).sort();
+    // The classifiable children — a service's own interior removed once, here, so
+    // every branch below agrees about it (see `RESERVED_INTERIOR`). `all` is still
+    // what the artifact probe reads: `adrs/` makes its parent a service, and
+    // `usecases/` is interior the parent may hold without becoming a group.
+    const dirs = all.filter((d) => !RESERVED_INTERIOR.has(d));
+    const marker = files.includes(SUBSYSTEM_MARKER);
+    const artifact = files.some((f) => ctx.request.isServiceArtifact(f, "file")) ||
+        all.some((d) => ctx.request.isServiceArtifact(d, "dir"));
+    if (marker && artifact) {
+        // Artifacts win the classification: the documents are somebody's work and
+        // the marker is one stray file, so the directory stays an addressable
+        // service and the finding names the contradiction instead of the walk
+        // quietly picking a reading. But the walk STILL descends (the module
+        // invariant: no reinterpretation may shrink the fleet) — the marker says
+        // a GROUP was here, and returning without walking made every service
+        // beneath it vanish with only this finding to hint why. Child directories
+        // that are themselves artifacts (`adrs/`) are service interior, not walked.
+        recordService(spot, ctx);
+        const stranded = await descendInto(spot, dirs.filter((d) => !ctx.request.isServiceArtifact(d, "dir")), ctx);
+        ctx.tree.findings.push({
+            severity: "error",
+            code: "subsystem.marker-misplaced",
+            subject: spot.name,
+            message: `${rel}/ holds ${SUBSYSTEM_MARKER} BESIDE service artifacts — a directory is a subsystem or a service, never both. ` +
+                `It stays classified as a service; delete ${rel}/${SUBSYSTEM_MARKER}, ` +
+                `or move the artifacts into a service directory of their own inside the group.` +
+                (stranded.length > 0 ? ` ${stranded.length} service(s) beneath it stay enumerated meanwhile: ${stranded.map((s) => s.id).join(", ")}.` : ""),
+            ...(stranded.length > 0 ? { details: stranded.map(serviceTreePath) } : {}),
+        });
+        return;
+    }
+    if (marker) {
+        await visitSubsystem(spot, { rel, dirs }, ctx);
+        return;
+    }
+    if (artifact) {
+        recordService(spot, ctx);
+        return;
+    }
+    if (dirs.length > 0) {
+        await visitUnmarked(spot, { rel, dirs }, ctx);
+        return;
+    }
+    // Neither marker nor artifact, and nothing beneath: today's flat behaviour —
+    // an empty (or not-yet-adopted) directory under services/ is a service.
+    recordService(spot, ctx);
+}
+function recordService(spot, ctx) {
+    ctx.tree.services.push({
+        id: rawServiceId(spot.name),
+        dir: serviceDirOf(spot.dir),
+        subsystem: spot.chain,
+    });
+    claimName(spot, ctx);
+}
+/** A subsystem: record it, report a broken marker or an illegal name, walk in. */
+async function visitSubsystem(spot, at, ctx) {
+    const meta = await readSubsystemMarker(join(spot.dir, SUBSYSTEM_MARKER));
+    if (meta.invalid !== undefined) {
+        // Exactly one finding per marker file: presence already classified the
+        // directory, so the content failure is metadata, not identity.
+        ctx.tree.findings.push({
+            severity: "error",
+            code: "subsystem.invalid",
+            subject: at.rel,
+            message: `${at.rel}/${SUBSYSTEM_MARKER} cannot be read as subsystem metadata — ${meta.invalid}. ` +
+                `The directory still counts as a subsystem (presence classifies; content is metadata). ` +
+                `Fix the file: a YAML mapping with optional title, description and owner — an empty file is also a valid marker.`,
+        });
+    }
+    const problem = subsystemNameProblem(spot.name, "subsystem directory name");
+    if (problem !== null) {
+        // Walked anyway, mirroring how an illegal service id stays enumerated
+        // (`idProblem`): the directory exists and hiding its subtree would shrink
+        // the fleet over a naming mistake.
+        ctx.tree.findings.push({
+            severity: "error",
+            code: "subsystem.name-invalid",
+            subject: spot.name,
+            message: `${at.rel}/ — ${problem} Rename the directory; its services stay enumerated meanwhile.`,
+        });
+    }
+    ctx.tree.subsystems.push({
+        name: spot.name,
+        path: [...spot.chain, spot.name],
+        dir: spot.dir,
+        meta,
+    });
+    claimName(spot, ctx);
+    await descendInto(spot, at.dirs, ctx);
+}
+/**
+ * Walk the children of a group directory (symlink-cycle guarded), returning
+ * the services newly recorded beneath it — the ONE spelling of descent, so
+ * the three descending branches agree about the guard and the chain.
+ */
+async function descendInto(spot, dirs, ctx) {
+    const before = ctx.tree.services.length;
+    // The guard (`./fs.ts`'s `markDescended`) protects SUBTREES, not entries: a
+    // directory reachable under two names is classified twice — both names
+    // exist and hiding the second would be the silent shrink this module
+    // refuses — but its children are enumerated once, so a symlink cycle
+    // terminates instead of recursing forever.
+    if (markDescended(spot.dir, ctx.visited)) {
+        for (const child of dirs) {
+            await visitDir({ dir: join(spot.dir, child), name: child, chain: [...spot.chain, spot.name] }, ctx);
+        }
+    }
+    return ctx.tree.services.slice(before);
+}
+/**
+ * The refusal branch — a group directory nothing marks. The walk STILL
+ * descends, so the services beneath stay in the enumeration and the finding
+ * can name them: the fleet must never be reported smaller than it is.
+ */
+async function visitUnmarked(spot, at, ctx) {
+    const stranded = await descendInto(spot, at.dirs, ctx);
+    ctx.tree.findings.push({
+        severity: "error",
+        code: "subsystem.unmarked",
+        subject: at.rel,
+        message: `${at.rel}/ is neither a subsystem (no ${SUBSYSTEM_MARKER}) nor a service (no service artifact), ` +
+            `but ${stranded.length} service(s) sit beneath it` +
+            (stranded.length > 0 ? `: ${stranded.map((s) => s.id).join(", ")}. ` : `. `) +
+            `Without the marker this directory would be read as a service and everything under it would vanish from the fleet — ` +
+            `the shape an ordinary merge produces when one branch deletes an emptied subsystem's marker while another moves a service in. ` +
+            `Restore ${at.rel}/${SUBSYSTEM_MARKER} (an empty file is a valid marker), or move the directories out.`,
+        ...(stranded.length > 0 ? { details: stranded.map(serviceTreePath) } : {}),
+    });
+}
+function claimName(spot, ctx) {
+    const rel = ["services", ...spot.chain, spot.name].join("/");
+    ctx.names.set(spot.name, [...(ctx.names.get(spot.name) ?? []), rel]);
+}
+/**
+ * One flat namespace: every subsystem name and service id, unique across the
+ * whole tree at any depth, never colliding with each other. The identity
+ * decision demands it — a service id is its leaf directory name ALONE, so two
+ * leaves spelling one name are one identity claimed twice, wherever they sit.
+ * One finding per name, naming every claimant, so the fix is a choice rather
+ * than a scavenger hunt.
+ */
+function namespaceFindings(ctx) {
+    for (const [name, dirs] of [...ctx.names].sort(([a], [b]) => (a < b ? -1 : 1))) {
+        if (dirs.length < 2)
+            continue;
+        ctx.tree.findings.push({
+            severity: "error",
+            code: "subsystem.name-collision",
+            subject: name,
+            message: `'${name}' is claimed by ${dirs.length} directories in the services/ tree: ${dirs.join(", ")} — ` +
+                `service ids and subsystem names share one flat namespace, unique at any depth, ` +
+                `because a service's identity is its leaf directory name alone and placement never disambiguates it. ` +
+                `Rename all but one.`,
+            details: dirs,
+        });
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/core/repo/tree/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../../../src/core/repo/tree/walk.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The tree read model: three-way classification of everything under\n * `services/`, in one walk.\n *\n * A directory holding `subsystem.yaml` is a SUBSYSTEM and is walked; one\n * holding any service artifact is a SERVICE and is not walked deeper — unless\n * a marker sits BESIDE the artifacts, where the walk descends anyway (the\n * marker says a group was here, and its members must not vanish); one holding\n * neither while containing subdirectories is an ERROR that still names every\n * service found beneath it. The third branch is the whole point:\n * two-way classification loses a service silently on an ordinary clean merge —\n * one branch deletes an emptied subsystem's marker while another moves a\n * service into it, and the group directory is then read as a service whose\n * real services vanish from the fleet with no finding. No directory under\n * `services/` may ever be reinterpreted as a different kind without saying so,\n * and the fleet is never reported smaller: the walk descends into the broken\n * group precisely so the stranded services stay enumerated and named.\n *\n * The package direction is `repo → repo/tree`, never back. That is why the\n * artifact-name question arrives INJECTED (`TreeWalkRequest.isServiceArtifact`\n * — `repo/paths.ts` owns the spellings and `repo/repo.ts` builds the request):\n * importing `paths.ts` from here while `repo.ts` delegates its enumeration to\n * this walk would close the exact package cycle `scripts/package-graph.mjs`\n * exists to refuse.\n *\n * A SERVICE'S OWN SUBDIRECTORIES ARE NEVER CLASSIFIED (`RESERVED_INTERIOR`).\n * That is a different question from `isServiceArtifact`, which asks whether a\n * name makes the directory holding it a service; this asks whether a child\n * directory may be READ as one at all, and the two answers diverged the moment\n * SCHEMA's service layout grew a slot the artifact table does not carry. A\n * `services/<svc>/` holding only the documented `usecases/` flow directory was\n * classified as a group: the walk descended, filed `usecases` as a service, and\n * one `loam validate --all` reported `subsystem.unmarked`,\n * `landscape.service-unmodelled` for `services/<svc>/usecases/` and\n * `landscape.binding-unknown` for the real service — three errors whose text\n * says the fleet is losing services, earned by following the instruction `loam\n * init` had just scaffolded (verification 2026-09-04). The names are SCHEMA's\n * service layout, and a directory named for one is service interior wherever it\n * sits, so no branch of the classification descends into one.\n *\n * Cost: exactly one readdir per directory walked, service directories included\n * (their own listing is what classifies them), plus one realpath per directory\n * for the symlink-cycle guard — `entryIs` follows symlinks on purpose, and a\n * followed cycle without the visited-set is an unbounded recursion.\n */\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { serviceDirOf, serviceTreePath, type DocsDir, type ServiceDir } from \"../../kernel/ids/dirs.js\";\nimport { rawServiceId, type RawServiceId } from \"../../kernel/ids/service.js\";\nimport { subsystemNameProblem } from \"../../kernel/ids/subsystem.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport { entryIs, markDescended, subdirNames } from \"./fs.js\";\nimport { readSubsystemMarker, SUBSYSTEM_MARKER, type SubsystemMeta } from \"./marker.js\";\n\n/**\n * The subdirectory names SCHEMA's service layout reserves for a service's own\n * interior (`SCHEMA.md`, \"services/<svc>/\"): `adrs/` the decisions, `usecases/`\n * the flows drawn over its containers, `ui/` the page-specs. A directory with\n * one of these names is never a service and never a subsystem — it is inside\n * one — so the walk neither classifies it nor counts it as a subdirectory that\n * makes its parent a group.\n *\n * Kept here rather than folded into `isServiceArtifact` because the two\n * questions are not the same one: `adrs/` answers both (it is an artifact AND\n * interior) and `usecases/` answers only this one today. Widening the injected\n * artifact table instead would also make a lone `usecases/` classify its parent\n * as a service by ARTIFACT, which hides a real service filed beside it — the\n * silent shrink this module refuses.\n *\n * Exported for the one other reader of this rule: `core/diff/base-state.ts`\n * classifies a base git ref's tree listing, which no walk can readdir, and its\n * banner already commits it to restating this module's branches rather than\n * inventing its own. It shares the SET for the reason it shares the artifact\n * table — a name respelled there is the drift both modules are written to\n * avoid.\n */\nexport const RESERVED_INTERIOR: ReadonlySet<string> = new Set([\"adrs\", \"usecases\", \"ui\"]);\n\nexport interface WalkedService {\n  id: RawServiceId;\n  dir: ServiceDir;\n  /**\n   * Names of the directories between `services/` and the service, outermost\n   * first. Empty = unfiled — directly under `services/`, which is permanent,\n   * normal and SILENT. For a service stranded under an unmarked group the\n   * chain still records the physical placement: the path is a fact even while\n   * `subsystem.unmarked` says the grouping is broken.\n   */\n  subsystem: string[];\n}\n\nexport interface SubsystemEntry {\n  /** The directory name — the subsystem's name in the flat namespace. */\n  name: string;\n  /** Names from `services/` down to and including this one. */\n  path: string[];\n  /** Absolute path of the subsystem directory. */\n  dir: string;\n  meta: SubsystemMeta;\n}\n\nexport interface FleetTree {\n  services: WalkedService[];\n  subsystems: SubsystemEntry[];\n  findings: Finding[];\n}\n\nexport interface TreeWalkRequest {\n  docsDir: DocsDir;\n  /** Does this entry name a service artifact? `repo/paths.ts`'s table, injected — the module doc says why. */\n  isServiceArtifact: (name: string, kind: \"file\" | \"dir\") => boolean;\n}\n\ninterface WalkContext {\n  request: TreeWalkRequest;\n  tree: FleetTree;\n  /** Realpaths already DESCENDED into — the symlink-cycle guard. */\n  visited: Set<string>;\n  /** Every name in the flat namespace → the directories that claim it. */\n  names: Map<string, string[]>;\n}\n\n/** One directory the walk is looking at: where it is, and how it is reached. */\ninterface Spot {\n  dir: string;\n  name: string;\n  /** Directory names between `services/` and this one, outermost first. */\n  chain: string[];\n}\n\nexport async function walkServicesTree(request: TreeWalkRequest): Promise<FleetTree> {\n  const ctx: WalkContext = {\n    request,\n    tree: { services: [], subsystems: [], findings: [] },\n    visited: new Set(),\n    names: new Map(),\n  };\n  const root = join(request.docsDir, \"services\");\n  markDescended(root, ctx.visited);\n  for (const name of await subdirNames(root)) {\n    await visitDir({ dir: join(root, name), name, chain: [] }, ctx);\n  }\n  namespaceFindings(ctx);\n  return ctx.tree;\n}\n\n/** Classify one directory and, for the group kinds, walk what is inside it. */\nasync function visitDir(spot: Spot, ctx: WalkContext): Promise<void> {\n  const rel = [\"services\", ...spot.chain, spot.name].join(\"/\");\n  const entries = (await readdir(spot.dir, { withFileTypes: true })).filter((e) => !e.name.startsWith(\".\"));\n  const files = entries.filter((e) => entryIs(spot.dir, e, \"file\")).map((e) => e.name);\n  const all = entries.filter((e) => entryIs(spot.dir, e, \"dir\")).map((e) => e.name).sort();\n  // The classifiable children — a service's own interior removed once, here, so\n  // every branch below agrees about it (see `RESERVED_INTERIOR`). `all` is still\n  // what the artifact probe reads: `adrs/` makes its parent a service, and\n  // `usecases/` is interior the parent may hold without becoming a group.\n  const dirs = all.filter((d) => !RESERVED_INTERIOR.has(d));\n  const marker = files.includes(SUBSYSTEM_MARKER);\n  const artifact =\n    files.some((f) => ctx.request.isServiceArtifact(f, \"file\")) ||\n    all.some((d) => ctx.request.isServiceArtifact(d, \"dir\"));\n\n  if (marker && artifact) {\n    // Artifacts win the classification: the documents are somebody's work and\n    // the marker is one stray file, so the directory stays an addressable\n    // service and the finding names the contradiction instead of the walk\n    // quietly picking a reading. But the walk STILL descends (the module\n    // invariant: no reinterpretation may shrink the fleet) — the marker says\n    // a GROUP was here, and returning without walking made every service\n    // beneath it vanish with only this finding to hint why. Child directories\n    // that are themselves artifacts (`adrs/`) are service interior, not walked.\n    recordService(spot, ctx);\n    const stranded = await descendInto(spot, dirs.filter((d) => !ctx.request.isServiceArtifact(d, \"dir\")), ctx);\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.marker-misplaced\",\n      subject: spot.name,\n      message:\n        `${rel}/ holds ${SUBSYSTEM_MARKER} BESIDE service artifacts — a directory is a subsystem or a service, never both. ` +\n        `It stays classified as a service; delete ${rel}/${SUBSYSTEM_MARKER}, ` +\n        `or move the artifacts into a service directory of their own inside the group.` +\n        (stranded.length > 0 ? ` ${stranded.length} service(s) beneath it stay enumerated meanwhile: ${stranded.map((s) => s.id).join(\", \")}.` : \"\"),\n      ...(stranded.length > 0 ? { details: stranded.map(serviceTreePath) } : {}),\n    });\n    return;\n  }\n  if (marker) {\n    await visitSubsystem(spot, { rel, dirs }, ctx);\n    return;\n  }\n  if (artifact) {\n    recordService(spot, ctx);\n    return;\n  }\n  if (dirs.length > 0) {\n    await visitUnmarked(spot, { rel, dirs }, ctx);\n    return;\n  }\n  // Neither marker nor artifact, and nothing beneath: today's flat behaviour —\n  // an empty (or not-yet-adopted) directory under services/ is a service.\n  recordService(spot, ctx);\n}\n\nfunction recordService(spot: Spot, ctx: WalkContext): void {\n  ctx.tree.services.push({\n    id: rawServiceId(spot.name),\n    dir: serviceDirOf(spot.dir),\n    subsystem: spot.chain,\n  });\n  claimName(spot, ctx);\n}\n\n/** A subsystem: record it, report a broken marker or an illegal name, walk in. */\nasync function visitSubsystem(spot: Spot, at: { rel: string; dirs: string[] }, ctx: WalkContext): Promise<void> {\n  const meta = await readSubsystemMarker(join(spot.dir, SUBSYSTEM_MARKER));\n  if (meta.invalid !== undefined) {\n    // Exactly one finding per marker file: presence already classified the\n    // directory, so the content failure is metadata, not identity.\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.invalid\",\n      subject: at.rel,\n      message:\n        `${at.rel}/${SUBSYSTEM_MARKER} cannot be read as subsystem metadata — ${meta.invalid}. ` +\n        `The directory still counts as a subsystem (presence classifies; content is metadata). ` +\n        `Fix the file: a YAML mapping with optional title, description and owner — an empty file is also a valid marker.`,\n    });\n  }\n  const problem = subsystemNameProblem(spot.name, \"subsystem directory name\");\n  if (problem !== null) {\n    // Walked anyway, mirroring how an illegal service id stays enumerated\n    // (`idProblem`): the directory exists and hiding its subtree would shrink\n    // the fleet over a naming mistake.\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.name-invalid\",\n      subject: spot.name,\n      message: `${at.rel}/ — ${problem} Rename the directory; its services stay enumerated meanwhile.`,\n    });\n  }\n  ctx.tree.subsystems.push({\n    name: spot.name,\n    path: [...spot.chain, spot.name],\n    dir: spot.dir,\n    meta,\n  });\n  claimName(spot, ctx);\n  await descendInto(spot, at.dirs, ctx);\n}\n\n/**\n * Walk the children of a group directory (symlink-cycle guarded), returning\n * the services newly recorded beneath it — the ONE spelling of descent, so\n * the three descending branches agree about the guard and the chain.\n */\nasync function descendInto(spot: Spot, dirs: string[], ctx: WalkContext): Promise<WalkedService[]> {\n  const before = ctx.tree.services.length;\n  // The guard (`./fs.ts`'s `markDescended`) protects SUBTREES, not entries: a\n  // directory reachable under two names is classified twice — both names\n  // exist and hiding the second would be the silent shrink this module\n  // refuses — but its children are enumerated once, so a symlink cycle\n  // terminates instead of recursing forever.\n  if (markDescended(spot.dir, ctx.visited)) {\n    for (const child of dirs) {\n      await visitDir({ dir: join(spot.dir, child), name: child, chain: [...spot.chain, spot.name] }, ctx);\n    }\n  }\n  return ctx.tree.services.slice(before);\n}\n\n/**\n * The refusal branch — a group directory nothing marks. The walk STILL\n * descends, so the services beneath stay in the enumeration and the finding\n * can name them: the fleet must never be reported smaller than it is.\n */\nasync function visitUnmarked(spot: Spot, at: { rel: string; dirs: string[] }, ctx: WalkContext): Promise<void> {\n  const stranded = await descendInto(spot, at.dirs, ctx);\n  ctx.tree.findings.push({\n    severity: \"error\",\n    code: \"subsystem.unmarked\",\n    subject: at.rel,\n    message:\n      `${at.rel}/ is neither a subsystem (no ${SUBSYSTEM_MARKER}) nor a service (no service artifact), ` +\n      `but ${stranded.length} service(s) sit beneath it` +\n      (stranded.length > 0 ? `: ${stranded.map((s) => s.id).join(\", \")}. ` : `. `) +\n      `Without the marker this directory would be read as a service and everything under it would vanish from the fleet — ` +\n      `the shape an ordinary merge produces when one branch deletes an emptied subsystem's marker while another moves a service in. ` +\n      `Restore ${at.rel}/${SUBSYSTEM_MARKER} (an empty file is a valid marker), or move the directories out.`,\n    ...(stranded.length > 0 ? { details: stranded.map(serviceTreePath) } : {}),\n  });\n}\n\nfunction claimName(spot: Spot, ctx: WalkContext): void {\n  const rel = [\"services\", ...spot.chain, spot.name].join(\"/\");\n  ctx.names.set(spot.name, [...(ctx.names.get(spot.name) ?? []), rel]);\n}\n\n/**\n * One flat namespace: every subsystem name and service id, unique across the\n * whole tree at any depth, never colliding with each other. The identity\n * decision demands it — a service id is its leaf directory name ALONE, so two\n * leaves spelling one name are one identity claimed twice, wherever they sit.\n * One finding per name, naming every claimant, so the fix is a choice rather\n * than a scavenger hunt.\n */\nfunction namespaceFindings(ctx: WalkContext): void {\n  for (const [name, dirs] of [...ctx.names].sort(([a], [b]) => (a < b ? -1 : 1))) {\n    if (dirs.length < 2) continue;\n    ctx.tree.findings.push({\n      severity: \"error\",\n      code: \"subsystem.name-collision\",\n      subject: name,\n      message:\n        `'${name}' is claimed by ${dirs.length} directories in the services/ tree: ${dirs.join(\", \")} — ` +\n        `service ids and subsystem names share one flat namespace, unique at any depth, ` +\n        `because a service's identity is its leaf directory name alone and placement never disambiguates it. ` +\n        `Rename all but one.`,\n      details: dirs,\n    });\n  }\n}\n"]}

package/dist/core/results.js

@@ -23,24 +23,127 @@
  * reports @Before/@After hook results in per-element `before[]`/`after[]`
  * arrays (a teardown assertion fails there while every step stays `passed`),
  * and behave carries an element-level `status` that a hook failure flips.
+ * cucumber-js puts its hooks among the `steps[]` instead, as entries marked
+ * `hidden` with the keyword `Before`/`After`, and they are read as hooks
+ * there too — the number of real steps is contract now, because a run is
+ * held to the step count of the scenario it claims to be (`runnerAnswers`).
  * Only those fields are contract: unknown fields, tagless elements
  * (backgrounds, hand-written scenarios) and stray entries are skipped without
  * comment. What is NOT tolerated is a file that is not that array at all: a
  * report loam cannot recognize must refuse rather than quietly answer every
  * claim "not found".
  */
-import { DIGEST_TAG_RE, scenarioDigestTag } from "./gherkin.js";
-import { isRecord } from "./records.js";
+import { DIGEST_TAG_RE, scenarioDigestTag } from "./gherkin/stamp.js";
+import { isRecord } from "./kernel/records.js";
 /**
  * Read a parsed cucumber JSON document down to its digest-tagged scenarios.
  * `reportName` is how the caller spelled the file, for the refusal message.
  */
+/** The marker key that makes a JSON document loam's own scenario shape, and the version this loam reads. */
+export const SCENARIO_REPORT_MARKER = "loamScenarioReport";
+export const SCENARIO_REPORT_VERSION = 1;
+/**
+ * Is this document loam's own scenario-report shape rather than a cucumber one?
+ *
+ * Marker-only, deliberately: the caller must be able to choose a READER before
+ * either has validated anything, so that a malformed `loamScenarioReport` file
+ * refuses as a malformed report of ITS kind rather than as "not a cucumber
+ * array". A file that claims the shape and then fails it must never fall
+ * through to the other parser and be told it is the wrong sort of document.
+ */
+export function isScenarioReport(doc) {
+    return isRecord(doc) && doc[SCENARIO_REPORT_MARKER] !== undefined;
+}
+/**
+ * `{"loamScenarioReport": 1, "results": [{"digest": "…", "status": "passed"}]}`
+ * — the runner-neutral answer sheet for `scenario.tested` claims.
+ *
+ * WHY THIS EXISTS. `loam gherkin` stamps every generated scenario
+ * `@loam-digest-<16hex>`, and until now only cucumber's JSON carried that tag
+ * back. A fleet on JUnit, pytest, Playwright, Vitest or a house runner could
+ * therefore never reach `verified` — not because its evidence was weaker, but
+ * because of a file format. The example fleet's own shipped record is the proof
+ * of the cost: every claim in it is `answered_by: agent`, so the product's
+ * showcase demonstrates only the lesser verdict.
+ *
+ * THE STANDARD OF PROOF IS UNCHANGED, and that is the whole argument. The
+ * contract was never the JSON dialect: it is the digest — content-derived, so
+ * rewording a `Given` breaks the match — plus a status that says a real run
+ * reported it green. Both halves are here. An answer from this file is
+ * `answered_by: runner` exactly as a cucumber one is, because it is the same
+ * claim answered to the same standard by the same identity.
+ *
+ * It also adds no forgeability. loam cannot prove any JSON came from executing
+ * a commit — SCHEMA says so, and the record stores the file's sha256 and mtime
+ * precisely because that is all it can honestly claim. A hand-written cucumber
+ * array was always exactly as easy to write as this is.
+ *
+ * The strict/tolerant split mirrors `verify/evidence/contract.ts` for its
+ * reason: a cucumber report is another tool's file full of entries loam has no
+ * business judging, while this shape exists for one purpose, so a malformed
+ * entry is a malformed report rather than scenery to skip. `status` must be
+ * exactly `passed` or `failed`; `skipped`, `pending` and vendor spellings are
+ * refused rather than guessed at, because guessing is how a not-run scenario
+ * becomes a confirmation.
+ */
+export function readScenarioReport(doc, reportName) {
+    if (!isRecord(doc)) {
+        return { ok: false, message: `${reportName} is not a JSON object.` };
+    }
+    const version = doc[SCENARIO_REPORT_MARKER];
+    if (version !== SCENARIO_REPORT_VERSION) {
+        return {
+            ok: false,
+            message: `${reportName} declares \`${SCENARIO_REPORT_MARKER}: ${JSON.stringify(version)}\`, and this loam reads ` +
+                `version ${SCENARIO_REPORT_VERSION}. A report loam cannot read is refused rather than answered in part.`,
+        };
+    }
+    const results = doc["results"];
+    if (!Array.isArray(results)) {
+        return {
+            ok: false,
+            message: `${reportName} has no \`results\` array — the shape is {"${SCENARIO_REPORT_MARKER}": 1, "results": [{"digest": "…", "status": "passed"}]}.`,
+        };
+    }
+    const scenarios = [];
+    for (const [i, entry] of results.entries()) {
+        const at = `${reportName} results[${i}]`;
+        if (!isRecord(entry))
+            return { ok: false, message: `${at} is not an object.` };
+        const digest = str(entry["digest"]);
+        if (digest === undefined || !/^[0-9a-f]{16}$/.test(digest)) {
+            return {
+                ok: false,
+                message: `${at} has no \`digest\` of 16 lowercase hex characters — that is the \`@loam-digest-…\` tag \`loam gherkin\` stamped on the scenario.`,
+            };
+        }
+        const status = str(entry["status"]);
+        if (status !== "passed" && status !== "failed") {
+            return {
+                ok: false,
+                message: `${at} has \`status: ${JSON.stringify(entry["status"])}\`; this shape accepts only "passed" or "failed". ` +
+                    "A scenario that did not run has no place in an answer sheet — omit it, and its claim stays unanswered rather than becoming a confirmation.",
+            };
+        }
+        scenarios.push({
+            // The runner's own name for the test, when it gave one — this is where a
+            // reader goes to see the run, and it is the only free text here.
+            where: str(entry["test"]) ?? `(${SCENARIO_REPORT_MARKER} entry ${i})`,
+            digests: [digest],
+            steps: [status],
+            stepwise: false,
+            hooks: [],
+        });
+    }
+    return { ok: true, scenarios };
+}
 export function readCucumberReport(doc, reportName) {
     if (!Array.isArray(doc)) {
         return {
             ok: false,
             message: `${reportName} is not a cucumber JSON report — expected the top-level array of features ` +
-                "that `cucumber-js --format json` (or cucumber-jvm, behave, SpecFlow) emits.",
+                "that `cucumber-js --format json` (or cucumber-jvm, behave, SpecFlow) emits. " +
+                `A runner with no cucumber formatter answers through loam's own shape instead: {"${SCENARIO_REPORT_MARKER}": 1, "results": [{"digest": "…", "status": "passed"}]}.`,
         };
     }
     const scenarios = [];
@@ -68,17 +171,24 @@ export function readCucumberReport(doc, reportName) {
             // scenario, another tool's output. Invisible here, deliberately.
             if (digests.length === 0)
                 continue;
-            const resultStatuses = (raw) => {
-                if (!Array.isArray(raw))
-                    return [];
-                return raw.map((s) => {
-                    const status = isRecord(s) && isRecord(s["result"]) ? str(s["result"]["status"]) : undefined;
-                    return (status ?? "unknown").toLowerCase();
-                });
+            const statusOf = (s) => {
+                const status = isRecord(s) && isRecord(s["result"]) ? str(s["result"]["status"]) : undefined;
+                return (status ?? "unknown").toLowerCase();
             };
-            const steps = resultStatuses(el["steps"]);
+            const resultStatuses = (raw) => (Array.isArray(raw) ? raw.map(statusOf) : []);
+            // cucumber-js reports its Before/After hooks INSIDE `steps`, as entries
+            // marked `hidden` with the keyword `Before`/`After`; they are hooks, not
+            // steps of the scenario, and counting them would make every hooked run
+            // look like a different scenario from the one stamped.
+            const listed = Array.isArray(el["steps"]) ? el["steps"] : [];
+            const isHook = (s) => isRecord(s) && (s["hidden"] === true || /^(before|after)$/i.test(str(s["keyword"])?.trim() ?? ""));
+            const steps = listed.filter((s) => !isHook(s)).map(statusOf);
             // cucumber-jvm's @Before/@After hooks: separate arrays, same result shape.
-            const hooks = [...resultStatuses(el["before"]), ...resultStatuses(el["after"])];
+            const hooks = [
+                ...resultStatuses(el["before"]),
+                ...listed.filter(isHook).map(statusOf),
+                ...resultStatuses(el["after"]),
+            ];
             // behave's element-level status — a hook failure flips it while the
             // steps that already ran keep "passed".
             const status = str(el["status"])?.toLowerCase();
@@ -86,6 +196,7 @@ export function readCucumberReport(doc, reportName) {
                 where: `${featureName} › ${str(el["name"]) ?? "(unnamed scenario)"}`,
                 digests,
                 steps,
+                stepwise: true,
                 hooks,
                 ...(status === undefined ? {} : { status }),
             });
@@ -139,6 +250,14 @@ export function contestedDigests(claims) {
  * occurrence wins as failure, a skipped-only run is "skipped" not green, and
  * no match at all is "not found in report". A digest two services share is
  * refused before any of that: see {@link contestedDigests}.
+ *
+ * And a cucumber occurrence must have run as many steps as the stamped
+ * scenario has (`Claim.steps`). The digest is only a tag, and a tag is text:
+ * a one-step stub named "a step" carrying the right digest confirmed
+ * five-step scenarios, because nothing compared what ran with what was
+ * stamped. The count is the check every dialect can be held to; loam's own
+ * runner-neutral shape carries no steps to count, so its entries are held to
+ * their status alone, as that shape has always promised.
  */
 export function runnerAnswers(claims, scenarios, reportName) {
     const contested = contestedDigests(claims);
@@ -153,13 +272,16 @@ export function runnerAnswers(claims, scenarios, reportName) {
             const tag = c.digest === undefined ? "a digest tag" : scenarioDigestTag(c.digest);
             return answer(c.id, "unconfirmed", [], `not found in report — no scenario in ${reportName} carries ${tag}`);
         }
-        const failing = runs.filter((r) => !passed(r));
+        const failing = runs.filter((r) => !passed(r) || !sameShape(r, c.steps));
         if (failing.length === 0) {
             return answer(c.id, "confirmed", runs.map((r) => `${reportName}: ${r.where}`));
         }
         const first = failing[0];
         const rerun = runs.length > 1 ? ` — ${failing.length} of ${runs.length} matching runs failed` : "";
-        return answer(c.id, "unconfirmed", [], `${reason(first)} (${reportName}: ${first.where})${rerun}`);
+        const why = passed(first)
+            ? `ran ${first.steps.length} step(s) where the stamped scenario has ${c.steps} — the report's scenario is not the one \`loam gherkin\` stamped with this digest`
+            : reason(first);
+        return answer(c.id, "unconfirmed", [], `${why} (${reportName}: ${first.where})${rerun}`);
     });
 }
 function answer(id, verdict, evidence, note) {
@@ -179,6 +301,16 @@ function passed(r) {
         r.hooks.every((h) => h === "passed") &&
         (r.status === undefined || r.status === "passed"));
 }
+/**
+ * Did this run execute the scenario the claim stamped — as far as the report
+ * can say? A cucumber run must have run exactly the stamped number of steps.
+ * An entry with no step structure (loam's own shape), and a claim carrying no
+ * count (only `scenario.tested` claims carry one, and only they carry a digest
+ * to match), are held to their status alone.
+ */
+function sameShape(r, expected) {
+    return !r.stepwise || expected === undefined || r.steps.length === expected;
+}
 /** Why a run did not pass, naming the step, hook or element status that says so. */
 function reason(r) {
     if (r.steps.length === 0)