@kontourai/flow-agents 3.0.0 → 3.2.0

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

@@ -57,6 +57,16 @@ import {
   VALID_TYPES,
   VALID_STATUS_TRANSITIONS,
   validateCategory,
+  // Record-identity resolution layer (short-id prefix + slug aliases, issue #339)
+  resolveRecordId,
+  normalizeAliases,
+  loadAliasIndex,
+  saveAliasIndex,
+  registerAliases,
+  // Record-carried freshness + derived staleness (issue #341, Addendum J).
+  freshnessPatch,
+  decodeFreshnessFields,
+  isRecordStale,
 } from "../shared/codec.js";
 
 // ---------------------------------------------------------------------------
@@ -94,9 +104,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
   // -------------------------------------------------------------------------
@@ -272,7 +306,8 @@ export class ObsidianKnowledgeStore {
     // Reconstruct the record body from the rendered markdown section.
     // `meta` no longer contains `body` — the rendered text is the source of truth.
     const body = this._parseBodyFromRendered(meta.type, renderedText);
-    return { ...meta, body };
+    // Coerce record-carried freshness fields to canonical types (#341).
+    return decodeFreshnessFields({ ...meta, body });
   }
 
   /**
@@ -505,6 +540,18 @@ 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);
+    }
+
+    // Validate optional freshness fields (#341) before any write.
+    const fresh = freshnessPatch(input);
+
     const explicitLinks = input.links || [];
     const wikilinks = extractWikilinks(input.body || "");
     const links = mergeLinks(explicitLinks, wikilinks);
@@ -515,9 +562,11 @@ export class ObsidianKnowledgeStore {
       title: input.title,
       category: input.category,
       tags: input.tags || [],
+      ...(aliases.length ? { aliases } : {}),
       status: "active",
       created_at: now,
       updated_at: now,
+      ...fresh,
       provenance: {
         agent: input.provenance.agent,
         ...(input.provenance.session_id ? { session_id: input.provenance.session_id } : {}),
@@ -535,6 +584,8 @@ export class ObsidianKnowledgeStore {
     addLinksToGraph(graph, id, links);
     saveGraph(this._graphPath, graph);
 
+    if (aliasIndex) saveAliasIndex(this._aliasPath, aliasIndex);
+
     return id;
   }
 
@@ -550,7 +601,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", "expires_at", "ttl_seconds"];
     const supplied = mutableKeys.filter((k) => fields[k] !== undefined);
     if (supplied.length === 0)
       throw missingEvidenceError("update: at least one mutable field must be supplied");
@@ -558,8 +609,23 @@ export class ObsidianKnowledgeStore {
     if (fields.category !== undefined && !validateCategory(fields.category))
       throw missingEvidenceError(`update: invalid category: ${fields.category}`);
 
+    // Validate/normalize supplied freshness fields (#341); null/"" clears a field.
+    const fresh = freshnessPatch(fields);
+
     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 +641,8 @@ 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 } : {}),
+      ...fresh,
       links: newLinks,
       updated_at: now,
       mutation_log: [
@@ -596,6 +664,8 @@ export class ObsidianKnowledgeStore {
 
     this._writeRecord(updated, pathIndex);
     this._savePathIndex(pathIndex);
+
+    if (aliasIndex) saveAliasIndex(this._aliasPath, aliasIndex);
   }
 
   // -------------------------------------------------------------------------
@@ -956,7 +1026,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 +1039,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 })),
     };
   }
 
@@ -978,18 +1056,19 @@ export class ObsidianKnowledgeStore {
   async listByCategory(category, options = {}) {
     const records = this._allRecords();
     const includeRetired = options.includeRetired === true;
+    // Derived staleness filter (#341): keep only records past their own effective
+    // expiry at `now` (injectable for tests). Absent → no staleness filtering.
+    const staleOnly = options.stale === true;
+    const nowMs = options.now !== undefined ? new Date(options.now).getTime() : Date.now();
+    const keep = (r) =>
+      (includeRetired || (r.status || "active") !== "retired") &&
+      (!staleOnly || isRecordStale(r, nowMs));
     if (options.prefix) {
       return records.filter(
-        (r) =>
-          (r.category === category || r.category.startsWith(`${category}.`)) &&
-          (includeRetired || (r.status || "active") !== "retired")
+        (r) => (r.category === category || r.category.startsWith(`${category}.`)) && keep(r)
       );
     }
-    return records.filter(
-      (r) =>
-        r.category === category &&
-        (includeRetired || (r.status || "active") !== "retired")
-    );
+    return records.filter((r) => r.category === category && keep(r));
   }
 
   // -------------------------------------------------------------------------
@@ -998,10 +1077,14 @@ export class ObsidianKnowledgeStore {
 
   async listByType(type, options = {}) {
     const includeRetired = options.includeRetired === true;
+    // Derived staleness filter (#341) — see listByCategory.
+    const staleOnly = options.stale === true;
+    const nowMs = options.now !== undefined ? new Date(options.now).getTime() : Date.now();
     return this._allRecords().filter(
       (r) =>
         r.type === type &&
-        (includeRetired || (r.status || "active") !== "retired")
+        (includeRetired || (r.status || "active") !== "retired") &&
+        (!staleOnly || isRecordStale(r, nowMs))
     );
   }
 }

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

@@ -323,3 +323,268 @@ 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;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Freshness + derived status  (issue #341, store-contract Addendum J)
+//
+// Optional, backward-compatible record-carried expiry aligned to Kontour's own
+// Hachure trust vocabulary (expiresAt / ttlSeconds; stale / superseded). Every
+// helper below is a no-op / null / false for a record that carries NO freshness
+// fields, so records written before this slice behave exactly as they did.
+//
+// `stale` and `superseded` are DERIVED states — computed here, never written
+// back onto the record's stored `status` (Addendum B). "No silent rot" means a
+// record goes VISIBLY stale under query, not that the store rewrites it behind
+// the operator's back.
+// ---------------------------------------------------------------------------
+
+// The optional freshness fields on the record envelope (§1.1 / Addendum J.1).
+export const FRESHNESS_KEYS = ["expires_at", "ttl_seconds"];
+
+/** Validate an `expires_at` value: a non-empty ISO-8601 string. */
+export function validateExpiresAt(value) {
+  if (typeof value !== "string" || !value.trim())
+    throw missingEvidenceError(
+      `expires_at must be a non-empty ISO-8601 string; got: ${JSON.stringify(value)}`
+    );
+  if (Number.isNaN(Date.parse(value)))
+    throw missingEvidenceError(
+      `expires_at must be a valid ISO-8601 timestamp; got: ${JSON.stringify(value)}`
+    );
+  return value;
+}
+
+/** Validate a `ttl_seconds` value: a positive, finite number of seconds. */
+export function validateTtlSeconds(value) {
+  const n = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+  if (typeof n !== "number" || !Number.isFinite(n) || n <= 0)
+    throw missingEvidenceError(
+      `ttl_seconds must be a positive number of seconds; got: ${JSON.stringify(value)}`
+    );
+  return n;
+}
+
+/**
+ * Extract + validate the freshness fields from a create/update input, returning
+ * a patch object containing only the supplied keys (normalized). A key set
+ * explicitly to `null` or `""` is returned as `undefined` — the signal to CLEAR
+ * it (the YAML serializer drops undefined). Absent keys are omitted, so an input
+ * with no freshness fields yields `{}` (full backward compatibility). Throws
+ * MISSING_EVIDENCE — the contract's rejection channel — on a malformed value,
+ * at the mutation boundary, so bad freshness never reaches disk.
+ */
+export function freshnessPatch(input) {
+  const patch = {};
+  if (!input || typeof input !== "object") return patch;
+  if (Object.prototype.hasOwnProperty.call(input, "expires_at")) {
+    patch.expires_at =
+      input.expires_at === null || input.expires_at === ""
+        ? undefined
+        : validateExpiresAt(input.expires_at);
+  }
+  if (Object.prototype.hasOwnProperty.call(input, "ttl_seconds")) {
+    patch.ttl_seconds =
+      input.ttl_seconds === null || input.ttl_seconds === ""
+        ? undefined
+        : validateTtlSeconds(input.ttl_seconds);
+  }
+  return patch;
+}
+
+/**
+ * Coerce freshness fields to their canonical runtime types after a frontmatter
+ * read: the zero-dep YAML codec returns every scalar as a string, so a numeric
+ * `ttl_seconds` round-trips as text without this. Mutates and returns the
+ * record; a no-op when no freshness field is present.
+ */
+export function decodeFreshnessFields(record) {
+  if (record && record.ttl_seconds !== undefined && record.ttl_seconds !== null) {
+    const n = Number(record.ttl_seconds);
+    if (Number.isFinite(n)) record.ttl_seconds = n;
+  }
+  return record;
+}
+
+/**
+ * The record's EFFECTIVE expiry as epoch-ms, or `null` when it carries no
+ * freshness fields. Precedence: an explicit `expires_at` wins over a derived
+ * `created_at + ttl_seconds`. Returns null (never throws) on an unparseable
+ * field, so malformed freshness can neither make a record spuriously
+ * "fresh forever" nor crash a read-only audit.
+ */
+export function effectiveExpiryMs(record) {
+  if (!record || typeof record !== "object") return null;
+  if (record.expires_at) {
+    const ms = Date.parse(record.expires_at);
+    if (!Number.isNaN(ms)) return ms;
+  }
+  if (record.ttl_seconds !== undefined && record.ttl_seconds !== null && record.created_at) {
+    const base = Date.parse(record.created_at);
+    const ttl = Number(record.ttl_seconds);
+    if (!Number.isNaN(base) && Number.isFinite(ttl)) return base + ttl * 1000;
+  }
+  return null;
+}
+
+/**
+ * Is the record STALE at instant `nowMs`? Derived, never stored. A record with
+ * no freshness fields is never stale via this path (backward compat). Boundary:
+ * the expiry instant itself counts as expired (`nowMs >= expiry`) — a record
+ * "expires_at T" is stale from T onward, inclusive.
+ */
+export function isRecordStale(record, nowMs) {
+  const exp = effectiveExpiryMs(record);
+  if (exp === null) return false;
+  return nowMs >= exp;
+}
+
+/**
+ * Is the record SUPERSEDED? Derived from the Addendum A.5 supersede
+ * relationship, surfaced as the incoming `supersedes` edge in the graph
+ * (`getLinks(id).reverse`) — equivalently, the record carries a `superseded-by`
+ * mutation-log entry. Never stored as a `status`.
+ */
+export function isSupersededByLinks(reverseLinks) {
+  return Array.isArray(reverseLinks) && reverseLinks.some((l) => l && l.kind === "supersedes");
+}

package/kits/knowledge/docs/README.md

@@ -49,6 +49,29 @@ See [`store-contract.md`](store-contract.md) for the full specification. Quick r
 
 Every mutation throws with `error.code === "MISSING_EVIDENCE"` when required evidence is absent.
 
+**Record identity resolution** (Addendum H)
+
+`get`/`getLinks` accept three handle forms, resolved in order: exact full `id`, then a
+category-scoped **slug alias**, then an **unambiguous id prefix** (≥ 8 chars).
+
+| Handle | Example | Resolves to |
+|---|---|---|
+| Full id | `12cc5573-1c4f-4a0e-8b6e-9d2f0a5b7c31` | the record (unchanged exact-id behavior) |
+| Slug alias | `decision.strategy/2026-07-03-gtm-direction` | the record that carries that alias |
+| Short-id prefix (≥ 8 chars, unique) | `12cc5573` | the single record whose id starts with it |
+
+Aliases are caller-supplied via the optional `aliases: string[]` field on `create`/`update`,
+append-only, and stored in an id-keyed alias map (`alias-index.json`) so a prefix or slug **still
+resolves after a store restructure** (e.g. a recategorize that moves the file). An unresolved
+handle returns `null` (`get`) / empty arrays (`getLinks`); an **ambiguous** prefix throws
+`error.code === "AMBIGUOUS_ID"` — it is never silently guessed. On-disk identity (`records/<id>.md`)
+is unchanged.
+
+| Error code | Raised when |
+|---|---|
+| `AMBIGUOUS_ID` | an id prefix matches more than one record (carries a `matches` array) |
+| `SLUG_CONFLICT` | a supplied slug alias is already assigned to a different record |
+
 ---
 
 ## Running the Contract Suite
@@ -89,6 +112,16 @@ All tests pass and exit 0. Any failure indicates a contract regression or an ada
 | AC2 | Default adapter passes contract suite (command evidence). | Run `node --test kits/knowledge/evals/contract-suite/suite.test.js` — exit 0, all tests pass. |
 | AC3 | Record round-trips raw → stored → queried with category + links intact. | Suite §2 "create: round-trip raw → stored → queried" tests this directly. |
 
+**Identity resolution (#339)** — mapped to that issue's ACs:
+
+| AC (#339) | Requirement | Evidence |
+|---|---|---|
+| AC1 | Unique 8-char prefix resolves; ambiguous prefix throws `AMBIGUOUS_ID`. | Suite §15 "identity: short-id prefix resolution (AC1)". |
+| AC2 | Slug alias resolves via `get`/`getLinks` (set at create or update). | Suite §16 "identity: slug alias resolution (AC2)". |
+| AC3 | Old slug + short-id prefix survive an `update` recategorize/move. | Suite §17 "identity: alias resolution survives restructure (AC3)". |
+| AC4 | Existing sections pass unmodified; files remain `records/<id>.md`. | §2 round-trip, §13 graph consistency, §12 missing-record unchanged; on-disk naming untouched. |
+| AC5 | Contract doc specifies prefix/slug/alias-map semantics. | [`store-contract.md`](store-contract.md) Addendum H + §1.1/§7/§8.1/§9 updates. |
+
 ---
 
 ## Default Adapter Details
@@ -103,6 +136,7 @@ built-ins only.
   records/
     <id>.md        ← one markdown file per record, YAML frontmatter + body
   graph-index.json ← forward + reverse link index, schema_version 1.0
+  alias-index.json ← slug → id alias map (Addendum H), schema_version 1.0
 ```
 
 **Constructor**
@@ -120,8 +154,8 @@ const store = new DefaultKnowledgeStore({ storeRoot: '/path/to/store' });
 - `propose(conceptId, proposerId, evidence)` → `Promise<void>`
 - `apply(conceptId, proposerId, evidence)` → `Promise<void>`
 - `reject(conceptId, proposerId, evidence)` → `Promise<void>`
-- `get(id)` → `Promise<Record | null>`
-- `getLinks(id)` → `Promise<{ forward: Link[], reverse: Link[] }>`
+- `get(idOrHandle)` → `Promise<Record | null>` (exact id, slug alias, or unambiguous id prefix — Addendum H)
+- `getLinks(idOrHandle)` → `Promise<{ forward: Link[], reverse: Link[] }>`
 - `listByCategory(category, options?)` → `Promise<Record[]>`
 - `listByType(type)` → `Promise<Record[]>`
 
@@ -326,3 +360,88 @@ const detector = createVectorSimilarityDetector({
 
 The `embed` function is called once per `synthesize`/`consolidate` call with all texts in a
 single batch (concept first, then candidates).
+
+---
+
+## Graph provider (opt-in)
+
+The `neo4j` provider is a real, queryable graph implementation of the store
+provider read interface (issue #327). It is the **owner's opt-in personal
+default** — the file providers (`markdown-vault`, `git-repo`, `work-item`) remain
+the portfolio default. The graph is a **materialized view** synced from those
+providers: the file stores stay the source of truth, and the write side stays
+proposals-only. `neo4j-driver` is an optional dependency; with no Neo4j reachable
+everything degrades to the file providers with a clear message — it is never a
+hard dependency.
+
+### 1. Start Neo4j (Docker)
+
+```bash
+docker run -d --name kg-neo4j -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/testpassword neo4j:5-community
+```
+
+### 2. Point the provider at it (connection by reference — never hardcoded)
+
+```bash
+export NEO4J_URI=bolt://localhost:7687
+export NEO4J_USER=neo4j
+export NEO4J_PASSWORD=testpassword   # use your own secret; this is an example
+export KNOWLEDGE_PROVIDER=neo4j      # opt in (repo/user-level); default is `file`
+npm install neo4j-driver             # optional dependency, only if not already present
+```
+
+### 3. Sync the file stores into the graph (idempotent)
+
+`sync` reads the other providers and MERGEs their combined graph into Neo4j. A
+re-sync of unchanged stores reports **zero writes** (content-keyed hash guard);
+a snapshot digest + timestamp is recorded on the graph.
+
+```js
+import { GitRepoProvider } from "./kits/knowledge/providers/git-repo/index.js";
+import { WorkItemProvider } from "./kits/knowledge/providers/work-item/index.js";
+import { syncToNeo4j } from "./kits/knowledge/providers/neo4j/index.js";
+import { resolveNeo4jConfig, createDriver } from "./kits/knowledge/providers/neo4j/index.js";
+
+const driver = await createDriver(resolveNeo4jConfig());
+const providers = [
+  new GitRepoProvider({ repoRoot: process.cwd() }),
+  new WorkItemProvider({ repo: "kontourai/flow-agents" }), // reads via gh
+];
+console.log(await syncToNeo4j({ driver, providers })); // { writes, unchanged, digest, ... }
+```
+
+### 4. Query it — Neo4j Browser or the provider verbs
+
+Open `http://localhost:7474` for the interactive Browser, or use the provider's
+Cypher-backed query/health verbs (they fall back to a portable JS spelling with
+identical answers when no Neo4j is reachable):
+
+```js
+import { Neo4jProvider } from "./kits/knowledge/providers/neo4j/index.js";
+const kg = new Neo4jProvider({ driver });
+await kg.transitiveBlockers("issue:313");     // Q1 transitive blocker closure
+await kg.contradictionCandidates();           // Q2 divergent status over one subject
+await kg.orphans();                           // Q3 node-type-aware orphans
+await kg.duplicateCandidates();               // Q4 duplicate candidates WITH stemming
+await kg.shortestPath("decision:adr-0011", "decision:adr-0021"); // Q5 shortest path
+```
+
+Example Cypher session in the Browser (the blocker subgraph the spike visualised):
+
+```cypher
+MATCH p=(a:Issue)-[:BLOCKS]->(b:Issue) RETURN p LIMIT 60;
+```
+
+### Running the full live integration locally
+
+CI has no Neo4j, so the conformance + unit tests run against an injected fake
+driver and the live integration test skips loudly. To run the live path:
+
+```bash
+docker run -d --name kg-neo4j -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/testpassword neo4j:5-community
+NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=testpassword \
+  node --test kits/knowledge/providers/neo4j/integration.test.js
+docker rm -f kg-neo4j
+```