@sanqianx/project-knowledge 4.6.1

package/_site/lib/kb-framework.js

@@ -0,0 +1,191 @@
+const fs = require('fs');
+const path = require('path');
+const { migrateAIWorkspace, ensureProjectAIPath } = require('./ai-workspace');
+const { regenerateIndexes } = require('./index-builder');
+
+const PROJECT_SCHEMA_VERSION = 'minimal';
+const KB_FRAMEWORK_SCHEMA = 'minimal-kb/v1';
+const TOP_LEVEL = ['README.md', 'GOAL.md', 'ARCHITECTURE.md', 'modules', 'changes'];
+
+function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function readTemplate(name) {
+  const file = path.resolve(__dirname, '..', '..', 'templates', name);
+  if (!fs.existsSync(file)) return null;
+  return fs.readFileSync(file, 'utf-8');
+}
+
+function renderTemplate(name, vars, fallback) {
+  const tpl = readTemplate(name) || fallback;
+  return String(tpl || '').replace(/__([A-Z_][A-Z0-9_]*)__/g, (_, key) => (
+    key in vars ? String(vars[key]) : `__${key}__`
+  ));
+}
+
+function frontmatter(fields) {
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value == null || value === '') continue;
+    if (Array.isArray(value)) lines.push(`${key}: [${value.join(', ')}]`);
+    else lines.push(`${key}: ${String(value).replace(/\r?\n/g, ' ')}`);
+  }
+  lines.push('---', '');
+  return lines.join('\n');
+}
+
+function ensureFile(file, content, created, base) {
+  if (fs.existsSync(file)) return;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, 'utf-8');
+  if (created) created.push(path.relative(base, file).replace(/\\/g, '/'));
+}
+
+function initProjectDirs(slug, kbPath) {
+  const base = path.resolve(kbPath);
+  // Import only declares the external project directory. Real Markdown and
+  // collection directories are created lazily by validated promotion; an
+  // empty/TODO skeleton would turn guesses into durable project knowledge.
+  fs.mkdirSync(base, { recursive: true });
+  return {
+    created: [],
+    basePath: base,
+    kbSchemaVersion: PROJECT_SCHEMA_VERSION,
+    frameworkSchema: KB_FRAMEWORK_SCHEMA,
+    topLevel: TOP_LEVEL.slice(),
+    lazy: true,
+  };
+}
+
+function readIfExists(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : '';
+}
+
+function visibleTopLevel(kbPath) {
+  if (!fs.existsSync(kbPath)) return [];
+  return fs.readdirSync(kbPath).filter(name => !name.startsWith('.')).sort();
+}
+
+function isCurrentKb(kbPath) {
+  return fs.existsSync(path.join(kbPath, 'GOAL.md')) &&
+    fs.existsSync(path.join(kbPath, 'ARCHITECTURE.md')) &&
+    fs.existsSync(path.join(kbPath, 'modules')) &&
+    fs.existsSync(path.join(kbPath, 'changes'));
+}
+
+function consolidateLegacyCommits({ slug, kbPath }) {
+  const commitsDir = path.join(kbPath, 'commits');
+  const aiRoot = ensureProjectAIPath(slug);
+  const backupDir = path.join(aiRoot, 'legacy-commits');
+  const result = { found: 0, created: [], backupDir };
+  if (!fs.existsSync(commitsDir)) return result;
+  const files = fs.readdirSync(commitsDir).filter(f => f.endsWith('.md') && f !== '00-index.md').sort();
+  result.found = files.length;
+  if (!files.length) return result;
+  fs.mkdirSync(backupDir, { recursive: true });
+  for (const file of files) fs.copyFileSync(path.join(commitsDir, file), path.join(backupDir, file));
+  const bucketCount = Math.min(10, Math.max(1, Math.ceil(files.length / 4)));
+  const bucketSize = Math.ceil(files.length / bucketCount);
+  const changesDir = path.join(kbPath, 'changes');
+  fs.mkdirSync(changesDir, { recursive: true });
+  for (let i = 0; i < bucketCount; i++) {
+    const bucket = files.slice(i * bucketSize, (i + 1) * bucketSize);
+    if (!bucket.length) continue;
+    const rel = `legacy-change-${String(i + 1).padStart(2, '0')}.md`;
+    const title = `Legacy Change ${i + 1}`;
+    const body = [
+      frontmatter({
+        schema: KB_FRAMEWORK_SCHEMA,
+        title,
+        tags: ['legacy-migration'],
+        updatedAt: todayIso(),
+        aggregatedFrom: `[${bucket.map(f => `commits/${f}`).join(', ')}]`,
+      }),
+      `# ${title}`,
+      '',
+      '## Development Intent',
+      '',
+      'This change was generated by consolidating older per-commit records. No raw prompts are preserved.',
+      '',
+      '## Implementation Result',
+      '',
+      'Legacy commit notes were grouped into this durable change summary.',
+      '',
+      '## Evidence',
+      '',
+      ...bucket.map(file => `- \`commits/${file}\``),
+      '',
+    ].join('\n');
+    fs.writeFileSync(path.join(changesDir, rel), body, 'utf-8');
+    result.created.push(`changes/${rel}`);
+  }
+  return result;
+}
+
+function removeLegacyItems(kbPath) {
+  const removed = [];
+  const names = [
+    '_ai', 'kb-manifest.json', 'project-goal.md', 'project-analysis.md', 'framework.md',
+    'architecture', 'commits', 'features', 'operations', 'quality', 'requirements', 'references',
+  ];
+  for (const name of names) {
+    const target = path.join(kbPath, name);
+    if (fs.existsSync(target)) {
+      fs.rmSync(target, { recursive: true, force: true });
+      removed.push(name);
+    }
+  }
+  return removed;
+}
+
+function migrateToFramework({ slug, kbPath, preserveLegacyAI = true }) {
+  const base = path.resolve(kbPath);
+  fs.mkdirSync(base, { recursive: true });
+  const aiMigration = migrateAIWorkspace({ slug, kbPath: base, preserveOriginal: preserveLegacyAI });
+
+  const oldGoal = readIfExists(path.join(base, 'project-goal.md'));
+  const oldFramework = readIfExists(path.join(base, 'framework.md'));
+  const oldArch = readIfExists(path.join(base, 'architecture', 'overview.md'));
+  const oldAnalysis = readIfExists(path.join(base, 'project-analysis.md'));
+
+  const init = initProjectDirs(slug, base);
+  if (oldGoal && !oldGoal.includes('TODO: confirm the project goal')) {
+    fs.writeFileSync(path.join(base, 'GOAL.md'), oldGoal, 'utf-8');
+  }
+  const archParts = [
+    oldFramework && `## Migrated Framework\n\n${oldFramework}`,
+    oldArch && `## Migrated Architecture Overview\n\n${oldArch}`,
+    oldAnalysis && `## Migrated Project Analysis\n\n${oldAnalysis}`,
+  ].filter(Boolean);
+  if (archParts.length) {
+    fs.writeFileSync(path.join(base, 'ARCHITECTURE.md'), `${frontmatter({ schema: KB_FRAMEWORK_SCHEMA, title: `${slug} Architecture`, updatedAt: todayIso() })}# ${slug} Architecture\n\n${archParts.join('\n\n')}\n`, 'utf-8');
+  }
+  const commits = consolidateLegacyCommits({ slug, kbPath: base });
+  const removed = removeLegacyItems(base);
+  regenerateIndexes(base);
+  return {
+    ok: true,
+    slug,
+    kbPath: base,
+    kbSchemaVersion: PROJECT_SCHEMA_VERSION,
+    frameworkSchema: KB_FRAMEWORK_SCHEMA,
+    init,
+    aiMigration,
+    legacyCommits: commits,
+    removed,
+    topLevel: visibleTopLevel(base),
+  };
+}
+
+module.exports = {
+  PROJECT_SCHEMA_VERSION,
+  KB_FRAMEWORK_SCHEMA,
+  TOP_LEVEL,
+  initProjectDirs,
+  migrateToFramework,
+  consolidateLegacyCommits,
+  isCurrentKb,
+  visibleTopLevel,
+  frontmatter,
+};

package/_site/lib/kb-validator.js

@@ -0,0 +1,124 @@
+// KB Validator
+//
+// The current knowledge base framework is intentionally small:
+//
+//   README.md
+//   GOAL.md
+//   ARCHITECTURE.md
+//   modules/
+//     00-index.md
+//   changes/
+//     00-index.md
+//
+// Everything inside this layout is trusted project memory. AI run state,
+// context packs, backups, and Claude workbench sessions live under the
+// application data directory, outside the project KB.
+
+const fs = require('fs');
+const path = require('path');
+const { KB_FRAMEWORK_SCHEMA, PROJECT_SCHEMA_VERSION, TOP_LEVEL } = require('./kb-framework');
+
+function walkTrustedFiles(root, dir = root, prefix = '') {
+  const out = [];
+  let entries = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith('.')) continue;
+    if (entry.name === '_ai' || entry.name === '_meta' || entry.name === 'node_modules') continue;
+    const rel = (prefix ? `${prefix}/` : '') + entry.name;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkTrustedFiles(root, full, rel));
+    else if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push({ path: rel, content: fs.readFileSync(full, 'utf-8'), size: fs.statSync(full).size });
+    }
+  }
+  return out;
+}
+
+function validateKb(kbPath) {
+  const info = {
+    kbPath,
+    schemaVersion: PROJECT_SCHEMA_VERSION,
+    frameworkSchema: KB_FRAMEWORK_SCHEMA,
+    goalStatus: 'unknown',
+    architectureStatus: 'unknown',
+    trustedKnowledgeEntries: 0,
+  };
+
+  if (!kbPath || !fs.existsSync(kbPath)) {
+    return { ok: false, status: 400, error: `kbPath does not exist: ${kbPath}` };
+  }
+  if (!fs.statSync(kbPath).isDirectory()) {
+    return { ok: false, status: 400, error: `kbPath is not a directory: ${kbPath}` };
+  }
+
+  const errors = [];
+  const warnings = [];
+  const required = [
+    ['README.md', 'file'],
+    ['GOAL.md', 'file'],
+    ['ARCHITECTURE.md', 'file'],
+    ['modules', 'dir'],
+    ['changes', 'dir'],
+    ['modules/00-index.md', 'file'],
+    ['changes/00-index.md', 'file'],
+  ];
+  for (const [rel, kind] of required) {
+    const abs = path.join(kbPath, rel);
+    if (!fs.existsSync(abs)) {
+      errors.push(`${rel} missing`);
+      continue;
+    }
+    const stat = fs.statSync(abs);
+    if (kind === 'file' && !stat.isFile()) errors.push(`${rel} must be a file`);
+    if (kind === 'dir' && !stat.isDirectory()) errors.push(`${rel} must be a directory`);
+  }
+
+  const top = fs.readdirSync(kbPath).filter(name => !name.startsWith('.')).sort();
+  const unexpected = top.filter(name => !TOP_LEVEL.includes(name));
+  if (unexpected.length) errors.push(`unexpected top-level KB items: ${unexpected.join(', ')}`);
+  if (fs.existsSync(path.join(kbPath, '_ai'))) errors.push('_ai must not live inside a project KB');
+  if (fs.existsSync(path.join(kbPath, 'kb-manifest.json'))) errors.push('kb-manifest.json is not part of the current KB framework');
+
+  info.goalStatus = fs.existsSync(path.join(kbPath, 'GOAL.md')) ? 'present' : 'missing';
+  info.architectureStatus = fs.existsSync(path.join(kbPath, 'ARCHITECTURE.md')) ? 'present' : 'missing';
+  info.trustedKnowledgeEntries = walkTrustedFiles(kbPath).length;
+
+  return {
+    ok: errors.length === 0,
+    status: errors.length ? 422 : 200,
+    info,
+    errors,
+    warnings,
+  };
+}
+
+function buildPrContextPack(kbPath) {
+  const validation = validateKb(kbPath);
+  if (!validation.ok) return { ok: false, status: validation.status || 422, error: 'kb invalid', validation };
+  const files = walkTrustedFiles(kbPath);
+  const readFile = rel => files.find(item => item.path === rel) || null;
+  return {
+    ok: true,
+    pack: {
+      schema: 'pr-context-pack/v1',
+      frameworkSchema: KB_FRAMEWORK_SCHEMA,
+      generatedAt: new Date().toISOString(),
+      project: path.basename(kbPath),
+      goal: readFile('GOAL.md'),
+      architecture: readFile('ARCHITECTURE.md'),
+      indexes: {
+        modules: readFile('modules/00-index.md'),
+        changes: readFile('changes/00-index.md'),
+      },
+      trustedKnowledge: files,
+    },
+  };
+}
+
+module.exports = {
+  KB_FRAMEWORK_SCHEMA,
+  validateKb,
+  buildPrContextPack,
+  walkTrustedFiles,
+};

package/_site/lib/knowledge-db.js

@@ -0,0 +1,363 @@
+const fs = require('fs');
+const path = require('path');
+const lancedb = require('@lancedb/lancedb');
+const {
+  KNOWLEDGE_TABLE,
+  EMBEDDING_DIMENSIONS,
+  knowledgeChunkSchema,
+  normalizeKnowledgeChunk,
+  decodeKnowledgeChunk,
+} = require('./knowledge-schema');
+
+const FTS_SCHEMA_VERSION = 2;
+const DEFAULT_OPTIMIZE_OPERATIONS = 20;
+const DEFAULT_OPTIMIZE_ROWS = 100000;
+
+function readJson(filePath, fallback) {
+  try {
+    const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return value && typeof value === 'object' ? value : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonAtomic(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temp = `${filePath}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  fs.renameSync(temp, filePath);
+}
+
+function sqlString(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function inPredicate(column, values) {
+  const clean = Array.from(new Set((values || []).map(value => String(value).trim()).filter(Boolean)));
+  if (!clean.length) throw new Error(`${column} filter must not be empty`);
+  return `${column} IN (${clean.map(sqlString).join(', ')})`;
+}
+
+class KnowledgeDatabase {
+  constructor(options = {}) {
+    if (!options.dbPath) throw new Error('dbPath is required');
+    this.dbPath = path.resolve(options.dbPath);
+    this.tableName = options.tableName || KNOWLEDGE_TABLE;
+    this.dimensions = options.dimensions || EMBEDDING_DIMENSIONS;
+    this.maintenancePath = options.maintenancePath || `${this.dbPath}.maintenance.json`;
+    this.optimizeOperationsThreshold = Number(options.optimizeOperationsThreshold || DEFAULT_OPTIMIZE_OPERATIONS);
+    this.optimizeRowsThreshold = Number(options.optimizeRowsThreshold || DEFAULT_OPTIMIZE_ROWS);
+    this.connection = null;
+    this.table = null;
+  }
+
+  maintenanceState() {
+    return {
+      schema: 'project-knowledge/lancedb-maintenance/v1',
+      ftsSchemaVersion: 0,
+      ftsUpgradeRequired: false,
+      pendingOperations: 0,
+      pendingRows: 0,
+      lastOptimizedAt: null,
+      ...readJson(this.maintenancePath, {}),
+    };
+  }
+
+  saveMaintenanceState(patch = {}) {
+    const state = { ...this.maintenanceState(), ...patch };
+    writeJsonAtomic(this.maintenancePath, state);
+    return state;
+  }
+
+  noteMutations(input = {}) {
+    const operations = Math.max(0, Number(input.operations || 0));
+    const rows = Math.max(0, Number(input.rows || 0));
+    if (!operations && !rows) return this.maintenanceState();
+    const current = this.maintenanceState();
+    return this.saveMaintenanceState({
+      pendingOperations: current.pendingOperations + operations,
+      pendingRows: current.pendingRows + rows,
+    });
+  }
+
+  async open() {
+    if (this.table) return this;
+    fs.mkdirSync(this.dbPath, { recursive: true });
+    this.connection = await lancedb.connect(this.dbPath);
+    const names = await this.connection.tableNames();
+    this.table = names.includes(this.tableName)
+      ? await this.connection.openTable(this.tableName)
+      : await this.connection.createEmptyTable(this.tableName, knowledgeChunkSchema(this.dimensions));
+    return this;
+  }
+
+  async close() {
+    this.table = null;
+    if (this.connection) this.connection.close();
+    this.connection = null;
+  }
+
+  async count(spaceIds = null) {
+    await this.open();
+    return this.table.countRows(spaceIds ? inPredicate('space_id', spaceIds) : undefined);
+  }
+
+  async rowsForEntry(spaceId, entryId) {
+    await this.open();
+    const rows = await this.table.query()
+      .where(`space_id = ${sqlString(spaceId)} AND entry_id = ${sqlString(entryId)}`)
+      .toArray();
+    return rows.map(decodeKnowledgeChunk);
+  }
+
+  async entryIds(spaceId) {
+    await this.open();
+    const rows = await this.table.query()
+      .where(`space_id = ${sqlString(spaceId)}`)
+      .select(['entry_id'])
+      .toArray();
+    return Array.from(new Set(rows.map(row => String(row.entry_id)))).sort();
+  }
+
+  async allRows() {
+    await this.open();
+    return this.table.query().toArray();
+  }
+
+  async addRows(rows) {
+    await this.open();
+    if (!Array.isArray(rows) || !rows.length) return { ok: true, added: 0 };
+    if (await this.table.countRows()) throw new Error('bulk destination table must be empty');
+    await this.table.add(rows);
+    return { ok: true, added: rows.length };
+  }
+
+  async versions() {
+    await this.open();
+    return this.table.listVersions();
+  }
+
+  async indexDetails() {
+    await this.open();
+    const indices = await this.table.listIndices();
+    const out = [];
+    for (const index of indices) {
+      out.push({ ...index, statistics: await this.table.indexStats(index.name) });
+    }
+    return out;
+  }
+
+  async getEntry(entryId, options = {}) {
+    await this.open();
+    const predicates = [inPredicate('space_id', options.spaceIds || []), `entry_id = ${sqlString(entryId)}`];
+    if (options.spaceId) predicates.push(`space_id = ${sqlString(options.spaceId)}`);
+    const rows = await this.table.query().where(predicates.join(' AND ')).toArray();
+    return rows.map(decodeKnowledgeChunk).sort((a, b) => a.chunk_order - b.chunk_order);
+  }
+
+  async history(options = {}) {
+    await this.open();
+    const limit = Math.max(1, Math.min(Number(options.limit || 20), 100));
+    const rows = await this.table.query()
+      .where(`${inPredicate('space_id', options.spaceIds || [])} AND entry_type = 'change'`)
+      .limit(limit * 4)
+      .toArray();
+    const entries = new Map();
+    for (const row of rows.map(decodeKnowledgeChunk)) {
+      const current = entries.get(row.record_id) || row;
+      if (String(row.updated_at) > String(current.updated_at)) entries.set(row.record_id, row);
+      else if (!entries.has(row.record_id)) entries.set(row.record_id, row);
+    }
+    return Array.from(entries.values())
+      .sort((a, b) => String(b.updated_at).localeCompare(String(a.updated_at)))
+      .slice(0, limit);
+  }
+
+  async replaceEntry(spaceId, entryId, chunks) {
+    await this.open();
+    if (!Array.isArray(chunks) || chunks.length === 0) {
+      const result = await this.deleteEntry(spaceId, entryId);
+      return { ok: true, action: 'deleted', deleted: result.deleted || 0, upserted: 0 };
+    }
+    const now = new Date().toISOString();
+    const existing = await this.rowsForEntry(spaceId, entryId);
+    const existingById = new Map(existing.map(row => [row.record_id, row]));
+    const normalized = chunks.map(chunk => normalizeKnowledgeChunk({ ...chunk, spaceId, entryId }, {
+      dimensions: this.dimensions,
+      now,
+    })).map(row => ({
+      ...row,
+      created_at: existingById.get(row.record_id)?.created_at || row.created_at,
+    }));
+
+    const unchanged = existing.length === normalized.length && normalized.every(row => {
+      const old = existingById.get(row.record_id);
+      return old && old.content_hash === row.content_hash && old.source_commit === row.source_commit;
+    });
+    if (unchanged) return { ok: true, action: 'unchanged', upserted: 0, deleted: 0, total: normalized.length };
+
+    await this.table.mergeInsert('record_id')
+      .whenMatchedUpdateAll()
+      .whenNotMatchedInsertAll()
+      .execute(normalized);
+
+    const keep = new Set(normalized.map(row => row.record_id));
+    const stale = existing.filter(row => !keep.has(row.record_id));
+    if (stale.length) {
+      await this.table.delete(`record_id IN (${stale.map(row => sqlString(row.record_id)).join(', ')})`);
+    }
+    return { ok: true, action: existing.length ? 'updated' : 'created', upserted: normalized.length, deleted: stale.length, total: normalized.length };
+  }
+
+  async deleteEntry(spaceId, entryId) {
+    await this.open();
+    const before = await this.table.countRows(`space_id = ${sqlString(spaceId)} AND entry_id = ${sqlString(entryId)}`);
+    if (before) await this.table.delete(`space_id = ${sqlString(spaceId)} AND entry_id = ${sqlString(entryId)}`);
+    return { ok: true, deleted: before };
+  }
+
+  async deleteSpace(spaceId) {
+    await this.open();
+    const before = await this.table.countRows(`space_id = ${sqlString(spaceId)}`);
+    if (before) await this.table.delete(`space_id = ${sqlString(spaceId)}`);
+    return { ok: true, deleted: before };
+  }
+
+  async vectorSearch(vector, options = {}) {
+    await this.open();
+    const spaceIds = options.spaceIds || [];
+    const limit = Math.max(1, Math.min(Number(options.limit || 10), 100));
+    const query = this.table.query()
+      .nearestTo(Array.from(vector || [], Number))
+      .column('vector')
+      .distanceType('cosine')
+      .where(inPredicate('space_id', spaceIds))
+      .limit(limit);
+    const rows = await query.toArray();
+    return rows.map(decodeKnowledgeChunk);
+  }
+
+  async ensureSearchIndexes() {
+    await this.open();
+    if (await this.table.countRows() === 0) return { ok: true, created: [], skipped: 'empty-table' };
+    const existing = new Set((await this.table.listIndices()).map(index => index.name));
+    let state = this.maintenanceState();
+    const created = [];
+    // A v4.0.0 FTS index can be very large. Rebuilding it in place would keep
+    // both generations alive until Lance's old-version retention expires and
+    // could exhaust the user's disk. Mark it for the atomic rebuild workflow
+    // instead. New databases create the compact v2 index immediately.
+    if (existing.has('search_text_idx') && !existing.has('chunk_text_idx') && state.ftsSchemaVersion === 0) {
+      state = this.saveMaintenanceState({ ftsSchemaVersion: 1, ftsUpgradeRequired: true });
+    }
+    const definitions = [
+      ['space_id', 'space_id_idx', lancedb.Index.bitmap()],
+      ['entry_id', 'entry_id_idx', lancedb.Index.btree()],
+    ];
+    if (!existing.has('search_text_idx') || existing.has('chunk_text_idx')) {
+      definitions.push(['chunk_text', 'chunk_text_idx', lancedb.Index.fts({
+        baseTokenizer: 'ngram',
+        ngramMinLength: 2,
+        // Chinese bigrams preserve exact keyword recall without creating the
+        // duplicate 2/3/4-gram postings used by v4.0.0.
+        ngramMaxLength: 2,
+        withPosition: false,
+        stem: false,
+        removeStopWords: false,
+      })]);
+    }
+    for (const [column, name, config] of definitions) {
+      if (existing.has(name)) continue;
+      await this.table.createIndex(column, { name, config, replace: false, waitTimeoutSeconds: 60 });
+      created.push(name);
+    }
+    if (created.includes('chunk_text_idx') || existing.has('chunk_text_idx')) {
+      state = this.saveMaintenanceState({ ftsSchemaVersion: FTS_SCHEMA_VERSION, ftsUpgradeRequired: false });
+    }
+    return {
+      ok: true,
+      created,
+      ftsSchemaVersion: state.ftsSchemaVersion,
+      ftsUpgradeRequired: state.ftsUpgradeRequired === true,
+    };
+  }
+
+  async optimize(options = {}) {
+    await this.open();
+    return this.table.optimize(options);
+  }
+
+  async maybeOptimize(options = {}) {
+    const state = this.maintenanceState();
+    if (state.ftsUpgradeRequired === true && options.allowLegacyFts !== true) {
+      return {
+        ok: true,
+        optimized: false,
+        due: false,
+        blockedBy: 'fts-upgrade-required',
+        state,
+      };
+    }
+    const due = options.force === true
+      || state.pendingOperations >= this.optimizeOperationsThreshold
+      || state.pendingRows >= this.optimizeRowsThreshold;
+    if (!due || (!state.pendingOperations && !state.pendingRows)) {
+      return { ok: true, optimized: false, due: false, state };
+    }
+    const stats = await this.optimize();
+    const next = this.saveMaintenanceState({
+      pendingOperations: 0,
+      pendingRows: 0,
+      lastOptimizedAt: new Date().toISOString(),
+    });
+    return { ok: true, optimized: true, due: true, stats, state: next };
+  }
+
+  async fullTextSearch(text, options = {}) {
+    await this.open();
+    const queryText = String(text || '').trim();
+    if (!queryText) throw new Error('search text is required');
+    const limit = Math.max(1, Math.min(Number(options.limit || 10), 100));
+    const ftsColumn = this.maintenanceState().ftsSchemaVersion >= FTS_SCHEMA_VERSION
+      ? 'chunk_text'
+      : 'search_text';
+    const rows = await this.table.query()
+      .fullTextSearch(queryText, { columns: ftsColumn })
+      .where(inPredicate('space_id', options.spaceIds || []))
+      .limit(limit)
+      .toArray();
+    return rows.map(decodeKnowledgeChunk);
+  }
+
+  async hybridSearch(input = {}) {
+    const limit = Math.max(1, Math.min(Number(input.limit || 10), 50));
+    const candidates = Math.max(limit, Math.min(Number(input.candidates || limit * 4), 200));
+    const [semantic, keyword] = await Promise.all([
+      this.vectorSearch(input.vector, { spaceIds: input.spaceIds, limit: candidates }),
+      this.fullTextSearch(input.text, { spaceIds: input.spaceIds, limit: candidates }),
+    ]);
+    const scores = new Map();
+    const add = (rows, channel, weight) => rows.forEach((row, rank) => {
+      const current = scores.get(row.record_id) || { row, score: 0, channels: [] };
+      current.score += weight / (60 + rank + 1);
+      current.channels.push(channel);
+      scores.set(row.record_id, current);
+    });
+    add(semantic, 'semantic', Number(input.semanticWeight || 0.65));
+    add(keyword, 'keyword', Number(input.keywordWeight || 0.35));
+    return Array.from(scores.values())
+      .sort((a, b) => b.score - a.score || a.row.record_id.localeCompare(b.row.record_id))
+      .slice(0, limit)
+      .map(item => ({ ...item.row, relevance_score: item.score, match_channels: item.channels }));
+  }
+}
+
+module.exports = {
+  KnowledgeDatabase,
+  sqlString,
+  inPredicate,
+  FTS_SCHEMA_VERSION,
+  DEFAULT_OPTIMIZE_OPERATIONS,
+  DEFAULT_OPTIMIZE_ROWS,
+};