@ctxr/skill-llm-wiki 1.0.2 → 1.1.0

package/scripts/lib/decision-log.mjs

@@ -16,9 +16,14 @@
 // queryable even after the op is reset.
 
 import {
+  appendFileSync,
+  closeSync,
   existsSync,
+  fstatSync,
   mkdirSync,
+  openSync,
   readFileSync,
+  readSync,
   renameSync,
   writeFileSync,
 } from "node:fs";
@@ -130,27 +135,112 @@ function emitEntry(entry) {
   return lines.join("\n");
 }
 
-// Append an entry atomically.
+// Append an entry.
+//
+// Hot path: at large-corpus scale (596 leaves → 189k pairwise
+// decisions observed) this is called once per decision. An earlier
+// implementation read the whole file, concatenated the new entry,
+// wrote to a temp, and renamed — O(file-size) per append. On a
+// 45 MB decisions.yaml that's ~22 MB of avg-read per call × 189k
+// calls ≈ 4 TB of I/O, which alone accounted for most of a 2h15m
+// build's wall-clock time.
+//
+// Durability guarantees:
+//
+//   - First call (file doesn't exist): writes header + first entry
+//     via temp+rename. The initial file materialises atomically —
+//     a crash during the first call leaves either no file or a
+//     well-formed single-entry file.
+//
+//   - Subsequent calls: best-effort `appendFileSync`. Each call is
+//     a single `write(2)` syscall of the serialised entry. In the
+//     common case the kernel writes the full buffer atomically,
+//     but this is NOT a formal durability contract for regular
+//     files the way temp+rename is:
+//
+//       * A crash mid-write can leave a torn trailing entry. On
+//         recovery the YAML parser will reject the truncated
+//         scalar; the audit log is recoverable by removing the
+//         last partial `- ...` block and re-running the op.
+//
+//       * Node's `writeSync`/`appendFileSync` MAY split a large
+//         buffer into multiple `write(2)` calls. Typical entry
+//         blocks here are ~200 bytes — well under typical
+//         single-write thresholds — but there is no portable
+//         small-write atomicity guarantee for regular files
+//         (POSIX's PIPE_BUF atomicity applies to pipes/FIFOs, not
+//         disk files).
+//
+//       * On Windows, `appendFileSync` has no equivalent of
+//         POSIX O_APPEND kernel serialisation under concurrent
+//         writers from multiple processes. This phase runs
+//         single-process though, so cross-process interleaving
+//         is not a concern in practice.
+//
+// The decision log is an audit trail, not a reproducibility
+// artefact — lost tail bytes on a crash are annoying but
+// recoverable, and the output tree's byte-reproducibility is
+// independent of this file's exact contents. If stronger
+// durability is needed for a specific use case, callers should
+// batch-flush to a temp file and rename on phase boundaries.
+//
+// Cost per append: O(entry-size), not O(file-size). ~200 µs vs
+// ~20 ms on a big log — a 100× speedup at scale.
 export function appendDecision(wikiRoot, entry) {
   validate(entry);
   const path = decisionLogPath(wikiRoot);
   mkdirSync(dirname(path), { recursive: true });
   const block = emitEntry(entry) + "\n";
-  let payload;
   if (!existsSync(path)) {
-    payload =
+    // First call: lay down the header atomically via temp+rename so
+    // a crash mid-creation doesn't leave an empty or orphan file.
+    const payload =
       "# skill-llm-wiki tiered-AI decision log (append-only)\n" +
       "version: 1\n" +
       "entries:\n" +
       block;
-  } else {
-    const existing = readFileSync(path, "utf8");
-    const prefix = existing.endsWith("\n") ? existing : existing + "\n";
-    payload = prefix + block;
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    writeFileSync(tmp, payload, "utf8");
+    renameSync(tmp, path);
+    return;
+  }
+  // Subsequent appends: O(entry-size) via POSIX append. Peek at
+  // the last byte first: if the existing file doesn't end in a
+  // newline (manual edit, prior torn-tail truncation, or a
+  // creative crash), appending directly would concatenate the new
+  // entry onto the previous line and produce invalid YAML. Prefix
+  // a newline in that case — a leading blank line inside the
+  // entries[] list is harmless and parses fine.
+  const needsLeadingNewline = !endsWithNewline(path);
+  appendFileSync(path, needsLeadingNewline ? "\n" + block : block, "utf8");
+}
+
+// Check the last byte of the decision log without reading the
+// whole file. Uses a small anchored read rather than `readFileSync`
+// so the hot append path still pays O(1) regardless of log size.
+// An unreadable file (ENOENT, EACCES, race window) is treated as
+// "already newline-terminated" so the caller doesn't double up on
+// leading newlines on a transient read error.
+function endsWithNewline(path) {
+  let fd;
+  try {
+    fd = openSync(path, "r");
+    const { size } = fstatSync(fd);
+    if (size === 0) return true; // empty file has no trailing content to collide
+    const buf = Buffer.alloc(1);
+    readSync(fd, buf, 0, 1, size - 1);
+    return buf[0] === 0x0a; // 0x0a == '\n'
+  } catch {
+    return true;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* best-effort */
+      }
+    }
   }
-  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
-  writeFileSync(tmp, payload, "utf8");
-  renameSync(tmp, path);
 }
 
 // Convenience helper for cluster-NEST outcomes. The convergence
@@ -164,14 +254,18 @@ export function appendDecision(wikiRoot, entry) {
 //
 //   op_id, operator="NEST"                — as-is
 //   sources                               — leaf ids in the cluster
-//   tier_used                             — 2 (every NEST decision
-//                                           touches Tier 2 either
-//                                           via propose_structure
-//                                           or nest_decision)
+//   tier_used                             — caller-supplied (default 2
+//                                           for legacy Tier-2-touching
+//                                           NEST paths; 0 under
+//                                           `--quality-mode deterministic`
+//                                           since no sub-agent is
+//                                           consulted)
 //   similarity                            — average_affinity
 //   confidence_band                       — one of:
 //                                           "tier2-proposed",
+//                                           "tier2-and-math",
 //                                           "math-gated",
+//                                           "deterministic-math",
 //                                           "empty-partition",
 //                                           "rejected-by-metric",
 //                                           "rejected-by-gate"
@@ -187,16 +281,28 @@ export function appendDecision(wikiRoot, entry) {
 // Coercion: average_affinity may be undefined for Tier-2-proposed
 // clusters; we coerce to 0 so the finite-number validator does
 // not reject the entry.
+//
+// tier_used default: pre-deterministic-mode every NEST decision
+// touched Tier 2 via propose_structure or nest_decision, so the
+// default of 2 was correct. Under `--quality-mode deterministic`
+// Tier 2 is never consulted for math candidates; callers on that
+// path pass `tier_used: 0` so the audit trail correctly reflects
+// the fact that no sub-agent was invoked. The default remains 2
+// for backward compatibility with every existing call site.
 export function appendNestDecision(wikiRoot, entry) {
   const similarity =
     Number.isFinite(entry.similarity)
       ? entry.similarity
       : (Number.isFinite(entry.average_affinity) ? entry.average_affinity : 0);
+  const tier_used =
+    typeof entry.tier_used === "number" && Number.isInteger(entry.tier_used)
+      ? entry.tier_used
+      : 2;
   appendDecision(wikiRoot, {
     op_id: entry.op_id,
     operator: "NEST",
     sources: Array.isArray(entry.sources) ? entry.sources : [],
-    tier_used: 2,
+    tier_used,
     similarity,
     confidence_band: entry.confidence_band ?? null,
     decision: entry.decision,

package/scripts/lib/heal.mjs

@@ -52,6 +52,11 @@ export const FINDING_ACTIONS = Object.freeze({
   "DANGLING-LINK": "fix",
   "DANGLING-OVERLAY": "fix",
 
+  // X.11 root-leaf containment invariant — `fix` runs Phase 4.4.5
+  // root-containment to move outlier leaves into per-slug
+  // subcategories:
+  "LEAF-AT-WIKI-ROOT": "fix",
+
   // Size cap is a warning surface only:
   "SIZE-CAP": "none",
 });

package/scripts/lib/intent.mjs

@@ -33,6 +33,16 @@
 //   INT-12   ambiguity reached interactive resolution in a non-TTY
 //            context (emitted by cli.mjs when NonInteractiveError fires)
 //   INT-13   unknown --quality-mode value
+//   INT-14   invalid --fanout-target value (must be a positive integer
+//            in [FANOUT_TARGET_MIN, FANOUT_TARGET_MAX])
+//   INT-14a  --fanout-target used on a subcommand other than build /
+//            rebuild (balance enforcement is build/rebuild-only)
+//   INT-15   invalid --max-depth value (must be a positive integer in
+//            [MAX_DEPTH_MIN, MAX_DEPTH_MAX])
+//   INT-15a  --max-depth used on a subcommand other than build /
+//            rebuild (balance enforcement is build/rebuild-only)
+//   INT-16a  --soft-dag-parents used on a subcommand other than build /
+//            rebuild (soft-DAG synthesis is build/rebuild-only)
 //
 // Plan shape (status === "ok"):
 //   {
@@ -50,7 +60,11 @@
 
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  DEFAULT_COLLISION_POLICY,
+  VALID_COLLISION_POLICIES,
+} from "./join-constants.mjs";
 import {
   defaultSiblingPath,
   hasPrivateGit,
@@ -64,14 +78,53 @@ export const VALID_LAYOUT_MODES = Object.freeze(["sibling", "in-place", "hosted"
 // rejects typos BEFORE the orchestrator runs, avoiding expensive
 // rollbacks on a trivial flag error. Must stay in sync with
 // tiered.mjs:QUALITY_MODES — the unit test
-// tests/unit/intent-resolve.test.mjs:valid-quality-modes verifies
-// this.
+// tests/unit/intent-resolve.test.mjs::"VALID_QUALITY_MODES is in
+// sync with tiered.mjs::QUALITY_MODES" pins that both lists contain
+// the same modes in the same order so a future drift fails loud
+// instead of silently letting one layer accept a mode the other
+// rejects.
 export const VALID_QUALITY_MODES = Object.freeze([
   "tiered-fast",
   "claude-first",
-  "tier0-only",
+  "deterministic",
 ]);
 
+// Range bounds for the balance-enforcement flags (`--fanout-target`,
+// `--max-depth`). Exported so tests and the balance module can
+// reference them directly without re-stating the literal values.
+//
+// The ranges cover the band where a post-convergence rebalance pass
+// has a meaningful effect. Fanout 1 is degenerate (every split forces
+// single-child chains); 100+ is effectively unbounded for any real
+// corpus (the cluster detector caps individual clusters at 8).
+// Max depth starts at 1 — the "no nesting"/flat-layout case is out
+// of this flag's scope; balance's purpose is to flatten OVERDEEP
+// branches, not to undo nesting the pipeline already decided to
+// create, and the regular NEST operator handles the no-nesting
+// starting condition anyway. 11+ max-depth is deeper than any
+// hand-authored corpus anyone has reported, so the flag becomes a
+// silent no-op above that. Out-of-range values are treated as user
+// errors at intent time so the flag is never a silent no-op at
+// runtime.
+export const FANOUT_TARGET_MIN = 2;
+export const FANOUT_TARGET_MAX = 100;
+export const MAX_DEPTH_MIN = 1;
+export const MAX_DEPTH_MAX = 10;
+
+// Parse + validate an integer-in-range flag value. Returns a short
+// human-readable reason string when the value is invalid (for use in
+// the ambiguity error), or null when valid. Factored out so INT-14
+// and INT-15 share one implementation.
+function invalidIntInRange(raw, min, max) {
+  if (typeof raw !== "string" || !/^\d+$/.test(raw)) {
+    return `expected a positive integer, got "${raw}"`;
+  }
+  const n = Number.parseInt(raw, 10);
+  if (n < min) return `${n} is below the minimum ${min}`;
+  if (n > max) return `${n} is above the maximum ${max}`;
+  return null;
+}
+
 export function ok(plan) {
   return { status: "ok", plan };
 }
@@ -265,6 +318,153 @@ export function resolveIntent(ctx) {
       "--quality-mode",
     );
   }
+  // Validate `LLM_WIKI_QUALITY_MODE` here too, but only for
+  // subcommands that actually consult runtime quality-mode
+  // resolution (build / extend / rebuild / fix / join all call
+  // through `resolveQualityMode` in the orchestrator). Commands
+  // like `rollback`, `validate`, `init`, `heal` never touch
+  // tiered.mjs, so blocking them on a stale env var — especially
+  // `rollback`, which is a recovery path — would make a trivial
+  // shell-config typo catastrophic. Without this gate, a stale
+  // `LLM_WIKI_QUALITY_MODE=tier0-only` would lock the user out of
+  // recovering the wiki they were trying to rollback.
+  //
+  // Symmetric with the flag path — same code, same suggestions,
+  // same exit-2 ambiguous shape — for the subcommands where the
+  // env var is actually consumed.
+  const QUALITY_MODE_CONSUMERS = new Set([
+    "build",
+    "extend",
+    "rebuild",
+    "fix",
+    "join",
+  ]);
+  const envQualityMode = process.env.LLM_WIKI_QUALITY_MODE;
+  if (
+    QUALITY_MODE_CONSUMERS.has(subcommand) &&
+    !f.quality_mode &&
+    envQualityMode &&
+    !VALID_QUALITY_MODES.includes(envQualityMode)
+  ) {
+    return ambiguous(
+      "INT-13",
+      `unknown LLM_WIKI_QUALITY_MODE value "${envQualityMode}"`,
+      VALID_QUALITY_MODES.map((m) => ({
+        description: `use ${m} quality mode`,
+        flag: `--quality-mode ${m}`,
+      })),
+      "LLM_WIKI_QUALITY_MODE",
+    );
+  }
+  // Balance-enforcement flags are build/rebuild-only. The CLI parser
+  // accepts them globally (to produce a uniform flag table), so intent
+  // has to gate the subcommand explicitly — otherwise `fix`, `join`,
+  // `rollback` etc. would silently carry them through to the
+  // orchestrator, where the hook would fire and apply unexpected
+  // structural mutations outside the documented surface.
+  const BALANCE_FLAG_SUBCOMMANDS = new Set(["build", "rebuild"]);
+  // Subcommands that operate on an existing wiki (take a wiki path).
+  // For these, the natural remediation is `rebuild` (which walks an
+  // existing wiki). For source-operating subcommands with no wiki
+  // path, `build` is the right suggestion. `build` itself isn't in
+  // either set since it can't reach this branch.
+  const WIKI_OPERATING = new Set(["fix", "validate", "extend", "rebuild", "rollback", "join"]);
+  const suggestedSub = WIKI_OPERATING.has(subcommand) ? "rebuild" : "build";
+  if (f.fanout_target !== undefined) {
+    if (!BALANCE_FLAG_SUBCOMMANDS.has(subcommand)) {
+      return ambiguous(
+        "INT-14a",
+        `--fanout-target is only supported on build / rebuild (got "${subcommand}")`,
+        [
+          {
+            description: "drop --fanout-target",
+            flag: "(remove --fanout-target)",
+          },
+          {
+            description: `run on a ${suggestedSub} instead`,
+            flag: `${suggestedSub} ... --fanout-target <N>`,
+          },
+        ],
+        "--fanout-target",
+      );
+    }
+    const bad = invalidIntInRange(
+      f.fanout_target,
+      FANOUT_TARGET_MIN,
+      FANOUT_TARGET_MAX,
+    );
+    if (bad) {
+      return ambiguous(
+        "INT-14",
+        `invalid --fanout-target "${f.fanout_target}" (${bad})`,
+        [
+          {
+            description: `use a positive integer in [${FANOUT_TARGET_MIN}, ${FANOUT_TARGET_MAX}]`,
+            flag: "--fanout-target <integer>",
+          },
+        ],
+        "--fanout-target",
+      );
+    }
+  }
+  if (f.max_depth !== undefined) {
+    if (!BALANCE_FLAG_SUBCOMMANDS.has(subcommand)) {
+      return ambiguous(
+        "INT-15a",
+        `--max-depth is only supported on build / rebuild (got "${subcommand}")`,
+        [
+          {
+            description: "drop --max-depth",
+            flag: "(remove --max-depth)",
+          },
+          {
+            description: `run on a ${suggestedSub} instead`,
+            flag: `${suggestedSub} ... --max-depth <D>`,
+          },
+        ],
+        "--max-depth",
+      );
+    }
+    const bad = invalidIntInRange(f.max_depth, MAX_DEPTH_MIN, MAX_DEPTH_MAX);
+    if (bad) {
+      return ambiguous(
+        "INT-15",
+        `invalid --max-depth "${f.max_depth}" (${bad})`,
+        [
+          {
+            description: `use a positive integer in [${MAX_DEPTH_MIN}, ${MAX_DEPTH_MAX}]`,
+            flag: "--max-depth <integer>",
+          },
+        ],
+        "--max-depth",
+      );
+    }
+  }
+  // --soft-dag-parents shares balance's subcommand scope (build /
+  // rebuild only). Same defense-in-depth as INT-14a / INT-15a: the
+  // CLI parser accepts the flag globally, so intent has to gate
+  // explicitly — otherwise `fix`, `join`, `rollback` etc. would
+  // silently carry the flag through to the orchestrator and rewrite
+  // parents[] on every leaf, outside the documented surface.
+  if (f.soft_dag_parents === true) {
+    if (!BALANCE_FLAG_SUBCOMMANDS.has(subcommand)) {
+      return ambiguous(
+        "INT-16a",
+        `--soft-dag-parents is only supported on build / rebuild (got "${subcommand}")`,
+        [
+          {
+            description: "drop --soft-dag-parents",
+            flag: "(remove --soft-dag-parents)",
+          },
+          {
+            description: `run on a ${suggestedSub} instead`,
+            flag: `${suggestedSub} ... --soft-dag-parents`,
+          },
+        ],
+        "--soft-dag-parents",
+      );
+    }
+  }
   if (f.layout_mode === "in-place" && f.target) {
     return ambiguous(
       "INT-09a",
@@ -324,6 +524,172 @@ export function resolveIntent(ctx) {
     });
   }
 
+  // ─── Join: N >= 2 existing wikis into a unified output ───────────
+  //
+  // Positional shape: `join <wiki-a> <wiki-b> [<wiki-c>...]`. The
+  // `--target` flag is REQUIRED (where to write the unified output)
+  // — join is inherently hosted-mode because the output belongs
+  // neither next to source A nor source B. Each source must exist
+  // and be a skill-managed wiki (have `.llmwiki/git`). Target must
+  // not already exist (or must be empty): the CLI materialises into
+  // a fresh tree so the source wikis stay strictly read-only.
+  //
+  // `--id-collision` selects the cross-source id-collision policy
+  // (`namespace` / `merge` / `ask`); defaults to `namespace`. The
+  // value is validated here against the same canonical list
+  // scripts/lib/join.mjs exports, so a typo fails at the intent
+  // layer with structured INT-17 rather than burning a pre-op
+  // snapshot and rolling back.
+  if (subcommand === "join") {
+    if (args.length < 2) {
+      return ambiguous(
+        "INT-06",
+        `join requires at least 2 <wiki-path> positionals (got ${args.length})`,
+        [
+          {
+            description: "specify two or more source wikis",
+            flag: "join <wiki-a> <wiki-b> [<wiki-c>...]",
+          },
+        ],
+        "positional wiki paths",
+      );
+    }
+    const sources = args.map((a) => absolute(cwd, a));
+    for (const s of sources) {
+      if (!existsSync(s)) {
+        return ambiguous(
+          "INT-06",
+          `join: source wiki ${s} does not exist`,
+          [
+            {
+              description: "point at an existing skill-managed wiki",
+              flag: `join <existing-wiki> <existing-wiki>`,
+            },
+          ],
+          "each positional must exist",
+        );
+      }
+      if (!hasPrivateGit(s)) {
+        return ambiguous(
+          "INT-06",
+          `join: ${s} is not a skill-managed wiki (no .llmwiki/git)`,
+          [
+            {
+              description: "build each source first",
+              flag: `build ${s} --layout-mode in-place`,
+            },
+          ],
+          "each source must be a managed wiki",
+        );
+      }
+    }
+    if (!f.target) {
+      return ambiguous(
+        "INT-09b",
+        `join requires --target <path> (join output is always hosted; see guide/operations/ingest/join.md)`,
+        [
+          {
+            description: "set an explicit output path",
+            flag: "--target <path/for/unified/wiki>",
+          },
+        ],
+        "--target",
+      );
+    }
+    const target = absolute(cwd, f.target);
+    // Source immutability guard: --target must not equal, nest
+    // under, or contain any source wiki. Join writes to target;
+    // any path relationship between target and a source means the
+    // write would either clobber source files or place output
+    // inside the source tree (violating the documented "sources
+    // are read-only" guarantee). Detect both subpath directions
+    // with `path.relative` and reject with INT-18 before the
+    // pre-op snapshot fires. This check runs BEFORE the
+    // empty-target check — a target that equals or contains a
+    // source would otherwise be (correctly) flagged as non-empty
+    // under INT-01, masking the more specific semantic problem.
+    for (const s of sources) {
+      const relTargetFromSource = relative(s, target);
+      const relSourceFromTarget = relative(target, s);
+      const targetUnderSource =
+        relTargetFromSource === "" ||
+        (!relTargetFromSource.startsWith("..") &&
+          !isAbsolute(relTargetFromSource));
+      const sourceUnderTarget =
+        relSourceFromTarget !== "" &&
+        !relSourceFromTarget.startsWith("..") &&
+        !isAbsolute(relSourceFromTarget);
+      if (targetUnderSource || sourceUnderTarget) {
+        return ambiguous(
+          "INT-18",
+          `join: --target ${target} must not equal, nest under, or contain any source wiki (conflicts with ${s})`,
+          [
+            {
+              description:
+                "pick a target path outside every source wiki tree",
+              flag: "--target <path-outside-sources>",
+            },
+          ],
+          "--target must not overlap sources",
+        );
+      }
+    }
+    if (existsSync(target)) {
+      // Allow an empty directory but nothing else — the target must
+      // be safe to materialise into without clobbering user data.
+      let entries;
+      try {
+        entries = readdirSync(target);
+      } catch {
+        entries = null;
+      }
+      if (!entries || entries.length > 0) {
+        return ambiguous(
+          "INT-01",
+          `join: --target path ${target} already exists and is not empty`,
+          [
+            {
+              description: "pick a fresh output path",
+              flag: "--target <new-path>",
+            },
+          ],
+          "--target must be empty or new",
+        );
+      }
+    }
+    // Share VALID_COLLISION_POLICIES with `join.mjs` — the single
+    // canonical list. A local copy here risked silent drift if the
+    // set gained or lost a policy; importing keeps the intent
+    // validator and the runtime in lockstep.
+    const policy = f.id_collision || DEFAULT_COLLISION_POLICY;
+    if (!VALID_COLLISION_POLICIES.includes(policy)) {
+      return ambiguous(
+        "INT-17",
+        `unknown --id-collision value "${policy}"`,
+        VALID_COLLISION_POLICIES.map((p) => ({
+          description: `use ${p} policy`,
+          flag: `--id-collision ${p}`,
+        })),
+        "--id-collision",
+      );
+    }
+    return ok({
+      operation: "join",
+      layout_mode: "hosted",
+      source: null,
+      sources,
+      target,
+      is_new_wiki: true,
+      flags: {
+        accept_dirty: f.accept_dirty === true,
+        no_prompt: f.no_prompt === true,
+        json_errors: f.json_errors === true || f.json === true,
+        id_collision: policy,
+        quality_mode: f.quality_mode,
+      },
+    });
+  }
+
   // ─── Rebuild / fix: the positional IS the wiki, not a source ──────
   // These operations read frontmatter from an existing wiki and write
   // back in place. There is no separate source — the wiki is both.

package/scripts/lib/join-constants.mjs

@@ -0,0 +1,22 @@
+// join-constants.mjs — the minimal shared constants between the
+// runtime pipeline (`join.mjs`) and the intent layer
+// (`intent.mjs`).
+//
+// Kept in its own file so that importing the policy allow-list
+// at intent time does NOT drag in the full join pipeline module
+// (ingest + convergence + indices + validation + every transitive
+// dependency). CLI paths that never run a join — build, rebuild,
+// fix, validate, rollback, init, heal, where — would otherwise
+// pay the cold-start cost of loading `join.mjs` and its
+// dependency graph on every invocation just to resolve the
+// `--id-collision` flag. Keeping this module dependency-light
+// (zero imports, plain string constants) keeps every non-join
+// CLI startup path fast.
+
+export const VALID_COLLISION_POLICIES = Object.freeze([
+  "namespace",
+  "merge",
+  "ask",
+]);
+
+export const DEFAULT_COLLISION_POLICY = "namespace";