@equationalapplications/core-llm-wiki 4.18.1 → 4.20.0

package/README.md

@@ -590,6 +590,14 @@ A `WikiEdge` represents a directed link between two concepts (`source_id`, `targ
 
 See [`docs/okf-profile.md`](https://github.com/equationalapplications/expo-llm-wiki/blob/main/docs/okf-profile.md) for the full normative spec and [`packages/okf/fixtures/`](https://github.com/equationalapplications/expo-llm-wiki/tree/main/packages/okf/fixtures) for conformance bundles.
 
+`importDump` persists an imported entity summary (profile ≥ 1 bundles) and
+`exportDump` re-emits it, so the profile §4 round-trip holds across storage.
+Read it directly with `wiki.getEntitySummary(entityId)`. The value lives in the
+`{prefix}meta` table under `entity_summary:{entity_id}` and is removed by
+`forget(entityId, { clearAll: true })`. See the
+[design spec](../../docs/superpowers/specs/2026-07-05-okf-summary-persistence-design.md)
+for import/merge semantics and wipe-path cleanup.
+
 ### The `okf_type` Field
 
 Facts and tasks include a nullable `okf_type` column. This preserves the literal OKF `type` string from an imported bundle frontmatter, independent of whether the item was routed to the `entries` or `tasks` table. When `formatOkfBundle` runs, it restores this specific string, falling back to `'fact'` or `'task'` if the field is null (ensuring non-imported rows export cleanly).
@@ -838,6 +846,31 @@ const adapter: SQLiteAdapter = {
 };
 ```
 
+## Concurrency
+
+All write APIs are safe to call from concurrent async contexts. Transactions are
+serialized internally on the single database connection — you never need to know that
+SQLite forbids nested `BEGIN`, and you never need to throttle callers yourself.
+
+- One connection per database file per process is the supported topology.
+- Non-transactional reads are **not** serialized, so read latency is unaffected.
+- Inside a transaction callback, use only the provided `tx` handle — never the outer
+  database handle. Using the outer handle deadlocks; opening a nested transaction throws.
+
+### `WikiTransactionError`
+
+Thrown when a SQLite driver error escapes a transaction (nested `BEGIN`,
+`SQLITE_BUSY`, constraint violation). Stable `instanceof` target for observability:
+
+- `error.cause` — the original driver error (the chain bottoms out here, not at a
+  rollback red herring).
+- `error.sqliteErrorCode` — best-effort SQLite code (e.g. `'SQLITE_BUSY'`), present
+  when it can be parsed. Group on this in Sentry/Datadog instead of inspecting
+  `error.cause` recursively.
+
+Domain errors thrown from your own callback logic (validation, `WikiBusyError`)
+pass through unwrapped with their original type intact.
+
 ## How It Works
 
 ```mermaid

package/dist/{chunk-V7QNRQFK.mjs → chunk-HKB5FEJG.mjs}

@@ -8,6 +8,83 @@ var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read fr
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 
+// src/db/sqliteCodes.ts
+var SQLITE_RESULT_CODE_NAMES = {
+  1: "SQLITE_ERROR",
+  2: "SQLITE_INTERNAL",
+  3: "SQLITE_PERM",
+  4: "SQLITE_ABORT",
+  5: "SQLITE_BUSY",
+  6: "SQLITE_LOCKED",
+  7: "SQLITE_NOMEM",
+  8: "SQLITE_READONLY",
+  9: "SQLITE_INTERRUPT",
+  10: "SQLITE_IOERR",
+  11: "SQLITE_CORRUPT",
+  12: "SQLITE_NOTFOUND",
+  13: "SQLITE_FULL",
+  14: "SQLITE_CANTOPEN",
+  15: "SQLITE_PROTOCOL",
+  16: "SQLITE_EMPTY",
+  17: "SQLITE_SCHEMA",
+  18: "SQLITE_TOOBIG",
+  19: "SQLITE_CONSTRAINT",
+  20: "SQLITE_MISMATCH",
+  21: "SQLITE_MISUSE",
+  22: "SQLITE_NOLFS",
+  23: "SQLITE_AUTH",
+  24: "SQLITE_FORMAT",
+  25: "SQLITE_RANGE",
+  26: "SQLITE_NOTADB",
+  27: "SQLITE_NOTICE",
+  28: "SQLITE_WARNING",
+  100: "SQLITE_ROW",
+  101: "SQLITE_DONE"
+};
+function nameForSqliteResultCode(n) {
+  return SQLITE_RESULT_CODE_NAMES[n] ?? `SQLITE_${n}`;
+}
+function extractSqliteCode(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const { code, message } = err;
+  if (typeof code === "string" && code.startsWith("SQLITE_")) return code;
+  if (typeof message === "string") {
+    const m = /^Error code (\d+):/.exec(message);
+    if (m) return nameForSqliteResultCode(Number(m[1]));
+  }
+  return void 0;
+}
+
+// src/types.ts
+var WikiBusyError = class extends Error {
+  constructor(operation, entityId) {
+    super(`${operation} already running for entity ${entityId}`);
+    this.name = "WikiBusyError";
+    this.operation = operation;
+    this.entityId = entityId;
+  }
+};
+var WikiTransactionError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "WikiTransactionError";
+    this.sqliteErrorCode = extractSqliteCode(options.cause);
+  }
+};
+var PrunePartialFailureError = class extends Error {
+  constructor(deleted, failedAt, remaining, cause, deletedTasks = 0, deletedEvents = 0) {
+    super(`Prune partially failed: deleted ${deleted}, failed at ${failedAt}, ${remaining} remaining`);
+    this.name = "PrunePartialFailureError";
+    this.deleted = deleted;
+    this.failedAt = failedAt;
+    this.remaining = remaining;
+    this.deletedTasks = deletedTasks;
+    this.deletedEvents = deletedEvents;
+    this.cause = cause;
+  }
+};
+var HOOK_TIMEOUT_MARKER = /* @__PURE__ */ Symbol("WikiMemoryHookTimeout");
+
 // src/utils/ids.ts
 var _injectedGetRandomValues = null;
 function configureRandomSource(fn) {
@@ -278,29 +355,6 @@ _SearchService.MAX_VECTOR_CACHE_ENTITIES = 16;
 _SearchService.MAX_VECTOR_CACHE_FACTS_PER_ENTITY = 500;
 var SearchService = _SearchService;
 
-// src/types.ts
-var WikiBusyError = class extends Error {
-  constructor(operation, entityId) {
-    super(`${operation} already running for entity ${entityId}`);
-    this.name = "WikiBusyError";
-    this.operation = operation;
-    this.entityId = entityId;
-  }
-};
-var PrunePartialFailureError = class extends Error {
-  constructor(deleted, failedAt, remaining, cause, deletedTasks = 0, deletedEvents = 0) {
-    super(`Prune partially failed: deleted ${deleted}, failed at ${failedAt}, ${remaining} remaining`);
-    this.name = "PrunePartialFailureError";
-    this.deleted = deleted;
-    this.failedAt = failedAt;
-    this.remaining = remaining;
-    this.deletedTasks = deletedTasks;
-    this.deletedEvents = deletedEvents;
-    this.cause = cause;
-  }
-};
-var HOOK_TIMEOUT_MARKER = /* @__PURE__ */ Symbol("WikiMemoryHookTimeout");
-
 // src/services/JobManager.ts
 var JobManager = class {
   constructor(prefix) {
@@ -1156,6 +1210,169 @@ var IngestionService = class {
   }
 };
 
+// src/repositories/BaseRepository.ts
+var BaseRepository = class {
+  constructor(db, prefix) {
+    this.db = db;
+    this.prefix = prefix;
+  }
+  /**
+   * Return the DB executor for a given transaction handle.
+   * If tx is provided, use it; otherwise fall back to this.db.
+   */
+  getExecutor(tx) {
+    return tx ?? this.db;
+  }
+};
+
+// src/repositories/MetadataRepository.ts
+function entitySummaryMetaKey(entityId) {
+  return `entity_summary:${entityId}`;
+}
+var MetadataRepository = class extends BaseRepository {
+  // CHECKPOINTS TABLE METHODS
+  async getCheckpoint(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT memory_checkpoint, heal_checkpoint FROM ${this.prefix}checkpoints WHERE entity_id = ?`,
+      [entityId]
+    );
+    if (!row) return {};
+    return {
+      memory: row.memory_checkpoint ?? void 0,
+      heal: row.heal_checkpoint ?? void 0
+    };
+  }
+  async updateCheckpoint(entityId, updates, tx) {
+    const fields = [];
+    const values = [];
+    if (updates.memory !== void 0) {
+      fields.push("memory_checkpoint = ?");
+      values.push(updates.memory);
+    }
+    if (updates.heal !== void 0) {
+      fields.push("heal_checkpoint = ?");
+      values.push(updates.heal);
+    }
+    if (fields.length === 0) return;
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}checkpoints (entity_id, memory_checkpoint, heal_checkpoint)
+       VALUES (?, ?, ?)
+       ON CONFLICT(entity_id) DO UPDATE SET ${fields.join(", ")}`,
+      [entityId, updates.memory ?? 0, updates.heal ?? 0, ...values]
+    );
+  }
+  async deleteCheckpoint(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `DELETE FROM ${this.prefix}checkpoints WHERE entity_id = ?`,
+      [entityId]
+    );
+  }
+  // META TABLE METHODS
+  async getMeta(key, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT value FROM ${this.prefix}meta WHERE key = ?`,
+      [key]
+    );
+    return row ? row.value : null;
+  }
+  async setMeta(key, value, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}meta (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value`,
+      [key, value]
+    );
+  }
+  async deleteMeta(key, tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `DELETE FROM ${this.prefix}meta WHERE key = ?`,
+      [key]
+    );
+  }
+  async clearDimensionMismatch(tx) {
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `DELETE FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
+    );
+  }
+  async tableExists(tableName, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT name FROM sqlite_master WHERE type='table' AND name=?`,
+      [tableName]
+    );
+    return row != null;
+  }
+  async getTableDdl(tableName, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(
+      `SELECT sql FROM sqlite_master WHERE type='table' AND name=?`,
+      [tableName]
+    );
+    return row?.sql ?? null;
+  }
+  async vacuum() {
+    await this.db.execAsync(`PRAGMA wal_checkpoint(TRUNCATE)`);
+    await this.db.execAsync(`VACUUM`);
+  }
+  async getDistinctEntityIds(tx) {
+    const executor = this.getExecutor(tx);
+    const rows = await executor.getAllAsync(
+      `SELECT DISTINCT entity_id FROM (
+         SELECT entity_id FROM ${this.prefix}entries WHERE deleted_at IS NULL
+         UNION
+         SELECT entity_id FROM ${this.prefix}tasks WHERE deleted_at IS NULL
+         UNION
+         SELECT entity_id FROM ${this.prefix}events
+       ) ORDER BY entity_id`
+    );
+    return rows.map((r) => r.entity_id);
+  }
+  async getManifest(entityId, tx) {
+    const executor = this.getExecutor(tx);
+    const row = await executor.getFirstAsync(`SELECT mode, manifest_json FROM ${this.prefix}entity_manifests WHERE entity_id = ?`, [entityId]);
+    if (!row) return null;
+    if (row.mode !== "off" && row.mode !== "strict" && row.mode !== "emergent") {
+      throw new Error(`Invalid ontology mode for entity ${entityId}: ${JSON.stringify(row.mode)}`);
+    }
+    let manifest;
+    try {
+      manifest = JSON.parse(row.manifest_json);
+    } catch (error) {
+      throw new Error(`Invalid manifest_json for entity ${entityId}: ${error.message}`);
+    }
+    validateManifest(manifest);
+    return {
+      mode: row.mode,
+      manifest
+    };
+  }
+  async setManifest(entityId, data, tx) {
+    validateManifest(data.manifest);
+    const executor = this.getExecutor(tx);
+    await executor.runAsync(
+      `INSERT INTO ${this.prefix}entity_manifests (entity_id, mode, manifest_json, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(entity_id) DO UPDATE SET mode = excluded.mode, manifest_json = excluded.manifest_json, updated_at = excluded.updated_at`,
+      [entityId, data.mode, JSON.stringify(data.manifest), Date.now()]
+    );
+  }
+  async mergeManifestUpdates(entityId, updates, tx) {
+    const current = await this.getManifest(entityId, tx) ?? {
+      mode: "emergent",
+      manifest: emptyManifest()
+    };
+    const merged = mergeOntologyUpdates(current.manifest, updates);
+    await this.setManifest(entityId, { mode: current.mode, manifest: merged }, tx);
+    return merged;
+  }
+};
+
 // src/services/MaintenanceService.ts
 var FUZZY_THRESHOLD = 0.5;
 var MIN_TOKENS_TO_QUALIFY = 3;
@@ -1331,6 +1548,7 @@ var MaintenanceService = class {
           deletedEntries = await this.entryRepo.bulkSoftDeleteByEntityId(entityId, tx);
           deletedTasks = await this.taskRepo.bulkSoftDeleteByEntityId(entityId, tx);
           await this.metadataRepo.updateCheckpoint(entityId, { memory: 0, heal: 0 }, tx);
+          await this.metadataRepo.deleteMeta(entitySummaryMetaKey(entityId), tx);
         } else {
           const hasIdSelectors = params.entryId !== void 0 || params.taskId !== void 0;
           const hasSourceSelectors = params.sourceRef !== void 0 || params.sourceHash !== void 0;
@@ -1679,11 +1897,12 @@ var ImportExportService = class {
     }
   }
   async getFullBundle(entityId, opts) {
-    const [factsRaw, tasks, events, edges] = await Promise.all([
+    const [factsRaw, tasks, events, edges, summaryValue] = await Promise.all([
       opts?.includeBlobs ? this.entryRepo.findAllByEntityIdWithBlobs(entityId) : this.entryRepo.findAllByEntityId(entityId),
       this.taskRepo.findAllByEntityId(entityId),
       this.eventRepo.getByEntityId(entityId, opts?.maxEvents),
-      this.edgeRepo.getByEntityId(entityId)
+      this.edgeRepo.getByEntityId(entityId),
+      this.metadataRepo.getMeta(entitySummaryMetaKey(entityId))
     ]);
     const facts = factsRaw.map((f) => {
       const {
@@ -1702,7 +1921,13 @@ var ImportExportService = class {
         tags: typeof factBase.tags === "string" ? JSON.parse(factBase.tags) : factBase.tags
       };
     });
-    return { facts, tasks, events, edges };
+    return {
+      facts,
+      tasks,
+      events,
+      edges,
+      ...summaryValue != null ? { summary: summaryValue } : {}
+    };
   }
   /** Single-entity import transaction + post-processing; package-internal hook for tests. */
   async doImportEntity(entityId, bundle, merge) {
@@ -1727,6 +1952,11 @@ var ImportExportService = class {
         await this.edgeRepo.bulkDeleteByEntityId(entityId, tx);
         await this.metadataRepo.deleteCheckpoint(entityId, tx);
       }
+      if (bundle.summary !== void 0) {
+        await this.metadataRepo.setMeta(entitySummaryMetaKey(entityId), bundle.summary, tx);
+      } else if (!merge) {
+        await this.metadataRepo.deleteMeta(entitySummaryMetaKey(entityId), tx);
+      }
       const factIds = bundle.facts.map((fact) => fact.id);
       const existingFactsById = /* @__PURE__ */ new Map();
       const existingFacts = await this.entryRepo.findExistingMetadataByIds(
@@ -2815,6 +3045,6 @@ var WriteService = class {
   }
 };
 
-export { EmbeddingService, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WriteService, __privateAdd, __privateGet, __privateSet, configureRandomSource, emptyManifest, generateId, mergeOntologyUpdates, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinition, resolveNodeType, validateInlineEdges, validateManifest };
-//# sourceMappingURL=chunk-V7QNRQFK.mjs.map
-//# sourceMappingURL=chunk-V7QNRQFK.mjs.map
+export { BaseRepository, EmbeddingService, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinition, resolveNodeType, validateInlineEdges };
+//# sourceMappingURL=chunk-HKB5FEJG.mjs.map
+//# sourceMappingURL=chunk-HKB5FEJG.mjs.map