@sanqianx/project-knowledge 5.0.24 → 5.0.26

package/_site/lib/prompt-registry.js

@@ -1,148 +1,148 @@
-// Prompt Registry — reads/writes claude-prompts.json and renders templated prompts.
-//
-// File location: <KB_ROOT>/claude-prompts.json
-// Schema: { schema: 'claude-prompts/v1', prompts: { <key>: { description, model, permissionMode,
-//            allowedTools, systemPrompt, userPrompt } } }
-//
-// Variable interpolation: {{KEY}} placeholders in systemPrompt/userPrompt are replaced
-// with values from the `vars` argument. Unknown placeholders are left untouched (so
-// incomplete prompts don't crash — they show the raw token for diagnosis).
-
-const fs = require('fs');
-const path = require('path');
-
-const { getDataDir } = require('./data-dir');
-const KB_ROOT = getDataDir();
-const PROMPTS_PATH = path.join(KB_ROOT, 'claude-prompts.json');
-const BUNDLED_PROMPTS_PATH = path.resolve(__dirname, '..', '..', 'claude-prompts.json');
-const SCHEMA = 'claude-prompts/v1';
-
-const PLACEHOLDER_RE = /\{\{\s*([A-Z_][A-Z0-9_]*)\s*\}\}/g;
-
-function normalizePromptsConfig(cfg) {
-  const normalized = cfg && typeof cfg === 'object' ? cfg : {};
-  if (!normalized.prompts || typeof normalized.prompts !== 'object') normalized.prompts = {};
-  if (!normalized.schema) normalized.schema = SCHEMA;
-  return normalized;
-}
-
-function readBundledPrompts() {
-  if (!fs.existsSync(BUNDLED_PROMPTS_PATH)) return { schema: SCHEMA, prompts: {} };
-  try {
-    return normalizePromptsConfig(JSON.parse(fs.readFileSync(BUNDLED_PROMPTS_PATH, 'utf-8')));
-  } catch {
-    return { schema: SCHEMA, prompts: {} };
-  }
-}
-
-function persistPrompts(cfg) {
-  fs.mkdirSync(path.dirname(PROMPTS_PATH), { recursive: true });
-  fs.writeFileSync(PROMPTS_PATH, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
-}
-
-function withBundledDefaults(cfg) {
-  const current = normalizePromptsConfig(cfg);
-  const bundled = readBundledPrompts();
-  let changed = false;
-  const prompts = { ...current.prompts };
-  for (const [key, prompt] of Object.entries(bundled.prompts || {})) {
-    if (!Object.prototype.hasOwnProperty.call(prompts, key)) {
-      prompts[key] = prompt;
-      changed = true;
-    }
-  }
-  return {
-    cfg: {
-      schema: current.schema || bundled.schema || SCHEMA,
-      prompts,
-    },
-    changed,
-  };
-}
-
-function readPrompts() {
-  if (!fs.existsSync(PROMPTS_PATH)) {
-    const seeded = withBundledDefaults({ schema: SCHEMA, prompts: {} }).cfg;
-    if (Object.keys(seeded.prompts).length) {
-      persistPrompts(seeded);
-    }
-    return seeded;
-  }
-  try {
-    const result = withBundledDefaults(JSON.parse(fs.readFileSync(PROMPTS_PATH, 'utf-8')));
-    if (result.changed) persistPrompts(result.cfg);
-    return result.cfg;
-  } catch (e) {
-    throw new Error(`failed to parse ${PROMPTS_PATH}: ${e.message}`);
-  }
-}
-
-function writePrompts(cfg) {
-  if (!cfg || typeof cfg !== 'object') throw new Error('prompts config must be an object');
-  if (cfg.prompts && typeof cfg.prompts !== 'object') throw new Error('prompts field must be an object');
-  const normalized = {
-    schema: cfg.schema || SCHEMA,
-    prompts: cfg.prompts || {},
-  };
-  for (const [key, val] of Object.entries(normalized.prompts)) {
-    if (!key || typeof key !== 'string') throw new Error(`invalid prompt key: ${key}`);
-    if (!val || typeof val !== 'object') throw new Error(`prompt "${key}" must be an object`);
-    if (typeof val.userPrompt !== 'string' || !val.userPrompt) {
-      throw new Error(`prompt "${key}" must have a non-empty userPrompt`);
-    }
-  }
-  persistPrompts(normalized);
-  return normalized;
-}
-
-function listPromptKeys() {
-  return Object.keys(readPrompts().prompts);
-}
-
-function getPrompt(key) {
-  const cfg = readPrompts();
-  const p = cfg.prompts[key];
-  if (!p) return null;
-  return p;
-}
-
-function interpolate(text, vars) {
-  if (typeof text !== 'string') return text;
-  if (!vars || typeof vars !== 'object') return text;
-  return text.replace(PLACEHOLDER_RE, (_, name) => {
-    if (Object.prototype.hasOwnProperty.call(vars, name)) {
-      const v = vars[name];
-      return v == null ? '' : String(v);
-    }
-    return `{{${name}}}`;
-  });
-}
-
-// Render the prompt for a given key, returning all fields needed to spawn claude.
-// Returns null if key doesn't exist.
-function renderPrompt(key, vars) {
-  const p = getPrompt(key);
-  if (!p) return null;
-  const safeVars = vars || {};
-  return {
-    key,
-    description: p.description || '',
-    model: p.model || 'sonnet',
-    permissionMode: p.permissionMode || 'bypassPermissions',
-    allowedTools: Array.isArray(p.allowedTools) ? p.allowedTools.slice() : ['Read', 'Grep', 'Glob'],
-    systemPrompt: interpolate(p.systemPrompt || '', safeVars),
-    userPrompt: interpolate(p.userPrompt, safeVars),
-  };
-}
-
-module.exports = {
-  PROMPTS_PATH,
-  BUNDLED_PROMPTS_PATH,
-  SCHEMA,
-  readPrompts,
-  writePrompts,
-  listPromptKeys,
-  getPrompt,
-  renderPrompt,
-  interpolate,
-};
+// Prompt Registry — reads/writes claude-prompts.json and renders templated prompts.
+//
+// File location: <KB_ROOT>/claude-prompts.json
+// Schema: { schema: 'claude-prompts/v1', prompts: { <key>: { description, model, permissionMode,
+//            allowedTools, systemPrompt, userPrompt } } }
+//
+// Variable interpolation: {{KEY}} placeholders in systemPrompt/userPrompt are replaced
+// with values from the `vars` argument. Unknown placeholders are left untouched (so
+// incomplete prompts don't crash — they show the raw token for diagnosis).
+
+const fs = require('fs');
+const path = require('path');
+
+const { getDataDir } = require('./data-dir');
+const KB_ROOT = getDataDir();
+const PROMPTS_PATH = path.join(KB_ROOT, 'claude-prompts.json');
+const BUNDLED_PROMPTS_PATH = path.resolve(__dirname, '..', '..', 'claude-prompts.json');
+const SCHEMA = 'claude-prompts/v1';
+
+const PLACEHOLDER_RE = /\{\{\s*([A-Z_][A-Z0-9_]*)\s*\}\}/g;
+
+function normalizePromptsConfig(cfg) {
+  const normalized = cfg && typeof cfg === 'object' ? cfg : {};
+  if (!normalized.prompts || typeof normalized.prompts !== 'object') normalized.prompts = {};
+  if (!normalized.schema) normalized.schema = SCHEMA;
+  return normalized;
+}
+
+function readBundledPrompts() {
+  if (!fs.existsSync(BUNDLED_PROMPTS_PATH)) return { schema: SCHEMA, prompts: {} };
+  try {
+    return normalizePromptsConfig(JSON.parse(fs.readFileSync(BUNDLED_PROMPTS_PATH, 'utf-8')));
+  } catch {
+    return { schema: SCHEMA, prompts: {} };
+  }
+}
+
+function persistPrompts(cfg) {
+  fs.mkdirSync(path.dirname(PROMPTS_PATH), { recursive: true });
+  fs.writeFileSync(PROMPTS_PATH, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+}
+
+function withBundledDefaults(cfg) {
+  const current = normalizePromptsConfig(cfg);
+  const bundled = readBundledPrompts();
+  let changed = false;
+  const prompts = { ...current.prompts };
+  for (const [key, prompt] of Object.entries(bundled.prompts || {})) {
+    if (!Object.prototype.hasOwnProperty.call(prompts, key)) {
+      prompts[key] = prompt;
+      changed = true;
+    }
+  }
+  return {
+    cfg: {
+      schema: current.schema || bundled.schema || SCHEMA,
+      prompts,
+    },
+    changed,
+  };
+}
+
+function readPrompts() {
+  if (!fs.existsSync(PROMPTS_PATH)) {
+    const seeded = withBundledDefaults({ schema: SCHEMA, prompts: {} }).cfg;
+    if (Object.keys(seeded.prompts).length) {
+      persistPrompts(seeded);
+    }
+    return seeded;
+  }
+  try {
+    const result = withBundledDefaults(JSON.parse(fs.readFileSync(PROMPTS_PATH, 'utf-8')));
+    if (result.changed) persistPrompts(result.cfg);
+    return result.cfg;
+  } catch (e) {
+    throw new Error(`failed to parse ${PROMPTS_PATH}: ${e.message}`);
+  }
+}
+
+function writePrompts(cfg) {
+  if (!cfg || typeof cfg !== 'object') throw new Error('prompts config must be an object');
+  if (cfg.prompts && typeof cfg.prompts !== 'object') throw new Error('prompts field must be an object');
+  const normalized = {
+    schema: cfg.schema || SCHEMA,
+    prompts: cfg.prompts || {},
+  };
+  for (const [key, val] of Object.entries(normalized.prompts)) {
+    if (!key || typeof key !== 'string') throw new Error(`invalid prompt key: ${key}`);
+    if (!val || typeof val !== 'object') throw new Error(`prompt "${key}" must be an object`);
+    if (typeof val.userPrompt !== 'string' || !val.userPrompt) {
+      throw new Error(`prompt "${key}" must have a non-empty userPrompt`);
+    }
+  }
+  persistPrompts(normalized);
+  return normalized;
+}
+
+function listPromptKeys() {
+  return Object.keys(readPrompts().prompts);
+}
+
+function getPrompt(key) {
+  const cfg = readPrompts();
+  const p = cfg.prompts[key];
+  if (!p) return null;
+  return p;
+}
+
+function interpolate(text, vars) {
+  if (typeof text !== 'string') return text;
+  if (!vars || typeof vars !== 'object') return text;
+  return text.replace(PLACEHOLDER_RE, (_, name) => {
+    if (Object.prototype.hasOwnProperty.call(vars, name)) {
+      const v = vars[name];
+      return v == null ? '' : String(v);
+    }
+    return `{{${name}}}`;
+  });
+}
+
+// Render the prompt for a given key, returning all fields needed to spawn claude.
+// Returns null if key doesn't exist.
+function renderPrompt(key, vars) {
+  const p = getPrompt(key);
+  if (!p) return null;
+  const safeVars = vars || {};
+  return {
+    key,
+    description: p.description || '',
+    model: p.model || 'sonnet',
+    permissionMode: p.permissionMode || 'bypassPermissions',
+    allowedTools: Array.isArray(p.allowedTools) ? p.allowedTools.slice() : ['Read', 'Grep', 'Glob'],
+    systemPrompt: interpolate(p.systemPrompt || '', safeVars),
+    userPrompt: interpolate(p.userPrompt, safeVars),
+  };
+}
+
+module.exports = {
+  PROMPTS_PATH,
+  BUNDLED_PROMPTS_PATH,
+  SCHEMA,
+  readPrompts,
+  writePrompts,
+  listPromptKeys,
+  getPrompt,
+  renderPrompt,
+  interpolate,
+};

package/_site/lib/public-version-info.js

@@ -0,0 +1,37 @@
+'use strict';
+/**
+ * Minimal read-only core version snapshot behind GET /api/system/version.
+ *
+ * The UI brand tooltip (ui/version-info.js) shows "知识库 vX.Y.Z" from this
+ * one payload: the version of the Project Knowledge package this server
+ * process is running — never a business repo's git tag, a sibling checkout,
+ * npm latest, or the desktop shell version. Nothing is guessed: if the
+ * running package cannot be read, `version` is null and the UI says 未知.
+ *
+ * (R1 of this lane shipped a full module-aggregation endpoint here — sidebar
+ * entry, per-module table, desktop IPC. The user simplified the requirement
+ * to a hover-only brand tooltip, so everything but this core snapshot was
+ * reverted; see docs/plans/VERSION-VISIBILITY-2026-10-23.md.)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_PACKAGE = path.resolve(__dirname, '..', '..', 'package.json');
+let pkg = null;
+try { pkg = JSON.parse(fs.readFileSync(ROOT_PACKAGE, 'utf8')); } catch { pkg = null; }
+
+function coreVersionSnapshot() {
+  return {
+    ok: true,
+    schema: 'system-version/v1',
+    checkedAt: new Date().toISOString(),
+    core: {
+      name: pkg && typeof pkg.name === 'string' ? pkg.name : null,
+      version: pkg && typeof pkg.version === 'string' && pkg.version.trim() ? pkg.version.trim() : null,
+      source: 'running-process-package',
+    },
+  };
+}
+
+module.exports = { coreVersionSnapshot };

package/_site/lib/registry-events.js

@@ -1,16 +1,16 @@
-'use strict';
-const { randomUUID } = require('node:crypto');
-
-class RegistryEvents {
-  constructor() { this.instanceId = randomUUID(); this.revision = 0; this.listeners = new Set(); }
-  publish(areas = ['projects', 'brain', 'health']) {
-    const event = { type: 'registry-changed', instanceId: this.instanceId, revision: ++this.revision, areas };
-    for (const listener of this.listeners) { try { listener(event); } catch { /* disconnected client */ } }
-  }
-  subscribe(listener) {
-    this.listeners.add(listener);
-    listener({ type: 'registry-snapshot', instanceId: this.instanceId, revision: this.revision });
-    return () => this.listeners.delete(listener);
-  }
-}
-module.exports = { RegistryEvents };
+'use strict';
+const { randomUUID } = require('node:crypto');
+
+class RegistryEvents {
+  constructor() { this.instanceId = randomUUID(); this.revision = 0; this.listeners = new Set(); }
+  publish(areas = ['projects', 'brain', 'health']) {
+    const event = { type: 'registry-changed', instanceId: this.instanceId, revision: ++this.revision, areas };
+    for (const listener of this.listeners) { try { listener(event); } catch { /* disconnected client */ } }
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    listener({ type: 'registry-snapshot', instanceId: this.instanceId, revision: this.revision });
+    return () => this.listeners.delete(listener);
+  }
+}
+module.exports = { RegistryEvents };

package/_site/lib/requirement-adapters.js

@@ -1,10 +1,10 @@
-const { DomainError } = require('./contracts');
-
-function createRequirementMetadataAdapter(recorder, client) {
-  if (!recorder || typeof recorder.recordRequirement !== 'function') {
-    throw new DomainError('INVALID_ARGUMENT', 'A RequirementRecorder is required.');
-  }
-  return input => recorder.recordRequirement({ ...input, client });
-}
-
-module.exports = { createRequirementMetadataAdapter };
+const { DomainError } = require('./contracts');
+
+function createRequirementMetadataAdapter(recorder, client) {
+  if (!recorder || typeof recorder.recordRequirement !== 'function') {
+    throw new DomainError('INVALID_ARGUMENT', 'A RequirementRecorder is required.');
+  }
+  return input => recorder.recordRequirement({ ...input, client });
+}
+
+module.exports = { createRequirementMetadataAdapter };

package/_site/lib/requirement-binder.js

@@ -1,112 +1,112 @@
-const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
-const { StorageLayout } = require('./storage-layout');
-const { ProjectRegistryStore } = require('./project-registry-store');
-const { ProjectStore } = require('./project-store');
-const { GitReader, normalizeClient, normalizeCommit } = require('./requirement-recorder');
-
-function unavailable(reason) {
-  return { requirementIds: [], requirementBinding: 'unavailable', reason };
-}
-
-class RequirementBinder {
-  constructor(options = {}) {
-    this.layout = options.layout || new StorageLayout(options);
-    this.projectStore = options.projectStore || new ProjectStore({ layout: this.layout });
-    this.registryStore = options.registryStore || new ProjectRegistryStore({ layout: this.layout });
-    this.gitReader = options.gitReader || new GitReader();
-  }
-
-  findRequirement(requirementId) {
-    const id = String(requirementId || '').trim();
-    if (!id) throw new DomainError('INVALID_ARGUMENT', 'requirementId is required.');
-    const matches = [];
-    for (const projectId of this.registryStore.listIds()) {
-      const record = this.projectStore.readRequirements(projectId).find(item => item.id === id);
-      if (record) matches.push(record);
-    }
-    if (matches.length !== 1) {
-      throw new DomainError('INVALID_ARGUMENT', matches.length ? 'requirementId is not unique.' : 'requirementId was not found.');
-    }
-    return matches[0];
-  }
-
-  frozenClaim(input, projectId, commitSha) {
-    const claim = input.claim || input.existingClaim;
-    if (!claim) return null;
-    if (claim.schema !== SCHEMAS.commitClaim || normalizeCommit(claim.commitSha) !== commitSha) {
-      throw new DomainError('INVALID_ARGUMENT', 'Existing claim does not match the requested commit.');
-    }
-    if (claim.projectId && claim.projectId !== projectId) {
-      throw new DomainError('INVALID_ARGUMENT', 'Existing claim belongs to a different project.');
-    }
-    return {
-      requirementIds: Array.isArray(claim.requirementIds) ? [...claim.requirementIds] : [],
-      requirementBinding: claim.requirementBinding || 'unavailable',
-      reason: 'frozen-claim',
-      frozen: true,
-    };
-  }
-
-  async bind(input = {}) {
-    const projectId = validateProjectId(input.projectId);
-    const commitSha = normalizeCommit(input.commitSha, 'commitSha');
-    if (!commitSha) throw new DomainError('INVALID_ARGUMENT', 'commitSha is required.');
-    const frozen = this.frozenClaim(input, projectId, commitSha);
-    if (frozen) return frozen;
-
-    const config = this.projectStore.readConfig(projectId);
-    const explicitIds = [...new Set([
-      ...(Array.isArray(input.requirementIds) ? input.requirementIds : []),
-      ...(input.requirementId ? [input.requirementId] : []),
-    ].map(value => String(value || '').trim()).filter(Boolean))];
-    if (explicitIds.length) {
-      const records = explicitIds.map(id => this.findRequirement(id));
-      if (records.some(record => record.projectId !== projectId)) {
-        throw new DomainError('INVALID_ARGUMENT', 'Explicit requirementId belongs to a different project.');
-      }
-      return { requirementIds: records.map(record => record.id), requirementBinding: 'explicit', reason: 'explicit-requirement-id' };
-    }
-
-    const allRecords = this.projectStore.readRequirements(projectId);
-    const explicitlyCommitted = allRecords.filter(record => record.explicitCommit === commitSha);
-    if (explicitlyCommitted.length) {
-      return {
-        requirementIds: explicitlyCommitted.map(record => record.id),
-        requirementBinding: 'explicit',
-        reason: 'explicit-commit',
-      };
-    }
-
-    if (!input.branch) return unavailable('commit-branch-unavailable');
-    const branch = String(input.branch);
-    const claimed = new Set(Array.isArray(input.claimedRequirementIds) ? input.claimedRequirementIds : []);
-    const requestedClient = input.client ? normalizeClient(input.client) : '';
-    const requestedSession = input.sessionId ? String(input.sessionId).trim() : '';
-    const candidates = [];
-    for (const record of allRecords) {
-      if (claimed.has(record.id) || !record.headAtRecord || record.branch !== branch) continue;
-      if (requestedClient && record.client !== requestedClient) continue;
-      if (requestedSession && record.sessionId !== requestedSession) continue;
-      let ancestor = false;
-      try { ancestor = await this.gitReader.isAncestor(config.repoPath, record.headAtRecord, commitSha); } catch { ancestor = false; }
-      if (ancestor) candidates.push(record);
-    }
-    if (!candidates.length) return unavailable('no-reliable-requirement');
-
-    const groups = new Map();
-    for (const record of candidates) {
-      const key = `${record.client}\u0000${record.sessionId}`;
-      if (!groups.has(key)) groups.set(key, []);
-      groups.get(key).push(record);
-    }
-    if (groups.size !== 1) return unavailable('ambiguous-sessions');
-    const sequence = [...groups.values()][0].sort((left, right) => String(left.ts).localeCompare(String(right.ts)) || left.id.localeCompare(right.id));
-    return {
-      requirementIds: sequence.map(record => record.id),
-      requirementBinding: 'session-ancestry',
-      reason: 'unique-session-ancestry',
-    };
-  }
-}
-
-module.exports = { RequirementBinder, unavailable };
+const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
+const { StorageLayout } = require('./storage-layout');
+const { ProjectRegistryStore } = require('./project-registry-store');
+const { ProjectStore } = require('./project-store');
+const { GitReader, normalizeClient, normalizeCommit } = require('./requirement-recorder');
+
+function unavailable(reason) {
+  return { requirementIds: [], requirementBinding: 'unavailable', reason };
+}
+
+class RequirementBinder {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.projectStore = options.projectStore || new ProjectStore({ layout: this.layout });
+    this.registryStore = options.registryStore || new ProjectRegistryStore({ layout: this.layout });
+    this.gitReader = options.gitReader || new GitReader();
+  }
+
+  findRequirement(requirementId) {
+    const id = String(requirementId || '').trim();
+    if (!id) throw new DomainError('INVALID_ARGUMENT', 'requirementId is required.');
+    const matches = [];
+    for (const projectId of this.registryStore.listIds()) {
+      const record = this.projectStore.readRequirements(projectId).find(item => item.id === id);
+      if (record) matches.push(record);
+    }
+    if (matches.length !== 1) {
+      throw new DomainError('INVALID_ARGUMENT', matches.length ? 'requirementId is not unique.' : 'requirementId was not found.');
+    }
+    return matches[0];
+  }
+
+  frozenClaim(input, projectId, commitSha) {
+    const claim = input.claim || input.existingClaim;
+    if (!claim) return null;
+    if (claim.schema !== SCHEMAS.commitClaim || normalizeCommit(claim.commitSha) !== commitSha) {
+      throw new DomainError('INVALID_ARGUMENT', 'Existing claim does not match the requested commit.');
+    }
+    if (claim.projectId && claim.projectId !== projectId) {
+      throw new DomainError('INVALID_ARGUMENT', 'Existing claim belongs to a different project.');
+    }
+    return {
+      requirementIds: Array.isArray(claim.requirementIds) ? [...claim.requirementIds] : [],
+      requirementBinding: claim.requirementBinding || 'unavailable',
+      reason: 'frozen-claim',
+      frozen: true,
+    };
+  }
+
+  async bind(input = {}) {
+    const projectId = validateProjectId(input.projectId);
+    const commitSha = normalizeCommit(input.commitSha, 'commitSha');
+    if (!commitSha) throw new DomainError('INVALID_ARGUMENT', 'commitSha is required.');
+    const frozen = this.frozenClaim(input, projectId, commitSha);
+    if (frozen) return frozen;
+
+    const config = this.projectStore.readConfig(projectId);
+    const explicitIds = [...new Set([
+      ...(Array.isArray(input.requirementIds) ? input.requirementIds : []),
+      ...(input.requirementId ? [input.requirementId] : []),
+    ].map(value => String(value || '').trim()).filter(Boolean))];
+    if (explicitIds.length) {
+      const records = explicitIds.map(id => this.findRequirement(id));
+      if (records.some(record => record.projectId !== projectId)) {
+        throw new DomainError('INVALID_ARGUMENT', 'Explicit requirementId belongs to a different project.');
+      }
+      return { requirementIds: records.map(record => record.id), requirementBinding: 'explicit', reason: 'explicit-requirement-id' };
+    }
+
+    const allRecords = this.projectStore.readRequirements(projectId);
+    const explicitlyCommitted = allRecords.filter(record => record.explicitCommit === commitSha);
+    if (explicitlyCommitted.length) {
+      return {
+        requirementIds: explicitlyCommitted.map(record => record.id),
+        requirementBinding: 'explicit',
+        reason: 'explicit-commit',
+      };
+    }
+
+    if (!input.branch) return unavailable('commit-branch-unavailable');
+    const branch = String(input.branch);
+    const claimed = new Set(Array.isArray(input.claimedRequirementIds) ? input.claimedRequirementIds : []);
+    const requestedClient = input.client ? normalizeClient(input.client) : '';
+    const requestedSession = input.sessionId ? String(input.sessionId).trim() : '';
+    const candidates = [];
+    for (const record of allRecords) {
+      if (claimed.has(record.id) || !record.headAtRecord || record.branch !== branch) continue;
+      if (requestedClient && record.client !== requestedClient) continue;
+      if (requestedSession && record.sessionId !== requestedSession) continue;
+      let ancestor = false;
+      try { ancestor = await this.gitReader.isAncestor(config.repoPath, record.headAtRecord, commitSha); } catch { ancestor = false; }
+      if (ancestor) candidates.push(record);
+    }
+    if (!candidates.length) return unavailable('no-reliable-requirement');
+
+    const groups = new Map();
+    for (const record of candidates) {
+      const key = `${record.client}\u0000${record.sessionId}`;
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push(record);
+    }
+    if (groups.size !== 1) return unavailable('ambiguous-sessions');
+    const sequence = [...groups.values()][0].sort((left, right) => String(left.ts).localeCompare(String(right.ts)) || left.id.localeCompare(right.id));
+    return {
+      requirementIds: sequence.map(record => record.id),
+      requirementBinding: 'session-ancestry',
+      reason: 'unique-session-ancestry',
+    };
+  }
+}
+
+module.exports = { RequirementBinder, unavailable };