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

package/dist/core/usecases/grade/usecases.js

@@ -0,0 +1,112 @@
+/**
+ * The use-case axis of `validate --all`: the `dynamic view`s a fleet declares,
+ * graded as business flows against the model they are drawn over.
+ *
+ * IN `core/` SINCE THE FEATURE GATE BECAME ITS SECOND CALLER. It began as
+ * `commands/validate/fleet/usecases/`, the fleet target's own package; the
+ * archive gate and `loam status` both grade a feature through
+ * `core/coherence/`, which may not import a command, so a feature's own flows
+ * archived ungraded and the next `validate --all` convicted them
+ * (`usecase.step-unbacked`, `usecase.requirement-unresolved` — the real-fleet
+ * review, 2026-10-21). One grader for both scopes is the rule this package's
+ * banner already stated for the service target; `./feature.ts` is the third
+ * caller, and `place` on the scope is the one thing each states for itself.
+ *
+ * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, and that opt-in is what lets
+ * this ship into a fleet that already has diagrams. An untagged `dynamic view`
+ * is somebody's hand-drawn sequence — drawn to explain something to a person,
+ * not to be joined to a model — and grading it would turn every existing docs
+ * repo red on upgrade over documents nobody promised anything about. A `#cap-`,
+ * `#req-` or `#suite-` tag is the author saying "this is a use case; hold it to
+ * the model", and nothing else says it: a view with no tags and a view whose
+ * tags are all somebody's own vocabulary are the same thing here. A
+ * `#suite-`-only view resolves nothing below — it carries no claim — and its
+ * hops are graded like any other's.
+ *
+ * THE TAG OPTS A VIEW IN WHETHER OR NOT IT RESOLVES. A `#cap-` slug that names
+ * no declared capability is a broken claim about the vocabulary, not a withdrawn
+ * one, so its steps are still graded — and the step grades read
+ * `architecture/capabilities.yaml` nowhere at all. Coupling them would mean a
+ * fleet that has not adopted the capability axis could never have a use case
+ * checked, which inverts the adoption order the whole axis is built on: draw the
+ * flow first, name the capability when the vocabulary exists.
+ *
+ * Everything here is LINEAR IN STEPS over documents `validate --all` has already
+ * parsed, and nothing in it reads a file or throws — a fleet with no tagged view
+ * produces exactly nothing. Linear in steps is not free per step: `attributeStep`
+ * scans `relationships` once for the exact tier and again for the resolved one,
+ * and `isActor` scans `elements`, so the real shape is O(steps × relationships)
+ * plus O(steps × elements). That is why `StepGrading` is built once below rather
+ * than per hop — the per-hop cost is a scan, so anything rebuilt per hop is paid
+ * against every hop in the fleet.
+ */
+import { compareIds } from "../../repo/entries.js";
+import { resolveCapabilityTags } from "../../capabilities/usecase-join.js";
+import { isUseCase } from "../fleet.js";
+import { capabilityTagFindings } from "./capability-tag.js";
+import { requirementTagFindings } from "./requirement-tag.js";
+import { stepFindings } from "./steps.js";
+import { viewFile } from "../place.js";
+/**
+ * The views that opted in, in a stable order.
+ *
+ * The opt-in itself is `isUseCase` in `core/usecases/fleet.ts` and is not
+ * restated here. It used to be — the same `startsWith` pair, spelled a second
+ * time — and the two spellings drifted: this one took either reserved prefix
+ * while the reader-side one took `#cap-` alone, so `validate` graded a
+ * `#req-`-only flow that `loam diff`, `delta`, `status`, the packs and `list
+ * capabilities` could not see. What is left here is the ORDER, which is this
+ * package's own concern.
+ *
+ * Sorted by (file, view id) rather than reported in LikeC4's own record order:
+ * nothing in loam has measured that the parse preserves declaration order, so a
+ * report whose row order depends on that would reorder under a dependency bump
+ * — the diff-stability rule `core/capabilities/rollup.ts` states for its rows,
+ * applied to findings.
+ */
+function gradedViews(views) {
+    return views
+        .filter(isUseCase)
+        .sort((a, b) => compareIds(viewFile(a), viewFile(b)) || compareIds(a.id, b.id));
+}
+/**
+ * Every use-case finding a fleet's declared views earn.
+ *
+ * The grading record is built once and shared across every step of every view:
+ * `attributeStep` caches its element→service resolver on the identity of the
+ * elements array and the fleet set, so handing it one `StepScope` for the whole
+ * run is what keeps the fleet's use cases from rebuilding that id map per hop.
+ */
+export function useCaseFindings(scope) {
+    const grading = {
+        // `known` and `services` come from ONE value, so the fleet set the
+        // attribution resolves against and the fleet set the provider guard tests
+        // cannot drift apart into two answers about the same element.
+        model: { elements: scope.elements, relationships: scope.relationships, known: scope.services },
+        services: scope.services,
+        resolve: scope.resolve,
+        place: scope.place,
+    };
+    const findings = [];
+    for (const view of gradedViews(scope.views)) {
+        // ONE resolution of this view's capability tags, shared by both grades. The
+        // `#req-` tag is scoped by exactly the capabilities the `#cap-` tags resolve
+        // to, so resolving twice would be two chances to disagree about which
+        // document a `Requirement-ID` is unique inside.
+        //
+        // THE LADDER IS THE `null`, NOT AN EMPTY LIST, and the distinction is a
+        // wrong answer away: a suspended vocabulary handed on as `[]` reads to the
+        // requirement grade as "this view resolves no capability", which is its
+        // `unscoped` ERROR — so every `#req-` tag in a fleet that has not adopted
+        // the capability axis would be convicted for the axis not existing.
+        if (scope.capabilities !== null) {
+            const claims = resolveCapabilityTags(view.tags, scope.capabilities);
+            findings.push(...capabilityTagFindings(view, claims, scope.place));
+            findings.push(...requirementTagFindings(view, claims, scope.requirementsOf, scope.place));
+        }
+        for (const step of view.steps)
+            findings.push(...stepFindings({ view, step }, grading));
+    }
+    return findings;
+}
+//# sourceMappingURL=usecases.js.map

package/dist/core/usecases/grade/usecases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usecases.js","sourceRoot":"","sources":["../../../../src/core/usecases/grade/usecases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAoB,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAkB,MAAM,aAAa,CAAC;AAkDvD;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,WAAW,CAAC,KAA4B;IAC/C,OAAO,KAAK;SACT,MAAM,CAAC,SAAS,CAAC;SACjB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACpF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB;IACjD,MAAM,OAAO,GAAgB;QAC3B,mEAAmE;QACnE,0EAA0E;QAC1E,8DAA8D;QAC9D,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE;QAC9F,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC;IACF,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,4EAA4E;QAC5E,6EAA6E;QAC7E,sEAAsE;QACtE,gDAAgD;QAChD,EAAE;QACF,wEAAwE;QACxE,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,oEAAoE;QACpE,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;YACpE,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;YACnE,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5F,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IACzF,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The use-case axis of `validate --all`: the `dynamic view`s a fleet declares,\n * graded as business flows against the model they are drawn over.\n *\n * IN `core/` SINCE THE FEATURE GATE BECAME ITS SECOND CALLER. It began as\n * `commands/validate/fleet/usecases/`, the fleet target's own package; the\n * archive gate and `loam status` both grade a feature through\n * `core/coherence/`, which may not import a command, so a feature's own flows\n * archived ungraded and the next `validate --all` convicted them\n * (`usecase.step-unbacked`, `usecase.requirement-unresolved` — the real-fleet\n * review, 2026-10-21). One grader for both scopes is the rule this package's\n * banner already stated for the service target; `./feature.ts` is the third\n * caller, and `place` on the scope is the one thing each states for itself.\n *\n * ONLY VIEWS CARRYING A RESERVED TAG ARE GRADED, and that opt-in is what lets\n * this ship into a fleet that already has diagrams. An untagged `dynamic view`\n * is somebody's hand-drawn sequence — drawn to explain something to a person,\n * not to be joined to a model — and grading it would turn every existing docs\n * repo red on upgrade over documents nobody promised anything about. A `#cap-`,\n * `#req-` or `#suite-` tag is the author saying \"this is a use case; hold it to\n * the model\", and nothing else says it: a view with no tags and a view whose\n * tags are all somebody's own vocabulary are the same thing here. A\n * `#suite-`-only view resolves nothing below — it carries no claim — and its\n * hops are graded like any other's.\n *\n * THE TAG OPTS A VIEW IN WHETHER OR NOT IT RESOLVES. A `#cap-` slug that names\n * no declared capability is a broken claim about the vocabulary, not a withdrawn\n * one, so its steps are still graded — and the step grades read\n * `architecture/capabilities.yaml` nowhere at all. Coupling them would mean a\n * fleet that has not adopted the capability axis could never have a use case\n * checked, which inverts the adoption order the whole axis is built on: draw the\n * flow first, name the capability when the vocabulary exists.\n *\n * Everything here is LINEAR IN STEPS over documents `validate --all` has already\n * parsed, and nothing in it reads a file or throws — a fleet with no tagged view\n * produces exactly nothing. Linear in steps is not free per step: `attributeStep`\n * scans `relationships` once for the exact tier and again for the resolved one,\n * and `isActor` scans `elements`, so the real shape is O(steps × relationships)\n * plus O(steps × elements). That is why `StepGrading` is built once below rather\n * than per hop — the per-hop cost is a scan, so anything rebuilt per hop is paid\n * against every hop in the fleet.\n */\nimport { compareIds } from \"../../repo/entries.js\";\nimport { resolveCapabilityTags } from \"../../capabilities/usecase-join.js\";\nimport { isUseCase } from \"../fleet.js\";\nimport type { Elem, Rel } from \"../../c4/likec4.js\";\nimport type { ParsedView } from \"../../c4/parsed/dynamic-views.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport { capabilityTagFindings } from \"./capability-tag.js\";\nimport { requirementTagFindings } from \"./requirement-tag.js\";\nimport { stepFindings, type StepGrading } from \"./steps.js\";\nimport { viewFile, type ViewPlace } from \"../place.js\";\n\n/** What the use-case grades run over: the views, the model they are drawn on, and the fleet. */\nexport interface UseCaseScope {\n  /**\n   * Every `dynamic view` the `architecture/` PROJECT declares, each carrying the\n   * file it was written in.\n   *\n   * The caller must pass views that came from `loadProject` and no others. Only\n   * that loader gives a view a `sourcePath` relative to `architecture/`; the\n   * single-file loaders name every document after themselves (`source.c4`), and\n   * a finding built from one of those would name a file that has never existed\n   * — see `../place.ts`, which is where the path is spelled. A feature's own\n   * flows come from the staged post-merge project (`../delta/overlay.ts`), whose\n   * `sourcePath` is mapped back to the file the author wrote.\n   */\n  views: readonly ParsedView[];\n  elements: Elem[];\n  relationships: Rel[];\n  /** The `services/<id>/` directories that exist. */\n  services: ReadonlySet<string>;\n  /** The shared element→service resolver — the same one every other edge join uses. */\n  resolve: (id: string) => string;\n  /**\n   * The declared capability ids, or `null` when `architecture/capabilities.yaml`\n   * is absent or does not read as a vocabulary.\n   *\n   * `null` and `[]` are deliberately different answers, and the join at\n   * `core/capabilities/usecase-join.ts` says why it cannot tell them apart\n   * itself: an empty list means \"the fleet declares no capabilities\", which is a\n   * real verdict every tag then fails against, while `null` means \"there is no\n   * vocabulary to grade against\" and suspends the tag grade entirely. The\n   * caller applies the ladder because the caller is the one that read the file.\n   */\n  capabilities: readonly string[] | null;\n  /**\n   * The requirement ids one capability's document declares, or `undefined` for a\n   * capability with no document — the scope a `#req-` tag is resolved in.\n   *\n   * A function rather than the map itself, so this package never learns what a\n   * capability document is: the fleet target reads them once\n   * (`capabilityRequirementIndex`) and hands the lookup over. `undefined` and an\n   * empty set are different answers here, exactly as they are one join over —\n   * no document at all, against a document declaring no promises yet.\n   */\n  requirementsOf: (capability: string) => ReadonlySet<string> | undefined;\n  /** Where every finding says its view is — the scope's own spelling (`ViewPlace`). */\n  place: ViewPlace;\n}\n\n/**\n * The views that opted in, in a stable order.\n *\n * The opt-in itself is `isUseCase` in `core/usecases/fleet.ts` and is not\n * restated here. It used to be — the same `startsWith` pair, spelled a second\n * time — and the two spellings drifted: this one took either reserved prefix\n * while the reader-side one took `#cap-` alone, so `validate` graded a\n * `#req-`-only flow that `loam diff`, `delta`, `status`, the packs and `list\n * capabilities` could not see. What is left here is the ORDER, which is this\n * package's own concern.\n *\n * Sorted by (file, view id) rather than reported in LikeC4's own record order:\n * nothing in loam has measured that the parse preserves declaration order, so a\n * report whose row order depends on that would reorder under a dependency bump\n * — the diff-stability rule `core/capabilities/rollup.ts` states for its rows,\n * applied to findings.\n */\nfunction gradedViews(views: readonly ParsedView[]): ParsedView[] {\n  return views\n    .filter(isUseCase)\n    .sort((a, b) => compareIds(viewFile(a), viewFile(b)) || compareIds(a.id, b.id));\n}\n\n/**\n * Every use-case finding a fleet's declared views earn.\n *\n * The grading record is built once and shared across every step of every view:\n * `attributeStep` caches its element→service resolver on the identity of the\n * elements array and the fleet set, so handing it one `StepScope` for the whole\n * run is what keeps the fleet's use cases from rebuilding that id map per hop.\n */\nexport function useCaseFindings(scope: UseCaseScope): Finding[] {\n  const grading: StepGrading = {\n    // `known` and `services` come from ONE value, so the fleet set the\n    // attribution resolves against and the fleet set the provider guard tests\n    // cannot drift apart into two answers about the same element.\n    model: { elements: scope.elements, relationships: scope.relationships, known: scope.services },\n    services: scope.services,\n    resolve: scope.resolve,\n    place: scope.place,\n  };\n  const findings: Finding[] = [];\n  for (const view of gradedViews(scope.views)) {\n    // ONE resolution of this view's capability tags, shared by both grades. The\n    // `#req-` tag is scoped by exactly the capabilities the `#cap-` tags resolve\n    // to, so resolving twice would be two chances to disagree about which\n    // document a `Requirement-ID` is unique inside.\n    //\n    // THE LADDER IS THE `null`, NOT AN EMPTY LIST, and the distinction is a\n    // wrong answer away: a suspended vocabulary handed on as `[]` reads to the\n    // requirement grade as \"this view resolves no capability\", which is its\n    // `unscoped` ERROR — so every `#req-` tag in a fleet that has not adopted\n    // the capability axis would be convicted for the axis not existing.\n    if (scope.capabilities !== null) {\n      const claims = resolveCapabilityTags(view.tags, scope.capabilities);\n      findings.push(...capabilityTagFindings(view, claims, scope.place));\n      findings.push(...requirementTagFindings(view, claims, scope.requirementsOf, scope.place));\n    }\n    for (const step of view.steps) findings.push(...stepFindings({ view, step }, grading));\n  }\n  return findings;\n}\n"]}

package/dist/core/usecases/operations.js

@@ -0,0 +1,123 @@
+/**
+ * Which hops of which business flows a contract removal breaks.
+ *
+ * `loam diff --base` already answers "who still depends on this operation" with
+ * landscape edges and other services' living requirements. Both are true and
+ * neither is the sentence a reviewer wants: an edge is a line in a diagram and a
+ * requirement is a heading in somebody else's spec, while "step 4 of Checkout
+ * stops working" is the fact a human weighs a pull request against. This module
+ * is the join that produces that sentence, and it produces NOTHING ELSE — no
+ * finding, no code, no severity. `core/consumers/consumers.ts` folds its
+ * answers into the `details[]` of the two codes that already exist.
+ *
+ * ## Attributed is a victim; contested is a suspension
+ *
+ * The distinction is the whole reason this module is careful rather than a
+ * filter. `attributeStep` (core/c4/resolve/steps.ts) grades a hop by the DISTINCT-op
+ * count across the relationships backing it:
+ *
+ *  - `attributed` with `op === X` means every relationship behind the hop agrees
+ *    the hop exercises X, or they disagree and the step's title opens with a
+ *    name declared by candidates that agree on X — the author naming the one
+ *    the hop means, by its op or by the message that edge also carries. Remove
+ *    X and the flow breaks at that hop. That is positive evidence, and it is a
+ *    victim.
+ *  - `contested` means the relationships DISAGREE and the title names none of
+ *    them, so loam does not know which operation the hop exercises. It must not
+ *    claim the flow breaks — a guessed victim reads exactly like a real one and
+ *    turns a warn into an error on somebody's PR — and it must not go silent
+ *    either, because silence here is the fail-open shape
+ *    `ConsumerScan.suspended` exists to forbid. It is a suspension: loam says it
+ *    could not answer.
+ *
+ * A contested hop is suspended only when X is among its candidate operations.
+ * That is not a noise trade, it is the honest boundary: the candidates ARE the
+ * relationships backing the hop, so an operation none of them names is an
+ * operation the hop cannot be exercising under any reading of the disagreement.
+ * Suspending every contested hop in the fleet on every removal would report
+ * doubt loam does not actually have.
+ *
+ * An `unbacked` hop is neither. Nothing in the model backs it, so it names no
+ * operation of anybody's contract — `usecase.step-unbacked` is already the error
+ * that convicts it, and repeating that here would file a modelling defect
+ * against whoever happened to remove an endpoint.
+ */
+import { attributeStep } from "../c4/resolve/steps.js";
+import { hopPlace } from "./place.js";
+const EMPTY = { breaks: [], unsure: [] };
+/** Every hop of every graded use case, view order preserved, so output is stable. */
+function hops(scan) {
+    return scan.views.flatMap((view) => view.steps.map((step) => ({ view, step })));
+}
+/**
+ * The flows one removed operation breaks, and the ones loam cannot answer for.
+ *
+ * An `unreadable` scan contributes NOTHING — neither break nor suspension — and
+ * that is the consumer index's own landscape doctrine (`livingMap` in
+ * `core/consumers/current.ts`, which reads the map for every consumer
+ * question) applied one axis over: an unreadable fleet map proves nothing either way, `landscape.invalid` is
+ * validate's finding to make, and inventing doubt out of a parse error would
+ * point the reviewer at a file their change never touched. The caller reports
+ * the hole; this join stays quiet about it.
+ */
+export function hopsExercising(scan, removed) {
+    if (scan.kind !== "read")
+        return EMPTY;
+    const out = { breaks: [], unsure: [] };
+    for (const { view, step } of hops(scan)) {
+        const attribution = attributeStep(step, scan.model);
+        if (attribution.verdict === "unbacked")
+            continue;
+        // The callee, through the SAME resolver every other join in this run uses,
+        // so a hop drawn into a modelled container `payment.api` is filed against
+        // payment-service rather than against a service called "api".
+        if (scan.resolve(attribution.to) !== removed.provider)
+            continue;
+        // And the CALLER, through the same resolver: a hop whose two endpoints
+        // resolve to one service is that service calling itself, which owes no
+        // operationId of its own contract — `usecase.step-unlinked`'s fourth guard,
+        // applied to the victim join. Without it an internal hop was a break of the
+        // provider's own removal (verification 2026-09-04, R3).
+        if (scan.resolve(attribution.from) === removed.provider)
+            continue;
+        if (attribution.verdict === "attributed") {
+            if (attribution.op === removed.op)
+                out.breaks.push(hopPlace(view, step));
+            continue;
+        }
+        if (!attribution.ops.includes(removed.op))
+            continue;
+        out.unsure.push(`${hopPlace(view, step)} — ${attribution.rels.length} relationships back ` +
+            `${attribution.from} -> ${attribution.to} and they name different operations, so whether this hop ` +
+            `exercises '${removed.op}' could not be answered`);
+    }
+    return out;
+}
+/**
+ * The flows one removed message breaks.
+ *
+ * No suspension arm, and the asymmetry is a fact about the model rather than an
+ * omission: `attributeStep` contests OPERATIONS, because that is where two
+ * relationships between one pair of endpoints can disagree. A `consumes` edge
+ * names a message outright, so a hop either is backed by one or is not — there
+ * is no disagreement for loam to refuse to resolve.
+ *
+ * The provider exclusion mirrors `messageConsumers` exactly: an edge INTO the
+ * provider is the provider's own consumption, which leaves with the same change,
+ * so a hop backed only by that edge is not a victim of it.
+ */
+export function hopsConsuming(scan, removed) {
+    if (scan.kind !== "read")
+        return [];
+    const out = [];
+    for (const { view, step } of hops(scan)) {
+        const attribution = attributeStep(step, scan.model);
+        if (attribution.verdict === "unbacked")
+            continue;
+        const consumes = attribution.rels.some((rel) => rel.consumes === removed.name && scan.resolve(rel.target) !== removed.provider);
+        if (consumes)
+            out.push(hopPlace(view, step));
+    }
+    return out;
+}
+//# sourceMappingURL=operations.js.map

package/dist/core/usecases/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/core/usecases/operations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which hops of which business flows a contract removal breaks.\n *\n * `loam diff --base` already answers \"who still depends on this operation\" with\n * landscape edges and other services' living requirements. Both are true and\n * neither is the sentence a reviewer wants: an edge is a line in a diagram and a\n * requirement is a heading in somebody else's spec, while \"step 4 of Checkout\n * stops working\" is the fact a human weighs a pull request against. This module\n * is the join that produces that sentence, and it produces NOTHING ELSE — no\n * finding, no code, no severity. `core/consumers/consumers.ts` folds its\n * answers into the `details[]` of the two codes that already exist.\n *\n * ## Attributed is a victim; contested is a suspension\n *\n * The distinction is the whole reason this module is careful rather than a\n * filter. `attributeStep` (core/c4/resolve/steps.ts) grades a hop by the DISTINCT-op\n * count across the relationships backing it:\n *\n *  - `attributed` with `op === X` means every relationship behind the hop agrees\n *    the hop exercises X, or they disagree and the step's title opens with a\n *    name declared by candidates that agree on X — the author naming the one\n *    the hop means, by its op or by the message that edge also carries. Remove\n *    X and the flow breaks at that hop. That is positive evidence, and it is a\n *    victim.\n *  - `contested` means the relationships DISAGREE and the title names none of\n *    them, so loam does not know which operation the hop exercises. It must not\n *    claim the flow breaks — a guessed victim reads exactly like a real one and\n *    turns a warn into an error on somebody's PR — and it must not go silent\n *    either, because silence here is the fail-open shape\n *    `ConsumerScan.suspended` exists to forbid. It is a suspension: loam says it\n *    could not answer.\n *\n * A contested hop is suspended only when X is among its candidate operations.\n * That is not a noise trade, it is the honest boundary: the candidates ARE the\n * relationships backing the hop, so an operation none of them names is an\n * operation the hop cannot be exercising under any reading of the disagreement.\n * Suspending every contested hop in the fleet on every removal would report\n * doubt loam does not actually have.\n *\n * An `unbacked` hop is neither. Nothing in the model backs it, so it names no\n * operation of anybody's contract — `usecase.step-unbacked` is already the error\n * that convicts it, and repeating that here would file a modelling defect\n * against whoever happened to remove an endpoint.\n */\nimport { attributeStep } from \"../c4/resolve/steps.js\";\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\nimport { hopPlace } from \"./place.js\";\nimport type { UseCaseScan } from \"./fleet.js\";\n\n/**\n * What one contract removal does to the fleet's use cases.\n *\n * Two lists rather than `victims`/`suspended` — the vocabulary\n * `core/consumers/consumers.ts` uses — because this module answers about FLOWS\n * and that one answers about consumers. The caller does the folding, and naming the two\n * differently is what stops a reader taking this for a second implementation of\n * `ConsumerScan` (it is not: it never scans a document, and it cannot be\n * unreadable — the scan it runs over was already graded).\n */\nexport interface UseCaseHits {\n  /** Hops the removal breaks, each spelled by `hopPlace`. */\n  breaks: string[];\n  /** Hops loam refuses to grade, each saying why in its own sentence. */\n  unsure: string[];\n}\n\n/** The one removal a scan is being asked about. */\nexport interface RemovedOperation {\n  /** The service dropping it — the same id the diff files its findings under. */\n  provider: string;\n  /** The operationId leaving the contract. */\n  op: string;\n}\n\nconst EMPTY: UseCaseHits = { breaks: [], unsure: [] };\n\n/** Every hop of every graded use case, view order preserved, so output is stable. */\nfunction hops(scan: Extract<UseCaseScan, { kind: \"read\" }>): Array<{ view: ParsedView; step: ParsedStep }> {\n  return scan.views.flatMap((view) => view.steps.map((step) => ({ view, step })));\n}\n\n/**\n * The flows one removed operation breaks, and the ones loam cannot answer for.\n *\n * An `unreadable` scan contributes NOTHING — neither break nor suspension — and\n * that is the consumer index's own landscape doctrine (`livingMap` in\n * `core/consumers/current.ts`, which reads the map for every consumer\n * question) applied one axis over: an unreadable fleet map proves nothing either way, `landscape.invalid` is\n * validate's finding to make, and inventing doubt out of a parse error would\n * point the reviewer at a file their change never touched. The caller reports\n * the hole; this join stays quiet about it.\n */\nexport function hopsExercising(scan: UseCaseScan, removed: RemovedOperation): UseCaseHits {\n  if (scan.kind !== \"read\") return EMPTY;\n  const out: UseCaseHits = { breaks: [], unsure: [] };\n  for (const { view, step } of hops(scan)) {\n    const attribution = attributeStep(step, scan.model);\n    if (attribution.verdict === \"unbacked\") continue;\n    // The callee, through the SAME resolver every other join in this run uses,\n    // so a hop drawn into a modelled container `payment.api` is filed against\n    // payment-service rather than against a service called \"api\".\n    if (scan.resolve(attribution.to) !== removed.provider) continue;\n    // And the CALLER, through the same resolver: a hop whose two endpoints\n    // resolve to one service is that service calling itself, which owes no\n    // operationId of its own contract — `usecase.step-unlinked`'s fourth guard,\n    // applied to the victim join. Without it an internal hop was a break of the\n    // provider's own removal (verification 2026-09-04, R3).\n    if (scan.resolve(attribution.from) === removed.provider) continue;\n    if (attribution.verdict === \"attributed\") {\n      if (attribution.op === removed.op) out.breaks.push(hopPlace(view, step));\n      continue;\n    }\n    if (!attribution.ops.includes(removed.op)) continue;\n    out.unsure.push(\n      `${hopPlace(view, step)} — ${attribution.rels.length} relationships back ` +\n        `${attribution.from} -> ${attribution.to} and they name different operations, so whether this hop ` +\n        `exercises '${removed.op}' could not be answered`,\n    );\n  }\n  return out;\n}\n\n/** The one message removal a scan is being asked about. */\nexport interface RemovedMessage {\n  /** The service dropping the declaration — the diff's own subject. */\n  provider: string;\n  /** The AsyncAPI message name leaving the contract. */\n  name: string;\n}\n\n/**\n * The flows one removed message breaks.\n *\n * No suspension arm, and the asymmetry is a fact about the model rather than an\n * omission: `attributeStep` contests OPERATIONS, because that is where two\n * relationships between one pair of endpoints can disagree. A `consumes` edge\n * names a message outright, so a hop either is backed by one or is not — there\n * is no disagreement for loam to refuse to resolve.\n *\n * The provider exclusion mirrors `messageConsumers` exactly: an edge INTO the\n * provider is the provider's own consumption, which leaves with the same change,\n * so a hop backed only by that edge is not a victim of it.\n */\nexport function hopsConsuming(scan: UseCaseScan, removed: RemovedMessage): string[] {\n  if (scan.kind !== \"read\") return [];\n  const out: string[] = [];\n  for (const { view, step } of hops(scan)) {\n    const attribution = attributeStep(step, scan.model);\n    if (attribution.verdict === \"unbacked\") continue;\n    const consumes = attribution.rels.some(\n      (rel) => rel.consumes === removed.name && scan.resolve(rel.target) !== removed.provider,\n    );\n    if (consumes) out.push(hopPlace(view, step));\n  }\n  return out;\n}\n"]}

package/dist/core/usecases/place.js

@@ -0,0 +1,44 @@
+/**
+ * The document the view was written in, spelled repo-relative.
+ *
+ * `sourcePath` is relative to the LikeC4 PROJECT root, which for
+ * `loadArchitecture` is `architecture/`, so the prefix is added here and nowhere
+ * else. The caller owes one thing in exchange: only views that came from
+ * `loadProject` may be spelled with this, because the single-file loaders name
+ * every document after themselves (`source.c4`) and this function would then
+ * spell a path that has never existed.
+ *
+ * An ABSENT `sourcePath` names the directory rather than guessing a file.
+ * LikeC4 synthesizes only element views and `readDynamicViews` drops those, so
+ * nothing at the 1.59.2 pin reaches this arm; if a release ever stopped emitting
+ * the field, falling back to `architecture/landscape.likec4` would put a false
+ * cross-reference in a message.
+ */
+export function viewFile(view) {
+    return view.sourcePath === undefined ? "architecture/" : `architecture/${view.sourcePath}`;
+}
+/**
+ * `step 4 'confirms the order'`, or `step 4` where the author labelled nothing.
+ *
+ * The ordinal is the view's own leaf numbering (`ParsedStep.ordinal`), which
+ * skips group brackets — so it counts what the author sees on the diagram, and
+ * a message naming step 4 is naming the fourth arrow.
+ */
+export function stepPlace(step) {
+    return step.title === undefined ? `step ${step.ordinal}` : `step ${step.ordinal} '${step.title}'`;
+}
+/**
+ * A use case and one of its hops, named the way a reader outside `validate`
+ * meets them: `use case 'uc_checkout' step 4 'authorizes the payment'
+ * (architecture/usecases/checkout.likec4)`.
+ *
+ * The file goes LAST here and first in validate's `viewPlace`, and that is not
+ * an inconsistency to tidy away. A validate finding is a line in a report about
+ * documents, so it leads with the document; a diff victim is one entry in a
+ * `details[]` list whose other entries name edges and requirements, so it has to
+ * lead with the thing that broke and carry the file as the place to go fix it.
+ */
+export function hopPlace(view, step) {
+    return `use case '${view.id}' ${stepPlace(step)} (${viewFile(view)})`;
+}
+//# sourceMappingURL=place.js.map

package/dist/core/usecases/place.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../../../src/core/usecases/place.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgB;IACvC,OAAO,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,UAAU,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,KAAK,GAAG,CAAC;AACpG,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAgB,EAAE,IAAgB;IACzD,OAAO,aAAa,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC;AACxE,CAAC","sourcesContent":["/**\n * Where a use case lives and where one of its hops sits — the two spellings\n * every surface that mentions a use case has to agree on.\n *\n * They began in `commands/validate/fleet/usecases/place.ts`, beside the four\n * `usecase.*` graders that were their only reader. `loam diff` naming the flow a\n * removal breaks is the second reader and `loam delta`/`loam context` are the\n * third and fourth, and `core/` may not import from `commands/` (AGENTS.md), so\n * the alternative was a second spelling of `architecture/<sourcePath>` in core.\n * The two would drift silently and in the worst possible direction: a file path\n * in a message that no longer names the file the view is in is how the next\n * reader stops looking (docs/CODE-STYLE.md).\n *\n * What did NOT move is `viewPlace`, the `landscape: …` opening the validate\n * findings carry. That prefix is the name of a validate TARGET, so it is command\n * vocabulary — a `loam diff` finding is filed against a service, not against the\n * fleet map, and borrowing validate's prefix there would claim a target that run\n * does not have.\n */\nimport type { ParsedStep, ParsedView } from \"../c4/parsed/dynamic-views.js\";\n\n/**\n * Where a use-case FINDING says its view is — the opening of every message the\n * graders in `./grade/` write. A function each scope supplies rather than one\n * spelling, because the three scopes file a view three ways: the fleet target\n * as `landscape: architecture/<file> — dynamic view '<id>'` (`viewPlace`, which\n * stayed command vocabulary for the reason above), the service target against\n * its own directory, and the feature gate against the feature's `usecases/`\n * file the view is still written in.\n */\nexport type ViewPlace = (view: ParsedView) => string;\n\n/**\n * The document the view was written in, spelled repo-relative.\n *\n * `sourcePath` is relative to the LikeC4 PROJECT root, which for\n * `loadArchitecture` is `architecture/`, so the prefix is added here and nowhere\n * else. The caller owes one thing in exchange: only views that came from\n * `loadProject` may be spelled with this, because the single-file loaders name\n * every document after themselves (`source.c4`) and this function would then\n * spell a path that has never existed.\n *\n * An ABSENT `sourcePath` names the directory rather than guessing a file.\n * LikeC4 synthesizes only element views and `readDynamicViews` drops those, so\n * nothing at the 1.59.2 pin reaches this arm; if a release ever stopped emitting\n * the field, falling back to `architecture/landscape.likec4` would put a false\n * cross-reference in a message.\n */\nexport function viewFile(view: ParsedView): string {\n  return view.sourcePath === undefined ? \"architecture/\" : `architecture/${view.sourcePath}`;\n}\n\n/**\n * `step 4 'confirms the order'`, or `step 4` where the author labelled nothing.\n *\n * The ordinal is the view's own leaf numbering (`ParsedStep.ordinal`), which\n * skips group brackets — so it counts what the author sees on the diagram, and\n * a message naming step 4 is naming the fourth arrow.\n */\nexport function stepPlace(step: ParsedStep): string {\n  return step.title === undefined ? `step ${step.ordinal}` : `step ${step.ordinal} '${step.title}'`;\n}\n\n/**\n * A use case and one of its hops, named the way a reader outside `validate`\n * meets them: `use case 'uc_checkout' step 4 'authorizes the payment'\n * (architecture/usecases/checkout.likec4)`.\n *\n * The file goes LAST here and first in validate's `viewPlace`, and that is not\n * an inconsistency to tidy away. A validate finding is a line in a report about\n * documents, so it leads with the document; a diff victim is one entry in a\n * `details[]` list whose other entries name edges and requirements, so it has to\n * lead with the thing that broke and carry the file as the place to go fix it.\n */\nexport function hopPlace(view: ParsedView, step: ParsedStep): string {\n  return `use case '${view.id}' ${stepPlace(step)} (${viewFile(view)})`;\n}\n"]}

package/dist/core/usecases/service/exclude.js

@@ -0,0 +1,119 @@
+/**
+ * Which `.likec4` files beside a `model.likec4` the RENDERER actually loads —
+ * the `exclude` list of the service's own `likec4.config.json`.
+ *
+ * loam writes that file with two keys and never reads it back
+ * (`core/repo/tree/render/projects.ts` states the ownership rule), but a team
+ * may add keys to it, and `exclude` is the one that changes what the project
+ * holds. Until this module existed the service-flow reader staged every sibling
+ * regardless: a view the renderer never sees was graded, and the finding it
+ * earned said the project is "read the way the renderer reads it" and that the
+ * view still renders — three claims about a file nobody would ever open
+ * (verification 2026-09-04, D10).
+ *
+ * STANDALONE MODELS ONLY, which is where this file IS the project config. A
+ * model that extends the map is read inside the ROOT project, whose own
+ * `exclude` decides what it holds; a per-service config beside such a model is
+ * a stray with a finding of its own (`service.likec4-config-stray`), and
+ * honouring its list here would silence a document the renderer really does
+ * load.
+ *
+ * THE MATCHER IS THE ONE MEASURED, at the likec4 1.59.2 pin, on a scratch
+ * service directory holding `model.likec4`, `views.likec4` and
+ * `usecases/flow.likec4` (`npx likec4 validate <dir>`, counting "found N source
+ * files"): an entry drops a file when the file's directory-relative path STARTS
+ * WITH the entry (`views`, `views.`, `views.likec4`, `usecases`, `usecases/`,
+ * `usecases/flow` each dropped one; `ews.likec4` dropped none), or when it
+ * matches as a glob whose `*` crosses `/` (`*.likec4` dropped all THREE), or
+ * when a leading RECURSIVE segment — a doubled star and a slash — stands for
+ * the zero or more directories above the file: that segment before `*.likec4`
+ * dropped all three, and before `usecases` (with a recursive tail) or
+ * `views.likec4` it dropped one each. All three halves are implemented because
+ * all three were observed; nothing here interprets more than that, and an entry
+ * loam cannot match leaves the file loaded — grading a file the renderer skips
+ * is a wrong sentence, and skipping one it reads is a missing finding, which is
+ * the worse of the two.
+ */
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { isRecord } from "../../kernel/records.js";
+import { excludingPath } from "../../c4/root-project/exclude.js";
+/** The per-service project file, by the name `core/repo/tree/render/projects.ts` writes it under. */
+const CONFIG = "likec4.config.json";
+/**
+ * The service project's `exclude` entries, or `[]` when there is no list to
+ * read — absent, unreadable, not JSON, or an `exclude` that is not a list of
+ * strings. Failing open is right here and nowhere else: the answer decides
+ * whether loam GRADES a document, and an empty list grades everything, which is
+ * exactly what loam did before this module and never a new silence.
+ */
+export async function serviceProjectExclude(dir) {
+    const text = await readFile(`${dir}/${CONFIG}`, "utf8").catch(() => null);
+    if (text === null)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (!isRecord(parsed))
+        return [];
+    const exclude = parsed["exclude"];
+    if (!Array.isArray(exclude))
+        return [];
+    const entries = exclude;
+    return entries.filter((entry) => typeof entry === "string" && entry.trim() !== "");
+}
+/** The siblings that survive the list — absolute paths in, absolute paths out, order kept. */
+export function keepIncluded(dir, exclude, paths) {
+    if (exclude.length === 0)
+        return [...paths];
+    return paths.filter((path) => !excluded(exclude, relative(dir, path).split(/[\\/]/).join("/")));
+}
+/**
+ * Three rungs, because three separate spellings were measured hiding a file and
+ * no one of them subsumes the others.
+ *
+ *  - the bare PREFIX (`views`, `usecases/flow`), which is the renderer's own
+ *    behaviour and matches nothing a glob would;
+ *  - `excludingPath`, the segment walk `core/c4/root-project/exclude.ts` already
+ *    owns, which is what reads a doubled star anywhere in the entry — the three
+ *    recursive spellings the docstring above measured each hide what the
+ *    renderer hides, and the `globRe` half alone matched NONE of them, because a
+ *    leading recursive segment compiled to a REQUIRED slash. loam therefore
+ *    graded a file in no project it may claim to be reading, and gated the run
+ *    on it (verification 2026-09-04);
+ *  - `globRe`, kept for the one case the segment walk cannot express: a `*` that
+ *    CROSSES `/`, which is what `*.likec4` hiding `usecases/flow.likec4` was
+ *    measured doing.
+ *
+ * A union only ever hides more, and the module's own rule says the worse of the
+ * two mistakes is skipping a file the renderer reads; each rung above is a
+ * measurement rather than an interpretation, so the union stays honest.
+ */
+function excluded(exclude, rel) {
+    return exclude.some((raw) => {
+        const entry = raw.replace(/^\.\//, "");
+        if (entry === "")
+            return false;
+        if (rel.startsWith(entry))
+            return true;
+        if (excludingPath([entry], rel) !== null)
+            return true;
+        return entry.includes("*") && globRe(entry).test(rel);
+    });
+}
+/**
+ * One entry as a whole-path regular expression, with `*` crossing `/` — which
+ * is what `*.likec4` excluding `usecases/flow.likec4` measures. Built per call
+ * rather than cached: a `RegExp` is cheap beside the readdir that produced the
+ * paths, and a module-level cache keyed on a string is the shared state
+ * AGENTS.md warns about.
+ */
+function globRe(entry) {
+    const source = entry.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*+/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${source}$`);
+}
+//# sourceMappingURL=exclude.js.map

package/dist/core/usecases/service/exclude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exclude.js","sourceRoot":"","sources":["../../../../src/core/usecases/service/exclude.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which `.likec4` files beside a `model.likec4` the RENDERER actually loads —\n * the `exclude` list of the service's own `likec4.config.json`.\n *\n * loam writes that file with two keys and never reads it back\n * (`core/repo/tree/render/projects.ts` states the ownership rule), but a team\n * may add keys to it, and `exclude` is the one that changes what the project\n * holds. Until this module existed the service-flow reader staged every sibling\n * regardless: a view the renderer never sees was graded, and the finding it\n * earned said the project is \"read the way the renderer reads it\" and that the\n * view still renders — three claims about a file nobody would ever open\n * (verification 2026-09-04, D10).\n *\n * STANDALONE MODELS ONLY, which is where this file IS the project config. A\n * model that extends the map is read inside the ROOT project, whose own\n * `exclude` decides what it holds; a per-service config beside such a model is\n * a stray with a finding of its own (`service.likec4-config-stray`), and\n * honouring its list here would silence a document the renderer really does\n * load.\n *\n * THE MATCHER IS THE ONE MEASURED, at the likec4 1.59.2 pin, on a scratch\n * service directory holding `model.likec4`, `views.likec4` and\n * `usecases/flow.likec4` (`npx likec4 validate <dir>`, counting \"found N source\n * files\"): an entry drops a file when the file's directory-relative path STARTS\n * WITH the entry (`views`, `views.`, `views.likec4`, `usecases`, `usecases/`,\n * `usecases/flow` each dropped one; `ews.likec4` dropped none), or when it\n * matches as a glob whose `*` crosses `/` (`*.likec4` dropped all THREE), or\n * when a leading RECURSIVE segment — a doubled star and a slash — stands for\n * the zero or more directories above the file: that segment before `*.likec4`\n * dropped all three, and before `usecases` (with a recursive tail) or\n * `views.likec4` it dropped one each. All three halves are implemented because\n * all three were observed; nothing here interprets more than that, and an entry\n * loam cannot match leaves the file loaded — grading a file the renderer skips\n * is a wrong sentence, and skipping one it reads is a missing finding, which is\n * the worse of the two.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { isRecord } from \"../../kernel/records.js\";\nimport { excludingPath } from \"../../c4/root-project/exclude.js\";\nimport type { ServiceDir } from \"../../kernel/ids/dirs.js\";\n\n/** The per-service project file, by the name `core/repo/tree/render/projects.ts` writes it under. */\nconst CONFIG = \"likec4.config.json\";\n\n/**\n * The service project's `exclude` entries, or `[]` when there is no list to\n * read — absent, unreadable, not JSON, or an `exclude` that is not a list of\n * strings. Failing open is right here and nowhere else: the answer decides\n * whether loam GRADES a document, and an empty list grades everything, which is\n * exactly what loam did before this module and never a new silence.\n */\nexport async function serviceProjectExclude(dir: ServiceDir): Promise<string[]> {\n  const text = await readFile(`${dir}/${CONFIG}`, \"utf8\").catch(() => null);\n  if (text === null) return [];\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(text);\n  } catch {\n    return [];\n  }\n  if (!isRecord(parsed)) return [];\n  const exclude: unknown = parsed[\"exclude\"];\n  if (!Array.isArray(exclude)) return [];\n  const entries: unknown[] = exclude;\n  return entries.filter((entry): entry is string => typeof entry === \"string\" && entry.trim() !== \"\");\n}\n\n/** The siblings that survive the list — absolute paths in, absolute paths out, order kept. */\nexport function keepIncluded(dir: ServiceDir, exclude: readonly string[], paths: readonly string[]): string[] {\n  if (exclude.length === 0) return [...paths];\n  return paths.filter((path) => !excluded(exclude, relative(dir, path).split(/[\\\\/]/).join(\"/\")));\n}\n\n/**\n * Three rungs, because three separate spellings were measured hiding a file and\n * no one of them subsumes the others.\n *\n *  - the bare PREFIX (`views`, `usecases/flow`), which is the renderer's own\n *    behaviour and matches nothing a glob would;\n *  - `excludingPath`, the segment walk `core/c4/root-project/exclude.ts` already\n *    owns, which is what reads a doubled star anywhere in the entry — the three\n *    recursive spellings the docstring above measured each hide what the\n *    renderer hides, and the `globRe` half alone matched NONE of them, because a\n *    leading recursive segment compiled to a REQUIRED slash. loam therefore\n *    graded a file in no project it may claim to be reading, and gated the run\n *    on it (verification 2026-09-04);\n *  - `globRe`, kept for the one case the segment walk cannot express: a `*` that\n *    CROSSES `/`, which is what `*.likec4` hiding `usecases/flow.likec4` was\n *    measured doing.\n *\n * A union only ever hides more, and the module's own rule says the worse of the\n * two mistakes is skipping a file the renderer reads; each rung above is a\n * measurement rather than an interpretation, so the union stays honest.\n */\nfunction excluded(exclude: readonly string[], rel: string): boolean {\n  return exclude.some((raw) => {\n    const entry = raw.replace(/^\\.\\//, \"\");\n    if (entry === \"\") return false;\n    if (rel.startsWith(entry)) return true;\n    if (excludingPath([entry], rel) !== null) return true;\n    return entry.includes(\"*\") && globRe(entry).test(rel);\n  });\n}\n\n/**\n * One entry as a whole-path regular expression, with `*` crossing `/` — which\n * is what `*.likec4` excluding `usecases/flow.likec4` measures. Built per call\n * rather than cached: a `RegExp` is cheap beside the readdir that produced the\n * paths, and a module-level cache keyed on a string is the shared state\n * AGENTS.md warns about.\n */\nfunction globRe(entry: string): RegExp {\n  const source = entry.replace(/[.+^${}()|[\\]\\\\]/g, \"\\\\$&\").replace(/\\*+/g, \".*\").replace(/\\?/g, \".\");\n  return new RegExp(`^${source}$`);\n}\n"]}