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

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/deployment/delta.js

@@ -0,0 +1,188 @@
+/**
+ * A feature's own topology: `features/<FEAT>/deployment/<name>.likec4`.
+ *
+ * Until this slot existed a change that stood up a standby cluster had to be
+ * written in two places at once — the requirement in the feature, the topology
+ * edited straight into `architecture/` — because `delta.likec4` refuses a
+ * `deployment { }` block and always will: that document re-declares the
+ * landscape's own identifiers and carries its own `specification`, so it cannot
+ * be staged beside the map in one LikeC4 project. A document that declares
+ * NEITHER can, which is exactly why the use-case axis put its flows in files of
+ * their own, and why this mirrors it rather than inventing a shape.
+ *
+ * WHAT MAKES IT WORK, and it was measured before the axis was written: LikeC4
+ * `extend` resolves across documents of one project. A feature writes
+ *
+ *     deployment {
+ *       extend eu {
+ *         dcC = datacenter 'DC-C' { k8sC = cluster 'cluster-c' { … } }
+ *       }
+ *       eu.dcA.k8sA -> eu.dcC.k8sC 'async replication'
+ *     }
+ *
+ * and the living region gains a datacenter with the living file untouched. So
+ * the merge is a copy, not a splice, and `unarchive` needs nothing new — a
+ * create is undone by deleting, which the snapshot manifest already records for
+ * every write in the plan.
+ *
+ * CREATE-ONLY, for `core/usecases/delta/flows.ts`'s reasons rather than a
+ * weaker version of them. A requirement delta merges INTO a living document and
+ * two features editing one requirement would overwrite each other silently; a
+ * topology document has no such algebra — the file is one block, the merge is a
+ * whole-file copy, and there is nothing to merge partially. Rewriting a living
+ * one through a feature would be a silent whole-file replacement with no pin to
+ * collide on, where editing `architecture/<name>.likec4` directly in the same
+ * pull request produces an ordinary git conflict a human resolves.
+ *
+ * ## Graded against the map its own merge would leave behind
+ *
+ * `ARCH-LOAM-FEATURE-CORPUS`, and this axis needs it more literally than the
+ * use-case one does: a feature that stands a service up in a new cluster
+ * declares that service in its `delta.likec4` and instances it here, so the
+ * element the topology names exists ONLY post-merge. Read against the living
+ * landscape it is unresolved, LikeC4 refuses the whole project, and loam would
+ * report a hole against a file whose only fault is arriving with the change
+ * that makes it true.
+ *
+ * The staging is `core/c4/project/staged.ts`, shared with the use-case slot
+ * rather than copied — the two would have disagreed first about the merge
+ * preview, which is the one thing both refusals rest on.
+ */
+import { existsSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { architectureDir } from "../c4/project/architecture.js";
+import { stageMergedProject } from "../c4/project/staged.js";
+import {} from "../c4/likec4.js";
+import { architectureDocuments } from "../c4/project/documents.js";
+import { featureDeploymentDir } from "../repo/authored/paths.js";
+import { reservedArchitectureName } from "../repo/paths.js";
+import {} from "../vocabulary/issue.js";
+/**
+ * The topology documents one feature carries, ordered by path.
+ *
+ * Zero readdirs when the feature has no `deployment/` directory, which is every
+ * feature in a fleet that has not adopted the axis: `architectureDocuments`
+ * answers an absent directory with an empty list rather than a throw. That
+ * directory's existence is the whole per-feature opt-in.
+ */
+export async function featureDeployments(featureDir) {
+    const dir = featureDeploymentDir(featureDir);
+    const paths = await architectureDocuments(dir);
+    const base = resolve(dir);
+    return paths.map((path) => ({ rel: relative(base, path).split(/[\\/]/).join("/"), path }));
+}
+/**
+ * The LIVING path a feature-local topology document addresses.
+ *
+ * Straight into `architecture/`, with no subdirectory of its own — unlike
+ * `architecture/usecases/`, and the difference is the model rather than taste.
+ * A `deployment { }` block is part of the fleet's ONE architecture project and
+ * is read as such by every loader; filing it under a subdirectory would suggest
+ * a second project, which is exactly the reading `subsystems.likec4` and
+ * `landscape.likec4` already refuse by sitting at the top level together.
+ *
+ * `rel` is joined un-split, which `node:path` normalizes. What holds the join is
+ * PROVENANCE: every `rel` here came out of an `architectureDocuments` walk, so
+ * each component is a directory entry that exists. No caller takes one from argv.
+ */
+export function livingDeploymentPath(docsDir, rel) {
+    return join(architectureDir(docsDir), rel);
+}
+/**
+ * The two things that can go wrong about a topology document's NAME, before
+ * anything about its contents is asked.
+ *
+ * `deployment.doc-reserved` — the name is one loam owns inside `architecture/`.
+ * The merge writes straight into that directory, unlike a flow, which lands
+ * under `usecases/`, so `<name>` is free to collide with the living map, the
+ * generated subsystem views, or the flow tree. `reservedArchitectureName`
+ * carries which and why. It is asked FIRST and WITHOUT an existence test,
+ * because two of the three fail silently when the target does not exist yet.
+ *
+ * `deployment.doc-exists` — a topology document this feature introduces that
+ * the living `architecture/` already holds.
+ *
+ * An ERROR and never a warning-that-gates, for `usecase.flow-exists`'s reason:
+ * there is no legal reading of it. The merge would replace an authored topology
+ * wholesale, and no `--approve` makes that a different act than it is. Two
+ * features introducing the same file is the case that makes it load-bearing
+ * rather than pedantic — whichever archives first creates the living document,
+ * and the second is told before it merges that its own file is the one to
+ * delete.
+ *
+ * The collision is on the FILE, not on what is inside it. Two features may both
+ * extend the same living region from two documents of their own and both
+ * archive; that is the shape `extend` exists for, and refusing it would make the
+ * slot useless for the fleet-wide change it was built for.
+ */
+export async function deploymentDeltaIssues(docsDir, featureDir) {
+    const docs = await featureDeployments(featureDir);
+    const issues = [];
+    // The reservation runs FIRST and independently of existence, because two of
+    // the three names it refuses need not exist for the merge to be wrong. A
+    // topology copied over `subsystems.likec4` is destroyed by the next
+    // `loam subsystem sync` and is invisible to every project load until then —
+    // the merge would report `created architecture/subsystems.likec4` and nothing
+    // downstream would ever say another word about it.
+    for (const doc of docs) {
+        const reason = reservedArchitectureName(doc.rel);
+        if (reason === null)
+            continue;
+        issues.push({
+            severity: "error",
+            code: "deployment.doc-reserved",
+            subject: doc.rel,
+            message: `features/<FEAT>/deployment/${doc.rel} would merge to architecture/${doc.rel}, and that name is loam's: ` +
+                `${reason}. Rename the feature's document — its name is yours to choose, and \`extend\` is how it adds to ` +
+                "what a living document already declares.",
+        });
+    }
+    return issues.concat(docs
+        .filter((doc) => reservedArchitectureName(doc.rel) === null)
+        .filter((doc) => existsSync(livingDeploymentPath(docsDir, doc.rel)))
+        .map((doc) => ({
+        severity: "error",
+        code: "deployment.doc-exists",
+        subject: doc.rel,
+        message: `architecture/${doc.rel} already exists, so this feature's topology would replace an authored one wholesale — ` +
+            "a feature-local deployment document INTRODUCES topology, it does not rewrite it. " +
+            `Delete features/<FEAT>/deployment/${doc.rel} and edit architecture/${doc.rel} directly in this same change, ` +
+            "where git produces an ordinary conflict if somebody else is editing it too. " +
+            `To ADD to what that file declares, write a document of another name that says \`extend\` — ` +
+            `\`${suggest(doc.rel)}\` — which is what lets two features grow one region without touching each other.`,
+    })));
+}
+/**
+ * Parse this feature's topology documents over the post-merge map.
+ *
+ * A feature with no `deployment/` directory is `read` at the cost of one walk
+ * over a directory that is not there — the axis's per-feature opt-in, and the
+ * whole price a fleet that has not adopted it pays. Nothing is staged, nothing
+ * is parsed, and no temp tree is made.
+ *
+ * The verdict is deliberately BINARY. The use-case overlay hands its caller the
+ * views it read because the axis has questions about their content; this one
+ * has none — a topology document is checked by being parseable against the map
+ * the merge will write, and everything else about it is graded by
+ * `loam validate --all` once it is living, exactly as the landscape is.
+ */
+export async function readFeatureDeployments(req) {
+    const docs = await featureDeployments(req.featureDir);
+    if (docs.length === 0)
+        return { kind: "read" };
+    const staged = await stageMergedProject({
+        docsDir: req.docsDir,
+        featureDir: req.featureDir,
+        featureId: req.featureId,
+        documents: docs.map((doc) => ({ rel: doc.rel, path: doc.path })),
+        ...(req.load === undefined ? {} : { load: req.load }),
+    });
+    return staged.kind === "unreadable" ? { kind: "unreadable", errors: staged.errors } : { kind: "read" };
+}
+/** A free name near the colliding one, so the fix is a rename the author can copy. */
+function suggest(rel) {
+    const name = basename(rel).replace(/\.likec4$/, "");
+    const dir = rel.slice(0, rel.length - basename(rel).length);
+    return `${dir}${name}-extend.likec4`;
+}
+//# sourceMappingURL=delta.js.map

package/dist/core/deployment/delta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.js","sourceRoot":"","sources":["../../../src/core/deployment/delta.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A feature's own topology: `features/<FEAT>/deployment/<name>.likec4`.\n *\n * Until this slot existed a change that stood up a standby cluster had to be\n * written in two places at once — the requirement in the feature, the topology\n * edited straight into `architecture/` — because `delta.likec4` refuses a\n * `deployment { }` block and always will: that document re-declares the\n * landscape's own identifiers and carries its own `specification`, so it cannot\n * be staged beside the map in one LikeC4 project. A document that declares\n * NEITHER can, which is exactly why the use-case axis put its flows in files of\n * their own, and why this mirrors it rather than inventing a shape.\n *\n * WHAT MAKES IT WORK, and it was measured before the axis was written: LikeC4\n * `extend` resolves across documents of one project. A feature writes\n *\n *     deployment {\n *       extend eu {\n *         dcC = datacenter 'DC-C' { k8sC = cluster 'cluster-c' { … } }\n *       }\n *       eu.dcA.k8sA -> eu.dcC.k8sC 'async replication'\n *     }\n *\n * and the living region gains a datacenter with the living file untouched. So\n * the merge is a copy, not a splice, and `unarchive` needs nothing new — a\n * create is undone by deleting, which the snapshot manifest already records for\n * every write in the plan.\n *\n * CREATE-ONLY, for `core/usecases/delta/flows.ts`'s reasons rather than a\n * weaker version of them. A requirement delta merges INTO a living document and\n * two features editing one requirement would overwrite each other silently; a\n * topology document has no such algebra — the file is one block, the merge is a\n * whole-file copy, and there is nothing to merge partially. Rewriting a living\n * one through a feature would be a silent whole-file replacement with no pin to\n * collide on, where editing `architecture/<name>.likec4` directly in the same\n * pull request produces an ordinary git conflict a human resolves.\n *\n * ## Graded against the map its own merge would leave behind\n *\n * `ARCH-LOAM-FEATURE-CORPUS`, and this axis needs it more literally than the\n * use-case one does: a feature that stands a service up in a new cluster\n * declares that service in its `delta.likec4` and instances it here, so the\n * element the topology names exists ONLY post-merge. Read against the living\n * landscape it is unresolved, LikeC4 refuses the whole project, and loam would\n * report a hole against a file whose only fault is arriving with the change\n * that makes it true.\n *\n * The staging is `core/c4/project/staged.ts`, shared with the use-case slot\n * rather than copied — the two would have disagreed first about the merge\n * preview, which is the one thing both refusals rest on.\n */\nimport { existsSync } from \"node:fs\";\nimport { basename, join, relative, resolve } from \"node:path\";\nimport { architectureDir } from \"../c4/project/architecture.js\";\nimport { stageMergedProject } from \"../c4/project/staged.js\";\nimport { type LoadedDoc } from \"../c4/likec4.js\";\nimport { architectureDocuments } from \"../c4/project/documents.js\";\nimport { featureDeploymentDir } from \"../repo/authored/paths.js\";\nimport { reservedArchitectureName } from \"../repo/paths.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { type Issue } from \"../vocabulary/issue.js\";\n\n/** One topology document a feature carries. */\nexport interface FeatureDeployment {\n  /**\n   * The path INSIDE the feature's `deployment/` directory, `/`-separated — the\n   * id this axis has. Nesting is spelled by the tree, as it is for every other\n   * authored tree in the repo.\n   */\n  rel: string;\n  /** The absolute path of the authored file. */\n  path: string;\n}\n\n/**\n * The topology documents one feature carries, ordered by path.\n *\n * Zero readdirs when the feature has no `deployment/` directory, which is every\n * feature in a fleet that has not adopted the axis: `architectureDocuments`\n * answers an absent directory with an empty list rather than a throw. That\n * directory's existence is the whole per-feature opt-in.\n */\nexport async function featureDeployments(featureDir: FeatureDir): Promise<FeatureDeployment[]> {\n  const dir = featureDeploymentDir(featureDir);\n  const paths = await architectureDocuments(dir);\n  const base = resolve(dir);\n  return paths.map((path) => ({ rel: relative(base, path).split(/[\\\\/]/).join(\"/\"), path }));\n}\n\n/**\n * The LIVING path a feature-local topology document addresses.\n *\n * Straight into `architecture/`, with no subdirectory of its own — unlike\n * `architecture/usecases/`, and the difference is the model rather than taste.\n * A `deployment { }` block is part of the fleet's ONE architecture project and\n * is read as such by every loader; filing it under a subdirectory would suggest\n * a second project, which is exactly the reading `subsystems.likec4` and\n * `landscape.likec4` already refuse by sitting at the top level together.\n *\n * `rel` is joined un-split, which `node:path` normalizes. What holds the join is\n * PROVENANCE: every `rel` here came out of an `architectureDocuments` walk, so\n * each component is a directory entry that exists. No caller takes one from argv.\n */\nexport function livingDeploymentPath(docsDir: DocsDir, rel: string): string {\n  return join(architectureDir(docsDir), rel);\n}\n\n/**\n * The two things that can go wrong about a topology document's NAME, before\n * anything about its contents is asked.\n *\n * `deployment.doc-reserved` — the name is one loam owns inside `architecture/`.\n * The merge writes straight into that directory, unlike a flow, which lands\n * under `usecases/`, so `<name>` is free to collide with the living map, the\n * generated subsystem views, or the flow tree. `reservedArchitectureName`\n * carries which and why. It is asked FIRST and WITHOUT an existence test,\n * because two of the three fail silently when the target does not exist yet.\n *\n * `deployment.doc-exists` — a topology document this feature introduces that\n * the living `architecture/` already holds.\n *\n * An ERROR and never a warning-that-gates, for `usecase.flow-exists`'s reason:\n * there is no legal reading of it. The merge would replace an authored topology\n * wholesale, and no `--approve` makes that a different act than it is. Two\n * features introducing the same file is the case that makes it load-bearing\n * rather than pedantic — whichever archives first creates the living document,\n * and the second is told before it merges that its own file is the one to\n * delete.\n *\n * The collision is on the FILE, not on what is inside it. Two features may both\n * extend the same living region from two documents of their own and both\n * archive; that is the shape `extend` exists for, and refusing it would make the\n * slot useless for the fleet-wide change it was built for.\n */\nexport async function deploymentDeltaIssues(docsDir: DocsDir, featureDir: FeatureDir): Promise<Issue[]> {\n  const docs = await featureDeployments(featureDir);\n  const issues: Issue[] = [];\n  // The reservation runs FIRST and independently of existence, because two of\n  // the three names it refuses need not exist for the merge to be wrong. A\n  // topology copied over `subsystems.likec4` is destroyed by the next\n  // `loam subsystem sync` and is invisible to every project load until then —\n  // the merge would report `created architecture/subsystems.likec4` and nothing\n  // downstream would ever say another word about it.\n  for (const doc of docs) {\n    const reason = reservedArchitectureName(doc.rel);\n    if (reason === null) continue;\n    issues.push({\n      severity: \"error\",\n      code: \"deployment.doc-reserved\",\n      subject: doc.rel,\n      message:\n        `features/<FEAT>/deployment/${doc.rel} would merge to architecture/${doc.rel}, and that name is loam's: ` +\n        `${reason}. Rename the feature's document — its name is yours to choose, and \\`extend\\` is how it adds to ` +\n        \"what a living document already declares.\",\n    });\n  }\n  return issues.concat(\n    docs\n      .filter((doc) => reservedArchitectureName(doc.rel) === null)\n      .filter((doc) => existsSync(livingDeploymentPath(docsDir, doc.rel)))\n      .map((doc) => ({\n        severity: \"error\" as const,\n        code: \"deployment.doc-exists\" as const,\n        subject: doc.rel,\n        message:\n          `architecture/${doc.rel} already exists, so this feature's topology would replace an authored one wholesale — ` +\n          \"a feature-local deployment document INTRODUCES topology, it does not rewrite it. \" +\n          `Delete features/<FEAT>/deployment/${doc.rel} and edit architecture/${doc.rel} directly in this same change, ` +\n          \"where git produces an ordinary conflict if somebody else is editing it too. \" +\n          `To ADD to what that file declares, write a document of another name that says \\`extend\\` — ` +\n          `\\`${suggest(doc.rel)}\\` — which is what lets two features grow one region without touching each other.`,\n      })),\n  );\n}\n\n/** What the caller needs to grade this feature's topology against the merge preview. */\nexport interface DeploymentOverlayRequest {\n  docsDir: DocsDir;\n  featureDir: FeatureDir;\n  /** The feature's id — the tag that selects the delta's own additions. */\n  featureId: string;\n  /**\n   * The caller's memoised LikeC4 read, when it has one. A FUNCTION rather than\n   * the `FleetContext` itself, for the reason the use-case overlay states: one\n   * memoised read does not justify an edge from this package to\n   * `core/fleet-context.ts`, and the edge would push it up a DAG level for\n   * nothing.\n   */\n  load?: (path: string) => Promise<LoadedDoc>;\n}\n\n/** Whether this feature's topology could be read at all, against the map its merge would leave. */\nexport type DeploymentOverlay = { kind: \"read\" } | { kind: \"unreadable\"; errors: string[] };\n\n/**\n * Parse this feature's topology documents over the post-merge map.\n *\n * A feature with no `deployment/` directory is `read` at the cost of one walk\n * over a directory that is not there — the axis's per-feature opt-in, and the\n * whole price a fleet that has not adopted it pays. Nothing is staged, nothing\n * is parsed, and no temp tree is made.\n *\n * The verdict is deliberately BINARY. The use-case overlay hands its caller the\n * views it read because the axis has questions about their content; this one\n * has none — a topology document is checked by being parseable against the map\n * the merge will write, and everything else about it is graded by\n * `loam validate --all` once it is living, exactly as the landscape is.\n */\nexport async function readFeatureDeployments(req: DeploymentOverlayRequest): Promise<DeploymentOverlay> {\n  const docs = await featureDeployments(req.featureDir);\n  if (docs.length === 0) return { kind: \"read\" };\n  const staged = await stageMergedProject({\n    docsDir: req.docsDir,\n    featureDir: req.featureDir,\n    featureId: req.featureId,\n    documents: docs.map((doc) => ({ rel: doc.rel, path: doc.path })),\n    ...(req.load === undefined ? {} : { load: req.load }),\n  });\n  return staged.kind === \"unreadable\" ? { kind: \"unreadable\", errors: staged.errors } : { kind: \"read\" };\n}\n\n/** A free name near the colliding one, so the fix is a rename the author can copy. */\nfunction suggest(rel: string): string {\n  const name = basename(rel).replace(/\\.likec4$/, \"\");\n  const dir = rel.slice(0, rel.length - basename(rel).length);\n  return `${dir}${name}-extend.likec4`;\n}\n"]}

package/dist/core/deployment/objects.js

@@ -0,0 +1,145 @@
+/**
+ * The deployment axis: which objects on the fleet's TOPOLOGY carry a rule, and
+ * who owns each of them.
+ *
+ * A `#obl-` tag is a claim about the object it sits on, and the object's model
+ * is not a property any reader can see. Before this module the same undeclared
+ * tag was `obligation.unknown` on a container and SILENCE on a datacenter,
+ * because `validate/fleet/obligations.ts` walked the logical model only — the
+ * fail-open case where a rule an architect placed does not exist for any check,
+ * and a reviewer has no way to tell that from a rule that passed. This is the
+ * derivation that closes it (FEAT-1's ARCH-LOAM-DEPLOY-TAGGED).
+ *
+ * ## The `where` string is the `Covers:` line
+ *
+ * Every finding about a tagged object tells its reader to write
+ * `Covers: <where>`, so `where` is spelled as the grammar reads it —
+ * `node:eu.dcA`, `node:a.db -> node:b.db` — and never as a bare id. A message
+ * that names an object one way and asks for a line spelled another way sends
+ * the reader round the loop twice.
+ *
+ * ## Who owns a datacenter
+ *
+ * Nobody, and the answer is `undefined` rather than a guess. An INSTANCE is
+ * owned by the service its logical element belongs to, which is a real join
+ * through the landscape's own binding; an edge between two instances of one
+ * service is owned by that service; a region, a datacenter or a cluster is
+ * owned by whoever runs the platform, and loam has no such concept. The finding
+ * changes its sentence rather than naming a service that did not ask for the
+ * work — "write it in payment-service's arch.spec.md" is actionable, and
+ * "write it in <the wrong team>'s" is worse than no attribution at all.
+ *
+ * This package is one module today and gains its second with the feature-local
+ * `features/<FEAT>/deployment/` slot, which is the step of the axis that needs
+ * `repo` and `kernel`. Nothing here reads a path.
+ */
+import {} from "../c4/likec4.js";
+import {} from "../c4/parsed/deployment.js";
+import { serviceResolver } from "../c4/resolve/service.js";
+/**
+ * Every `#obl-` tag on the deployment model, one entry per (obligation, object)
+ * pair — the same shape, and the same bare-prefix tolerance, the logical walk
+ * has: a bare `#obl-` slugs to the empty string and is KEPT, because the prefix
+ * is the author's opt-in however little follows it, and dropping it would leave
+ * an object that asked to be graded silently ungraded.
+ */
+export function taggedDeployment(deployment, elements, known, prefix) {
+    const owner = instanceOwners(deployment, elements, known);
+    const out = [];
+    const push = (tags, rest) => {
+        for (const tag of tags.filter((t) => t.startsWith(prefix))) {
+            out.push({ obligation: tag.slice(prefix.length), ...rest });
+        }
+    };
+    // Nodes first, then instances, then edges — the order the model declares them
+    // in, so a fleet report reads top-down the way the document does.
+    for (const node of deployment.nodes)
+        push(node.tags, { where: `node:${node.id}`, id: node.id });
+    for (const instance of deployment.instances) {
+        const service = owner.get(instance.id);
+        push(instance.tags, {
+            where: `node:${instance.id}`,
+            id: instance.id,
+            ...(service === undefined ? {} : { service }),
+        });
+    }
+    for (const edge of deployment.relationships) {
+        // An edge is owned only when BOTH ends agree. A replication edge between
+        // two instances of one service belongs to that service; one crossing
+        // services belongs to neither, and picking the target — the rule the
+        // logical walk uses, where the arrow means "calls" — says nothing here,
+        // because a deployment edge is as often symmetric as directed.
+        const from = owner.get(edge.source);
+        const to = owner.get(edge.target);
+        const service = from !== undefined && from === to ? from : undefined;
+        push(edge.tags, {
+            where: `node:${edge.source} -> node:${edge.target}`,
+            edge,
+            ...(service === undefined ? {} : { service }),
+        });
+    }
+    return out;
+}
+/**
+ * The topology one service is part of.
+ *
+ * Built for the CONTEXT PACK, which is the surface whose reader is an agent
+ * about to write the implementation. Before this, that pack described a
+ * service's calls and contracts and said nothing whatever about where it runs —
+ * so a failover was implemented against a map nobody had read, which is the
+ * gap FEAT-1's ARCH-LOAM-DEPLOY-UNCHECKED names alongside the sentence about
+ * what a green axis does not mean.
+ *
+ * BOTH ENDS, not only the outbound one. A replication edge is as often read
+ * from the standby's side as from the primary's, and a pack that showed only
+ * what this service points at would hide the stream it receives.
+ */
+export function serviceTopology(deployment, elements, known, service) {
+    const owner = instanceOwners(deployment, elements, known);
+    const mine = deployment.instances.filter((i) => owner.get(i.id) === service);
+    const ids = new Set(mine.map((i) => i.id));
+    return {
+        instances: mine.map((i) => ({ id: i.id, element: i.element })),
+        edges: deployment.relationships
+            .filter((r) => ids.has(r.source) || ids.has(r.target))
+            .map((r) => ({ source: r.source, target: r.target, ...(r.title === undefined ? {} : { title: r.title }) })),
+    };
+}
+/**
+ * instance id → the service its logical element belongs to.
+ *
+ * Through `serviceResolver` and NOT `elementService`, and the difference is a
+ * defect this axis shipped once. A deployment instances a CONTAINER far more
+ * often than a whole system — `instanceOf orders.cache` is the ordinary way to
+ * say where the Redis a service owns actually runs — and `elementService` reads
+ * the binding or the TITLE of the element handed to it. A nested container
+ * carries no `metadata { service }` of its own, so that read answered "order
+ * cache", and `obligation.uncovered` told an author to write the requirement in
+ * "order cache's arch.spec.md" — a service that has never existed. The
+ * resolver's whole job is the ancestor walk that finds the bound system above
+ * it, which is the same join every other check makes about a container.
+ *
+ * `known` rides in for the reason `coversEdge` takes it: without the enumerated
+ * fleet the resolver's second tier — the nearest ancestor whose title names a
+ * real `services/<id>/` — cannot run, and a fleet that binds by title rather
+ * than by `metadata { service }` resolves to the title alone. It must be the
+ * SAME set the caller's own findings resolve with, or the message names one
+ * service and the check counts another.
+ *
+ * An instance of an element the landscape does not declare is left UNOWNED
+ * rather than filed under a fabricated name. LikeC4 refuses an unresolved
+ * `instanceOf` outright, so that state is reachable only when the caller hands
+ * in elements from a narrower document than the one the topology was parsed
+ * with.
+ */
+function instanceOwners(deployment, elements, known) {
+    const ids = new Set(elements.map((e) => e.id));
+    const resolve = serviceResolver([...elements], known);
+    const out = new Map();
+    for (const instance of deployment.instances) {
+        if (ids.has(instance.element))
+            out.set(instance.id, resolve(instance.element));
+    }
+    return out;
+}
+//# sourceMappingURL=objects.js.map