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

package/dist/core/repo/paths.js

@@ -0,0 +1,322 @@
+/**
+ * Where every artifact lives. Artifact filenames are spelled here and nowhere
+ * else, so a rename is one edit rather than a grep.
+ *
+ * This is also the module that carries loam's one path guarantee.
+ * `unfiledServicePaths(docsDir, service)` spells `<docsDir>/services/<service>/`,
+ * so both parts are caller-controlled path input, and `node:path` cannot help:
+ * `join(...paths: string[])` accepts every string there is. The guarantee IS
+ * the parameter brands and nothing else — `PathableService` for the id (a name
+ * whose provenance is the repository, unconstructible from document text),
+ * `DocsDir`/`FeatureDir` for the roots (a resolved config or validated
+ * `--docs`; a directory an enumeration read), and `ServiceDir` for
+ * `servicePathsAt` (the enumeration's own resolved directory, narrower still)
+ * — the `kernel/ids/` package holds the only casts, so an unchecked value at
+ * these call sites does not compile.
+ * Code that spells `services/<id>/` or a feature layout with a bare join is
+ * outside the guarantee — `commands/new.ts` and the openspec migrator both do,
+ * held instead by `resolveInside` at the write.
+ */
+import { join } from "node:path";
+import { serviceDirOf } from "../kernel/ids/dirs.js";
+/** Directory under features/ holding shipped features. Never a feature itself. */
+export const ARCHIVE_DIR = "archive";
+/* ------------------------------------------------------------------ */
+/* Paths — artifact filenames are spelled here and nowhere else        */
+/* ------------------------------------------------------------------ */
+/**
+ * The living artifact filenames, as one table, because three questions read
+ * them: `servicePathsAt` below spells the paths, the tree walk classifies
+ * a directory as a service by whether any of these names sit in it, and
+ * `core/diff/base-state.ts` classifies the SAME way over a base git ref's
+ * tree listing (exported for that reader — a filename respelled there would
+ * be the drift this table exists to prevent). The walk cannot import this
+ * module — `repo → repo/tree` is the package direction, and an edge back
+ * would be the cycle `scripts/package-graph.mjs` refuses — so `repo.ts`
+ * injects `isServiceArtifactName` into the walk request instead.
+ */
+export const ARTIFACT_FILES = {
+    model: "model.likec4",
+    spec: "spec.md",
+    archSpec: "arch.spec.md",
+    openapi: "openapi.yaml",
+    asyncapi: "asyncapi.yaml",
+    runbook: "runbook.md",
+    health: "health.yaml",
+    steps: "steps.yaml",
+};
+const ADRS_DIR = "adrs";
+/** Does a directory entry name a living service artifact? The classification half of the table above. */
+export function isServiceArtifactName(name, kind) {
+    if (kind === "dir")
+        return name === ADRS_DIR;
+    return Object.values(ARTIFACT_FILES).some((file) => file === name);
+}
+/**
+ * The artifact paths of a service whose directory is already KNOWN — the
+ * enumeration's `dir`, at whatever depth the tree walk found it. This is the
+ * spelling every reader of an existing service must use: joining
+ * `services/<id>/` at the root is only true for a fleet nobody has filed, and
+ * a moved service would silently grade as absent through it.
+ */
+export function servicePathsAt(dir) {
+    return {
+        dir,
+        model: join(dir, ARTIFACT_FILES.model),
+        spec: join(dir, ARTIFACT_FILES.spec),
+        archSpec: join(dir, ARTIFACT_FILES.archSpec),
+        openapi: join(dir, ARTIFACT_FILES.openapi),
+        asyncapi: join(dir, ARTIFACT_FILES.asyncapi),
+        runbook: join(dir, ARTIFACT_FILES.runbook),
+        health: join(dir, ARTIFACT_FILES.health),
+        steps: join(dir, ARTIFACT_FILES.steps),
+        adrsDir: join(dir, ADRS_DIR),
+    };
+}
+/**
+ * The UNFILED spelling — `<docsDir>/services/<id>/`, the tree's root level.
+ * This is where creation lands (`adopt`'s brief, a new service materialised by
+ * `archive`, the OpenSpec migration) and the honest fallback for a service the
+ * enumeration does not answer; for a service that EXISTS, resolve through the
+ * enumeration instead (`servicePathsAt(entry.dir)`, or
+ * `locateServicePaths` in `service-target.ts`, which chooses between the two).
+ * Renamed from `servicePaths` when the tree landed, precisely so the compiler
+ * would put every remaining caller in front of a reviewer: a root join that
+ * survives unreviewed is a moved service silently grading as absent.
+ */
+export function unfiledServicePaths(docsDir, service) {
+    return servicePathsAt(serviceDirOf(join(docsDir, "services", service)));
+}
+/**
+ * The creation spelling INSIDE a subsystem — `<subsystemDir>/<id>/`, the
+ * target `adopt --subsystem` briefs so an adoption need not land unfiled and
+ * cost a second command. The same two provenances the unfiled spelling
+ * combines, one level down: the subsystem directory came off the tree walk's
+ * readdir, and the id passed the service grammar before it reached here.
+ */
+export function servicePathsUnder(subsystemDir, service) {
+    return servicePathsAt(serviceDirOf(join(subsystemDir, service)));
+}
+/**
+ * The directory a SUBSYSTEM occupies (or will occupy) under a parent — the
+ * spelling `subsystem new` creates and `subsystem rename` renames into. The
+ * same guarantee-by-brand as the service spellings above: the parent came off
+ * the tree walk's readdir (or is `servicesDir` itself), and demanding
+ * `SubsystemName` here is what makes the validator unskippable — a raw argv
+ * string at this call site does not compile, so no future verb can hoist the
+ * join above the check that earns it.
+ */
+export function subsystemPathUnder(parentDir, name) {
+    return join(parentDir, name);
+}
+/**
+ * The pair of requirement-carrying spec files, living and delta alike: the
+ * business spec and the architecture spec. Same grammar, same delta algebra,
+ * same merge — everything that walks "the spec files" of a service walks this
+ * list, so the two axes cannot drift apart in what handles them. `key` indexes
+ * ServicePaths/FeatureSpecPaths; `label` is how the axis names itself in prose.
+ */
+export const SPEC_AXES = [
+    { key: "spec", file: "spec.md", label: "requirements" },
+    { key: "archSpec", file: "arch.spec.md", label: "arch requirements" },
+];
+export function featurePaths(featureDir) {
+    return {
+        dir: featureDir,
+        intent: join(featureDir, "intent.md"),
+        delta: join(featureDir, "delta.likec4"),
+        specsDir: join(featureDir, "specs"),
+        adrsDir: join(featureDir, "adrs"),
+    };
+}
+export function featureSpecPaths(featureDir, service) {
+    const dir = join(featureDir, "specs", service);
+    return {
+        dir,
+        spec: join(dir, "spec.md"),
+        archSpec: join(dir, "arch.spec.md"),
+        openapi: join(dir, "openapi.yaml"),
+        asyncapi: join(dir, "asyncapi.yaml"),
+    };
+}
+export function landscapePath(docsDir) {
+    return join(docsDir, "architecture", LANDSCAPE_FILE);
+}
+/** The fleet's authorization vocabulary — beside the fleet map, for the same reason. */
+export function permissionsPath(docsDir) {
+    return join(docsDir, "architecture", "permissions.yaml");
+}
+/** The fleet's capability vocabulary — beside the other two fleet documents, for the same reason. */
+export function capabilitiesPath(docsDir) {
+    return join(docsDir, "architecture", "capabilities.yaml");
+}
+/**
+ * The fleet's ARCHITECTURAL OBLIGATION vocabulary — beside the landscape it tags
+ * and the two vocabularies it sits with, for their reason: it is a fact about
+ * the fleet that no single service owns.
+ */
+export function obligationsPath(docsDir) {
+    return join(docsDir, "architecture", "obligations.yaml");
+}
+/**
+ * The FLEET's decision records — `architecture/adrs/`, beside the landscape and
+ * the two vocabularies.
+ *
+ * ADRs used to exist at two altitudes only, `services/<id>/adrs/` and
+ * `features/<FEAT>/adrs/`, so a decision about the fleet itself — "event
+ * publishers use a transactional outbox", "cross-service calls carry a circuit
+ * breaker" — had no home but one arbitrary service's directory, where the next
+ * reader of the other fifty services never finds it. This is not a new axis: it
+ * is the same `ADRS_DIR` name one level up, spelled through the same constant so
+ * the two altitudes cannot drift into `adrs/` and `decisions/`.
+ *
+ * PRESENCE-TRACKED AND NOTHING MORE, exactly like the service directory it
+ * mirrors: `loam list` counts the files (`repo.ts`'s `fleetAdrCount`) and no
+ * check anywhere reads one. A fleet with no fleet-level ADRs owes nothing and
+ * must produce no finding — which is also why `loam init` does NOT scaffold the
+ * directory. git does not carry an empty one, so it would vanish on the first
+ * clone and come back as a diff on the next `init`; and an empty `adrs/` in a
+ * fresh repo reads as an obligation nobody has met, when there is no obligation
+ * at all.
+ */
+export function fleetAdrsDir(docsDir) {
+    return join(docsDir, "architecture", ADRS_DIR);
+}
+const SUBSYSTEM_VIEWS_FILE = "subsystems.likec4";
+const SERVICE_VIEWS_FILE = "services.likec4";
+/**
+ * The documents inside `architecture/` that LOAM GENERATES — ONE list, because
+ * four questions read it and a name in one reader and missing from another fails
+ * silently both ways: the path functions below, the reservation below, the project
+ * loads that must EXCLUDE these files (`core/c4/project/architecture.ts` and
+ * `commands/validate/fleet/views/projects.ts` — a views-only document does not
+ * parse standalone, so loading one blanks the project it lands in), and `loam
+ * archive`'s withhold-and-name — each of which hard-coded "the generated one"
+ * while there was only one. The VALUE is what the reservation below prints.
+ */
+export const GENERATED_ARCHITECTURE_FILES = {
+    [SUBSYSTEM_VIEWS_FILE]: "`subsystems.likec4` is generated by `loam subsystem sync`, which overwrites it wholesale — and nothing in loam ever parses it, so anything landing there is invisible from the moment it archives",
+    [SERVICE_VIEWS_FILE]: "`services.likec4` is generated by `loam subsystem sync`, one overview view per service, and is overwritten wholesale — and nothing in loam ever parses it, so anything landing there is invisible from the moment it archives",
+};
+/**
+ * The two GENERATED views files — beside the fleet map because the LikeC4
+ * renderer merges the whole `architecture/` project, and a view can only
+ * `include` elements the landscape beside it defines. `loam subsystem sync` owns
+ * both files' bytes (`render/views.ts`, `render/service/views.ts`); loam parses
+ * neither, and staleness against the tree is a content compare.
+ */
+export function subsystemViewsPath(docsDir) {
+    return join(docsDir, "architecture", SUBSYSTEM_VIEWS_FILE);
+}
+export function serviceViewsPath(docsDir) {
+    return join(docsDir, "architecture", SERVICE_VIEWS_FILE);
+}
+/**
+ * Names inside `architecture/` that LOAM owns, and what goes wrong if a
+ * feature's own document claims one. `features/<FEAT>/deployment/<name>.likec4`
+ * merges as a whole-file COPY straight into `architecture/` — unlike a flow,
+ * which lands under `usecases/` — so its `<name>` is free to be any of them. A
+ * generated name fails silently both ways (the table above says how); a copy over
+ * `landscape.likec4` would discard the living map the archive SPLICES; and
+ * `usecases/` is the flow tree the scan walks, where a deployment document parses
+ * and is then looked for by a reader asking another question. Returns the reason,
+ * or null when the name is the author's — over the rel a walk produced, never argv.
+ */
+export function reservedArchitectureName(rel) {
+    const parts = rel.split("/");
+    if (parts[0] === USECASE_DIR) {
+        return `\`${USECASE_DIR}/\` is the use-case tree — a flow belongs in \`features/<FEAT>/usecases/\`, which merges there`;
+    }
+    // Own key only: a bare lookup answers `constructor` with something inherited.
+    if (Object.hasOwn(GENERATED_ARCHITECTURE_FILES, rel))
+        return GENERATED_ARCHITECTURE_FILES[rel];
+    if (rel === LANDSCAPE_FILE) {
+        return "`landscape.likec4` is the living fleet map, which the archive SPLICES into rather than replaces";
+    }
+    return null;
+}
+/** The living map's file name, and the flow tree's directory — spelled once, read by the reservation. */
+const LANDSCAPE_FILE = "landscape.likec4";
+const USECASE_DIR = "usecases";
+export function featuresDir(docsDir) {
+    return join(docsDir, "features");
+}
+/**
+ * The root of the tree that IS the fleet — where an unfiled service and a
+ * root-level subsystem both sit. The `subsystem` verbs join validated names
+ * under it; the enumerating walk spells the same join for itself
+ * (`repo/tree/walk.ts`), because it cannot import this module.
+ */
+export function servicesDir(docsDir) {
+    return join(docsDir, "services");
+}
+/**
+ * The agent contract's filename, and where it sits in a docs repo.
+ *
+ * Both spellings are exported because the two questions are different: `init`,
+ * `doctor` and `validate` want a path under a docsDir they already hold, while
+ * `docs.ts` builds the scaffold as `[relative path, bytes]` pairs and needs the
+ * bare name. Four modules spelled the literal out for themselves, and one of
+ * them — `init` — uses it to decide whether a directory IS a docs repo at all,
+ * so a rename that reached three of the four would leave `init` recognising a
+ * file nothing else writes any more.
+ *
+ * `openspec-inventory.ts`'s "AGENTS.md" is deliberately NOT this constant: it
+ * names a file in a foreign OpenSpec tree that happens to share the name.
+ */
+export const AGENTS_FILENAME = "AGENTS.md";
+export function agentsPath(docsDir) {
+    return join(docsDir, AGENTS_FILENAME);
+}
+/**
+ * Where shipped features live. `features/archive/` is spelled here and nowhere
+ * else for the same reason every other artifact path is: `archive` and
+ * `unarchive` move directories in and out of it, and a layout string that two
+ * commands re-derive is a layout two commands can disagree about. The
+ * `features/archive/…` strings in refusal PROSE are not this path — they are
+ * what a reader types into `ls`, and they stay spelled out.
+ */
+export function archiveDir(docsDir) {
+    return join(featuresDir(docsDir), ARCHIVE_DIR);
+}
+/**
+ * The LikeC4 project file — the one thing in a docs repo loam writes for a
+ * tool other than itself — and it lives at two altitudes.
+ *
+ * At the ROOT, `loam init --create` writes the project `fleet` (`core/docs.ts`
+ * composes those bytes), which holds the fleet map and every service model that
+ * EXTENDS it. Beside a model that STANDS ALONE — one declaring its own
+ * `specification` block, which can only be parsed on its own — `loam subsystem
+ * sync` writes a project of the service's own, and adds that directory to the
+ * root's `exclude`; without both, such a model is either a duplicate of the map
+ * or a box on it with nothing renderable inside.
+ * `core/repo/tree/render/projects.ts` composes the per-service bytes and records
+ * what was measured; `core/c4/root-project/exclude.ts` owns reading the root's
+ * `exclude` list and deciding what an entry covers; `core/c4/service-model/renderer.ts`
+ * owns the list `loam subsystem sync` writes back.
+ *
+ * Spelled here and NOT in `ARTIFACT_FILES`, and the distinction is
+ * load-bearing: a filename in that table classifies a directory as a service,
+ * and this file is the renderer's — a stray one must mint nothing. The root's
+ * NAME sits beside the filename because the per-service rule needs it too (a
+ * service id equal to the root project's name would be silently renamed by
+ * the renderer), and two spellings of the word are how the scaffold and the
+ * rule drift apart.
+ */
+export const LIKEC4_PROJECT_FILENAME = "likec4.config.json";
+/** The root project's name, exactly as `loam init --create` scaffolds it. */
+export const LIKEC4_ROOT_PROJECT = "fleet";
+export function rootProjectPath(docsDir) {
+    return join(docsDir, LIKEC4_PROJECT_FILENAME);
+}
+/**
+ * The two files the per-service project question is asked of — the model that
+ * needs rendering and the project file that renders it — in one spelling for
+ * the writer (`subsystem sync`) and the grader (`validate --all`) alike. Handed
+ * INTO `render/projects.ts` rather than imported there, because that package
+ * cannot import this module: `render/stale.ts` records the cycle.
+ */
+export function serviceRenderPaths(dir) {
+    return { model: join(dir, ARTIFACT_FILES.model), project: join(dir, LIKEC4_PROJECT_FILENAME) };
+}
+//# sourceMappingURL=paths.js.map

package/dist/core/repo/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/core/repo/paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Where every artifact lives. Artifact filenames are spelled here and nowhere\n * else, so a rename is one edit rather than a grep.\n *\n * This is also the module that carries loam's one path guarantee.\n * `unfiledServicePaths(docsDir, service)` spells `<docsDir>/services/<service>/`,\n * so both parts are caller-controlled path input, and `node:path` cannot help:\n * `join(...paths: string[])` accepts every string there is. The guarantee IS\n * the parameter brands and nothing else — `PathableService` for the id (a name\n * whose provenance is the repository, unconstructible from document text),\n * `DocsDir`/`FeatureDir` for the roots (a resolved config or validated\n * `--docs`; a directory an enumeration read), and `ServiceDir` for\n * `servicePathsAt` (the enumeration's own resolved directory, narrower still)\n * — the `kernel/ids/` package holds the only casts, so an unchecked value at\n * these call sites does not compile.\n * Code that spells `services/<id>/` or a feature layout with a bare join is\n * outside the guarantee — `commands/new.ts` and the openspec migrator both do,\n * held instead by `resolveInside` at the write.\n */\nimport { join } from \"node:path\";\nimport { serviceDirOf, type DocsDir, type FeatureDir, type ServiceDir } from \"../kernel/ids/dirs.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport type { SubsystemName } from \"../kernel/ids/subsystem.js\";\n\n/** Directory under features/ holding shipped features. Never a feature itself. */\nexport const ARCHIVE_DIR = \"archive\";\n\n/* ------------------------------------------------------------------ */\n/* Paths — artifact filenames are spelled here and nowhere else        */\n/* ------------------------------------------------------------------ */\n\n/**\n * The living artifact filenames, as one table, because three questions read\n * them: `servicePathsAt` below spells the paths, the tree walk classifies\n * a directory as a service by whether any of these names sit in it, and\n * `core/diff/base-state.ts` classifies the SAME way over a base git ref's\n * tree listing (exported for that reader — a filename respelled there would\n * be the drift this table exists to prevent). The walk cannot import this\n * module — `repo → repo/tree` is the package direction, and an edge back\n * would be the cycle `scripts/package-graph.mjs` refuses — so `repo.ts`\n * injects `isServiceArtifactName` into the walk request instead.\n */\nexport const ARTIFACT_FILES = {\n  model: \"model.likec4\",\n  spec: \"spec.md\",\n  archSpec: \"arch.spec.md\",\n  openapi: \"openapi.yaml\",\n  asyncapi: \"asyncapi.yaml\",\n  runbook: \"runbook.md\",\n  health: \"health.yaml\",\n  steps: \"steps.yaml\",\n} as const;\nconst ADRS_DIR = \"adrs\";\n\n/** Does a directory entry name a living service artifact? The classification half of the table above. */\nexport function isServiceArtifactName(name: string, kind: \"file\" | \"dir\"): boolean {\n  if (kind === \"dir\") return name === ADRS_DIR;\n  return Object.values(ARTIFACT_FILES).some((file) => file === name);\n}\n\nexport interface ServicePaths {\n  dir: ServiceDir;\n  model: string;\n  spec: string;\n  archSpec: string;\n  openapi: string;\n  /** The async contract — the event axis's sibling of `openapi`. */\n  asyncapi: string;\n  runbook: string;\n  health: string;\n  /**\n   * The step catalogue — which phrases this service's suite has DECIDED to\n   * define. Authored and opt-in; its CONTENTS are read by `loam steps` alone and\n   * nothing in `validate` consults them\n   * (`core/gherkin/steps/catalogue.ts` records why).\n   *\n   * Its EXISTENCE is read more widely, and that is not the same statement: the\n   * filename is in `ARTIFACT_FILES`, so `isServiceArtifactName` classifies it\n   * and the tree walk treats a directory holding one as a service. That is\n   * correct — it is a service artifact — and it is worth writing down, because\n   * it means a `steps.yaml` written at the wrong path mints a service.\n   */\n  steps: string;\n  adrsDir: string;\n}\n\n/**\n * The artifact paths of a service whose directory is already KNOWN — the\n * enumeration's `dir`, at whatever depth the tree walk found it. This is the\n * spelling every reader of an existing service must use: joining\n * `services/<id>/` at the root is only true for a fleet nobody has filed, and\n * a moved service would silently grade as absent through it.\n */\nexport function servicePathsAt(dir: ServiceDir): ServicePaths {\n  return {\n    dir,\n    model: join(dir, ARTIFACT_FILES.model),\n    spec: join(dir, ARTIFACT_FILES.spec),\n    archSpec: join(dir, ARTIFACT_FILES.archSpec),\n    openapi: join(dir, ARTIFACT_FILES.openapi),\n    asyncapi: join(dir, ARTIFACT_FILES.asyncapi),\n    runbook: join(dir, ARTIFACT_FILES.runbook),\n    health: join(dir, ARTIFACT_FILES.health),\n    steps: join(dir, ARTIFACT_FILES.steps),\n    adrsDir: join(dir, ADRS_DIR),\n  };\n}\n\n/**\n * The UNFILED spelling — `<docsDir>/services/<id>/`, the tree's root level.\n * This is where creation lands (`adopt`'s brief, a new service materialised by\n * `archive`, the OpenSpec migration) and the honest fallback for a service the\n * enumeration does not answer; for a service that EXISTS, resolve through the\n * enumeration instead (`servicePathsAt(entry.dir)`, or\n * `locateServicePaths` in `service-target.ts`, which chooses between the two).\n * Renamed from `servicePaths` when the tree landed, precisely so the compiler\n * would put every remaining caller in front of a reviewer: a root join that\n * survives unreviewed is a moved service silently grading as absent.\n */\nexport function unfiledServicePaths(docsDir: DocsDir, service: PathableService): ServicePaths {\n  return servicePathsAt(serviceDirOf(join(docsDir, \"services\", service)));\n}\n\n/**\n * The creation spelling INSIDE a subsystem — `<subsystemDir>/<id>/`, the\n * target `adopt --subsystem` briefs so an adoption need not land unfiled and\n * cost a second command. The same two provenances the unfiled spelling\n * combines, one level down: the subsystem directory came off the tree walk's\n * readdir, and the id passed the service grammar before it reached here.\n */\nexport function servicePathsUnder(subsystemDir: string, service: PathableService): ServicePaths {\n  return servicePathsAt(serviceDirOf(join(subsystemDir, service)));\n}\n\n/**\n * The directory a SUBSYSTEM occupies (or will occupy) under a parent — the\n * spelling `subsystem new` creates and `subsystem rename` renames into. The\n * same guarantee-by-brand as the service spellings above: the parent came off\n * the tree walk's readdir (or is `servicesDir` itself), and demanding\n * `SubsystemName` here is what makes the validator unskippable — a raw argv\n * string at this call site does not compile, so no future verb can hoist the\n * join above the check that earns it.\n */\nexport function subsystemPathUnder(parentDir: string, name: SubsystemName): string {\n  return join(parentDir, name);\n}\n\n/**\n * The pair of requirement-carrying spec files, living and delta alike: the\n * business spec and the architecture spec. Same grammar, same delta algebra,\n * same merge — everything that walks \"the spec files\" of a service walks this\n * list, so the two axes cannot drift apart in what handles them. `key` indexes\n * ServicePaths/FeatureSpecPaths; `label` is how the axis names itself in prose.\n */\nexport const SPEC_AXES = [\n  { key: \"spec\", file: \"spec.md\", label: \"requirements\" },\n  { key: \"archSpec\", file: \"arch.spec.md\", label: \"arch requirements\" },\n] as const;\nexport type SpecAxis = (typeof SPEC_AXES)[number];\n\nexport interface FeaturePaths {\n  dir: string;\n  intent: string;\n  delta: string;\n  specsDir: string;\n  adrsDir: string;\n}\n\nexport function featurePaths(featureDir: FeatureDir): FeaturePaths {\n  return {\n    dir: featureDir,\n    intent: join(featureDir, \"intent.md\"),\n    delta: join(featureDir, \"delta.likec4\"),\n    specsDir: join(featureDir, \"specs\"),\n    adrsDir: join(featureDir, \"adrs\"),\n  };\n}\n\nexport interface FeatureSpecPaths {\n  dir: string;\n  spec: string;\n  archSpec: string;\n  openapi: string;\n  /** The async contract delta — the event axis's sibling of `openapi`. */\n  asyncapi: string;\n}\n\nexport function featureSpecPaths(featureDir: FeatureDir, service: PathableService): FeatureSpecPaths {\n  const dir = join(featureDir, \"specs\", service);\n  return {\n    dir,\n    spec: join(dir, \"spec.md\"),\n    archSpec: join(dir, \"arch.spec.md\"),\n    openapi: join(dir, \"openapi.yaml\"),\n    asyncapi: join(dir, \"asyncapi.yaml\"),\n  };\n}\n\nexport function landscapePath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", LANDSCAPE_FILE);\n}\n\n/** The fleet's authorization vocabulary — beside the fleet map, for the same reason. */\nexport function permissionsPath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", \"permissions.yaml\");\n}\n\n/** The fleet's capability vocabulary — beside the other two fleet documents, for the same reason. */\nexport function capabilitiesPath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", \"capabilities.yaml\");\n}\n\n/**\n * The fleet's ARCHITECTURAL OBLIGATION vocabulary — beside the landscape it tags\n * and the two vocabularies it sits with, for their reason: it is a fact about\n * the fleet that no single service owns.\n */\nexport function obligationsPath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", \"obligations.yaml\");\n}\n\n/**\n * The FLEET's decision records — `architecture/adrs/`, beside the landscape and\n * the two vocabularies.\n *\n * ADRs used to exist at two altitudes only, `services/<id>/adrs/` and\n * `features/<FEAT>/adrs/`, so a decision about the fleet itself — \"event\n * publishers use a transactional outbox\", \"cross-service calls carry a circuit\n * breaker\" — had no home but one arbitrary service's directory, where the next\n * reader of the other fifty services never finds it. This is not a new axis: it\n * is the same `ADRS_DIR` name one level up, spelled through the same constant so\n * the two altitudes cannot drift into `adrs/` and `decisions/`.\n *\n * PRESENCE-TRACKED AND NOTHING MORE, exactly like the service directory it\n * mirrors: `loam list` counts the files (`repo.ts`'s `fleetAdrCount`) and no\n * check anywhere reads one. A fleet with no fleet-level ADRs owes nothing and\n * must produce no finding — which is also why `loam init` does NOT scaffold the\n * directory. git does not carry an empty one, so it would vanish on the first\n * clone and come back as a diff on the next `init`; and an empty `adrs/` in a\n * fresh repo reads as an obligation nobody has met, when there is no obligation\n * at all.\n */\nexport function fleetAdrsDir(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", ADRS_DIR);\n}\n\nconst SUBSYSTEM_VIEWS_FILE = \"subsystems.likec4\";\nconst SERVICE_VIEWS_FILE = \"services.likec4\";\n\n/**\n * The documents inside `architecture/` that LOAM GENERATES — ONE list, because\n * four questions read it and a name in one reader and missing from another fails\n * silently both ways: the path functions below, the reservation below, the project\n * loads that must EXCLUDE these files (`core/c4/project/architecture.ts` and\n * `commands/validate/fleet/views/projects.ts` — a views-only document does not\n * parse standalone, so loading one blanks the project it lands in), and `loam\n * archive`'s withhold-and-name — each of which hard-coded \"the generated one\"\n * while there was only one. The VALUE is what the reservation below prints.\n */\nexport const GENERATED_ARCHITECTURE_FILES: Readonly<Record<string, string>> = {\n  [SUBSYSTEM_VIEWS_FILE]:\n    \"`subsystems.likec4` is generated by `loam subsystem sync`, which overwrites it wholesale — and nothing in loam ever parses it, so anything landing there is invisible from the moment it archives\",\n  [SERVICE_VIEWS_FILE]:\n    \"`services.likec4` is generated by `loam subsystem sync`, one overview view per service, and is overwritten wholesale — and nothing in loam ever parses it, so anything landing there is invisible from the moment it archives\",\n};\n\n/**\n * The two GENERATED views files — beside the fleet map because the LikeC4\n * renderer merges the whole `architecture/` project, and a view can only\n * `include` elements the landscape beside it defines. `loam subsystem sync` owns\n * both files' bytes (`render/views.ts`, `render/service/views.ts`); loam parses\n * neither, and staleness against the tree is a content compare.\n */\nexport function subsystemViewsPath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", SUBSYSTEM_VIEWS_FILE);\n}\n\nexport function serviceViewsPath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", SERVICE_VIEWS_FILE);\n}\n\n/**\n * Names inside `architecture/` that LOAM owns, and what goes wrong if a\n * feature's own document claims one. `features/<FEAT>/deployment/<name>.likec4`\n * merges as a whole-file COPY straight into `architecture/` — unlike a flow,\n * which lands under `usecases/` — so its `<name>` is free to be any of them. A\n * generated name fails silently both ways (the table above says how); a copy over\n * `landscape.likec4` would discard the living map the archive SPLICES; and\n * `usecases/` is the flow tree the scan walks, where a deployment document parses\n * and is then looked for by a reader asking another question. Returns the reason,\n * or null when the name is the author's — over the rel a walk produced, never argv.\n */\nexport function reservedArchitectureName(rel: string): string | null {\n  const parts = rel.split(\"/\");\n  if (parts[0] === USECASE_DIR) {\n    return `\\`${USECASE_DIR}/\\` is the use-case tree — a flow belongs in \\`features/<FEAT>/usecases/\\`, which merges there`;\n  }\n  // Own key only: a bare lookup answers `constructor` with something inherited.\n  if (Object.hasOwn(GENERATED_ARCHITECTURE_FILES, rel)) return GENERATED_ARCHITECTURE_FILES[rel]!;\n  if (rel === LANDSCAPE_FILE) {\n    return \"`landscape.likec4` is the living fleet map, which the archive SPLICES into rather than replaces\";\n  }\n  return null;\n}\n\n/** The living map's file name, and the flow tree's directory — spelled once, read by the reservation. */\nconst LANDSCAPE_FILE = \"landscape.likec4\";\nconst USECASE_DIR = \"usecases\";\n\nexport function featuresDir(docsDir: DocsDir): string {\n  return join(docsDir, \"features\");\n}\n\n/**\n * The root of the tree that IS the fleet — where an unfiled service and a\n * root-level subsystem both sit. The `subsystem` verbs join validated names\n * under it; the enumerating walk spells the same join for itself\n * (`repo/tree/walk.ts`), because it cannot import this module.\n */\nexport function servicesDir(docsDir: DocsDir): string {\n  return join(docsDir, \"services\");\n}\n\n/**\n * The agent contract's filename, and where it sits in a docs repo.\n *\n * Both spellings are exported because the two questions are different: `init`,\n * `doctor` and `validate` want a path under a docsDir they already hold, while\n * `docs.ts` builds the scaffold as `[relative path, bytes]` pairs and needs the\n * bare name. Four modules spelled the literal out for themselves, and one of\n * them — `init` — uses it to decide whether a directory IS a docs repo at all,\n * so a rename that reached three of the four would leave `init` recognising a\n * file nothing else writes any more.\n *\n * `openspec-inventory.ts`'s \"AGENTS.md\" is deliberately NOT this constant: it\n * names a file in a foreign OpenSpec tree that happens to share the name.\n */\nexport const AGENTS_FILENAME = \"AGENTS.md\";\n\nexport function agentsPath(docsDir: DocsDir): string {\n  return join(docsDir, AGENTS_FILENAME);\n}\n\n/**\n * Where shipped features live. `features/archive/` is spelled here and nowhere\n * else for the same reason every other artifact path is: `archive` and\n * `unarchive` move directories in and out of it, and a layout string that two\n * commands re-derive is a layout two commands can disagree about. The\n * `features/archive/…` strings in refusal PROSE are not this path — they are\n * what a reader types into `ls`, and they stay spelled out.\n */\nexport function archiveDir(docsDir: DocsDir): string {\n  return join(featuresDir(docsDir), ARCHIVE_DIR);\n}\n\n/**\n * The LikeC4 project file — the one thing in a docs repo loam writes for a\n * tool other than itself — and it lives at two altitudes.\n *\n * At the ROOT, `loam init --create` writes the project `fleet` (`core/docs.ts`\n * composes those bytes), which holds the fleet map and every service model that\n * EXTENDS it. Beside a model that STANDS ALONE — one declaring its own\n * `specification` block, which can only be parsed on its own — `loam subsystem\n * sync` writes a project of the service's own, and adds that directory to the\n * root's `exclude`; without both, such a model is either a duplicate of the map\n * or a box on it with nothing renderable inside.\n * `core/repo/tree/render/projects.ts` composes the per-service bytes and records\n * what was measured; `core/c4/root-project/exclude.ts` owns reading the root's\n * `exclude` list and deciding what an entry covers; `core/c4/service-model/renderer.ts`\n * owns the list `loam subsystem sync` writes back.\n *\n * Spelled here and NOT in `ARTIFACT_FILES`, and the distinction is\n * load-bearing: a filename in that table classifies a directory as a service,\n * and this file is the renderer's — a stray one must mint nothing. The root's\n * NAME sits beside the filename because the per-service rule needs it too (a\n * service id equal to the root project's name would be silently renamed by\n * the renderer), and two spellings of the word are how the scaffold and the\n * rule drift apart.\n */\nexport const LIKEC4_PROJECT_FILENAME = \"likec4.config.json\";\n\n/** The root project's name, exactly as `loam init --create` scaffolds it. */\nexport const LIKEC4_ROOT_PROJECT = \"fleet\";\n\nexport function rootProjectPath(docsDir: DocsDir): string {\n  return join(docsDir, LIKEC4_PROJECT_FILENAME);\n}\n\n/**\n * The two files the per-service project question is asked of — the model that\n * needs rendering and the project file that renders it — in one spelling for\n * the writer (`subsystem sync`) and the grader (`validate --all`) alike. Handed\n * INTO `render/projects.ts` rather than imported there, because that package\n * cannot import this module: `render/stale.ts` records the cycle.\n */\nexport function serviceRenderPaths(dir: ServiceDir): { model: string; project: string } {\n  return { model: join(dir, ARTIFACT_FILES.model), project: join(dir, LIKEC4_PROJECT_FILENAME) };\n}\n"]}