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

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

@@ -0,0 +1,72 @@
+/**
+ * The spelling rule for a capability id that ARRIVED FROM ARGV — the one
+ * provenance `repo/authored/paths.ts` says must never reach a path join unchecked.
+ *
+ * `livingCapabilityPaths` takes a plain `string`, and its comment states why: a
+ * capability id has no grammar of its own — it is a YAML key and a chain of
+ * directory names — so what holds that join is PROVENANCE. Every id it sees
+ * today came out of a `readCapabilityTree` walk, where each component is a
+ * `readdir` entry name and therefore demonstrably a directory that exists.
+ * (`featureCapabilityDeltasDir` beside it takes a branded `FeatureDir` and no
+ * capability id at all; the feature-side join is spelled by `loam new` itself.)
+ *
+ * `loam new --capability <id>` is the first caller with no such provenance. The
+ * string is whatever a person typed, and it is joined as
+ * `features/<dirName>/capabilities/<id>/spec.md` — so `--capability ../../evil`
+ * resolves to `features/evil/spec.md`, a directory `listFeatures` then
+ * enumerates as a feature, and one `..` further reaches the docs-repo root.
+ * `resolveInside` cannot refuse either: both are still inside the repo. That is
+ * the failure this module closes, and it is the same one
+ * `core/kernel/ids/service.ts` opens with one file over.
+ *
+ * IT IS THE DIRECTORY-NAME RULE, NOT A NEW ONE. Nesting is spelled by the tree
+ * (`payments/refunds` is two directories), so an id is legal exactly when every
+ * one of its `/`-separated segments is a legal directory name in the docs repo
+ * — `dirNameHazard`, the same check a service id and a subsystem name are held
+ * to, Windows device names and trailing dots included. A capability tree that
+ * only clones onto some of the machines that read it is the same defect there
+ * as it is under `services/`.
+ *
+ * NO BRAND, deliberately, and the reason is the provenance rule above rather
+ * than an omission: a brand is worth its annotations when a path builder can
+ * DEMAND it, and neither builder can — both are called with walk-derived ids
+ * that were never parsed here and must keep working. What this module gives is
+ * the check the argv path owes; the rule that walk-derived ids are safe stays
+ * where `repo/paths.ts` already writes it down.
+ */
+import { dirNameHazard } from "./service.js";
+/** Prose form of the rule, shown verbatim in the refusal so the fix is obvious. */
+const CAPABILITY_ID_RULE = "a capability id is one or more '/'-separated segments, each starting with a letter or digit and " +
+    "containing only letters, digits, '.', '_' or '-' (no '..', no spaces, no leading or trailing '/') — " +
+    "it becomes the capabilities/<id>/ directory chain, one directory per segment";
+/**
+ * Why `id` cannot be a capability id, or null when it can.
+ *
+ * A sentence rather than a boolean, matching `serviceIdProblem`: a caller that
+ * is collecting findings prints exactly what a refusal would.
+ */
+export function capabilityIdProblem(id, label = "--capability") {
+    if (typeof id !== "string" || id === "") {
+        return `${label} must name a capability: ${CAPABILITY_ID_RULE}.`;
+    }
+    for (const segment of id.split("/")) {
+        const hazard = dirNameHazard(segment);
+        if (hazard === null)
+            continue;
+        switch (hazard.kind) {
+            case "grammar":
+                return `Invalid ${label} '${id}': ${CAPABILITY_ID_RULE}.`;
+            // Both Windows refusals keep their own sentence for `serviceIdProblem`'s
+            // reason: "does not match the 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 — ` +
+                    `the capabilities/${id}/ 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} '${id}': no segment of a capability id may end with '.' or a space — ` +
+                    "Windows strips both when creating a directory, so the id would silently name one directory there and another everywhere else.");
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=capability.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../../src/core/kernel/ids/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,mFAAmF;AACnF,MAAM,kBAAkB,GACtB,kGAAkG;IAClG,sGAAsG;IACtG,8EAA8E,CAAC;AAEjF;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAW,EAAE,KAAK,GAAG,cAAc;IACrE,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACxC,OAAO,GAAG,KAAK,4BAA4B,kBAAkB,GAAG,CAAC;IACnE,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QAC9B,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,SAAS;gBACZ,OAAO,WAAW,KAAK,KAAK,EAAE,MAAM,kBAAkB,GAAG,CAAC;YAC5D,yEAAyE;YACzE,wEAAwE;YACxE,qEAAqE;YACrE,KAAK,gBAAgB;gBACnB,OAAO,CACL,WAAW,KAAK,KAAK,EAAE,OAAO,MAAM,CAAC,IAAI,2CAA2C;oBACpF,oBAAoB,EAAE,qHAAqH,CAC5I,CAAC;YACJ,KAAK,kBAAkB;gBACrB,OAAO,CACL,WAAW,KAAK,KAAK,EAAE,iEAAiE;oBACxF,+HAA+H,CAChI,CAAC;QACN,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * The spelling rule for a capability id that ARRIVED FROM ARGV — the one\n * provenance `repo/authored/paths.ts` says must never reach a path join unchecked.\n *\n * `livingCapabilityPaths` takes a plain `string`, and its comment states why: a\n * capability id has no grammar of its own — it is a YAML key and a chain of\n * directory names — so what holds that join is PROVENANCE. Every id it sees\n * today came out of a `readCapabilityTree` walk, where each component is a\n * `readdir` entry name and therefore demonstrably a directory that exists.\n * (`featureCapabilityDeltasDir` beside it takes a branded `FeatureDir` and no\n * capability id at all; the feature-side join is spelled by `loam new` itself.)\n *\n * `loam new --capability <id>` is the first caller with no such provenance. The\n * string is whatever a person typed, and it is joined as\n * `features/<dirName>/capabilities/<id>/spec.md` — so `--capability ../../evil`\n * resolves to `features/evil/spec.md`, a directory `listFeatures` then\n * enumerates as a feature, and one `..` further reaches the docs-repo root.\n * `resolveInside` cannot refuse either: both are still inside the repo. That is\n * the failure this module closes, and it is the same one\n * `core/kernel/ids/service.ts` opens with one file over.\n *\n * IT IS THE DIRECTORY-NAME RULE, NOT A NEW ONE. Nesting is spelled by the tree\n * (`payments/refunds` is two directories), so an id is legal exactly when every\n * one of its `/`-separated segments is a legal directory name in the docs repo\n * — `dirNameHazard`, the same check a service id and a subsystem name are held\n * to, Windows device names and trailing dots included. A capability tree that\n * only clones onto some of the machines that read it is the same defect there\n * as it is under `services/`.\n *\n * NO BRAND, deliberately, and the reason is the provenance rule above rather\n * than an omission: a brand is worth its annotations when a path builder can\n * DEMAND it, and neither builder can — both are called with walk-derived ids\n * that were never parsed here and must keep working. What this module gives is\n * the check the argv path owes; the rule that walk-derived ids are safe stays\n * where `repo/paths.ts` already writes it down.\n */\nimport { dirNameHazard } from \"./service.js\";\n\n/** Prose form of the rule, shown verbatim in the refusal so the fix is obvious. */\nconst CAPABILITY_ID_RULE =\n  \"a capability id is one or more '/'-separated segments, each starting with a letter or digit and \" +\n  \"containing only letters, digits, '.', '_' or '-' (no '..', no spaces, no leading or trailing '/') — \" +\n  \"it becomes the capabilities/<id>/ directory chain, one directory per segment\";\n\n/**\n * Why `id` cannot be a capability id, or null when it can.\n *\n * A sentence rather than a boolean, matching `serviceIdProblem`: a caller that\n * is collecting findings prints exactly what a refusal would.\n */\nexport function capabilityIdProblem(id: unknown, label = \"--capability\"): string | null {\n  if (typeof id !== \"string\" || id === \"\") {\n    return `${label} must name a capability: ${CAPABILITY_ID_RULE}.`;\n  }\n  for (const segment of id.split(\"/\")) {\n    const hazard = dirNameHazard(segment);\n    if (hazard === null) continue;\n    switch (hazard.kind) {\n      case \"grammar\":\n        return `Invalid ${label} '${id}': ${CAPABILITY_ID_RULE}.`;\n      // Both Windows refusals keep their own sentence for `serviceIdProblem`'s\n      // reason: \"does not match the grammar\" is true and useless, because the\n      // id 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          `the capabilities/${id}/ 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} '${id}': no segment of a capability id may end with '.' or a space — ` +\n          \"Windows strips both when creating a directory, so the id would silently name one directory there and another everywhere else.\"\n        );\n    }\n  }\n  return null;\n}\n"]}

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

@@ -0,0 +1,33 @@
+/** The only constructor. `resolved` must carry `DocsDir`'s provenance, above. */
+export function docsDirOf(resolved) {
+    return resolved;
+}
+/** The only constructor. `abs` must carry `FeatureDir`'s provenance, above. */
+export function featureDirOf(abs) {
+    return abs;
+}
+/** The only constructor. `abs` must carry one of `ServiceDir`'s two provenances, above. */
+export function serviceDirOf(abs) {
+    return abs;
+}
+/**
+ * Where a service sits under `services/`, repo-relative and spelled from its
+ * own placement chain — `services/<subsystem>/…/<id>/` for a filed service,
+ * `services/<id>/` for an unfiled one.
+ *
+ * The join it replaces is `services/${id}`, which is right for an unfiled
+ * service and WRONG for every filed one, and the failure is the kind a reader
+ * cannot diagnose: the message names a directory that does not exist, so the
+ * fix goes to the wrong place, or a `cd` simply fails. Three findings already
+ * spelled it correctly by hand and `loam status` spelled it by id; this exists
+ * so the rule has one implementation rather than a convention.
+ *
+ * DISPLAY only, and not a `ServiceDir`: it is repo-relative text for a human
+ * to read, while `ServiceDir` is the absolute path artifacts resolve from. And
+ * `subsystem` is placement carrying no identity, so nothing here may be joined
+ * on — the id is the identity, at whatever depth it lives.
+ */
+export function serviceTreePath(s) {
+    return ["services", ...s.subsystem, s.id].join("/");
+}
+//# sourceMappingURL=dirs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dirs.js","sourceRoot":"","sources":["../../../../src/core/kernel/ids/dirs.ts"],"names":[],"mappings":"AAwDA,iFAAiF;AACjF,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,OAAO,QAAmB,CAAC;AAC7B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAiB,CAAC;AAC3B,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAiB,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,CAAsC;IACpE,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtD,CAAC","sourcesContent":["/**\n * The two directory roots loam's path builders spell paths under, branded by\n * PROVENANCE — where the string came from — exactly as the id brands beside\n * this file are.\n *\n * `repo/paths.ts` interpolates caller-controlled ids into these roots, and its\n * guarantee is only as good as the root it starts from: an\n * `unfiledServicePaths(dir, id)` whose `dir` is whatever string happened to\n * be in scope spells paths\n * into whatever tree that string names. Honestly stated: these constructors\n * VALIDATE nothing — they RECORD a provenance the caller must already have\n * established, and what the gate contributes is that the cast appears in\n * exactly one place per brand (a cast anywhere else in `src/` is a finding,\n * not a shortcut). `init` brands its `--docs` resolution before its guards\n * run and refuses before any path is built — the provenance comment is the\n * contract those call sites are held to by review, not by the compiler.\n *\n * The two brands are deliberately disjoint: a docs repo root and a feature\n * directory are different trees, and `featurePaths(docsDir)` is precisely the\n * confusion the compiler should refuse.\n */\ndeclare const provenance: unique symbol;\n\n/**\n * The resolved absolute root of the shared docs repo. Provenance: resolved\n * through a loaded config (`parseConfig` resolves the stored spelling against\n * the config file's own directory) or an explicit `--docs` a command\n * validated. NOT the stored spelling — loam.json deliberately keeps the\n * relative form (`storedDocsDir`), and that spelling stays a plain `string`.\n */\nexport type DocsDir = string & { readonly [provenance]: \"docs-dir\" };\n\n/**\n * The absolute path of one feature's directory. Provenance: an enumeration\n * read this directory — `listFeatures` joined a name `readdir` returned onto\n * the features root it walked, so the directory demonstrably exists (or did,\n * one readdir ago).\n */\nexport type FeatureDir = string & { readonly [provenance]: \"feature-dir\" };\n\n/**\n * The absolute path of one service's directory — the value the artifact paths\n * in `repo/paths.ts` are spelled under. Two provenances, both stated because\n * both are load-bearing: the tree walk read it (`core/repo/tree/walk.ts`\n * joined a name `readdir` returned onto the directory it was listed under, at\n * whatever depth the service actually lives), or it is the canonical UNFILED\n * spelling `<docsDir>/services/<id>/` that `unfiledServicePaths` builds from a\n * validated id and a `DocsDir` — the one place creation lands, and the honest\n * fallback for a service the enumeration does not answer. A path from a\n * readdir is NARROWER than one built from a validated string: the directory\n * demonstrably exists where the path says. Nothing else may construct this —\n * in particular not a bare `join(docsDir, \"services\", name)` at a call site,\n * which is exactly the root-level assumption the subsystem tree retired.\n */\nexport type ServiceDir = string & { readonly [provenance]: \"service-dir\" };\n\n/** The only constructor. `resolved` must carry `DocsDir`'s provenance, above. */\nexport function docsDirOf(resolved: string): DocsDir {\n  return resolved as DocsDir;\n}\n\n/** The only constructor. `abs` must carry `FeatureDir`'s provenance, above. */\nexport function featureDirOf(abs: string): FeatureDir {\n  return abs as FeatureDir;\n}\n\n/** The only constructor. `abs` must carry one of `ServiceDir`'s two provenances, above. */\nexport function serviceDirOf(abs: string): ServiceDir {\n  return abs as ServiceDir;\n}\n\n/**\n * Where a service sits under `services/`, repo-relative and spelled from its\n * own placement chain — `services/<subsystem>/…/<id>/` for a filed service,\n * `services/<id>/` for an unfiled one.\n *\n * The join it replaces is `services/${id}`, which is right for an unfiled\n * service and WRONG for every filed one, and the failure is the kind a reader\n * cannot diagnose: the message names a directory that does not exist, so the\n * fix goes to the wrong place, or a `cd` simply fails. Three findings already\n * spelled it correctly by hand and `loam status` spelled it by id; this exists\n * so the rule has one implementation rather than a convention.\n *\n * DISPLAY only, and not a `ServiceDir`: it is repo-relative text for a human\n * to read, while `ServiceDir` is the absolute path artifacts resolve from. And\n * `subsystem` is placement carrying no identity, so nothing here may be joined\n * on — the id is the identity, at whatever depth it lives.\n */\nexport function serviceTreePath(s: { id: string; subsystem: string[] }): string {\n  return [\"services\", ...s.subsystem, s.id].join(\"/\");\n}\n"]}

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/fqn/ancestors.js

@@ -0,0 +1,65 @@
+/**
+ * The ancestor chain of a dotted element id — `a.b.c` yields `a.b`, then `a`.
+ *
+ * A leaf of its own because five modules were each walking it privately, in two
+ * spellings, and the walk is not incidental to any of them: it is the rule that
+ * a landscape does not have to draw a service as one opaque box. The moment
+ * somebody models its containers — `paymentService.api`, `paymentService.worker`
+ * — an edge drawn INTO a container is still an edge into the service, and every
+ * join that groups by service has to know that. Resolving only the exact id is
+ * what made those edges invisible: the spine check silently skipped them, and
+ * the no-openapi grace treated a service with a dozen inbound container calls as
+ * one nobody calls at all.
+ *
+ * The same walk answers a second question one altitude down, which is why a
+ * fifth copy appeared. A service model draws an edge at `kafka.orderEvents`
+ * while the fleet's health.yaml names the dependency `kafka`, so the slice of a
+ * per-service project has to carry the ANCESTOR of a partner endpoint as well as
+ * the endpoint (`core/c4/service-model/slice.ts`). Dropping it would turn a
+ * fleet's dependency declarations into `health.dependency-unmodelled` findings
+ * on the day it migrated its models, with nothing in the docs having changed.
+ *
+ * TWO SPELLINGS, both exported, because both are real and picking one would make
+ * every second caller write `[id, ...properAncestorIds(id)]` or `.slice(1)` — a
+ * per-call-site adjustment is exactly how a shared walk drifts back into five.
+ * A resolver that also looks the element itself up wants `ancestorIds`; a walk
+ * that has already handled the element wants `properAncestorIds`.
+ *
+ * No brand and no validation: this is string arithmetic over an id a DOCUMENT
+ * spells, and `core/kernel/ids/service.ts`'s provenance rules are about names
+ * that have to answer for a directory. An id with no dot in it has no ancestors
+ * and yields the empty list, which is the correct answer rather than an edge
+ * case — a top-level element belongs to nothing above it.
+ */
+/** Every dotted ancestor of an id, NEAREST FIRST and excluding the id itself. */
+export function properAncestorIds(id) {
+    const out = [];
+    // Walking right-to-left from the last dot rather than splitting and rejoining:
+    // the ids are already strings, the answer is a set of prefixes of one of them,
+    // and a split/join round trip would invent a rule about what a segment may
+    // contain that nothing else here has.
+    for (let dot = id.lastIndexOf("."); dot !== -1; dot = id.lastIndexOf(".", dot - 1)) {
+        out.push(id.slice(0, dot));
+    }
+    return out;
+}
+/** The id itself, then every dotted ancestor of it, nearest first. */
+export function ancestorIds(id) {
+    return [id, ...properAncestorIds(id)];
+}
+/**
+ * The id a declaration nests directly under — `""` for a top-level one, which
+ * nests under nothing.
+ *
+ * The nearest ancestor, named because that is the question the callers ask:
+ * `properAncestorIds(id)[0] ?? ""` is the same walk spelled as an array index,
+ * and every reader has to re-derive that the first entry is the parent. It is
+ * here rather than beside its callers for the reason the file exists at all —
+ * the archive's two merges had each grown a private copy, and a third was about
+ * to appear the moment the routing gained a module.
+ */
+export function parentIdOf(id) {
+    const dot = id.lastIndexOf(".");
+    return dot === -1 ? "" : id.slice(0, dot);
+}
+//# sourceMappingURL=ancestors.js.map

package/dist/core/kernel/ids/fqn/ancestors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ancestors.js","sourceRoot":"","sources":["../../../../../src/core/kernel/ids/fqn/ancestors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,iFAAiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,+EAA+E;IAC/E,+EAA+E;IAC/E,2EAA2E;IAC3E,sCAAsC;IACtC,KAAK,IAAI,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC;QACnF,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,CAAC,EAAE,EAAE,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,MAAM,GAAG,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC5C,CAAC","sourcesContent":["/**\n * The ancestor chain of a dotted element id — `a.b.c` yields `a.b`, then `a`.\n *\n * A leaf of its own because five modules were each walking it privately, in two\n * spellings, and the walk is not incidental to any of them: it is the rule that\n * a landscape does not have to draw a service as one opaque box. The moment\n * somebody models its containers — `paymentService.api`, `paymentService.worker`\n * — an edge drawn INTO a container is still an edge into the service, and every\n * join that groups by service has to know that. Resolving only the exact id is\n * what made those edges invisible: the spine check silently skipped them, and\n * the no-openapi grace treated a service with a dozen inbound container calls as\n * one nobody calls at all.\n *\n * The same walk answers a second question one altitude down, which is why a\n * fifth copy appeared. A service model draws an edge at `kafka.orderEvents`\n * while the fleet's health.yaml names the dependency `kafka`, so the slice of a\n * per-service project has to carry the ANCESTOR of a partner endpoint as well as\n * the endpoint (`core/c4/service-model/slice.ts`). Dropping it would turn a\n * fleet's dependency declarations into `health.dependency-unmodelled` findings\n * on the day it migrated its models, with nothing in the docs having changed.\n *\n * TWO SPELLINGS, both exported, because both are real and picking one would make\n * every second caller write `[id, ...properAncestorIds(id)]` or `.slice(1)` — a\n * per-call-site adjustment is exactly how a shared walk drifts back into five.\n * A resolver that also looks the element itself up wants `ancestorIds`; a walk\n * that has already handled the element wants `properAncestorIds`.\n *\n * No brand and no validation: this is string arithmetic over an id a DOCUMENT\n * spells, and `core/kernel/ids/service.ts`'s provenance rules are about names\n * that have to answer for a directory. An id with no dot in it has no ancestors\n * and yields the empty list, which is the correct answer rather than an edge\n * case — a top-level element belongs to nothing above it.\n */\n\n/** Every dotted ancestor of an id, NEAREST FIRST and excluding the id itself. */\nexport function properAncestorIds(id: string): string[] {\n  const out: string[] = [];\n  // Walking right-to-left from the last dot rather than splitting and rejoining:\n  // the ids are already strings, the answer is a set of prefixes of one of them,\n  // and a split/join round trip would invent a rule about what a segment may\n  // contain that nothing else here has.\n  for (let dot = id.lastIndexOf(\".\"); dot !== -1; dot = id.lastIndexOf(\".\", dot - 1)) {\n    out.push(id.slice(0, dot));\n  }\n  return out;\n}\n\n/** The id itself, then every dotted ancestor of it, nearest first. */\nexport function ancestorIds(id: string): string[] {\n  return [id, ...properAncestorIds(id)];\n}\n\n/**\n * The id a declaration nests directly under — `\"\"` for a top-level one, which\n * nests under nothing.\n *\n * The nearest ancestor, named because that is the question the callers ask:\n * `properAncestorIds(id)[0] ?? \"\"` is the same walk spelled as an array index,\n * and every reader has to re-derive that the first entry is the parent. It is\n * here rather than beside its callers for the reason the file exists at all —\n * the archive's two merges had each grown a private copy, and a third was about\n * to appear the moment the routing gained a module.\n */\nexport function parentIdOf(id: string): string {\n  const dot = id.lastIndexOf(\".\");\n  return dot === -1 ? \"\" : id.slice(0, dot);\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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAyDH,uFAAuF;AACvF,MAAM,UAAU,GAAG,8BAA8B,CAAC;AAElD;;;;GAIG;AACH,MAAM,cAAc,GAAG,yCAAyC,CAAC;AAiBjE,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,4EAA4E;IAC5E,mEAAmE;IACnE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC9E,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACjC,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACrF,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC5D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qFAAqF;AACrF,MAAM,eAAe,GACnB,mGAAmG;IACnG,iFAAiF,CAAC;AAEpF,2EAA2E;AAC3E,MAAM,OAAO,cAAe,SAAQ,KAAK;IAE5B,KAAK;IADhB,YACW,KAAa,EACtB,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;qBAHN,KAAK;QAId,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAW,EAAE,KAAK,GAAG,WAAW;IAC/D,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACxC,OAAO,GAAG,KAAK,yBAAyB,eAAe,GAAG,CAAC;IAC7D,CAAC;IACD,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,SAAS;YACZ,OAAO,WAAW,KAAK,KAAK,EAAE,MAAM,eAAe,GAAG,CAAC;QACzD,0EAA0E;QAC1E,sEAAsE;QACtE,kEAAkE;QAClE,KAAK,gBAAgB;YACnB,OAAO,CACL,WAAW,KAAK,KAAK,EAAE,OAAO,MAAM,CAAC,IAAI,2CAA2C;gBACpF,YAAY,EAAE,2GAA2G,CAC1H,CAAC;QACJ,KAAK,kBAAkB;YACrB,OAAO,CACL,WAAW,KAAK,KAAK,EAAE,oDAAoD;gBAC3E,sDAAsD,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,sEAAsE,CACjK,CAAC;IACN,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,EAAW,EAAE,KAAK,GAAG,WAAW;IAC9D,MAAM,OAAO,GAAG,gBAAgB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC5C,IAAI,OAAO,KAAK,IAAI;QAAE,MAAM,IAAI,cAAc,CAAC,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;AACpG,CAAC;AAED,sEAAsE;AACtE,uEAAuE;AACvE,sEAAsE;AAEtE;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,KAAK,GAAG,WAAW;IAEnB,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,eAAe,CAC7B,GAAsB,EACtB,KAAK,GAAG,WAAW;IAEnB,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,MAAM,CAAC;QAC9B,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAuB,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAuB,CAAC;AACjC,CAAC","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"]}