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

package/dist/core/dependencies/facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.js","sourceRoot":"","sources":["../../../src/core/dependencies/facts.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What one feature ADDS and what it NEEDS, read out of its own delta.\n *\n * The whole graph is built from these five lists and nothing else, which is why\n * they are computed once per feature and indexed rather than re-derived per\n * edge: a feature is a node here only because some other feature's requirement\n * or operation resolves into it, and answering that per pair would be a fleet\n * walk per pair.\n *\n * `reqKeys` returns BOTH spellings of a requirement's identity — the stable\n * `Requirement-ID` and the exact heading — because a legacy requirement has only\n * the second, and an edge that existed under one spelling and not the other\n * would make the graph depend on when the corpus was migrated.\n */\nimport { existsSync } from \"node:fs\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport { operations } from \"../openapi/doc.js\";\nimport { type FeatureEntry } from \"../repo/entries.js\";\nimport { SPEC_AXES, featurePaths, featureSpecPaths, type SpecAxis } from \"../repo/paths.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport { enumeratedServiceIds, enumeratedServiceIndex } from \"../repo/service-target.js\";\nimport type { Requirement } from \"../document/spec.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\nexport type DependencyReason =\n  | {\n      kind: \"requirement\";\n      service: string;\n      axis: SpecAxis[\"file\"];\n      identity: string;\n    }\n  | { kind: \"operation\"; service: string; operationId: string };\n\nexport interface DependencyEdge {\n  /** The feature that consumes/modifies something. */\n  from: string;\n  /** The feature that introduces it and therefore has to land first. */\n  to: string;\n  reasons: DependencyReason[];\n}\n\nexport interface FeatureConflict {\n  kind: \"requirement\" | \"operation\";\n  /**\n   * How the owners collide.\n   *\n   * `added` — two features ADD the same identity (or define the same\n   * operationId): whichever archives second replaces the first outright.\n   *\n   * `changed` — two features MODIFY or REMOVE the same living requirement.\n   * That collision was invisible until now, and it is the more common one on a\n   * fleet: nobody adds \"Cancel an order\" twice, but two teams editing its text\n   * in the same week is a Tuesday. A MODIFIED requirement carries its FULL new\n   * text, so the second archive does not merge the first one's wording — it\n   * overwrites it, silently and completely.\n   */\n  change: \"added\" | \"changed\";\n  service: string;\n  axis?: SpecAxis[\"file\"];\n  identity: string;\n  features: string[];\n}\n\nexport interface DependencyNode {\n  id: string;\n  dirName: string;\n  services: string[];\n  dependsOn: string[];\n}\n\nexport interface DependencyGraph {\n  nodes: DependencyNode[];\n  edges: DependencyEdge[];\n  conflicts: FeatureConflict[];\n  /** Dependencies precede their consumers; cyclic members remain deterministic. */\n  order: string[];\n  /** Strongly connected components with more than one node (or a self-loop). */\n  cycles: string[][];\n}\n\nexport interface FeatureFacts {\n  feature: FeatureEntry;\n  addedRequirements: Array<{\n    service: string;\n    axis: SpecAxis[\"file\"];\n    requirement: Requirement;\n  }>;\n  changedRequirements: Array<{\n    service: string;\n    axis: SpecAxis[\"file\"];\n    requirement: Requirement;\n  }>;\n  introducedOperations: Array<{ service: string; operationId: string }>;\n  requiredOperations: Array<{ service: string; operationId: string }>;\n}\n\nexport function reqKeys(requirement: Pick<Requirement, \"id\" | \"name\">): string[] {\n  return [\n    ...(requirement.id === undefined ? [] : [`id:${requirement.id}`]),\n    `name:${requirement.name}`,\n  ];\n}\n\n/**\n * WHERE a collision happens, kept as fields rather than as a string.\n *\n * An index needs one scalar per entry to hash on, so the fields get NUL-joined\n * into a key — but the conflict records want those fields back, and splitting\n * the key apart again means asserting the pieces back into their types. That\n * assertion is a claim about data loam does not own: a service directory or a\n * requirement name containing a NUL would hand `axis` a fragment of an identity\n * with nothing to notice. Carrying the structured value beside the owner set\n * means the key is only ever a key, and the record is read, not reconstructed.\n */\nexport interface ReqAt {\n  service: string;\n  axis: SpecAxis[\"file\"];\n  identity: string;\n}\n\nexport interface OpAt {\n  service: string;\n  operationId: string;\n}\n\nexport interface Owners<T> {\n  readonly at: T;\n  readonly features: Set<string>;\n}\n\nexport function reqIndexKey(at: ReqAt): string {\n  return `${at.service}\\0${at.axis}\\0${at.identity}`;\n}\n\nexport function opIndexKey(at: OpAt): string {\n  return `${at.service}\\0${at.operationId}`;\n}\n\nexport function addOwner<T>(index: Map<string, Owners<T>>, key: string, at: T, feature: string): void {\n  const owners = index.get(key) ?? { at, features: new Set<string>() };\n  owners.features.add(feature);\n  index.set(key, owners);\n}\n\nexport async function readFacts(\n  docsDir: DocsDir,\n  feature: FeatureEntry,\n  context: FleetContext,\n): Promise<FeatureFacts> {\n  const addedRequirements: FeatureFacts[\"addedRequirements\"] = [];\n  const changedRequirements: FeatureFacts[\"changedRequirements\"] = [];\n  const introducedOperations: FeatureFacts[\"introducedOperations\"] = [];\n  const requiredOperations: FeatureFacts[\"requiredOperations\"] = [];\n\n  /**\n   * The operationIds a service ALREADY has, per service.\n   *\n   * This is the whole difference between a dependency graph and a rumour mill.\n   * A feature's `openapi.yaml` is a COMPLETE document, not a patch — authors\n   * restate the living API around the slot they are changing — so every feature\n   * that so much as mentions `authorizePayment` used to be recorded as\n   * INTRODUCING it, and every other feature governing it as REQUIRING it. Two\n   * features quoting the same living operation therefore depended on each other\n   * in both directions: an invented cycle, an invented conflict, and an ordering\n   * for work that had none. `loam validate`'s coherence pass already subtracts\n   * the living contract this way (core/coherence/coherence.ts); this is the\n   * same subtraction, so the two cannot disagree about what \"new\" means.\n   *\n   * Cached per service inside the call and, through the FleetContext, across\n   * features: a fleet-wide graph asks about the same ten services N times.\n   */\n  const livingByService = new Map<string, Set<string>>();\n  const living = async (service: PathableService): Promise<Set<string>> => {\n    let ids = livingByService.get(service);\n    if (ids === undefined) {\n      ids = new Set(\n        (await operations((await locateServicePaths(docsDir, service, context)).openapi, context))\n          .filter((op) => !op.remove)\n          .map((op) => op.id),\n      );\n      livingByService.set(service, ids);\n    }\n    return ids;\n  };\n\n  for (const service of feature.services) {\n    const paths = featureSpecPaths(feature.dir, service);\n    const livingIds = await living(service);\n    for (const axis of SPEC_AXES) {\n      const path = paths[axis.key];\n      if (!existsSync(path)) continue;\n      const requirements = await context.readRequirements(path);\n      for (const requirement of requirements) {\n        const fact = { service, axis: axis.file, requirement };\n        if (requirement.kind === \"ADDED\") addedRequirements.push(fact);\n        if (requirement.kind === \"MODIFIED\" || requirement.kind === \"REMOVED\") {\n          changedRequirements.push(fact);\n        }\n        for (const operationId of requirement.operations) {\n          // Governing an operation the service already provides is not a\n          // dependency on anybody: the contract it needs is already merged.\n          if (livingIds.has(operationId)) continue;\n          requiredOperations.push({ service, operationId });\n        }\n      }\n    }\n\n    if (existsSync(paths.openapi)) {\n      const featureOperations = await operations(paths.openapi, context);\n      for (const operation of featureOperations) {\n        if (livingIds.has(operation.id)) continue;\n        if (operation.remove) requiredOperations.push({ service, operationId: operation.id });\n        else introducedOperations.push({ service, operationId: operation.id });\n      }\n    }\n  }\n\n  // The C4 delta is the FOURTH place a feature names an operation, and it was\n  // the one the graph could not see: an edge carrying `metadata { op 'x' }` is\n  // a call this feature builds on `x`, which is exactly the \"must land first\"\n  // relation this module exists to compute. Validate already says so — it\n  // reports `c4-api.op-pending` when the op is defined by another feature in\n  // flight — so the graph disagreeing with the validator about the same pair of\n  // features was the graph being wrong, not quiet.\n  //\n  // Endpoints resolve through `serviceResolver` — the element's\n  // `metadata { service }` binding, title as fallback — the same join every\n  // other check uses, so renaming a box in a diagram cannot silently unhook it\n  // here either.\n  const deltaPath = featurePaths(feature.dir).delta;\n  if (existsSync(deltaPath)) {\n    const doc = await context.loadLikeC4(deltaPath);\n    // A delta that does not parse proves nothing about who depends on whom.\n    // `loam validate` owns that diagnosis (`delta.invalid`); inventing edges out\n    // of a half-read document would be worse than the silence.\n    if (doc.errors.length === 0) {\n      // One resolver for the whole delta: `serviceOf` rebuilds its id map on\n      // every call, and this loop asks once per edge. The enumerated fleet —\n      // `services/` plus this feature's own `specs/` directories, the same\n      // union `enumeratedTarget` probes below — rides into the resolver so a\n      // delta that models CONTAINERS keeps its edges attached: without it, an\n      // edge into `payment.api` resolves to a service called \"api\" that has\n      // never existed, the op lookup misses the living contract, and the graph\n      // invents a dependency (or orders two features that share nothing). An\n      // unenumerable services/ falls back to the feature's own names — every\n      // living probe would have found nothing there anyway.\n      const fleetIds = await enumeratedServiceIds(docsDir, context);\n      const svcOf = serviceResolver(doc.elements, new Set([...fleetIds, ...feature.services]));\n      // The resolver answers with document text and `living` builds a path, so\n      // the name crosses through the enumeration — coherence.ts grades its\n      // edges through the same bridge. A name no enumeration vouches for has\n      // no living contract anywhere: the op is required, exactly what the\n      // probe answered for an absent service.\n      const enumeratedTarget = enumeratedServiceIndex(docsDir, feature.services, context);\n      for (const rel of doc.relationships) {\n        if (rel.op === undefined) continue;\n        const service = svcOf(rel.target);\n        const pathable = await enumeratedTarget(service);\n        if (pathable !== undefined && (await living(pathable)).has(rel.op)) continue;\n        requiredOperations.push({ service, operationId: rel.op });\n      }\n    }\n  }\n\n  return {\n    feature,\n    addedRequirements,\n    changedRequirements,\n    introducedOperations,\n    requiredOperations,\n  };\n}\n"]}

package/dist/core/dependencies/fanin.js

@@ -0,0 +1,88 @@
+/**
+ * Fleet fan-in: for each service, how many DISTINCT other known services
+ * depend on it — the blast radius behind `loam list --needs-work
+ * --review-order`. Reviewing the most-depended-on service first is the one
+ * ordering a campaign lead cannot derive by eye from the worklist.
+ *
+ * Pure derivation, derived-never-stored, in the package that already owns
+ * who-depends-on-whom: `core/dependencies/` derives the feature ordering from
+ * artifact identities, and this module derives the service-level analog. The
+ * command layer (commands/list/review.ts) gathers the inputs from reads the
+ * repository already pays for and hands them in as data, so the module itself
+ * imports nothing — no IO, no parser import, never prints. The edge slice is
+ * structural for the same reason `core/vocabulary/maturity.ts`'s EdgeSource
+ * is: `core/c4/likec4.ts`'s `Rel` satisfies it without an import edge into
+ * the parser.
+ */
+/**
+ * Distinct known consumers per service, as a count for every id in
+ * `req.services` (0 when nothing depends on it — a proven zero, since only
+ * positive evidence ever increments it).
+ *
+ * Three joins, unioned by DISTINCT consumer so overlapping evidence for one
+ * caller counts once:
+ *  1. a drawn edge WITHOUT `consumes` into a service — its source is a
+ *     caller, whether or not the edge carries an `op` (an op edge and a plain
+ *     edge are one claim of dependence each);
+ *  2. a drawn edge carrying `consumes` — the rule of
+ *     commands/validate/service/events/events.ts: `consumes` binds the edge's
+ *     TARGET as the consumer and its SOURCE as the producer, so an edge drawn
+ *     producer→consumer is fan-in on the SOURCE. Such an edge contributes
+ *     join 2 ONLY: on the event spine THE ARROW FOLLOWS THE MESSAGE (the
+ *     scaffolded landscape's own doctrine, examples/docs' landscape spells
+ *     it), so the arrow of a delivery edge is not a call into its target —
+ *     reading it as one would rank a pure event sink above a real dependency
+ *     and hand a bound broker service one phantom dependant per consumer;
+ *  3. the landscape-independent requirement join — a service consumes a
+ *     message some other service declares `action: send` for.
+ * Self-dependence proves nothing, and an endpoint outside the known-service
+ * set (an actor, an `#external` system, an unresolved id) is not a fleet
+ * caller — review order ranks work the FLEET depends on.
+ */
+export function fleetFanIn(req) {
+    const known = new Set(req.services);
+    const consumers = new Map();
+    const depend = (producer, consumer) => {
+        if (producer === consumer)
+            return;
+        if (!known.has(producer) || !known.has(consumer))
+            return;
+        const set = consumers.get(producer) ?? new Set();
+        set.add(consumer);
+        consumers.set(producer, set);
+    };
+    if (req.landscape.parses) {
+        const { relationships, svcOf } = req.landscape;
+        for (const r of relationships) {
+            const source = svcOf(r.source);
+            const target = svcOf(r.target);
+            // The variants of the join comment above: a delivery edge (consumes)
+            // claims producer→consumer, never a call into its target.
+            if (r.consumes === undefined)
+                depend(target, source);
+            else
+                depend(source, target);
+        }
+    }
+    // Join 3. Producer index first: message name → every service declaring it
+    // sent. A message more than one service declares lands its subscribers on
+    // every declarer — the derivation never guesses which declaration wins.
+    const producers = new Map();
+    for (const [id, slice] of req.contracts) {
+        if (!known.has(id))
+            continue;
+        for (const message of slice.sent) {
+            producers.set(message, [...(producers.get(message) ?? []), id]);
+        }
+    }
+    for (const [id, slice] of req.contracts) {
+        if (!known.has(id))
+            continue;
+        for (const message of slice.consumed) {
+            for (const producer of producers.get(message) ?? [])
+                depend(producer, id);
+        }
+    }
+    return new Map(req.services.map((id) => [id, consumers.get(id)?.size ?? 0]));
+}
+//# sourceMappingURL=fanin.js.map

package/dist/core/dependencies/fanin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fanin.js","sourceRoot":"","sources":["../../../src/core/dependencies/fanin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA2CH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,UAAU,CAAC,GAAiB;IAC1C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;IACjD,MAAM,MAAM,GAAG,CAAC,QAAgB,EAAE,QAAgB,EAAQ,EAAE;QAC1D,IAAI,QAAQ,KAAK,QAAQ;YAAE,OAAO;QAClC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO;QACzD,MAAM,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,GAAG,EAAU,CAAC;QACzD,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClB,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC,CAAC;IAEF,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,SAAS,CAAC;QAC/C,KAAK,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;YAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC/B,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC/B,qEAAqE;YACrE,0DAA0D;YAC1D,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS;gBAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;;gBAChD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,0EAA0E;IAC1E,wEAAwE;IACxE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC9C,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,SAAS;QAC7B,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACjC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,SAAS;QAC7B,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACrC,KAAK,MAAM,QAAQ,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE;gBAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC/E,CAAC","sourcesContent":["/**\n * Fleet fan-in: for each service, how many DISTINCT other known services\n * depend on it — the blast radius behind `loam list --needs-work\n * --review-order`. Reviewing the most-depended-on service first is the one\n * ordering a campaign lead cannot derive by eye from the worklist.\n *\n * Pure derivation, derived-never-stored, in the package that already owns\n * who-depends-on-whom: `core/dependencies/` derives the feature ordering from\n * artifact identities, and this module derives the service-level analog. The\n * command layer (commands/list/review.ts) gathers the inputs from reads the\n * repository already pays for and hands them in as data, so the module itself\n * imports nothing — no IO, no parser import, never prints. The edge slice is\n * structural for the same reason `core/vocabulary/maturity.ts`'s EdgeSource\n * is: `core/c4/likec4.ts`'s `Rel` satisfies it without an import edge into\n * the parser.\n */\n\n/** The slice of a drawn relationship the joins read. */\nexport interface FanInEdge {\n  source: string;\n  target: string;\n  /** AsyncAPI message this edge CONSUMES — binds the TARGET as the consumer. */\n  consumes?: string;\n}\n\n/** One service's contract slice: what it declares it sends, and what its living requirements consume. */\nexport interface FanInContracts {\n  /** Message names this service's asyncapi.yaml reaches from an `action: send` operation. */\n  sent: readonly string[];\n  /** Message names the service's living (non-REMOVED) spec/arch requirements carry on `Consumes:` lines. */\n  consumed: readonly string[];\n}\n\n/**\n * The fleet map's contribution, as a variant rather than optional fields: a\n * landscape either parses — and then it has relationships and a resolver — or\n * it proves nothing, and there is no half-state in which `parses: false`\n * arrives carrying edges anyway. Positive evidence only, the rule\n * `landscapeEvidence` (core/vocabulary/maturity.ts) spells for the same map:\n * an absent or unparseable landscape contributes NOTHING to the edge joins,\n * while the requirement join below still counts.\n */\nexport type FanInLandscape =\n  | {\n      parses: true;\n      relationships: readonly FanInEdge[];\n      /** The shared container-aware resolver (`core/c4/resolve/service.ts` serviceResolver), widened to plain strings. */\n      svcOf: (id: string) => string;\n    }\n  | { parses: false };\n\nexport interface FanInRequest {\n  /** Every known service id — the universe both ends of every join are filtered to. */\n  services: readonly string[];\n  landscape: FanInLandscape;\n  contracts: ReadonlyMap<string, FanInContracts>;\n}\n\n/**\n * Distinct known consumers per service, as a count for every id in\n * `req.services` (0 when nothing depends on it — a proven zero, since only\n * positive evidence ever increments it).\n *\n * Three joins, unioned by DISTINCT consumer so overlapping evidence for one\n * caller counts once:\n *  1. a drawn edge WITHOUT `consumes` into a service — its source is a\n *     caller, whether or not the edge carries an `op` (an op edge and a plain\n *     edge are one claim of dependence each);\n *  2. a drawn edge carrying `consumes` — the rule of\n *     commands/validate/service/events/events.ts: `consumes` binds the edge's\n *     TARGET as the consumer and its SOURCE as the producer, so an edge drawn\n *     producer→consumer is fan-in on the SOURCE. Such an edge contributes\n *     join 2 ONLY: on the event spine THE ARROW FOLLOWS THE MESSAGE (the\n *     scaffolded landscape's own doctrine, examples/docs' landscape spells\n *     it), so the arrow of a delivery edge is not a call into its target —\n *     reading it as one would rank a pure event sink above a real dependency\n *     and hand a bound broker service one phantom dependant per consumer;\n *  3. the landscape-independent requirement join — a service consumes a\n *     message some other service declares `action: send` for.\n * Self-dependence proves nothing, and an endpoint outside the known-service\n * set (an actor, an `#external` system, an unresolved id) is not a fleet\n * caller — review order ranks work the FLEET depends on.\n */\nexport function fleetFanIn(req: FanInRequest): Map<string, number> {\n  const known = new Set(req.services);\n  const consumers = new Map<string, Set<string>>();\n  const depend = (producer: string, consumer: string): void => {\n    if (producer === consumer) return;\n    if (!known.has(producer) || !known.has(consumer)) return;\n    const set = consumers.get(producer) ?? new Set<string>();\n    set.add(consumer);\n    consumers.set(producer, set);\n  };\n\n  if (req.landscape.parses) {\n    const { relationships, svcOf } = req.landscape;\n    for (const r of relationships) {\n      const source = svcOf(r.source);\n      const target = svcOf(r.target);\n      // The variants of the join comment above: a delivery edge (consumes)\n      // claims producer→consumer, never a call into its target.\n      if (r.consumes === undefined) depend(target, source);\n      else depend(source, target);\n    }\n  }\n\n  // Join 3. Producer index first: message name → every service declaring it\n  // sent. A message more than one service declares lands its subscribers on\n  // every declarer — the derivation never guesses which declaration wins.\n  const producers = new Map<string, string[]>();\n  for (const [id, slice] of req.contracts) {\n    if (!known.has(id)) continue;\n    for (const message of slice.sent) {\n      producers.set(message, [...(producers.get(message) ?? []), id]);\n    }\n  }\n  for (const [id, slice] of req.contracts) {\n    if (!known.has(id)) continue;\n    for (const message of slice.consumed) {\n      for (const producer of producers.get(message) ?? []) depend(producer, id);\n    }\n  }\n\n  return new Map(req.services.map((id) => [id, consumers.get(id)?.size ?? 0]));\n}\n"]}

package/dist/core/dependencies/graph.js

@@ -0,0 +1,106 @@
+/**
+ * The graph arithmetic: which edges exist, which of them form a cycle, and what
+ * order the features can be archived in.
+ *
+ * Kept apart from `./facts.ts` because it knows nothing about requirements or
+ * operations — it takes ids and edges. That is what makes the cycle detection
+ * and the ordering testable against a graph nobody had to build a fleet for,
+ * and it is why `compareIds` sorts every adjacency list: the answer has to be
+ * the same on two machines that enumerated the docs tree in different orders.
+ */
+import { compareIds } from "../repo/entries.js";
+import {} from "./facts.js";
+export function compareReasons(a, b) {
+    const ak = a.kind === "requirement"
+        ? `${a.kind}\0${a.service}\0${a.axis}\0${a.identity}`
+        : `${a.kind}\0${a.service}\0${a.operationId}`;
+    const bk = b.kind === "requirement"
+        ? `${b.kind}\0${b.service}\0${b.axis}\0${b.identity}`
+        : `${b.kind}\0${b.service}\0${b.operationId}`;
+    return compareIds(ak, bk);
+}
+export function edgeKey(from, to) {
+    return `${from}\0${to}`;
+}
+export function appendReason(edges, from, to, reason) {
+    if (from === to)
+        return;
+    const key = edgeKey(from, to);
+    const edge = edges.get(key) ?? { from, to, reasons: [] };
+    const encoded = JSON.stringify(reason);
+    if (!edge.reasons.some((item) => JSON.stringify(item) === encoded))
+        edge.reasons.push(reason);
+    edges.set(key, edge);
+}
+export function stronglyConnected(ids, edges) {
+    const adjacency = new Map(ids.map((id) => [id, []]));
+    for (const edge of edges)
+        adjacency.get(edge.from)?.push(edge.to);
+    for (const targets of adjacency.values())
+        targets.sort(compareIds);
+    let nextIndex = 0;
+    const indices = new Map();
+    const low = new Map();
+    const stack = [];
+    const onStack = new Set();
+    const components = [];
+    const visit = (id) => {
+        indices.set(id, nextIndex);
+        low.set(id, nextIndex);
+        nextIndex += 1;
+        stack.push(id);
+        onStack.add(id);
+        for (const target of adjacency.get(id) ?? []) {
+            if (!indices.has(target)) {
+                visit(target);
+                low.set(id, Math.min(low.get(id), low.get(target)));
+            }
+            else if (onStack.has(target)) {
+                low.set(id, Math.min(low.get(id), indices.get(target)));
+            }
+        }
+        if (low.get(id) !== indices.get(id))
+            return;
+        const component = [];
+        while (stack.length > 0) {
+            const member = stack.pop();
+            onStack.delete(member);
+            component.push(member);
+            if (member === id)
+                break;
+        }
+        component.sort(compareIds);
+        const selfLoop = component.length === 1
+            && (adjacency.get(component[0]) ?? []).includes(component[0]);
+        if (component.length > 1 || selfLoop)
+            components.push(component);
+    };
+    for (const id of [...ids].sort(compareIds))
+        if (!indices.has(id))
+            visit(id);
+    return components.sort((a, b) => compareIds(a[0], b[0]));
+}
+export function dependencyFirstOrder(ids, edges) {
+    const deps = new Map(ids.map((id) => [id, []]));
+    for (const edge of edges)
+        deps.get(edge.from)?.push(edge.to);
+    for (const values of deps.values())
+        values.sort(compareIds);
+    const visited = new Set();
+    const visiting = new Set();
+    const order = [];
+    const visit = (id) => {
+        if (visited.has(id) || visiting.has(id))
+            return;
+        visiting.add(id);
+        for (const dependency of deps.get(id) ?? [])
+            visit(dependency);
+        visiting.delete(id);
+        visited.add(id);
+        order.push(id);
+    };
+    for (const id of [...ids].sort(compareIds))
+        visit(id);
+    return order;
+}
+//# sourceMappingURL=graph.js.map

package/dist/core/dependencies/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../../src/core/dependencies/graph.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The graph arithmetic: which edges exist, which of them form a cycle, and what\n * order the features can be archived in.\n *\n * Kept apart from `./facts.ts` because it knows nothing about requirements or\n * operations — it takes ids and edges. That is what makes the cycle detection\n * and the ordering testable against a graph nobody had to build a fleet for,\n * and it is why `compareIds` sorts every adjacency list: the answer has to be\n * the same on two machines that enumerated the docs tree in different orders.\n */\nimport { compareIds } from \"../repo/entries.js\";\nimport { type DependencyEdge, type DependencyReason } from \"./facts.js\";\n\nexport function compareReasons(a: DependencyReason, b: DependencyReason): number {\n  const ak = a.kind === \"requirement\"\n    ? `${a.kind}\\0${a.service}\\0${a.axis}\\0${a.identity}`\n    : `${a.kind}\\0${a.service}\\0${a.operationId}`;\n  const bk = b.kind === \"requirement\"\n    ? `${b.kind}\\0${b.service}\\0${b.axis}\\0${b.identity}`\n    : `${b.kind}\\0${b.service}\\0${b.operationId}`;\n  return compareIds(ak, bk);\n}\n\nexport function edgeKey(from: string, to: string): string {\n  return `${from}\\0${to}`;\n}\n\nexport function appendReason(\n  edges: Map<string, DependencyEdge>,\n  from: string,\n  to: string,\n  reason: DependencyReason,\n): void {\n  if (from === to) return;\n  const key = edgeKey(from, to);\n  const edge = edges.get(key) ?? { from, to, reasons: [] };\n  const encoded = JSON.stringify(reason);\n  if (!edge.reasons.some((item) => JSON.stringify(item) === encoded)) edge.reasons.push(reason);\n  edges.set(key, edge);\n}\n\nexport function stronglyConnected(ids: string[], edges: DependencyEdge[]): string[][] {\n  const adjacency = new Map(ids.map((id) => [id, [] as string[]]));\n  for (const edge of edges) adjacency.get(edge.from)?.push(edge.to);\n  for (const targets of adjacency.values()) targets.sort(compareIds);\n\n  let nextIndex = 0;\n  const indices = new Map<string, number>();\n  const low = new Map<string, number>();\n  const stack: string[] = [];\n  const onStack = new Set<string>();\n  const components: string[][] = [];\n\n  const visit = (id: string): void => {\n    indices.set(id, nextIndex);\n    low.set(id, nextIndex);\n    nextIndex += 1;\n    stack.push(id);\n    onStack.add(id);\n\n    for (const target of adjacency.get(id) ?? []) {\n      if (!indices.has(target)) {\n        visit(target);\n        low.set(id, Math.min(low.get(id)!, low.get(target)!));\n      } else if (onStack.has(target)) {\n        low.set(id, Math.min(low.get(id)!, indices.get(target)!));\n      }\n    }\n    if (low.get(id) !== indices.get(id)) return;\n    const component: string[] = [];\n    while (stack.length > 0) {\n      const member = stack.pop()!;\n      onStack.delete(member);\n      component.push(member);\n      if (member === id) break;\n    }\n    component.sort(compareIds);\n    const selfLoop = component.length === 1\n      && (adjacency.get(component[0]!) ?? []).includes(component[0]!);\n    if (component.length > 1 || selfLoop) components.push(component);\n  };\n\n  for (const id of [...ids].sort(compareIds)) if (!indices.has(id)) visit(id);\n  return components.sort((a, b) => compareIds(a[0]!, b[0]!));\n}\n\nexport function dependencyFirstOrder(ids: string[], edges: DependencyEdge[]): string[] {\n  const deps = new Map(ids.map((id) => [id, [] as string[]]));\n  for (const edge of edges) deps.get(edge.from)?.push(edge.to);\n  for (const values of deps.values()) values.sort(compareIds);\n  const visited = new Set<string>();\n  const visiting = new Set<string>();\n  const order: string[] = [];\n  const visit = (id: string): void => {\n    if (visited.has(id) || visiting.has(id)) return;\n    visiting.add(id);\n    for (const dependency of deps.get(id) ?? []) visit(dependency);\n    visiting.delete(id);\n    visited.add(id);\n    order.push(id);\n  };\n  for (const id of [...ids].sort(compareIds)) visit(id);\n  return order;\n}\n"]}

package/dist/core/diff/base-git.js

@@ -0,0 +1,148 @@
+/**
+ * Git-at-a-ref reader for the DOCS repo — the base side of `loam diff`.
+ *
+ * Three questions, all read-only: does this docs directory sit in a git
+ * repository and where (`resolveBase`), what did `services/` hold at the base
+ * commit (`listBaseTree`), and what were one file's bytes there
+ * (`showBaseFile`). No checkout, no temp writes — the base state is read
+ * straight out of the object store with `rev-parse`/`ls-tree`/`show`.
+ *
+ * The doctrine here is deliberately NOT provenance's. `../provenance/git.ts`
+ * answers every git decline with "git will not say" — null, no finding —
+ * because provenance has no denominator without git and nothing to report.
+ * Diff is the opposite case: without the base there is no honest diff at all,
+ * and a silently empty base would report the whole fleet as ADDED — the exact
+ * "green over zero services" failure `docsRepoReady` exists to prevent, one
+ * step later. So every decline travels as a typed outcome the command REFUSES
+ * on, carrying git's own words (bounded) so the refusal can say why.
+ *
+ * What is shared with provenance is the mechanics: the one timeout and the
+ * capped stdout reader, so rule 20 (every child spawn bounded) holds by
+ * construction.
+ */
+import { spawn } from "node:child_process";
+import { collectStderr, declineDetail, GIT_TIMEOUT_MS, gitSaid, gitText } from "../provenance/git.js";
+/**
+ * How many bytes one base file may be — the same generosity as
+ * `../provenance/git.ts`'s stdout cap, restated here because that constant is
+ * private to its module and this one collects BYTES, not text (a base
+ * contract's UTF-8-ness is a fact to grade, and `setEncoding("utf8")` would
+ * substitute U+FFFD before anyone could check). Past the cap the child is
+ * killed and the file reads as unreadable for its subject, never truncated.
+ *
+ * The question-asking mechanics — `gitText`, `GitAnswer`, `gitSaid`,
+ * `declineDetail`, `collectStderr` — are the shared set exported beside
+ * `collectStdout`: `../provenance/gitq/vouched-ancestor.ts` asks with the
+ * same shapes and the opposite consequence (it degrades to "full read" where
+ * this module's callers REFUSE), and the helpers stay verdict-free so the two
+ * doctrines cannot bleed into each other through a shared line.
+ */
+const MAX_BASE_FILE_BYTES = 64 * 1024 * 1024;
+/**
+ * Resolve the base: is `docsDir` inside a git work tree, where does it sit in
+ * that repository, and which commit does `ref` name?
+ *
+ * `--show-prefix` is asked FIRST and is not decoration: a docs repo checked
+ * out as a subdirectory of a larger repository (a monorepo's `docs/`) answers
+ * every later `ls-tree`/`show` only under that prefix. Dropping it makes every
+ * path miss, and a diff whose base paths all miss reports the whole fleet as
+ * added — silently, in exactly the repositories big enough to care.
+ */
+export async function resolveBase(docsDir, ref) {
+    const where = await gitText(docsDir, ["rev-parse", "--show-prefix"]);
+    if (where.spawnError !== undefined || where.code !== 0) {
+        return { kind: "no-git", detail: declineDetail(where) };
+    }
+    // A ref spelled like an option would be parsed as one by git, not resolved
+    // as a revision — refuse it before it reaches an argv. Same reason the MCP
+    // argv boundary refuses '-'-prefixed strings.
+    const spelled = ref.trim();
+    if (spelled === "" || spelled.startsWith("-")) {
+        return { kind: "no-ref", detail: "a ref must be a revision name, not empty and not option-shaped." };
+    }
+    // `^{commit}` peels an annotated tag to the commit it tags, and refuses a
+    // ref that names any other object kind — a tree or blob sha is not a base
+    // state to diff against.
+    const verified = await gitText(docsDir, ["rev-parse", "--verify", `${spelled}^{commit}`]);
+    const commit = verified.out.trim();
+    if (verified.code !== 0 || !/^[0-9a-f]{40}$/.test(commit)) {
+        const said = gitSaid(verified);
+        return { kind: "no-ref", detail: said === "" ? "" : `git said: ${said}` };
+    }
+    return { kind: "ok", commit, prefix: where.out.trim() };
+}
+/**
+ * Every file path under `services/` at the base commit, DOCS-RELATIVE
+ * (`services/...`, prefix already stripped). `--full-tree` anchors both the
+ * pathspec and the output at the repository root regardless of cwd, so the
+ * one prefix from `resolveBase` is the whole story; `-z` because git quotes
+ * non-ASCII paths in line output. An empty answer is git ANSWERING — the base
+ * commit simply has no `services/` — and only a non-zero exit is a failure.
+ */
+export async function listBaseTree(base) {
+    const answer = await gitText(base.docsDir, [
+        "ls-tree", "-r", "-z", "--name-only", "--full-tree", base.commit, "--", `${base.prefix}services`,
+    ]);
+    if (answer.spawnError !== undefined || answer.code !== 0 || answer.overflowed) {
+        return {
+            kind: "failed",
+            detail: answer.overflowed
+                ? "the base tree listing exceeded the output cap."
+                : declineDetail(answer),
+        };
+    }
+    return {
+        kind: "ok",
+        paths: answer.out
+            .split("\0")
+            .filter((p) => p.startsWith(base.prefix) && p !== "")
+            .map((p) => p.slice(base.prefix.length)),
+    };
+}
+/**
+ * One base file's bytes, by docs-relative path. Callers only ask for paths
+ * `listBaseTree` returned, so there is no "absent" arm: a decline here is
+ * abnormal and travels as `failed` for per-subject containment — that one
+ * subject degrades with the detail, never the whole diff.
+ */
+export async function showBaseFile(base, rel) {
+    return new Promise((done) => {
+        const child = spawn("git", ["show", `${base.commit}:${base.prefix}${rel}`], {
+            cwd: base.docsDir,
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: GIT_TIMEOUT_MS,
+        });
+        // Bytes, not text: `collectStdout` decodes as UTF-8, and a base contract
+        // whose bytes are NOT UTF-8 must arrive intact so base-state can grade it
+        // unreadable instead of parsing a document nobody wrote.
+        const chunks = [];
+        let held = 0;
+        let overflowed = false;
+        child.stdout.on("data", (chunk) => {
+            if (overflowed)
+                return;
+            if (held + chunk.length > MAX_BASE_FILE_BYTES) {
+                overflowed = true;
+                child.kill();
+                return;
+            }
+            chunks.push(chunk);
+            held += chunk.length;
+        });
+        const err = collectStderr(child);
+        child.on("error", (e) => done({ kind: "failed", detail: `git could not be started: ${e.message}.` }));
+        child.on("close", (code) => {
+            if (code !== 0 || overflowed) {
+                done({
+                    kind: "failed",
+                    detail: overflowed
+                        ? "the file exceeds the base-read byte cap."
+                        : declineDetail({ code, out: "", err: err(), overflowed }),
+                });
+                return;
+            }
+            done({ kind: "ok", bytes: Buffer.concat(chunks) });
+        });
+    });
+}
+//# sourceMappingURL=base-git.js.map

package/dist/core/diff/base-git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-git.js","sourceRoot":"","sources":["../../../src/core/diff/base-git.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Git-at-a-ref reader for the DOCS repo — the base side of `loam diff`.\n *\n * Three questions, all read-only: does this docs directory sit in a git\n * repository and where (`resolveBase`), what did `services/` hold at the base\n * commit (`listBaseTree`), and what were one file's bytes there\n * (`showBaseFile`). No checkout, no temp writes — the base state is read\n * straight out of the object store with `rev-parse`/`ls-tree`/`show`.\n *\n * The doctrine here is deliberately NOT provenance's. `../provenance/git.ts`\n * answers every git decline with \"git will not say\" — null, no finding —\n * because provenance has no denominator without git and nothing to report.\n * Diff is the opposite case: without the base there is no honest diff at all,\n * and a silently empty base would report the whole fleet as ADDED — the exact\n * \"green over zero services\" failure `docsRepoReady` exists to prevent, one\n * step later. So every decline travels as a typed outcome the command REFUSES\n * on, carrying git's own words (bounded) so the refusal can say why.\n *\n * What is shared with provenance is the mechanics: the one timeout and the\n * capped stdout reader, so rule 20 (every child spawn bounded) holds by\n * construction.\n */\nimport { spawn } from \"node:child_process\";\nimport { collectStderr, declineDetail, GIT_TIMEOUT_MS, gitSaid, gitText } from \"../provenance/git.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\n\n/**\n * How many bytes one base file may be — the same generosity as\n * `../provenance/git.ts`'s stdout cap, restated here because that constant is\n * private to its module and this one collects BYTES, not text (a base\n * contract's UTF-8-ness is a fact to grade, and `setEncoding(\"utf8\")` would\n * substitute U+FFFD before anyone could check). Past the cap the child is\n * killed and the file reads as unreadable for its subject, never truncated.\n *\n * The question-asking mechanics — `gitText`, `GitAnswer`, `gitSaid`,\n * `declineDetail`, `collectStderr` — are the shared set exported beside\n * `collectStdout`: `../provenance/gitq/vouched-ancestor.ts` asks with the\n * same shapes and the opposite consequence (it degrades to \"full read\" where\n * this module's callers REFUSE), and the helpers stay verdict-free so the two\n * doctrines cannot bleed into each other through a shared line.\n */\nconst MAX_BASE_FILE_BYTES = 64 * 1024 * 1024;\n\nexport type BaseResolution =\n  | { kind: \"no-git\"; detail: string }\n  | { kind: \"no-ref\"; detail: string }\n  | { kind: \"ok\"; commit: string; prefix: string };\n\n/**\n * Resolve the base: is `docsDir` inside a git work tree, where does it sit in\n * that repository, and which commit does `ref` name?\n *\n * `--show-prefix` is asked FIRST and is not decoration: a docs repo checked\n * out as a subdirectory of a larger repository (a monorepo's `docs/`) answers\n * every later `ls-tree`/`show` only under that prefix. Dropping it makes every\n * path miss, and a diff whose base paths all miss reports the whole fleet as\n * added — silently, in exactly the repositories big enough to care.\n */\nexport async function resolveBase(docsDir: DocsDir, ref: string): Promise<BaseResolution> {\n  const where = await gitText(docsDir, [\"rev-parse\", \"--show-prefix\"]);\n  if (where.spawnError !== undefined || where.code !== 0) {\n    return { kind: \"no-git\", detail: declineDetail(where) };\n  }\n  // A ref spelled like an option would be parsed as one by git, not resolved\n  // as a revision — refuse it before it reaches an argv. Same reason the MCP\n  // argv boundary refuses '-'-prefixed strings.\n  const spelled = ref.trim();\n  if (spelled === \"\" || spelled.startsWith(\"-\")) {\n    return { kind: \"no-ref\", detail: \"a ref must be a revision name, not empty and not option-shaped.\" };\n  }\n  // `^{commit}` peels an annotated tag to the commit it tags, and refuses a\n  // ref that names any other object kind — a tree or blob sha is not a base\n  // state to diff against.\n  const verified = await gitText(docsDir, [\"rev-parse\", \"--verify\", `${spelled}^{commit}`]);\n  const commit = verified.out.trim();\n  if (verified.code !== 0 || !/^[0-9a-f]{40}$/.test(commit)) {\n    const said = gitSaid(verified);\n    return { kind: \"no-ref\", detail: said === \"\" ? \"\" : `git said: ${said}` };\n  }\n  return { kind: \"ok\", commit, prefix: where.out.trim() };\n}\n\n/** The resolved base every later question is asked against. */\nexport interface ResolvedBase {\n  docsDir: DocsDir;\n  commit: string;\n  /** The docs repo's path inside its repository, `\"\"` or `\"docs/\"`-shaped — `rev-parse --show-prefix`'s answer. */\n  prefix: string;\n}\n\nexport type BaseTreeListing =\n  | { kind: \"ok\"; paths: string[] }\n  | { kind: \"failed\"; detail: string };\n\n/**\n * Every file path under `services/` at the base commit, DOCS-RELATIVE\n * (`services/...`, prefix already stripped). `--full-tree` anchors both the\n * pathspec and the output at the repository root regardless of cwd, so the\n * one prefix from `resolveBase` is the whole story; `-z` because git quotes\n * non-ASCII paths in line output. An empty answer is git ANSWERING — the base\n * commit simply has no `services/` — and only a non-zero exit is a failure.\n */\nexport async function listBaseTree(base: ResolvedBase): Promise<BaseTreeListing> {\n  const answer = await gitText(base.docsDir, [\n    \"ls-tree\", \"-r\", \"-z\", \"--name-only\", \"--full-tree\", base.commit, \"--\", `${base.prefix}services`,\n  ]);\n  if (answer.spawnError !== undefined || answer.code !== 0 || answer.overflowed) {\n    return {\n      kind: \"failed\",\n      detail: answer.overflowed\n        ? \"the base tree listing exceeded the output cap.\"\n        : declineDetail(answer),\n    };\n  }\n  return {\n    kind: \"ok\",\n    paths: answer.out\n      .split(\"\\0\")\n      .filter((p) => p.startsWith(base.prefix) && p !== \"\")\n      .map((p) => p.slice(base.prefix.length)),\n  };\n}\n\nexport type BaseFileRead =\n  | { kind: \"ok\"; bytes: Buffer }\n  | { kind: \"failed\"; detail: string };\n\n/**\n * One base file's bytes, by docs-relative path. Callers only ask for paths\n * `listBaseTree` returned, so there is no \"absent\" arm: a decline here is\n * abnormal and travels as `failed` for per-subject containment — that one\n * subject degrades with the detail, never the whole diff.\n */\nexport async function showBaseFile(base: ResolvedBase, rel: string): Promise<BaseFileRead> {\n  return new Promise<BaseFileRead>((done) => {\n    const child = spawn(\"git\", [\"show\", `${base.commit}:${base.prefix}${rel}`], {\n      cwd: base.docsDir,\n      stdio: [\"ignore\", \"pipe\", \"pipe\"],\n      timeout: GIT_TIMEOUT_MS,\n    });\n    // Bytes, not text: `collectStdout` decodes as UTF-8, and a base contract\n    // whose bytes are NOT UTF-8 must arrive intact so base-state can grade it\n    // unreadable instead of parsing a document nobody wrote.\n    const chunks: Buffer[] = [];\n    let held = 0;\n    let overflowed = false;\n    child.stdout.on(\"data\", (chunk: Buffer) => {\n      if (overflowed) return;\n      if (held + chunk.length > MAX_BASE_FILE_BYTES) {\n        overflowed = true;\n        child.kill();\n        return;\n      }\n      chunks.push(chunk);\n      held += chunk.length;\n    });\n    const err = collectStderr(child);\n    child.on(\"error\", (e) => done({ kind: \"failed\", detail: `git could not be started: ${e.message}.` }));\n    child.on(\"close\", (code) => {\n      if (code !== 0 || overflowed) {\n        done({\n          kind: \"failed\",\n          detail: overflowed\n            ? \"the file exceeds the base-read byte cap.\"\n            : declineDetail({ code, out: \"\", err: err(), overflowed }),\n        });\n        return;\n      }\n      done({ kind: \"ok\", bytes: Buffer.concat(chunks) });\n    });\n  });\n}\n"]}