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

package/dist/commands/validate/service/evidence-pins.js

@@ -0,0 +1,177 @@
+/**
+ * The evidence-pin re-check as validate findings: every ACTIVE feature record
+ * this service has attested, its pins graded against THIS working tree.
+ *
+ * Service-repo-scoped like `sources.*` and the gherkin chain — the citations
+ * resolve only inside the service's own repository. From the docs repo this
+ * TARGET is silent by design: every pin would grade `unresolved` there, which
+ * would be a lie about the code rather than about the record, and
+ * `sources.unverifiable-from-here` already names the blind spot once per
+ * service. One code of the family is not about the code at all —
+ * `evidence.record-unreadable` is about the record, which lives in the docs
+ * repo — so the FEATURE target (`../feature.ts`) raises it too, from anywhere,
+ * through `featureRecordFindings` below:
+ * with only this target raising it, `validate --all` in the docs repo stayed
+ * green over a conflict-marked record that `verify` refused and `status`,
+ * `gate` and `tasks` all reported. In a service repo's `--all` the same file
+ * is therefore named twice, once per target: here as this service's pins
+ * going unchecked, there as the feature's record itself.
+ *
+ * ARCHIVED records are deliberately not linted (a v1 non-goal, recorded here):
+ * a frozen record is history, post-ship code drift is normal evolution, and
+ * grading it would turn every service's CI permanently yellow the week after
+ * every ship. If audit-time re-checks of shipped records are ever wanted, the
+ * same `lintEvidencePins` call over `listFeatures` include-archived is the
+ * whole change — behind an explicit flag, so the default stays quiet.
+ *
+ * Everything here demotes reviewer confidence only: warns never flip `valid`,
+ * `--strict` may gate on them as it gates on any warning, and no grade ever
+ * moves a verdict — `attested` never silently becomes `verified` and a drifted
+ * pin never un-confirms a claim.
+ */
+import { repoPath } from "../../../core/envelope/json.js";
+import { inOrder } from "../../../core/kernel/concurrency.js";
+import {} from "../../../core/kernel/ids/service.js";
+import {} from "../../../core/repo/entries.js";
+import { listFeatures } from "../../../core/repo/repo.js";
+import { readVerificationState } from "../../../core/verify/read/file.js";
+import { lintEvidencePins } from "../../../core/verify/pins/lint.js";
+import {} from "../../../core/vocabulary/report.js";
+export async function evidencePinFindings(docsDir, service, repoDir, fleet) {
+    if (repoDir === undefined)
+        return [];
+    // Membership questions cross the provenance line through plain strings by
+    // design (kernel/ids/service.ts) — record subjects are document text.
+    const me = service;
+    // ACTIVE features only — see the header for why archived records stay frozen.
+    const features = await listFeatures(docsDir, {}, fleet);
+    const lints = await inOrder(features, async (feature) => {
+        // Three states, graded apart on purpose. ABSENT is a feature nobody has
+        // verified — legitimate silence. UNREADABLE is somebody's record this run
+        // could not use, and it must be a finding here rather than a skip: the
+        // damage that most plausibly breaks a record in a service repo's CI is a
+        // hand edit to the very pins this family grades, and a lint that went
+        // silent over it would turn "someone broke the record" into a green run —
+        // `verify` names the same file `record-unreadable`, but this CI job never
+        // runs verify. An unreadable record also cannot say whether it attests
+        // this service, so the finding fires regardless of attestation.
+        const read = await readVerificationState(feature.dir);
+        if (read.state === "unreadable") {
+            return { feature: feature.id, path: repoPath(docsDir, read.path), unreadable: read.reason, advice: read.advice };
+        }
+        if (read.state === "absent" || read.verification.schema !== 2)
+            return null;
+        if (!(read.verification.attestations ?? []).some((a) => a.service === me))
+            return null;
+        return { feature: feature.id, lint: await lintEvidencePins(read.verification.claims, me, repoDir) };
+    });
+    const findings = [];
+    let checked = 0;
+    let pinnedRecords = 0;
+    let drifted = false;
+    for (const entry of lints) {
+        if (entry === null)
+            continue;
+        if ("unreadable" in entry) {
+            findings.push({
+                severity: "warn",
+                code: "evidence.record-unreadable",
+                subject: service,
+                message: recordUnreadableMessage(`${me}: ${entry.feature}`, entry),
+            });
+            continue;
+        }
+        const { feature, lint } = entry;
+        if (lint.checked > 0 || lint.drifts.length > 0)
+            pinnedRecords += 1;
+        checked += lint.checked;
+        // The code is spelled as a literal at each call below, and the grade rides
+        // beside it rather than being sliced back out of the code string — the
+        // codes-drift collector resolves the `code` slot, and a derivation would
+        // be a second definition of the pairing free to drift from the first.
+        const drift = (grade, code, sentence) => {
+            const drifts = lint.drifts.filter((d) => d.grade === grade);
+            if (drifts.length === 0)
+                return;
+            drifted = true;
+            findings.push({
+                severity: "warn",
+                code,
+                subject: service,
+                message: `${me}: ${feature}: ${drifts.length} recorded evidence pin(s) ${sentence} — ` +
+                    "a reading priority for the reviewer, never a verdict change; re-answer and re-record " +
+                    `(\`loam verify ${feature} --service ${me} --record answers.json\`) once the evidence is re-read`,
+                details: drifts.map(detailLine),
+            });
+        };
+        drift("unresolved", "evidence.unresolved", "cannot be re-checked in this working tree: the cited file is gone, unreadable, not a regular file, or the cited line is past its end");
+        drift("moved", "evidence.moved", "cite a file that changed since the record, though each cited line survives");
+        drift("line-changed", "evidence.line-changed", "cite line(s) that no longer say what was recorded");
+        drift("token-missing", "evidence.token-missing", "cite file(s) that no longer contain the literal string the claim asserts");
+        if (lint.unpinned > 0) {
+            findings.push({
+                severity: "ok",
+                // The pre-content_digest-vouch precedent: a record from before the
+                // capability existed is not wrong, it is unfindable-by-this-check.
+                code: "evidence.unpinned",
+                subject: service,
+                message: `${me}: ${feature}: ${lint.unpinned} agent-confirmed citation(s) carry no evidence pin — ` +
+                    `recorded before pins existed; the next \`loam verify ${feature} --service ${me} --record\` makes them drift-checkable`,
+            });
+        }
+    }
+    if (checked > 0 && !drifted) {
+        findings.push({
+            severity: "ok",
+            code: "evidence.checked",
+            subject: service,
+            message: `${me}: ${checked} evidence pin(s) across ${pinnedRecords} feature record(s) re-checked against this working tree`,
+        });
+    }
+    return findings;
+}
+/**
+ * `evidence.record-unreadable` on the FEATURE target (`../feature.ts`), from
+ * anywhere — the docs repo included, which is where the record lives. Kept
+ * here, beside the service target's emission, so one module owns the code and
+ * its words: the record read is the same `readVerificationState`, the path is
+ * made docs-relative the same way, and the message is the same sentence.
+ * Readability only — an `ok` record contributes nothing here, its verdict is
+ * `verify`'s and `status`'s to state — and a warn for the reasons the header
+ * gives: `valid` and `loam archive` are untouched, `--strict` is the lever.
+ */
+export async function featureRecordFindings(docsDir, feature) {
+    const read = await readVerificationState(feature.dir);
+    if (read.state !== "unreadable")
+        return [];
+    const path = repoPath(docsDir, read.path);
+    return [
+        {
+            severity: "warn",
+            code: "evidence.record-unreadable",
+            message: recordUnreadableMessage(feature.id, { path, unreadable: read.reason, advice: read.advice }),
+            locations: [{ path, role: "primary" }],
+        },
+    ];
+}
+/**
+ * The sentence `evidence.record-unreadable` carries, for both targets that
+ * raise it. Each emission spells the code literally (the codes-drift
+ * collector resolves the `code` slot, as `drift` above says); only the words
+ * are shared, so the two cannot drift into two descriptions of one file.
+ *
+ * The reader's own recipe for the one file that failed, never a fixed one:
+ * "re-record" alone sent this finding's reader into `--record`'s refusal of
+ * the very same file, and the safe repair differs between a service's own
+ * attestation file and the one-file record other services' evidence may sit
+ * in. `path` is docs-relative.
+ */
+function recordUnreadableMessage(label, file) {
+    return (`${label}: ${file.path} exists but cannot be read as a verification record (${file.unreadable}) — ` +
+        `none of its evidence was checked. ${file.advice} loam never overwrites a record it could not read`);
+}
+/** One drift as a detail line: which claim, which citation, what changed. */
+function detailLine(d) {
+    return `${d.claim} ${d.evidence} — ${d.what}`;
+}
+//# sourceMappingURL=evidence-pins.js.map

package/dist/commands/validate/service/evidence-pins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-pins.js","sourceRoot":"","sources":["../../../../src/commands/validate/service/evidence-pins.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The evidence-pin re-check as validate findings: every ACTIVE feature record\n * this service has attested, its pins graded against THIS working tree.\n *\n * Service-repo-scoped like `sources.*` and the gherkin chain — the citations\n * resolve only inside the service's own repository. From the docs repo this\n * TARGET is silent by design: every pin would grade `unresolved` there, which\n * would be a lie about the code rather than about the record, and\n * `sources.unverifiable-from-here` already names the blind spot once per\n * service. One code of the family is not about the code at all —\n * `evidence.record-unreadable` is about the record, which lives in the docs\n * repo — so the FEATURE target (`../feature.ts`) raises it too, from anywhere,\n * through `featureRecordFindings` below:\n * with only this target raising it, `validate --all` in the docs repo stayed\n * green over a conflict-marked record that `verify` refused and `status`,\n * `gate` and `tasks` all reported. In a service repo's `--all` the same file\n * is therefore named twice, once per target: here as this service's pins\n * going unchecked, there as the feature's record itself.\n *\n * ARCHIVED records are deliberately not linted (a v1 non-goal, recorded here):\n * a frozen record is history, post-ship code drift is normal evolution, and\n * grading it would turn every service's CI permanently yellow the week after\n * every ship. If audit-time re-checks of shipped records are ever wanted, the\n * same `lintEvidencePins` call over `listFeatures` include-archived is the\n * whole change — behind an explicit flag, so the default stays quiet.\n *\n * Everything here demotes reviewer confidence only: warns never flip `valid`,\n * `--strict` may gate on them as it gates on any warning, and no grade ever\n * moves a verdict — `attested` never silently becomes `verified` and a drifted\n * pin never un-confirms a claim.\n */\nimport { repoPath } from \"../../../core/envelope/json.js\";\nimport { inOrder } from \"../../../core/kernel/concurrency.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type FeatureEntry } from \"../../../core/repo/entries.js\";\nimport { listFeatures } from \"../../../core/repo/repo.js\";\nimport { readVerificationState } from \"../../../core/verify/read/file.js\";\nimport { lintEvidencePins, type PinDrift, type PinLint } from \"../../../core/verify/pins/lint.js\";\nimport { type Finding } from \"../../../core/vocabulary/report.js\";\nimport type { FleetContext } from \"../../../core/fleet-context.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\n\nexport async function evidencePinFindings(\n  docsDir: DocsDir,\n  service: PathableService,\n  repoDir: string | undefined,\n  fleet: FleetContext,\n): Promise<Finding[]> {\n  if (repoDir === undefined) return [];\n  // Membership questions cross the provenance line through plain strings by\n  // design (kernel/ids/service.ts) — record subjects are document text.\n  const me: string = service;\n  // ACTIVE features only — see the header for why archived records stay frozen.\n  const features = await listFeatures(docsDir, {}, fleet);\n  type Linted =\n    | null\n    | { feature: string; path: string; unreadable: string; advice: string }\n    | { feature: string; lint: PinLint };\n  const lints = await inOrder(features, async (feature): Promise<Linted> => {\n    // Three states, graded apart on purpose. ABSENT is a feature nobody has\n    // verified — legitimate silence. UNREADABLE is somebody's record this run\n    // could not use, and it must be a finding here rather than a skip: the\n    // damage that most plausibly breaks a record in a service repo's CI is a\n    // hand edit to the very pins this family grades, and a lint that went\n    // silent over it would turn \"someone broke the record\" into a green run —\n    // `verify` names the same file `record-unreadable`, but this CI job never\n    // runs verify. An unreadable record also cannot say whether it attests\n    // this service, so the finding fires regardless of attestation.\n    const read = await readVerificationState(feature.dir);\n    if (read.state === \"unreadable\") {\n      return { feature: feature.id, path: repoPath(docsDir, read.path), unreadable: read.reason, advice: read.advice };\n    }\n    if (read.state === \"absent\" || read.verification.schema !== 2) return null;\n    if (!(read.verification.attestations ?? []).some((a) => a.service === me)) return null;\n    return { feature: feature.id, lint: await lintEvidencePins(read.verification.claims, me, repoDir) };\n  });\n\n  const findings: Finding[] = [];\n  let checked = 0;\n  let pinnedRecords = 0;\n  let drifted = false;\n  for (const entry of lints) {\n    if (entry === null) continue;\n    if (\"unreadable\" in entry) {\n      findings.push({\n        severity: \"warn\",\n        code: \"evidence.record-unreadable\",\n        subject: service,\n        message: recordUnreadableMessage(`${me}: ${entry.feature}`, entry),\n      });\n      continue;\n    }\n    const { feature, lint } = entry;\n    if (lint.checked > 0 || lint.drifts.length > 0) pinnedRecords += 1;\n    checked += lint.checked;\n    // The code is spelled as a literal at each call below, and the grade rides\n    // beside it rather than being sliced back out of the code string — the\n    // codes-drift collector resolves the `code` slot, and a derivation would\n    // be a second definition of the pairing free to drift from the first.\n    const drift = (grade: PinDrift[\"grade\"], code: string, sentence: string): void => {\n      const drifts = lint.drifts.filter((d) => d.grade === grade);\n      if (drifts.length === 0) return;\n      drifted = true;\n      findings.push({\n        severity: \"warn\",\n        code,\n        subject: service,\n        message:\n          `${me}: ${feature}: ${drifts.length} recorded evidence pin(s) ${sentence} — ` +\n          \"a reading priority for the reviewer, never a verdict change; re-answer and re-record \" +\n          `(\\`loam verify ${feature} --service ${me} --record answers.json\\`) once the evidence is re-read`,\n        details: drifts.map(detailLine),\n      });\n    };\n    drift(\n      \"unresolved\",\n      \"evidence.unresolved\",\n      \"cannot be re-checked in this working tree: the cited file is gone, unreadable, not a regular file, or the cited line is past its end\",\n    );\n    drift(\"moved\", \"evidence.moved\", \"cite a file that changed since the record, though each cited line survives\");\n    drift(\"line-changed\", \"evidence.line-changed\", \"cite line(s) that no longer say what was recorded\");\n    drift(\n      \"token-missing\",\n      \"evidence.token-missing\",\n      \"cite file(s) that no longer contain the literal string the claim asserts\",\n    );\n    if (lint.unpinned > 0) {\n      findings.push({\n        severity: \"ok\",\n        // The pre-content_digest-vouch precedent: a record from before the\n        // capability existed is not wrong, it is unfindable-by-this-check.\n        code: \"evidence.unpinned\",\n        subject: service,\n        message:\n          `${me}: ${feature}: ${lint.unpinned} agent-confirmed citation(s) carry no evidence pin — ` +\n          `recorded before pins existed; the next \\`loam verify ${feature} --service ${me} --record\\` makes them drift-checkable`,\n      });\n    }\n  }\n  if (checked > 0 && !drifted) {\n    findings.push({\n      severity: \"ok\",\n      code: \"evidence.checked\",\n      subject: service,\n      message: `${me}: ${checked} evidence pin(s) across ${pinnedRecords} feature record(s) re-checked against this working tree`,\n    });\n  }\n  return findings;\n}\n\n/**\n * `evidence.record-unreadable` on the FEATURE target (`../feature.ts`), from\n * anywhere — the docs repo included, which is where the record lives. Kept\n * here, beside the service target's emission, so one module owns the code and\n * its words: the record read is the same `readVerificationState`, the path is\n * made docs-relative the same way, and the message is the same sentence.\n * Readability only — an `ok` record contributes nothing here, its verdict is\n * `verify`'s and `status`'s to state — and a warn for the reasons the header\n * gives: `valid` and `loam archive` are untouched, `--strict` is the lever.\n */\nexport async function featureRecordFindings(docsDir: DocsDir, feature: FeatureEntry): Promise<Finding[]> {\n  const read = await readVerificationState(feature.dir);\n  if (read.state !== \"unreadable\") return [];\n  const path = repoPath(docsDir, read.path);\n  return [\n    {\n      severity: \"warn\",\n      code: \"evidence.record-unreadable\",\n      message: recordUnreadableMessage(feature.id, { path, unreadable: read.reason, advice: read.advice }),\n      locations: [{ path, role: \"primary\" }],\n    },\n  ];\n}\n\n/**\n * The sentence `evidence.record-unreadable` carries, for both targets that\n * raise it. Each emission spells the code literally (the codes-drift\n * collector resolves the `code` slot, as `drift` above says); only the words\n * are shared, so the two cannot drift into two descriptions of one file.\n *\n * The reader's own recipe for the one file that failed, never a fixed one:\n * \"re-record\" alone sent this finding's reader into `--record`'s refusal of\n * the very same file, and the safe repair differs between a service's own\n * attestation file and the one-file record other services' evidence may sit\n * in. `path` is docs-relative.\n */\nfunction recordUnreadableMessage(\n  label: string,\n  file: { path: string; unreadable: string; advice: string },\n): string {\n  return (\n    `${label}: ${file.path} exists but cannot be read as a verification record (${file.unreadable}) — ` +\n    `none of its evidence was checked. ${file.advice} loam never overwrites a record it could not read`\n  );\n}\n\n/** One drift as a detail line: which claim, which citation, what changed. */\nfunction detailLine(d: PinDrift): string {\n  return `${d.claim} ${d.evidence} — ${d.what}`;\n}\n"]}

package/dist/commands/validate/service/model/diverged.js

@@ -0,0 +1,226 @@
+import { ARTIFACT_FILES } from "../../../../core/repo/paths.js";
+import { serviceLevelElements } from "../../fleet/census.js";
+/**
+ * How the OTHER declaration is named.
+ *
+ * The document, not the file: `Elem` carries no source path, and the map is a
+ * PROJECT — `architecture/landscape.likec4` plus every other `.likec4` under
+ * `architecture/` — so naming the landscape file was a guess that sent an author
+ * to a document that does not declare the element at all.
+ */
+const MAP = "the fleet map (architecture/)";
+export function divergedFindings(check) {
+    const { service, model, architecture, known } = check;
+    // An extending model declares each of these elements exactly once by
+    // construction — there is no copy to diverge — and the shapes' other grade
+    // (`c4.element-unowned`) is what asks its question.
+    if (model.shape !== "standalone")
+        return [];
+    if (model.doc.errors.length > 0)
+        return [];
+    if (architecture === null || architecture.errors.length > 0)
+        return [];
+    const index = joinIndex(architecture.elements, known);
+    const findings = [];
+    for (const mine of model.doc.elements) {
+        const theirs = counterpart(index, mine);
+        if (theirs === undefined)
+            continue;
+        const fields = differing(mine, theirs);
+        if (fields.length === 0)
+            continue;
+        // Where "copy the map's declaration verbatim" is a no-op: the tag sets are
+        // all that differ (so the two kinds are equal, and the block to open can be
+        // named) and copying the map's literal tags across would leave them still
+        // differing. `fields` is checked first because copying DOES fix a title or a
+        // binding, so the verbatim remedy stays right whenever one of those differs.
+        const specs = { mine: model.doc.specification, theirs: architecture.specification };
+        const inherited = fields.length === 1 && fields[0] === "tags" && copyIsNoOp(mine, theirs, specs)
+            ? declaringSide(mine.kind, specs)
+            : null;
+        findings.push({
+            severity: "warn",
+            code: "c4.declaration-diverged",
+            subject: service,
+            message: `${service}: ${ARTIFACT_FILES.model} declares '${mine.id}' as ${describe(mine)} and ` +
+                `${MAP} declares ${theirs.id === mine.id ? "it" : `'${theirs.id}'`} as ${describe(theirs)} — ` +
+                remedy(fields, mine.kind, inherited),
+        });
+    }
+    return findings;
+}
+/**
+ * What the message says after the two declarations: which fields differ, and
+ * what to do about it. `inherited` is null when copying the map's declaration
+ * fixes this, and otherwise the clause naming which document's `specification`
+ * puts the tags on the kind — the side an author has to open.
+ */
+function remedy(fields, kind, inherited) {
+    // "the kind differs" / "the title differs" / "the tags differ": the verb
+    // agrees with the last field named, and `tags` is the one plural noun in the
+    // set. It shipped as "the kind differ", and a sentence a reader trips over is
+    // one they stop reading.
+    const plural = fields.length > 1 || fields[fields.length - 1] === "tags";
+    const named = `the ${fields.join(", ")} differ${plural ? "" : "s"}`;
+    // The two kinds are equal whenever `tags` is the only differing field, so the
+    // block to open can be named exactly.
+    if (inherited !== null) {
+        return (`${named}, and copying the map's declaration would not clear it: the sets come apart on ` +
+            `\`specification { element ${kind} { … } }\`, ${inherited}. Either match the two specification ` +
+            'blocks on that kind, or migrate the model to extend the map (SCHEMA.md, "Two shapes of a service ' +
+            'model") so there is one specification and one declaration');
+    }
+    return (`${named}, so two documents are two authorities on one element. Copy the map's declaration verbatim, or ` +
+        'migrate the model to extend the map (SCHEMA.md, "Two shapes of a service model") so it is declared once');
+}
+function joinIndex(elements, known) {
+    // Which map elements are the fleet's own boxes rather than somebody's
+    // interior, by the ONE predicate every other fleet check asks it with
+    // (`fleet/census.ts`): a binding or a title naming a real services/<id>/ makes
+    // an element a service at any depth, and what sits inside one is that
+    // service's container. Everything else is fleet-level — a top-level element,
+    // or a box the map draws inside a plain grouping element — see the header.
+    const fleetLevel = new Set(serviceLevelElements([...elements], known).map((e) => e.id));
+    return {
+        byId: unique(elements, (e) => [e.id]),
+        byBinding: unique(elements, (e) => (e.service === undefined ? [] : [e.service])),
+        // Every DOTTED tail of the id, so a model's `paymentService.api` reaches the
+        // map's `marketplace.paymentService.api`: a tail carrying a dot names the
+        // owner as well as the leaf, so the two documents are talking about one
+        // element.
+        //
+        // The bare LAST segment names only the leaf, and it is emitted for
+        // FLEET-LEVEL boxes alone. This shipped unconditional, and the comment
+        // here claimed it was not: a standalone model's own `db`, `api` or `agent`
+        // joined whatever `<something>.<that name>` the map happened to hold — one
+        // service's private cache told to copy another service's store, verbatim.
+        // loam's own meta/docs hit it (`agent` ↔ `loam.core.agent`, a container of
+        // src/core/agent/), which is the case that made the rung wrong rather than
+        // merely risky (verification 2026-09-04).
+        //
+        // A box the map draws inside a plain GROUP still emits its bare segment,
+        // and deliberately: `infra.cache` is the fleet's cache, so a model's own
+        // top-level `cache` is a second meaning for one name and worth the warning.
+        // Grouping is a drawing convenience, not ownership — only a SERVICE owns an
+        // interior — so the guard is "no ancestor stands for a service" and not
+        // "the id carries no dot".
+        bySuffix: unique(elements, (e) => {
+            const segments = e.id.split(".");
+            const tails = segments.map((_, i) => segments.slice(i).join("."));
+            return fleetLevel.has(e.id) ? tails : tails.slice(0, -1);
+        }),
+    };
+}
+/** An index holding only the keys exactly ONE element answers to — a shared key joins nothing. */
+function unique(elements, keys) {
+    const claims = new Map();
+    for (const element of elements) {
+        for (const key of keys(element)) {
+            const held = claims.get(key);
+            if (held === undefined)
+                claims.set(key, [element]);
+            else
+                held.push(element);
+        }
+    }
+    const index = new Map();
+    for (const [key, held] of claims)
+        if (held.length === 1)
+            index.set(key, held[0]);
+    return index;
+}
+/** The map's declaration of the element this model declares, or undefined when nothing joins. */
+function counterpart(index, mine) {
+    const byId = index.byId.get(mine.id);
+    if (byId !== undefined)
+        return byId;
+    // The binding is the strongest evidence after the id: both documents wrote
+    // `metadata { service '<id>' }`, so both mean the same directory.
+    const bound = mine.service === undefined ? undefined : index.byBinding.get(mine.service);
+    if (bound !== undefined)
+        return bound;
+    return index.bySuffix.get(mine.id);
+}
+/** Which of the four compared fields disagree, in a fixed order so two runs read alike. */
+function differing(mine, theirs) {
+    const fields = [];
+    if (mine.kind !== theirs.kind)
+        fields.push("kind");
+    if (mine.title !== theirs.title)
+        fields.push("title");
+    // A SET, sorted: tag order is authoring order and means nothing, and a model
+    // that lists the map's two tags the other way round is the same declaration.
+    if (tagList(mine) !== tagList(theirs))
+        fields.push("tags");
+    if (mine.service !== theirs.service)
+        fields.push("service binding");
+    return fields;
+}
+function tagList(e) {
+    return [...new Set(e.tags)].sort().join(" ");
+}
+/**
+ * Would "copy the map's declaration verbatim" leave the tag sets still
+ * differing? Answered by SIMULATING the copy, which is the only way to be right
+ * about it in both directions.
+ *
+ * `Elem.tags` is what LikeC4 hands over, and since 1.59.0 that includes every
+ * tag the element's kind declares (`core/c4/parsed/specification.ts` says why
+ * loam reads the block at all). Copying the map's DECLARATION copies its literal
+ * tags into the model and nothing else — the model keeps its own specification —
+ * so the model's element would come back carrying `mine's kind defaults ∪ the
+ * map's literal tags`, against the map's `its kind defaults ∪ the same literal
+ * tags`. Those differ exactly when the two kind defaults differ outside the
+ * copied literals, and then the remedy is a no-op.
+ *
+ * The first version compared the two LITERAL tag lists and switched arms only
+ * when they were equal, which caught one direction of the same case and missed
+ * its mirror: a model writing `#external` on an element whose map twin inherits
+ * `#external #platform` from `element topic { … }` was told to copy the map's
+ * bare line, and doing exactly that produced the OTHER arm of this same message
+ * (verification 2026-09-04, second pass, examples/docs order-service).
+ */
+function copyIsNoOp(mine, theirs, specs) {
+    const copied = literalTags(theirs, specs.theirs);
+    const after = union(kindTags(mine.kind, specs.mine), copied);
+    const before = union(kindTags(theirs.kind, specs.theirs), copied);
+    return after !== before;
+}
+/**
+ * Which document's `specification` puts the tags on the kind — the half of the
+ * message that tells an author which file to open. "Both, differently" is a real
+ * state (each block declares its own tag on the same kind) and gets its own
+ * words rather than a guess at one side.
+ */
+function declaringSide(kind, specs) {
+    const mine = kindTags(kind, specs.mine);
+    const theirs = kindTags(kind, specs.theirs);
+    if (mine.length > 0 && theirs.length > 0)
+        return "which the two documents declare different tags on";
+    if (theirs.length > 0)
+        return `which ${MAP} declares tags on and ${ARTIFACT_FILES.model} does not`;
+    if (mine.length > 0)
+        return `which ${ARTIFACT_FILES.model} declares tags on and ${MAP} does not`;
+    // No kind declares anything and the copy still fails: not reachable from the
+    // predicate above (with equal kinds and no defaults the copy always clears
+    // it), and a sentence that names no file beats one that names the wrong file.
+    return "which the two documents' blocks disagree on";
+}
+/** The tags `spec` puts on every element of `kind`, sorted — the defaults an element cannot see. */
+function kindTags(kind, spec) {
+    return [...new Set(spec?.elementKindTags[kind] ?? [])].sort();
+}
+/** A tag SET as one comparable string; see `tagList` for why order is dropped. */
+function union(a, b) {
+    return [...new Set([...a, ...b])].sort().join(" ");
+}
+function literalTags(e, spec) {
+    const inherited = new Set(kindTags(e.kind, spec));
+    return [...new Set(e.tags)].filter((tag) => !inherited.has(tag)).sort();
+}
+/** One element as the message names it — every compared field, in the order `differing` reports them. */
+function describe(e) {
+    const tags = tagList(e);
+    return `${e.kind} '${e.title}' [${tags === "" ? "no tags" : tags}, bound to ${e.service ?? "unbound"}]`;
+}
+//# sourceMappingURL=diverged.js.map

package/dist/commands/validate/service/model/diverged.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diverged.js","sourceRoot":"","sources":["../../../../../src/commands/validate/service/model/diverged.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `c4.declaration-diverged` — the check the \"every shared element is declared\n * once per document\" report asked for.\n *\n * A STANDALONE model has to re-declare every element it talks about: it is\n * parsed alone, so `kafka`, `uaa` and each peer service appear a second time,\n * with a second kind, a second title, a second tag list and a second binding.\n * Nothing compared the copies. Measured on the fleet that filed the report: 78\n * double declarations across 56 services, and the copies had already drifted —\n * `#platform` was on the map's elements and missing from the models'.\n *\n * WHAT IS COMPARED, and why exactly these four. `kind`, `title`, the tag SET and\n * the `metadata { service }` binding each change what loam concludes or what a\n * view shows: the kind decides which specification rule applies and which\n * exemptions (`ACTOR_KINDS`, `#external`) fire, the title is a resolver fallback\n * when nothing is bound, a tag is graded (`#external`, `#obl-…`), and the\n * binding decides which directory an edge is filed under. `description` is\n * deliberately NOT compared: it is prose, nothing joins on it, and reporting two\n * differently-worded sentences as a divergence would train a reader to ignore\n * the code.\n *\n * WHICH TWO DECLARATIONS ARE ONE ELEMENT is `counterpart` below, and it is the\n * half the first release got wrong: it joined on the literal id, so in a GROUPED\n * map — one that nests its services under `marketplace`, as loam's own example\n * does — a model's `paymentService` never met the map's\n * `marketplace.paymentService` and the check was silent on every fleet that\n * groups (verification 2026-09-04, W3). The three rungs are ordered by how much\n * they assume: the id, then the `metadata { service }` binding both sides wrote,\n * then a unique dotted TAIL of the map's id. Ambiguity is never resolved by\n * picking one — a key two map elements answer to joins nothing, because a\n * divergence reported against the wrong peer is worse than the silence. And the\n * BARE last segment is a tail only when the map element it names is a\n * FLEET-LEVEL box: see `joinIndex`, where the first release of the tail rung\n * joined one service's `db` to another service's.\n *\n * WHAT \"FLEET-LEVEL\" MEANS, spelled once here because three pages spelled it\n * differently and all three were wrong (verification 2026-09-04, second pass):\n * a map element NO ANCESTOR of which stands for a service — `serviceLevelElements`,\n * the one predicate every fleet check asks this question with. That is a\n * top-level element, and equally a child of a plain grouping element: a map\n * that draws `infra = group 'Infra' { cache = database … }` is drawing the\n * fleet's cache, at fleet level, and a standalone model that declares its own\n * top-level `cache` IS shadowing that box — the two documents give one name two\n * meanings, which is the thing this code exists to report. What the rung must\n * never reach is an element drawn INSIDE a service's own element: that is\n * somebody's interior, it belongs to that service, and a model's private `db`\n * being told to copy another service's `db` verbatim is the wrong-join class\n * the tail rung was restricted for in the first place.\n *\n * SILENT WHEN THE MAP DOES NOT PARSE, and when the model does not: a diff\n * against half a document is invention, and both states already have a finding\n * of their own.\n *\n * The repair has two forms on purpose. Copying the map's declaration verbatim\n * keeps the standalone shape, which is legal forever; migrating the model to\n * extend the map removes the copy altogether, which is the only fix that cannot\n * drift again. Except where the first repair is a no-op, and `copyIsNoOp`\n * decides that by SIMULATING it rather than by pattern-matching one shape of it:\n * a tag difference that survives the copy comes off the two documents'\n * `specification` blocks, so the message names the block instead.\n */\nimport type { Elem, LoadedDoc } from \"../../../../core/c4/likec4.js\";\nimport type { DocSpecification } from \"../../../../core/c4/parsed/specification.js\";\nimport type { ServiceModel } from \"../../../../core/c4/service-model/load.js\";\nimport type { PathableService } from \"../../../../core/kernel/ids/service.js\";\nimport { ARTIFACT_FILES } from \"../../../../core/repo/paths.js\";\nimport type { Finding } from \"../../../../core/vocabulary/report.js\";\nimport { serviceLevelElements } from \"../../fleet/census.js\";\n\n/**\n * How the OTHER declaration is named.\n *\n * The document, not the file: `Elem` carries no source path, and the map is a\n * PROJECT — `architecture/landscape.likec4` plus every other `.likec4` under\n * `architecture/` — so naming the landscape file was a guess that sent an author\n * to a document that does not declare the element at all.\n */\nconst MAP = \"the fleet map (architecture/)\";\n\nexport interface DivergenceCheck {\n  service: PathableService;\n  model: ServiceModel;\n  /** The `architecture/` project — the map as every other fleet check reads it. Null when the repo has none. */\n  architecture: LoadedDoc | null;\n  /**\n   * Every `services/<id>/` that exists — the census's positive evidence, which\n   * is what tells a map's fleet-level box from a container drawn inside a\n   * service. Only the bare-last-segment tail join reads it; see `joinIndex`.\n   */\n  known: ReadonlySet<string>;\n}\n\nexport function divergedFindings(check: DivergenceCheck): Finding[] {\n  const { service, model, architecture, known } = check;\n  // An extending model declares each of these elements exactly once by\n  // construction — there is no copy to diverge — and the shapes' other grade\n  // (`c4.element-unowned`) is what asks its question.\n  if (model.shape !== \"standalone\") return [];\n  if (model.doc.errors.length > 0) return [];\n  if (architecture === null || architecture.errors.length > 0) return [];\n\n  const index = joinIndex(architecture.elements, known);\n  const findings: Finding[] = [];\n  for (const mine of model.doc.elements) {\n    const theirs = counterpart(index, mine);\n    if (theirs === undefined) continue;\n    const fields = differing(mine, theirs);\n    if (fields.length === 0) continue;\n    // Where \"copy the map's declaration verbatim\" is a no-op: the tag sets are\n    // all that differ (so the two kinds are equal, and the block to open can be\n    // named) and copying the map's literal tags across would leave them still\n    // differing. `fields` is checked first because copying DOES fix a title or a\n    // binding, so the verbatim remedy stays right whenever one of those differs.\n    const specs = { mine: model.doc.specification, theirs: architecture.specification };\n    const inherited =\n      fields.length === 1 && fields[0] === \"tags\" && copyIsNoOp(mine, theirs, specs)\n        ? declaringSide(mine.kind, specs)\n        : null;\n    findings.push({\n      severity: \"warn\",\n      code: \"c4.declaration-diverged\",\n      subject: service,\n      message:\n        `${service}: ${ARTIFACT_FILES.model} declares '${mine.id}' as ${describe(mine)} and ` +\n        `${MAP} declares ${theirs.id === mine.id ? \"it\" : `'${theirs.id}'`} as ${describe(theirs)} — ` +\n        remedy(fields, mine.kind, inherited),\n    });\n  }\n  return findings;\n}\n\n/**\n * What the message says after the two declarations: which fields differ, and\n * what to do about it. `inherited` is null when copying the map's declaration\n * fixes this, and otherwise the clause naming which document's `specification`\n * puts the tags on the kind — the side an author has to open.\n */\nfunction remedy(fields: string[], kind: string, inherited: string | null): string {\n  // \"the kind differs\" / \"the title differs\" / \"the tags differ\": the verb\n  // agrees with the last field named, and `tags` is the one plural noun in the\n  // set. It shipped as \"the kind differ\", and a sentence a reader trips over is\n  // one they stop reading.\n  const plural = fields.length > 1 || fields[fields.length - 1] === \"tags\";\n  const named = `the ${fields.join(\", \")} differ${plural ? \"\" : \"s\"}`;\n  // The two kinds are equal whenever `tags` is the only differing field, so the\n  // block to open can be named exactly.\n  if (inherited !== null) {\n    return (\n      `${named}, and copying the map's declaration would not clear it: the sets come apart on ` +\n      `\\`specification { element ${kind} { … } }\\`, ${inherited}. Either match the two specification ` +\n      'blocks on that kind, or migrate the model to extend the map (SCHEMA.md, \"Two shapes of a service ' +\n      'model\") so there is one specification and one declaration'\n    );\n  }\n  return (\n    `${named}, so two documents are two authorities on one element. Copy the map's declaration verbatim, or ` +\n    'migrate the model to extend the map (SCHEMA.md, \"Two shapes of a service model\") so it is declared once'\n  );\n}\n\n/** The map's elements, indexed by each key `counterpart` may join on — ambiguous keys dropped. */\ninterface JoinIndex {\n  byId: Map<string, Elem>;\n  byBinding: Map<string, Elem>;\n  bySuffix: Map<string, Elem>;\n}\n\nfunction joinIndex(elements: readonly Elem[], known: ReadonlySet<string>): JoinIndex {\n  // Which map elements are the fleet's own boxes rather than somebody's\n  // interior, by the ONE predicate every other fleet check asks it with\n  // (`fleet/census.ts`): a binding or a title naming a real services/<id>/ makes\n  // an element a service at any depth, and what sits inside one is that\n  // service's container. Everything else is fleet-level — a top-level element,\n  // or a box the map draws inside a plain grouping element — see the header.\n  const fleetLevel = new Set(serviceLevelElements([...elements], known).map((e) => e.id));\n  return {\n    byId: unique(elements, (e) => [e.id]),\n    byBinding: unique(elements, (e) => (e.service === undefined ? [] : [e.service as string])),\n    // Every DOTTED tail of the id, so a model's `paymentService.api` reaches the\n    // map's `marketplace.paymentService.api`: a tail carrying a dot names the\n    // owner as well as the leaf, so the two documents are talking about one\n    // element.\n    //\n    // The bare LAST segment names only the leaf, and it is emitted for\n    // FLEET-LEVEL boxes alone. This shipped unconditional, and the comment\n    // here claimed it was not: a standalone model's own `db`, `api` or `agent`\n    // joined whatever `<something>.<that name>` the map happened to hold — one\n    // service's private cache told to copy another service's store, verbatim.\n    // loam's own meta/docs hit it (`agent` ↔ `loam.core.agent`, a container of\n    // src/core/agent/), which is the case that made the rung wrong rather than\n    // merely risky (verification 2026-09-04).\n    //\n    // A box the map draws inside a plain GROUP still emits its bare segment,\n    // and deliberately: `infra.cache` is the fleet's cache, so a model's own\n    // top-level `cache` is a second meaning for one name and worth the warning.\n    // Grouping is a drawing convenience, not ownership — only a SERVICE owns an\n    // interior — so the guard is \"no ancestor stands for a service\" and not\n    // \"the id carries no dot\".\n    bySuffix: unique(elements, (e) => {\n      const segments = e.id.split(\".\");\n      const tails = segments.map((_, i) => segments.slice(i).join(\".\"));\n      return fleetLevel.has(e.id) ? tails : tails.slice(0, -1);\n    }),\n  };\n}\n\n/** An index holding only the keys exactly ONE element answers to — a shared key joins nothing. */\nfunction unique(elements: readonly Elem[], keys: (e: Elem) => string[]): Map<string, Elem> {\n  const claims = new Map<string, Elem[]>();\n  for (const element of elements) {\n    for (const key of keys(element)) {\n      const held = claims.get(key);\n      if (held === undefined) claims.set(key, [element]);\n      else held.push(element);\n    }\n  }\n  const index = new Map<string, Elem>();\n  for (const [key, held] of claims) if (held.length === 1) index.set(key, held[0]!);\n  return index;\n}\n\n/** The map's declaration of the element this model declares, or undefined when nothing joins. */\nfunction counterpart(index: JoinIndex, mine: Elem): Elem | undefined {\n  const byId = index.byId.get(mine.id);\n  if (byId !== undefined) return byId;\n  // The binding is the strongest evidence after the id: both documents wrote\n  // `metadata { service '<id>' }`, so both mean the same directory.\n  const bound = mine.service === undefined ? undefined : index.byBinding.get(mine.service as string);\n  if (bound !== undefined) return bound;\n  return index.bySuffix.get(mine.id);\n}\n\n/** Which of the four compared fields disagree, in a fixed order so two runs read alike. */\nfunction differing(mine: Elem, theirs: Elem): string[] {\n  const fields: string[] = [];\n  if (mine.kind !== theirs.kind) fields.push(\"kind\");\n  if (mine.title !== theirs.title) fields.push(\"title\");\n  // A SET, sorted: tag order is authoring order and means nothing, and a model\n  // that lists the map's two tags the other way round is the same declaration.\n  if (tagList(mine) !== tagList(theirs)) fields.push(\"tags\");\n  if (mine.service !== theirs.service) fields.push(\"service binding\");\n  return fields;\n}\n\nfunction tagList(e: Elem): string {\n  return [...new Set(e.tags)].sort().join(\" \");\n}\n\n/** The two documents' `specification` blocks, as `copyIsNoOp` and `declaringSide` read them. */\ninterface SpecPair {\n  mine: DocSpecification | undefined;\n  theirs: DocSpecification | undefined;\n}\n\n/**\n * Would \"copy the map's declaration verbatim\" leave the tag sets still\n * differing? Answered by SIMULATING the copy, which is the only way to be right\n * about it in both directions.\n *\n * `Elem.tags` is what LikeC4 hands over, and since 1.59.0 that includes every\n * tag the element's kind declares (`core/c4/parsed/specification.ts` says why\n * loam reads the block at all). Copying the map's DECLARATION copies its literal\n * tags into the model and nothing else — the model keeps its own specification —\n * so the model's element would come back carrying `mine's kind defaults ∪ the\n * map's literal tags`, against the map's `its kind defaults ∪ the same literal\n * tags`. Those differ exactly when the two kind defaults differ outside the\n * copied literals, and then the remedy is a no-op.\n *\n * The first version compared the two LITERAL tag lists and switched arms only\n * when they were equal, which caught one direction of the same case and missed\n * its mirror: a model writing `#external` on an element whose map twin inherits\n * `#external #platform` from `element topic { … }` was told to copy the map's\n * bare line, and doing exactly that produced the OTHER arm of this same message\n * (verification 2026-09-04, second pass, examples/docs order-service).\n */\nfunction copyIsNoOp(mine: Elem, theirs: Elem, specs: SpecPair): boolean {\n  const copied = literalTags(theirs, specs.theirs);\n  const after = union(kindTags(mine.kind, specs.mine), copied);\n  const before = union(kindTags(theirs.kind, specs.theirs), copied);\n  return after !== before;\n}\n\n/**\n * Which document's `specification` puts the tags on the kind — the half of the\n * message that tells an author which file to open. \"Both, differently\" is a real\n * state (each block declares its own tag on the same kind) and gets its own\n * words rather than a guess at one side.\n */\nfunction declaringSide(kind: string, specs: SpecPair): string {\n  const mine = kindTags(kind, specs.mine);\n  const theirs = kindTags(kind, specs.theirs);\n  if (mine.length > 0 && theirs.length > 0) return \"which the two documents declare different tags on\";\n  if (theirs.length > 0) return `which ${MAP} declares tags on and ${ARTIFACT_FILES.model} does not`;\n  if (mine.length > 0) return `which ${ARTIFACT_FILES.model} declares tags on and ${MAP} does not`;\n  // No kind declares anything and the copy still fails: not reachable from the\n  // predicate above (with equal kinds and no defaults the copy always clears\n  // it), and a sentence that names no file beats one that names the wrong file.\n  return \"which the two documents' blocks disagree on\";\n}\n\n/** The tags `spec` puts on every element of `kind`, sorted — the defaults an element cannot see. */\nfunction kindTags(kind: string, spec: DocSpecification | undefined): string[] {\n  return [...new Set(spec?.elementKindTags[kind] ?? [])].sort();\n}\n\n/** A tag SET as one comparable string; see `tagList` for why order is dropped. */\nfunction union(a: readonly string[], b: readonly string[]): string {\n  return [...new Set([...a, ...b])].sort().join(\" \");\n}\n\nfunction literalTags(e: Elem, spec: DocSpecification | undefined): string[] {\n  const inherited = new Set(kindTags(e.kind, spec));\n  return [...new Set(e.tags)].filter((tag) => !inherited.has(tag)).sort();\n}\n\n/** One element as the message names it — every compared field, in the order `differing` reports them. */\nfunction describe(e: Elem): string {\n  const tags = tagList(e);\n  return `${e.kind} '${e.title}' [${tags === \"\" ? \"no tags\" : tags}, bound to ${e.service ?? \"unbound\"}]`;\n}\n"]}