@sanqianx/project-knowledge 4.6.1

package/_site/lib/project-registry-store.js

@@ -0,0 +1,129 @@
+const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
+const AtomicFile = require('./atomic-file');
+const { StorageLayout } = require('./storage-layout');
+
+function emptyRegistry() {
+  return {
+    schema: SCHEMAS.projectRegistry,
+    schemaVersion: 2,
+    projectOrder: [],
+    projects: {},
+    revision: 0,
+    updatedAt: '',
+  };
+}
+
+function validateRegistry(registry) {
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
+    throw new DomainError('DATA_CORRUPT', 'Project registry must be an object.', { status: 500 });
+  }
+  if (registry.schema !== SCHEMAS.projectRegistry || registry.schemaVersion !== 2) {
+    throw new DomainError('SCHEMA_UNSUPPORTED', 'Unsupported project registry schema.', { status: 409 });
+  }
+  if (!Array.isArray(registry.projectOrder) || !registry.projects || typeof registry.projects !== 'object') {
+    throw new DomainError('DATA_CORRUPT', 'Project registry index is invalid.', { status: 500 });
+  }
+  const ordered = new Set();
+  for (const projectId of registry.projectOrder) {
+    validateProjectId(projectId);
+    if (ordered.has(projectId) || !registry.projects[projectId]) {
+      throw new DomainError('DATA_CORRUPT', 'Project registry order is inconsistent.', { status: 500 });
+    }
+    ordered.add(projectId);
+  }
+  for (const projectId of Object.keys(registry.projects)) {
+    validateProjectId(projectId);
+    if (!ordered.has(projectId)) throw new DomainError('DATA_CORRUPT', 'Project registry contains an unordered project.', { status: 500 });
+  }
+  return registry;
+}
+
+class ProjectRegistryStore {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.atomic = options.atomic || AtomicFile;
+    this.filePath = options.filePath || this.layout.getProjectRegistryPath();
+    this.lockPath = options.lockPath || this.layout.getRegistryLockPath();
+  }
+
+  read(options = {}) {
+    return this.atomic.readJsonStrict(this.filePath, {
+      allowMissing: options.allowMissing === true,
+      defaultValue: emptyRegistry(),
+      category: 'project-registry',
+      validate: validateRegistry,
+    });
+  }
+
+  async initialize() {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      let existing;
+      try { existing = this.read(); } catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
+      if (existing) return existing;
+      const registry = emptyRegistry();
+      registry.updatedAt = new Date().toISOString();
+      this.atomic.writeJsonAtomic(this.filePath, registry);
+      return registry;
+    });
+  }
+
+  listIds() { return [...this.read({ allowMissing: true }).projectOrder]; }
+
+  readDisplaySnapshot(projectId) {
+    validateProjectId(projectId);
+    const registry = this.read({ allowMissing: true });
+    return registry.projects[projectId] || null;
+  }
+
+  async add(projectId, snapshot = {}) {
+    validateProjectId(projectId);
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      const registry = this.read({ allowMissing: true });
+      if (registry.projects[projectId]) {
+        throw new DomainError('INVALID_ARGUMENT', 'Project is already registered.', { status: 409 });
+      }
+      registry.projects[projectId] = {
+        createdAt: String(snapshot.createdAt || new Date().toISOString()),
+        displayNameSnapshot: String(snapshot.displayNameSnapshot || snapshot.displayName || projectId),
+      };
+      registry.projectOrder.push(projectId);
+      registry.revision = Number(registry.revision || 0) + 1;
+      registry.updatedAt = new Date().toISOString();
+      validateRegistry(registry);
+      this.atomic.writeJsonAtomic(this.filePath, registry);
+      return registry.projects[projectId];
+    });
+  }
+
+  async remove(projectId) {
+    validateProjectId(projectId);
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      const registry = this.read({ allowMissing: true });
+      if (!registry.projects[projectId]) return false;
+      delete registry.projects[projectId];
+      registry.projectOrder = registry.projectOrder.filter(id => id !== projectId);
+      registry.revision = Number(registry.revision || 0) + 1;
+      registry.updatedAt = new Date().toISOString();
+      validateRegistry(registry);
+      this.atomic.writeJsonAtomic(this.filePath, registry);
+      return true;
+    });
+  }
+
+  async reorder(projectIds) {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      const registry = this.read({ allowMissing: true });
+      const next = Array.isArray(projectIds) ? projectIds.map(validateProjectId) : [];
+      if (next.length !== registry.projectOrder.length || new Set(next).size !== next.length || next.some(id => !registry.projects[id])) {
+        throw new DomainError('INVALID_ARGUMENT', 'Reorder must contain every registered project exactly once.');
+      }
+      registry.projectOrder = next;
+      registry.revision = Number(registry.revision || 0) + 1;
+      registry.updatedAt = new Date().toISOString();
+      this.atomic.writeJsonAtomic(this.filePath, registry);
+      return [...next];
+    });
+  }
+}
+
+module.exports = { ProjectRegistryStore, emptyRegistry, validateRegistry };

package/_site/lib/project-store.js

@@ -0,0 +1,262 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const {
+  SCHEMAS,
+  DomainError,
+  assertMutableProjectPatch,
+  validateProjectId,
+} = require('./contracts');
+const AtomicFile = require('./atomic-file');
+const { StorageLayout } = require('./storage-layout');
+
+const processQueues = new Map();
+
+function defaultProjectConfig(projectId, input = {}) {
+  validateProjectId(projectId);
+  const createdAt = String(input.createdAt || new Date().toISOString());
+  return {
+    schema: SCHEMAS.projectConfig,
+    schemaVersion: 2,
+    projectId,
+    displayName: String(input.displayName || projectId),
+    storageName: String(input.storageName || projectId),
+    repoPath: path.resolve(String(input.repoPath || '.')),
+    knowledgePath: path.resolve(String(input.knowledgePath || '.')),
+    enabled: input.enabled !== false,
+    createdAt,
+    teamBinding: input.teamBinding || null,
+    aiProfileId: input.aiProfileId || null,
+    knowledgeLanguage: input.knowledgeLanguage || 'zh-CN',
+    relatedProjectIds: Array.isArray(input.relatedProjectIds) ? [...new Set(input.relatedProjectIds)] : [],
+    repoIdentity: input.repoIdentity || null,
+    legacyExtensions: input.legacyExtensions || {},
+  };
+}
+
+function defaultProjectState(input = {}) {
+  return {
+    schema: SCHEMAS.projectState,
+    schemaVersion: 2,
+    revision: Number.isInteger(input.revision) ? input.revision : 0,
+    trackingStartCommit: input.trackingStartCommit || null,
+    lastAnalyzedCommit: input.lastAnalyzedCommit || null,
+    conversationBaselineCursor: Number.isInteger(input.conversationBaselineCursor) && input.conversationBaselineCursor >= 0
+      ? input.conversationBaselineCursor
+      : null,
+    conversation: {
+      lastConsumedCursor: Number.isInteger(input.conversation && input.conversation.lastConsumedCursor)
+        ? input.conversation.lastConsumedCursor
+        : null,
+      captureStatus: input.conversation && input.conversation.captureStatus || 'unavailable',
+      lastError: input.conversation && input.conversation.lastError || null,
+    },
+    trackingMode: input.trackingMode === 'empty-repo' ? 'empty-repo' : 'normal',
+    analysis: {
+      status: input.analysis && input.analysis.status || 'idle',
+      activeClaim: input.analysis && input.analysis.activeClaim || null,
+      lastError: input.analysis && input.analysis.lastError || null,
+      rescanRequested: input.analysis && input.analysis.rescanRequested === true,
+    },
+    index: {
+      dirty: input.index && input.index.dirty === true,
+      generation: Number(input.index && input.index.generation || 0),
+      sinceCommit: input.index && input.index.sinceCommit || null,
+      lastError: input.index && input.index.lastError || null,
+    },
+    hook: {
+      managedVersion: Number(input.hook && input.hook.managedVersion || 0),
+      migrationVersion: Number(input.hook && input.hook.migrationVersion || 0),
+      lastVerifiedAt: input.hook && input.hook.lastVerifiedAt || '',
+    },
+    updatedAt: input.updatedAt || new Date().toISOString(),
+  };
+}
+
+function validateProjectConfig(config, expectedProjectId) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new DomainError('DATA_CORRUPT', 'Project config is invalid.', { status: 500 });
+  if (config.schema !== SCHEMAS.projectConfig || config.schemaVersion !== 2) throw new DomainError('SCHEMA_UNSUPPORTED', 'Unsupported project config schema.', { status: 409 });
+  validateProjectId(config.projectId);
+  if (expectedProjectId && config.projectId !== expectedProjectId) throw new DomainError('DATA_CORRUPT', 'Project config identity mismatch.', { status: 500 });
+  if (!config.storageName || !config.repoPath || !config.knowledgePath || !config.createdAt) throw new DomainError('DATA_CORRUPT', 'Project config is incomplete.', { status: 500 });
+  return config;
+}
+
+function validateProjectState(state) {
+  if (!state || typeof state !== 'object' || Array.isArray(state)) throw new DomainError('DATA_CORRUPT', 'Project state is invalid.', { status: 500 });
+  if (state.schema !== SCHEMAS.projectState || state.schemaVersion !== 2) throw new DomainError('SCHEMA_UNSUPPORTED', 'Unsupported project state schema.', { status: 409 });
+  if (!Number.isInteger(state.revision) || !state.analysis || !state.index || !state.hook) throw new DomainError('DATA_CORRUPT', 'Project state is incomplete.', { status: 500 });
+  if (!['normal', 'empty-repo'].includes(state.trackingMode)) throw new DomainError('DATA_CORRUPT', 'Project tracking mode is invalid.', { status: 500 });
+  if (!Object.prototype.hasOwnProperty.call(state, 'conversationBaselineCursor')) state.conversationBaselineCursor = null;
+  if (!state.conversation || typeof state.conversation !== 'object') {
+    state.conversation = { lastConsumedCursor: null, captureStatus: 'unavailable', lastError: null };
+  }
+  return state;
+}
+
+class ProjectStore {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.atomic = options.atomic || AtomicFile;
+  }
+
+  async withProjectLock(projectId, fn, options = {}) {
+    validateProjectId(projectId);
+    const previous = processQueues.get(projectId) || Promise.resolve();
+    let releaseQueue;
+    const current = new Promise(resolve => { releaseQueue = resolve; });
+    const queued = previous.then(() => current);
+    processQueues.set(projectId, queued);
+    await previous;
+    try {
+      return await this.atomic.withFileLock(this.layout.getProjectLockPath(projectId), fn, options);
+    } finally {
+      releaseQueue();
+      if (processQueues.get(projectId) === queued) processQueues.delete(projectId);
+    }
+  }
+
+  readConfig(projectId) {
+    validateProjectId(projectId);
+    return this.atomic.readJsonStrict(this.layout.getProjectConfigPath(projectId), {
+      category: 'project-config',
+      validate: config => validateProjectConfig(config, projectId),
+    });
+  }
+
+  readState(projectId) {
+    validateProjectId(projectId);
+    return this.atomic.readJsonStrict(this.layout.getProjectStatePath(projectId), {
+      category: 'project-state',
+      validate: validateProjectState,
+    });
+  }
+
+  async create(projectId, configInput, stateInput = {}) {
+    validateProjectId(projectId);
+    return this.withProjectLock(projectId, async () => {
+      const dir = this.layout.getProjectMetadataDir(projectId);
+      const configPath = this.layout.getProjectConfigPath(projectId);
+      const statePath = this.layout.getProjectStatePath(projectId);
+      if (fs.existsSync(configPath) || fs.existsSync(statePath)) throw new DomainError('INVALID_ARGUMENT', 'Project metadata already exists.', { status: 409 });
+      fs.mkdirSync(dir, { recursive: true });
+      const config = validateProjectConfig(defaultProjectConfig(projectId, configInput), projectId);
+      const state = validateProjectState(defaultProjectState(stateInput));
+      try {
+        this.atomic.writeJsonAtomic(configPath, config);
+        this.atomic.writeJsonAtomic(statePath, state);
+      } catch (error) {
+        try { if (fs.existsSync(configPath)) fs.unlinkSync(configPath); } catch {
+          // Preserve the original create error; the lifecycle journal records rollback residue.
+        }
+        try { if (fs.existsSync(statePath)) fs.unlinkSync(statePath); } catch {
+          // Preserve the original create error; the lifecycle journal records rollback residue.
+        }
+        throw error;
+      }
+      return { config, state };
+    });
+  }
+
+  async updateConfig(projectId, patch, options = {}) {
+    validateProjectId(projectId);
+    assertMutableProjectPatch(patch, {
+      allowKnowledgePath: options.allowKnowledgePath === true,
+      allowRepoPath: options.allowRepoPath === true,
+    });
+    return this.withProjectLock(projectId, async () => {
+      const current = this.readConfig(projectId);
+      const next = { ...current, ...patch, projectId: current.projectId, storageName: current.storageName, createdAt: current.createdAt };
+      validateProjectConfig(next, projectId);
+      this.atomic.writeJsonAtomic(this.layout.getProjectConfigPath(projectId), next);
+      return next;
+    });
+  }
+
+  /**
+   * Deliberate one-way upgrade: write a canonical repo-identity/v1 onto a
+   * project that was imported before v4.2.3 (repoIdentity null or a legacy
+   * { commonDir }-only shape). Only the Bridge consumer migration calls
+   * this; it is intentionally not reachable through the generic config
+   * update path. Rewrites are refused once a v1 identity exists.
+   */
+  async migrateRepoIdentity(projectId, repoIdentity) {
+    validateProjectId(projectId);
+    if (!repoIdentity || typeof repoIdentity !== 'object'
+      || repoIdentity.schema !== 'repo-identity/v1'
+      || typeof repoIdentity.workspaceId !== 'string'
+      || typeof repoIdentity.workspaceRoot !== 'string' || !repoIdentity.workspaceRoot) {
+      throw new DomainError('INVALID_ARGUMENT', 'migrateRepoIdentity requires a canonical repo-identity/v1 object.');
+    }
+    return this.withProjectLock(projectId, async () => {
+      const current = this.readConfig(projectId);
+      if (current.repoIdentity && typeof current.repoIdentity.workspaceId === 'string') {
+        return current;
+      }
+      const next = { ...current, repoIdentity };
+      validateProjectConfig(next, projectId);
+      this.atomic.writeJsonAtomic(this.layout.getProjectConfigPath(projectId), next);
+      return next;
+    });
+  }
+
+  async updateState(projectId, updater, options = {}) {
+    validateProjectId(projectId);
+    if (typeof updater !== 'function') throw new DomainError('INVALID_ARGUMENT', 'State updater must be a function.');
+    return this.withProjectLock(projectId, async () => {
+      const current = this.readState(projectId);
+      if (Number.isInteger(options.expectedRevision) && current.revision !== options.expectedRevision) {
+        throw new DomainError('PROJECT_BUSY', 'Project state revision changed.', { status: 409, retryable: true });
+      }
+      const draft = JSON.parse(JSON.stringify(current));
+      const updated = await updater(draft);
+      const next = updated && typeof updated === 'object' ? updated : draft;
+      next.schema = SCHEMAS.projectState;
+      next.schemaVersion = 2;
+      next.revision = current.revision + 1;
+      next.updatedAt = new Date().toISOString();
+      validateProjectState(next);
+      this.atomic.writeJsonAtomic(this.layout.getProjectStatePath(projectId), next);
+      return next;
+    });
+  }
+
+  async appendRequirement(projectId, record) {
+    validateProjectId(projectId);
+    if (!record || typeof record !== 'object' || record.schema !== SCHEMAS.requirement || record.projectId !== projectId || !record.id) {
+      throw new DomainError('INVALID_ARGUMENT', 'Requirement record is invalid.');
+    }
+    const filePath = this.layout.getProjectRequirementsPath(projectId);
+    await this.atomic.appendJsonlLocked(filePath, record, { lockPath: `${filePath}.append.lock` });
+    return record;
+  }
+
+  readRequirements(projectId) {
+    validateProjectId(projectId);
+    const filePath = this.layout.getProjectRequirementsPath(projectId);
+    if (!fs.existsSync(filePath)) return [];
+    const records = [];
+    const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      if (!lines[index].trim()) continue;
+      try {
+        const record = JSON.parse(lines[index]);
+        if (record.schema !== SCHEMAS.requirement || record.projectId !== projectId) throw new Error('schema or project mismatch');
+        records.push(record);
+      } catch (error) {
+        throw new DomainError('DATA_CORRUPT', 'Requirements JSONL is corrupt.', { status: 500, cause: error, details: { line: index + 1 } });
+      }
+    }
+    return records;
+  }
+
+  generateRequirementId() { return `req-${crypto.randomUUID()}`; }
+}
+
+module.exports = {
+  ProjectStore,
+  defaultProjectConfig,
+  defaultProjectState,
+  validateProjectConfig,
+  validateProjectState,
+};

package/_site/lib/prompt-registry.js

@@ -0,0 +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,
+};

package/_site/lib/requirement-adapters.js

@@ -0,0 +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 };

package/_site/lib/requirement-binder.js

@@ -0,0 +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 };