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

package/dist/core/pack/pack.js

@@ -0,0 +1,76 @@
+/**
+ * One service's context pack: the exact docs slice bound to a service —
+ * living requirements verbatim, both contracts, the fleet edges one hop out,
+ * the permission and capability joins, provenance, and every active feature's
+ * delta over it — assembled as one deterministic payload an agent loads before
+ * working in that service's repository.
+ *
+ * Core rather than the command, exactly as `core/explore/explore.ts` sits
+ * behind `loam explore`: a future facade (an MCP tool, a second renderer)
+ * reuses the assembly without the printing, and the command layer stays I/O.
+ * Deterministic by construction — identical state must yield identical bytes:
+ * no timestamps, repo-relative forward-slash paths only, every unioned set
+ * sorted with `compareIds`, contract entries in document order (a fact of the
+ * file, hence of the state).
+ */
+import { FleetContext } from "../fleet-context.js";
+import { repoPath } from "../envelope/json.js";
+import {} from "../repo/entries.js";
+import { buildLiving } from "./living.js";
+import { buildJoins } from "./joins.js";
+import { buildFeatures } from "./features.js";
+/**
+ * Assemble the pack. Reads only; writes nothing, and refuses nothing — every
+ * miss is a field, and an unreadable DOCUMENT is a flag the caller grades
+ * (`packHoles`). What does throw — an unreadable directory, bytes that are
+ * not UTF-8 — is the all-or-nothing class explore takes too: the honest
+ * answer is a refusal naming the path, not a pack with a silent hole.
+ */
+export async function assemblePack(req) {
+    const { docsDir, entry, feature, context } = req;
+    // The three sections are independent derivations over one shared read
+    // index; identical reads share their in-flight promise, so the fan-out
+    // costs no duplicate I/O and no section can see a different file version.
+    const [living, joins, features] = await Promise.all([
+        buildLiving({ docsDir, entry, context }),
+        buildJoins({ docsDir, entry, context }),
+        buildFeatures({ docsDir, entry, feature, context }),
+    ]);
+    return {
+        service: entry.id,
+        path: repoPath(docsDir, entry.dir),
+        feature: feature === null ? null : feature.id,
+        ...living,
+        ...joins,
+        features,
+    };
+}
+/**
+ * Whether the pack has a silent hole: a document that exists but could not be
+ * read, so a section that LOOKS empty is really unanswered. The command maps
+ * this to exit 1 with `ok: true` — delta's precedent, same reasoning: the
+ * pack is consumed by agents that never ran validate, so the exit code must
+ * carry the failure itself. Set before the format fork; the guard is about
+ * the pack, not about how it is rendered.
+ */
+export function packHoles(pack) {
+    return ((pack.landscape.present && !pack.landscape.parses) ||
+        pack.openapi.unreadable ||
+        pack.asyncapi.unreadable ||
+        // The two fleet vocabularies and the rollup's fleet walk fail the same
+        // way the contracts do: an unreadable file EMPTIES a section (`declared:
+        // false` on every permission, "(none realized here)") while looking like
+        // an answer, so their health is part of the hole contract, not decoration.
+        pack.permissionsVocabulary.invalid !== undefined ||
+        pack.capabilitiesVocabulary.invalid !== undefined ||
+        pack.capabilitiesUnread.length > 0 ||
+        // The use-case axis fails the same way, and one step wider than
+        // `landscape.parses` above: that flag is about `architecture/landscape.likec4`
+        // alone, while a flow lives in `architecture/usecases/*.likec4` and the whole
+        // directory is read as ONE LikeC4 project. So a use-case file with an
+        // unresolved element leaves `landscape.parses` true and empties every flow
+        // in the pack — the exact silent hole this predicate exists to refuse.
+        pack.useCaseScan.unreadable ||
+        pack.features.some((f) => f.architecture.errors.length > 0 || f.openapi.unreadable || f.events.unreadable));
+}
+//# sourceMappingURL=pack.js.map

package/dist/core/pack/pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.js","sourceRoot":"","sources":["../../../src/core/pack/pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAwC,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAoB,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAmB,MAAM,YAAY,CAAC;AACzD,OAAO,EAAE,aAAa,EAAoB,MAAM,eAAe,CAAC;AA0BhE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAgB;IACjD,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;IACjD,sEAAsE;IACtE,uEAAuE;IACvE,0EAA0E;IAC1E,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAClD,WAAW,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACxC,UAAU,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACvC,aAAa,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;KACpD,CAAC,CAAC;IACH,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,EAAE;QACjB,IAAI,EAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC;QAClC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE;QAC7C,GAAG,MAAM;QACT,GAAG,KAAK;QACR,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,IAAiB;IACzC,OAAO,CACL,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QAClD,IAAI,CAAC,OAAO,CAAC,UAAU;QACvB,IAAI,CAAC,QAAQ,CAAC,UAAU;QACxB,uEAAuE;QACvE,yEAAyE;QACzE,yEAAyE;QACzE,2EAA2E;QAC3E,IAAI,CAAC,qBAAqB,CAAC,OAAO,KAAK,SAAS;QAChD,IAAI,CAAC,sBAAsB,CAAC,OAAO,KAAK,SAAS;QACjD,IAAI,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC;QAClC,gEAAgE;QAChE,+EAA+E;QAC/E,8EAA8E;QAC9E,sEAAsE;QACtE,2EAA2E;QAC3E,uEAAuE;QACvE,IAAI,CAAC,WAAW,CAAC,UAAU;QAC3B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAChB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,MAAM,CAAC,UAAU,CACvF,CACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * One service's context pack: the exact docs slice bound to a service —\n * living requirements verbatim, both contracts, the fleet edges one hop out,\n * the permission and capability joins, provenance, and every active feature's\n * delta over it — assembled as one deterministic payload an agent loads before\n * working in that service's repository.\n *\n * Core rather than the command, exactly as `core/explore/explore.ts` sits\n * behind `loam explore`: a future facade (an MCP tool, a second renderer)\n * reuses the assembly without the printing, and the command layer stays I/O.\n * Deterministic by construction — identical state must yield identical bytes:\n * no timestamps, repo-relative forward-slash paths only, every unioned set\n * sorted with `compareIds`, contract entries in document order (a fact of the\n * file, hence of the state).\n */\nimport { FleetContext } from \"../fleet-context.js\";\nimport { repoPath } from \"../envelope/json.js\";\nimport { type FeatureEntry, type ServiceEntry } from \"../repo/entries.js\";\nimport { buildLiving, type LivingSlice } from \"./living.js\";\nimport { buildJoins, type JoinsSlice } from \"./joins.js\";\nimport { buildFeatures, type PackFeature } from \"./features.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\nexport interface PackRequest {\n  docsDir: DocsDir;\n  /** The service, as the enumeration answered it — the entry, not an id and a dir (rule 17). */\n  entry: ServiceEntry;\n  /** The one feature `--feature` resolved, or null for every touching feature. */\n  feature: FeatureEntry | null;\n  context: FleetContext;\n}\n\nexport interface ContextPack extends LivingSlice, JoinsSlice {\n  service: string;\n  path: string;\n  /**\n   * The canonical id of the one feature `--feature` narrowed to, or null for\n   * the everything-in-flight default. Echoed so a stored pack SAYS it is a\n   * narrowed view: two packs of the same service can otherwise differ only by\n   * what they silently left out, and an agent diffing them (or resuming from\n   * one) has no way to tell a narrowed pack from a fleet gone quiet.\n   */\n  feature: string | null;\n  features: PackFeature[];\n}\n\n/**\n * Assemble the pack. Reads only; writes nothing, and refuses nothing — every\n * miss is a field, and an unreadable DOCUMENT is a flag the caller grades\n * (`packHoles`). What does throw — an unreadable directory, bytes that are\n * not UTF-8 — is the all-or-nothing class explore takes too: the honest\n * answer is a refusal naming the path, not a pack with a silent hole.\n */\nexport async function assemblePack(req: PackRequest): Promise<ContextPack> {\n  const { docsDir, entry, feature, context } = req;\n  // The three sections are independent derivations over one shared read\n  // index; identical reads share their in-flight promise, so the fan-out\n  // costs no duplicate I/O and no section can see a different file version.\n  const [living, joins, features] = await Promise.all([\n    buildLiving({ docsDir, entry, context }),\n    buildJoins({ docsDir, entry, context }),\n    buildFeatures({ docsDir, entry, feature, context }),\n  ]);\n  return {\n    service: entry.id,\n    path: repoPath(docsDir, entry.dir),\n    feature: feature === null ? null : feature.id,\n    ...living,\n    ...joins,\n    features,\n  };\n}\n\n/**\n * Whether the pack has a silent hole: a document that exists but could not be\n * read, so a section that LOOKS empty is really unanswered. The command maps\n * this to exit 1 with `ok: true` — delta's precedent, same reasoning: the\n * pack is consumed by agents that never ran validate, so the exit code must\n * carry the failure itself. Set before the format fork; the guard is about\n * the pack, not about how it is rendered.\n */\nexport function packHoles(pack: ContextPack): boolean {\n  return (\n    (pack.landscape.present && !pack.landscape.parses) ||\n    pack.openapi.unreadable ||\n    pack.asyncapi.unreadable ||\n    // The two fleet vocabularies and the rollup's fleet walk fail the same\n    // way the contracts do: an unreadable file EMPTIES a section (`declared:\n    // false` on every permission, \"(none realized here)\") while looking like\n    // an answer, so their health is part of the hole contract, not decoration.\n    pack.permissionsVocabulary.invalid !== undefined ||\n    pack.capabilitiesVocabulary.invalid !== undefined ||\n    pack.capabilitiesUnread.length > 0 ||\n    // The use-case axis fails the same way, and one step wider than\n    // `landscape.parses` above: that flag is about `architecture/landscape.likec4`\n    // alone, while a flow lives in `architecture/usecases/*.likec4` and the whole\n    // directory is read as ONE LikeC4 project. So a use-case file with an\n    // unresolved element leaves `landscape.parses` true and empties every flow\n    // in the pack — the exact silent hole this predicate exists to refuse.\n    pack.useCaseScan.unreadable ||\n    pack.features.some(\n      (f) => f.architecture.errors.length > 0 || f.openapi.unreadable || f.events.unreadable,\n    )\n  );\n}\n"]}

package/dist/core/permissions/permissions.js

@@ -0,0 +1,87 @@
+/**
+ * The fleet's authorization vocabulary: which permissions exist, and on which
+ * kind of subject each one is checked.
+ *
+ * It is a fleet document rather than a service one because permissions cross
+ * services in the shape that matters — a permission a profile holds is owned by
+ * whatever service owns profiles and enforced by every service that reads it,
+ * and a per-service copy would be N copies of one word. `architecture/` is
+ * where the fleet's shared documents already live.
+ *
+ * The unit is a PAIR, `<subject>/<permission>`, and that is the whole reason
+ * this file exists instead of a `Requires:` line joined against OpenAPI's
+ * `security`. OpenAPI carries permission NAMES only for oauth2 and
+ * openIdConnect — for `http bearer` and `apiKey` the spec requires the scope
+ * array to be empty — so a fleet on bearer tokens has nowhere in its contract
+ * to say what it checks. And `security` answers only for the CALLER, while a
+ * permission is as often checked on an entity inside the request.
+ *
+ * What this is NOT, deliberately: a domain model. Permissions are a flat list
+ * of names under a subject kind — no entities, no relations, no resources.
+ * Everything past that has no ground truth to check against, which is the same
+ * reason the capability axis stops at declared names
+ * (core/capabilities/capabilities.ts) and there is still no AUTHORED capability
+ * layer (SCHEMA.md) — a vocabulary loam cannot
+ * check is a vocabulary that drifts while looking authoritative. A permission
+ * that varies by resource is separate names (`channel:send:sms`,
+ * `channel:send:email`) or a column in a scenario's Examples table.
+ */
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { isRecord } from "../kernel/records.js";
+const EMPTY = { present: false, subjects: [], byId: new Map() };
+/**
+ * Read the vocabulary. A missing file is not a finding — a fleet that gates
+ * nothing on permissions owes no vocabulary, and the checks that read this stay
+ * silent on an absent one exactly as the OpenAPI axis stays silent for a
+ * service the landscape shows nobody calls.
+ */
+export async function readVocabulary(path) {
+    if (!existsSync(path))
+        return EMPTY;
+    let doc;
+    try {
+        doc = parseYaml(await readFile(path, "utf8"));
+    }
+    catch (e) {
+        return { ...EMPTY, present: true, invalid: e instanceof Error ? e.message : String(e) };
+    }
+    if (doc === null || doc === undefined)
+        return { ...EMPTY, present: true };
+    if (!isRecord(doc))
+        return { ...EMPTY, present: true, invalid: "the document is not a mapping" };
+    const subjects = isRecord(doc["subjects"]) ? Object.keys(doc["subjects"]) : [];
+    const permsBlock = doc["permissions"];
+    if (permsBlock === undefined)
+        return { present: true, subjects, byId: new Map() };
+    if (!isRecord(permsBlock))
+        return { ...EMPTY, present: true, invalid: "`permissions` is not a mapping of subject kind to permissions" };
+    const byId = new Map();
+    for (const [subject, block] of Object.entries(permsBlock)) {
+        // A permission under an undeclared subject is the typo this shape exists to
+        // make impossible: `Requires: profiles/channel:send` against a `profile`
+        // block resolves nowhere, and without this the vocabulary would simply grow
+        // a second subject kind nobody meant to declare.
+        if (!subjects.includes(subject)) {
+            return { ...EMPTY, present: true, invalid: `'${subject}' holds permissions but is not declared under \`subjects\`` };
+        }
+        if (!isRecord(block)) {
+            return { ...EMPTY, present: true, invalid: `\`permissions.${subject}\` is not a mapping of permission name to its declaration` };
+        }
+        for (const [name, body] of Object.entries(block)) {
+            const decl = isRecord(body) ? body : {};
+            const enforced = decl["enforced_by"];
+            byId.set(`${subject}/${name}`, {
+                subject,
+                name,
+                id: `${subject}/${name}`,
+                ...(typeof decl["description"] === "string" ? { description: decl["description"] } : {}),
+                ...(typeof decl["owned_by"] === "string" ? { ownedBy: decl["owned_by"] } : {}),
+                enforcedBy: Array.isArray(enforced) ? enforced.filter((s) => typeof s === "string") : [],
+            });
+        }
+    }
+    return { present: true, subjects, byId };
+}
+//# sourceMappingURL=permissions.js.map

package/dist/core/permissions/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../../src/core/permissions/permissions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The fleet's authorization vocabulary: which permissions exist, and on which\n * kind of subject each one is checked.\n *\n * It is a fleet document rather than a service one because permissions cross\n * services in the shape that matters — a permission a profile holds is owned by\n * whatever service owns profiles and enforced by every service that reads it,\n * and a per-service copy would be N copies of one word. `architecture/` is\n * where the fleet's shared documents already live.\n *\n * The unit is a PAIR, `<subject>/<permission>`, and that is the whole reason\n * this file exists instead of a `Requires:` line joined against OpenAPI's\n * `security`. OpenAPI carries permission NAMES only for oauth2 and\n * openIdConnect — for `http bearer` and `apiKey` the spec requires the scope\n * array to be empty — so a fleet on bearer tokens has nowhere in its contract\n * to say what it checks. And `security` answers only for the CALLER, while a\n * permission is as often checked on an entity inside the request.\n *\n * What this is NOT, deliberately: a domain model. Permissions are a flat list\n * of names under a subject kind — no entities, no relations, no resources.\n * Everything past that has no ground truth to check against, which is the same\n * reason the capability axis stops at declared names\n * (core/capabilities/capabilities.ts) and there is still no AUTHORED capability\n * layer (SCHEMA.md) — a vocabulary loam cannot\n * check is a vocabulary that drifts while looking authoritative. A permission\n * that varies by resource is separate names (`channel:send:sms`,\n * `channel:send:email`) or a column in a scenario's Examples table.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { parse as parseYaml } from \"yaml\";\nimport { isRecord } from \"../kernel/records.js\";\n\n/** One declared permission, under the subject kind it is checked on. */\nexport interface Permission {\n  /** The subject kind — `user`, `profile`, `service`. */\n  subject: string;\n  /** The permission name as `Requires:` spells it, without the subject. */\n  name: string;\n  /** `<subject>/<name>` — the token a requirement writes. */\n  id: string;\n  description?: string;\n  /**\n   * Where the permission is DEFINED — a service id, or `idp` for a vocabulary\n   * some identity provider owns. Never resolved: see `UNCHECKED`. It is here\n   * because \"who would change this\" is the first question a reader asks, and a\n   * blank is a worse answer than an unverified one.\n   */\n  ownedBy?: string;\n  /** Services that CHECK it. Never resolved, for the same reason. */\n  enforcedBy: string[];\n}\n\nexport interface Vocabulary {\n  /** False when `architecture/permissions.yaml` does not exist — not an error. */\n  present: boolean;\n  /** Why the file could not be read as a vocabulary, when it could not. */\n  invalid?: string;\n  /** Declared subject kinds, in declaration order. */\n  subjects: string[];\n  /** Declared permissions, keyed by `<subject>/<name>`. */\n  byId: Map<string, Permission>;\n}\n\nconst EMPTY: Vocabulary = { present: false, subjects: [], byId: new Map() };\n\n/**\n * Read the vocabulary. A missing file is not a finding — a fleet that gates\n * nothing on permissions owes no vocabulary, and the checks that read this stay\n * silent on an absent one exactly as the OpenAPI axis stays silent for a\n * service the landscape shows nobody calls.\n */\nexport async function readVocabulary(path: string): Promise<Vocabulary> {\n  if (!existsSync(path)) return EMPTY;\n  let doc: unknown;\n  try {\n    doc = parseYaml(await readFile(path, \"utf8\"));\n  } catch (e) {\n    return { ...EMPTY, present: true, invalid: e instanceof Error ? e.message : String(e) };\n  }\n  if (doc === null || doc === undefined) return { ...EMPTY, present: true };\n  if (!isRecord(doc)) return { ...EMPTY, present: true, invalid: \"the document is not a mapping\" };\n\n  const subjects = isRecord(doc[\"subjects\"]) ? Object.keys(doc[\"subjects\"]) : [];\n  const permsBlock = doc[\"permissions\"];\n  if (permsBlock === undefined) return { present: true, subjects, byId: new Map() };\n  if (!isRecord(permsBlock)) return { ...EMPTY, present: true, invalid: \"`permissions` is not a mapping of subject kind to permissions\" };\n\n  const byId = new Map<string, Permission>();\n  for (const [subject, block] of Object.entries(permsBlock)) {\n    // A permission under an undeclared subject is the typo this shape exists to\n    // make impossible: `Requires: profiles/channel:send` against a `profile`\n    // block resolves nowhere, and without this the vocabulary would simply grow\n    // a second subject kind nobody meant to declare.\n    if (!subjects.includes(subject)) {\n      return { ...EMPTY, present: true, invalid: `'${subject}' holds permissions but is not declared under \\`subjects\\`` };\n    }\n    if (!isRecord(block)) {\n      return { ...EMPTY, present: true, invalid: `\\`permissions.${subject}\\` is not a mapping of permission name to its declaration` };\n    }\n    for (const [name, body] of Object.entries(block)) {\n      const decl = isRecord(body) ? body : {};\n      const enforced = decl[\"enforced_by\"];\n      byId.set(`${subject}/${name}`, {\n        subject,\n        name,\n        id: `${subject}/${name}`,\n        ...(typeof decl[\"description\"] === \"string\" ? { description: decl[\"description\"] } : {}),\n        ...(typeof decl[\"owned_by\"] === \"string\" ? { ownedBy: decl[\"owned_by\"] } : {}),\n        enforcedBy: Array.isArray(enforced) ? enforced.filter((s): s is string => typeof s === \"string\") : [],\n      });\n    }\n  }\n  return { present: true, subjects, byId };\n}\n"]}

package/dist/core/projection/api.js

@@ -0,0 +1,84 @@
+/**
+ * The OpenAPI half of projecting a feature onto one service: which operations
+ * its contract delta defines, as slots rather than names.
+ *
+ * Moved out of `commands/delta/slices.ts` (rule 8 in docs/DESIGN.md) when
+ * `loam context` became the second caller — a command may not import another
+ * command, and a second copy of a projection is a second chance for the brief
+ * and the pack to disagree about what a feature changes. The answers here are
+ * what `loam delta --json` serializes verbatim, so they are computed once and
+ * never re-derived while printing — a printed number that disagrees with the
+ * payload beside it is the failure this separation prevents.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { readOpenapi } from "../openapi/doc.js";
+import { isRecord } from "../kernel/records.js";
+import { compareIds } from "../repo/entries.js";
+/**
+ * The feature's OpenAPI delta for one service, as slots rather than names.
+ *
+ * The operation set comes from core/openapi/doc.ts — the same structure-aware reader
+ * every other check uses, so this view cannot see an operation validate does not.
+ * `summary` is the one field that reader does not carry, and it is the sentence
+ * an implementer most wants, so it is looked up by the path+method the reader
+ * already resolved: a second read of the same document, never a second opinion
+ * about what an operation IS.
+ */
+export async function apiChanges(openapiPath) {
+    if (!existsSync(openapiPath))
+        return { changes: [], unreadable: false };
+    // `readOpenapi`, not `operations`: the operation list alone cannot tell a
+    // contract that defines nothing from one that could not be read, and this is
+    // the command whose output IS the implementation task.
+    const api = await readOpenapi(openapiPath);
+    if (api.unreadable) {
+        return { changes: [], unreadable: true, ...(api.error === undefined ? {} : { error: api.error }) };
+    }
+    const ops = api.ops;
+    if (ops.length === 0)
+        return { changes: [], unreadable: false };
+    let doc;
+    try {
+        doc = parseYaml(await readFile(openapiPath, "utf8"));
+    }
+    catch {
+        // Unreadable is impossible here (the reader above said otherwise), but a
+        // summary is decoration and must never be the reason a task brief fails to
+        // print.
+        doc = null;
+    }
+    // The summary walk below descends four levels into a document nobody has
+    // validated, and `isRecord` is what it asks at each step: a cast there would
+    // assert a shape the parser never promised, and a sequence or a scalar in any of
+    // those slots would be indexed as a mapping.
+    const summaryOf = (op) => {
+        if (!isRecord(doc))
+            return null;
+        const paths = doc["paths"];
+        if (!isRecord(paths))
+            return null;
+        const item = paths[op.path];
+        if (!isRecord(item))
+            return null;
+        const entry = item[op.method];
+        if (!isRecord(entry))
+            return null;
+        const summary = entry["summary"];
+        return typeof summary === "string" && summary.length > 0 ? summary : null;
+    };
+    return {
+        changes: ops
+            .map((op) => ({
+            path: op.path,
+            method: op.method.toUpperCase(),
+            operationId: op.id,
+            summary: summaryOf(op),
+            remove: op.remove,
+        }))
+            .sort((a, b) => compareIds(a.path, b.path) || compareIds(a.method, b.method)),
+        unreadable: false,
+    };
+}
+//# sourceMappingURL=api.js.map

package/dist/core/projection/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../src/core/projection/api.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The OpenAPI half of projecting a feature onto one service: which operations\n * its contract delta defines, as slots rather than names.\n *\n * Moved out of `commands/delta/slices.ts` (rule 8 in docs/DESIGN.md) when\n * `loam context` became the second caller — a command may not import another\n * command, and a second copy of a projection is a second chance for the brief\n * and the pack to disagree about what a feature changes. The answers here are\n * what `loam delta --json` serializes verbatim, so they are computed once and\n * never re-derived while printing — a printed number that disagrees with the\n * payload beside it is the failure this separation prevents.\n */\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse as parseYaml } from \"yaml\";\nimport { readOpenapi, type Operation } from \"../openapi/doc.js\";\nimport { isRecord } from \"../kernel/records.js\";\nimport { compareIds } from \"../repo/entries.js\";\n\n/**\n * One operation the feature's OpenAPI delta defines for this service. The\n * projection is a task brief, and \"implement createSplit\" without the path and\n * the method is not a task — it is a name to go look up in a file the reader\n * was not told about.\n */\nexport interface ApiChange {\n  path: string;\n  method: string;\n  operationId: string;\n  summary: string | null;\n  /** `x-loam-remove: true` — this operation is being retired, not added. */\n  remove: boolean;\n}\n\n/**\n * The contract axis of the brief: the operations, and whether the document they\n * came from could be read at all.\n *\n * The two have to travel together. A feature `openapi.yaml` that does not parse\n * yields zero operations, which is the same answer as a delta that genuinely\n * changes no endpoints — and this projection is a task brief, so \"no contract\n * work here\" over a YAML error is the vacuously-green trap the architecture\n * axis already guards against.\n */\nexport interface ApiSlice {\n  changes: ApiChange[];\n  unreadable: boolean;\n  /** The parser's own message, when there is one to quote back. */\n  error?: string;\n}\n\n/**\n * The feature's OpenAPI delta for one service, as slots rather than names.\n *\n * The operation set comes from core/openapi/doc.ts — the same structure-aware reader\n * every other check uses, so this view cannot see an operation validate does not.\n * `summary` is the one field that reader does not carry, and it is the sentence\n * an implementer most wants, so it is looked up by the path+method the reader\n * already resolved: a second read of the same document, never a second opinion\n * about what an operation IS.\n */\nexport async function apiChanges(openapiPath: string): Promise<ApiSlice> {\n  if (!existsSync(openapiPath)) return { changes: [], unreadable: false };\n  // `readOpenapi`, not `operations`: the operation list alone cannot tell a\n  // contract that defines nothing from one that could not be read, and this is\n  // the command whose output IS the implementation task.\n  const api = await readOpenapi(openapiPath);\n  if (api.unreadable) {\n    return { changes: [], unreadable: true, ...(api.error === undefined ? {} : { error: api.error }) };\n  }\n  const ops = api.ops;\n  if (ops.length === 0) return { changes: [], unreadable: false };\n  let doc: unknown;\n  try {\n    doc = parseYaml(await readFile(openapiPath, \"utf8\"));\n  } catch {\n    // Unreadable is impossible here (the reader above said otherwise), but a\n    // summary is decoration and must never be the reason a task brief fails to\n    // print.\n    doc = null;\n  }\n  // The summary walk below descends four levels into a document nobody has\n  // validated, and `isRecord` is what it asks at each step: a cast there would\n  // assert a shape the parser never promised, and a sequence or a scalar in any of\n  // those slots would be indexed as a mapping.\n  const summaryOf = (op: Operation): string | null => {\n    if (!isRecord(doc)) return null;\n    const paths = doc[\"paths\"];\n    if (!isRecord(paths)) return null;\n    const item = paths[op.path];\n    if (!isRecord(item)) return null;\n    const entry = item[op.method];\n    if (!isRecord(entry)) return null;\n    const summary = entry[\"summary\"];\n    return typeof summary === \"string\" && summary.length > 0 ? summary : null;\n  };\n  return {\n    changes: ops\n      .map((op): ApiChange => ({\n        path: op.path,\n        method: op.method.toUpperCase(),\n        operationId: op.id,\n        summary: summaryOf(op),\n        remove: op.remove,\n      }))\n      .sort((a, b) => compareIds(a.path, b.path) || compareIds(a.method, b.method)),\n    unreadable: false,\n  };\n}\n"]}

package/dist/core/projection/arch-slice.js

@@ -0,0 +1,63 @@
+/**
+ * The C4 half of projecting a feature onto one service: which services exist,
+ * which the feature introduces, and what its tagged edges add around the one
+ * being projected onto. Moved out of `commands/delta/slices.ts` beside
+ * `./api.ts` and `./events.ts`; named `arch-slice.ts` rather than `arch.ts`
+ * because `core/c4/arch.ts` already exists and a twin name invites the wrong
+ * import.
+ */
+import {} from "../c4/likec4.js";
+import { elementService, serviceResolver } from "../c4/resolve/service.js";
+import { DocsRepoUnavailableError } from "../repo/state.js";
+import { listServices } from "../repo/repo.js";
+/** Every service in the docs repo, or none when there is no docs repo to ask. */
+export async function livingServices(docsDir) {
+    try {
+        return (await listServices(docsDir)).map((s) => s.id);
+    }
+    catch (err) {
+        // "There is no docs repo at all" is a different diagnosis with its own
+        // command (`loam doctor`); turning it into "unknown service" here would
+        // send the reader after a typo that is not there.
+        if (!(err instanceof DocsRepoUnavailableError))
+            throw err;
+        return [];
+    }
+}
+/** Services the feature's C4 delta introduces — its own tagged top-level elements. */
+export function introducedServices(doc, featureId) {
+    if (doc === null || doc.errors.length > 0)
+        return [];
+    return doc.elements.filter((e) => e.tags.includes(featureId)).map(elementService);
+}
+/** The feature's tagged edges around one service, plus whether the service is new. */
+export function archSlice(doc, service, featureId, known) {
+    const empty = { isNew: false, inbound: [], outbound: [], errors: [] };
+    if (doc === null)
+        return empty;
+    const { errors, elements, relationships } = doc;
+    if (errors.length > 0) {
+        return { ...empty, errors: errors.map((e) => (typeof e.line === "number" ? `L${e.line}: ${e.message}` : e.message)) };
+    }
+    // Which service an element stands for is the binding's call, not the title's
+    // — and the enumerated fleet rides in so the slice agrees with `validate`
+    // about an edge drawn into a modelled container. Without it, this projection
+    // told the provider "no inbound calls" and the consumer "you call 'api'" for
+    // the same `checkoutWeb -> paymentService.api` edge the validator was
+    // grading against payment-service — and the brief an agent implements from
+    // must never disagree with the gate it will be checked by.
+    const svcOf = serviceResolver(elements, known);
+    const edge = (r, other) => ({
+        service: other,
+        op: r.op ?? null,
+        title: r.title ?? null,
+    });
+    const featRels = relationships.filter((r) => r.tags.includes(featureId));
+    return {
+        isNew: elements.some((e) => elementService(e) === service && e.tags.includes(featureId)),
+        inbound: featRels.filter((r) => svcOf(r.target) === service).map((r) => edge(r, svcOf(r.source))),
+        outbound: featRels.filter((r) => svcOf(r.source) === service).map((r) => edge(r, svcOf(r.target))),
+        errors: [],
+    };
+}
+//# sourceMappingURL=arch-slice.js.map

package/dist/core/projection/arch-slice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arch-slice.js","sourceRoot":"","sources":["../../../src/core/projection/arch-slice.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The C4 half of projecting a feature onto one service: which services exist,\n * which the feature introduces, and what its tagged edges add around the one\n * being projected onto. Moved out of `commands/delta/slices.ts` beside\n * `./api.ts` and `./events.ts`; named `arch-slice.ts` rather than `arch.ts`\n * because `core/c4/arch.ts` already exists and a twin name invites the wrong\n * import.\n */\nimport { type Elem, type LoadedDoc, type Rel } from \"../c4/likec4.js\";\nimport { elementService, serviceResolver } from \"../c4/resolve/service.js\";\nimport { DocsRepoUnavailableError } from \"../repo/state.js\";\nimport { listServices } from \"../repo/repo.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/** One end of a feature edge, as seen from the projected service. */\nexport interface Edge {\n  service: string;\n  op: string | null;\n  title: string | null;\n}\n\nexport interface ArchSlice {\n  isNew: boolean;\n  inbound: Edge[];\n  outbound: Edge[];\n  errors: string[];\n}\n\n/** Every service in the docs repo, or none when there is no docs repo to ask. */\nexport async function livingServices(docsDir: DocsDir): Promise<string[]> {\n  try {\n    return (await listServices(docsDir)).map((s) => s.id);\n  } catch (err) {\n    // \"There is no docs repo at all\" is a different diagnosis with its own\n    // command (`loam doctor`); turning it into \"unknown service\" here would\n    // send the reader after a typo that is not there.\n    if (!(err instanceof DocsRepoUnavailableError)) throw err;\n    return [];\n  }\n}\n\n/** Services the feature's C4 delta introduces — its own tagged top-level elements. */\nexport function introducedServices(doc: LoadedDoc | null, featureId: string): string[] {\n  if (doc === null || doc.errors.length > 0) return [];\n  return doc.elements.filter((e: Elem) => e.tags.includes(featureId)).map(elementService);\n}\n\n/** The feature's tagged edges around one service, plus whether the service is new. */\nexport function archSlice(\n  doc: LoadedDoc | null,\n  service: string,\n  featureId: string,\n  known?: ReadonlySet<string>,\n): ArchSlice {\n  const empty: ArchSlice = { isNew: false, inbound: [], outbound: [], errors: [] };\n  if (doc === null) return empty;\n\n  const { errors, elements, relationships } = doc;\n  if (errors.length > 0) {\n    return { ...empty, errors: errors.map((e) => (typeof e.line === \"number\" ? `L${e.line}: ${e.message}` : e.message)) };\n  }\n\n  // Which service an element stands for is the binding's call, not the title's\n  // — and the enumerated fleet rides in so the slice agrees with `validate`\n  // about an edge drawn into a modelled container. Without it, this projection\n  // told the provider \"no inbound calls\" and the consumer \"you call 'api'\" for\n  // the same `checkoutWeb -> paymentService.api` edge the validator was\n  // grading against payment-service — and the brief an agent implements from\n  // must never disagree with the gate it will be checked by.\n  const svcOf = serviceResolver(elements, known);\n  const edge = (r: Rel, other: string): Edge => ({\n    service: other,\n    op: r.op ?? null,\n    title: r.title ?? null,\n  });\n  const featRels = relationships.filter((r) => r.tags.includes(featureId));\n\n  return {\n    isNew: elements.some((e) => elementService(e) === service && e.tags.includes(featureId)),\n    inbound: featRels.filter((r) => svcOf(r.target) === service).map((r) => edge(r, svcOf(r.source))),\n    outbound: featRels.filter((r) => svcOf(r.source) === service).map((r) => edge(r, svcOf(r.target))),\n    errors: [],\n  };\n}\n"]}

package/dist/core/projection/events.js

@@ -0,0 +1,34 @@
+/**
+ * The AsyncAPI half of projecting a feature onto one service — the event-axis
+ * mirror of `./api.ts`, moved out of `commands/delta/slices.ts` with it for
+ * the same second-caller reason.
+ */
+import { existsSync } from "node:fs";
+import { readAsyncapi } from "../asyncapi/read.js";
+/**
+ * The feature's AsyncAPI delta for one service, as slots rather than names —
+ * the event-axis mirror of `apiChanges`, read through `core/asyncapi/read.ts`
+ * so this view cannot see a message validate does not. Like the API slice, it
+ * lists the WHOLE document, restated living slots included: the delta is a
+ * complete document, and which slots are new is `loam validate`'s question.
+ */
+export async function eventChanges(asyncapiPath) {
+    if (!existsSync(asyncapiPath))
+        return { changes: [], unreadable: false };
+    const doc = await readAsyncapi(asyncapiPath);
+    if (doc.unreadable) {
+        return { changes: [], unreadable: true, ...(doc.error === undefined ? {} : { error: doc.error }) };
+    }
+    const sent = new Set(doc.sent);
+    const received = new Set(doc.received);
+    return {
+        changes: doc.messages.map((m) => ({
+            slot: m.slot,
+            message: m.name,
+            direction: sent.has(m.name) ? "send" : received.has(m.name) ? "receive" : null,
+            remove: m.remove === true,
+        })),
+        unreadable: false,
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/core/projection/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/core/projection/events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AA+BnD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,YAAoB;IACrD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACzE,MAAM,GAAG,GAAG,MAAM,YAAY,CAAC,YAAY,CAAC,CAAC;IAC7C,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;QACnB,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;IACrG,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,OAAO;QACL,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAChC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,IAAI;YACf,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;YAC9E,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,IAAI;SAC1B,CAAC,CAAC;QACH,UAAU,EAAE,KAAK;KAClB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The AsyncAPI half of projecting a feature onto one service — the event-axis\n * mirror of `./api.ts`, moved out of `commands/delta/slices.ts` with it for\n * the same second-caller reason.\n */\nimport { existsSync } from \"node:fs\";\nimport { readAsyncapi } from \"../asyncapi/read.js\";\n\n/**\n * One message declaration the feature's AsyncAPI delta carries for this\n * service. `slot` is where it is declared — `components.messages.<key>`, or an\n * inline `channels.<ck>.messages.<mk>` — the same spelling the validate\n * findings use; `message` is the join token an edge's `metadata { publishes }`\n * and a requirement's `Publishes:` line name.\n */\nexport interface EventChange {\n  slot: string;\n  message: string;\n  /**\n   * What the document's own operations do with the message: `send`, `receive`,\n   * or null when no operation reaches it (declared but not wired — and always\n   * null for a removal, whose marker joins nothing). A name both sent and\n   * received reports `send`: the producer's side owns the contract.\n   */\n  direction: \"send\" | \"receive\" | null;\n  /** `x-loam-remove: true` — this declaration retires the slot, not adds it. */\n  remove: boolean;\n}\n\n/** The event axis of the brief. Same discipline as ApiSlice: the changes and the document's readability travel together. */\nexport interface EventSlice {\n  changes: EventChange[];\n  unreadable: boolean;\n  /** The parser's own message, when there is one to quote back. */\n  error?: string;\n}\n\n/**\n * The feature's AsyncAPI delta for one service, as slots rather than names —\n * the event-axis mirror of `apiChanges`, read through `core/asyncapi/read.ts`\n * so this view cannot see a message validate does not. Like the API slice, it\n * lists the WHOLE document, restated living slots included: the delta is a\n * complete document, and which slots are new is `loam validate`'s question.\n */\nexport async function eventChanges(asyncapiPath: string): Promise<EventSlice> {\n  if (!existsSync(asyncapiPath)) return { changes: [], unreadable: false };\n  const doc = await readAsyncapi(asyncapiPath);\n  if (doc.unreadable) {\n    return { changes: [], unreadable: true, ...(doc.error === undefined ? {} : { error: doc.error }) };\n  }\n  const sent = new Set(doc.sent);\n  const received = new Set(doc.received);\n  return {\n    changes: doc.messages.map((m) => ({\n      slot: m.slot,\n      message: m.name,\n      direction: sent.has(m.name) ? \"send\" : received.has(m.name) ? \"receive\" : null,\n      remove: m.remove === true,\n    })),\n    unreadable: false,\n  };\n}\n"]}

package/dist/core/provenance/findings.js

@@ -0,0 +1,208 @@
+/**
+ * Provenance checks: is this artifact anchored to anything, and has anyone
+ * vouched for it?
+ *
+ * SCHEMA.md has declared `status` / `owner` / `sources` / `last_verified` since
+ * the beginning and nothing read them. They matter more now that the prose is
+ * written by an agent: coherence proves the corpus agrees with itself, and only
+ * `sources` says it has anything to do with the code.
+ *
+ * Absence and contradiction are graded differently on purpose. A missing field
+ * is incompleteness — a warning, something to work through. A field that says
+ * the wrong thing (a spec claiming to be another service, a status nobody
+ * defined) is a bug, and gates.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { parseFrontmatter, readFrontmatter, stringField, FEATURE_STATUSES, SERVICE_STATUSES, } from "../document/frontmatter.js";
+import { featurePaths, SPEC_AXES } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { readVouchScope } from "./sample/scope.js";
+import { sourceFindings } from "./sources.js";
+import { contentDigest } from "./stamp.js";
+/** Fields every artifact is expected to carry, beyond its identity and status. */
+const EXPECTED = ["owner"];
+export async function serviceProvenance(docsDir, service, opts = {}) {
+    const paths = await locateServicePaths(docsDir, service, opts.fleet);
+    const findings = [];
+    // Both requirement-carrying specs get the same pass: arch.spec.md follows
+    // spec.md's frontmatter conventions exactly, so the checks are one loop —
+    // only the label tells a reader which file moved. The pair comes from
+    // SPEC_AXES rather than being respelled, so a third axis is graded here the
+    // day it is declared instead of the day somebody notices.
+    for (const { path, file } of SPEC_AXES.map((axis) => ({ path: paths[axis.key], file: axis.file }))) {
+        if (!existsSync(path))
+            continue;
+        const raw = await readFile(path, "utf8");
+        const fm = parseFrontmatter(raw);
+        const label = `${service}: ${file}`;
+        findings.push(...identityFindings(fm, {
+            label,
+            idField: "service",
+            idValue: service,
+            statuses: [...SERVICE_STATUSES],
+        }));
+        // With no frontmatter at all, "it names no sources" says nothing the missing
+        // header did not already say — and a malformed one proves nothing either:
+        // `sources.absent` against a header nobody can read is the same false
+        // advice as the field cascade, so frontmatter.malformed stands alone.
+        if (fm.present && !fm.malformed) {
+            findings.push(...(await sourceFindings(fm, service, label, opts.repoDir)));
+            findings.push(...contentFindings(fm, raw, service, label));
+            findings.push(...scopeFindings(fm, service, label));
+        }
+    }
+    return findings;
+}
+export async function featureProvenance(featureDir, featureId) {
+    const path = featurePaths(featureDir).intent;
+    if (!existsSync(path))
+        return [];
+    const fm = await readFrontmatter(path);
+    return identityFindings(fm, {
+        label: "intent.md",
+        idField: "feature",
+        idValue: featureId,
+        statuses: [...FEATURE_STATUSES],
+    });
+}
+function identityFindings(fm, spec) {
+    const findings = [];
+    if (!fm.present) {
+        return [
+            {
+                severity: "warn",
+                code: "frontmatter.missing",
+                subject: spec.idValue,
+                message: `${spec.label} has no frontmatter — no owner, no status, no link to the code it describes`,
+            },
+        ];
+    }
+    // One honest error instead of the cascade: with an unreadable header the
+    // field checks below would grade owner/status/service "missing" and send the
+    // author adding fields to a block YAML refuses to parse. Nothing can be
+    // concluded from a header nobody can read — including that it lacks fields.
+    if (fm.malformed) {
+        return [
+            {
+                severity: "error",
+                code: "frontmatter.malformed",
+                subject: spec.idValue,
+                message: `${spec.label} has frontmatter that does not parse as YAML — owner, status and sources are unreadable until the header is fixed`,
+            },
+        ];
+    }
+    const id = stringField(fm, spec.idField);
+    if (id !== undefined && id !== spec.idValue) {
+        findings.push({
+            severity: "error",
+            code: "frontmatter.field-mismatch",
+            subject: spec.idValue,
+            message: `${spec.label} declares ${spec.idField}: ${id}, but it lives under ${spec.idValue}`,
+        });
+    }
+    const status = stringField(fm, "status");
+    if (status !== undefined && !spec.statuses.includes(status)) {
+        findings.push({
+            severity: "error",
+            code: "frontmatter.status-unknown",
+            subject: spec.idValue,
+            message: `${spec.label} has status '${status}' — expected one of ${spec.statuses.join(", ")}`,
+        });
+    }
+    const missing = [
+        ...(id === undefined ? [spec.idField] : []),
+        ...(status === undefined ? ["status"] : []),
+        ...EXPECTED.filter((f) => stringField(fm, f) === undefined),
+    ];
+    if (missing.length > 0) {
+        findings.push({
+            severity: "warn",
+            code: "frontmatter.field-missing",
+            subject: spec.idValue,
+            message: `${spec.label} is missing ${missing.length} frontmatter field(s)`,
+            details: missing,
+            text: { detailPrefix: "- " },
+        });
+    }
+    return findings;
+}
+/**
+ * The doc-side half of the freshness check. `sources_digest` says whether the
+ * CODE moved since a person looked, and only that service's repo can recompute
+ * it; `content_digest` says whether the DOCUMENT did, and needs nothing but
+ * the document — so this runs wherever the spec is readable, `--service` and
+ * `--all` alike. Without it, editing a spec after it was vouched left
+ * `status: verified` standing over words nobody read — forged freshness, in
+ * the exact agent-written-prose threat model this layer exists for.
+ */
+function contentFindings(fm, raw, service, label) {
+    if (stringField(fm, "status") !== "verified")
+        return [];
+    const stamped = stringField(fm, "content_digest");
+    // A verified doc with no stamp predates the field. Quiet on purpose: the fix
+    // is re-vouching, and grading years of pre-feature vouches as suspect would
+    // drown the fleet in warnings nobody chose.
+    if (stamped === undefined)
+        return [];
+    if (contentDigest(raw) === stamped)
+        return [];
+    const since = stringField(fm, "last_verified") ?? "it was vouched";
+    return [
+        {
+            // A warning, not an error — the sources.stale doctrine: the doc changed
+            // since it was vouched, and only a person can say whether verified still
+            // holds of the new words.
+            severity: "warn",
+            code: "content.stale",
+            message: `${label} changed since ${since} — the doc moved under its vouch, and only a person can say whether 'verified' still holds. Run \`loam vouch --pack --service ${service}\` for what to re-read, then \`loam vouch --service ${service}\`.`,
+        },
+    ];
+}
+/**
+ * The other half of what a stamp can hide: a `verified` document that a person
+ * read only a SAMPLE of.
+ *
+ * `loam vouch --sample <n>` deliberately trades assurance for a vouch that
+ * actually happens, and the trade is only sound while the reduction stays
+ * visible. `status: verified` cannot carry it — that string is a published
+ * contract and the maturity rung `vouched` is derived from it — so the scope
+ * rides beside it in `vouch_scope`, and this is the check that makes a fleet
+ * able to see it: one warning per sampled spec file, with the k/n, the seed
+ * to recompute the sample from, and the one action that clears it.
+ *
+ * A WARNING, following the `sources.stale` / `content.stale` doctrine: the
+ * document is not wrong, it is incompletely read, and only a person can close
+ * that. Warnings never gate, which is exactly what a fleet adopting sampling
+ * as policy needs — and a fleet that wants to gate on it branches on the code
+ * in its own CI, which is what stable codes are for.
+ *
+ * Doc-side, like `content.stale`: it needs no service repo, so it fires from
+ * the docs repo under `--service` and `--all` alike. A scope that does not
+ * decode still fires, saying so — `isSampled` asks about PRESENCE, because a
+ * mangled field must never be the way a partial read is promoted to a full
+ * one.
+ */
+function scopeFindings(fm, service, label) {
+    if (stringField(fm, "status") !== "verified")
+        return [];
+    const stamp = readVouchScope(fm);
+    if (stamp.kind === "none")
+        return [];
+    const when = stringField(fm, "last_verified");
+    const said = stamp.kind === "unreadable"
+        ? `carries a vouch_scope that does not decode (${stamp.text === null ? "its value is not text at all" : `\`${stamp.text}\``}), so it is graded as sampled — an unreadable scope must never read as a full vouch`
+        : `was vouched from a sample: ${stamp.scope.sections} of ${stamp.scope.of} section(s) were read${when === undefined ? "" : ` on ${when}`}, ` +
+            `chosen by seed ${stamp.scope.seed} — the other ${stamp.scope.of - stamp.scope.sections} were read by nobody`;
+    return [
+        {
+            severity: "warn",
+            code: "sources.sampled-vouch",
+            subject: service,
+            message: `${label} ${said}. \`status: verified\` stands over the whole document either way. Only a person can clear ` +
+                `it, by reading the rest and running a full \`loam vouch --service ${service}\` (no --sample); ` +
+                `\`loam vouch --pack --service ${service}\` lists what that sample left unread.`,
+        },
+    ];
+}
+//# sourceMappingURL=findings.js.map