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

package/dist/core/kernel/ids/feature.js

@@ -0,0 +1,75 @@
+/**
+ * The spelling rule for feature ids, and the brands that carry its provenance.
+ *
+ * Split out of `service.ts` when the feature grammar grew the same brand
+ * lattice the service grammar has: the two rules share a package because both
+ * become directory names in the shared docs repo, but a feature id is not a
+ * service id — the brands below are deliberately disjoint from `RawServiceId`
+ * and `ServiceId`, so one grammar's checked value cannot stand in where the
+ * other's is demanded.
+ */
+/**
+ * Feature ids are `<word>-<number>`: the id has to survive being read back off
+ * the directory name (`FEAT-101-payment-splitting` -> `FEAT-101`), or the
+ * feature would answer to a name it was never given.
+ *
+ * Here for the same reason the service grammar is — this was spelled twice,
+ * privately, in `commands/new.ts` and `core/openspec/`, and
+ * docs/DESIGN.md rule 7 recorded the pair as a hazard rather than a fact. The
+ * third caller is what made it one: `loam explore --as <FEAT>` interpolates its
+ * argument into a `loam new` line that loam PRINTS for an agent to run, so
+ * without this check `explore` cheerfully handed back a command `new` refuses.
+ * A guard test catches that class only for literal source strings — a command
+ * assembled at runtime from argv is invisible to it — which is exactly why the
+ * grammar has to be shared rather than re-derived by whoever needs it next.
+ */
+const FEATURE_ID = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+/** Prose form, shown verbatim in every refusal so the fix is obvious. */
+export const FEATURE_ID_RULE = "Expected <word>-<number>, e.g. FEAT-101 or BUG-42.";
+export function isFeatureId(id) {
+    return typeof id === "string" && FEATURE_ID.test(id);
+}
+/**
+ * Why `id` is not a usable feature id, or null when it is — the `serviceIdProblem`
+ * shape, so a caller already collecting findings reports the sentence a refusal
+ * would print.
+ */
+export function featureIdProblem(id, label = "feature id") {
+    if (!isFeatureId(id)) {
+        const shown = typeof id === "string" ? `'${id}'` : String(id);
+        return `${shown} is not a usable ${label}. ${FEATURE_ID_RULE}`;
+    }
+    return null;
+}
+/* ---------------------------------------------------------------- */
+/* The two constructors — the only place a brand is asserted         */
+/* ---------------------------------------------------------------- */
+/**
+ * The one constructor that validates — `parseServiceId`'s shape, for the same
+ * reason: a discriminated pair rather than `FeatureId | string`, because that
+ * second shape compiles and is unusable, and the problem sentence is the one
+ * `featureIdProblem` already produces, so a caller that is collecting findings
+ * prints exactly what a refusal would.
+ */
+export function parseFeatureId(raw, label = "feature id") {
+    const problem = featureIdProblem(raw, label);
+    if (problem !== null)
+        return { ok: false, problem };
+    // The cast, on the line immediately after the check that earns it.
+    return { ok: true, id: raw };
+}
+/**
+ * An id derived from a directory name a repository listed. Says nothing about
+ * whether it is a legal id — that is the point: the enumeration must be able to
+ * name the directory that is there, however it is spelled.
+ *
+ * This is a cast, and it has to be: the derivation in
+ * `core/repo/entries.ts`'s `featureIdFromDirName` starts from a plain `readdir`
+ * string, and a brand does not survive it. What the rule in
+ * `docs/CODE-STYLE.md` buys is that both of this file's casts live HERE and
+ * nowhere else — a third one somewhere in `src/` is a finding, not a shortcut.
+ */
+export function rawFeatureId(derived) {
+    return derived;
+}
+//# sourceMappingURL=feature.js.map

package/dist/core/kernel/ids/feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature.js","sourceRoot":"","sources":["../../../../src/core/kernel/ids/feature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA2BH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,GAAG,4BAA4B,CAAC;AAEhD,yEAAyE;AACzE,MAAM,CAAC,MAAM,eAAe,GAAG,oDAAoD,CAAC;AAEpF,MAAM,UAAU,WAAW,CAAC,EAAW;IACrC,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAW,EAAE,KAAK,GAAG,YAAY;IAChE,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC9D,OAAO,GAAG,KAAK,oBAAoB,KAAK,KAAK,eAAe,EAAE,CAAC;IACjE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,sEAAsE;AACtE,uEAAuE;AACvE,sEAAsE;AAEtE;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,KAAK,GAAG,YAAY;IAEpB,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACpD,mEAAmE;IACnE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,GAAgB,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAuB,CAAC;AACjC,CAAC","sourcesContent":["/**\n * The spelling rule for feature ids, and the brands that carry its provenance.\n *\n * Split out of `service.ts` when the feature grammar grew the same brand\n * lattice the service grammar has: the two rules share a package because both\n * become directory names in the shared docs repo, but a feature id is not a\n * service id — the brands below are deliberately disjoint from `RawServiceId`\n * and `ServiceId`, so one grammar's checked value cannot stand in where the\n * other's is demanded.\n */\n\n/* ---------------------------------------------------------------- */\n/* The two provenances a feature name can have                       */\n/* ---------------------------------------------------------------- */\n\n/**\n * Same hierarchy as the service brands, for the same measured reason: the raw\n * form is the base — a name whose provenance is the repository — and the\n * checked form is a SUBTYPE, so `id === arg`, `Set<RawFeatureId>.has(id)` and\n * sorting a mixed list all stay the ordinary string business they are.\n */\ndeclare const provenance: unique symbol;\ndeclare const checked: unique symbol;\n\n/**\n * A feature id a repository listed this directory for: read back off a\n * `features/` directory name by the enumeration. It exists; it may still be an\n * illegal loam id — `core/repo/repo.ts`'s `listFeatures` deliberately returns\n * those, because `loam list` must show you the badly-named directory that is\n * there.\n */\nexport type RawFeatureId = string & { readonly [provenance]: \"loam\" };\n\n/** An id that passed `featureIdProblem`. The only form a caller may construct. */\nexport type FeatureId = RawFeatureId & { readonly [checked]: true };\n\n/**\n * Feature ids are `<word>-<number>`: the id has to survive being read back off\n * the directory name (`FEAT-101-payment-splitting` -> `FEAT-101`), or the\n * feature would answer to a name it was never given.\n *\n * Here for the same reason the service grammar is — this was spelled twice,\n * privately, in `commands/new.ts` and `core/openspec/`, and\n * docs/DESIGN.md rule 7 recorded the pair as a hazard rather than a fact. The\n * third caller is what made it one: `loam explore --as <FEAT>` interpolates its\n * argument into a `loam new` line that loam PRINTS for an agent to run, so\n * without this check `explore` cheerfully handed back a command `new` refuses.\n * A guard test catches that class only for literal source strings — a command\n * assembled at runtime from argv is invisible to it — which is exactly why the\n * grammar has to be shared rather than re-derived by whoever needs it next.\n */\nconst FEATURE_ID = /^[A-Za-z][A-Za-z0-9]*-\\d+$/;\n\n/** Prose form, shown verbatim in every refusal so the fix is obvious. */\nexport const FEATURE_ID_RULE = \"Expected <word>-<number>, e.g. FEAT-101 or BUG-42.\";\n\nexport function isFeatureId(id: unknown): id is string {\n  return typeof id === \"string\" && FEATURE_ID.test(id);\n}\n\n/**\n * Why `id` is not a usable feature id, or null when it is — the `serviceIdProblem`\n * shape, so a caller already collecting findings reports the sentence a refusal\n * would print.\n */\nexport function featureIdProblem(id: unknown, label = \"feature id\"): string | null {\n  if (!isFeatureId(id)) {\n    const shown = typeof id === \"string\" ? `'${id}'` : String(id);\n    return `${shown} is not a usable ${label}. ${FEATURE_ID_RULE}`;\n  }\n  return null;\n}\n\n/* ---------------------------------------------------------------- */\n/* The two constructors — the only place a brand is asserted         */\n/* ---------------------------------------------------------------- */\n\n/**\n * The one constructor that validates — `parseServiceId`'s shape, for the same\n * reason: a discriminated pair rather than `FeatureId | string`, because that\n * second shape compiles and is unusable, and the problem sentence is the one\n * `featureIdProblem` already produces, so a caller that is collecting findings\n * prints exactly what a refusal would.\n */\nexport function parseFeatureId(\n  raw: string,\n  label = \"feature id\",\n): { ok: true; id: FeatureId } | { ok: false; problem: string } {\n  const problem = featureIdProblem(raw, label);\n  if (problem !== null) return { ok: false, problem };\n  // The cast, on the line immediately after the check that earns it.\n  return { ok: true, id: raw as FeatureId };\n}\n\n/**\n * An id derived from a directory name a repository listed. Says nothing about\n * whether it is a legal id — that is the point: the enumeration must be able to\n * name the directory that is there, however it is spelled.\n *\n * This is a cast, and it has to be: the derivation in\n * `core/repo/entries.ts`'s `featureIdFromDirName` starts from a plain `readdir`\n * string, and a brand does not survive it. What the rule in\n * `docs/CODE-STYLE.md` buys is that both of this file's casts live HERE and\n * nowhere else — a third one somewhere in `src/` is a finding, not a shortcut.\n */\nexport function rawFeatureId(derived: string): RawFeatureId {\n  return derived as RawFeatureId;\n}\n"]}

package/dist/core/kernel/ids/service.js

@@ -0,0 +1,156 @@
+/**
+ * The spelling rules for the ids loam turns into directory names.
+ *
+ * A service id is not a label: it becomes `services/<id>/` in the shared docs
+ * repo, and it is interpolated into paths by adopt, validate, vouch, gherkin and
+ * new. That makes it caller-controlled path input, so it is validated in exactly
+ * one place — here — rather than by each command inventing its own guard. The
+ * failure mode this closes is not theoretical: `--service ../../etc` would have
+ * had `unfiledServicePaths()` hand a writer a directory outside the docs repo, and
+ * `--service ''` would have made `services//spec.md` collapse to a file the
+ * enumeration in repo.ts can never see again.
+ *
+ * The rule is deliberately narrower than "a path segment that happens to work":
+ * ids are also compared, sorted and printed in tables, so shell metacharacters,
+ * spaces and leading dots are refused even where the filesystem would accept
+ * them. Widening the alphabet later is a compatible change; narrowing it is not.
+ *
+ * "Works" also means "works on Windows", which this project tests in CI: the
+ * two rules below are the ones POSIX accepts and Windows does not. They used to
+ * live in migrate-openspec.ts alone, as a second, stricter copy of this grammar
+ * — so the PRIMARY authoring path (`--service`, `--touches`, `adopt`) accepted
+ * ids the migration refused, and `services/CON/` or `services/payments./` got
+ * as far as a directory nobody can create or open. Narrowing is not a
+ * compatible change, which is exactly why it belongs here, once, rather than in
+ * whichever command happened to think of it.
+ */
+/** The one grammar: alphanumeric head, then alphanumerics, dot, underscore, hyphen. */
+const SERVICE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * The MS-DOS device names Windows still reserves. Reserved with any extension
+ * and in any case (`nul`, `NUL.txt`), so the test is on the stem — the part
+ * before the first dot — uppercased.
+ */
+const WINDOWS_DEVICE = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/;
+export function dirNameHazard(name) {
+    // `..` produces the same verdict the pattern would; it is not special-cased
+    // here — the CALLERS' prose is where "no '..'" gets its own words.
+    if (name.includes("..") || !SERVICE_ID.test(name))
+        return { kind: "grammar" };
+    const stem = name.split(".")[0];
+    if (WINDOWS_DEVICE.test(stem.toUpperCase()))
+        return { kind: "windows-device", stem };
+    if (/[. ]$/.test(name))
+        return { kind: "windows-trailing" };
+    return null;
+}
+/** Prose form of the rule, shown verbatim in every refusal so the fix is obvious. */
+const SERVICE_ID_RULE = "a service id must start with a letter or digit and contain only letters, digits, '.', '_' or '-' " +
+    "(no slashes, no '..', no spaces) — it becomes the services/<id>/ directory name";
+/** Refusal carrying the offending value, so a caller can quote it back. */
+export class InvalidIdError extends Error {
+    value;
+    constructor(value, message) {
+        super(message);
+        this.value = value;
+        this.name = "InvalidIdError";
+    }
+}
+/**
+ * Why `id` is not a usable service id, or null when it is. Returning the reason
+ * instead of a boolean lets a caller that is already collecting findings report
+ * the same sentence a refusal would print.
+ */
+export function serviceIdProblem(id, label = "--service") {
+    if (typeof id !== "string" || id === "") {
+        return `${label} must name a service: ${SERVICE_ID_RULE}.`;
+    }
+    const hazard = dirNameHazard(id);
+    if (hazard === null)
+        return null;
+    switch (hazard.kind) {
+        case "grammar":
+            return `Invalid ${label} '${id}': ${SERVICE_ID_RULE}.`;
+        // Both refusals below are about Windows, and both get their own sentence:
+        // "does not match the id grammar" is true and useless, because the id
+        // LOOKS fine and the problem is what the filesystem does with it.
+        case "windows-device":
+            return (`Invalid ${label} '${id}': '${hazard.stem}' is a reserved device name on Windows — ` +
+                `services/${id}/ cannot be created there at all, so the docs repo would only work on some of the machines that clone it.`);
+        case "windows-trailing":
+            return (`Invalid ${label} '${id}': a service id may not end with '.' or a space — ` +
+                `Windows strips both when creating a directory, so '${id}' and '${id.replace(/[. ]+$/, "")}' would silently become one directory there and two everywhere else.`);
+    }
+}
+/**
+ * Assert that `id` may be used as a `services/<id>/` directory name. Throws
+ * InvalidIdError; commands catch it and report `invalid-option`, because a bad
+ * id is always something the caller typed, never a state of the repository.
+ */
+export function assertServiceId(id, label = "--service") {
+    const problem = serviceIdProblem(id, label);
+    if (problem !== null)
+        throw new InvalidIdError(typeof id === "string" ? id : String(id), problem);
+}
+/* ---------------------------------------------------------------- */
+/* The three constructors — the only place a brand is asserted       */
+/* ---------------------------------------------------------------- */
+/**
+ * The one constructor that validates. It takes a plain `string`, so a
+ * `DeclaredService` flows straight in — a brand is still a string — which is
+ * what makes this the single bridge out of document text.
+ *
+ * The result is a discriminated pair rather than `ServiceId | string`: that
+ * second shape compiles and is unusable, because nothing can narrow it back.
+ * The problem sentence is the one `serviceIdProblem` already produces, so a
+ * caller that is collecting findings prints exactly what a refusal would.
+ */
+export function parseServiceId(raw, label = "--service") {
+    const problem = serviceIdProblem(raw, label);
+    if (problem !== null)
+        return { ok: false, problem };
+    // The cast, on the line immediately after the check that earns it.
+    return { ok: true, id: raw };
+}
+/**
+ * The plural form, for the two commands that take a LIST of ids.
+ *
+ * It exists because `for (const id of ids) assertServiceId(id)` narrows the
+ * ELEMENT and not the array: the loop leaves `string[]`, so the value that
+ * reaches core is unbranded no matter how thoroughly each item was checked.
+ * That is invisible in review and the compiler is the only thing that sees it.
+ *
+ * Returns the offending value alongside the problem so the caller prints the
+ * same sentence, with the same code, that the element-wise loop printed.
+ */
+export function parseServiceIds(ids, label = "--service") {
+    const out = [];
+    for (const raw of ids) {
+        const parsed = parseServiceId(raw, label);
+        if (!parsed.ok)
+            return parsed;
+        out.push(parsed.id);
+    }
+    return { ok: true, ids: out };
+}
+/**
+ * A directory name off `readdir`. Says nothing about whether it is a legal id —
+ * that is the point, and `idProblem` is where the answer goes.
+ *
+ * This is a second cast, and it has to be: `readdir` and `basename` return plain
+ * `string`, and a brand does not survive them. What the rule in
+ * `docs/CODE-STYLE.md` actually buys is that all three casts live in THIS FILE
+ * and nowhere else. A fourth one somewhere in `src/` is a finding, not a shortcut.
+ */
+export function rawServiceId(dirName) {
+    return dirName;
+}
+/**
+ * A name a document asserted. Third and last cast, for the crossing between
+ * LikeC4's parse output and loam's type system: `e.service ?? e.title` is a
+ * plain `string` and does not brand itself.
+ */
+export function declaredService(text) {
+    return text;
+}
+//# sourceMappingURL=service.js.map

package/dist/core/kernel/ids/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../../../src/core/kernel/ids/service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The spelling rules for the ids loam turns into directory names.\n *\n * A service id is not a label: it becomes `services/<id>/` in the shared docs\n * repo, and it is interpolated into paths by adopt, validate, vouch, gherkin and\n * new. That makes it caller-controlled path input, so it is validated in exactly\n * one place — here — rather than by each command inventing its own guard. The\n * failure mode this closes is not theoretical: `--service ../../etc` would have\n * had `unfiledServicePaths()` hand a writer a directory outside the docs repo, and\n * `--service ''` would have made `services//spec.md` collapse to a file the\n * enumeration in repo.ts can never see again.\n *\n * The rule is deliberately narrower than \"a path segment that happens to work\":\n * ids are also compared, sorted and printed in tables, so shell metacharacters,\n * spaces and leading dots are refused even where the filesystem would accept\n * them. Widening the alphabet later is a compatible change; narrowing it is not.\n *\n * \"Works\" also means \"works on Windows\", which this project tests in CI: the\n * two rules below are the ones POSIX accepts and Windows does not. They used to\n * live in migrate-openspec.ts alone, as a second, stricter copy of this grammar\n * — so the PRIMARY authoring path (`--service`, `--touches`, `adopt`) accepted\n * ids the migration refused, and `services/CON/` or `services/payments./` got\n * as far as a directory nobody can create or open. Narrowing is not a\n * compatible change, which is exactly why it belongs here, once, rather than in\n * whichever command happened to think of it.\n */\n\n/* ---------------------------------------------------------------- */\n/* The three provenances a service name can have                     */\n/* ---------------------------------------------------------------- */\n\n/**\n * A service name is one of three things, and until now all three were `string`.\n *\n * The distinction that matters is not \"valid\" versus \"invalid\" — it is WHERE the\n * name came from, because that is what decides whether loam may join it into a\n * path. A directory name read off disk is safe to join whether or not it is a\n * legal id: it demonstrably exists, `readdir` just returned it. A name a\n * *document* asserts is not, because nothing has checked it and `metadata {\n * service '../../../etc' }` parses in LikeC4 without a single error.\n *\n * So `RawServiceId` is the base — a name whose provenance is the repository —\n * and `ServiceId` is that plus the grammar check, which makes it a SUBTYPE\n * rather than a sibling. That hierarchy is deliberate and was measured: with\n * three disjoint brands, `id === dirName`, `Set<RawServiceId>.has(id)` and\n * `[...ids, ...raws].sort()` all stop compiling, and none of them is a safety\n * question — they are the ordinary business of comparing a validated id with a\n * directory that exists. Only `DeclaredService` is disjoint, because only there\n * is the comparison a real crossing.\n *\n * `path.join` is NOT the enforcement point and cannot be made one: node types it\n * `join(...paths: string[])`, so every brand satisfies it. The guarantee lives\n * in `unfiledServicePaths`' own parameter type — `PathableService`, declared below and\n * demanded by that signature — so a `DeclaredService` at the call site is a\n * compile error, not a review finding. Code that spells `services/<svc>/` with\n * a bare join is outside the guarantee; `repo/paths.ts`'s banner names it.\n */\ndeclare const provenance: unique symbol;\ndeclare const checked: unique symbol;\n\n/**\n * A directory name read off `services/` or `features/<id>/specs/`. It exists;\n * it may still be an illegal loam id — `core/repo/repo.ts`'s `listServices`\n * deliberately returns those, reporting the failure as an `idProblem` field,\n * because `loam list` must show you the badly-named directory that is there.\n */\nexport type RawServiceId = string & { readonly [provenance]: \"loam\" };\n\n/** A name that passed `serviceIdProblem`. The only form a caller may construct. */\nexport type ServiceId = RawServiceId & { readonly [checked]: true };\n\n/**\n * A name a DOCUMENT asserts — `metadata { service '...' }` in a `.likec4` file,\n * an element title standing in for one, or an element id. Arbitrary unchecked\n * text, and disjoint from the two above on purpose: it must not reach a path\n * join without going through `parseServiceId` first.\n */\nexport type DeclaredService = string & { readonly [provenance]: \"document\" };\n\n/** What `unfiledServicePaths` accepts: a name whose provenance is the repository. */\nexport type PathableService = RawServiceId;\n\n/** The one grammar: alphanumeric head, then alphanumerics, dot, underscore, hyphen. */\nconst SERVICE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;\n\n/**\n * The MS-DOS device names Windows still reserves. Reserved with any extension\n * and in any case (`nul`, `NUL.txt`), so the test is on the stem — the part\n * before the first dot — uppercased.\n */\nconst WINDOWS_DEVICE = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/;\n\n/**\n * Why `name` cannot be a directory name in the docs repo, as a discriminated\n * fact rather than a sentence. Split out of `serviceIdProblem` when subsystem\n * names arrived (`./subsystem.ts`): both kinds of name become directories in\n * the same tree and share one flat namespace, so they must share ONE grammar\n * and one set of Windows rules — a name legal as one and illegal as the other\n * would make the namespace-collision refusal incoherent. Each caller keeps its\n * own prose, because \"a service id\" and \"a subsystem name\" point the reader at\n * different fixes; the CHECKS are what may never fork.\n */\nexport type DirNameHazard =\n  | { kind: \"grammar\" }\n  | { kind: \"windows-device\"; stem: string }\n  | { kind: \"windows-trailing\" };\n\nexport function dirNameHazard(name: string): DirNameHazard | null {\n  // `..` produces the same verdict the pattern would; it is not special-cased\n  // here — the CALLERS' prose is where \"no '..'\" gets its own words.\n  if (name.includes(\"..\") || !SERVICE_ID.test(name)) return { kind: \"grammar\" };\n  const stem = name.split(\".\")[0]!;\n  if (WINDOWS_DEVICE.test(stem.toUpperCase())) return { kind: \"windows-device\", stem };\n  if (/[. ]$/.test(name)) return { kind: \"windows-trailing\" };\n  return null;\n}\n\n/** Prose form of the rule, shown verbatim in every refusal so the fix is obvious. */\nconst SERVICE_ID_RULE =\n  \"a service id must start with a letter or digit and contain only letters, digits, '.', '_' or '-' \" +\n  \"(no slashes, no '..', no spaces) — it becomes the services/<id>/ directory name\";\n\n/** Refusal carrying the offending value, so a caller can quote it back. */\nexport class InvalidIdError extends Error {\n  constructor(\n    readonly value: string,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"InvalidIdError\";\n  }\n}\n\n/**\n * Why `id` is not a usable service id, or null when it is. Returning the reason\n * instead of a boolean lets a caller that is already collecting findings report\n * the same sentence a refusal would print.\n */\nexport function serviceIdProblem(id: unknown, label = \"--service\"): string | null {\n  if (typeof id !== \"string\" || id === \"\") {\n    return `${label} must name a service: ${SERVICE_ID_RULE}.`;\n  }\n  const hazard = dirNameHazard(id);\n  if (hazard === null) return null;\n  switch (hazard.kind) {\n    case \"grammar\":\n      return `Invalid ${label} '${id}': ${SERVICE_ID_RULE}.`;\n    // Both refusals below are about Windows, and both get their own sentence:\n    // \"does not match the id grammar\" is true and useless, because the id\n    // LOOKS fine and the problem is what the filesystem does with it.\n    case \"windows-device\":\n      return (\n        `Invalid ${label} '${id}': '${hazard.stem}' is a reserved device name on Windows — ` +\n        `services/${id}/ cannot be created there at all, so the docs repo would only work on some of the machines that clone it.`\n      );\n    case \"windows-trailing\":\n      return (\n        `Invalid ${label} '${id}': a service id may not end with '.' or a space — ` +\n        `Windows strips both when creating a directory, so '${id}' and '${id.replace(/[. ]+$/, \"\")}' would silently become one directory there and two everywhere else.`\n      );\n  }\n}\n\n/**\n * Assert that `id` may be used as a `services/<id>/` directory name. Throws\n * InvalidIdError; commands catch it and report `invalid-option`, because a bad\n * id is always something the caller typed, never a state of the repository.\n */\nexport function assertServiceId(id: unknown, label = \"--service\"): asserts id is ServiceId {\n  const problem = serviceIdProblem(id, label);\n  if (problem !== null) throw new InvalidIdError(typeof id === \"string\" ? id : String(id), problem);\n}\n\n/* ---------------------------------------------------------------- */\n/* The three constructors — the only place a brand is asserted       */\n/* ---------------------------------------------------------------- */\n\n/**\n * The one constructor that validates. It takes a plain `string`, so a\n * `DeclaredService` flows straight in — a brand is still a string — which is\n * what makes this the single bridge out of document text.\n *\n * The result is a discriminated pair rather than `ServiceId | string`: that\n * second shape compiles and is unusable, because nothing can narrow it back.\n * The problem sentence is the one `serviceIdProblem` already produces, so a\n * caller that is collecting findings prints exactly what a refusal would.\n */\nexport function parseServiceId(\n  raw: string,\n  label = \"--service\",\n): { ok: true; id: ServiceId } | { ok: false; problem: string } {\n  const problem = serviceIdProblem(raw, label);\n  if (problem !== null) return { ok: false, problem };\n  // The cast, on the line immediately after the check that earns it.\n  return { ok: true, id: raw as ServiceId };\n}\n\n/**\n * The plural form, for the two commands that take a LIST of ids.\n *\n * It exists because `for (const id of ids) assertServiceId(id)` narrows the\n * ELEMENT and not the array: the loop leaves `string[]`, so the value that\n * reaches core is unbranded no matter how thoroughly each item was checked.\n * That is invisible in review and the compiler is the only thing that sees it.\n *\n * Returns the offending value alongside the problem so the caller prints the\n * same sentence, with the same code, that the element-wise loop printed.\n */\nexport function parseServiceIds(\n  ids: readonly string[],\n  label = \"--service\",\n): { ok: true; ids: ServiceId[] } | { ok: false; problem: string } {\n  const out: ServiceId[] = [];\n  for (const raw of ids) {\n    const parsed = parseServiceId(raw, label);\n    if (!parsed.ok) return parsed;\n    out.push(parsed.id);\n  }\n  return { ok: true, ids: out };\n}\n\n/**\n * A directory name off `readdir`. Says nothing about whether it is a legal id —\n * that is the point, and `idProblem` is where the answer goes.\n *\n * This is a second cast, and it has to be: `readdir` and `basename` return plain\n * `string`, and a brand does not survive them. What the rule in\n * `docs/CODE-STYLE.md` actually buys is that all three casts live in THIS FILE\n * and nowhere else. A fourth one somewhere in `src/` is a finding, not a shortcut.\n */\nexport function rawServiceId(dirName: string): RawServiceId {\n  return dirName as RawServiceId;\n}\n\n/**\n * A name a document asserted. Third and last cast, for the crossing between\n * LikeC4's parse output and loam's type system: `e.service ?? e.title` is a\n * plain `string` and does not brand itself.\n */\nexport function declaredService(text: string): DeclaredService {\n  return text as DeclaredService;\n}\n"]}

package/dist/core/kernel/ids/subsystem.js

@@ -0,0 +1,63 @@
+/**
+ * The spelling rule for subsystem names — the directories that GROUP services
+ * under `services/`, marked by a `subsystem.yaml` (the walk that classifies
+ * them lives in `core/repo/tree/`).
+ *
+ * A subsystem name takes the service-id grammar and the same Windows rules,
+ * through the shared `dirNameHazard` in `./service.ts`, because both kinds of
+ * name become directory names in the same tree and share ONE flat namespace —
+ * unique across the whole tree at any depth, services and subsystems together.
+ * If the two grammars could drift, a name legal as one and illegal as the
+ * other would make the namespace-collision refusal incoherent.
+ *
+ * The BRAND is distinct on purpose, and deliberately not a subtype of
+ * `ServiceId`: a subsystem is a place services live, never a thing a `--service`
+ * flag may name or a path a spec's frontmatter may claim — `--into <name>` and
+ * `--service <id>` must not be satisfiable by each other's values. Placement is
+ * never part of any identity, and the type system is where that stops being a
+ * review comment — `repo/paths.ts`'s `subsystemPathUnder` is the consumer that
+ * DEMANDS the brand, so the joins `subsystem new` and `rename` build cannot be
+ * fed a raw argv string: a brand no signature requires is a validator with
+ * good intentions, which is exactly what this one briefly was.
+ */
+import { dirNameHazard } from "./service.js";
+/** Prose form of the rule, shown verbatim in every refusal so the fix is obvious. */
+const SUBSYSTEM_NAME_RULE = "a subsystem name must start with a letter or digit and contain only letters, digits, '.', '_' or '-' " +
+    "(no slashes, no '..', no spaces) — it becomes a directory name under services/";
+/**
+ * Why `name` is not a usable subsystem name, or null when it is. The same
+ * shape as `serviceIdProblem`, for the same reason: the tree walk reports the
+ * sentence as a finding (`subsystem.name-invalid`) while a command refusal
+ * prints it verbatim, and the two must not disagree.
+ */
+export function subsystemNameProblem(name, label = "subsystem name") {
+    if (typeof name !== "string" || name === "") {
+        return `${label} must name a subsystem: ${SUBSYSTEM_NAME_RULE}.`;
+    }
+    const hazard = dirNameHazard(name);
+    if (hazard === null)
+        return null;
+    switch (hazard.kind) {
+        case "grammar":
+            return `Invalid ${label} '${name}': ${SUBSYSTEM_NAME_RULE}.`;
+        case "windows-device":
+            return (`Invalid ${label} '${name}': '${hazard.stem}' is a reserved device name on Windows — ` +
+                `a '${name}/' directory cannot be created there at all, so the docs repo would only work on some of the machines that clone it.`);
+        case "windows-trailing":
+            return (`Invalid ${label} '${name}': a subsystem name may not end with '.' or a space — ` +
+                `Windows strips both when creating a directory, so '${name}' and '${name.replace(/[. ]+$/, "")}' would silently become one directory there and two everywhere else.`);
+    }
+}
+/**
+ * The one constructor that validates. Discriminated pair rather than
+ * `SubsystemName | string` for `parseServiceId`'s reason: the union shape
+ * compiles and is unusable, because nothing can narrow it back.
+ */
+export function parseSubsystemName(raw, label = "subsystem name") {
+    const problem = subsystemNameProblem(raw, label);
+    if (problem !== null)
+        return { ok: false, problem };
+    // The cast, on the line immediately after the check that earns it.
+    return { ok: true, name: raw };
+}
+//# sourceMappingURL=subsystem.js.map

package/dist/core/kernel/ids/subsystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subsystem.js","sourceRoot":"","sources":["../../../../src/core/kernel/ids/subsystem.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAO7C,qFAAqF;AACrF,MAAM,mBAAmB,GACvB,uGAAuG;IACvG,gFAAgF,CAAC;AAEnF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAa,EAAE,KAAK,GAAG,gBAAgB;IAC1E,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAC5C,OAAO,GAAG,KAAK,2BAA2B,mBAAmB,GAAG,CAAC;IACnE,CAAC;IACD,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,WAAW,KAAK,KAAK,IAAI,MAAM,mBAAmB,GAAG,CAAC;QAC/D,KAAK,gBAAgB;YACnB,OAAO,CACL,WAAW,KAAK,KAAK,IAAI,OAAO,MAAM,CAAC,IAAI,2CAA2C;gBACtF,MAAM,IAAI,sHAAsH,CACjI,CAAC;QACJ,KAAK,kBAAkB;YACrB,OAAO,CACL,WAAW,KAAK,KAAK,IAAI,wDAAwD;gBACjF,sDAAsD,IAAI,UAAU,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,sEAAsE,CACrK,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAW,EACX,KAAK,GAAG,gBAAgB;IAExB,MAAM,OAAO,GAAG,oBAAoB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACpD,mEAAmE;IACnE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAoB,EAAE,CAAC;AAClD,CAAC","sourcesContent":["/**\n * The spelling rule for subsystem names — the directories that GROUP services\n * under `services/`, marked by a `subsystem.yaml` (the walk that classifies\n * them lives in `core/repo/tree/`).\n *\n * A subsystem name takes the service-id grammar and the same Windows rules,\n * through the shared `dirNameHazard` in `./service.ts`, because both kinds of\n * name become directory names in the same tree and share ONE flat namespace —\n * unique across the whole tree at any depth, services and subsystems together.\n * If the two grammars could drift, a name legal as one and illegal as the\n * other would make the namespace-collision refusal incoherent.\n *\n * The BRAND is distinct on purpose, and deliberately not a subtype of\n * `ServiceId`: a subsystem is a place services live, never a thing a `--service`\n * flag may name or a path a spec's frontmatter may claim — `--into <name>` and\n * `--service <id>` must not be satisfiable by each other's values. Placement is\n * never part of any identity, and the type system is where that stops being a\n * review comment — `repo/paths.ts`'s `subsystemPathUnder` is the consumer that\n * DEMANDS the brand, so the joins `subsystem new` and `rename` build cannot be\n * fed a raw argv string: a brand no signature requires is a validator with\n * good intentions, which is exactly what this one briefly was.\n */\nimport { dirNameHazard } from \"./service.js\";\n\ndeclare const checked: unique symbol;\n\n/** A name that passed `subsystemNameProblem`. The only form a caller may construct. */\nexport type SubsystemName = string & { readonly [checked]: \"subsystem\" };\n\n/** Prose form of the rule, shown verbatim in every refusal so the fix is obvious. */\nconst SUBSYSTEM_NAME_RULE =\n  \"a subsystem name must start with a letter or digit and contain only letters, digits, '.', '_' or '-' \" +\n  \"(no slashes, no '..', no spaces) — it becomes a directory name under services/\";\n\n/**\n * Why `name` is not a usable subsystem name, or null when it is. The same\n * shape as `serviceIdProblem`, for the same reason: the tree walk reports the\n * sentence as a finding (`subsystem.name-invalid`) while a command refusal\n * prints it verbatim, and the two must not disagree.\n */\nexport function subsystemNameProblem(name: unknown, label = \"subsystem name\"): string | null {\n  if (typeof name !== \"string\" || name === \"\") {\n    return `${label} must name a subsystem: ${SUBSYSTEM_NAME_RULE}.`;\n  }\n  const hazard = dirNameHazard(name);\n  if (hazard === null) return null;\n  switch (hazard.kind) {\n    case \"grammar\":\n      return `Invalid ${label} '${name}': ${SUBSYSTEM_NAME_RULE}.`;\n    case \"windows-device\":\n      return (\n        `Invalid ${label} '${name}': '${hazard.stem}' is a reserved device name on Windows — ` +\n        `a '${name}/' directory cannot be created there at all, so the docs repo would only work on some of the machines that clone it.`\n      );\n    case \"windows-trailing\":\n      return (\n        `Invalid ${label} '${name}': a subsystem name may not end with '.' or a space — ` +\n        `Windows strips both when creating a directory, so '${name}' and '${name.replace(/[. ]+$/, \"\")}' would silently become one directory there and two everywhere else.`\n      );\n  }\n}\n\n/**\n * The one constructor that validates. Discriminated pair rather than\n * `SubsystemName | string` for `parseServiceId`'s reason: the union shape\n * compiles and is unusable, because nothing can narrow it back.\n */\nexport function parseSubsystemName(\n  raw: string,\n  label = \"subsystem name\",\n): { ok: true; name: SubsystemName } | { ok: false; problem: string } {\n  const problem = subsystemNameProblem(raw, label);\n  if (problem !== null) return { ok: false, problem };\n  // The cast, on the line immediately after the check that earns it.\n  return { ok: true, name: raw as SubsystemName };\n}\n"]}

package/dist/core/{path-safety.js → kernel/path-safety.js}

@@ -73,9 +73,10 @@ export function resolveInside(root, candidate, label = "path") {
 /**
  * Snapshot manifests are portable data, so their path spelling is stricter
  * than an interactive path: forward slashes, no redundant components, and a
- * file (not directory) name at the end.
+ * file (not directory) name at the end. The one constructor of `PortablePath`,
+ * because these checks are what the brand asserts.
  */
-export function resolvePortableFileInside(root, candidate, label = "path") {
+export function portablePathOf(candidate, label = "path") {
     if (candidate.includes("\\")) {
         throw new UnsafePathError(candidate, `${label} must use forward slashes`);
     }
@@ -83,7 +84,20 @@ export function resolvePortableFileInside(root, candidate, label = "path") {
     if (parts.some((part) => part === "" || part === "." || part === "..")) {
         throw new UnsafePathError(candidate, `${label} must be a canonical relative file path`);
     }
-    return resolveInside(root, candidate, label);
+    // The cast, on the line immediately after the checks that earn it.
+    return candidate;
+}
+/**
+ * Containment for a path that already EARNED the portable spelling — the one
+ * signature that demands the brand, so `PortablePath` has a consumer the
+ * compiler checks rather than a comment claiming the order of two calls.
+ */
+function resolvePortableInside(root, portable, label) {
+    return resolveInside(root, portable, label);
+}
+/** The portable spelling checks, then `resolveInside`'s containment proof — the ONE spelling of the pair. */
+export function resolvePortableFileInside(root, candidate, label = "path") {
+    return resolvePortableInside(root, portablePathOf(candidate, label), label);
 }
 /**
  * The same portable spelling rules, with containment judged LEXICALLY — for a
@@ -99,7 +113,7 @@ export function resolvePortableFileInside(root, candidate, label = "path") {
  * between two checkouts — is a supported layout that every walk of the repo
  * FOLLOWS rather than refuses (repo.ts's `entryIs` says so in full), and that
  * `archive` already writes through: its living-document writes are planned from
- * `servicePaths()` and never see this file. With the realpath test in force on
+ * `unfiledServicePaths()`/`servicePathsAt()` and never see this file. With the realpath test in force on
  * the manifest's `path` field, a `services/<svc>/` mounted that way made an
  * interrupted archive permanently unrepairable — the retry was told the
  * snapshot could not be read when it was perfectly intact, and the half-merge it

package/dist/core/kernel/path-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.js","sourceRoot":"","sources":["../../../src/core/kernel/path-safety.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Resolve caller-controlled paths without letting them leave an owned tree.\n *\n * A lexical `relative()` check is not enough: an existing component may be a\n * symlink whose target lives elsewhere. Conversely, checking only the final\n * path misses destinations that do not exist yet but whose nearest existing\n * parent is a symlink. This helper checks both views before a caller reads,\n * writes, walks, or removes anything.\n */\nimport { lstatSync, realpathSync } from \"node:fs\";\nimport { dirname, isAbsolute, relative, resolve, sep, win32 } from \"node:path\";\n\nexport class UnsafePathError extends Error {\n  constructor(\n    readonly candidate: string,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"UnsafePathError\";\n  }\n}\n\n/** True when `target` is `root` or one of its descendants. */\nexport function isPathInside(root: string, target: string): boolean {\n  const rel = relative(resolve(root), resolve(target));\n  return rel === \"\" || (!isAbsolute(rel) && rel !== \"..\" && !rel.startsWith(`..${sep}`));\n}\n\n/**\n * Resolve a relative path beneath `root`, rejecting absolute paths, explicit\n * parent traversal, and symlink escape. The final path may be absent: its\n * nearest existing ancestor is checked in that case.\n */\nexport function resolveInside(root: string, candidate: string, label = \"path\"): string {\n  if (candidate.length === 0) {\n    throw new UnsafePathError(candidate, `${label} must not be empty`);\n  }\n  // win32.isAbsolute is intentional even on POSIX. Persisted/configured paths\n  // may be moved between operating systems, and `C:\\\\...` must never turn into\n  // an innocuous relative filename merely because validation ran on Linux.\n  if (isAbsolute(candidate) || win32.isAbsolute(candidate)) {\n    throw new UnsafePathError(candidate, `${label} must be relative to its owning directory`);\n  }\n  if (candidate.split(/[\\\\/]/).includes(\"..\")) {\n    throw new UnsafePathError(candidate, `${label} must not contain '..' path segments`);\n  }\n\n  const rootAbs = resolve(root);\n  const target = resolve(rootAbs, candidate);\n  if (!isPathInside(rootAbs, target)) {\n    throw new UnsafePathError(candidate, `${label} resolves outside its owning directory`);\n  }\n\n  let rootReal: string;\n  let existing: string;\n  try {\n    rootReal = realpathSync(rootAbs);\n    existing = nearestExisting(target, rootAbs);\n  } catch (err) {\n    const detail = err instanceof Error ? err.message : String(err);\n    throw new UnsafePathError(candidate, `${label} cannot be resolved safely: ${detail}`);\n  }\n\n  let existingReal: string;\n  try {\n    existingReal = realpathSync(existing);\n  } catch (err) {\n    // A broken symlink is an existing path according to lstat, but realpath\n    // cannot prove where a later write through it would land. Refuse it.\n    const detail = err instanceof Error ? err.message : String(err);\n    throw new UnsafePathError(candidate, `${label} crosses an unreadable or broken symlink: ${detail}`);\n  }\n  if (!isPathInside(rootReal, existingReal)) {\n    throw new UnsafePathError(candidate, `${label} crosses a symlink outside its owning directory`);\n  }\n  return target;\n}\n\n/**\n * A relative file path in the portable spelling — forward slashes, no\n * redundant components. The brand's provenance is `portablePathOf` below: the\n * spelling checks there are the only way to construct one, so a value carrying\n * it has demonstrably passed them. Deliberately thin: it says nothing about\n * containment (that stays `resolveInside`'s question, asked per root), and it\n * is consumed by `resolvePortableInside` below — the one signature that\n * demands it — and every boundary (verify's evidence, unarchive's manifests)\n * reaches it through `resolvePortableFileInside`, the pair's one spelling.\n * The staging manifests keep their plain strings until the writer work that\n * owns those formats re-keys them.\n */\ndeclare const portable: unique symbol;\nexport type PortablePath = string & { readonly [portable]: true };\n\n/**\n * Snapshot manifests are portable data, so their path spelling is stricter\n * than an interactive path: forward slashes, no redundant components, and a\n * file (not directory) name at the end. The one constructor of `PortablePath`,\n * because these checks are what the brand asserts.\n */\nexport function portablePathOf(candidate: string, label = \"path\"): PortablePath {\n  if (candidate.includes(\"\\\\\")) {\n    throw new UnsafePathError(candidate, `${label} must use forward slashes`);\n  }\n  const parts = candidate.split(\"/\");\n  if (parts.some((part) => part === \"\" || part === \".\" || part === \"..\")) {\n    throw new UnsafePathError(candidate, `${label} must be a canonical relative file path`);\n  }\n  // The cast, on the line immediately after the checks that earn it.\n  return candidate as PortablePath;\n}\n\n/**\n * Containment for a path that already EARNED the portable spelling — the one\n * signature that demands the brand, so `PortablePath` has a consumer the\n * compiler checks rather than a comment claiming the order of two calls.\n */\nfunction resolvePortableInside(root: string, portable: PortablePath, label: string): string {\n  return resolveInside(root, portable, label);\n}\n\n/** The portable spelling checks, then `resolveInside`'s containment proof — the ONE spelling of the pair. */\nexport function resolvePortableFileInside(root: string, candidate: string, label = \"path\"): string {\n  return resolvePortableInside(root, portablePathOf(candidate, label), label);\n}\n\n/**\n * The same portable spelling rules, with containment judged LEXICALLY — for a\n * path that names a file the docs repo itself mounts.\n *\n * Every spelling defence above is kept, and for its reason: a snapshot manifest\n * is loam's own file, but a corrupted or hostile one could carry `..` segments,\n * an absolute path or a `C:\\` spelling, and what comes out of this join is a\n * path a caller then goes and reads.\n *\n * What is deliberately not applied is the realpath test. Composing a docs repo\n * out of symlinks — a worktree, a submodule, one service's directory shared\n * between two checkouts — is a supported layout that every walk of the repo\n * FOLLOWS rather than refuses (repo.ts's `entryIs` says so in full), and that\n * `archive` already writes through: its living-document writes are planned from\n * `unfiledServicePaths()`/`servicePathsAt()` and never see this file. With the realpath test in force on\n * the manifest's `path` field, a `services/<svc>/` mounted that way made an\n * interrupted archive permanently unrepairable — the retry was told the\n * snapshot could not be read when it was perfectly intact, and the half-merge it\n * was the only record of could never be repaired.\n *\n * This is only ever safe on a READ. A symlink that leaves the repo is\n * lexically indistinguishable from a service directory the operator mounted on\n * purpose — `escape/owned.txt` and `services/<svc>/spec.md` are both \"inside\n * docsDir\" until something resolves them — so the realpath test is the only\n * check that can refuse the first, at the price of also refusing the second.\n * A caller that goes on to WRITE through the path must pay that price and use\n * `resolvePortableFileInside`; `unarchive` does, and says so where it does.\n * A caller that only reads a file and compares a digest it never discloses\n * gains nothing from refusing, and loses the operator's ability to repair an\n * interrupted archive.\n */\nexport function resolvePortableFileInsideLexically(root: string, candidate: string, label = \"path\"): string {\n  if (candidate.length === 0) {\n    throw new UnsafePathError(candidate, `${label} must not be empty`);\n  }\n  if (candidate.includes(\"\\\\\")) {\n    throw new UnsafePathError(candidate, `${label} must use forward slashes`);\n  }\n  const parts = candidate.split(\"/\");\n  if (parts.some((part) => part === \"\" || part === \".\" || part === \"..\")) {\n    throw new UnsafePathError(candidate, `${label} must be a canonical relative file path`);\n  }\n  // win32.isAbsolute is intentional even on POSIX, for the reason `resolveInside`\n  // gives: a snapshot travels with its feature directory between operating\n  // systems, and `C:\\...` must never turn into an innocuous relative filename\n  // merely because the question was asked on Linux.\n  if (isAbsolute(candidate) || win32.isAbsolute(candidate)) {\n    throw new UnsafePathError(candidate, `${label} must be relative to its owning directory`);\n  }\n  const rootAbs = resolve(root);\n  const target = resolve(rootAbs, ...parts);\n  // Already implied by the segment test above, and asked anyway: this line is\n  // the containment claim itself, so a later loosening of the spelling rules\n  // cannot quietly stop making it.\n  if (!isPathInside(rootAbs, target)) {\n    throw new UnsafePathError(candidate, `${label} resolves outside its owning directory`);\n  }\n  return target;\n}\n\n/** Find the closest lexically contained path that exists, including symlinks. */\nfunction nearestExisting(target: string, root: string): string {\n  let current = target;\n  for (;;) {\n    try {\n      lstatSync(current);\n      return current;\n    } catch (err) {\n      const code = (err as NodeJS.ErrnoException).code;\n      if (code !== \"ENOENT\" && code !== \"ENOTDIR\") throw err;\n    }\n    if (current === root) return root;\n    const parent = dirname(current);\n    if (parent === current || !isPathInside(root, parent)) return root;\n    current = parent;\n  }\n}\n"]}

package/dist/core/kernel/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../../src/core/kernel/records.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,+DAA+D;AAC/D,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAsB,CAAC;AAClD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,QAAQ,CAAI,MAAyB,EAAE,GAAW;IAChE,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrF,CAAC","sourcesContent":["/**\n * The shapes an unknown parsed document is asked about, in one place.\n *\n * Every YAML and JSON file loam reads arrives as `unknown`, and every reader\n * has to answer the same first question before it can look at a key: is this an\n * object at all? Six modules each carried their own copy of the answer, two of\n * them spelled with a cast — and a cast is exactly what this test exists to\n * make unnecessary, since the predicate form hands the caller a narrowed type\n * that tsc keeps checking. A leaf with no imports, so any layer can ask.\n */\n\n/** An object with string keys — not null, and not an array. */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** The same question where the answer is used rather than branched on. */\nexport function asRecord(value: unknown): Record<string, unknown> | null {\n  return isRecord(value) ? value : null;\n}\n\n/**\n * A map whose keys come from a document somebody else wrote.\n *\n * `Object.create(null)` rather than `{}` because a key read out of untrusted\n * YAML can be `__proto__` or `constructor`, and on a normal object those either\n * mutate the prototype or read back a function that was never in the file.\n */\nexport function dictionary<T>(): Record<string, T> {\n  return Object.create(null) as Record<string, T>;\n}\n\n/** The value a record actually holds for `key`, never one it inherited. */\nexport function ownValue<T>(record: Record<string, T>, key: string): T | undefined {\n  return Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined;\n}\n"]}

package/dist/core/links/backlinks.js

@@ -0,0 +1,68 @@
+/**
+ * Who links to what, across the whole repository — the link graph read
+ * backwards.
+ *
+ * `link.unresolved` asks each document about its own links. This asks the
+ * opposite question, and it is the one the glossary is built on: "which
+ * documents use this term" is exactly "which documents link to `glossary/<term>.md`",
+ * and no single target can answer it. A term is cited from a service's spec, a
+ * capability document and a feature's intent, so the index is fleet-scope by
+ * construction.
+ *
+ * IT IS THE SAME WALK AS THE FINDING, deliberately — `resolveLinks` produces
+ * both halves of one answer, and the corpus is `core/links/corpus.ts`'s single
+ * definition. An index built from a second enumeration would report a term as
+ * unused while the document citing it was being graded one target over.
+ *
+ * AN UNREADABLE DOCUMENT IS RETURNED, not swallowed. A term can only be shown as
+ * cited by nobody if loam actually read everybody, and a UTF-16 spec.md would
+ * otherwise turn into a silently missing citation. Under `validate` the same
+ * file already earns `link.unreadable`; `loam list` has no such finding, so it
+ * needs the list to say what it did not read.
+ */
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { repoPath } from "../envelope/json.js";
+import { decodeDocument } from "../kernel/document-bytes.js";
+import { pathCaseIndex } from "./case.js";
+import { allAuthoredDocuments } from "./corpus.js";
+import { resolveLinks } from "./findings.js";
+/**
+ * Build the index over every authored document in the repository.
+ *
+ * One `pathCaseIndex` for the whole walk, because this one really is fleet-wide
+ * and the same directories are asked about hundreds of times. Still not a
+ * module-level cache: it lives exactly as long as this call.
+ */
+export async function backlinkIndex(docsDir, fleet) {
+    const linkers = new Map();
+    const unreadable = [];
+    const scope = { docsDir, cases: pathCaseIndex() };
+    for (const path of await allAuthoredDocuments(docsDir, fleet)) {
+        if (!existsSync(path))
+            continue;
+        let text;
+        try {
+            text = fleet === undefined ? decodeDocument(await readFile(path), path) : await fleet.readText(path);
+        }
+        catch {
+            unreadable.push(repoPath(docsDir, path));
+            continue;
+        }
+        const from = repoPath(docsDir, path);
+        for (const { target } of resolveLinks({ path, text }, scope).resolved) {
+            const key = resolve(target);
+            let sources = linkers.get(key);
+            if (sources === undefined)
+                linkers.set(key, (sources = new Set()));
+            sources.add(from);
+        }
+    }
+    unreadable.sort();
+    return {
+        linkersOf: (target) => [...(linkers.get(resolve(target)) ?? [])].sort(),
+        unreadable,
+    };
+}
+//# sourceMappingURL=backlinks.js.map

package/dist/core/links/backlinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backlinks.js","sourceRoot":"","sources":["../../../src/core/links/backlinks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAS7C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAgB,EAAE,KAAoB;IACxE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC/C,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,EAAE,CAAC;IAClD,KAAK,MAAM,IAAI,IAAI,MAAM,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAChC,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACvG,CAAC;QAAC,MAAM,CAAC;YACP,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;YACzC,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrC,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;YACtE,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC5B,IAAI,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC;YACnE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,UAAU,CAAC,IAAI,EAAE,CAAC;IAClB,OAAO;QACL,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE;QACvE,UAAU;KACX,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Who links to what, across the whole repository — the link graph read\n * backwards.\n *\n * `link.unresolved` asks each document about its own links. This asks the\n * opposite question, and it is the one the glossary is built on: \"which\n * documents use this term\" is exactly \"which documents link to `glossary/<term>.md`\",\n * and no single target can answer it. A term is cited from a service's spec, a\n * capability document and a feature's intent, so the index is fleet-scope by\n * construction.\n *\n * IT IS THE SAME WALK AS THE FINDING, deliberately — `resolveLinks` produces\n * both halves of one answer, and the corpus is `core/links/corpus.ts`'s single\n * definition. An index built from a second enumeration would report a term as\n * unused while the document citing it was being graded one target over.\n *\n * AN UNREADABLE DOCUMENT IS RETURNED, not swallowed. A term can only be shown as\n * cited by nobody if loam actually read everybody, and a UTF-16 spec.md would\n * otherwise turn into a silently missing citation. Under `validate` the same\n * file already earns `link.unreadable`; `loam list` has no such finding, so it\n * needs the list to say what it did not read.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { existsSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { repoPath } from \"../envelope/json.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { decodeDocument } from \"../kernel/document-bytes.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport { pathCaseIndex } from \"./case.js\";\nimport { allAuthoredDocuments } from \"./corpus.js\";\nimport { resolveLinks } from \"./findings.js\";\n\nexport interface BacklinkIndex {\n  /** Repo-relative paths of the documents linking to `target`, ordered, without duplicates. */\n  linkersOf(target: string): string[];\n  /** Repo-relative paths of documents whose links could not be read at all. */\n  unreadable: string[];\n}\n\n/**\n * Build the index over every authored document in the repository.\n *\n * One `pathCaseIndex` for the whole walk, because this one really is fleet-wide\n * and the same directories are asked about hundreds of times. Still not a\n * module-level cache: it lives exactly as long as this call.\n */\nexport async function backlinkIndex(docsDir: DocsDir, fleet?: FleetContext): Promise<BacklinkIndex> {\n  const linkers = new Map<string, Set<string>>();\n  const unreadable: string[] = [];\n  const scope = { docsDir, cases: pathCaseIndex() };\n  for (const path of await allAuthoredDocuments(docsDir, fleet)) {\n    if (!existsSync(path)) continue;\n    let text: string;\n    try {\n      text = fleet === undefined ? decodeDocument(await readFile(path), path) : await fleet.readText(path);\n    } catch {\n      unreadable.push(repoPath(docsDir, path));\n      continue;\n    }\n    const from = repoPath(docsDir, path);\n    for (const { target } of resolveLinks({ path, text }, scope).resolved) {\n      const key = resolve(target);\n      let sources = linkers.get(key);\n      if (sources === undefined) linkers.set(key, (sources = new Set()));\n      sources.add(from);\n    }\n  }\n  unreadable.sort();\n  return {\n    linkersOf: (target) => [...(linkers.get(resolve(target)) ?? [])].sort(),\n    unreadable,\n  };\n}\n"]}

package/dist/core/links/case.js

@@ -0,0 +1,74 @@
+/**
+ * Is a path spelled the way it is stored — the half of "does this link resolve"
+ * that `existsSync` cannot answer.
+ *
+ * `[Order](Order.md)` beside a file called `order.md` resolves on Windows and
+ * macOS and 404s on GitHub, which renders these documents and is
+ * case-sensitive, as is every Linux CI runner. That is the exact shape loam
+ * refuses everywhere else: a check that is green on the author's machine and red
+ * where the work is actually read. `link.unresolved` shipped without it as a
+ * recorded limit; this closes it.
+ *
+ * THE ANSWER IS A DIRECTORY LISTING, not a filesystem probe, because a probe is
+ * what is already wrong: on a case-insensitive volume every spelling of a name
+ * stats successfully, so the only place the true spelling exists is the parent's
+ * own listing. Each path segment between the docs root and the target is
+ * checked against that listing, verbatim.
+ *
+ * THE INDEX IS PER-INVOCATION AND PASSED, never module-level. A cached listing
+ * that outlived one command would answer for a directory that has since
+ * changed, and in this repository's forked test processes a module-level memo
+ * leaks between fixtures — `AGENTS.md` names that hazard directly. Cost is one
+ * `readdir` per distinct directory a link points into, which for a docs repo is
+ * a handful.
+ */
+import { readdirSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+/** A fresh index. One per command invocation — see the module note on why it is not shared. */
+export function pathCaseIndex() {
+    const listings = new Map();
+    const namesIn = (dir) => {
+        let names = listings.get(dir);
+        if (names === undefined) {
+            try {
+                names = new Set(readdirSync(dir));
+            }
+            catch {
+                // An unreadable directory answers nothing, and the honest reading is
+                // "not disproved": the target stat'ed, so something is there. Refusing
+                // a link because its parent denied a listing would convict the author
+                // for a permission bit.
+                names = new Set();
+            }
+            listings.set(dir, names);
+        }
+        return names;
+    };
+    return {
+        spelledExactly(root, target) {
+            const rootAbs = resolve(root);
+            const rel = relative(rootAbs, resolve(target));
+            if (rel === "")
+                return true;
+            let dir = rootAbs;
+            for (const segment of rel.split(sep)) {
+                const names = namesIn(dir);
+                // The empty set is the unreadable-directory case above: stop asking
+                // rather than convict every segment beneath it.
+                if (names.size > 0 && !names.has(segment))
+                    return false;
+                dir = resolve(dir, segment);
+            }
+            return true;
+        },
+        storedAs(dir, name) {
+            const wanted = name.toLowerCase();
+            for (const stored of namesIn(resolve(dir))) {
+                if (stored !== name && stored.toLowerCase() === wanted)
+                    return stored;
+            }
+            return undefined;
+        },
+    };
+}
+//# sourceMappingURL=case.js.map

package/dist/core/links/case.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"case.js","sourceRoot":"","sources":["../../../src/core/links/case.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAsBnD,+FAA+F;AAC/F,MAAM,UAAU,aAAa;IAC3B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;IAChD,MAAM,OAAO,GAAG,CAAC,GAAW,EAAe,EAAE;QAC3C,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,KAAK,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,qEAAqE;gBACrE,uEAAuE;gBACvE,sEAAsE;gBACtE,wBAAwB;gBACxB,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;YAC5B,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO;QACL,cAAc,CAAC,IAAI,EAAE,MAAM;YACzB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;YAC9B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;YAC/C,IAAI,GAAG,KAAK,EAAE;gBAAE,OAAO,IAAI,CAAC;YAC5B,IAAI,GAAG,GAAG,OAAO,CAAC;YAClB,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBACrC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC3B,oEAAoE;gBACpE,gDAAgD;gBAChD,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACxD,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC9B,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,QAAQ,CAAC,GAAG,EAAE,IAAI;YAChB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YAClC,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBAC3C,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,MAAM;oBAAE,OAAO,MAAM,CAAC;YACxE,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Is a path spelled the way it is stored — the half of \"does this link resolve\"\n * that `existsSync` cannot answer.\n *\n * `[Order](Order.md)` beside a file called `order.md` resolves on Windows and\n * macOS and 404s on GitHub, which renders these documents and is\n * case-sensitive, as is every Linux CI runner. That is the exact shape loam\n * refuses everywhere else: a check that is green on the author's machine and red\n * where the work is actually read. `link.unresolved` shipped without it as a\n * recorded limit; this closes it.\n *\n * THE ANSWER IS A DIRECTORY LISTING, not a filesystem probe, because a probe is\n * what is already wrong: on a case-insensitive volume every spelling of a name\n * stats successfully, so the only place the true spelling exists is the parent's\n * own listing. Each path segment between the docs root and the target is\n * checked against that listing, verbatim.\n *\n * THE INDEX IS PER-INVOCATION AND PASSED, never module-level. A cached listing\n * that outlived one command would answer for a directory that has since\n * changed, and in this repository's forked test processes a module-level memo\n * leaks between fixtures — `AGENTS.md` names that hazard directly. Cost is one\n * `readdir` per distinct directory a link points into, which for a docs repo is\n * a handful.\n */\nimport { readdirSync } from \"node:fs\";\nimport { relative, resolve, sep } from \"node:path\";\n\nexport interface PathCaseIndex {\n  /**\n   * True when every segment of `target` below `root` is spelled exactly as the\n   * filesystem stores it. `target` must already be known to lie inside `root`;\n   * this asks only about spelling.\n   */\n  spelledExactly(root: string, target: string): boolean;\n  /**\n   * The name `dir` actually stores for `name`, when one differs from it only by\n   * case — the hint that turns \"resolves to nothing\" into \"you spelled it\n   * `Order.md` and it is stored as `order.md`\".\n   *\n   * Asked on both platforms and not only the case-insensitive one, which is the\n   * whole point: on Linux the same link fails `existsSync` outright and on\n   * Windows it fails `spelledExactly`, and a diagnosis that differed by\n   * operating system would be a machine contract that does not hold.\n   */\n  storedAs(dir: string, name: string): string | undefined;\n}\n\n/** A fresh index. One per command invocation — see the module note on why it is not shared. */\nexport function pathCaseIndex(): PathCaseIndex {\n  const listings = new Map<string, Set<string>>();\n  const namesIn = (dir: string): Set<string> => {\n    let names = listings.get(dir);\n    if (names === undefined) {\n      try {\n        names = new Set(readdirSync(dir));\n      } catch {\n        // An unreadable directory answers nothing, and the honest reading is\n        // \"not disproved\": the target stat'ed, so something is there. Refusing\n        // a link because its parent denied a listing would convict the author\n        // for a permission bit.\n        names = new Set<string>();\n      }\n      listings.set(dir, names);\n    }\n    return names;\n  };\n\n  return {\n    spelledExactly(root, target) {\n      const rootAbs = resolve(root);\n      const rel = relative(rootAbs, resolve(target));\n      if (rel === \"\") return true;\n      let dir = rootAbs;\n      for (const segment of rel.split(sep)) {\n        const names = namesIn(dir);\n        // The empty set is the unreadable-directory case above: stop asking\n        // rather than convict every segment beneath it.\n        if (names.size > 0 && !names.has(segment)) return false;\n        dir = resolve(dir, segment);\n      }\n      return true;\n    },\n    storedAs(dir, name) {\n      const wanted = name.toLowerCase();\n      for (const stored of namesIn(resolve(dir))) {\n        if (stored !== name && stored.toLowerCase() === wanted) return stored;\n      }\n      return undefined;\n    },\n  };\n}\n"]}