@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/core/diff/joins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"joins.js","sourceRoot":"","sources":["../../../src/core/diff/joins.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The cross-service joins `loam diff` reports appearing or going away between\n * the base ref and the working tree — `diff.consumer-added` /\n * `diff.consumer-removed`.\n *\n * These lived in `./victims.ts` beside the per-removal victim index until that\n * index moved down to `core/consumers/` to become the one consumer answer the\n * coherence gate and the archive planner read too. The joins below stayed: they\n * compare two WHOLE states, which only the diff has, while the index answers\n * about one fleet.\n */\nimport type { Requirement } from \"../document/spec.js\";\nimport type { ServiceState } from \"../consumers/state.js\";\nimport { ownsOperation, REQUIREMENT_AXES } from \"../consumers/consumers.js\";\n\n/** The requirements one service contributes to a join — both spec files, a REMOVED one governing nothing. */\nfunction reqsOf(state: ServiceState): Requirement[] {\n  return REQUIREMENT_AXES.flatMap((axis) => {\n    const a = state[axis];\n    return a.kind === \"read\" ? a.value.filter((r) => r.kind !== \"REMOVED\") : [];\n  });\n}\n\n/**\n * One cross-service join: `consumer`'s living requirements name a `token` that\n * `provider`'s contract defines. The same \"who depends on what\" question the\n * consumer index (`core/consumers/consumers.ts`) answers per removal, asked\n * here of a WHOLE state — base or current — so `./semantic.ts` can report\n * joins that appeared or went away.\n */\nexport interface ConsumerTuple {\n  kind: \"op\" | \"message\";\n  consumer: string;\n  provider: string;\n  token: string;\n}\n\n/** The map key a tuple is joined on between the two states. */\nfunction tupleKey(t: ConsumerTuple): string {\n  return `${t.kind}\\0${t.consumer}\\0${t.provider}\\0${t.token}`;\n}\n\n/**\n * Every cross-service join one state holds, keyed for the base/current join.\n * The rules are the consumer index's, read off it rather than restated: both\n * spec files for `Operations:` and `Consumes:` alike (`REQUIREMENT_AXES`), and\n * an `Operations:` line naming an id the consumer's own contract defines is\n * that consumer's own operation, no join onto anybody else's\n * (`ownsOperation`). An unreadable axis simply contributes nothing here — no\n * line from a spec file nobody could read, no ownership from a contract nobody\n * could read — and `tupleVisible` below guards the GRADING, so a join is never\n * called added or removed off a side nobody could read, and `ownershipFlicker`\n * keeps one from being called so off a consumer's own contract that merely\n * stopped or started parsing.\n */\nexport function consumerTuples(states: ReadonlyMap<string, ServiceState>): Map<string, ConsumerTuple> {\n  const providersOf = (pick: (s: ServiceState) => string[]): Map<string, string[]> => {\n    const map = new Map<string, string[]>();\n    for (const id of [...states.keys()].sort()) {\n      for (const token of pick(states.get(id)!)) map.set(token, [...(map.get(token) ?? []), id]);\n    }\n    return map;\n  };\n  const opProviders = providersOf((s) => (s.openapi.kind === \"read\" ? s.openapi.value.map((op) => op.id) : []));\n  const msgProviders = providersOf((s) => (s.asyncapi.kind === \"read\" ? s.asyncapi.value.map((m) => m.name) : []));\n  const out = new Map<string, ConsumerTuple>();\n  const add = (t: ConsumerTuple): void => {\n    out.set(tupleKey(t), t);\n  };\n  for (const consumer of [...states.keys()].sort()) {\n    const state = states.get(consumer)!;\n    for (const r of reqsOf(state)) {\n      for (const op of r.operations) {\n        if (ownsOperation(state, op)) continue;\n        for (const p of opProviders.get(op) ?? []) if (p !== consumer) add({ kind: \"op\", consumer, provider: p, token: op });\n      }\n      for (const name of r.consumes) {\n        for (const p of msgProviders.get(name) ?? []) if (p !== consumer) add({ kind: \"message\", consumer, provider: p, token: name });\n      }\n    }\n  }\n  return out;\n}\n\n/** May a tuple be graded off this side? Absence answers; unreadable does not; an ambiguous base identity answers nothing. */\nfunction tupleVisible(states: ReadonlyMap<string, ServiceState>, ambiguous: ReadonlySet<string>, t: ConsumerTuple): boolean {\n  if (ambiguous.has(t.consumer) || ambiguous.has(t.provider)) return false;\n  const readable = (id: string, axes: (\"spec\" | \"archSpec\" | \"openapi\" | \"asyncapi\")[]): boolean => {\n    const state = states.get(id);\n    return state === undefined || axes.every((axis) => state[axis].kind !== \"unreadable\");\n  };\n  // Both spec files on the consumer's side, for either kind: a line in the file\n  // nobody could read may be the very one the join came or went by. NOT the\n  // consumer's own contract, although an operation join reads it: it is asked\n  // only whether the line names the consumer's OWN operation, and an\n  // unreadable contract proves no ownership (`ownsOperation`), so the line\n  // counts on that side — the index's own rule. A side holding it unread can\n  // only have MORE joins, never hide one, and suppressing the join there kept\n  // `diff.consumer-added` / `-removed` off a report whose victims named that\n  // very consumer (the contract review, finding 4). Those extra joins are a\n  // change of their own only when the readable side does not prove the\n  // ownership the unread one could not — `ownershipFlicker` below.\n  return readable(t.consumer, [\"spec\", \"archSpec\"]) && readable(t.provider, [t.kind === \"op\" ? \"openapi\" : \"asyncapi\"]);\n}\n\n/**\n * Is this operation join held only because the consumer's own contract did not\n * parse on the side that holds it, while on the other side it reads and\n * defines the id? Then the line names the consumer's OWN operation — the\n * readable side says so — and nothing about the join moved but the contract's\n * readability: the line that never changed \"went away\" when the contract was\n * fixed and \"appeared\" when it broke, once per provider of a shared id such as\n * `healthCheck` (the verification of finding 4, N1). The unreadable contract\n * is already its own `unreadable[]` entry on the consumer, which carries the\n * run to exit 1; a second, false finding on every provider said nothing true.\n *\n * Only that shape is skipped. A readable side that defines no such id proves\n * no ownership either, so the join is the line's and is graded as before; a\n * message join asks no ownership at all (`ownsOperation` says why).\n */\nfunction ownershipFlicker(sides: { holding: ReadonlyMap<string, ServiceState>; other: ReadonlyMap<string, ServiceState> }, t: ConsumerTuple): boolean {\n  if (t.kind !== \"op\" || sides.holding.get(t.consumer)?.openapi.kind !== \"unreadable\") return false;\n  const other = sides.other.get(t.consumer);\n  return other !== undefined && ownsOperation(other, t.token);\n}\n\n/** One graded cross-service join change between the two states. */\nexport interface ConsumerChange {\n  t: ConsumerTuple;\n  change: \"added\" | \"removed\";\n}\n\n/**\n * The joins that appeared or went away between base and current, sorted for\n * deterministic output (provider, kind, token, consumer). The visibility\n * guard is the containment rule: a join is never called \"added\" off a base\n * side nobody could read, nor \"removed\" off an unreadable working file — the\n * suspended axis already carries that fact. The flicker guard is its mirror on\n * the side that HOLDS the join: one held only because the consumer's own\n * contract did not read there, over an id the other side shows it owns, is no\n * change either.\n */\nexport function consumerJoinChanges(input: {\n  base: ReadonlyMap<string, ServiceState>;\n  baseAmbiguous: ReadonlySet<string>;\n  current: ReadonlyMap<string, ServiceState>;\n  currentAmbiguous: ReadonlySet<string>;\n}): ConsumerChange[] {\n  const baseTuples = consumerTuples(input.base);\n  const currentTuples = consumerTuples(input.current);\n  const graded: ConsumerChange[] = [];\n  const added = { holding: input.current, other: input.base };\n  const removed = { holding: input.base, other: input.current };\n  for (const [key, t] of currentTuples) {\n    if (baseTuples.has(key) || ownershipFlicker(added, t)) continue;\n    if (tupleVisible(input.base, input.baseAmbiguous, t)) graded.push({ t, change: \"added\" });\n  }\n  for (const [key, t] of baseTuples) {\n    if (currentTuples.has(key) || ownershipFlicker(removed, t)) continue;\n    if (tupleVisible(input.current, input.currentAmbiguous, t)) graded.push({ t, change: \"removed\" });\n  }\n  return graded.sort((a, b) => {\n    const ka = `${a.t.provider}\\0${a.t.kind}\\0${a.t.token}\\0${a.t.consumer}\\0${a.change}`;\n    const kb = `${b.t.provider}\\0${b.t.kind}\\0${b.t.token}\\0${b.t.consumer}\\0${b.change}`;\n    return ka < kb ? -1 : 1;\n  });\n}\n"]}

package/dist/core/diff/scope/changed-paths.js

@@ -15,7 +15,9 @@
  * directory is at the five-file limit and because this is a different subject
  * from the semantic diff beside it: `diff` compares two states of the fleet and
  * reports what moved, this one only decides WHICH SUBJECTS a run should look
- * at. Nothing here reads a document.
+ * at. Nothing here reads a document; the one question that has to — which call
+ * edges on the fleet map are this branch's — is `./edges.ts`'s, and it reads
+ * only the map documents the branch changed.
  *
  * What it does NOT do, and the line is not negotiable: a diff-scoped validate
  * cannot see a victim boundary the change did not touch. Removing an operation
@@ -25,10 +27,17 @@
  * the two gates answer "did you document what you touched" and "did you break a
  * consumer", and neither substitutes for the other. Selling a green here that
  * hides a broken join would be worse than shipping no flag at all.
+ *
+ * A join the branch WROTE is a different case, and it is graded: an edge the
+ * branch added or edited on the fleet map is checked against its provider's
+ * contract even with the provider out of scope (`edges` below), because the
+ * edge is the document this branch touched and the provider is only where its
+ * answer lives.
  */
 import { declineDetail, gitText } from "../../provenance/git.js";
 import { repoPath } from "../../envelope/json.js";
 import { resolveBase } from "../base-git.js";
+import { edgesSince } from "./edges.js";
 /**
  * Every path that differs between `ref` and the WORKING TREE, docs-relative.
  *
@@ -88,6 +97,10 @@ async function changedPaths(docsDir, commit, prefix) {
 function inside(path, dir) {
     return dir !== "" && (path === dir || path.startsWith(`${dir}/`));
 }
+/** Did this branch change `rel` — a docs-relative file, or anything under a docs-relative directory? */
+export function touched(scope, rel) {
+    return scope.changed.some((path) => inside(path, rel));
+}
 /** The fleet's own documents — the landscape target's subject, which owns no service directory. */
 const ARCHITECTURE_DIR = "architecture";
 /**
@@ -134,15 +147,18 @@ export async function scopeSince(request) {
         };
     }
     const dirOf = (abs) => repoPath(docsDir, abs);
+    // `architecture/` is the landscape target's whole directory: the fleet map,
+    // the permission/capability/obligation vocabularies and the fleet ADRs all
+    // live there, and every one of them is graded by the landscape target
+    // rather than by any service.
+    const architecture = changed.filter((path) => inside(path, ARCHITECTURE_DIR));
     return {
         kind: "scope",
         ref,
         commit: base.commit,
-        // `architecture/` is the landscape target's whole directory: the fleet map,
-        // the permission/capability/obligation vocabularies and the fleet ADRs all
-        // live there, and every one of them is graded by the landscape target
-        // rather than by any service.
-        landscape: changed.some((path) => inside(path, ARCHITECTURE_DIR)),
+        landscape: architecture.length > 0,
+        changed,
+        edges: await edgesSince({ docsDir, commit: base.commit, prefix: base.prefix }, architecture.filter((path) => path.endsWith(".likec4"))),
         services: request.services.filter((svc) => changed.some((path) => inside(path, dirOf(svc.dir)))),
         features: request.features.filter((feat) => changed.some((path) => inside(path, dirOf(feat.dir)))),
         totals: { services: request.services.length, features: request.features.length },

package/dist/core/diff/scope/changed-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"changed-paths.js","sourceRoot":"","sources":["../../../../src/core/diff/scope/changed-paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which targets a base git ref puts in scope — the narrowing behind\n * `loam validate --all --base <ref>`.\n *\n * The defect this exists for: a partly-adopted fleet has no CI setting that is\n * both passing today and tightening over time. `--all` is green over eleven\n * undocumented services (they warn, and warnings do not gate) and `--strict` is\n * red from the first minute of adoption until the last boundary is written, so\n * a team installs either a gate that never notices adoption stalling at 8% or\n * one it cannot turn on. `--base` is the third setting: grade what this branch\n * TOUCHED, at full `--strict` severity if the caller wants it, and let the\n * untouched majority stay untouched.\n *\n * A SUB-PACKAGE of `core/diff/` rather than a sixth file in it, because that\n * directory is at the five-file limit and because this is a different subject\n * from the semantic diff beside it: `diff` compares two states of the fleet and\n * reports what moved, this one only decides WHICH SUBJECTS a run should look\n * at. Nothing here reads a document.\n *\n * What it does NOT do, and the line is not negotiable: a diff-scoped validate\n * cannot see a victim boundary the change did not touch. Removing an operation\n * from `payment-service` puts `payment-service` in scope and leaves\n * `checkout-web` — whose living requirement still names the operation — out of\n * it. That join is `loam diff --base`'s question and it stays `loam diff`'s;\n * the two gates answer \"did you document what you touched\" and \"did you break a\n * consumer\", and neither substitutes for the other. Selling a green here that\n * hides a broken join would be worse than shipping no flag at all.\n */\nimport { declineDetail, gitText } from \"../../provenance/git.js\";\nimport { repoPath, type ErrorCode } from \"../../envelope/json.js\";\nimport { resolveBase } from \"../base-git.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport type { FeatureEntry, ServiceEntry } from \"../../repo/entries.js\";\n\n/** Everything the narrowing needs: where to ask, what to ask about, and what there is to narrow. */\nexport interface ScopeRequest {\n  docsDir: DocsDir;\n  /** The ref as the caller spelled it — echoed in every message and in the payload. */\n  ref: string;\n  /** The run's full service enumeration, at whatever depth the tree walk found each one. */\n  services: readonly ServiceEntry[];\n  /** The run's full ACTIVE feature enumeration. */\n  features: readonly FeatureEntry[];\n}\n\n/** The narrowed run: which targets the branch touched, and what it narrowed from. */\nexport interface ValidateScope {\n  kind: \"scope\";\n  ref: string;\n  /** The 40-hex commit `ref` resolved to — what a rerun would have to pass to reproduce this scope. */\n  commit: string;\n  /** Did `architecture/` change? The landscape target is the fleet's own subject and has no directory of its own. */\n  landscape: boolean;\n  services: ServiceEntry[];\n  features: FeatureEntry[];\n  /** The denominators — what the run would have graded without `--base`. */\n  totals: { services: number; features: number };\n}\n\n/**\n * A refusal, already spelled. The code is one `loam diff` already emits for the\n * same two conditions and the message is in the same register, deliberately: a\n * second stable code for \"that ref does not resolve\" would be a second thing to\n * document, branch on and keep in step, for a condition that is identical.\n *\n * The prose is built here rather than in the command because it is the same\n * sentence for every caller and because `base-git.ts`'s `detail` — git's own\n * words, bounded — is what makes it diagnosable; a command that only received a\n * `kind` would have to reinvent the sentence to say why.\n */\nexport interface ScopeRefusal {\n  kind: \"refused\";\n  code: ErrorCode;\n  message: string;\n}\n\nexport type ScopeOutcome = ValidateScope | ScopeRefusal;\n\n/**\n * Every path that differs between `ref` and the WORKING TREE, docs-relative.\n *\n * Two questions, not one, and the second is not optional: `git diff` compares\n * the tree git tracks, so a service adopted five minutes ago — a brand new\n * `services/<id>/spec.md` nobody has committed — is invisible to it. `validate`\n * grades the working tree, so the scope has to be the working tree's, and an\n * untracked new boundary that the run then skipped would be the flag's very\n * first user reporting that it graded nothing.\n *\n * `--no-renames` on purpose: with rename detection on (git's default since\n * 2.9) a service moved into a subsystem reports only its DESTINATION, and the\n * checks that grade the fleet from the old placement would be out of scope.\n * Two paths for a move is the honest answer.\n *\n * `-z` because git quotes non-ASCII and space-bearing paths in line output —\n * the same reason `gitTrackedFiles` asks that way, and the same phantom\n * directory named `\"src` if it did not.\n */\nasync function changedPaths(docsDir: DocsDir, commit: string, prefix: string): Promise<string[] | { detail: string }> {\n  // Both run from docsDir. `git diff` ignores cwd and answers for the whole\n  // repository with root-relative paths; `git ls-files` restricts itself to\n  // cwd, and `--full-name` makes ITS paths root-relative too — so one prefix\n  // strip below is correct for both, exactly as `listBaseTree` needs one.\n  const tracked = await gitText(docsDir, [\"diff\", \"--name-only\", \"--no-renames\", \"-z\", commit, \"--\"]);\n  if (tracked.spawnError !== undefined || tracked.code !== 0 || tracked.overflowed) {\n    return { detail: tracked.overflowed ? \"the changed-path listing exceeded the output cap.\" : declineDetail(tracked) };\n  }\n  const untracked = await gitText(docsDir, [\"ls-files\", \"--others\", \"--exclude-standard\", \"--full-name\", \"-z\"]);\n  if (untracked.spawnError !== undefined || untracked.code !== 0 || untracked.overflowed) {\n    return { detail: untracked.overflowed ? \"the untracked-path listing exceeded the output cap.\" : declineDetail(untracked) };\n  }\n  const seen = new Set<string>();\n  for (const raw of [...tracked.out.split(\"\\0\"), ...untracked.out.split(\"\\0\")]) {\n    // A docs repo checked out as a subdirectory of a larger repository answers\n    // in the whole repository's paths; anything outside the docs dir is\n    // somebody else's change and is not a target here.\n    if (raw === \"\" || !raw.startsWith(prefix)) continue;\n    const rel = raw.slice(prefix.length);\n    if (rel !== \"\") seen.add(rel);\n  }\n  return [...seen].sort();\n}\n\n/**\n * Is `path` inside `dir`? Both docs-relative, forward-slashed.\n *\n * A prefix test on the directory plus a separator, never a split on \"/\" and a\n * read of the second segment: a service filed under a subsystem lives at\n * `services/platform/payment-service/`, not at `services/<id>/`, and a\n * path-splitting implementation drops every filed service out of scope\n * SILENTLY — the run stays green because it graded nothing, which is the exact\n * failure this flag is not allowed to have. The separator is what stops\n * `services/pay` from claiming `services/payments/spec.md`.\n */\nfunction inside(path: string, dir: string): boolean {\n  return dir !== \"\" && (path === dir || path.startsWith(`${dir}/`));\n}\n\n/** The fleet's own documents — the landscape target's subject, which owns no service directory. */\nconst ARCHITECTURE_DIR = \"architecture\";\n\n/**\n * Narrow a `--all` run to what changed since `ref`.\n *\n * Targets are matched through the ENUMERATIONS' own directories\n * (`ServiceEntry.dir`, `FeatureEntry.dir`), turned docs-relative by the same\n * `repoPath` the JSON contract uses. That is the whole reason the enumerations\n * are passed in rather than re-derived: they already know where each service\n * sits, at whatever depth, and asking them is what makes a filed fleet work.\n */\nexport async function scopeSince(request: ScopeRequest): Promise<ScopeOutcome> {\n  const { docsDir, ref } = request;\n  const base = await resolveBase(docsDir, ref);\n  if (base.kind === \"no-git\") {\n    return {\n      kind: \"refused\",\n      code: \"repository-unavailable\",\n      message:\n        `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +\n        `--base narrows the run to what changed since a ref, which it reads with read-only git questions ` +\n        `(rev-parse/diff/ls-files). Clone the docs repo with its history, then re-run — or drop --base to grade every target.`,\n    };\n  }\n  if (base.kind === \"no-ref\") {\n    return {\n      kind: \"refused\",\n      code: \"unknown-target\",\n      message:\n        `--base ${ref} does not resolve to a commit in the docs repo at ${docsDir}` +\n        `${base.detail === \"\" ? \"\" : ` (${base.detail})`}. ` +\n        `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`,\n    };\n  }\n\n  const changed = await changedPaths(docsDir, base.commit, base.prefix);\n  if (!Array.isArray(changed)) {\n    // Git resolved the ref and then would not say what moved. There is no\n    // partial answer to give: a scope built from half an answer grades a\n    // subset nobody chose and reports it as the branch's whole footprint.\n    return {\n      kind: \"refused\",\n      code: \"repository-unavailable\",\n      message:\n        `git could not list what changed since ${ref} in the docs repo at ${docsDir} (${changed.detail}) — ` +\n        `without that list there is no honest scope, and a run over a guessed subset would report a green ` +\n        `for targets nobody graded. Re-run once git can answer, or drop --base to grade every target.`,\n    };\n  }\n\n  const dirOf = (abs: string): string => repoPath(docsDir, abs);\n  return {\n    kind: \"scope\",\n    ref,\n    commit: base.commit,\n    // `architecture/` is the landscape target's whole directory: the fleet map,\n    // the permission/capability/obligation vocabularies and the fleet ADRs all\n    // live there, and every one of them is graded by the landscape target\n    // rather than by any service.\n    landscape: changed.some((path) => inside(path, ARCHITECTURE_DIR)),\n    services: request.services.filter((svc) => changed.some((path) => inside(path, dirOf(svc.dir)))),\n    features: request.features.filter((feat) => changed.some((path) => inside(path, dirOf(feat.dir)))),\n    totals: { services: request.services.length, features: request.features.length },\n  };\n}\n\n/**\n * The `scope` object the `--json` payload carries — the run saying out loud\n * what it looked at.\n *\n * Additive, and emitted only under `--base`, so no consumer of today's payload\n * moves. It exists because the alternative is a payload that is byte-shaped\n * like a whole-fleet run and is not one: `summary.services` would report two\n * where the fleet has twelve, `valid: true` would read as a claim about the\n * fleet, and nothing in the document would say otherwise.\n */\nexport function scopeJson(scope: ValidateScope): Record<string, unknown> {\n  return {\n    base: scope.ref,\n    commit: scope.commit,\n    landscape: scope.landscape,\n    services: scope.services.map((svc) => svc.id),\n    features: scope.features.map((feat) => feat.id),\n    totals: scope.totals,\n  };\n}\n\n/**\n * The one line both the text view and a reader of a CI log need: how much of\n * the fleet this run actually graded, and against what.\n *\n * The \"nothing was graded\" clause is the load-bearing half. A `--base` run with\n * no targets in scope has nothing to report and exits 0 — correctly, the branch\n * touched no governed boundary — and a 0 that reads like a green over the\n * system is the exact failure the docs-repo readiness gate exists to prevent.\n * So the sentence says it, rather than letting an empty report say nothing.\n */\nexport function scopeLine(scope: ValidateScope): string {\n  const graded = scope.services.length + scope.features.length + (scope.landscape ? 1 : 0);\n  return (\n    `${scope.services.length} of ${scope.totals.services} services, ` +\n    `${scope.features.length} of ${scope.totals.features} features in scope since ${scope.ref}` +\n    (scope.landscape ? \", plus the landscape\" : \"\") +\n    (graded === 0 ? \" — nothing was graded\" : \"\")\n  );\n}\n"]}
+{"version":3,"file":"changed-paths.js","sourceRoot":"","sources":["../../../../src/core/diff/scope/changed-paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which targets a base git ref puts in scope — the narrowing behind\n * `loam validate --all --base <ref>`.\n *\n * The defect this exists for: a partly-adopted fleet has no CI setting that is\n * both passing today and tightening over time. `--all` is green over eleven\n * undocumented services (they warn, and warnings do not gate) and `--strict` is\n * red from the first minute of adoption until the last boundary is written, so\n * a team installs either a gate that never notices adoption stalling at 8% or\n * one it cannot turn on. `--base` is the third setting: grade what this branch\n * TOUCHED, at full `--strict` severity if the caller wants it, and let the\n * untouched majority stay untouched.\n *\n * A SUB-PACKAGE of `core/diff/` rather than a sixth file in it, because that\n * directory is at the five-file limit and because this is a different subject\n * from the semantic diff beside it: `diff` compares two states of the fleet and\n * reports what moved, this one only decides WHICH SUBJECTS a run should look\n * at. Nothing here reads a document; the one question that has to — which call\n * edges on the fleet map are this branch's — is `./edges.ts`'s, and it reads\n * only the map documents the branch changed.\n *\n * What it does NOT do, and the line is not negotiable: a diff-scoped validate\n * cannot see a victim boundary the change did not touch. Removing an operation\n * from `payment-service` puts `payment-service` in scope and leaves\n * `checkout-web` — whose living requirement still names the operation — out of\n * it. That join is `loam diff --base`'s question and it stays `loam diff`'s;\n * the two gates answer \"did you document what you touched\" and \"did you break a\n * consumer\", and neither substitutes for the other. Selling a green here that\n * hides a broken join would be worse than shipping no flag at all.\n *\n * A join the branch WROTE is a different case, and it is graded: an edge the\n * branch added or edited on the fleet map is checked against its provider's\n * contract even with the provider out of scope (`edges` below), because the\n * edge is the document this branch touched and the provider is only where its\n * answer lives.\n */\nimport { declineDetail, gitText } from \"../../provenance/git.js\";\nimport { repoPath, type ErrorCode } from \"../../envelope/json.js\";\nimport { resolveBase } from \"../base-git.js\";\nimport { edgesSince } from \"./edges.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\nimport type { FeatureEntry, ServiceEntry } from \"../../repo/entries.js\";\n\n/** Everything the narrowing needs: where to ask, what to ask about, and what there is to narrow. */\nexport interface ScopeRequest {\n  docsDir: DocsDir;\n  /** The ref as the caller spelled it — echoed in every message and in the payload. */\n  ref: string;\n  /** The run's full service enumeration, at whatever depth the tree walk found each one. */\n  services: readonly ServiceEntry[];\n  /** The run's full ACTIVE feature enumeration. */\n  features: readonly FeatureEntry[];\n}\n\n/** The narrowed run: which targets the branch touched, and what it narrowed from. */\nexport interface ValidateScope {\n  kind: \"scope\";\n  ref: string;\n  /** The 40-hex commit `ref` resolved to — what a rerun would have to pass to reproduce this scope. */\n  commit: string;\n  /** Did `architecture/` change? The landscape target is the fleet's own subject and has no directory of its own. */\n  landscape: boolean;\n  /**\n   * Every docs-relative path that differs from the base, untracked files\n   * included. Kept because the landscape target grades more files than the\n   * map — the fleet vocabularies, AGENTS.md — and `touched` is how the run asks\n   * which of them this branch changed.\n   */\n  changed: readonly string[];\n  /**\n   * The fleet-map call edges this branch introduced or changed, as\n   * `./edges.ts`'s `edgeKey`s. Empty unless `architecture/` changed.\n   */\n  edges: ReadonlySet<string>;\n  services: ServiceEntry[];\n  features: FeatureEntry[];\n  /** The denominators — what the run would have graded without `--base`. */\n  totals: { services: number; features: number };\n}\n\n/**\n * A refusal, already spelled. The code is one `loam diff` already emits for the\n * same two conditions and the message is in the same register, deliberately: a\n * second stable code for \"that ref does not resolve\" would be a second thing to\n * document, branch on and keep in step, for a condition that is identical.\n *\n * The prose is built here rather than in the command because it is the same\n * sentence for every caller and because `base-git.ts`'s `detail` — git's own\n * words, bounded — is what makes it diagnosable; a command that only received a\n * `kind` would have to reinvent the sentence to say why.\n */\nexport interface ScopeRefusal {\n  kind: \"refused\";\n  code: ErrorCode;\n  message: string;\n}\n\nexport type ScopeOutcome = ValidateScope | ScopeRefusal;\n\n/**\n * Every path that differs between `ref` and the WORKING TREE, docs-relative.\n *\n * Two questions, not one, and the second is not optional: `git diff` compares\n * the tree git tracks, so a service adopted five minutes ago — a brand new\n * `services/<id>/spec.md` nobody has committed — is invisible to it. `validate`\n * grades the working tree, so the scope has to be the working tree's, and an\n * untracked new boundary that the run then skipped would be the flag's very\n * first user reporting that it graded nothing.\n *\n * `--no-renames` on purpose: with rename detection on (git's default since\n * 2.9) a service moved into a subsystem reports only its DESTINATION, and the\n * checks that grade the fleet from the old placement would be out of scope.\n * Two paths for a move is the honest answer.\n *\n * `-z` because git quotes non-ASCII and space-bearing paths in line output —\n * the same reason `gitTrackedFiles` asks that way, and the same phantom\n * directory named `\"src` if it did not.\n */\nasync function changedPaths(docsDir: DocsDir, commit: string, prefix: string): Promise<string[] | { detail: string }> {\n  // Both run from docsDir. `git diff` ignores cwd and answers for the whole\n  // repository with root-relative paths; `git ls-files` restricts itself to\n  // cwd, and `--full-name` makes ITS paths root-relative too — so one prefix\n  // strip below is correct for both, exactly as `listBaseTree` needs one.\n  const tracked = await gitText(docsDir, [\"diff\", \"--name-only\", \"--no-renames\", \"-z\", commit, \"--\"]);\n  if (tracked.spawnError !== undefined || tracked.code !== 0 || tracked.overflowed) {\n    return { detail: tracked.overflowed ? \"the changed-path listing exceeded the output cap.\" : declineDetail(tracked) };\n  }\n  const untracked = await gitText(docsDir, [\"ls-files\", \"--others\", \"--exclude-standard\", \"--full-name\", \"-z\"]);\n  if (untracked.spawnError !== undefined || untracked.code !== 0 || untracked.overflowed) {\n    return { detail: untracked.overflowed ? \"the untracked-path listing exceeded the output cap.\" : declineDetail(untracked) };\n  }\n  const seen = new Set<string>();\n  for (const raw of [...tracked.out.split(\"\\0\"), ...untracked.out.split(\"\\0\")]) {\n    // A docs repo checked out as a subdirectory of a larger repository answers\n    // in the whole repository's paths; anything outside the docs dir is\n    // somebody else's change and is not a target here.\n    if (raw === \"\" || !raw.startsWith(prefix)) continue;\n    const rel = raw.slice(prefix.length);\n    if (rel !== \"\") seen.add(rel);\n  }\n  return [...seen].sort();\n}\n\n/**\n * Is `path` inside `dir`? Both docs-relative, forward-slashed.\n *\n * A prefix test on the directory plus a separator, never a split on \"/\" and a\n * read of the second segment: a service filed under a subsystem lives at\n * `services/platform/payment-service/`, not at `services/<id>/`, and a\n * path-splitting implementation drops every filed service out of scope\n * SILENTLY — the run stays green because it graded nothing, which is the exact\n * failure this flag is not allowed to have. The separator is what stops\n * `services/pay` from claiming `services/payments/spec.md`.\n */\nfunction inside(path: string, dir: string): boolean {\n  return dir !== \"\" && (path === dir || path.startsWith(`${dir}/`));\n}\n\n/** Did this branch change `rel` — a docs-relative file, or anything under a docs-relative directory? */\nexport function touched(scope: ValidateScope, rel: string): boolean {\n  return scope.changed.some((path) => inside(path, rel));\n}\n\n/** The fleet's own documents — the landscape target's subject, which owns no service directory. */\nconst ARCHITECTURE_DIR = \"architecture\";\n\n/**\n * Narrow a `--all` run to what changed since `ref`.\n *\n * Targets are matched through the ENUMERATIONS' own directories\n * (`ServiceEntry.dir`, `FeatureEntry.dir`), turned docs-relative by the same\n * `repoPath` the JSON contract uses. That is the whole reason the enumerations\n * are passed in rather than re-derived: they already know where each service\n * sits, at whatever depth, and asking them is what makes a filed fleet work.\n */\nexport async function scopeSince(request: ScopeRequest): Promise<ScopeOutcome> {\n  const { docsDir, ref } = request;\n  const base = await resolveBase(docsDir, ref);\n  if (base.kind === \"no-git\") {\n    return {\n      kind: \"refused\",\n      code: \"repository-unavailable\",\n      message:\n        `The docs repo at ${docsDir} is not somewhere git can answer from (${base.detail}) — ` +\n        `--base narrows the run to what changed since a ref, which it reads with read-only git questions ` +\n        `(rev-parse/diff/ls-files). Clone the docs repo with its history, then re-run — or drop --base to grade every target.`,\n    };\n  }\n  if (base.kind === \"no-ref\") {\n    return {\n      kind: \"refused\",\n      code: \"unknown-target\",\n      message:\n        `--base ${ref} does not resolve to a commit in the docs repo at ${docsDir}` +\n        `${base.detail === \"\" ? \"\" : ` (${base.detail})`}. ` +\n        `Pass a ref that exists there — main, origin/main, a tag or a commit sha — fetching first if it lives on the remote.`,\n    };\n  }\n\n  const changed = await changedPaths(docsDir, base.commit, base.prefix);\n  if (!Array.isArray(changed)) {\n    // Git resolved the ref and then would not say what moved. There is no\n    // partial answer to give: a scope built from half an answer grades a\n    // subset nobody chose and reports it as the branch's whole footprint.\n    return {\n      kind: \"refused\",\n      code: \"repository-unavailable\",\n      message:\n        `git could not list what changed since ${ref} in the docs repo at ${docsDir} (${changed.detail}) — ` +\n        `without that list there is no honest scope, and a run over a guessed subset would report a green ` +\n        `for targets nobody graded. Re-run once git can answer, or drop --base to grade every target.`,\n    };\n  }\n\n  const dirOf = (abs: string): string => repoPath(docsDir, abs);\n  // `architecture/` is the landscape target's whole directory: the fleet map,\n  // the permission/capability/obligation vocabularies and the fleet ADRs all\n  // live there, and every one of them is graded by the landscape target\n  // rather than by any service.\n  const architecture = changed.filter((path) => inside(path, ARCHITECTURE_DIR));\n  return {\n    kind: \"scope\",\n    ref,\n    commit: base.commit,\n    landscape: architecture.length > 0,\n    changed,\n    edges: await edgesSince(\n      { docsDir, commit: base.commit, prefix: base.prefix },\n      architecture.filter((path) => path.endsWith(\".likec4\")),\n    ),\n    services: request.services.filter((svc) => changed.some((path) => inside(path, dirOf(svc.dir)))),\n    features: request.features.filter((feat) => changed.some((path) => inside(path, dirOf(feat.dir)))),\n    totals: { services: request.services.length, features: request.features.length },\n  };\n}\n\n/**\n * The `scope` object the `--json` payload carries — the run saying out loud\n * what it looked at.\n *\n * Additive, and emitted only under `--base`, so no consumer of today's payload\n * moves. It exists because the alternative is a payload that is byte-shaped\n * like a whole-fleet run and is not one: `summary.services` would report two\n * where the fleet has twelve, `valid: true` would read as a claim about the\n * fleet, and nothing in the document would say otherwise.\n */\nexport function scopeJson(scope: ValidateScope): Record<string, unknown> {\n  return {\n    base: scope.ref,\n    commit: scope.commit,\n    landscape: scope.landscape,\n    services: scope.services.map((svc) => svc.id),\n    features: scope.features.map((feat) => feat.id),\n    totals: scope.totals,\n  };\n}\n\n/**\n * The one line both the text view and a reader of a CI log need: how much of\n * the fleet this run actually graded, and against what.\n *\n * The \"nothing was graded\" clause is the load-bearing half. A `--base` run with\n * no targets in scope has nothing to report and exits 0 — correctly, the branch\n * touched no governed boundary — and a 0 that reads like a green over the\n * system is the exact failure the docs-repo readiness gate exists to prevent.\n * So the sentence says it, rather than letting an empty report say nothing.\n */\nexport function scopeLine(scope: ValidateScope): string {\n  const graded = scope.services.length + scope.features.length + (scope.landscape ? 1 : 0);\n  return (\n    `${scope.services.length} of ${scope.totals.services} services, ` +\n    `${scope.features.length} of ${scope.totals.features} features in scope since ${scope.ref}` +\n    (scope.landscape ? \", plus the landscape\" : \"\") +\n    (graded === 0 ? \" — nothing was graded\" : \"\")\n  );\n}\n"]}

package/dist/core/diff/scope/edges.js

@@ -0,0 +1,82 @@
+/**
+ * Which fleet-map call edges a branch introduced — the one half of the `--base`
+ * narrowing that reads a document.
+ *
+ * The defect this exists for: `spine.op-undefined` is graded on the PROVIDER's
+ * service target, and an `architecture/` change only ever put the landscape in
+ * scope. So the hand edit the spine-first path is built on — naming the
+ * operation on a call edge — was graded by no gate a PR runs: README's own
+ * one-letter example (`authorisePayment` against a contract spelling it
+ * `authorizePayment`) merged green through `loam diff --base` and through
+ * `validate --all --base --strict`, on the adopted example fleet and on a
+ * freshly seeded one alike. This module answers the question that grade needs
+ * — which edges are this branch's — and `commands/validate/scope.ts` grades
+ * exactly those against their providers' contracts.
+ *
+ * AN EDGE IS ITS (source, target, op) TUPLE. A tuple present now and absent at
+ * the base is new or changed — a new edge, a re-pointed one, a renamed
+ * endpoint, an op named or re-spelled — and every one of those is a join the
+ * branch wrote. A tuple present at both ends is not, wherever in the file it
+ * moved and however it was re-indented: the key is what the edge MEANS, so a
+ * reformat grades nothing.
+ *
+ * TEXT, NOT A PARSE, at both ends. The base side would otherwise need a second
+ * LikeC4 workspace over bytes read out of git — the most expensive thing loam
+ * does, paid on every map PR to answer a question about a handful of lines.
+ * `scanModel` is the archive's splice map and resolves endpoints the way LikeC4
+ * does; `test/likec4-scan-parity.test.ts` pins the two readings together, and
+ * the key below is built from the same three fields the parsed `Rel` carries, so
+ * a scanned key names the edge the parsed map holds.
+ *
+ * ONLY THE DOCUMENTS THAT CHANGED are read, at both ends: an edge in an
+ * untouched document is by construction not this branch's, and an edge moved
+ * between two documents changes both, so its base key is still read.
+ *
+ * Which way a failure falls, and why: a base document git will not show — new
+ * on this branch, or a git that declines — contributes no base keys, so every
+ * edge in it reads as new and is graded. Grading an edge the branch did not
+ * write costs a reader one finding; skipping one it did write is the green this
+ * module exists to remove.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { scanModel } from "../../c4/source-scan.js";
+import { inOrder } from "../../kernel/concurrency.js";
+import { showBaseFile } from "../base-git.js";
+/**
+ * One edge's identity as a string a `Set` can hold. JSON rather than a joined
+ * string because an element id may legally carry any separator a join would
+ * pick, and two different tuples must never spell one key.
+ */
+export function edgeKey(edge) {
+    return JSON.stringify([edge.source, edge.target, edge.op ?? null]);
+}
+function keysOf(text) {
+    return text === null ? [] : (scanModel(text)?.rels ?? []).map(edgeKey);
+}
+/** The document as the base commit held it, or null when git will not show it (see the banner for why that is safe). */
+async function baseText(base, rel) {
+    const read = await showBaseFile(base, rel);
+    return read.kind === "ok" ? read.bytes.toString("utf8") : null;
+}
+/** The document as the working tree holds it, or null when the branch deleted it. */
+async function currentText(base, rel) {
+    const abs = join(base.docsDir, rel);
+    return existsSync(abs) ? readFile(abs, "utf8") : null;
+}
+/**
+ * The `edgeKey`s of every edge `documents` hold now and did not hold at the
+ * base. `documents` are docs-relative `.likec4` paths the branch changed —
+ * the caller's filter, so this module never has to know which directory the
+ * fleet map lives in.
+ */
+export async function edgesSince(base, documents) {
+    const sides = await inOrder(documents, async (rel) => {
+        const [before, after] = await Promise.all([baseText(base, rel), currentText(base, rel)]);
+        return { before: keysOf(before), after: keysOf(after) };
+    });
+    const before = new Set(sides.flatMap((side) => side.before));
+    return new Set(sides.flatMap((side) => side.after).filter((key) => !before.has(key)));
+}
+//# sourceMappingURL=edges.js.map

package/dist/core/diff/scope/edges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edges.js","sourceRoot":"","sources":["../../../../src/core/diff/scope/edges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACtD,OAAO,EAAE,YAAY,EAAqB,MAAM,gBAAgB,CAAC;AASjE;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,IAAe;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,MAAM,CAAC,IAAmB;IACjC,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACzE,CAAC;AAED,wHAAwH;AACxH,KAAK,UAAU,QAAQ,CAAC,IAAkB,EAAE,GAAW;IACrD,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3C,OAAO,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC;AAED,qFAAqF;AACrF,KAAK,UAAU,WAAW,CAAC,IAAkB,EAAE,GAAW;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACpC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAkB,EAAE,SAA4B;IAC/E,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QACnD,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QACzF,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1D,CAAC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACxF,CAAC","sourcesContent":["/**\n * Which fleet-map call edges a branch introduced — the one half of the `--base`\n * narrowing that reads a document.\n *\n * The defect this exists for: `spine.op-undefined` is graded on the PROVIDER's\n * service target, and an `architecture/` change only ever put the landscape in\n * scope. So the hand edit the spine-first path is built on — naming the\n * operation on a call edge — was graded by no gate a PR runs: README's own\n * one-letter example (`authorisePayment` against a contract spelling it\n * `authorizePayment`) merged green through `loam diff --base` and through\n * `validate --all --base --strict`, on the adopted example fleet and on a\n * freshly seeded one alike. This module answers the question that grade needs\n * — which edges are this branch's — and `commands/validate/scope.ts` grades\n * exactly those against their providers' contracts.\n *\n * AN EDGE IS ITS (source, target, op) TUPLE. A tuple present now and absent at\n * the base is new or changed — a new edge, a re-pointed one, a renamed\n * endpoint, an op named or re-spelled — and every one of those is a join the\n * branch wrote. A tuple present at both ends is not, wherever in the file it\n * moved and however it was re-indented: the key is what the edge MEANS, so a\n * reformat grades nothing.\n *\n * TEXT, NOT A PARSE, at both ends. The base side would otherwise need a second\n * LikeC4 workspace over bytes read out of git — the most expensive thing loam\n * does, paid on every map PR to answer a question about a handful of lines.\n * `scanModel` is the archive's splice map and resolves endpoints the way LikeC4\n * does; `test/likec4-scan-parity.test.ts` pins the two readings together, and\n * the key below is built from the same three fields the parsed `Rel` carries, so\n * a scanned key names the edge the parsed map holds.\n *\n * ONLY THE DOCUMENTS THAT CHANGED are read, at both ends: an edge in an\n * untouched document is by construction not this branch's, and an edge moved\n * between two documents changes both, so its base key is still read.\n *\n * Which way a failure falls, and why: a base document git will not show — new\n * on this branch, or a git that declines — contributes no base keys, so every\n * edge in it reads as new and is graded. Grading an edge the branch did not\n * write costs a reader one finding; skipping one it did write is the green this\n * module exists to remove.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { scanModel } from \"../../c4/source-scan.js\";\nimport { inOrder } from \"../../kernel/concurrency.js\";\nimport { showBaseFile, type ResolvedBase } from \"../base-git.js\";\n\n/** The fields of an edge that make it the same join — shared by a parsed `Rel` and a scanned one. */\ninterface EdgeTuple {\n  source: string;\n  target: string;\n  op?: string;\n}\n\n/**\n * One edge's identity as a string a `Set` can hold. JSON rather than a joined\n * string because an element id may legally carry any separator a join would\n * pick, and two different tuples must never spell one key.\n */\nexport function edgeKey(edge: EdgeTuple): string {\n  return JSON.stringify([edge.source, edge.target, edge.op ?? null]);\n}\n\nfunction keysOf(text: string | null): string[] {\n  return text === null ? [] : (scanModel(text)?.rels ?? []).map(edgeKey);\n}\n\n/** The document as the base commit held it, or null when git will not show it (see the banner for why that is safe). */\nasync function baseText(base: ResolvedBase, rel: string): Promise<string | null> {\n  const read = await showBaseFile(base, rel);\n  return read.kind === \"ok\" ? read.bytes.toString(\"utf8\") : null;\n}\n\n/** The document as the working tree holds it, or null when the branch deleted it. */\nasync function currentText(base: ResolvedBase, rel: string): Promise<string | null> {\n  const abs = join(base.docsDir, rel);\n  return existsSync(abs) ? readFile(abs, \"utf8\") : null;\n}\n\n/**\n * The `edgeKey`s of every edge `documents` hold now and did not hold at the\n * base. `documents` are docs-relative `.likec4` paths the branch changed —\n * the caller's filter, so this module never has to know which directory the\n * fleet map lives in.\n */\nexport async function edgesSince(base: ResolvedBase, documents: readonly string[]): Promise<ReadonlySet<string>> {\n  const sides = await inOrder(documents, async (rel) => {\n    const [before, after] = await Promise.all([baseText(base, rel), currentText(base, rel)]);\n    return { before: keysOf(before), after: keysOf(after) };\n  });\n  const before = new Set(sides.flatMap((side) => side.before));\n  return new Set(sides.flatMap((side) => side.after).filter((key) => !before.has(key)));\n}\n"]}

package/dist/core/diff/semantic.js

@@ -1,21 +1,30 @@
 /**
  * The diff computation: join the base fleet (`./base-state.ts`) against the
- * working tree (`./current-state.ts`) and say, per service, what changed in
+ * working tree (`core/consumers/current.ts`) and say, per service, what changed in
  * FLEET-MEANINGFUL terms — requirements by identity and digest, operations
- * and messages by their join tokens, cross-service joins by tuple — with the
- * current consumers of every removal named (`./victims.ts`).
+ * and messages by their join tokens and their `$ref`-closure digests,
+ * cross-service joins by tuple — with the authored consumers of every
+ * removal, deprecation and modification named (`core/consumers/consumers.ts`),
+ * and the cross-service joins that appeared or went away (`./joins.ts`).
  *
  * Two disciplines rule every branch here. Removal is graded against who still
  * depends on it: a removal nobody names is a warning, a removal the fleet
- * still joins to is an error and sets `breaking`. And "nobody could look" is
+ * still joins to is an error and sets `breaking`. A MODIFICATION is never an
+ * error, whoever is joined to it: whether a changed schema breaks its readers
+ * is a field-level question loam hands to oasdiff on purpose, so the finding
+ * names the consumers and the tool, and stops there. And "nobody could look" is
  * never "nothing changed": an unreadable artifact on EITHER side suspends
  * that subject's axis — recorded in `unreadable[]`, counted in the summary,
  * carried into the exit code by the command — instead of letting an
  * unreadable base read as everything-added or an unreadable working file
- * read as everything-removed.
+ * read as everything-removed. The one thing that is not a suspension is a
+ * contract the base held byte-for-byte: somebody COULD look, at the bytes,
+ * and they did not change (`comparable`, `UNTOUCHED_SKIPS`).
  */
 import { requirementDigest } from "../document/spec.js";
-import { consumerJoinChanges } from "./victims.js";
+import { rawServiceId } from "../kernel/ids/service.js";
+import { consumerStance, scanDetails } from "../consumers/scan.js";
+import { consumerJoinChanges } from "./joins.js";
 /** Severity is a fact about the code, not a call-site choice — one table, no drift. */
 const DIFF_SEVERITY = {
     "diff.service-added": "ok",
@@ -27,9 +36,11 @@ const DIFF_SEVERITY = {
     "diff.op-removed": "warn",
     "diff.op-removed-consumed": "error",
     "diff.op-deprecated": "warn",
+    "diff.op-modified": "warn",
     "diff.message-added": "ok",
     "diff.message-removed": "warn",
     "diff.message-removed-consumed": "error",
+    "diff.message-modified": "warn",
     "diff.consumer-added": "ok",
     "diff.consumer-removed": "ok",
 };
@@ -37,15 +48,43 @@ function found(code, message, details) {
     const carry = details !== undefined && details.length > 0;
     return { severity: DIFF_SEVERITY[code], code, message, ...(carry ? { details } : {}) };
 }
-/** A side the service does not exist on: absence everywhere, honestly. */
+/**
+ * A side the service does not exist on: absence everywhere, honestly. The id is
+ * a key of one of the two sides' maps, each keyed by a directory's leaf name.
+ */
 const ABSENT = { kind: "absent" };
-const emptyState = (id) => ({ id, dir: "", spec: ABSENT, archSpec: ABSENT, openapi: ABSENT, asyncapi: ABSENT });
+const emptyState = (id) => ({ id: rawServiceId(id), dir: "", spec: ABSENT, archSpec: ABSENT, openapi: ABSENT, asyncapi: ABSENT });
+/**
+ * The axes on which an unreadable document the branch left byte-identical is
+ * SKIPPED rather than suspended: the two contracts. Identical bytes are a
+ * proof, not a guess — the same parser over the same bytes cannot read
+ * differently on the two sides, so there is nothing of this document's own
+ * to diff, and suspending it anyway made every `loam diff` exit 1 over a
+ * fleet that holds one AsyncAPI 2.x file (unreadable by policy since
+ * core/asyncapi/read.ts refused pre-3.0), whatever the branch changed.
+ *
+ * Not the spec axes, and that is the victims scan's doing, not an oversight:
+ * an unreadable spec.md or arch.spec.md is also the document ANOTHER
+ * service's removal could not be checked against (`core/consumers/consumers.ts`'s
+ * `scanRequirements`), and its `unreadable[]` entry here is what carries that
+ * suspension to exit 1 (`opsDiff`'s removal branch says so). No scan reads a
+ * contract it could not parse as evidence of anything — `producers` takes
+ * positive evidence only — so skipping one hides no other answer.
+ */
+const UNTOUCHED_SKIPS = new Set(["openapi", "asyncapi"]);
 /**
  * Guard one axis pair: record unreadable sides on the sink and say whether
  * the axis may be compared at all. Reading one good side against a suspended
- * one would grade absence it never proved.
+ * one would grade absence it never proved. A contract unreadable on BOTH
+ * sides with one byte hash is the branch's untouched file: not compared and
+ * not recorded either (`UNTOUCHED_SKIPS`). A changed one, or one only one
+ * side cannot read, still suspends.
  */
 function comparable(sink, axis, pair) {
+    const { base, current } = pair;
+    if (UNTOUCHED_SKIPS.has(axis) && base.kind === "unreadable" && current.kind === "unreadable" &&
+        base.bytes !== undefined && base.bytes === current.bytes)
+        return false;
     for (const side of ["base", "current"]) {
         const state = pair[side];
         if (state.kind === "unreadable")
@@ -92,6 +131,13 @@ function requirementsDiff(sink, pair) {
             sink.findings.push(found("diff.requirement-removed", `living requirement removed since base: '${reqLabel(r)}'`));
     }
 }
+/**
+ * The second half of every modification message. loam joins consumers to the
+ * thing that moved; it does not read what a schema SAYS (core/brief/unchecked.ts
+ * lists that as unchecked), so a breaking rename and a new optional field are
+ * the same finding here — the specialist diff tells them apart.
+ */
+const notGraded = (tool) => `loam does not grade whether the change is breaking — run ${tool} on the two states of this contract`;
 async function opsDiff(sink, pair, victims) {
     if (!comparable(sink, "openapi", { base: pair.base.openapi, current: pair.current.openapi }))
         return;
@@ -104,11 +150,17 @@ async function opsDiff(sink, pair, victims) {
         }
         else if (!before.deprecated && op.deprecated) {
             const scan = await victims.opConsumers(sink.id, id);
-            // Three honest phrasings — never a confident negative over a scan that skipped an unreadable consumer document.
-            const stance = scan.victims.length > 0 ? `${scan.victims.length} current consumer(s) still name it`
-                : scan.suspended.length > 0 ? "whether current consumers name it could not be fully answered"
-                    : "no current consumer names it";
-            sink.findings.push(found("diff.op-deprecated", `operation '${id}' is deprecated since base — ${stance}`, [...scan.victims, ...scan.suspended]));
+            sink.findings.push(found("diff.op-deprecated", `operation '${id}' is deprecated since base — ${consumerStance(scan)}`, scanDetails(scan)));
+        }
+        else if (before.closureDigest !== op.closureDigest || before.path !== op.path || before.method !== op.method) {
+            // `else`, because setting the flag moves the digest by itself (it is a
+            // key of the node): a deprecation already names the same consumers, and
+            // a second finding over them would say nothing new. The digest covers
+            // the `$ref` closure — a field renamed in a shared component is exactly
+            // the change this code exists for, and the operation's own bytes never
+            // move for it. A relocated slot is a change too, though the node is not.
+            const scan = await victims.opConsumers(sink.id, id);
+            sink.findings.push(found("diff.op-modified", `operation '${id}' (${op.method.toUpperCase()} ${op.path}) changed since base, in its own definition or a schema it references — ${consumerStance(scan)}; ${notGraded("`oasdiff breaking`")}`, scanDetails(scan)));
         }
     }
     for (const [id] of [...base].sort(byKey)) {
@@ -116,16 +168,18 @@ async function opsDiff(sink, pair, victims) {
             continue;
         const scan = await victims.opConsumers(sink.id, id);
         if (scan.victims.length > 0) {
-            sink.findings.push(found("diff.op-removed-consumed", `operation '${id}' was removed since base and the current fleet still names it — these joins break`, [...scan.victims, ...scan.suspended]));
+            sink.findings.push(found("diff.op-removed-consumed", `operation '${id}' was removed since base and the current fleet still names it — these joins break`, scanDetails(scan)));
         }
         else if (scan.suspended.length > 0) {
-            // "Nobody could be scanned" is not "nobody names it" — the consumer's own
-            // unreadable[] entry already carries the run to exit 1; this message must
-            // not assert a negative the scan never proved.
-            sink.findings.push(found("diff.op-removed", `operation '${id}' was removed since base; whether the current fleet still names it could NOT be fully answered — ${scan.suspended.length} consumer document(s) were not scannable`, scan.suspended));
+            // "Nobody could be checked" is not "nobody names it", so this message
+            // must not assert a negative the scan never proved. An unreadable
+            // consumer document carries the run to exit 1 through its own
+            // unreadable[] entry; a caller drawn with no op does not — it stays this
+            // warning, so a seeded, op-less map does not fail every removal.
+            sink.findings.push(found("diff.op-removed", `operation '${id}' was removed since base; whether the current fleet still names it could NOT be fully answered — ${scan.suspended.length} possible consumer(s) could not be checked`, scanDetails(scan)));
         }
         else {
-            sink.findings.push(found("diff.op-removed", `operation '${id}' was removed since base; no current landscape edge or living requirement names it`));
+            sink.findings.push(found("diff.op-removed", `operation '${id}' was removed since base; no current edge, requirement or use-case hop names it`));
         }
     }
 }
@@ -134,33 +188,46 @@ async function messagesDiff(sink, pair, victims) {
         return;
     const base = firstWins(valueOr(pair.base.asyncapi), (m) => m.name);
     const current = firstWins(valueOr(pair.current.asyncapi), (m) => m.name);
-    for (const [name] of [...current].sort(byKey)) {
-        if (!base.has(name))
+    for (const [name, message] of [...current].sort(byKey)) {
+        const before = base.get(name);
+        if (before === undefined) {
             sink.findings.push(found("diff.message-added", `message '${name}' added since base`));
+        }
+        else if (before.closureDigest !== message.closureDigest) {
+            const scan = await victims.messageConsumers(sink.id, name);
+            sink.findings.push(found("diff.message-modified", `message '${name}' changed since base, in its declaration or a schema its payload references — ${consumerStance(scan)}; ${notGraded("`asyncapi diff`")}`, scanDetails(scan)));
+        }
     }
     for (const [name] of [...base].sort(byKey)) {
         if (current.has(name))
             continue;
-        // Fleet-global join: a name another current service still declares is not
-        // orphaned (positive evidence only — an unreadable contract never vouches).
-        const elsewhere = victims.declarers(name).filter((d) => d !== sink.id);
-        if (elsewhere.length > 0) {
-            sink.findings.push(found("diff.message-removed", `message '${name}' was removed since base; still declared by ${elsewhere.join(", ")}`));
+        // Fleet-global join: a name another current service still SENDS is not
+        // orphaned (positive evidence only — an unreadable contract never vouches,
+        // and a service that only receives it is one of its consumers, never its
+        // producer: `producers` says why that distinction is the gate's too). Nor
+        // is one an #external element still publishes, by validate's own rule
+        // (`externalProducer` says why): counting the fleet's senders alone made
+        // this removal an error that the next `validate --all` called clean.
+        const elsewhere = (await victims.producers(name)).filter((d) => d !== sink.id);
+        const outside = await victims.externalProducer(name);
+        const senders = outside === null ? elsewhere : [...elsewhere, `${outside} (#external)`];
+        if (senders.length > 0) {
+            sink.findings.push(found("diff.message-removed", `message '${name}' was removed since base; still sent by ${senders.join(", ")}`));
             continue;
         }
         const scan = await victims.messageConsumers(sink.id, name);
         if (scan.victims.length > 0) {
-            sink.findings.push(found("diff.message-removed-consumed", `message '${name}' was removed since base and the current fleet still consumes it — these joins break`, [...scan.victims, ...scan.suspended]));
+            sink.findings.push(found("diff.message-removed-consumed", `message '${name}' was removed since base and the current fleet still consumes it — these joins break`, scanDetails(scan)));
         }
         else if (scan.suspended.length > 0) {
-            sink.findings.push(found("diff.message-removed", `message '${name}' was removed since base; whether anything still consumes it could NOT be fully answered — ${scan.suspended.length} consumer document(s) were not scannable`, scan.suspended));
+            sink.findings.push(found("diff.message-removed", `message '${name}' was removed since base; whether anything still consumes it could NOT be fully answered — ${scan.suspended.length} consumer document(s) were not scannable`, scanDetails(scan)));
         }
         else {
             sink.findings.push(found("diff.message-removed", `message '${name}' was removed since base; nothing currently consumes it`));
         }
     }
 }
-/** The graded join changes (`victims.ts`) as findings on each PROVIDER — the service whose surface the join lands on. */
+/** The graded join changes (`./joins.ts`) as findings on each PROVIDER — the service whose surface the join lands on. */
 function consumerFindings(input) {
     const changes = consumerJoinChanges({
         base: input.base.services,
@@ -233,7 +300,9 @@ export async function computeDiff(input) {
         summary: {
             added: count((f) => f.code.endsWith("-added")),
             removed: count((f) => f.code.endsWith("-removed") || f.code.endsWith("-removed-consumed")),
-            modified: count((f) => f.code === "diff.requirement-modified"),
+            // Requirements, operations and messages alike: a reader scanning the one
+            // summary line must not see "0 modified" over a PR that renamed a field.
+            modified: count((f) => f.code.endsWith("-modified")),
             deprecated: count((f) => f.code === "diff.op-deprecated"),
             unreadable: services.reduce((n, s) => n + s.unreadable.length, 0) +
                 services.filter((s) => s.ambiguous !== undefined).length,