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

package/dist/core/asyncapi/merge/pin.js.map

@@ -1 +1 @@
-{"version":3,"file":"pin.js","sourceRoot":"","sources":["../../../../src/core/asyncapi/merge/pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,UAAU,GAEX,MAAM,cAAc,CAAC;AA2BtB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB,EAAE,UAAkB,EAAE,OAAe;IACvF,MAAM,GAAG,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IACvC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,CAAC;IACpG,uBAAuB,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,SAAkB,CAAC;IACvB,IAAI,WAAoB,CAAC;IACzB,IAAI,CAAC;QACH,SAAS,GAAG,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,CAAC;QACzG,uBAAuB,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,WAAW,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IACpC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,kBAAkB;YAAE,MAAM,KAAK,CAAC;QACrD,MAAM,IAAI,kBAAkB,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAC/G,MAAM,IAAI,GAAsB,EAAE,CAAC;IACnC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5C,sEAAsE;QACtE,qEAAqE;QACrE,+DAA+D;QAC/D,IAAI,IAAI,CAAC,MAAM;YAAE,SAAS;QAE1B,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;QACpD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;QAClC,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAChE,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAClH,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;YACpE,SAAS;QACX,CAAC;QACD,mEAAmE;QACnE,uEAAuE;QACvE,yEAAyE;QACzE,oEAAoE;QACpE,oEAAoE;QACpE,qEAAqE;QACrE,oEAAoE;QACpE,wEAAwE;QACxE,uEAAuE;QACvE,+BAA+B;QAC/B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACnD,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,SAAS;QACX,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACtF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;QAC9C,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IAED,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC;IACxC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;AACH,CAAC","sourcesContent":["/**\n * The pin that tells a QUOTE from an EDIT, on the event axis.\n *\n * A feature's asyncapi.yaml is a complete document, so most of what it spells\n * is quotation: the author restated the living contract around the slot they\n * were changing. Without a pin the merge cannot tell the two apart and\n * upserts both — the exact silent-revert the OpenAPI axis's pin closed, with\n * no overlap between two features required, just two deltas over one service.\n *\n * Separate from `./merge.ts` because this is `loam rebase`'s half: it plans\n * the pins a delta is missing, while the merge only ever reads pins already\n * written. Slot-keyed over the three named sections exactly as the merge\n * upserts (core/asyncapi/digest.ts owns the walker and the section→path\n * spelling); an inline channel message is channel-slot interior and is never\n * pinned on its own — SCHEMA.md's recorded decision.\n */\nimport { isMap, parseDocument } from \"yaml\";\nimport { AsyncapiMergeError, errorMessage } from \"./error.js\";\nimport { refuseAmbiguousSlotKeys, slotPair } from \"./markers.js\";\nimport {\n  ASYNCAPI_BASELINE_KEY,\n  asyncapiSlots,\n  slotDigest,\n  type AsyncapiSection,\n} from \"../digest.js\";\n\n/** What happened to one slot's `x-loam-based-on`. */\nexport interface AsyncapiSlotPin {\n  section: AsyncapiSection;\n  key: string;\n  status:\n    /** It had no pin and now has one. */\n    | \"pinned\"\n    /** It named an older living version; it now names the current one. */\n    | \"repinned\"\n    /** It already named the current living version — no write. */\n    | \"unchanged\"\n    /** The living contract has no slot at this (section, key): this feature is adding it. */\n    | \"unresolved\"\n    /** Written as a YAML alias (one shared value backs every use) or under a key no string can address — loam will not stamp through either. */\n    | \"unwritable\";\n  from: string | null;\n  to: string | null;\n}\n\nexport interface AsyncapiPinPlan {\n  /** The rewritten contract, or null when no pin changes. */\n  text: string | null;\n  pins: AsyncapiSlotPin[];\n}\n\n/**\n * Pin every slot in a feature contract against the living one — what\n * `loam rebase` writes on this axis.\n *\n * The pin is always `slotDigest` of the LIVING slot, never of the delta's\n * own, and that single rule produces both merge verdicts by itself: a slot\n * the author only QUOTED is byte-equal to living, so its pin equals its own\n * content and classifies as a quote; one the author EDITED differs from its\n * pin, so the merge writes it. A slot the living document lacks is\n * `unresolved` and correct — there is no living version of a channel,\n * operation or message the contract does not carry yet.\n */\nexport function pinAsyncapiSlots(featureText: string, livingText: string, service: string): AsyncapiPinPlan {\n  const doc = parseDocument(featureText);\n  if (doc.errors.length > 0) throw new AsyncapiMergeError(\"feature\", service, doc.errors[0]!.message);\n  refuseAmbiguousSlotKeys(doc, \"feature\", service);\n  let featPlain: unknown;\n  let livingPlain: unknown;\n  try {\n    featPlain = doc.toJS() ?? {};\n  } catch (error) {\n    throw new AsyncapiMergeError(\"feature\", service, errorMessage(error));\n  }\n  try {\n    const parsed = parseDocument(livingText);\n    if (parsed.errors.length > 0) throw new AsyncapiMergeError(\"living\", service, parsed.errors[0]!.message);\n    refuseAmbiguousSlotKeys(parsed, \"living\", service);\n    livingPlain = parsed.toJS() ?? {};\n  } catch (error) {\n    if (error instanceof AsyncapiMergeError) throw error;\n    throw new AsyncapiMergeError(\"living\", service, errorMessage(error));\n  }\n\n  const livingBySlot = new Map(asyncapiSlots(livingPlain).map((slot) => [`${slot.section}\\0${slot.key}`, slot]));\n  const pins: AsyncapiSlotPin[] = [];\n  let edited = false;\n  for (const slot of asyncapiSlots(featPlain)) {\n    // A removal marker asserts a slot rather than restating it, so it has\n    // nothing to be based on; `asyncapi.remove-target-missing/-mismatch`\n    // are what guard it against a living slot that moved under it.\n    if (slot.remove) continue;\n\n    const at = { section: slot.section, key: slot.key };\n    const from = slot.basedOn ?? null;\n    const living = livingBySlot.get(`${slot.section}\\0${slot.key}`);\n    if (living === undefined || living.node === null || typeof living.node !== \"object\" || Array.isArray(living.node)) {\n      pins.push({ ...at, status: \"unresolved\", from, to: null });\n      continue;\n    }\n    const digest = slotDigest(living.node);\n    if (from === digest) {\n      pins.push({ ...at, status: \"unchanged\", from: digest, to: digest });\n      continue;\n    }\n    // Located string-matched through the same door as every other slot\n    // access (markers.ts's slotPair): a channel written `404:` is the YAML\n    // number 404, which a raw `getIn(\"404\")` misses — the miss used to grade\n    // every non-string-keyed slot `unwritable`, with an alias diagnosis\n    // nothing in the document backed, and the gate's own remedy was the\n    // command that had just refused. What stays refused: an aliased slot\n    // value (one shared value backs every use of an anchor, so stamping\n    // through it would pin every other use too — the OpenAPI pin's refusal,\n    // for the same data-loss reason) and a slot whose key is not a scalar,\n    // which no string can address.\n    const pair = slotPair(doc, slot.section, slot.key);\n    if (pair === undefined || !isMap(pair.value)) {\n      pins.push({ ...at, status: \"unwritable\", from, to: null });\n      continue;\n    }\n    pins.push({ ...at, status: from === null ? \"pinned\" : \"repinned\", from, to: digest });\n    pair.value.set(ASYNCAPI_BASELINE_KEY, digest);\n    edited = true;\n  }\n\n  if (!edited) return { text: null, pins };\n  try {\n    return { text: doc.toString(), pins };\n  } catch (error) {\n    throw new AsyncapiMergeError(\"feature\", service, errorMessage(error));\n  }\n}\n"]}
+{"version":3,"file":"pin.js","sourceRoot":"","sources":["../../../../src/core/asyncapi/merge/pin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,UAAU,EACV,OAAO,EACP,UAAU,GAEX,MAAM,cAAc,CAAC;AA2BtB;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB,EAAE,UAAkB,EAAE,OAAe;IACvF,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,aAAa,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACjF,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,aAAa,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAE5E,MAAM,YAAY,GAAG,UAAU,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAsB,EAAE,CAAC;IACnC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5C,sEAAsE;QACtE,qEAAqE;QACrE,+DAA+D;QAC/D,IAAI,IAAI,CAAC,MAAM;YAAE,SAAS;QAE1B,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;QACpD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;QAClC,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAClH,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;YACpE,SAAS;QACX,CAAC;QACD,mEAAmE;QACnE,uEAAuE;QACvE,yEAAyE;QACzE,oEAAoE;QACpE,oEAAoE;QACpE,qEAAqE;QACrE,oEAAoE;QACpE,wEAAwE;QACxE,uEAAuE;QACvE,+BAA+B;QAC/B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACnD,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,SAAS;QACX,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QACtF,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;QAC9C,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IAED,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACzC,0EAA0E;IAC1E,mDAAmD;IACnD,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;AAC9F,CAAC","sourcesContent":["/**\n * The pin that tells a QUOTE from an EDIT, on the event axis.\n *\n * A feature's asyncapi.yaml is a complete document, so most of what it spells\n * is quotation: the author restated the living contract around the slot they\n * were changing. Without a pin the merge cannot tell the two apart and\n * upserts both — the exact silent-revert the OpenAPI axis's pin closed, with\n * no overlap between two features required, just two deltas over one service.\n *\n * Separate from `./merge.ts` because this is `loam rebase`'s half: it plans\n * the pins a delta is missing, while the merge only ever reads pins already\n * written. Slot-keyed over the three named sections exactly as the merge\n * upserts (core/asyncapi/digest.ts owns the walker and the section→path\n * spelling); an inline channel message is channel-slot interior and is never\n * pinned on its own — SCHEMA.md's recorded decision.\n */\nimport { isMap } from \"yaml\";\nimport { writeTreeOver } from \"../../openapi/contract-tree.js\";\nimport { asyncapiRefusal } from \"./error.js\";\nimport { readEventTree, slotPair } from \"./markers.js\";\nimport {\n  ASYNCAPI_BASELINE_KEY,\n  asyncapiSlots,\n  slotDigest,\n  slotKey,\n  slotsByKey,\n  type AsyncapiSection,\n} from \"../digest.js\";\n\n/** What happened to one slot's `x-loam-based-on`. */\nexport interface AsyncapiSlotPin {\n  section: AsyncapiSection;\n  key: string;\n  status:\n    /** It had no pin and now has one. */\n    | \"pinned\"\n    /** It named an older living version; it now names the current one. */\n    | \"repinned\"\n    /** It already named the current living version — no write. */\n    | \"unchanged\"\n    /** The living contract has no slot at this (section, key): this feature is adding it. */\n    | \"unresolved\"\n    /** Written as a YAML alias (one shared value backs every use) or under a key no string can address — loam will not stamp through either. */\n    | \"unwritable\";\n  from: string | null;\n  to: string | null;\n}\n\nexport interface AsyncapiPinPlan {\n  /** The rewritten contract, or null when no pin changes. */\n  text: string | null;\n  pins: AsyncapiSlotPin[];\n}\n\n/**\n * Pin every slot in a feature contract against the living one — what\n * `loam rebase` writes on this axis.\n *\n * The pin is always `slotDigest` of the LIVING slot, never of the delta's\n * own, and that single rule produces both merge verdicts by itself: a slot\n * the author only QUOTED is byte-equal to living, so its pin equals its own\n * content and classifies as a quote; one the author EDITED differs from its\n * pin, so the merge writes it. A slot the living document lacks is\n * `unresolved` and correct — there is no living version of a channel,\n * operation or message the contract does not carry yet.\n */\nexport function pinAsyncapiSlots(featureText: string, livingText: string, service: string): AsyncapiPinPlan {\n  const { doc, plain: featPlain } = readEventTree(featureText, \"feature\", service);\n  const { plain: livingPlain } = readEventTree(livingText, \"living\", service);\n\n  const livingBySlot = slotsByKey(asyncapiSlots(livingPlain));\n  const pins: AsyncapiSlotPin[] = [];\n  let edited = false;\n  for (const slot of asyncapiSlots(featPlain)) {\n    // A removal marker asserts a slot rather than restating it, so it has\n    // nothing to be based on; `asyncapi.remove-target-missing/-mismatch`\n    // are what guard it against a living slot that moved under it.\n    if (slot.remove) continue;\n\n    const at = { section: slot.section, key: slot.key };\n    const from = slot.basedOn ?? null;\n    const living = livingBySlot.get(slotKey(slot));\n    if (living === undefined || living.node === null || typeof living.node !== \"object\" || Array.isArray(living.node)) {\n      pins.push({ ...at, status: \"unresolved\", from, to: null });\n      continue;\n    }\n    const digest = slotDigest(living.node);\n    if (from === digest) {\n      pins.push({ ...at, status: \"unchanged\", from: digest, to: digest });\n      continue;\n    }\n    // Located string-matched through the same door as every other slot\n    // access (markers.ts's slotPair): a channel written `404:` is the YAML\n    // number 404, which a raw `getIn(\"404\")` misses — the miss used to grade\n    // every non-string-keyed slot `unwritable`, with an alias diagnosis\n    // nothing in the document backed, and the gate's own remedy was the\n    // command that had just refused. What stays refused: an aliased slot\n    // value (one shared value backs every use of an anchor, so stamping\n    // through it would pin every other use too — the OpenAPI pin's refusal,\n    // for the same data-loss reason) and a slot whose key is not a scalar,\n    // which no string can address.\n    const pair = slotPair(doc, slot.section, slot.key);\n    if (pair === undefined || !isMap(pair.value)) {\n      pins.push({ ...at, status: \"unwritable\", from, to: null });\n      continue;\n    }\n    pins.push({ ...at, status: from === null ? \"pinned\" : \"repinned\", from, to: digest });\n    pair.value.set(ASYNCAPI_BASELINE_KEY, digest);\n    edited = true;\n  }\n\n  if (!edited) return { text: null, pins };\n  // Over the author's text, so the pins are the only lines this run changes\n  // (`writeTreeOver` says what re-serializing cost).\n  return { text: writeTreeOver(doc, featureText, asyncapiRefusal(\"feature\", service)), pins };\n}\n"]}

package/dist/core/asyncapi/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/core/asyncapi/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * The read model of one AsyncAPI document — what `./read.ts`'s walk produces\n * and every consumer of the axis branches on. Split from `read.ts` when the\n * `asyncapiFromText` extraction pushed that module past the 300-line ceiling:\n * the walk and its result are two subjects (`read.ts` says HOW a document is\n * read, this file says WHAT a read answers), and the type block is the seam\n * that already existed. The doctrine comments travel with the fields they\n * explain — they are the documentation of the model, not of the walk.\n */\n\n/** One message declaration, as the reader sees it. */\nexport interface EventMessage {\n  /**\n   * The join token — what a landscape edge's `metadata { publishes }` and a\n   * requirement's `Publishes:` line name.\n   *\n   * The Message Object's own `name` when it has one, otherwise the key it is\n   * declared under. Both are legal AsyncAPI, and the key is what an author who\n   * never wrote a `name` would reasonably expect to reference; falling back to\n   * it means a minimal hand-written contract still joins to the spine.\n   */\n  name: string;\n  /**\n   * Where it was declared — `components.messages.<key>` or\n   * `channels.<key>.messages.<key>`. Carried so `asyncapi.duplicate-message` can\n   * name both slots instead of only saying that a name repeats, the way\n   * `openapi.duplicate-operationid` names both `METHOD /path` slots.\n   */\n  slot: string;\n  /**\n   * Present when the declaration's payload defines no shape a consumer could\n   * code against (`payloadUndeclared`, depth.ts). Set only when true, and\n   * never set for a payload declaring a non-JSON `schemaFormat`.\n   */\n  payloadEmpty?: true;\n  /**\n   * Present when the declaration carries `x-loam-remove: true` — a FEATURE\n   * delta retiring it. A marker asserts a slot rather than declaring a\n   * message, so it joins nothing: excluded from sent/received and from\n   * duplicate counting, the discipline `core/openapi/doc.ts` set for\n   * operation markers. Set only when true, like `payloadEmpty`.\n   */\n  remove?: true;\n}\n\n/** The parse of one AsyncAPI document: what it declares, and whether it could be read at all. */\nexport interface AsyncapiDoc {\n  /** Every message declaration in the document, in document order. */\n  messages: EventMessage[];\n  /** Message names reachable from an `action: send` operation — what this service PRODUCES. */\n  sent: string[];\n  /** Message names reachable from an `action: receive` operation — what this service CONSUMES. */\n  received: string[];\n  /**\n   * Names declared in more than one slot. Every join on this axis is by name, so\n   * two slots claiming one name is the same ambiguity `openapi.duplicate-operationid`\n   * grades: the join picks one arbitrarily and the other declaration is invisible.\n   */\n  duplicateNames: string[];\n  /**\n   * True when the file EXISTS but cannot be read as an AsyncAPI document —\n   * broken YAML, non-UTF-8 bytes, or a document that is not a mapping. A missing\n   * file is not unreadable (absence is `service.no-asyncapi`'s question), and an\n   * empty one parses to null and honestly declares nothing.\n   */\n  unreadable: boolean;\n  /** The parser's own message, when there is one to quote back. */\n  error?: string;\n  /** Internal `#/` refs that resolve to nothing in this document (depth.ts). */\n  danglingRefs: string[];\n  /**\n   * Where `x-loam-remove: true` appears — at ANY depth (digest.ts's\n   * `removalMarkerPaths`): the three slot depths the format spec gives the\n   * key meaning at, inline channel messages (channel-slot interior the merge\n   * strips at that nested depth), and every place the key means nothing —\n   * the document root, `info`, a `components` sibling. Feature-only\n   * bookkeeping wherever it sits: `validate` grades any of these in a LIVING\n   * contract as `asyncapi.remove-marker-living`, and the sweep is as deep as\n   * the strip so a leaked marker can never be invisible to it.\n   */\n  markers: string[];\n}\n"]}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/core/asyncapi/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * The read model of one AsyncAPI document — what `./read.ts`'s walk produces\n * and every consumer of the axis branches on. Split from `read.ts` when the\n * `asyncapiFromText` extraction pushed that module past the 300-line ceiling:\n * the walk and its result are two subjects (`read.ts` says HOW a document is\n * read, this file says WHAT a read answers), and the type block is the seam\n * that already existed. The doctrine comments travel with the fields they\n * explain — they are the documentation of the model, not of the walk.\n */\n\n/** One message declaration, as the reader sees it. */\nexport interface EventMessage {\n  /**\n   * The join token — what a landscape edge's `metadata { publishes }` and a\n   * requirement's `Publishes:` line name.\n   *\n   * The Message Object's own `name` when it has one, otherwise the key it is\n   * declared under. Both are legal AsyncAPI, and the key is what an author who\n   * never wrote a `name` would reasonably expect to reference; falling back to\n   * it means a minimal hand-written contract still joins to the spine.\n   */\n  name: string;\n  /**\n   * Where it was declared — `components.messages.<key>` or\n   * `channels.<key>.messages.<key>`. Carried so `asyncapi.duplicate-message` can\n   * name both slots instead of only saying that a name repeats, the way\n   * `openapi.duplicate-operationid` names both `METHOD /path` slots.\n   */\n  slot: string;\n  /**\n   * The declaration plus every internal `$ref` it reaches, transitively — the\n   * OpenAPI axis's `closureDigester` (core/openapi/digest.ts), so a payload\n   * schema factored into `components.schemas` still moves it. Content equality\n   * only, and so inside the stance read.ts states: what `loam diff` compares to\n   * say a message changed, never a join on a payload field. Absent on a removal\n   * marker, which declares nothing to compare.\n   */\n  closureDigest?: string;\n  /**\n   * Present when the declaration's payload defines no shape a consumer could\n   * code against (`payloadUndeclared`, depth.ts). Set only when true, and\n   * never set for a payload declaring a non-JSON `schemaFormat`.\n   */\n  payloadEmpty?: true;\n  /**\n   * Present when the declaration carries `x-loam-remove: true` — a FEATURE\n   * delta retiring it. A marker asserts a slot rather than declaring a\n   * message, so it joins nothing: excluded from sent/received and from\n   * duplicate counting, the discipline `core/openapi/doc.ts` set for\n   * operation markers. Set only when true, like `payloadEmpty`.\n   */\n  remove?: true;\n}\n\n/** The parse of one AsyncAPI document: what it declares, and whether it could be read at all. */\nexport interface AsyncapiDoc {\n  /** Every message declaration in the document, in document order. */\n  messages: EventMessage[];\n  /** Message names reachable from an `action: send` operation — what this service PRODUCES. */\n  sent: string[];\n  /** Message names reachable from an `action: receive` operation — what this service CONSUMES. */\n  received: string[];\n  /**\n   * Names declared in more than one slot. Every join on this axis is by name, so\n   * two slots claiming one name is the same ambiguity `openapi.duplicate-operationid`\n   * grades: the join picks one arbitrarily and the other declaration is invisible.\n   */\n  duplicateNames: string[];\n  /**\n   * True when the file EXISTS but cannot be read as an AsyncAPI document —\n   * broken YAML, non-UTF-8 bytes, or a document that is not a mapping. A missing\n   * file is not unreadable (absence is `service.no-asyncapi`'s question), and an\n   * empty one parses to null and honestly declares nothing.\n   */\n  unreadable: boolean;\n  /** The parser's own message, when there is one to quote back. */\n  error?: string;\n  /** Internal `#/` refs that resolve to nothing in this document (depth.ts). */\n  danglingRefs: string[];\n  /**\n   * Where `x-loam-remove: true` appears — at ANY depth (digest.ts's\n   * `removalMarkerPaths`): the three slot depths the format spec gives the\n   * key meaning at, inline channel messages (channel-slot interior the merge\n   * strips at that nested depth), and every place the key means nothing —\n   * the document root, `info`, a `components` sibling. Feature-only\n   * bookkeeping wherever it sits: `validate` grades any of these in a LIVING\n   * contract as `asyncapi.remove-marker-living`, and the sweep is as deep as\n   * the strip so a leaked marker can never be invisible to it.\n   */\n  markers: string[];\n}\n"]}

package/dist/core/asyncapi/read.js

@@ -3,7 +3,8 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { parse } from "yaml";
 import { danglingRefs, deref, payloadUndeclared } from "./depth.js";
-import { isSlotRemoval, removalMarkerPaths } from "./digest.js";
+import { entriesOf, isSlotRemoval, removalMarkerPaths } from "./digest.js";
+import { closureDigester } from "../openapi/digest.js";
 /**
  * The async contract axis: AsyncAPI 3.0, read the way `core/openapi/doc.ts` reads
  * OpenAPI — a shallow structural walk over the `yaml` parse, never a real
@@ -15,9 +16,20 @@ import { isSlotRemoval, removalMarkerPaths } from "./digest.js";
  * `action: send|receive`, which is the exact analog of an `operationId`; 2.x
  * spells the same thing as `publish`/`subscribe` nested under a channel, where
  * the two words are notoriously ambiguous about whose perspective they take.
- * Supporting one dialect is cheaper than supporting two, and a 2.x document
- * declares no `operations` at all — so it reads as a contract with no messages
- * rather than as a silently mis-parsed one.
+ * Supporting one dialect is cheaper than supporting two. A 2.x (or 1.x)
+ * document declares no `operations` at all, and it used to read as a contract
+ * with no messages: one `asyncapi.yaml` copied in from an older service turned
+ * into a `spine.message-undefined` per landscape edge, a
+ * `spec-event.message-undefined` per requirement and a knock-on
+ * `spine.message-unproduced` on every consumer, none of them naming the
+ * version and every fix text saying "declare the operation" about a file that
+ * does declare it, as `publish`/`subscribe`. That is exactly the false
+ * diagnosis the unreadable policy below exists to prevent, so an older
+ * version now reads as UNREADABLE (`asyncapiDocOf`): one `asyncapi.invalid`
+ * naming the version and the upgrade command, and nothing graded against it.
+ * `loam diff` skips such a document when the base ref holds the same bytes
+ * (core/diff/semantic.ts's `UNTOUCHED_SKIPS`); without that, one unconverted
+ * file suspended the event axis on every run and failed every PR's diff.
  *
  * WHAT THIS READER MUST NEVER DO: join on anything inside a message's `payload`.
  * The payload is JSON Schema today and may be Avro later, and that switch is
@@ -32,7 +44,9 @@ import { isSlotRemoval, removalMarkerPaths } from "./digest.js";
  * slot digests (./digest.ts) are COMPATIBLE with it, not an exception: they
  * hash payload bytes as content equality — a changed payload moves the slot's
  * identity — and content equality is not a join; nothing a digest reads ever
- * contributes a name to the spine.
+ * contributes a name to the spine. The per-message `closureDigest` `loam diff`
+ * compares is the same kind of read followed through `$ref`s: it hashes what
+ * the payload points at, transitively, and still never names a field.
  */
 /*
  * The `EventMessage`/`AsyncapiDoc` read model lives in `./model.ts` — split
@@ -54,12 +68,6 @@ export function messageName(node, key) {
     }
     return key;
 }
-/** Entries of a mapping node, or nothing — every structural read here goes through it. */
-function entriesOf(node) {
-    if (node === null || typeof node !== "object" || Array.isArray(node))
-        return [];
-    return Object.entries(node);
-}
 /**
  * Read an AsyncAPI 3.0 document into the slice loam joins on: the messages it
  * declares, and which of them it sends and receives.
@@ -125,8 +133,24 @@ export function asyncapiDocOf(doc) {
     if (doc === null)
         return empty();
     const root = doc;
+    // A pre-3.0 document is not a 3.0 document with nothing in it, so it takes
+    // the unreadable path rather than the empty one (see the module header).
+    // Only a version that SAYS 1.x or 2.x is refused: a file with no `asyncapi:`
+    // key at all (a hand-trimmed feature delta that restates slots and not the
+    // header) keeps reading as 3.0, and so does any later major, which is a
+    // question for the day it exists rather than a guess made now. A bare `2`
+    // or `2.6` parses as a YAML number, hence the String() and the `$`.
+    const version = root["asyncapi"];
+    if ((typeof version === "string" || typeof version === "number") && /^[12](\.|$)/.test(String(version))) {
+        return {
+            ...empty(),
+            unreadable: true,
+            error: `AsyncAPI ${String(version)}: loam reads AsyncAPI 3.0 only; \`asyncapi convert --target-version=3.0.0\` upgrades it`,
+        };
+    }
     const messages = [];
     const seen = new Map();
+    const closureDigest = closureDigester(root);
     const declare = (name, slot, node) => {
         // A declaration carrying the removal marker asserts a slot rather than
         // declaring a message: it is listed (with `remove`) so the gate can see
@@ -135,7 +159,7 @@ export function asyncapiDocOf(doc) {
             messages.push({ name, slot, remove: true });
             return;
         }
-        messages.push({ name, slot, ...(payloadUndeclared(root, node) ? { payloadEmpty: true } : {}) });
+        messages.push({ name, slot, closureDigest: closureDigest(node), ...(payloadUndeclared(root, node) ? { payloadEmpty: true } : {}) });
         seen.set(name, [...(seen.get(name) ?? []), slot]);
     };
     // `components.messages` — the ordinary place a message is declared.

package/dist/core/asyncapi/read.js.map

@@ -1 +1 @@
-{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/core/asyncapi/read.ts"],"names":[],"mappings":"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","sourcesContent":["import { isUtf8 } from \"node:buffer\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\nimport { danglingRefs, deref, payloadUndeclared } from \"./depth.js\";\nimport { isSlotRemoval, removalMarkerPaths } from \"./digest.js\";\nimport type { AsyncapiDoc, EventMessage } from \"./model.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\n\n/**\n * The async contract axis: AsyncAPI 3.0, read the way `core/openapi/doc.ts` reads\n * OpenAPI — a shallow structural walk over the `yaml` parse, never a real\n * AsyncAPI parser. `@asyncapi/parser` would be a fourth runtime dependency\n * (AGENTS.md: adding one is a product decision), and loam needs a slice of the\n * document so thin that the parser's whole model would be dead weight.\n *\n * 3.0 only, deliberately. Its operations are named top-level objects carrying\n * `action: send|receive`, which is the exact analog of an `operationId`; 2.x\n * spells the same thing as `publish`/`subscribe` nested under a channel, where\n * the two words are notoriously ambiguous about whose perspective they take.\n * Supporting one dialect is cheaper than supporting two, and a 2.x document\n * declares no `operations` at all — so it reads as a contract with no messages\n * rather than as a silently mis-parsed one.\n *\n * WHAT THIS READER MUST NEVER DO: join on anything inside a message's `payload`.\n * The payload is JSON Schema today and may be Avro later, and that switch is\n * meant to be a line in the document (`schemaFormat`) rather than a branch in\n * loam. Every check on this axis joins on a message NAME; nothing joins on a\n * field, and nothing under `payload` may ever contribute one. The day\n * something here reads a `required` array or a `fields` list INTO A JOIN, the\n * Avro migration stops being free. The one look the reader takes inside is\n * `payloadUndeclared` (depth.ts) — a presence probe that checks whether any\n * shape was declared at all, reads key existence and never a value, and skips\n * any payload declaring a non-JSON `schemaFormat`, so the stance holds. The\n * slot digests (./digest.ts) are COMPATIBLE with it, not an exception: they\n * hash payload bytes as content equality — a changed payload moves the slot's\n * identity — and content equality is not a join; nothing a digest reads ever\n * contributes a name to the spine.\n */\n\n/*\n * The `EventMessage`/`AsyncapiDoc` read model lives in `./model.ts` — split\n * there when the `asyncapiFromText` extraction pushed this module past the\n * 300-line ceiling. This module keeps the walk; that one keeps what the walk\n * answers.\n */\n\n/**\n * A message's join token: its `name`, or the key it is declared under.\n * Exported for the merge (./merge/merge.ts), whose removal exactness compares\n * this same spelling — a second definition of the fallback rule is how a\n * marker would delete a message the reader joins under a different name.\n */\nexport function messageName(node: unknown, key: string): string {\n  if (node !== null && typeof node === \"object\" && !Array.isArray(node)) {\n    const name = (node as Record<string, unknown>)[\"name\"];\n    if (typeof name === \"string\" && name.trim().length > 0) return name.trim();\n  }\n  return key;\n}\n\n/** Entries of a mapping node, or nothing — every structural read here goes through it. */\nfunction entriesOf(node: unknown): [string, unknown][] {\n  if (node === null || typeof node !== \"object\" || Array.isArray(node)) return [];\n  return Object.entries(node as Record<string, unknown>);\n}\n\n/**\n * Read an AsyncAPI 3.0 document into the slice loam joins on: the messages it\n * declares, and which of them it sends and receives.\n *\n * The send/receive sets are what make the spine directional, and the direction\n * is not decoration: on the HTTP axis the PROVIDER owns the contract and a\n * consumer's edge is checked against it, while here the PRODUCER owns the\n * message and a consumer joins to it from another repository entirely. That\n * inversion is why `spine.message-unproduced` has no OpenAPI analog.\n *\n * An unreadable document yields empty sets PLUS the `unreadable` flag, the\n * policy every reader here follows: parsers never diagnose. Swallowing the\n * failure into empty sets would make a broken contract indistinguishable from\n * one that declares nothing, and every inbound edge would be graded\n * `spine.message-undefined` — a false diagnosis pointing at the landscape when\n * the truth is this file.\n */\nexport async function readAsyncapi(asyncapiPath: string, context?: FleetContext): Promise<AsyncapiDoc> {\n  if (context !== undefined) return context.readAsyncapi(asyncapiPath);\n  if (!existsSync(asyncapiPath)) return empty();\n  const bytes = await readFile(asyncapiPath);\n  // Bytes that are not UTF-8 are as unreadable as broken YAML and for a worse\n  // reason: `toString(\"utf8\")` substitutes U+FFFD and hands the parser a\n  // document nobody wrote. The openapi axis learned this the same way.\n  if (!isUtf8(bytes)) return { ...empty(), unreadable: true, error: \"file is not valid UTF-8\" };\n  return asyncapiFromText(bytes.toString(\"utf8\"));\n}\n\n/**\n * The same read over text already in hand — the parse half of `readAsyncapi`,\n * split out so `loam diff` can read a contract fetched from a base git ref\n * (core/diff/base-state.ts) without writing it to disk. The YAML-throw catch\n * lives here and nowhere else; `asyncapiDocOf` below owns everything after\n * the parse, and the byte concerns (existence, UTF-8) stay with the reader\n * that holds the bytes.\n */\nexport function asyncapiFromText(text: string): AsyncapiDoc {\n  let doc: unknown;\n  try {\n    doc = parse(text);\n  } catch (e) {\n    return { ...empty(), unreadable: true, error: e instanceof Error ? e.message : String(e) };\n  }\n  return asyncapiDocOf(doc);\n}\n\n/**\n * The same read over an already-parsed root — what the coherence gate's\n * merge simulation grades (core/coherence/events/), where the \"file\" is a\n * document the merge computed and never wrote. One spelling of the walk for\n * both entries, so a simulated contract can never read differently from the\n * living file the archive would produce from it.\n */\nexport function asyncapiDocOf(doc: unknown): AsyncapiDoc {\n  // A scalar or sequence document has no mapping to look `channels` up in, so\n  // nothing can be concluded from it. null (an empty file) stays readable — it\n  // declares nothing, and says so honestly.\n  if (doc !== null && (typeof doc !== \"object\" || Array.isArray(doc))) {\n    return { ...empty(), unreadable: true, error: \"document is not a YAML mapping\" };\n  }\n  if (doc === null) return empty();\n\n  const root = doc as Record<string, unknown>;\n  const messages: EventMessage[] = [];\n  const seen = new Map<string, string[]>();\n  const declare = (name: string, slot: string, node: unknown): void => {\n    // A declaration carrying the removal marker asserts a slot rather than\n    // declaring a message: it is listed (with `remove`) so the gate can see\n    // it, but it joins nothing — not sent/received, not the duplicate count.\n    if (isSlotRemoval(node)) {\n      messages.push({ name, slot, remove: true as const });\n      return;\n    }\n    messages.push({ name, slot, ...(payloadUndeclared(root, node) ? { payloadEmpty: true as const } : {}) });\n    seen.set(name, [...(seen.get(name) ?? []), slot]);\n  };\n\n  // `components.messages` — the ordinary place a message is declared.\n  for (const [key, node] of entriesOf((root[\"components\"] as Record<string, unknown> | undefined)?.[\"messages\"])) {\n    declare(messageName(node, key), `components.messages.${key}`, node);\n  }\n\n  // `channels.<ck>.messages.<mk>` — an entry here is either an ALIAS of a\n  // components declaration (a `$ref`) or an inline declaration of its own. Only\n  // the second is a new slot: counting an alias would report every properly\n  // factored document as declaring each message twice, which is the shape the\n  // spec's own examples use.\n  const channelMessages = new Map<string, string[]>();\n  for (const [ck, channel] of entriesOf(root[\"channels\"])) {\n    // A channel-slot removal retires the whole channel, inline interior\n    // included: nothing under it declares or joins anything any more.\n    if (isSlotRemoval(channel)) {\n      channelMessages.set(ck, []);\n      continue;\n    }\n    const names: string[] = [];\n    for (const [mk, entry] of entriesOf((channel as Record<string, unknown> | null)?.[\"messages\"])) {\n      const isAlias =\n        entry !== null && typeof entry === \"object\" && !Array.isArray(entry) && \"$ref\" in (entry as object);\n      const { node, key } = deref(root, entry, mk);\n      const name = messageName(node, key);\n      // A name whose declaration is being retired stays off the channel's\n      // list, whether the marker sits on the aliased components entry or on\n      // the inline declaration itself — the operation fallback below must\n      // not join through a message the feature is removing.\n      if (!isSlotRemoval(node)) names.push(name);\n      if (!isAlias) declare(name, `channels.${ck}.messages.${mk}`, node);\n    }\n    channelMessages.set(ck, names);\n  }\n\n  const sent = new Set<string>();\n  const received = new Set<string>();\n  for (const [, operation] of entriesOf(root[\"operations\"])) {\n    const op = operation as Record<string, unknown> | null;\n    // An operation-slot removal retires the operation: it contributes no\n    // send/receive whatever its `action` says.\n    if (isSlotRemoval(op)) continue;\n    const action = op?.[\"action\"];\n    if (action !== \"send\" && action !== \"receive\") continue;\n    const into = action === \"send\" ? sent : received;\n    // The channel this operation acts on, by pointer — its key is what the\n    // fallback below indexes.\n    const channelRef = (op?.[\"channel\"] as Record<string, unknown> | undefined)?.[\"$ref\"];\n    const channelKey = typeof channelRef === \"string\" ? channelRef.slice(channelRef.lastIndexOf(\"/\") + 1) : undefined;\n    const listed = op?.[\"messages\"];\n    if (Array.isArray(listed) && listed.length > 0) {\n      for (const entry of listed) {\n        const { node, key } = deref(root, entry, \"\");\n        // A pointer that resolves nowhere contributes no name rather than an\n        // empty one: a phantom \"\" would join to nothing and read as a message\n        // the service produces.\n        if (node === undefined && key === \"\") continue;\n        // A pointer into a declaration being retired joins nothing either —\n        // the marker means the message is leaving the contract.\n        if (isSlotRemoval(node)) continue;\n        const name = messageName(node, key);\n        if (name.length > 0) into.add(name);\n      }\n      continue;\n    }\n    // AsyncAPI 3: an operation that lists no messages applies to every message\n    // of its channel. Omitting the list is the normal shape of a minimal\n    // hand-written contract — exactly what a fleet with no registry writes — so\n    // reading it as \"produces nothing\" would report the common case broken.\n    if (channelKey !== undefined) for (const name of channelMessages.get(channelKey) ?? []) into.add(name);\n  }\n\n  const duplicateNames = [...seen].filter(([, slots]) => slots.length > 1).map(([name]) => name);\n  return {\n    messages,\n    sent: [...sent],\n    received: [...received],\n    duplicateNames,\n    unreadable: false,\n    danglingRefs: danglingRefs(root),\n    // One deep scan rather than pushes scattered through the walk above: the\n    // walk only visits the depths that JOIN, and a marker leaked anywhere\n    // else (the root, `info`) was invisible to the living sweep while the\n    // strip still owed its removal.\n    markers: removalMarkerPaths(root, \"\"),\n  };\n}\n\nfunction empty(): AsyncapiDoc {\n  return { messages: [], sent: [], received: [], duplicateNames: [], unreadable: false, danglingRefs: [], markers: [] };\n}\n\n/** The slots one message name is declared in — what `asyncapi.duplicate-message` names. */\nexport function slotsOf(doc: AsyncapiDoc, name: string): string[] {\n  return doc.messages.filter((m) => m.name === name).map((m) => m.slot);\n}\n\n"]}
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/core/asyncapi/read.ts"],"names":[],"mappings":"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","sourcesContent":["import { isUtf8 } from \"node:buffer\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { parse } from \"yaml\";\nimport { danglingRefs, deref, payloadUndeclared } from \"./depth.js\";\nimport { entriesOf, isSlotRemoval, removalMarkerPaths } from \"./digest.js\";\nimport { closureDigester } from \"../openapi/digest.js\";\nimport type { AsyncapiDoc, EventMessage } from \"./model.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\n\n/**\n * The async contract axis: AsyncAPI 3.0, read the way `core/openapi/doc.ts` reads\n * OpenAPI — a shallow structural walk over the `yaml` parse, never a real\n * AsyncAPI parser. `@asyncapi/parser` would be a fourth runtime dependency\n * (AGENTS.md: adding one is a product decision), and loam needs a slice of the\n * document so thin that the parser's whole model would be dead weight.\n *\n * 3.0 only, deliberately. Its operations are named top-level objects carrying\n * `action: send|receive`, which is the exact analog of an `operationId`; 2.x\n * spells the same thing as `publish`/`subscribe` nested under a channel, where\n * the two words are notoriously ambiguous about whose perspective they take.\n * Supporting one dialect is cheaper than supporting two. A 2.x (or 1.x)\n * document declares no `operations` at all, and it used to read as a contract\n * with no messages: one `asyncapi.yaml` copied in from an older service turned\n * into a `spine.message-undefined` per landscape edge, a\n * `spec-event.message-undefined` per requirement and a knock-on\n * `spine.message-unproduced` on every consumer, none of them naming the\n * version and every fix text saying \"declare the operation\" about a file that\n * does declare it, as `publish`/`subscribe`. That is exactly the false\n * diagnosis the unreadable policy below exists to prevent, so an older\n * version now reads as UNREADABLE (`asyncapiDocOf`): one `asyncapi.invalid`\n * naming the version and the upgrade command, and nothing graded against it.\n * `loam diff` skips such a document when the base ref holds the same bytes\n * (core/diff/semantic.ts's `UNTOUCHED_SKIPS`); without that, one unconverted\n * file suspended the event axis on every run and failed every PR's diff.\n *\n * WHAT THIS READER MUST NEVER DO: join on anything inside a message's `payload`.\n * The payload is JSON Schema today and may be Avro later, and that switch is\n * meant to be a line in the document (`schemaFormat`) rather than a branch in\n * loam. Every check on this axis joins on a message NAME; nothing joins on a\n * field, and nothing under `payload` may ever contribute one. The day\n * something here reads a `required` array or a `fields` list INTO A JOIN, the\n * Avro migration stops being free. The one look the reader takes inside is\n * `payloadUndeclared` (depth.ts) — a presence probe that checks whether any\n * shape was declared at all, reads key existence and never a value, and skips\n * any payload declaring a non-JSON `schemaFormat`, so the stance holds. The\n * slot digests (./digest.ts) are COMPATIBLE with it, not an exception: they\n * hash payload bytes as content equality — a changed payload moves the slot's\n * identity — and content equality is not a join; nothing a digest reads ever\n * contributes a name to the spine. The per-message `closureDigest` `loam diff`\n * compares is the same kind of read followed through `$ref`s: it hashes what\n * the payload points at, transitively, and still never names a field.\n */\n\n/*\n * The `EventMessage`/`AsyncapiDoc` read model lives in `./model.ts` — split\n * there when the `asyncapiFromText` extraction pushed this module past the\n * 300-line ceiling. This module keeps the walk; that one keeps what the walk\n * answers.\n */\n\n/**\n * A message's join token: its `name`, or the key it is declared under.\n * Exported for the merge (./merge/merge.ts), whose removal exactness compares\n * this same spelling — a second definition of the fallback rule is how a\n * marker would delete a message the reader joins under a different name.\n */\nexport function messageName(node: unknown, key: string): string {\n  if (node !== null && typeof node === \"object\" && !Array.isArray(node)) {\n    const name = (node as Record<string, unknown>)[\"name\"];\n    if (typeof name === \"string\" && name.trim().length > 0) return name.trim();\n  }\n  return key;\n}\n\n/**\n * Read an AsyncAPI 3.0 document into the slice loam joins on: the messages it\n * declares, and which of them it sends and receives.\n *\n * The send/receive sets are what make the spine directional, and the direction\n * is not decoration: on the HTTP axis the PROVIDER owns the contract and a\n * consumer's edge is checked against it, while here the PRODUCER owns the\n * message and a consumer joins to it from another repository entirely. That\n * inversion is why `spine.message-unproduced` has no OpenAPI analog.\n *\n * An unreadable document yields empty sets PLUS the `unreadable` flag, the\n * policy every reader here follows: parsers never diagnose. Swallowing the\n * failure into empty sets would make a broken contract indistinguishable from\n * one that declares nothing, and every inbound edge would be graded\n * `spine.message-undefined` — a false diagnosis pointing at the landscape when\n * the truth is this file.\n */\nexport async function readAsyncapi(asyncapiPath: string, context?: FleetContext): Promise<AsyncapiDoc> {\n  if (context !== undefined) return context.readAsyncapi(asyncapiPath);\n  if (!existsSync(asyncapiPath)) return empty();\n  const bytes = await readFile(asyncapiPath);\n  // Bytes that are not UTF-8 are as unreadable as broken YAML and for a worse\n  // reason: `toString(\"utf8\")` substitutes U+FFFD and hands the parser a\n  // document nobody wrote. The openapi axis learned this the same way.\n  if (!isUtf8(bytes)) return { ...empty(), unreadable: true, error: \"file is not valid UTF-8\" };\n  return asyncapiFromText(bytes.toString(\"utf8\"));\n}\n\n/**\n * The same read over text already in hand — the parse half of `readAsyncapi`,\n * split out so `loam diff` can read a contract fetched from a base git ref\n * (core/diff/base-state.ts) without writing it to disk. The YAML-throw catch\n * lives here and nowhere else; `asyncapiDocOf` below owns everything after\n * the parse, and the byte concerns (existence, UTF-8) stay with the reader\n * that holds the bytes.\n */\nexport function asyncapiFromText(text: string): AsyncapiDoc {\n  let doc: unknown;\n  try {\n    doc = parse(text);\n  } catch (e) {\n    return { ...empty(), unreadable: true, error: e instanceof Error ? e.message : String(e) };\n  }\n  return asyncapiDocOf(doc);\n}\n\n/**\n * The same read over an already-parsed root — what the coherence gate's\n * merge simulation grades (core/coherence/events/), where the \"file\" is a\n * document the merge computed and never wrote. One spelling of the walk for\n * both entries, so a simulated contract can never read differently from the\n * living file the archive would produce from it.\n */\nexport function asyncapiDocOf(doc: unknown): AsyncapiDoc {\n  // A scalar or sequence document has no mapping to look `channels` up in, so\n  // nothing can be concluded from it. null (an empty file) stays readable — it\n  // declares nothing, and says so honestly.\n  if (doc !== null && (typeof doc !== \"object\" || Array.isArray(doc))) {\n    return { ...empty(), unreadable: true, error: \"document is not a YAML mapping\" };\n  }\n  if (doc === null) return empty();\n\n  const root = doc as Record<string, unknown>;\n  // A pre-3.0 document is not a 3.0 document with nothing in it, so it takes\n  // the unreadable path rather than the empty one (see the module header).\n  // Only a version that SAYS 1.x or 2.x is refused: a file with no `asyncapi:`\n  // key at all (a hand-trimmed feature delta that restates slots and not the\n  // header) keeps reading as 3.0, and so does any later major, which is a\n  // question for the day it exists rather than a guess made now. A bare `2`\n  // or `2.6` parses as a YAML number, hence the String() and the `$`.\n  const version = root[\"asyncapi\"];\n  if ((typeof version === \"string\" || typeof version === \"number\") && /^[12](\\.|$)/.test(String(version))) {\n    return {\n      ...empty(),\n      unreadable: true,\n      error: `AsyncAPI ${String(version)}: loam reads AsyncAPI 3.0 only; \\`asyncapi convert --target-version=3.0.0\\` upgrades it`,\n    };\n  }\n  const messages: EventMessage[] = [];\n  const seen = new Map<string, string[]>();\n  const closureDigest = closureDigester(root);\n  const declare = (name: string, slot: string, node: unknown): void => {\n    // A declaration carrying the removal marker asserts a slot rather than\n    // declaring a message: it is listed (with `remove`) so the gate can see\n    // it, but it joins nothing — not sent/received, not the duplicate count.\n    if (isSlotRemoval(node)) {\n      messages.push({ name, slot, remove: true as const });\n      return;\n    }\n    messages.push({ name, slot, closureDigest: closureDigest(node), ...(payloadUndeclared(root, node) ? { payloadEmpty: true as const } : {}) });\n    seen.set(name, [...(seen.get(name) ?? []), slot]);\n  };\n\n  // `components.messages` — the ordinary place a message is declared.\n  for (const [key, node] of entriesOf((root[\"components\"] as Record<string, unknown> | undefined)?.[\"messages\"])) {\n    declare(messageName(node, key), `components.messages.${key}`, node);\n  }\n\n  // `channels.<ck>.messages.<mk>` — an entry here is either an ALIAS of a\n  // components declaration (a `$ref`) or an inline declaration of its own. Only\n  // the second is a new slot: counting an alias would report every properly\n  // factored document as declaring each message twice, which is the shape the\n  // spec's own examples use.\n  const channelMessages = new Map<string, string[]>();\n  for (const [ck, channel] of entriesOf(root[\"channels\"])) {\n    // A channel-slot removal retires the whole channel, inline interior\n    // included: nothing under it declares or joins anything any more.\n    if (isSlotRemoval(channel)) {\n      channelMessages.set(ck, []);\n      continue;\n    }\n    const names: string[] = [];\n    for (const [mk, entry] of entriesOf((channel as Record<string, unknown> | null)?.[\"messages\"])) {\n      const isAlias =\n        entry !== null && typeof entry === \"object\" && !Array.isArray(entry) && \"$ref\" in (entry as object);\n      const { node, key } = deref(root, entry, mk);\n      const name = messageName(node, key);\n      // A name whose declaration is being retired stays off the channel's\n      // list, whether the marker sits on the aliased components entry or on\n      // the inline declaration itself — the operation fallback below must\n      // not join through a message the feature is removing.\n      if (!isSlotRemoval(node)) names.push(name);\n      if (!isAlias) declare(name, `channels.${ck}.messages.${mk}`, node);\n    }\n    channelMessages.set(ck, names);\n  }\n\n  const sent = new Set<string>();\n  const received = new Set<string>();\n  for (const [, operation] of entriesOf(root[\"operations\"])) {\n    const op = operation as Record<string, unknown> | null;\n    // An operation-slot removal retires the operation: it contributes no\n    // send/receive whatever its `action` says.\n    if (isSlotRemoval(op)) continue;\n    const action = op?.[\"action\"];\n    if (action !== \"send\" && action !== \"receive\") continue;\n    const into = action === \"send\" ? sent : received;\n    // The channel this operation acts on, by pointer — its key is what the\n    // fallback below indexes.\n    const channelRef = (op?.[\"channel\"] as Record<string, unknown> | undefined)?.[\"$ref\"];\n    const channelKey = typeof channelRef === \"string\" ? channelRef.slice(channelRef.lastIndexOf(\"/\") + 1) : undefined;\n    const listed = op?.[\"messages\"];\n    if (Array.isArray(listed) && listed.length > 0) {\n      for (const entry of listed) {\n        const { node, key } = deref(root, entry, \"\");\n        // A pointer that resolves nowhere contributes no name rather than an\n        // empty one: a phantom \"\" would join to nothing and read as a message\n        // the service produces.\n        if (node === undefined && key === \"\") continue;\n        // A pointer into a declaration being retired joins nothing either —\n        // the marker means the message is leaving the contract.\n        if (isSlotRemoval(node)) continue;\n        const name = messageName(node, key);\n        if (name.length > 0) into.add(name);\n      }\n      continue;\n    }\n    // AsyncAPI 3: an operation that lists no messages applies to every message\n    // of its channel. Omitting the list is the normal shape of a minimal\n    // hand-written contract — exactly what a fleet with no registry writes — so\n    // reading it as \"produces nothing\" would report the common case broken.\n    if (channelKey !== undefined) for (const name of channelMessages.get(channelKey) ?? []) into.add(name);\n  }\n\n  const duplicateNames = [...seen].filter(([, slots]) => slots.length > 1).map(([name]) => name);\n  return {\n    messages,\n    sent: [...sent],\n    received: [...received],\n    duplicateNames,\n    unreadable: false,\n    danglingRefs: danglingRefs(root),\n    // One deep scan rather than pushes scattered through the walk above: the\n    // walk only visits the depths that JOIN, and a marker leaked anywhere\n    // else (the root, `info`) was invisible to the living sweep while the\n    // strip still owed its removal.\n    markers: removalMarkerPaths(root, \"\"),\n  };\n}\n\nfunction empty(): AsyncapiDoc {\n  return { messages: [], sent: [], received: [], duplicateNames: [], unreadable: false, danglingRefs: [], markers: [] };\n}\n\n/** The slots one message name is declared in — what `asyncapi.duplicate-message` names. */\nexport function slotsOf(doc: AsyncapiDoc, name: string): string[] {\n  return doc.messages.filter((m) => m.name === name).map((m) => m.slot);\n}\n\n"]}

package/dist/core/brief/brief.js

@@ -19,15 +19,20 @@
  * ties the result to a repository, which is why the brief argues for it instead
  * of merely listing it.
  */
-import { existsSync, statSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { readdir } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { landscapePath } from "../repo/paths.js";
 import { locateServicePaths } from "../repo/service-target.js";
+import { specAdoption } from "../repo/repo.js";
+import { entryIs } from "../repo/tree/fs.js";
 import { VALIDATE_CHECKS } from "./checks.js";
 import { UNCHECKED } from "./unchecked.js";
-import { landscapeArtifact, landscapeContext } from "./landscape.js";
-import { ARTIFACTS } from "./targets.js";
+import { landscapeContext } from "./landscape.js";
+import { landscapeArtifact } from "./map/owed.js";
+import { exampleFor, extendPoint, FQN } from "./map/extend.js";
+import { ARTIFACTS, USECASES_DIR } from "./targets.js";
+import { EXTERNAL_TAG } from "../vocabulary/maturity.js";
 /**
  * The architecture walk: the order a service is read in, and what each stop is
  * for.
@@ -135,32 +140,87 @@ export async function serviceBrief(docsDir, service, at) {
     const paths = at ?? (await locateServicePaths(docsDir, service));
     const rel = (abs) => relative(docsDir, abs).split(/[\\/]/).join("/");
     // Read before the artifact loop, not after it: what the fleet already says
-    // about this service decides whether it owes an API contract at all.
-    const landscape = await landscapeContext(docsDir, service);
+    // about this service decides whether it owes an API contract at all. The
+    // model path travels with it — located through the enumeration above, never
+    // joined at `services/<id>/` — so the edgeless state can name the calls the
+    // service's own model attests.
+    const landscape = await landscapeContext(docsDir, service, paths);
     const owesApi = apiExpected(landscape);
+    // The one id the model target's grammar and example are written against,
+    // resolved here because `ARTIFACTS` is static on purpose (a target list that
+    // varied per repository would be a second thing to keep true) and because this
+    // is the only place the fleet map has already been read.
+    const extend = extendPoint(landscape);
     const targets = [];
     for (const { key, ...artifact } of ARTIFACTS) {
-        // `adrs/` is a directory, and an empty one is not an existing artifact —
-        // reporting it as present would tell the agent to diff against nothing.
-        const dir = key === "adrsDir";
-        const exists = dir ? await hasMarkdown(paths[key]) : existsSync(paths[key]);
+        // `adrs/` and `usecases/` are DIRECTORIES, and an empty one is not an
+        // existing artifact — reporting it as present would tell the agent to diff
+        // against nothing, and for `usecases/` it would also tell the agent an
+        // optional slot was already taken.
+        //
+        // `usecases/` is the one target with no `ServicePaths` entry, and that is
+        // deliberate rather than an omission: nothing loam checks JOINS on that
+        // path. The slot a service's flows are graded out of is its whole LikeC4
+        // project (`core/usecases/service/flows.ts` reads every `.likec4` under the
+        // directory), so `usecases/<name>.likec4` is a convention this brief
+        // publishes, not a path a writer writes — and `targets.ts` is where a
+        // convention belongs.
+        const ext = key === "adrsDir" ? ".md" : key === "usecasesDir" ? ".likec4" : null;
+        const at = key === "usecasesDir" ? join(paths.dir, USECASES_DIR) : paths[key];
+        const exists = ext === null ? existsSync(at) : await hasEntry(at, ext);
+        const partial = key === "spec" && exists && (await specAdoption(at)) === "partial";
         targets.push({
             ...artifact,
+            ...(partial ? { partial: true } : {}),
             ...(key === "openapi" ? { required: owesApi } : {}),
-            path: dir ? `${rel(paths[key])}/` : rel(paths[key]),
+            // Every `<fqn>` in the model target, replaced by the element this service
+            // actually extends. The placeholder is left literal in `targets.ts` — the
+            // brief is handed to an agent that will WRITE the file, and
+            // `extend <fqn> {` copied verbatim is a document that does not parse.
+            shape: artifact.shape.map((rule) => rule.replaceAll(FQN, extend.id)),
+            ...(artifact.example === undefined ? {} : { example: exampleFor(artifact.example, extend, service) }),
+            path: ext === null ? rel(at) : `${rel(at)}/`,
             exists,
             action: exists ? "diff" : "create",
         });
     }
-    // The eighth target is the fleet map, and it is conditional: a service the
-    // landscape ALREADY resolves an element to owes it nothing, and briefing an
-    // edit there would invite an agent to draw a second box for a service that
-    // has one. Everything else about the target is unconditional — the file is
+    // The eighth target is the fleet map, and it is conditional on TWO facts: an
+    // element resolving to the service, and an edge touching it. A service the
+    // landscape already draws AND reaches owes it nothing, and briefing an edit
+    // there would invite an agent to draw a second box for a service that has
+    // one. A service with a box and no edge — what `loam seed` leaves for every
+    // service nobody listed under `calls:` — owes it the edges, and until
+    // 2026-09-03 element existence alone read as "the map is complete" here, so
+    // the brief declared the map finished for exactly the services it had not
+    // reached. Everything else about the target is unconditional — the file is
     // shared, so `action` is `edit` whenever it exists and `create` only for the
     // very first service of a brand-new docs repo.
-    if (landscape.modelled !== true) {
+    //
+    // `modelled === false` and not `!== true`: `null` is "loam could not read the
+    // map", and it fell through the same branch as "the map genuinely draws
+    // nothing for this service". The brief then handed over the UNDRAWN target —
+    // whose shape rule is "add one top-level element bound to its directory" and
+    // whose example is a block to splice — for services the map already declares
+    // and binds, and an agent that spliced it earned `landscape.binding-duplicate`
+    // for doing exactly what the brief asked. With the map unreadable there is no
+    // write to ask for; `landscape.instruction` carries the whole answer and names
+    // the documents that failed.
+    if (landscape.modelled === false || landscape.touched === false) {
         targets.push({
-            ...landscapeArtifact(service, landscape.expects, landscape.present, rel(paths.dir)),
+            ...landscapeArtifact({
+                service,
+                expects: landscape.expects,
+                present: landscape.present,
+                servicePath: rel(paths.dir),
+                // The existing element's id, in the edgeless state only: it switches
+                // the example from a block to edges on that element.
+                // …and whether it is `#external`, which decides what the shape rule may
+                // promise: `landscape.service-isolated` never fires on such an element.
+                ...(landscape.touched === false && landscape.elements[0] !== undefined
+                    ? { elementId: landscape.elements[0].id, external: landscape.elements[0].tags.includes(EXTERNAL_TAG) }
+                    : {}),
+                attested: landscape.attested,
+            }),
             path: rel(landscapePath(docsDir)),
             exists: landscape.present,
             action: landscape.present ? "edit" : "create",
@@ -180,27 +240,20 @@ export async function serviceBrief(docsDir, service, at) {
         rule: NEVER_OVERWRITE,
     };
 }
-async function hasMarkdown(dir) {
+/**
+ * Does this directory already hold an artifact of the given extension? The
+ * "exists" question for the two DIRECTORY targets — `adrs/` (`.md`) and
+ * `usecases/` (`.likec4`) — where an empty or absent directory is the same
+ * answer, because neither is something to diff against.
+ */
+async function hasEntry(dir, ext) {
     if (!existsSync(dir))
         return false;
     const entries = await readdir(dir, { withFileTypes: true });
-    // `statSync` for the symlink case: a Dirent never follows one, so `isFile()`
-    // is false for a symlinked ADR and the directory reads as empty (repo.ts's
-    // `entryIs` is the same rule for `services/` and `features/`).
-    return entries.some((e) => {
-        if (!e.name.endsWith(".md"))
-            return false;
-        if (e.isFile())
-            return true;
-        if (!e.isSymbolicLink())
-            return false;
-        try {
-            return statSync(join(dir, e.name)).isFile();
-        }
-        catch {
-            return false;
-        }
-    });
+    // `entryIs` for the symlink case: a Dirent never follows one, so `isFile()`
+    // is false for a symlinked ADR and the directory would read as empty — the
+    // same rule `services/` and `features/` are enumerated by.
+    return entries.some((e) => e.name.endsWith(ext) && entryIs(dir, e, "file"));
 }
 /**
  * Does the fleet expect an API of this service?
@@ -215,11 +268,18 @@ async function hasMarkdown(dir) {
  * in `openapi.yaml`'s shape rules (`ARTIFACTS`, targets.ts).
  *
  * Positive evidence only, exactly as `list` reads it: a landscape that is
- * absent or does not parse proves nothing about who calls this service, so the
+ * absent or unreadable proves nothing about who calls this service, so the
  * contract is still owed. `expects` is the ops on inbound edges, which is
  * `list`'s `called` set seen from one service.
+ *
+ * `callersKnown` and not `parses`, because since W4 `parses` answers about the
+ * whole `architecture/` PROJECT: a broken palette or use case beside a landscape
+ * loam reads perfectly made this discard the map and demand an OpenAPI contract
+ * of a browser UI — inventing an API into the source of truth, which is the one
+ * class of guess this module exists to refuse. `callersKnown` is the narrower
+ * fact this question actually needs, and it is the one `list` and `context` read.
  */
 function apiExpected(landscape) {
-    return !landscape.parses || landscape.expects.length > 0;
+    return !landscape.callersKnown || landscape.expects.length > 0;
 }
 //# sourceMappingURL=brief.js.map

package/dist/core/brief/brief.js.map

@@ -1 +1 @@
-{"version":3,"file":"brief.js","sourceRoot":"","sources":["../../../src/core/brief/brief.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The adoption brief: what an agent needs in order to write one service's\n * baseline documentation, and what will be checked when it does.\n *\n * `adopt` was specified for years as \"read the code, emit the C4\". It is not\n * being built, because it cannot be: nothing deterministic reads a legacy\n * service and says what its architecture MEANS, and a guessed model is worse\n * than no model — everyone downstream has to re-derive it to know whether to\n * believe it.\n *\n * So loam takes the half of the job that IS deterministic. It states the work\n * precisely (which files, in which grammar, bound to which existing elements),\n * it says exactly which checks the result will face, and then it says which\n * checks do not exist — because everything in that last list is honesty no\n * validator will ever supply, and an agent that does not know where the checking\n * stops will assume it never does.\n *\n * Nothing here reads code. `sources` in the frontmatter is the only line that\n * ties the result to a repository, which is why the brief argues for it instead\n * of merely listing it.\n */\nimport { existsSync, statSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join, relative } from \"node:path\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { landscapePath, type ServicePaths } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { VALIDATE_CHECKS, type BriefCheck } from \"./checks.js\";\nimport { UNCHECKED } from \"./unchecked.js\";\nimport { landscapeArtifact, landscapeContext, type LandscapeContext } from \"./landscape.js\";\nimport { ARTIFACTS, type BriefTarget } from \"./targets.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/* ------------------------------------------------------------------ */\n/* The walk — what to read, in what order, and where each finding lands */\n/* ------------------------------------------------------------------ */\n\nexport interface WalkStop {\n  /** What to open, named as a thing to go and find rather than a file name. */\n  where: string;\n  /** What to take out of it. */\n  find: string;\n  /** The artifacts this stop feeds, by `artifact` name from `targets[]`. */\n  lands: string[];\n}\n\n/**\n * The architecture walk: the order a service is read in, and what each stop is\n * for.\n *\n * The brief said \"read the code: entry points, HTTP routes and handlers,\n * published events, config, deploy manifests, tests\" — one sentence, six nouns,\n * no order and no landing site. What came back matched the sentence: the HTTP\n * surface documented well, because it is the noun an agent recognises fastest,\n * and the scheduler, the consumer group and the outbox missing entirely. Not\n * because they were judged unimportant — because nothing said to go and look,\n * and every check loam owns is computed from what was written rather than from\n * what is there. `UNCHECKED` has said COMPLETENESS is unverifiable since the\n * beginning; that is an argument for stating the sweep, not for leaving it\n * implied.\n *\n * The order is deliberate and it is not the order a reader browses in. Stops 1\n * and 2 fix the SHAPE of the service — which processes exist at all — before\n * any surface is enumerated, because an agent that starts at the HTTP routes\n * has already concluded the service is an API by the time it meets the\n * scheduler. Everything after them is one surface each.\n *\n * `lands` names artifacts rather than describing them, because the two lists\n * are joined: test/agent-contract.test.ts requires every name here to be a\n * target the same brief hands over, so a stop can never feed a file nobody was\n * asked to write.\n */\nexport const WALK: WalkStop[] = [\n  {\n    where: \"the build and dependency manifests — pom.xml, build.gradle, package.json, go.mod, requirements.txt, and whatever the repo's own README calls the build\",\n    find: \"what this service is built from, and every client library it links against. A broker client, an HTTP client, a database driver: each one is a dependency that has to appear as an edge or a container later, and this list is the only place they are all named at once. A library whose SEMANTICS decide behaviour — a retry budget, a delivery guarantee, a serialization format — is an arch requirement (arch.spec.md), not a fact to leave in your head.\",\n    lands: [\"model.likec4\", \"runbook.md\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the entry points — main/Application/server bootstrap, the DI or module wiring, and anything the deploy manifests actually start\",\n    find: \"how many PROCESSES this service is, and what each one is. An API, a worker, a scheduler, a consumer — a service that is three of those and documented as one is the most common way a baseline is wrong, and it is wrong in a shape no later check can see.\",\n    lands: [\"model.likec4\"],\n  },\n  {\n    where: \"the HTTP surface — every route, controller, handler and middleware, counted\",\n    find: \"the operation set, in full, and inside each operation the DECISIONS its code makes: the permission and role checks — each one is a `Requires:` entry, and a name `architecture/permissions.yaml` does not declare yet is a line to ADD to that shared file, never to invent locally — the fields required only when another field is present, the defaults and normalisations applied before anything is stored, the transitions a request is refused for. Count both — operations, and branches per operation — before you write, and say both counts in the hand-back. `api.ungoverned` can tell you an operation you WROTE has no requirement; nothing at all can tell you about the twelve you never wrote down, or about the thirty branches inside the one you did. A guard is not implementation detail: what a service REFUSES is behaviour its caller observes and a test pins, and it is the half of a legacy service that lives only in the code and in one developer's head.\",\n    lands: [\"openapi.yaml\", \"spec.md\"],\n  },\n  {\n    where: \"the message surface — producers, consumers, listener annotations, topic and queue names, the outbox table and its relay\",\n    find: \"every message this service puts on and takes off the bus, with its direction, and — on the consuming side — the DECISIONS the handler makes about a message before it acts on one. The direction is the half that gets lost: a consumer documented as a producer is a contract the whole fleet then joins against backwards. The guards are the half nobody looks for at all: which messages are filtered out and on what field, what happens to one whose entity has since been deleted, what is idempotency-keyed against a replay, what is dead-lettered rather than retried. Each of those is a scenario, and none of them appears anywhere in the contract — asyncapi.yaml describes the message, never what this service refuses to do with it.\",\n    lands: [\"asyncapi.yaml\", \"landscape.likec4\"],\n  },\n  {\n    where: \"the scheduled and background work — cron entries, timers, retry loops, reconcilers, migrations that run at boot\",\n    find: \"behaviour no request ever triggers, and the conditions under which it does or does not run. It has requirements like anything else, and it is invisible to every surface above — which is why a baseline written from routes alone describes a service that does half of what it does. Take the decisions with it: which rows a reconciler SELECTS and which it skips, what a retry loop gives up on and after how long, what a migration does when it finds the state it is meant to fix already fixed. A scheduled job documented as 'runs nightly' is a requirement with no behaviour in it.\",\n    lands: [\"spec.md\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the state — datastores, caches, buckets, and the schema or migration directory that says what is in them\",\n    find: \"what this service OWNS versus what it borrows. Ownership is the fact the C4 is for, and it is the one nobody can reconstruct later from the code without re-reading all of it.\",\n    lands: [\"model.likec4\"],\n  },\n  {\n    where: \"the outbound calls — HTTP clients, generated stubs, gRPC channels, and the config that says which host each one points at\",\n    find: \"who this service calls, and which operation each call names. These become the fleet map's edges; an edge missing here is a dependency the fleet cannot see, and `loam explore` will under-report the blast radius of every future change to the callee. An edge that only configuration attests is PROVISIONAL until the runtime stop: hold it until the deploy manifests confirm nothing switches that client off.\",\n    lands: [\"landscape.likec4\"],\n  },\n  {\n    where: \"the runtime — config and env vars, deploy manifests, pipelines, alert rules, dashboards\",\n    find: \"how it is run and what pages whom. Alerts are the honest source for health.yaml: an SLO nobody agreed to is invention, but an alert that already fires is a fact somebody wrote down. Deployment manifests OVERRIDE configuration files, and they usually live in another repository — go and find them before any dependency that only configuration attests goes in the model, and check for an environment variable that disables the feature. A capability switched off at deploy time is not a dependency, however completely the config wires it: delete its edge and container, and record it in runbook.md's 'configured but not a dependency, and why' list. A manifest read from another repository is named in the runbook's prose — never in `sources`, which may only hold paths of this service's own repository. An EFFECTIVE configuration value behaviour depends on — the timeout the chart sets, the flag that switches a code path — is an arch requirement in arch.spec.md, with a Covers: line naming what it decides; loam holds its coverage even though it can never check the value.\",\n    lands: [\"runbook.md\", \"health.yaml\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the tests, integration and component ones first\",\n    find: \"the behaviours somebody already thought worth pinning. This is the PRIMARY source for scenarios, not the last sweep: a behaviour a test already pins is written FROM that test, and the code is read only for what no test covers. A test suite is the only part of a legacy service that states intent rather than mechanism, and a scenario derived from one is the only kind that starts out true. Carry the shape across as well as the content — a parameterised test (`@ParameterizedTest`, `@parametrize`, `test.each`) is one scenario with a table, not one scenario per case. Then say in the hand-back how well this service is covered and how many of its tests became scenarios: that number is the ceiling on what this whole baseline can be worth, and nothing downstream can compute it.\",\n    lands: [\"spec.md\", \"arch.spec.md\"],\n  },\n];\n\n/**\n * The stop that closes the walk. Separate from `WALK` because it is not a place\n * to go — it is the question asked once the walking is done, and the only\n * defence against a sweep that felt thorough because the parts it covered were\n * covered well.\n */\nexport const WALK_CLOSE =\n  \"Then list the directories you did NOT open, and say why for each. `loam validate --service <id>`, run inside the service's own repo, reports the same list back as `sources.unwalked` — it compares your `sources` against the files git tracks. A directory you deliberately skipped is a sentence in the hand-back; a directory you skipped without noticing is the gap this walk exists to find.\";\n\n/* ------------------------------------------------------------------ */\n/* The frontmatter                                                     */\n/* ------------------------------------------------------------------ */\n\nexport interface FrontmatterBrief {\n  /** Field -> what to write in it. */\n  fields: Record<string, string>;\n  /** Fields to leave alone entirely. */\n  never: string[];\n  /** Why `sources` carries the weight. */\n  why: string;\n}\n\nconst FRONTMATTER_BRIEF: FrontmatterBrief = {\n  fields: {\n    service: \"the directory this file lives under, exactly. A mismatch is an error (`frontmatter.field-mismatch`).\",\n    status:\n      \"`draft`, always. `verified` is a human's word, stamped by `loam vouch --service <id>` run inside the service's own repo — never written by hand.\",\n    owner: \"the team or person who answers for this service.\",\n    sources:\n      \"the paths in THIS SERVICE'S repository you actually read to write the document — files and directories only, a directory covering everything beneath it; glob patterns are refused. Not the paths a reader would expect to have been read. This is NOT a reading list for a human: nobody follows these, and nothing about the document asks them to.\",\n  },\n  // `vouch_scope` is in this list for a sharper reason than its siblings: the\n  // others are stamps an agent could only forge, while this one is a stamp an\n  // agent could DELETE — and deleting it turns a vouch that read four sections\n  // into one that read the document, on every surface at once.\n  never: [\"last_verified\", \"sources_digest\", \"content_digest\", \"sources_files\", \"vouch_scope\"],\n  why:\n    \"`sources` is digest input, not a citation. It is the only mechanical tie between this document and the code — everything else loam checks is internal consistency, and a corpus can agree with itself perfectly while describing nothing that exists. `loam validate`, run inside the service's repo, checks every listed path is still there; `loam vouch` hashes their CONTENT so that a later `validate` can say the code has moved since anyone read it. That hash is the entire point, and it is why padding the list costs something real rather than merely being untidy: a path nobody read still gets hashed, so its next change reports as drift in a document it never described, and a path that WAS read and went unlisted moves under the document in silence. Neither failure is visible to a reader; both are decided by whether this list is honest.\",\n};\n\nexport interface Brief {\n  service: string;\n  /** Absolute docs repo root — the anchor the repo-relative paths hang off. */\n  docsDir: DocsDir;\n  /** Repo-relative path of services/<id>/. */\n  path: string;\n  targets: BriefTarget[];\n  /** The order to read the service in, and what each stop feeds. */\n  walk: WalkStop[];\n  /** The question the walk ends on — see `WALK_CLOSE`. */\n  walkClose: string;\n  landscape: LandscapeContext;\n  frontmatter: FrontmatterBrief;\n  checks: BriefCheck[];\n  unchecked: string[];\n  /** The one instruction that outranks the rest. */\n  rule: string;\n}\n\nconst NEVER_OVERWRITE =\n  \"Do not overwrite an artifact that already exists. Read it, diff your findings against it, and report what disagrees — a document somebody wrote is evidence, and replacing it destroys the only copy of what they knew.\";\n\n/**\n * Assemble the brief for one service. Reads the docs repo; writes nothing.\n * `at` overrides where the artifacts are briefed to land — `adopt\n * --subsystem`'s target inside a group — and is only ever passed for a\n * service the enumeration does NOT answer: an existing service is briefed\n * where it already lives, because the brief's one rule is to never overwrite,\n * and a second address would brief a duplicate.\n */\nexport async function serviceBrief(\n  docsDir: DocsDir,\n  service: PathableService,\n  at?: ServicePaths,\n): Promise<Brief> {\n  const paths = at ?? (await locateServicePaths(docsDir, service));\n  const rel = (abs: string): string => relative(docsDir, abs).split(/[\\\\/]/).join(\"/\");\n\n  // Read before the artifact loop, not after it: what the fleet already says\n  // about this service decides whether it owes an API contract at all.\n  const landscape = await landscapeContext(docsDir, service);\n  const owesApi = apiExpected(landscape);\n\n  const targets: BriefTarget[] = [];\n  for (const { key, ...artifact } of ARTIFACTS) {\n    // `adrs/` is a directory, and an empty one is not an existing artifact —\n    // reporting it as present would tell the agent to diff against nothing.\n    const dir = key === \"adrsDir\";\n    const exists = dir ? await hasMarkdown(paths[key]) : existsSync(paths[key]);\n    targets.push({\n      ...artifact,\n      ...(key === \"openapi\" ? { required: owesApi } : {}),\n      path: dir ? `${rel(paths[key])}/` : rel(paths[key]),\n      exists,\n      action: exists ? \"diff\" : \"create\",\n    });\n  }\n\n  // The eighth target is the fleet map, and it is conditional: a service the\n  // landscape ALREADY resolves an element to owes it nothing, and briefing an\n  // edit there would invite an agent to draw a second box for a service that\n  // has one. Everything else about the target is unconditional — the file is\n  // shared, so `action` is `edit` whenever it exists and `create` only for the\n  // very first service of a brand-new docs repo.\n  if (landscape.modelled !== true) {\n    targets.push({\n      ...landscapeArtifact(service, landscape.expects, landscape.present, rel(paths.dir)),\n      path: rel(landscapePath(docsDir)),\n      exists: landscape.present,\n      action: landscape.present ? \"edit\" : \"create\",\n    });\n  }\n\n  return {\n    service,\n    docsDir,\n    path: rel(paths.dir),\n    targets,\n    walk: WALK,\n    walkClose: WALK_CLOSE,\n    landscape,\n    frontmatter: FRONTMATTER_BRIEF,\n    checks: VALIDATE_CHECKS,\n    unchecked: UNCHECKED,\n    rule: NEVER_OVERWRITE,\n  };\n}\n\nasync function hasMarkdown(dir: string): Promise<boolean> {\n  if (!existsSync(dir)) return false;\n  const entries = await readdir(dir, { withFileTypes: true });\n  // `statSync` for the symlink case: a Dirent never follows one, so `isFile()`\n  // is false for a symlinked ADR and the directory reads as empty (repo.ts's\n  // `entryIs` is the same rule for `services/` and `features/`).\n  return entries.some((e) => {\n    if (!e.name.endsWith(\".md\")) return false;\n    if (e.isFile()) return true;\n    if (!e.isSymbolicLink()) return false;\n    try {\n      return statSync(join(dir, e.name)).isFile();\n    } catch {\n      return false;\n    }\n  });\n}\n\n/**\n * Does the fleet expect an API of this service?\n *\n * The brief marked `openapi.yaml` required unconditionally, and printed the\n * absence as `MISSING` in capitals — while `loam validate` and `loam list`\n * derive the opposite from the same landscape (`service.no-openapi` stays quiet\n * when nothing calls the service, and `list`'s maturity ladder stops demanding\n * a contract). For a UI, a worker or a cron the brief was therefore telling an\n * agent to INVENT an API contract into the source of truth — the one class of\n * guess this whole module exists to refuse, and the one the brief itself names\n * in `openapi.yaml`'s shape rules (`ARTIFACTS`, targets.ts).\n *\n * Positive evidence only, exactly as `list` reads it: a landscape that is\n * absent or does not parse proves nothing about who calls this service, so the\n * contract is still owed. `expects` is the ops on inbound edges, which is\n * `list`'s `called` set seen from one service.\n */\nfunction apiExpected(landscape: LandscapeContext): boolean {\n  return !landscape.parses || landscape.expects.length > 0;\n}\n"]}
+{"version":3,"file":"brief.js","sourceRoot":"","sources":["../../../src/core/brief/brief.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The adoption brief: what an agent needs in order to write one service's\n * baseline documentation, and what will be checked when it does.\n *\n * `adopt` was specified for years as \"read the code, emit the C4\". It is not\n * being built, because it cannot be: nothing deterministic reads a legacy\n * service and says what its architecture MEANS, and a guessed model is worse\n * than no model — everyone downstream has to re-derive it to know whether to\n * believe it.\n *\n * So loam takes the half of the job that IS deterministic. It states the work\n * precisely (which files, in which grammar, bound to which existing elements),\n * it says exactly which checks the result will face, and then it says which\n * checks do not exist — because everything in that last list is honesty no\n * validator will ever supply, and an agent that does not know where the checking\n * stops will assume it never does.\n *\n * Nothing here reads code. `sources` in the frontmatter is the only line that\n * ties the result to a repository, which is why the brief argues for it instead\n * of merely listing it.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join, relative } from \"node:path\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { landscapePath, type ServicePaths } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { specAdoption } from \"../repo/repo.js\";\nimport { entryIs } from \"../repo/tree/fs.js\";\nimport { VALIDATE_CHECKS, type BriefCheck } from \"./checks.js\";\nimport { UNCHECKED } from \"./unchecked.js\";\nimport { landscapeContext, type LandscapeContext } from \"./landscape.js\";\nimport { landscapeArtifact } from \"./map/owed.js\";\nimport { exampleFor, extendPoint, FQN } from \"./map/extend.js\";\nimport { ARTIFACTS, USECASES_DIR, type BriefTarget } from \"./targets.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport { EXTERNAL_TAG } from \"../vocabulary/maturity.js\";\n\n/* ------------------------------------------------------------------ */\n/* The walk — what to read, in what order, and where each finding lands */\n/* ------------------------------------------------------------------ */\n\nexport interface WalkStop {\n  /** What to open, named as a thing to go and find rather than a file name. */\n  where: string;\n  /** What to take out of it. */\n  find: string;\n  /** The artifacts this stop feeds, by `artifact` name from `targets[]`. */\n  lands: string[];\n}\n\n/**\n * The architecture walk: the order a service is read in, and what each stop is\n * for.\n *\n * The brief said \"read the code: entry points, HTTP routes and handlers,\n * published events, config, deploy manifests, tests\" — one sentence, six nouns,\n * no order and no landing site. What came back matched the sentence: the HTTP\n * surface documented well, because it is the noun an agent recognises fastest,\n * and the scheduler, the consumer group and the outbox missing entirely. Not\n * because they were judged unimportant — because nothing said to go and look,\n * and every check loam owns is computed from what was written rather than from\n * what is there. `UNCHECKED` has said COMPLETENESS is unverifiable since the\n * beginning; that is an argument for stating the sweep, not for leaving it\n * implied.\n *\n * The order is deliberate and it is not the order a reader browses in. Stops 1\n * and 2 fix the SHAPE of the service — which processes exist at all — before\n * any surface is enumerated, because an agent that starts at the HTTP routes\n * has already concluded the service is an API by the time it meets the\n * scheduler. Everything after them is one surface each.\n *\n * `lands` names artifacts rather than describing them, because the two lists\n * are joined: test/agent-contract.test.ts requires every name here to be a\n * target the same brief hands over, so a stop can never feed a file nobody was\n * asked to write.\n */\nexport const WALK: WalkStop[] = [\n  {\n    where: \"the build and dependency manifests — pom.xml, build.gradle, package.json, go.mod, requirements.txt, and whatever the repo's own README calls the build\",\n    find: \"what this service is built from, and every client library it links against. A broker client, an HTTP client, a database driver: each one is a dependency that has to appear as an edge or a container later, and this list is the only place they are all named at once. A library whose SEMANTICS decide behaviour — a retry budget, a delivery guarantee, a serialization format — is an arch requirement (arch.spec.md), not a fact to leave in your head.\",\n    lands: [\"model.likec4\", \"runbook.md\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the entry points — main/Application/server bootstrap, the DI or module wiring, and anything the deploy manifests actually start\",\n    find: \"how many PROCESSES this service is, and what each one is. An API, a worker, a scheduler, a consumer — a service that is three of those and documented as one is the most common way a baseline is wrong, and it is wrong in a shape no later check can see.\",\n    lands: [\"model.likec4\"],\n  },\n  {\n    where: \"the HTTP surface — every route, controller, handler and middleware, counted\",\n    find: \"the operation set, in full, and inside each operation the DECISIONS its code makes: the permission and role checks — each one is a `Requires:` entry, and a name `architecture/permissions.yaml` does not declare yet is a line to ADD to that shared file, never to invent locally — the fields required only when another field is present, the defaults and normalisations applied before anything is stored, the transitions a request is refused for. Count both — operations, and branches per operation — before you write, and say both counts in the hand-back. `api.ungoverned` can tell you an operation you WROTE has no requirement; nothing at all can tell you about the twelve you never wrote down, or about the thirty branches inside the one you did. A guard is not implementation detail: what a service REFUSES is behaviour its caller observes and a test pins, and it is the half of a legacy service that lives only in the code and in one developer's head.\",\n    lands: [\"openapi.yaml\", \"spec.md\"],\n  },\n  {\n    where: \"the message surface — producers, consumers, listener annotations, topic and queue names, the outbox table and its relay\",\n    find: \"every message this service puts on and takes off the bus, with its direction, and — on the consuming side — the DECISIONS the handler makes about a message before it acts on one. The direction is the half that gets lost: a consumer documented as a producer is a contract the whole fleet then joins against backwards. The guards are the half nobody looks for at all: which messages are filtered out and on what field, what happens to one whose entity has since been deleted, what is idempotency-keyed against a replay, what is dead-lettered rather than retried. Each of those is a scenario, and none of them appears anywhere in the contract — asyncapi.yaml describes the message, never what this service refuses to do with it.\",\n    lands: [\"asyncapi.yaml\", \"landscape.likec4\"],\n  },\n  {\n    where: \"the scheduled and background work — cron entries, timers, retry loops, reconcilers, migrations that run at boot\",\n    find: \"behaviour no request ever triggers, and the conditions under which it does or does not run. It has requirements like anything else, and it is invisible to every surface above — which is why a baseline written from routes alone describes a service that does half of what it does. Take the decisions with it: which rows a reconciler SELECTS and which it skips, what a retry loop gives up on and after how long, what a migration does when it finds the state it is meant to fix already fixed. A scheduled job documented as 'runs nightly' is a requirement with no behaviour in it.\",\n    lands: [\"spec.md\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the state — datastores, caches, buckets, and the schema or migration directory that says what is in them\",\n    find: \"what this service OWNS versus what it borrows. Ownership is the fact the C4 is for, and it is the one nobody can reconstruct later from the code without re-reading all of it.\",\n    lands: [\"model.likec4\"],\n  },\n  {\n    where: \"the outbound calls — HTTP clients, generated stubs, gRPC channels, and the config that says which host each one points at\",\n    find: \"who this service calls, and which operation each call names. These become the fleet map's edges; an edge missing here is a dependency the fleet cannot see, and `loam explore` will under-report the blast radius of every future change to the callee. An edge that only configuration attests is PROVISIONAL until the runtime stop: hold it until the deploy manifests confirm nothing switches that client off.\",\n    lands: [\"landscape.likec4\"],\n  },\n  {\n    where: \"the runtime — config and env vars, deploy manifests, pipelines, alert rules, dashboards\",\n    find: \"how it is run and what pages whom. Alerts are the honest source for health.yaml: an SLO nobody agreed to is invention, but an alert that already fires is a fact somebody wrote down. Deployment manifests OVERRIDE configuration files, and they usually live in another repository — go and find them before any dependency that only configuration attests goes in the model, and check for an environment variable that disables the feature. A capability switched off at deploy time is not a dependency, however completely the config wires it: delete its edge and container, and record it in runbook.md's 'configured but not a dependency, and why' list. A manifest read from another repository is named in the runbook's prose — never in `sources`, which may only hold paths of this service's own repository. An EFFECTIVE configuration value behaviour depends on — the timeout the chart sets, the flag that switches a code path — is an arch requirement in arch.spec.md, with a Covers: line naming what it decides; loam holds its coverage even though it can never check the value.\",\n    lands: [\"runbook.md\", \"health.yaml\", \"arch.spec.md\"],\n  },\n  {\n    where: \"the tests, integration and component ones first\",\n    find: \"the behaviours somebody already thought worth pinning. This is the PRIMARY source for scenarios, not the last sweep: a behaviour a test already pins is written FROM that test, and the code is read only for what no test covers. A test suite is the only part of a legacy service that states intent rather than mechanism, and a scenario derived from one is the only kind that starts out true. Carry the shape across as well as the content — a parameterised test (`@ParameterizedTest`, `@parametrize`, `test.each`) is one scenario with a table, not one scenario per case. Then say in the hand-back how well this service is covered and how many of its tests became scenarios: that number is the ceiling on what this whole baseline can be worth, and nothing downstream can compute it.\",\n    lands: [\"spec.md\", \"arch.spec.md\"],\n  },\n];\n\n/**\n * The stop that closes the walk. Separate from `WALK` because it is not a place\n * to go — it is the question asked once the walking is done, and the only\n * defence against a sweep that felt thorough because the parts it covered were\n * covered well.\n */\nexport const WALK_CLOSE =\n  \"Then list the directories you did NOT open, and say why for each. `loam validate --service <id>`, run inside the service's own repo, reports the same list back as `sources.unwalked` — it compares your `sources` against the files git tracks. A directory you deliberately skipped is a sentence in the hand-back; a directory you skipped without noticing is the gap this walk exists to find.\";\n\n/* ------------------------------------------------------------------ */\n/* The frontmatter                                                     */\n/* ------------------------------------------------------------------ */\n\nexport interface FrontmatterBrief {\n  /** Field -> what to write in it. */\n  fields: Record<string, string>;\n  /** Fields to leave alone entirely. */\n  never: string[];\n  /** Why `sources` carries the weight. */\n  why: string;\n}\n\nconst FRONTMATTER_BRIEF: FrontmatterBrief = {\n  fields: {\n    service: \"the directory this file lives under, exactly. A mismatch is an error (`frontmatter.field-mismatch`).\",\n    status:\n      \"`draft`, always. `verified` is a human's word, stamped by `loam vouch --service <id>` run inside the service's own repo — never written by hand.\",\n    owner: \"the team or person who answers for this service.\",\n    sources:\n      \"the paths in THIS SERVICE'S repository you actually read to write the document — files and directories only, a directory covering everything beneath it; glob patterns are refused. Not the paths a reader would expect to have been read. This is NOT a reading list for a human: nobody follows these, and nothing about the document asks them to.\",\n  },\n  // `vouch_scope` is in this list for a sharper reason than its siblings: the\n  // others are stamps an agent could only forge, while this one is a stamp an\n  // agent could DELETE — and deleting it turns a vouch that read four sections\n  // into one that read the document, on every surface at once.\n  never: [\"last_verified\", \"sources_digest\", \"content_digest\", \"sources_files\", \"vouch_scope\"],\n  why:\n    \"`sources` is digest input, not a citation. It is the only mechanical tie between this document and the code — everything else loam checks is internal consistency, and a corpus can agree with itself perfectly while describing nothing that exists. `loam validate`, run inside the service's repo, checks every listed path is still there; `loam vouch` hashes their CONTENT so that a later `validate` can say the code has moved since anyone read it. That hash is the entire point, and it is why padding the list costs something real rather than merely being untidy: a path nobody read still gets hashed, so its next change reports as drift in a document it never described, and a path that WAS read and went unlisted moves under the document in silence. Neither failure is visible to a reader; both are decided by whether this list is honest.\",\n};\n\nexport interface Brief {\n  service: string;\n  /** Absolute docs repo root — the anchor the repo-relative paths hang off. */\n  docsDir: DocsDir;\n  /** Repo-relative path of services/<id>/. */\n  path: string;\n  targets: BriefTarget[];\n  /** The order to read the service in, and what each stop feeds. */\n  walk: WalkStop[];\n  /** The question the walk ends on — see `WALK_CLOSE`. */\n  walkClose: string;\n  landscape: LandscapeContext;\n  frontmatter: FrontmatterBrief;\n  checks: BriefCheck[];\n  unchecked: string[];\n  /** The one instruction that outranks the rest. */\n  rule: string;\n}\n\nconst NEVER_OVERWRITE =\n  \"Do not overwrite an artifact that already exists. Read it, diff your findings against it, and report what disagrees — a document somebody wrote is evidence, and replacing it destroys the only copy of what they knew.\";\n\n/**\n * Assemble the brief for one service. Reads the docs repo; writes nothing.\n * `at` overrides where the artifacts are briefed to land — `adopt\n * --subsystem`'s target inside a group — and is only ever passed for a\n * service the enumeration does NOT answer: an existing service is briefed\n * where it already lives, because the brief's one rule is to never overwrite,\n * and a second address would brief a duplicate.\n */\nexport async function serviceBrief(\n  docsDir: DocsDir,\n  service: PathableService,\n  at?: ServicePaths,\n): Promise<Brief> {\n  const paths = at ?? (await locateServicePaths(docsDir, service));\n  const rel = (abs: string): string => relative(docsDir, abs).split(/[\\\\/]/).join(\"/\");\n\n  // Read before the artifact loop, not after it: what the fleet already says\n  // about this service decides whether it owes an API contract at all. The\n  // model path travels with it — located through the enumeration above, never\n  // joined at `services/<id>/` — so the edgeless state can name the calls the\n  // service's own model attests.\n  const landscape = await landscapeContext(docsDir, service, paths);\n  const owesApi = apiExpected(landscape);\n\n  // The one id the model target's grammar and example are written against,\n  // resolved here because `ARTIFACTS` is static on purpose (a target list that\n  // varied per repository would be a second thing to keep true) and because this\n  // is the only place the fleet map has already been read.\n  const extend = extendPoint(landscape);\n\n  const targets: BriefTarget[] = [];\n  for (const { key, ...artifact } of ARTIFACTS) {\n    // `adrs/` and `usecases/` are DIRECTORIES, and an empty one is not an\n    // existing artifact — reporting it as present would tell the agent to diff\n    // against nothing, and for `usecases/` it would also tell the agent an\n    // optional slot was already taken.\n    //\n    // `usecases/` is the one target with no `ServicePaths` entry, and that is\n    // deliberate rather than an omission: nothing loam checks JOINS on that\n    // path. The slot a service's flows are graded out of is its whole LikeC4\n    // project (`core/usecases/service/flows.ts` reads every `.likec4` under the\n    // directory), so `usecases/<name>.likec4` is a convention this brief\n    // publishes, not a path a writer writes — and `targets.ts` is where a\n    // convention belongs.\n    const ext = key === \"adrsDir\" ? \".md\" : key === \"usecasesDir\" ? \".likec4\" : null;\n    const at = key === \"usecasesDir\" ? join(paths.dir, USECASES_DIR) : paths[key];\n    const exists = ext === null ? existsSync(at) : await hasEntry(at, ext);\n    const partial = key === \"spec\" && exists && (await specAdoption(at)) === \"partial\";\n    targets.push({\n      ...artifact,\n      ...(partial ? { partial: true as const } : {}),\n      ...(key === \"openapi\" ? { required: owesApi } : {}),\n      // Every `<fqn>` in the model target, replaced by the element this service\n      // actually extends. The placeholder is left literal in `targets.ts` — the\n      // brief is handed to an agent that will WRITE the file, and\n      // `extend <fqn> {` copied verbatim is a document that does not parse.\n      shape: artifact.shape.map((rule) => rule.replaceAll(FQN, extend.id)),\n      ...(artifact.example === undefined ? {} : { example: exampleFor(artifact.example, extend, service) }),\n      path: ext === null ? rel(at) : `${rel(at)}/`,\n      exists,\n      action: exists ? \"diff\" : \"create\",\n    });\n  }\n\n  // The eighth target is the fleet map, and it is conditional on TWO facts: an\n  // element resolving to the service, and an edge touching it. A service the\n  // landscape already draws AND reaches owes it nothing, and briefing an edit\n  // there would invite an agent to draw a second box for a service that has\n  // one. A service with a box and no edge — what `loam seed` leaves for every\n  // service nobody listed under `calls:` — owes it the edges, and until\n  // 2026-09-03 element existence alone read as \"the map is complete\" here, so\n  // the brief declared the map finished for exactly the services it had not\n  // reached. Everything else about the target is unconditional — the file is\n  // shared, so `action` is `edit` whenever it exists and `create` only for the\n  // very first service of a brand-new docs repo.\n  //\n  // `modelled === false` and not `!== true`: `null` is \"loam could not read the\n  // map\", and it fell through the same branch as \"the map genuinely draws\n  // nothing for this service\". The brief then handed over the UNDRAWN target —\n  // whose shape rule is \"add one top-level element bound to its directory\" and\n  // whose example is a block to splice — for services the map already declares\n  // and binds, and an agent that spliced it earned `landscape.binding-duplicate`\n  // for doing exactly what the brief asked. With the map unreadable there is no\n  // write to ask for; `landscape.instruction` carries the whole answer and names\n  // the documents that failed.\n  if (landscape.modelled === false || landscape.touched === false) {\n    targets.push({\n      ...landscapeArtifact({\n        service,\n        expects: landscape.expects,\n        present: landscape.present,\n        servicePath: rel(paths.dir),\n        // The existing element's id, in the edgeless state only: it switches\n        // the example from a block to edges on that element.\n        // …and whether it is `#external`, which decides what the shape rule may\n        // promise: `landscape.service-isolated` never fires on such an element.\n        ...(landscape.touched === false && landscape.elements[0] !== undefined\n          ? { elementId: landscape.elements[0].id, external: landscape.elements[0].tags.includes(EXTERNAL_TAG) }\n          : {}),\n        attested: landscape.attested,\n      }),\n      path: rel(landscapePath(docsDir)),\n      exists: landscape.present,\n      action: landscape.present ? \"edit\" : \"create\",\n    });\n  }\n\n  return {\n    service,\n    docsDir,\n    path: rel(paths.dir),\n    targets,\n    walk: WALK,\n    walkClose: WALK_CLOSE,\n    landscape,\n    frontmatter: FRONTMATTER_BRIEF,\n    checks: VALIDATE_CHECKS,\n    unchecked: UNCHECKED,\n    rule: NEVER_OVERWRITE,\n  };\n}\n\n/**\n * Does this directory already hold an artifact of the given extension? The\n * \"exists\" question for the two DIRECTORY targets — `adrs/` (`.md`) and\n * `usecases/` (`.likec4`) — where an empty or absent directory is the same\n * answer, because neither is something to diff against.\n */\nasync function hasEntry(dir: string, ext: string): Promise<boolean> {\n  if (!existsSync(dir)) return false;\n  const entries = await readdir(dir, { withFileTypes: true });\n  // `entryIs` for the symlink case: a Dirent never follows one, so `isFile()`\n  // is false for a symlinked ADR and the directory would read as empty — the\n  // same rule `services/` and `features/` are enumerated by.\n  return entries.some((e) => e.name.endsWith(ext) && entryIs(dir, e, \"file\"));\n}\n\n/**\n * Does the fleet expect an API of this service?\n *\n * The brief marked `openapi.yaml` required unconditionally, and printed the\n * absence as `MISSING` in capitals — while `loam validate` and `loam list`\n * derive the opposite from the same landscape (`service.no-openapi` stays quiet\n * when nothing calls the service, and `list`'s maturity ladder stops demanding\n * a contract). For a UI, a worker or a cron the brief was therefore telling an\n * agent to INVENT an API contract into the source of truth — the one class of\n * guess this whole module exists to refuse, and the one the brief itself names\n * in `openapi.yaml`'s shape rules (`ARTIFACTS`, targets.ts).\n *\n * Positive evidence only, exactly as `list` reads it: a landscape that is\n * absent or unreadable proves nothing about who calls this service, so the\n * contract is still owed. `expects` is the ops on inbound edges, which is\n * `list`'s `called` set seen from one service.\n *\n * `callersKnown` and not `parses`, because since W4 `parses` answers about the\n * whole `architecture/` PROJECT: a broken palette or use case beside a landscape\n * loam reads perfectly made this discard the map and demand an OpenAPI contract\n * of a browser UI — inventing an API into the source of truth, which is the one\n * class of guess this module exists to refuse. `callersKnown` is the narrower\n * fact this question actually needs, and it is the one `list` and `context` read.\n */\nfunction apiExpected(landscape: LandscapeContext): boolean {\n  return !landscape.callersKnown || landscape.expects.length > 0;\n}\n"]}