@kontourai/flow-agents 3.0.0 → 3.1.0

package/kits/builder/skills/design-probe/SKILL.md

@@ -82,6 +82,43 @@ Maintain a compact running record in the active artifact or conversation when no
 
 When workflow artifacts exist, update the appropriate session, handoff, Probe record, or planning artifact according to the local artifact contract. Do not invent a project-specific storage format when the repository already defines one.
 
+## Docs-Write: Two-Delta Emission
+
+Per `context/contracts/probe-docs-write-contract.md`, when a `decisions` entry above is a **decision subject** — a durable, reusable answer to a named domain question, not an implementation detail or transient planning choice — emit two deltas into durable docs in the same motion, before moving to the next branch:
+
+1. **Vocabulary delta**: the subject noun must exist as a `CONTEXT.md` glossary term. If absent, coin it first (a tight one- or two-sentence `### <Term>` entry); if present, refine the definition when the crystallized decision changes what it says (e.g. an "open" pointer becoming a stated answer).
+2. **Decision delta**: consult `docs/decisions/index.md` and propose revise-vs-create against the existing topic slugs (this includes any `needs-decision` stub already naming the subject); revise the existing topic file in place, or create `docs/decisions/<slug>.md` per `context/contracts/decision-registry-contract.md`. Run `npm run gen:decisions-index && npm run check:decisions` after writing.
+3. **Transcript provenance**: add a `session-archive` evidence ref pointing at this Probe's own session artifact (the live `.kontourai/flow-agents/<slug>/...` path — it does not need to be archived yet).
+
+Example — coining a new term and creating its topic file:
+
+```markdown
+### Retry Budget
+
+The maximum number of automatic retries a workflow step may attempt before routing back to the user. Configured per Flow Definition step, not globally.
+```
+
+```markdown
+---
+status: current
+subject: Retry budget
+decided: 2026-07-03
+evidence:
+  - kind: session-archive
+    ref: .kontourai/flow-agents/<slug>/<slug>--design-probe.md
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/<n>
+---
+
+# Retry budget
+
+Each Flow Definition step declares its own retry budget; there is no global default. Set during design-probe alignment on <n>.
+```
+
+Example — revising a `needs-decision` stub seeded by the ADR-freeze cutover (issue #314) once its frozen ADR's decision is confirmed still current: flip `status: needs-decision` to `current`, set `decided` to today, keep the existing `adr` evidence ref, and append the `session-archive` ref for this Probe session plus a `pr` ref once one exists. See `context/contracts/probe-docs-write-contract.md` § Worked Example for the full step-by-step.
+
+Do not write a numbered ADR — `docs/adr/` is frozen history (`docs/adr/README.md`); every decision delta targets the topic-keyed registry.
+
 ## Stop Conditions
 
 Stop probing when one of these is true:

package/kits/builder/skills/pickup-probe/SKILL.md

@@ -115,15 +115,15 @@ When the gate fails, record `--status fail` with `--expectation pickup-probe-rea
 
 
 
-## Docs And ADR Policy
+## Docs-Write Policy: Two-Delta Emission
 
-`pickup-probe` may identify durable terminology and decision gaps, but it must keep documentation changes narrow:
+`pickup-probe` may identify durable terminology and decision gaps, but it must keep documentation changes narrow. Per `context/contracts/probe-docs-write-contract.md`, a **decision subject** crystallizing during pickup probing (a durable, reusable answer to a named domain question — not an implementation detail or transient planning choice) gets both deltas in the same motion:
 
-- Update `CONTEXT.md` inline only for glossary-style durable terminology decisions, using tight one- or two-sentence definitions and `_Avoid_` terms when useful. Keep implementation details out of `CONTEXT.md`.
+- Update `CONTEXT.md` inline only for glossary-style durable terminology decisions, using tight one- or two-sentence definitions and `_Avoid_` terms when useful. Keep implementation details out of `CONTEXT.md`. Coin the subject term first if it is not already a glossary entry — vocabulary is the decision registry's topic namespace (`context/contracts/decision-registry-contract.md` § Slug rules) — or refine the existing entry when a decision changes what it says.
 - If a `CONTEXT-MAP.md` exists, update the relevant context instead of assuming the root glossary owns the term.
 - Create a lazy context file only when a resolved term or workflow concept has no existing home.
 - Do not create context files for transient planning notes, open questions, or provider snapshots.
-- Propose or create ADRs sparingly, only when all three are true: the decision is hard to reverse, surprising without context, and the result of a real trade-off.
+- Record a decision delta at `docs/decisions/<slug>.md`: consult `docs/decisions/index.md` first and propose revise-vs-create (an existing topic file, including a `needs-decision` stub, is revised in place; only an uncovered subject gets a new file), then run `npm run gen:decisions-index && npm run check:decisions`. Link this Probe's own session artifact as a `session-archive` evidence ref (transcript provenance). Never propose or create a numbered ADR — `docs/adr/` is frozen history; decisions go into the topic-keyed registry.
 - Prefer workflow artifacts for pickup decisions, unresolved questions, accepted gaps, and route reasons until the work is accepted.
 
 ## Handoff To Plan Work

package/kits/knowledge/adapters/default-store/index.js

@@ -16,6 +16,18 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
 
+// Record-identity resolution layer (short-id prefix + slug aliases, issue #339).
+// Single-sourced in the shared codec so both bundled adapters resolve
+// identically; the rest of this adapter keeps its own zero-import helpers.
+import {
+  resolveRecordId,
+  normalizeAliases,
+  emptyAliasIndex,
+  loadAliasIndex,
+  saveAliasIndex,
+  registerAliases,
+} from "../shared/codec.js";
+
 // ---------------------------------------------------------------------------
 // Error helpers
 // ---------------------------------------------------------------------------
@@ -340,6 +352,7 @@ export class DefaultKnowledgeStore {
     this._root = path.resolve(storeRoot);
     this._recordsDir = path.join(this._root, "records");
     this._graphPath = path.join(this._root, "graph-index.json");
+    this._aliasPath = path.join(this._root, "alias-index.json");
     fs.mkdirSync(this._recordsDir, { recursive: true });
   }
 
@@ -351,6 +364,35 @@ export class DefaultKnowledgeStore {
     return path.join(this._recordsDir, `${id}.md`);
   }
 
+  // -- Record-identity resolution (short-id prefix + slug alias, issue #339) --
+
+  /** Does a record file exist for this exact full id? */
+  _idExists(id) {
+    return fs.existsSync(this._recordPath(id));
+  }
+
+  /** All full record ids, derived cheaply from the records/ directory. */
+  _listIds() {
+    if (!fs.existsSync(this._recordsDir)) return [];
+    return fs.readdirSync(this._recordsDir)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => f.slice(0, -3));
+  }
+
+  /**
+   * Resolve a query token (exact id, slug alias, or unambiguous id prefix) to a
+   * single full record id, or null when it resolves to nothing. Throws
+   * AMBIGUOUS_ID when a prefix matches more than one record.
+   */
+  _resolveId(input) {
+    const aliasIndex = loadAliasIndex(this._aliasPath);
+    return resolveRecordId(input, {
+      idExists: (rid) => this._idExists(rid),
+      listIds: () => this._listIds(),
+      bySlug: aliasIndex.by_slug,
+    });
+  }
+
   _readRecord(id) {
     const p = this._recordPath(id);
     if (!fs.existsSync(p)) return null;
@@ -393,6 +435,15 @@ export class DefaultKnowledgeStore {
     const id = input.id || randomUUID();
     const now = this._now();
 
+    // Validate slug aliases (issue #339) and reserve them in the alias map
+    // BEFORE any write, so a SLUG_CONFLICT aborts create without a partial record.
+    const aliases = normalizeAliases(input.aliases);
+    let aliasIndex = null;
+    if (aliases.length) {
+      aliasIndex = loadAliasIndex(this._aliasPath);
+      registerAliases(aliasIndex, id, aliases);
+    }
+
     // Merge explicit links + wikilinks from body
     const explicitLinks = input.links || [];
     const wikilinks = extractWikilinks(input.body || "");
@@ -404,6 +455,7 @@ export class DefaultKnowledgeStore {
       title: input.title,
       category: input.category,
       tags: input.tags || [],
+      ...(aliases.length ? { aliases } : {}),
       status: "active",
       created_at: now,
       updated_at: now,
@@ -425,6 +477,9 @@ export class DefaultKnowledgeStore {
     addLinksToGraph(graph, id, links);
     saveGraph(this._graphPath, graph);
 
+    // Persist the alias map only after the record is on disk.
+    if (aliasIndex) saveAliasIndex(this._aliasPath, aliasIndex);
+
     return id;
   }
 
@@ -439,7 +494,7 @@ export class DefaultKnowledgeStore {
     const record = this._readRecord(id);
     if (!record) throw notFoundError(id);
 
-    const mutableKeys = ["title", "body", "category", "tags", "links"];
+    const mutableKeys = ["title", "body", "category", "tags", "links", "aliases"];
     const supplied = mutableKeys.filter((k) => fields[k] !== undefined);
     if (supplied.length === 0)
       throw missingEvidenceError("update: at least one mutable field must be supplied");
@@ -449,6 +504,18 @@ export class DefaultKnowledgeStore {
 
     const now = this._now();
 
+    // Slug aliases are append-only: supplied aliases are UNIONED with existing
+    // ones so a previously issued slug keeps resolving after a restructure (R3).
+    let mergedAliases = Array.isArray(record.aliases) ? record.aliases.slice() : [];
+    let aliasIndex = null;
+    if (fields.aliases !== undefined) {
+      const incoming = normalizeAliases(fields.aliases);
+      const seen = new Set(mergedAliases);
+      for (const s of incoming) if (!seen.has(s)) { seen.add(s); mergedAliases.push(s); }
+      aliasIndex = loadAliasIndex(this._aliasPath);
+      registerAliases(aliasIndex, id, mergedAliases);
+    }
+
     // Merge links if updated
     let newLinks = record.links || [];
     if (fields.links !== undefined) {
@@ -465,6 +532,7 @@ export class DefaultKnowledgeStore {
       ...(fields.body !== undefined ? { body: fields.body } : {}),
       ...(fields.category !== undefined ? { category: fields.category } : {}),
       ...(fields.tags !== undefined ? { tags: fields.tags } : {}),
+      ...(mergedAliases.length ? { aliases: mergedAliases } : {}),
       links: newLinks,
       updated_at: now,
       mutation_log: [
@@ -486,6 +554,8 @@ export class DefaultKnowledgeStore {
     saveGraph(this._graphPath, graph);
 
     this._writeRecord(updated);
+
+    if (aliasIndex) saveAliasIndex(this._aliasPath, aliasIndex);
   }
 
   // -------------------------------------------------------------------------
@@ -843,7 +913,12 @@ export class DefaultKnowledgeStore {
   // -------------------------------------------------------------------------
 
   async get(id) {
-    return this._readRecord(id);
+    // Accept an exact id, a slug alias, or an unambiguous id prefix (issue #339).
+    // Unresolved → null (unchanged missing-record semantics); ambiguous prefix
+    // → throws AMBIGUOUS_ID.
+    const resolvedId = this._resolveId(id);
+    if (!resolvedId) return null;
+    return this._readRecord(resolvedId);
   }
 
   // -------------------------------------------------------------------------
@@ -851,10 +926,13 @@ export class DefaultKnowledgeStore {
   // -------------------------------------------------------------------------
 
   async getLinks(id) {
+    // Resolve prefix/slug to a full id; fall back to the raw token when it
+    // resolves to nothing so unknown ids still return empty arrays (not throw).
+    const key = this._resolveId(id) || id;
     const graph = loadGraph(this._graphPath);
     return {
-      forward: (graph.forward[id] || []).map((l) => ({ ...l })),
-      reverse: (graph.reverse[id] || []).map((l) => ({ ...l })),
+      forward: (graph.forward[key] || []).map((l) => ({ ...l })),
+      reverse: (graph.reverse[key] || []).map((l) => ({ ...l })),
     };
   }
 
@@ -911,6 +989,16 @@ export class DefaultKnowledgeStore {
     const links = Object.values(rebuilt.forward).reduce((n, arr) => n + arr.length, 0);
     const changed = canonicalGraph(loadGraph(this._graphPath)) !== canonicalGraph(rebuilt);
     saveGraph(this._graphPath, rebuilt);
+
+    // The alias map is likewise derived from records' `aliases` — rebuild it so
+    // a lost/hand-edited alias-index.json recovers on the same recovery path.
+    const rebuiltAliases = emptyAliasIndex();
+    for (const record of records) {
+      const slugs = normalizeAliases(record.aliases);
+      if (slugs.length) registerAliases(rebuiltAliases, record.id, slugs);
+    }
+    saveAliasIndex(this._aliasPath, rebuiltAliases);
+
     return {
       records: records.length,
       links,

package/kits/knowledge/adapters/obsidian-store/index.js

@@ -57,6 +57,12 @@ import {
   VALID_TYPES,
   VALID_STATUS_TRANSITIONS,
   validateCategory,
+  // Record-identity resolution layer (short-id prefix + slug aliases, issue #339)
+  resolveRecordId,
+  normalizeAliases,
+  loadAliasIndex,
+  saveAliasIndex,
+  registerAliases,
 } from "../shared/codec.js";
 
 // ---------------------------------------------------------------------------
@@ -94,9 +100,33 @@ export class ObsidianKnowledgeStore {
     this._graphPath = path.join(this._root, "graph-index.json");
     // Path index (internal): { by_id: { id: { path, archived } }, by_path: { relPath: id } }
     this._pathIndexPath = path.join(this._root, ".graph-index.json");
+    // Alias map (issue #339): { schema_version, by_slug: { slug: id } }. Keyed by
+    // full id, never by file path, so slugs survive the folder moves this adapter
+    // performs on recategorize/archive.
+    this._aliasPath = path.join(this._root, "alias-index.json");
     fs.mkdirSync(this._root, { recursive: true });
   }
 
+  // -------------------------------------------------------------------------
+  // Record-identity resolution (short-id prefix + slug alias, issue #339)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Resolve a query token (exact id, slug alias, or unambiguous id prefix) to a
+   * single full record id, or null. Throws AMBIGUOUS_ID on a >1-match prefix.
+   * Ids and aliases are read from the persisted indexes, so resolution is
+   * unaffected by where a record's file currently lives.
+   */
+  _resolveId(input, pathIndex, aliasIndex) {
+    pathIndex = pathIndex || this._loadPathIndex();
+    aliasIndex = aliasIndex || loadAliasIndex(this._aliasPath);
+    return resolveRecordId(input, {
+      idExists: (rid) => Boolean(pathIndex.by_id[rid]),
+      listIds: () => Object.keys(pathIndex.by_id),
+      bySlug: aliasIndex.by_slug,
+    });
+  }
+
   // -------------------------------------------------------------------------
   // Path / slug helpers
   // -------------------------------------------------------------------------
@@ -505,6 +535,15 @@ export class ObsidianKnowledgeStore {
     const id = input.id || randomUUID();
     const now = this._now();
 
+    // Validate + reserve slug aliases before any write (issue #339); a
+    // SLUG_CONFLICT aborts create without leaving a partial note behind.
+    const aliases = normalizeAliases(input.aliases);
+    let aliasIndex = null;
+    if (aliases.length) {
+      aliasIndex = loadAliasIndex(this._aliasPath);
+      registerAliases(aliasIndex, id, aliases);
+    }
+
     const explicitLinks = input.links || [];
     const wikilinks = extractWikilinks(input.body || "");
     const links = mergeLinks(explicitLinks, wikilinks);
@@ -515,6 +554,7 @@ export class ObsidianKnowledgeStore {
       title: input.title,
       category: input.category,
       tags: input.tags || [],
+      ...(aliases.length ? { aliases } : {}),
       status: "active",
       created_at: now,
       updated_at: now,
@@ -535,6 +575,8 @@ export class ObsidianKnowledgeStore {
     addLinksToGraph(graph, id, links);
     saveGraph(this._graphPath, graph);
 
+    if (aliasIndex) saveAliasIndex(this._aliasPath, aliasIndex);
+
     return id;
   }
 
@@ -550,7 +592,7 @@ export class ObsidianKnowledgeStore {
     const record = this._readRecord(id, pathIndex);
     if (!record) throw notFoundError(id);
 
-    const mutableKeys = ["title", "body", "category", "tags", "links"];
+    const mutableKeys = ["title", "body", "category", "tags", "links", "aliases"];
     const supplied = mutableKeys.filter((k) => fields[k] !== undefined);
     if (supplied.length === 0)
       throw missingEvidenceError("update: at least one mutable field must be supplied");
@@ -560,6 +602,18 @@ export class ObsidianKnowledgeStore {
 
     const now = this._now();
 
+    // Slug aliases are append-only: union supplied aliases with existing ones so
+    // a previously issued slug keeps resolving after the file relocates (R3).
+    let mergedAliases = Array.isArray(record.aliases) ? record.aliases.slice() : [];
+    let aliasIndex = null;
+    if (fields.aliases !== undefined) {
+      const incoming = normalizeAliases(fields.aliases);
+      const seen = new Set(mergedAliases);
+      for (const s of incoming) if (!seen.has(s)) { seen.add(s); mergedAliases.push(s); }
+      aliasIndex = loadAliasIndex(this._aliasPath);
+      registerAliases(aliasIndex, id, mergedAliases);
+    }
+
     let newLinks = record.links || [];
     if (fields.links !== undefined) {
       const wikilinks = extractWikilinks(fields.body !== undefined ? fields.body : record.body);
@@ -575,6 +629,7 @@ export class ObsidianKnowledgeStore {
       ...(fields.body !== undefined ? { body: fields.body } : {}),
       ...(fields.category !== undefined ? { category: fields.category } : {}),
       ...(fields.tags !== undefined ? { tags: fields.tags } : {}),
+      ...(mergedAliases.length ? { aliases: mergedAliases } : {}),
       links: newLinks,
       updated_at: now,
       mutation_log: [
@@ -596,6 +651,8 @@ export class ObsidianKnowledgeStore {
 
     this._writeRecord(updated, pathIndex);
     this._savePathIndex(pathIndex);
+
+    if (aliasIndex) saveAliasIndex(this._aliasPath, aliasIndex);
   }
 
   // -------------------------------------------------------------------------
@@ -956,7 +1013,12 @@ export class ObsidianKnowledgeStore {
   // -------------------------------------------------------------------------
 
   async get(id) {
-    return this._readRecord(id);
+    // Accept an exact id, slug alias, or unambiguous id prefix (issue #339).
+    // Unresolved → null; ambiguous prefix → throws AMBIGUOUS_ID.
+    const pathIndex = this._loadPathIndex();
+    const resolvedId = this._resolveId(id, pathIndex);
+    if (!resolvedId) return null;
+    return this._readRecord(resolvedId, pathIndex);
   }
 
   // -------------------------------------------------------------------------
@@ -964,10 +1026,13 @@ export class ObsidianKnowledgeStore {
   // -------------------------------------------------------------------------
 
   async getLinks(id) {
+    // Resolve prefix/slug to a full id; fall back to the raw token when it
+    // resolves to nothing so unknown ids return empty arrays (not throw).
+    const key = this._resolveId(id) || id;
     const graph = loadGraph(this._graphPath);
     return {
-      forward: (graph.forward[id] || []).map((l) => ({ ...l })),
-      reverse: (graph.reverse[id] || []).map((l) => ({ ...l })),
+      forward: (graph.forward[key] || []).map((l) => ({ ...l })),
+      reverse: (graph.reverse[key] || []).map((l) => ({ ...l })),
     };
   }
 

package/kits/knowledge/adapters/shared/codec.js

@@ -323,3 +323,144 @@ export function validateCategory(cat) {
   if (!cat || typeof cat !== "string") return false;
   return cat.split(".").every((seg) => CATEGORY_SEGMENT_RE.test(seg));
 }
+
+// ---------------------------------------------------------------------------
+// Record identity resolution — short-id prefix + slug aliases  (issue #339)
+//
+// On-disk identity is unchanged: records remain keyed by their full `id`
+// (§9). The functions below add a *resolution layer* on top of that identity
+// so a query token may be the full id, a category-scoped human-readable slug
+// alias, or an unambiguous id prefix. See store-contract.md Addendum H.
+// ---------------------------------------------------------------------------
+
+// Minimum length of an id prefix that `get`/`getLinks` will attempt to resolve.
+// Tokens shorter than this are never treated as prefixes (they resolve to null
+// rather than risk a wildly ambiguous match). The ops design partner cites
+// records by 8-char short ids, so 8 is the contract minimum.
+export const MIN_ID_PREFIX = 8;
+
+// A slug alias is a lowercase, category-scoped handle, e.g.
+// `decision.strategy/2026-07-03-gtm-direction`. It must start and end with an
+// alphanumeric and may contain dots, slashes, hyphens and underscores between.
+export const SLUG_PATTERN = "^[a-z0-9]([a-z0-9._/-]*[a-z0-9])?$";
+const SLUG_RE = new RegExp(SLUG_PATTERN);
+
+export function validateSlug(slug) {
+  return typeof slug === "string" && slug.length > 0 && slug.length <= 200 && SLUG_RE.test(slug);
+}
+
+/**
+ * Validate + de-duplicate a caller-supplied `aliases` array. Throws
+ * MISSING_EVIDENCE (the contract's rejection channel) on a non-array or a
+ * malformed slug so bad aliases are rejected at the mutation boundary.
+ * @returns {string[]} normalized, order-preserving, de-duplicated slug list
+ */
+export function normalizeAliases(input) {
+  if (input === undefined || input === null) return [];
+  if (!Array.isArray(input))
+    throw missingEvidenceError("aliases must be an array of slug strings");
+  const out = [];
+  const seen = new Set();
+  for (const raw of input) {
+    if (!validateSlug(raw))
+      throw missingEvidenceError(
+        `invalid slug alias: ${JSON.stringify(raw)} (must match ${SLUG_PATTERN})`
+      );
+    if (!seen.has(raw)) { seen.add(raw); out.push(raw); }
+  }
+  return out;
+}
+
+export function ambiguousIdError(input, matches) {
+  const shown = matches.slice(0, 5).join(", ");
+  const err = new Error(
+    `Ambiguous id prefix "${input}" matches ${matches.length} records: ${shown}${matches.length > 5 ? ", …" : ""}`
+  );
+  err.code = "AMBIGUOUS_ID";
+  err.matches = matches.slice();
+  return err;
+}
+
+/**
+ * Resolve a query token to a single record id.
+ *
+ * Resolution order (first hit wins):
+ *   1. Exact full-id match — preserves exact-id semantics and the O(1) hot path.
+ *   2. Slug alias — an entry in the alias map (`bySlug`) whose target still exists.
+ *   3. Unambiguous id prefix (length >= MIN_ID_PREFIX) matching exactly one id.
+ *
+ * @param {string} input
+ * @param {{ idExists:(id:string)=>boolean, listIds:()=>Iterable<string>, bySlug?:Record<string,string> }} ctx
+ * @returns {string|null} resolved id, or null when the token resolves to nothing
+ * @throws error with `code === "AMBIGUOUS_ID"` when a prefix matches >1 record
+ */
+export function resolveRecordId(input, ctx) {
+  if (typeof input !== "string" || input.length === 0) return null;
+  // 1. Exact full-id match.
+  if (ctx.idExists(input)) return input;
+  // 2. Slug alias.
+  const bySlug = ctx.bySlug || {};
+  if (Object.prototype.hasOwnProperty.call(bySlug, input)) {
+    const target = bySlug[input];
+    if (target && ctx.idExists(target)) return target;
+  }
+  // 3. Unambiguous id prefix.
+  if (input.length >= MIN_ID_PREFIX) {
+    const matches = [];
+    for (const id of ctx.listIds()) {
+      if (typeof id === "string" && id.startsWith(input)) matches.push(id);
+    }
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) throw ambiguousIdError(input, matches);
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Alias map (alias-index.json) — the durable slug → id mapping.
+//
+// Like the graph index, the alias map is a DERIVED cache: each record's own
+// `aliases` array is the source of truth, so the map is fully rebuildable by
+// scanning records. Keying by full id (never by category or file path) is what
+// lets aliases survive store restructures — recategorizing a record or moving
+// its file leaves the slug → id mapping untouched.
+// ---------------------------------------------------------------------------
+
+export const ALIAS_INDEX_SCHEMA_VERSION = "1.0";
+
+export function emptyAliasIndex() {
+  return { schema_version: ALIAS_INDEX_SCHEMA_VERSION, by_slug: {} };
+}
+
+export function loadAliasIndex(aliasPath) {
+  if (!fs.existsSync(aliasPath)) return emptyAliasIndex();
+  try {
+    const idx = JSON.parse(fs.readFileSync(aliasPath, "utf8"));
+    if (!idx || typeof idx.by_slug !== "object" || idx.by_slug === null) return emptyAliasIndex();
+    return idx;
+  } catch {
+    return emptyAliasIndex();
+  }
+}
+
+export function saveAliasIndex(aliasPath, index) {
+  fs.writeFileSync(aliasPath, JSON.stringify(index, null, 2) + "\n", "utf8");
+}
+
+/**
+ * Point each slug at `id` in the alias map. A slug already owned by a
+ * different record is a genuine collision — throws `SLUG_CONFLICT` (rather than
+ * silently re-pointing the alias). Re-registering a slug already owned by `id`
+ * is a no-op, so this is idempotent per record.
+ */
+export function registerAliases(index, id, slugs) {
+  for (const slug of slugs) {
+    const owner = index.by_slug[slug];
+    if (owner && owner !== id) {
+      const err = new Error(`slug alias "${slug}" already assigned to record ${owner}`);
+      err.code = "SLUG_CONFLICT";
+      throw err;
+    }
+    index.by_slug[slug] = id;
+  }
+}