@kontourai/flow-agents 2.4.0 → 3.1.0

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;
+  }
+}

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
+```