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

package/dist/core/delta/select.js

@@ -0,0 +1,237 @@
+/**
+ * What each delta requirement SELECTS in the living document, and whether the
+ * merge would do what its author meant.
+ *
+ * This is the half that needs both documents at once, which is why it is not in
+ * `./document.ts`. Every refusal here is a shape the merge would apply cleanly
+ * and silently: MODIFIED of a requirement that does not exist is merged as a
+ * creation, ADDED of one that does exist REPLACES it scenarios and all, and a
+ * stale `Based-On:` means someone landed a change in between that this delta
+ * would overwrite with text written against a document that no longer exists.
+ */
+import {} from "../vocabulary/issue.js";
+import { isRequirementsHeading } from "../document/parse.js";
+import { basedOnDeclarations, REQUIREMENT_DIGEST_RE, requirementDigest, } from "../document/spec.js";
+import {} from "./claims.js";
+import {} from "./scope.js";
+export async function selectionIssues(scope, reqs, living, claims) {
+    const { featureId, subject, where, livingDoc } = scope;
+    const issues = [];
+    /**
+     * The pin, against the living requirement this delta actually selects.
+     *
+     * This is the check `delta.modified-conflict` cannot be: that one names
+     * the other feature while BOTH are in flight, and the collision that
+     * happens on a fleet outlives the window. A archives, leaves `features/`,
+     * and stops being an active claim; B revalidates GREEN, and its MODIFIED —
+     * carrying the full text it wrote against the pre-A document — replaces
+     * A's requirement wholesale, scenarios and all, with `+0 ~1 -0` and exit
+     * 0. Nothing downstream can even detect it afterwards: `unarchive A`
+     * refuses `snapshot-stale`, and `--force` takes B out with it.
+     *
+     * A digest of what the author read closes that by not depending on
+     * timing at all. Stale is an ERROR and gates, because there is no reading
+     * of a stale delta under which the merge is what its author meant.
+     * Missing is a warning that GATES: the document is legal — a delta
+     * adopted from OpenSpec never had the line — but an unpinned MODIFIED or
+     * REMOVED is exactly the timing hole the pin exists to close, and letting
+     * it through archived the silent rollback at exit 0. The migrated corpus
+     * is why this stays a warning rather than an error, and why the refusal
+     * is not an outage: `loam rebase <feat>` pins every delta in one command,
+     * and `--approve` remains the way to say the unpinned merge is meant.
+     */
+    const checkBaseline = (r, selected) => {
+        // A pin the document pass already refused is not also stale: that would
+        // send its author to `loam rebase` for a problem rebase does not fix.
+        const declared = basedOnDeclarations(r);
+        if (declared.length > 1)
+            return;
+        if (r.basedOn !== undefined && !REQUIREMENT_DIGEST_RE.test(r.basedOn))
+            return;
+        const current = requirementDigest(selected);
+        if (r.basedOn === undefined) {
+            issues.push({
+                severity: "warn",
+                gates: true,
+                code: "delta.baseline-missing",
+                subject,
+                message: `${where}: ${r.kind} requirement '${r.name}' carries no Based-On, so nothing can say whether the living text moved since this delta was written — merging it would replace whatever landed in between. Run \`loam rebase ${featureId}\` to pin it (Based-On: ${current}), or archive with --approve to merge unpinned deliberately.`,
+            });
+            return;
+        }
+        if (r.basedOn === current)
+            return;
+        issues.push({
+            severity: "error",
+            code: "delta.baseline-stale",
+            subject,
+            message: `${where}: ${r.kind} requirement '${r.name}' was written against living version ${r.basedOn}, but the ${livingDoc} now holds ${current} — someone landed a change to it in between. ` +
+                (r.kind === "MODIFIED"
+                    ? `This MODIFIED carries its FULL new text, so merging it would replace theirs outright.`
+                    : `Merging this REMOVED would delete what they landed.`) +
+                ` Re-read the living requirement, fold in what you still mean, then run \`loam rebase ${featureId}\`.`,
+        });
+    };
+    for (const r of reqs) {
+        // BASE in a delta file means the requirement is under no delta section, so
+        // the merge skips it. Reported rather than merged: deciding that `## Behavior`
+        // means ADDED would be archive guessing at intent, and it would guess wrong
+        // for every prose section that quotes a requirement as documentation. A
+        // requirement above every heading has no heading to name, and no claim to be
+        // written in the delta grammar at all — same judgement as `## Requirements`.
+        //
+        // A warning that GATES archive — the one check where the two axes
+        // diverge. Severity says whether the document is valid: this shape is
+        // legal OpenSpec, so an error would fail `loam validate` on every
+        // adopted repo whose active deltas still use it. Gating says whether
+        // the merge is safe: it is not — the merge would silently drop authored
+        // content, the exact loss this module exists to prevent — so archive
+        // refuses, and `--approve` remains the way to say the loss is meant.
+        if (r.kind === "BASE") {
+            if (r.section !== undefined && !isRequirementsHeading(r.section)) {
+                issues.push({
+                    severity: "warn",
+                    gates: true,
+                    code: "delta.requirement-not-merged",
+                    subject,
+                    message: `${where}: requirement '${r.name}' sits under '${r.section}', which is not a delta section — archive will NOT merge it. Move it under '## ADDED Requirements' (or MODIFIED/REMOVED), or drop it if it is documentation.`,
+                });
+            }
+            continue;
+        }
+        if (r.kind === "ADDED") {
+            const idMatches = r.id === undefined ? [] : (living.byId.get(r.id) ?? []);
+            const nameMatches = living.byName.get(r.name) ?? [];
+            const nameSelectsOther = r.id !== undefined && nameMatches.some((candidate) => candidate.id !== r.id);
+            if (nameSelectsOther) {
+                issues.push({
+                    severity: "error",
+                    code: "delta.requirement-identity-collision",
+                    subject,
+                    message: `${where}: ADDED requirement '${r.name}' carries Requirement-ID '${r.id}', but that heading already identifies a different living requirement — ID and name cannot select different identities`,
+                });
+                continue;
+            }
+            if ((r.id === undefined && living.names.has(r.name)) || idMatches.length > 0) {
+                issues.push({
+                    severity: "error",
+                    code: "delta.added-duplicate",
+                    subject,
+                    message: r.id === undefined
+                        ? `${where}: ADDED requirement '${r.name}' already exists in the ${livingDoc} — the merge would REPLACE it, scenarios and all. Use MODIFIED, or rename.`
+                        : `${where}: ADDED requirement '${r.name}' uses Requirement-ID '${r.id}', which already exists in the ${livingDoc} — use MODIFIED to change that identity`,
+                });
+                continue;
+            }
+            // Merge identity is exact string equality (applyRequirementDelta), so a
+            // name that differs only in case slips past the duplicate check above and
+            // lands as a SECOND requirement next to the living one. A warning, not an
+            // error: the author may genuinely mean a distinct requirement, but with
+            // LLM authors the case drift is the likely story. Never fires together
+            // with added-duplicate — an exact match continues before this runs.
+            const near = living.folded.get(r.name.toLowerCase());
+            if (near !== undefined) {
+                issues.push({
+                    severity: "warn",
+                    code: "delta.added-near-duplicate",
+                    subject,
+                    message: `${where}: ADDED requirement '${r.name}' differs only in case from living requirement '${near}' — the merge matches names exactly, so both would coexist. Match the living spelling and use MODIFIED, or pick a distinct name.`,
+                });
+            }
+            const other = await claims.added(scope, r);
+            if (other !== undefined) {
+                issues.push({
+                    severity: "warn",
+                    code: "delta.added-conflict",
+                    subject,
+                    message: `${where}: requirement '${r.name}' is also added by ${other} — whichever archives first lands it, and the second archive is refused (delta.added-duplicate) unless --approve`,
+                });
+            }
+            continue;
+        }
+        // MODIFIED vs MODIFIED on ONE living requirement. The ADDED case has
+        // been caught since delta.added-conflict: two features adding the same
+        // name collide loudly, because the second archive is refused. Two
+        // features CHANGING the same requirement collide in total silence —
+        // both deltas apply cleanly, and whichever archives second replaces
+        // the first's text, scenarios and all, with a version written against
+        // a document that no longer exists. A warning, not a gate: the second
+        // author may well be rewriting on purpose, and only they can say.
+        const alsoChanged = await claims.changed(scope, r);
+        if (alsoChanged !== undefined) {
+            issues.push({
+                severity: "warn",
+                code: "delta.modified-conflict",
+                subject,
+                message: `${where}: ${r.kind} requirement '${r.name}' is also changed by ${alsoChanged} — both deltas apply cleanly, so whichever archives second REPLACES the other's text wholesale. Agree on one owner, or fold the two changes together.`,
+            });
+        }
+        if (r.id !== undefined) {
+            const idMatches = living.byId.get(r.id) ?? [];
+            const nameMatches = living.byName.get(r.name) ?? [];
+            const nameSelectsOther = nameMatches.some((candidate) => candidate.id !== r.id);
+            // The second disjunct is defensive rather than reachable: a living
+            // requirement under this heading that the ID did NOT select must carry
+            // some other ID, which is what `nameSelectsOther` already says. It is
+            // kept because it states the rule the reader is being told — ID and
+            // heading must select the same identity — without depending on that
+            // derivation holding after the next edit.
+            if (nameSelectsOther || (idMatches.length === 0 && nameMatches.length > 0)) {
+                issues.push({
+                    severity: "error",
+                    code: "delta.requirement-identity-collision",
+                    subject,
+                    message: `${where}: ${r.kind} requirement '${r.name}' carries Requirement-ID '${r.id}', but its ID and heading select different living requirements — fix the ID or heading; archive will not guess`,
+                });
+                continue;
+            }
+            // A differing heading is the explicit loam rename mechanism: the
+            // stable ID selects the old requirement, MODIFIED supplies its new name.
+            //
+            // Total in the ID, deliberately: an ID that matches SEVERAL living
+            // requirements has already been refused as
+            // `delta.living-requirement-id-invalid` (severity error, so archive is
+            // gated either way), and the living document is where it gets fixed.
+            // Falling through instead added `delta.modified-unknown` — "does not
+            // exist … Did you mean ADDED?" — beside it, which is both false and
+            // the more actionable-sounding of the two, and it sends the author to
+            // edit the delta over a problem that is not in the delta. There is no
+            // baseline to check against an ambiguous selection, so the pin is
+            // simply not graded until the ambiguity is gone.
+            if (idMatches.length > 0) {
+                const selected = idMatches.length === 1 ? idMatches[0] : undefined;
+                if (selected !== undefined)
+                    checkBaseline(r, selected);
+                continue;
+            }
+        }
+        else if (living.names.has(r.name)) {
+            // Twins under one heading are already refused
+            // (`delta.living-duplicate-requirement`), and applyRequirementDelta
+            // takes the first either way — so the pin is compared against the
+            // same requirement the merge would rewrite.
+            checkBaseline(r, living.byName.get(r.name)[0]);
+            continue;
+        }
+        const other = await claims.added(scope, r);
+        if (other !== undefined) {
+            issues.push({
+                severity: "warn",
+                code: r.kind === "MODIFIED" ? "delta.modified-pending" : "delta.removed-pending",
+                subject,
+                message: `${where}: ${r.kind} requirement '${r.name}' is not in the ${livingDoc} yet — ${other} introduces it. Archive ${other} first.`,
+            });
+            continue;
+        }
+        issues.push({
+            severity: "error",
+            code: r.kind === "MODIFIED" ? "delta.modified-unknown" : "delta.removed-unknown",
+            subject,
+            message: r.kind === "MODIFIED"
+                ? `${where}: MODIFIED requirement '${r.name}' does not exist in the ${livingDoc} — the merge would create it. Did you mean ADDED?`
+                : `${where}: REMOVED requirement '${r.name}' does not exist in the ${livingDoc} — there is nothing to remove`,
+        });
+    }
+    return issues;
+}
+//# sourceMappingURL=select.js.map

package/dist/core/delta/select.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.js","sourceRoot":"","sources":["../../../src/core/delta/select.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What each delta requirement SELECTS in the living document, and whether the\n * merge would do what its author meant.\n *\n * This is the half that needs both documents at once, which is why it is not in\n * `./document.ts`. Every refusal here is a shape the merge would apply cleanly\n * and silently: MODIFIED of a requirement that does not exist is merged as a\n * creation, ADDED of one that does exist REPLACES it scenarios and all, and a\n * stale `Based-On:` means someone landed a change in between that this delta\n * would overwrite with text written against a document that no longer exists.\n */\nimport { type Issue } from \"../vocabulary/issue.js\";\nimport { isRequirementsHeading } from \"../document/parse.js\";\nimport {\n  basedOnDeclarations,\n  REQUIREMENT_DIGEST_RE,\n  requirementDigest,\n  type Requirement,\n} from \"../document/spec.js\";\nimport { type ClaimLookup } from \"./claims.js\";\nimport { type DeltaScope, type LivingIndex } from \"./scope.js\";\n\nexport async function selectionIssues(\n  scope: DeltaScope,\n  reqs: Requirement[],\n  living: LivingIndex,\n  claims: ClaimLookup,\n): Promise<Issue[]> {\n  const { featureId, subject, where, livingDoc } = scope;\n  const issues: Issue[] = [];\n  /**\n   * The pin, against the living requirement this delta actually selects.\n   *\n   * This is the check `delta.modified-conflict` cannot be: that one names\n   * the other feature while BOTH are in flight, and the collision that\n   * happens on a fleet outlives the window. A archives, leaves `features/`,\n   * and stops being an active claim; B revalidates GREEN, and its MODIFIED —\n   * carrying the full text it wrote against the pre-A document — replaces\n   * A's requirement wholesale, scenarios and all, with `+0 ~1 -0` and exit\n   * 0. Nothing downstream can even detect it afterwards: `unarchive A`\n   * refuses `snapshot-stale`, and `--force` takes B out with it.\n   *\n   * A digest of what the author read closes that by not depending on\n   * timing at all. Stale is an ERROR and gates, because there is no reading\n   * of a stale delta under which the merge is what its author meant.\n   * Missing is a warning that GATES: the document is legal — a delta\n   * adopted from OpenSpec never had the line — but an unpinned MODIFIED or\n   * REMOVED is exactly the timing hole the pin exists to close, and letting\n   * it through archived the silent rollback at exit 0. The migrated corpus\n   * is why this stays a warning rather than an error, and why the refusal\n   * is not an outage: `loam rebase <feat>` pins every delta in one command,\n   * and `--approve` remains the way to say the unpinned merge is meant.\n   */\n  const checkBaseline = (r: Requirement, selected: Requirement): void => {\n    // A pin the document pass already refused is not also stale: that would\n    // send its author to `loam rebase` for a problem rebase does not fix.\n    const declared = basedOnDeclarations(r);\n    if (declared.length > 1) return;\n    if (r.basedOn !== undefined && !REQUIREMENT_DIGEST_RE.test(r.basedOn)) return;\n    const current = requirementDigest(selected);\n    if (r.basedOn === undefined) {\n      issues.push({\n        severity: \"warn\",\n        gates: true,\n        code: \"delta.baseline-missing\",\n        subject,\n        message: `${where}: ${r.kind} requirement '${r.name}' carries no Based-On, so nothing can say whether the living text moved since this delta was written — merging it would replace whatever landed in between. Run \\`loam rebase ${featureId}\\` to pin it (Based-On: ${current}), or archive with --approve to merge unpinned deliberately.`,\n      });\n      return;\n    }\n    if (r.basedOn === current) return;\n    issues.push({\n      severity: \"error\",\n      code: \"delta.baseline-stale\",\n      subject,\n      message:\n        `${where}: ${r.kind} requirement '${r.name}' was written against living version ${r.basedOn}, but the ${livingDoc} now holds ${current} — someone landed a change to it in between. ` +\n        (r.kind === \"MODIFIED\"\n          ? `This MODIFIED carries its FULL new text, so merging it would replace theirs outright.`\n          : `Merging this REMOVED would delete what they landed.`) +\n        ` Re-read the living requirement, fold in what you still mean, then run \\`loam rebase ${featureId}\\`.`,\n    });\n  };\n\n  for (const r of reqs) {\n    // BASE in a delta file means the requirement is under no delta section, so\n    // the merge skips it. Reported rather than merged: deciding that `## Behavior`\n    // means ADDED would be archive guessing at intent, and it would guess wrong\n    // for every prose section that quotes a requirement as documentation. A\n    // requirement above every heading has no heading to name, and no claim to be\n    // written in the delta grammar at all — same judgement as `## Requirements`.\n    //\n    // A warning that GATES archive — the one check where the two axes\n    // diverge. Severity says whether the document is valid: this shape is\n    // legal OpenSpec, so an error would fail `loam validate` on every\n    // adopted repo whose active deltas still use it. Gating says whether\n    // the merge is safe: it is not — the merge would silently drop authored\n    // content, the exact loss this module exists to prevent — so archive\n    // refuses, and `--approve` remains the way to say the loss is meant.\n    if (r.kind === \"BASE\") {\n      if (r.section !== undefined && !isRequirementsHeading(r.section)) {\n        issues.push({\n          severity: \"warn\",\n          gates: true,\n          code: \"delta.requirement-not-merged\",\n          subject,\n          message: `${where}: requirement '${r.name}' sits under '${r.section}', which is not a delta section — archive will NOT merge it. Move it under '## ADDED Requirements' (or MODIFIED/REMOVED), or drop it if it is documentation.`,\n        });\n      }\n      continue;\n    }\n\n    if (r.kind === \"ADDED\") {\n      const idMatches = r.id === undefined ? [] : (living.byId.get(r.id) ?? []);\n      const nameMatches = living.byName.get(r.name) ?? [];\n      const nameSelectsOther = r.id !== undefined && nameMatches.some((candidate) => candidate.id !== r.id);\n      if (nameSelectsOther) {\n        issues.push({\n          severity: \"error\",\n          code: \"delta.requirement-identity-collision\",\n          subject,\n          message: `${where}: ADDED requirement '${r.name}' carries Requirement-ID '${r.id}', but that heading already identifies a different living requirement — ID and name cannot select different identities`,\n        });\n        continue;\n      }\n      if ((r.id === undefined && living.names.has(r.name)) || idMatches.length > 0) {\n        issues.push({\n          severity: \"error\",\n          code: \"delta.added-duplicate\",\n          subject,\n          message: r.id === undefined\n            ? `${where}: ADDED requirement '${r.name}' already exists in the ${livingDoc} — the merge would REPLACE it, scenarios and all. Use MODIFIED, or rename.`\n            : `${where}: ADDED requirement '${r.name}' uses Requirement-ID '${r.id}', which already exists in the ${livingDoc} — use MODIFIED to change that identity`,\n        });\n        continue;\n      }\n      // Merge identity is exact string equality (applyRequirementDelta), so a\n      // name that differs only in case slips past the duplicate check above and\n      // lands as a SECOND requirement next to the living one. A warning, not an\n      // error: the author may genuinely mean a distinct requirement, but with\n      // LLM authors the case drift is the likely story. Never fires together\n      // with added-duplicate — an exact match continues before this runs.\n      const near = living.folded.get(r.name.toLowerCase());\n      if (near !== undefined) {\n        issues.push({\n          severity: \"warn\",\n          code: \"delta.added-near-duplicate\",\n          subject,\n          message: `${where}: ADDED requirement '${r.name}' differs only in case from living requirement '${near}' — the merge matches names exactly, so both would coexist. Match the living spelling and use MODIFIED, or pick a distinct name.`,\n        });\n      }\n      const other = await claims.added(scope, r);\n      if (other !== undefined) {\n        issues.push({\n          severity: \"warn\",\n          code: \"delta.added-conflict\",\n          subject,\n          message: `${where}: requirement '${r.name}' is also added by ${other} — whichever archives first lands it, and the second archive is refused (delta.added-duplicate) unless --approve`,\n        });\n      }\n      continue;\n    }\n\n    // MODIFIED vs MODIFIED on ONE living requirement. The ADDED case has\n    // been caught since delta.added-conflict: two features adding the same\n    // name collide loudly, because the second archive is refused. Two\n    // features CHANGING the same requirement collide in total silence —\n    // both deltas apply cleanly, and whichever archives second replaces\n    // the first's text, scenarios and all, with a version written against\n    // a document that no longer exists. A warning, not a gate: the second\n    // author may well be rewriting on purpose, and only they can say.\n    const alsoChanged = await claims.changed(scope, r);\n    if (alsoChanged !== undefined) {\n      issues.push({\n        severity: \"warn\",\n        code: \"delta.modified-conflict\",\n        subject,\n        message: `${where}: ${r.kind} requirement '${r.name}' is also changed by ${alsoChanged} — both deltas apply cleanly, so whichever archives second REPLACES the other's text wholesale. Agree on one owner, or fold the two changes together.`,\n      });\n    }\n\n    if (r.id !== undefined) {\n      const idMatches = living.byId.get(r.id) ?? [];\n      const nameMatches = living.byName.get(r.name) ?? [];\n      const nameSelectsOther = nameMatches.some((candidate) => candidate.id !== r.id);\n      // The second disjunct is defensive rather than reachable: a living\n      // requirement under this heading that the ID did NOT select must carry\n      // some other ID, which is what `nameSelectsOther` already says. It is\n      // kept because it states the rule the reader is being told — ID and\n      // heading must select the same identity — without depending on that\n      // derivation holding after the next edit.\n      if (nameSelectsOther || (idMatches.length === 0 && nameMatches.length > 0)) {\n        issues.push({\n          severity: \"error\",\n          code: \"delta.requirement-identity-collision\",\n          subject,\n          message: `${where}: ${r.kind} requirement '${r.name}' carries Requirement-ID '${r.id}', but its ID and heading select different living requirements — fix the ID or heading; archive will not guess`,\n        });\n        continue;\n      }\n      // A differing heading is the explicit loam rename mechanism: the\n      // stable ID selects the old requirement, MODIFIED supplies its new name.\n      //\n      // Total in the ID, deliberately: an ID that matches SEVERAL living\n      // requirements has already been refused as\n      // `delta.living-requirement-id-invalid` (severity error, so archive is\n      // gated either way), and the living document is where it gets fixed.\n      // Falling through instead added `delta.modified-unknown` — \"does not\n      // exist … Did you mean ADDED?\" — beside it, which is both false and\n      // the more actionable-sounding of the two, and it sends the author to\n      // edit the delta over a problem that is not in the delta. There is no\n      // baseline to check against an ambiguous selection, so the pin is\n      // simply not graded until the ambiguity is gone.\n      if (idMatches.length > 0) {\n        const selected = idMatches.length === 1 ? idMatches[0] : undefined;\n        if (selected !== undefined) checkBaseline(r, selected);\n        continue;\n      }\n    } else if (living.names.has(r.name)) {\n      // Twins under one heading are already refused\n      // (`delta.living-duplicate-requirement`), and applyRequirementDelta\n      // takes the first either way — so the pin is compared against the\n      // same requirement the merge would rewrite.\n      checkBaseline(r, living.byName.get(r.name)![0]!);\n      continue;\n    }\n\n    const other = await claims.added(scope, r);\n    if (other !== undefined) {\n      issues.push({\n        severity: \"warn\",\n        code: r.kind === \"MODIFIED\" ? \"delta.modified-pending\" : \"delta.removed-pending\",\n        subject,\n        message: `${where}: ${r.kind} requirement '${r.name}' is not in the ${livingDoc} yet — ${other} introduces it. Archive ${other} first.`,\n      });\n      continue;\n    }\n    issues.push({\n      severity: \"error\",\n      code: r.kind === \"MODIFIED\" ? \"delta.modified-unknown\" : \"delta.removed-unknown\",\n      subject,\n      message:\n        r.kind === \"MODIFIED\"\n          ? `${where}: MODIFIED requirement '${r.name}' does not exist in the ${livingDoc} — the merge would create it. Did you mean ADDED?`\n          : `${where}: REMOVED requirement '${r.name}' does not exist in the ${livingDoc} — there is nothing to remove`,\n    });\n  }\n  return issues;\n}\n"]}

package/dist/core/dependencies/dependencies.js

@@ -0,0 +1,141 @@
+/**
+ * The active-feature dependency graph: who has to archive before whom.
+ *
+ * A feature depends on another when it MODIFIES or REMOVES a requirement the
+ * other adds, or calls an operation the other introduces — the two ways one
+ * delta can only apply after another has landed. This module is the walk that
+ * puts `./facts.ts` and `./graph.ts` together; the reasons it attaches to each
+ * edge are what makes the answer explainable rather than merely true.
+ */
+import { inOrder } from "../kernel/concurrency.js";
+import { FleetContext } from "../fleet-context.js";
+import { compareIds } from "../repo/entries.js";
+import { listFeatures } from "../repo/repo.js";
+import { addOwner, opIndexKey, readFacts, reqIndexKey, reqKeys, } from "./facts.js";
+import { appendReason, compareReasons, dependencyFirstOrder, stronglyConnected } from "./graph.js";
+/** Derive the complete active-feature graph, or one feature and its transitive prerequisites. */
+export async function analyzeDependencies(docsDir, featureId, context = new FleetContext()) {
+    const features = await listFeatures(docsDir, {}, context);
+    // Bounded, not `Promise.all`: `readFacts` loads the feature's delta.likec4,
+    // and each of those is a whole Langium workspace held open until the read
+    // finishes — the same resource `validate --all` rations for the same measured
+    // reason (see core/kernel/concurrency.ts). This module fanned out over every active
+    // feature at once, and it is not only `loam dependencies` that pays: the fleet
+    // form of `loam status` calls in here too. `inOrder` returns results in input
+    // order, so the graph, the conflict list and their ordering are unchanged.
+    const facts = await inOrder(features, (feature) => readFacts(docsDir, feature, context));
+    const requirementOwners = new Map();
+    // The second index over the SAME identity: who MODIFIES or REMOVES it. Only
+    // the first index existed, so the graph could see "two features add the same
+    // requirement" and was blind to "two features rewrite the same requirement" —
+    // the collision that actually happens on a fleet, and the one whose loser
+    // loses their whole authored text without a word from any command.
+    const changedOwners = new Map();
+    const operationOwners = new Map();
+    for (const fact of facts) {
+        for (const added of fact.addedRequirements) {
+            for (const identity of reqKeys(added.requirement)) {
+                const at = { service: added.service, axis: added.axis, identity };
+                addOwner(requirementOwners, reqIndexKey(at), at, fact.feature.id);
+            }
+        }
+        for (const changed of fact.changedRequirements) {
+            for (const identity of reqKeys(changed.requirement)) {
+                const at = { service: changed.service, axis: changed.axis, identity };
+                addOwner(changedOwners, reqIndexKey(at), at, fact.feature.id);
+            }
+        }
+        for (const operation of fact.introducedOperations) {
+            addOwner(operationOwners, opIndexKey(operation), operation, fact.feature.id);
+        }
+    }
+    const edgeMap = new Map();
+    for (const fact of facts) {
+        for (const changed of fact.changedRequirements) {
+            for (const identity of reqKeys(changed.requirement)) {
+                const at = { service: changed.service, axis: changed.axis, identity };
+                for (const owner of requirementOwners.get(reqIndexKey(at))?.features ?? []) {
+                    appendReason(edgeMap, fact.feature.id, owner, { kind: "requirement", ...at });
+                }
+            }
+        }
+        for (const required of fact.requiredOperations) {
+            for (const owner of operationOwners.get(opIndexKey(required))?.features ?? []) {
+                appendReason(edgeMap, fact.feature.id, owner, { kind: "operation", ...required });
+            }
+        }
+    }
+    let edges = [...edgeMap.values()]
+        .map((edge) => ({ ...edge, reasons: edge.reasons.sort(compareReasons) }))
+        .sort((a, b) => compareIds(a.from, b.from) || compareIds(a.to, b.to));
+    const conflicts = [];
+    for (const [index, change] of [
+        [requirementOwners, "added"],
+        [changedOwners, "changed"],
+    ]) {
+        for (const { at, features } of index.values()) {
+            if (features.size < 2)
+                continue;
+            conflicts.push({
+                kind: "requirement",
+                change,
+                service: at.service,
+                axis: at.axis,
+                identity: at.identity,
+                features: [...features].sort(compareIds),
+            });
+        }
+    }
+    for (const { at, features } of operationOwners.values()) {
+        if (features.size < 2)
+            continue;
+        conflicts.push({
+            kind: "operation",
+            // Two features DEFINING the same operationId — the only way an operation
+            // collides, since removals address a living slot rather than claim one.
+            change: "added",
+            service: at.service,
+            identity: at.operationId,
+            features: [...features].sort(compareIds),
+        });
+    }
+    conflicts.sort((a, b) => compareIds(a.kind, b.kind)
+        || compareIds(a.change, b.change)
+        || compareIds(a.service, b.service)
+        || compareIds(a.axis ?? "", b.axis ?? "")
+        || compareIds(a.identity, b.identity));
+    // `Set<string>`, not the ids' own brand: `DependencyEdge.from`/`to` are plain
+    // strings, and the reassignment below rebuilds the set from a caller's
+    // argument.
+    let selected = new Set(features.map((feature) => feature.id));
+    if (featureId !== undefined) {
+        selected = new Set([featureId]);
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const edge of edges) {
+                if (selected.has(edge.from) && !selected.has(edge.to)) {
+                    selected.add(edge.to);
+                    changed = true;
+                }
+            }
+        }
+        edges = edges.filter((edge) => selected.has(edge.from) && selected.has(edge.to));
+    }
+    const selectedFeatures = features.filter((feature) => selected.has(feature.id));
+    const ids = selectedFeatures.map((feature) => feature.id);
+    const nodes = selectedFeatures.map((feature) => ({
+        id: feature.id,
+        dirName: feature.dirName,
+        services: [...feature.services],
+        dependsOn: edges.filter((edge) => edge.from === feature.id).map((edge) => edge.to).sort(compareIds),
+    }));
+    return {
+        nodes,
+        edges,
+        conflicts: conflicts.filter((conflict) => conflict.features.some((id) => selected.has(id))),
+        order: dependencyFirstOrder(ids, edges),
+        cycles: stronglyConnected(ids, edges),
+    };
+}
+//# sourceMappingURL=dependencies.js.map

package/dist/core/dependencies/dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.js","sourceRoot":"","sources":["../../../src/core/dependencies/dependencies.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The active-feature dependency graph: who has to archive before whom.\n *\n * A feature depends on another when it MODIFIES or REMOVES a requirement the\n * other adds, or calls an operation the other introduces — the two ways one\n * delta can only apply after another has landed. This module is the walk that\n * puts `./facts.ts` and `./graph.ts` together; the reasons it attaches to each\n * edge are what makes the answer explainable rather than merely true.\n */\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { compareIds } from \"../repo/entries.js\";\nimport { listFeatures } from \"../repo/repo.js\";\nimport {\n  addOwner,\n  opIndexKey,\n  readFacts,\n  reqIndexKey,\n  reqKeys,\n  type DependencyEdge,\n  type DependencyGraph,\n  type DependencyNode,\n  type FeatureConflict,\n  type OpAt,\n  type Owners,\n  type ReqAt,\n} from \"./facts.js\";\nimport { appendReason, compareReasons, dependencyFirstOrder, stronglyConnected } from \"./graph.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/** Derive the complete active-feature graph, or one feature and its transitive prerequisites. */\nexport async function analyzeDependencies(\n  docsDir: DocsDir,\n  featureId?: string,\n  context = new FleetContext(),\n): Promise<DependencyGraph> {\n  const features = await listFeatures(docsDir, {}, context);\n  // Bounded, not `Promise.all`: `readFacts` loads the feature's delta.likec4,\n  // and each of those is a whole Langium workspace held open until the read\n  // finishes — the same resource `validate --all` rations for the same measured\n  // reason (see core/kernel/concurrency.ts). This module fanned out over every active\n  // feature at once, and it is not only `loam dependencies` that pays: the fleet\n  // form of `loam status` calls in here too. `inOrder` returns results in input\n  // order, so the graph, the conflict list and their ordering are unchanged.\n  const facts = await inOrder(features, (feature) => readFacts(docsDir, feature, context));\n  const requirementOwners = new Map<string, Owners<ReqAt>>();\n  // The second index over the SAME identity: who MODIFIES or REMOVES it. Only\n  // the first index existed, so the graph could see \"two features add the same\n  // requirement\" and was blind to \"two features rewrite the same requirement\" —\n  // the collision that actually happens on a fleet, and the one whose loser\n  // loses their whole authored text without a word from any command.\n  const changedOwners = new Map<string, Owners<ReqAt>>();\n  const operationOwners = new Map<string, Owners<OpAt>>();\n\n  for (const fact of facts) {\n    for (const added of fact.addedRequirements) {\n      for (const identity of reqKeys(added.requirement)) {\n        const at: ReqAt = { service: added.service, axis: added.axis, identity };\n        addOwner(requirementOwners, reqIndexKey(at), at, fact.feature.id);\n      }\n    }\n    for (const changed of fact.changedRequirements) {\n      for (const identity of reqKeys(changed.requirement)) {\n        const at: ReqAt = { service: changed.service, axis: changed.axis, identity };\n        addOwner(changedOwners, reqIndexKey(at), at, fact.feature.id);\n      }\n    }\n    for (const operation of fact.introducedOperations) {\n      addOwner(operationOwners, opIndexKey(operation), operation, fact.feature.id);\n    }\n  }\n\n  const edgeMap = new Map<string, DependencyEdge>();\n  for (const fact of facts) {\n    for (const changed of fact.changedRequirements) {\n      for (const identity of reqKeys(changed.requirement)) {\n        const at: ReqAt = { service: changed.service, axis: changed.axis, identity };\n        for (const owner of requirementOwners.get(reqIndexKey(at))?.features ?? []) {\n          appendReason(edgeMap, fact.feature.id, owner, { kind: \"requirement\", ...at });\n        }\n      }\n    }\n    for (const required of fact.requiredOperations) {\n      for (const owner of operationOwners.get(opIndexKey(required))?.features ?? []) {\n        appendReason(edgeMap, fact.feature.id, owner, { kind: \"operation\", ...required });\n      }\n    }\n  }\n\n  let edges = [...edgeMap.values()]\n    .map((edge) => ({ ...edge, reasons: edge.reasons.sort(compareReasons) }))\n    .sort((a, b) => compareIds(a.from, b.from) || compareIds(a.to, b.to));\n\n  const conflicts: FeatureConflict[] = [];\n  for (const [index, change] of [\n    [requirementOwners, \"added\"],\n    [changedOwners, \"changed\"],\n  ] as const) {\n    for (const { at, features } of index.values()) {\n      if (features.size < 2) continue;\n      conflicts.push({\n        kind: \"requirement\",\n        change,\n        service: at.service,\n        axis: at.axis,\n        identity: at.identity,\n        features: [...features].sort(compareIds),\n      });\n    }\n  }\n  for (const { at, features } of operationOwners.values()) {\n    if (features.size < 2) continue;\n    conflicts.push({\n      kind: \"operation\",\n      // Two features DEFINING the same operationId — the only way an operation\n      // collides, since removals address a living slot rather than claim one.\n      change: \"added\",\n      service: at.service,\n      identity: at.operationId,\n      features: [...features].sort(compareIds),\n    });\n  }\n  conflicts.sort((a, b) =>\n    compareIds(a.kind, b.kind)\n    || compareIds(a.change, b.change)\n    || compareIds(a.service, b.service)\n    || compareIds(a.axis ?? \"\", b.axis ?? \"\")\n    || compareIds(a.identity, b.identity));\n\n  // `Set<string>`, not the ids' own brand: `DependencyEdge.from`/`to` are plain\n  // strings, and the reassignment below rebuilds the set from a caller's\n  // argument.\n  let selected = new Set<string>(features.map((feature) => feature.id));\n  if (featureId !== undefined) {\n    selected = new Set<string>([featureId]);\n    let changed = true;\n    while (changed) {\n      changed = false;\n      for (const edge of edges) {\n        if (selected.has(edge.from) && !selected.has(edge.to)) {\n          selected.add(edge.to);\n          changed = true;\n        }\n      }\n    }\n    edges = edges.filter((edge) => selected.has(edge.from) && selected.has(edge.to));\n  }\n\n  const selectedFeatures = features.filter((feature) => selected.has(feature.id));\n  const ids = selectedFeatures.map((feature) => feature.id);\n  const nodes = selectedFeatures.map((feature): DependencyNode => ({\n    id: feature.id,\n    dirName: feature.dirName,\n    services: [...feature.services],\n    dependsOn: edges.filter((edge) => edge.from === feature.id).map((edge) => edge.to).sort(compareIds),\n  }));\n\n  return {\n    nodes,\n    edges,\n    conflicts: conflicts.filter((conflict) => conflict.features.some((id) => selected.has(id))),\n    order: dependencyFirstOrder(ids, edges),\n    cycles: stronglyConnected(ids, edges),\n  };\n}\n"]}

package/dist/core/dependencies/facts.js

@@ -0,0 +1,165 @@
+/**
+ * What one feature ADDS and what it NEEDS, read out of its own delta.
+ *
+ * The whole graph is built from these five lists and nothing else, which is why
+ * they are computed once per feature and indexed rather than re-derived per
+ * edge: a feature is a node here only because some other feature's requirement
+ * or operation resolves into it, and answering that per pair would be a fleet
+ * walk per pair.
+ *
+ * `reqKeys` returns BOTH spellings of a requirement's identity — the stable
+ * `Requirement-ID` and the exact heading — because a legacy requirement has only
+ * the second, and an edge that existed under one spelling and not the other
+ * would make the graph depend on when the corpus was migrated.
+ */
+import { existsSync } from "node:fs";
+import { FleetContext } from "../fleet-context.js";
+import { serviceResolver } from "../c4/resolve/service.js";
+import { operations } from "../openapi/doc.js";
+import {} from "../repo/entries.js";
+import { SPEC_AXES, featurePaths, featureSpecPaths } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { enumeratedServiceIds, enumeratedServiceIndex } from "../repo/service-target.js";
+export function reqKeys(requirement) {
+    return [
+        ...(requirement.id === undefined ? [] : [`id:${requirement.id}`]),
+        `name:${requirement.name}`,
+    ];
+}
+export function reqIndexKey(at) {
+    return `${at.service}\0${at.axis}\0${at.identity}`;
+}
+export function opIndexKey(at) {
+    return `${at.service}\0${at.operationId}`;
+}
+export function addOwner(index, key, at, feature) {
+    const owners = index.get(key) ?? { at, features: new Set() };
+    owners.features.add(feature);
+    index.set(key, owners);
+}
+export async function readFacts(docsDir, feature, context) {
+    const addedRequirements = [];
+    const changedRequirements = [];
+    const introducedOperations = [];
+    const requiredOperations = [];
+    /**
+     * The operationIds a service ALREADY has, per service.
+     *
+     * This is the whole difference between a dependency graph and a rumour mill.
+     * A feature's `openapi.yaml` is a COMPLETE document, not a patch — authors
+     * restate the living API around the slot they are changing — so every feature
+     * that so much as mentions `authorizePayment` used to be recorded as
+     * INTRODUCING it, and every other feature governing it as REQUIRING it. Two
+     * features quoting the same living operation therefore depended on each other
+     * in both directions: an invented cycle, an invented conflict, and an ordering
+     * for work that had none. `loam validate`'s coherence pass already subtracts
+     * the living contract this way (core/coherence/coherence.ts); this is the
+     * same subtraction, so the two cannot disagree about what "new" means.
+     *
+     * Cached per service inside the call and, through the FleetContext, across
+     * features: a fleet-wide graph asks about the same ten services N times.
+     */
+    const livingByService = new Map();
+    const living = async (service) => {
+        let ids = livingByService.get(service);
+        if (ids === undefined) {
+            ids = new Set((await operations((await locateServicePaths(docsDir, service, context)).openapi, context))
+                .filter((op) => !op.remove)
+                .map((op) => op.id));
+            livingByService.set(service, ids);
+        }
+        return ids;
+    };
+    for (const service of feature.services) {
+        const paths = featureSpecPaths(feature.dir, service);
+        const livingIds = await living(service);
+        for (const axis of SPEC_AXES) {
+            const path = paths[axis.key];
+            if (!existsSync(path))
+                continue;
+            const requirements = await context.readRequirements(path);
+            for (const requirement of requirements) {
+                const fact = { service, axis: axis.file, requirement };
+                if (requirement.kind === "ADDED")
+                    addedRequirements.push(fact);
+                if (requirement.kind === "MODIFIED" || requirement.kind === "REMOVED") {
+                    changedRequirements.push(fact);
+                }
+                for (const operationId of requirement.operations) {
+                    // Governing an operation the service already provides is not a
+                    // dependency on anybody: the contract it needs is already merged.
+                    if (livingIds.has(operationId))
+                        continue;
+                    requiredOperations.push({ service, operationId });
+                }
+            }
+        }
+        if (existsSync(paths.openapi)) {
+            const featureOperations = await operations(paths.openapi, context);
+            for (const operation of featureOperations) {
+                if (livingIds.has(operation.id))
+                    continue;
+                if (operation.remove)
+                    requiredOperations.push({ service, operationId: operation.id });
+                else
+                    introducedOperations.push({ service, operationId: operation.id });
+            }
+        }
+    }
+    // The C4 delta is the FOURTH place a feature names an operation, and it was
+    // the one the graph could not see: an edge carrying `metadata { op 'x' }` is
+    // a call this feature builds on `x`, which is exactly the "must land first"
+    // relation this module exists to compute. Validate already says so — it
+    // reports `c4-api.op-pending` when the op is defined by another feature in
+    // flight — so the graph disagreeing with the validator about the same pair of
+    // features was the graph being wrong, not quiet.
+    //
+    // Endpoints resolve through `serviceResolver` — the element's
+    // `metadata { service }` binding, title as fallback — the same join every
+    // other check uses, so renaming a box in a diagram cannot silently unhook it
+    // here either.
+    const deltaPath = featurePaths(feature.dir).delta;
+    if (existsSync(deltaPath)) {
+        const doc = await context.loadLikeC4(deltaPath);
+        // A delta that does not parse proves nothing about who depends on whom.
+        // `loam validate` owns that diagnosis (`delta.invalid`); inventing edges out
+        // of a half-read document would be worse than the silence.
+        if (doc.errors.length === 0) {
+            // One resolver for the whole delta: `serviceOf` rebuilds its id map on
+            // every call, and this loop asks once per edge. The enumerated fleet —
+            // `services/` plus this feature's own `specs/` directories, the same
+            // union `enumeratedTarget` probes below — rides into the resolver so a
+            // delta that models CONTAINERS keeps its edges attached: without it, an
+            // edge into `payment.api` resolves to a service called "api" that has
+            // never existed, the op lookup misses the living contract, and the graph
+            // invents a dependency (or orders two features that share nothing). An
+            // unenumerable services/ falls back to the feature's own names — every
+            // living probe would have found nothing there anyway.
+            const fleetIds = await enumeratedServiceIds(docsDir, context);
+            const svcOf = serviceResolver(doc.elements, new Set([...fleetIds, ...feature.services]));
+            // The resolver answers with document text and `living` builds a path, so
+            // the name crosses through the enumeration — coherence.ts grades its
+            // edges through the same bridge. A name no enumeration vouches for has
+            // no living contract anywhere: the op is required, exactly what the
+            // probe answered for an absent service.
+            const enumeratedTarget = enumeratedServiceIndex(docsDir, feature.services, context);
+            for (const rel of doc.relationships) {
+                if (rel.op === undefined)
+                    continue;
+                const service = svcOf(rel.target);
+                const pathable = await enumeratedTarget(service);
+                if (pathable !== undefined && (await living(pathable)).has(rel.op))
+                    continue;
+                requiredOperations.push({ service, operationId: rel.op });
+            }
+        }
+    }
+    return {
+        feature,
+        addedRequirements,
+        changedRequirements,
+        introducedOperations,
+        requiredOperations,
+    };
+}
+//# sourceMappingURL=facts.js.map