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

package/dist/core/dependencies/facts.js

@@ -0,0 +1,165 @@
+/**
+ * What one feature ADDS and what it NEEDS, read out of its own delta.
+ *
+ * The whole graph is built from these five lists and nothing else, which is why
+ * they are computed once per feature and indexed rather than re-derived per
+ * edge: a feature is a node here only because some other feature's requirement
+ * or operation resolves into it, and answering that per pair would be a fleet
+ * walk per pair.
+ *
+ * `reqKeys` returns BOTH spellings of a requirement's identity — the stable
+ * `Requirement-ID` and the exact heading — because a legacy requirement has only
+ * the second, and an edge that existed under one spelling and not the other
+ * would make the graph depend on when the corpus was migrated.
+ */
+import { existsSync } from "node:fs";
+import { FleetContext } from "../fleet-context.js";
+import { serviceResolver } from "../c4/resolve/service.js";
+import { operations } from "../openapi/doc.js";
+import {} from "../repo/entries.js";
+import { SPEC_AXES, featurePaths, featureSpecPaths } from "../repo/paths.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { enumeratedServiceIds, enumeratedServiceIndex } from "../repo/service-target.js";
+export function reqKeys(requirement) {
+    return [
+        ...(requirement.id === undefined ? [] : [`id:${requirement.id}`]),
+        `name:${requirement.name}`,
+    ];
+}
+export function reqIndexKey(at) {
+    return `${at.service}\0${at.axis}\0${at.identity}`;
+}
+export function opIndexKey(at) {
+    return `${at.service}\0${at.operationId}`;
+}
+export function addOwner(index, key, at, feature) {
+    const owners = index.get(key) ?? { at, features: new Set() };
+    owners.features.add(feature);
+    index.set(key, owners);
+}
+export async function readFacts(docsDir, feature, context) {
+    const addedRequirements = [];
+    const changedRequirements = [];
+    const introducedOperations = [];
+    const requiredOperations = [];
+    /**
+     * The operationIds a service ALREADY has, per service.
+     *
+     * This is the whole difference between a dependency graph and a rumour mill.
+     * A feature's `openapi.yaml` is a COMPLETE document, not a patch — authors
+     * restate the living API around the slot they are changing — so every feature
+     * that so much as mentions `authorizePayment` used to be recorded as
+     * INTRODUCING it, and every other feature governing it as REQUIRING it. Two
+     * features quoting the same living operation therefore depended on each other
+     * in both directions: an invented cycle, an invented conflict, and an ordering
+     * for work that had none. `loam validate`'s coherence pass already subtracts
+     * the living contract this way (core/coherence/coherence.ts); this is the
+     * same subtraction, so the two cannot disagree about what "new" means.
+     *
+     * Cached per service inside the call and, through the FleetContext, across
+     * features: a fleet-wide graph asks about the same ten services N times.
+     */
+    const livingByService = new Map();
+    const living = async (service) => {
+        let ids = livingByService.get(service);
+        if (ids === undefined) {
+            ids = new Set((await operations((await locateServicePaths(docsDir, service, context)).openapi, context))
+                .filter((op) => !op.remove)
+                .map((op) => op.id));
+            livingByService.set(service, ids);
+        }
+        return ids;
+    };
+    for (const service of feature.services) {
+        const paths = featureSpecPaths(feature.dir, service);
+        const livingIds = await living(service);
+        for (const axis of SPEC_AXES) {
+            const path = paths[axis.key];
+            if (!existsSync(path))
+                continue;
+            const requirements = await context.readRequirements(path);
+            for (const requirement of requirements) {
+                const fact = { service, axis: axis.file, requirement };
+                if (requirement.kind === "ADDED")
+                    addedRequirements.push(fact);
+                if (requirement.kind === "MODIFIED" || requirement.kind === "REMOVED") {
+                    changedRequirements.push(fact);
+                }
+                for (const operationId of requirement.operations) {
+                    // Governing an operation the service already provides is not a
+                    // dependency on anybody: the contract it needs is already merged.
+                    if (livingIds.has(operationId))
+                        continue;
+                    requiredOperations.push({ service, operationId });
+                }
+            }
+        }
+        if (existsSync(paths.openapi)) {
+            const featureOperations = await operations(paths.openapi, context);
+            for (const operation of featureOperations) {
+                if (livingIds.has(operation.id))
+                    continue;
+                if (operation.remove)
+                    requiredOperations.push({ service, operationId: operation.id });
+                else
+                    introducedOperations.push({ service, operationId: operation.id });
+            }
+        }
+    }
+    // The C4 delta is the FOURTH place a feature names an operation, and it was
+    // the one the graph could not see: an edge carrying `metadata { op 'x' }` is
+    // a call this feature builds on `x`, which is exactly the "must land first"
+    // relation this module exists to compute. Validate already says so — it
+    // reports `c4-api.op-pending` when the op is defined by another feature in
+    // flight — so the graph disagreeing with the validator about the same pair of
+    // features was the graph being wrong, not quiet.
+    //
+    // Endpoints resolve through `serviceResolver` — the element's
+    // `metadata { service }` binding, title as fallback — the same join every
+    // other check uses, so renaming a box in a diagram cannot silently unhook it
+    // here either.
+    const deltaPath = featurePaths(feature.dir).delta;
+    if (existsSync(deltaPath)) {
+        const doc = await context.loadLikeC4(deltaPath);
+        // A delta that does not parse proves nothing about who depends on whom.
+        // `loam validate` owns that diagnosis (`delta.invalid`); inventing edges out
+        // of a half-read document would be worse than the silence.
+        if (doc.errors.length === 0) {
+            // One resolver for the whole delta: `serviceOf` rebuilds its id map on
+            // every call, and this loop asks once per edge. The enumerated fleet —
+            // `services/` plus this feature's own `specs/` directories, the same
+            // union `enumeratedTarget` probes below — rides into the resolver so a
+            // delta that models CONTAINERS keeps its edges attached: without it, an
+            // edge into `payment.api` resolves to a service called "api" that has
+            // never existed, the op lookup misses the living contract, and the graph
+            // invents a dependency (or orders two features that share nothing). An
+            // unenumerable services/ falls back to the feature's own names — every
+            // living probe would have found nothing there anyway.
+            const fleetIds = await enumeratedServiceIds(docsDir, context);
+            const svcOf = serviceResolver(doc.elements, new Set([...fleetIds, ...feature.services]));
+            // The resolver answers with document text and `living` builds a path, so
+            // the name crosses through the enumeration — coherence.ts grades its
+            // edges through the same bridge. A name no enumeration vouches for has
+            // no living contract anywhere: the op is required, exactly what the
+            // probe answered for an absent service.
+            const enumeratedTarget = enumeratedServiceIndex(docsDir, feature.services, context);
+            for (const rel of doc.relationships) {
+                if (rel.op === undefined)
+                    continue;
+                const service = svcOf(rel.target);
+                const pathable = await enumeratedTarget(service);
+                if (pathable !== undefined && (await living(pathable)).has(rel.op))
+                    continue;
+                requiredOperations.push({ service, operationId: rel.op });
+            }
+        }
+    }
+    return {
+        feature,
+        addedRequirements,
+        changedRequirements,
+        introducedOperations,
+        requiredOperations,
+    };
+}
+//# sourceMappingURL=facts.js.map

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
+ *     core/c4/direction/direction.ts: `consumes` binds the edge's TARGET as
+ *     the consumer, so the source is what it consumes from, and 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 *     core/c4/direction/direction.ts: `consumes` binds the edge's TARGET as\n *     the consumer, so the source is what it consumes from, and 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,191 @@
+/**
+ * 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 } from "node:path";
+import { architectureDir } from "../c4/project/architecture.js";
+import { stageMergedProject } from "../c4/project/staged.js";
+import {} from "../c4/likec4.js";
+import { relativeDocuments } 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) {
+    return relativeDocuments(featureDeploymentDir(featureDir));
+}
+/**
+ * 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, either
+ * of the two GENERATED views files (`subsystems.likec4` and `services.likec4`),
+ * or the flow tree. `reservedArchitectureName` carries which and why. It is
+ * asked FIRST and WITHOUT an existence test, because three of the four 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 three of
+    // the four names it refuses need not exist for the merge to be wrong. A
+    // topology copied over either GENERATED file — `subsystems.likec4` or
+    // `services.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" };
+    // AFTER the early return: the fleet read is paid only by a feature that
+    // actually brings a topology document.
+    const models = req.models === undefined ? undefined : await req.models();
+    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 }),
+        ...(models === undefined ? {} : { models }),
+    });
+    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