heyspex 0.1.0

package/scripts/vault-id-lib.mjs

@@ -0,0 +1,173 @@
+/**
+ * Shared vault ID allocation (ESM) — mirrors spex-console/src/lib/vault-id.ts.
+ * Used by validate-vault-ids.mjs and vendor/heyspex-mcp.
+ *
+ * Family-first ([[HS-EPIC-DLE3]] / [[HS-MIL-KY1F]]): minted ids are
+ * `HS-<familyKey>-<TYPE>`. Occupancy detection is dual-read (it normalizes ids of
+ * EITHER ordering to the canonical family-first form via `parseSpecId`), so
+ * suffix-collision detection keeps working while the vault is mid-migration.
+ */
+
+import { parseSpecId, FILE_KEY_RE, fileKeyFromBasename, KNOWN_TYPE_LABELS } from '../vendor/heyspex-mcp/spec-id-lib.mjs';
+
+export const VAULT_ID_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+export const VAULT_ID_MIN_SUFFIX_LENGTH = 4;
+
+/** Per-file FILE KEY length (owner ruling 2026-07-10) — see spec-id-lib.mjs FILE_KEY_RE. */
+export const FILE_KEY_LENGTH = 4;
+export { FILE_KEY_RE, fileKeyFromBasename };
+
+// Legacy type-first id matchers. Retained for backward compatibility; new code
+// should parse ids via `parseSpecId` (dual-read) rather than these.
+export const TASK_ID_RE = /^HS-TASK-([A-Z0-9]{4,})$/;
+export const EPIC_ID_RE = /^HS-EPIC-(\d{4}|[A-Z0-9]{4,})$/;
+export const RESEARCH_ID_RE = /^HS-RES-(\d{3}|[A-Z0-9]{4,})$/;
+export const CAPTURE_ID_RE = /^HS-CAP-([A-Z0-9]{4,})$/;
+export const DIAGNOSE_ID_RE = /^HS-DIAG-([A-Z0-9]{4,})$/;
+
+// The type label each random-keyed kind mints. (Slug-only kinds — memory,
+// protocol, pillar, ADR — have no family key and are out of scope for the flip.)
+const KIND_TYPE_LABEL = {
+  task: 'TASK',
+  epic: 'EPIC',
+  research: 'RES',
+  capture: 'CAP',
+  diagnose: 'DIAG',
+};
+const TYPE_LABEL_KIND = {
+  TASK: 'task',
+  EPIC: 'epic',
+  RES: 'research',
+  CAP: 'capture',
+  DIAG: 'diagnose',
+};
+
+const BUCKETS = {
+  task: 'tasks',
+  epic: 'epics',
+  research: 'research',
+  capture: 'captures',
+  diagnose: 'diagnoses',
+};
+
+function randomSuffix(length, charset, randomUnit) {
+  let out = '';
+  for (let i = 0; i < length; i++) {
+    const idx = Math.floor(randomUnit() * charset.length);
+    out += charset[Math.min(idx, charset.length - 1)];
+  }
+  return out;
+}
+
+function capacity(charset, length) {
+  return charset.length ** length;
+}
+
+function suffixLengthForId(kind, id) {
+  const p = parseSpecId(id);
+  return p && p.typeLabel === KIND_TYPE_LABEL[kind] ? p.familyKey.length : null;
+}
+
+function countIdsAtSuffixLength(kind, occupied, length) {
+  let n = 0;
+  for (const id of occupied) {
+    if (suffixLengthForId(kind, id) === length) n++;
+  }
+  return n;
+}
+
+export function allocateRandomVaultId(kind, occupied, options = {}) {
+  const charset = options.charset ?? VAULT_ID_CHARSET;
+  const randomUnit = options.randomUnit ?? (() => Math.random());
+  let length = options.minLength ?? VAULT_ID_MIN_SUFFIX_LENGTH;
+  const typeLabel = KIND_TYPE_LABEL[kind];
+
+  while (true) {
+    const usedAtLength = countIdsAtSuffixLength(kind, occupied, length);
+    if (usedAtLength >= capacity(charset, length)) {
+      length++;
+      continue;
+    }
+    const remaining = capacity(charset, length) - usedAtLength;
+    const maxAttempts = Math.min(remaining, 10_000);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const suffix = randomSuffix(length, charset, randomUnit);
+      // A suffix equal to a type label would corrupt era detection (closed-set
+      // type-label position is the era discriminator) — never mint one.
+      if (KNOWN_TYPE_LABELS.has(suffix)) continue;
+      const id = `HS-${suffix}-${typeLabel}`; // family-first
+      // Compare against the canonical form so a suffix already taken in EITHER
+      // ordering still counts as occupied during the migration grace window.
+      if (!occupied.has(id)) return id;
+    }
+    length++;
+  }
+}
+
+/**
+ * Allocate a per-file FILE KEY unique against `occupied` (vault-wide): 4 chars,
+ * at least one letter (all-digit rejected). Auto-extends on exhaustion.
+ * Mirror: spex-console/src/lib/vault-id.ts `allocateFileKey`.
+ */
+export function allocateFileKey(occupied, options = {}) {
+  const charset = options.charset ?? VAULT_ID_CHARSET;
+  const randomUnit = options.randomUnit ?? (() => Math.random());
+  let length = options.minLength ?? FILE_KEY_LENGTH;
+
+  while (true) {
+    const maxAttempts = Math.min(capacity(charset, length), 10_000);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const key = randomSuffix(length, charset, randomUnit);
+      if (!FILE_KEY_RE.test(key)) continue; // all-digit — never minted
+      // Never mint a key equal to a type label — era detection keys on
+      // closed-set type-label position ([[HS-SJOT-AEP1-DIAG]]).
+      if (KNOWN_TYPE_LABELS.has(key)) continue;
+      if (!occupied.has(key)) return key;
+    }
+    length++;
+  }
+}
+
+/**
+ * Every occupied file key across loaded specs (frontmatter `file_id:` SSOT +
+ * basename token), for `allocateFileKey`'s vault-wide uniqueness check.
+ * PRECISE (file keys only) — cross-namespace mint safety ([[HS-SJOT-AEP1-DIAG]])
+ * is a call-site concern: union this with the occupied FAMILY keys before
+ * allocating, as vault.ts and spec-id-lib.mjs's mint helpers do.
+ */
+export function collectOccupiedFileKeysFromSpecs(specs) {
+  const occupied = new Set();
+  for (const s of specs) {
+    if (s.file_id && FILE_KEY_RE.test(String(s.file_id))) occupied.add(String(s.file_id));
+    if (s.fileId && FILE_KEY_RE.test(String(s.fileId))) occupied.add(String(s.fileId));
+    const fromBasename = s.basename ? fileKeyFromBasename(s.basename) : null;
+    if (fromBasename) occupied.add(fromBasename);
+  }
+  return occupied;
+}
+
+export function collectOccupiedIdsFromSpecs(specs) {
+  const tasks = new Set();
+  const epics = new Set();
+  const research = new Set();
+  const captures = new Set();
+  const diagnoses = new Set();
+  const sets = { tasks, epics, research, captures, diagnoses };
+
+  // Normalize an id or basename of EITHER ordering to its canonical family-first
+  // id and bucket it by type. Non-managed kinds (memory/protocol/…) parse to a
+  // type label not in TYPE_LABEL_KIND and are skipped.
+  const add = (value) => {
+    const p = parseSpecId(value);
+    if (!p) return;
+    const kind = TYPE_LABEL_KIND[p.typeLabel];
+    if (!kind) return;
+    sets[BUCKETS[kind]].add(`HS-${p.familyKey}-${p.typeLabel}`);
+  };
+
+  for (const s of specs) {
+    add(s.id);
+    add(s.basename);
+  }
+  return { tasks, epics, research, captures, diagnoses };
+}