@equationalapplications/core-llm-wiki 7.1.2 → 7.1.3

package/README.md

@@ -1016,6 +1016,33 @@ const { nodesWritten, edgesWritten, superseded } = await wikiMemory.upsertGraph(
 
 `upsertGraph` is "the tail of `ingestDocument` with the middle (LLM extraction) step removed" — it accepts caller-supplied nodes (`{ id, type, title, body? }`) and edges (`{ type, sourceId, targetId, id? }`) and writes them under the same `(sourceRef, sourceHash)` semantics. If a *different* live `sourceRef` already holds the same `sourceHash`, it throws `WikiSourceRefHashCollision`; re-writing the identical `(sourceRef, sourceHash)` is a no-op returning zero counts. The adapter parameter is required so writes participate in the caller's transaction.
 
+Entry IDs occupy one globally shared namespace within a database. An ID belongs
+to its existing entity while its row exists, including after soft deletion.
+Same-entity updates and resurrection retain their existing behavior; physically
+absent IDs may be inserted. Hosts remain responsible for authenticating callers
+and selecting the authorized entity ID. Entity-qualified deterministic IDs can
+avoid accidental collisions, but are not required by the API.
+
+A foreign node ID rejects the entire non-no-op graph write with
+`WikiGraphNodeOwnershipConflict` (code `WIKI_GRAPH_NODE_OWNERSHIP_CONFLICT`).
+The error does not identify the owner, conflicting node, or stored details.
+A collision visible to node preflight performs no persistent writes, including
+seed-manifest writes. The live source-hash probe still runs first: an identical
+mapping is a zero-count no-op; a different live reference retains its hash
+collision error. Deleted source-reference mappings do not trigger that probe.
+
+Call `upsertGraph` inside the host transaction and pass that callback's `tx`.
+It neither starts nor ends a transaction. Propagate later failures so the host
+transaction rolls back partial writes; catching a late error and committing is
+not atomic. Foreign edge-ID collisions retain their existing late bare `Error`
+and require host rollback, even though the foreign edge is never overwritten.
+
+`ingestDocument` shares ownership enforcement on both its full and partial paths
+and may also throw `WikiGraphNodeOwnershipConflict`. It normally generates new
+IDs, so collisions are unexpected. Unlike direct graph preflight, ingestion may
+already have persisted ontology or other state when rejection occurs; its
+transaction rollback, not a zero-write preflight guarantee, protects atomicity.
+
 ## Duplicate Hash Detection
 
 Control behavior when a different live `sourceRef` already holds the same `sourceHash`. The option is passed as a third argument to `ingestDocument`, not inside the params object:
@@ -1115,11 +1142,17 @@ export interface SQLiteAdapter {
   runAsync(sql: string, params?: unknown[]): Promise<{ changes: number; lastInsertRowId: number }>;
   getAllAsync<T>(sql: string, params?: unknown[]): Promise<T[]>;
   getFirstAsync<T>(sql: string, params?: unknown[]): Promise<T | null>;
-  withTransactionAsync<T>(fn: () => Promise<T>): Promise<T>;
+  withTransactionAsync<T>(fn: (tx: SQLiteAdapter) => Promise<T>): Promise<T>;
   closeAsync(): Promise<void>;
 }
 ```
 
+`runAsync().changes` must accurately count written rows: a conflict-suppressed
+write reports 0, while a permitted value-identical update still counts its row.
+Host adapters are responsible for this contract; see the full affected-row
+requirements on [`SQLiteAdapter.runAsync`](src/types.ts). Ownership checks,
+edge counts, metadata compare-and-set, and maintenance depend on accurate counts.
+
 `@equationalapplications/expo-llm-wiki` provides a pre-built adapter for Expo/React Native. For web and Node.js, implement the interface yourself — examples below.
 
 **Browser ([sql.js](https://github.com/sql-js/sql.js)):**
@@ -1155,7 +1188,7 @@ const adapter: SQLiteAdapter = {
   },
   async withTransactionAsync(fn) {
     sqlDb.run('BEGIN');
-    try { const r = await fn(); sqlDb.run('COMMIT'); return r; }
+    try { const r = await fn(this); sqlDb.run('COMMIT'); return r; }
     catch (e) { sqlDb.run('ROLLBACK'); throw e; }
   },
   async closeAsync() { sqlDb.close(); },
@@ -1184,7 +1217,7 @@ const adapter: SQLiteAdapter = {
   },
   async withTransactionAsync(fn) {
     db.exec('BEGIN');
-    try { const r = await fn(); db.exec('COMMIT'); return r; }
+    try { const r = await fn(this); db.exec('COMMIT'); return r; }
     catch (e) { db.exec('ROLLBACK'); throw e; }
   },
   async closeAsync() { db.close(); },

package/dist/{chunk-ZU7K6NAU.mjs → chunk-TTECJ3S3.mjs}

@@ -105,6 +105,21 @@ var WikiSourceRefHashCollision = class extends Error {
     this.name = "WikiSourceRefHashCollision";
   }
 };
+var WikiGraphNodeOwnershipConflict = class extends Error {
+  /**
+   * Privacy-preserving constructor: accepts no arguments, so neither the foreign
+   * owner, the conflicting node ID, the stored content, nor any provenance can
+   * leak through this error. The fixed message and `code` are the entire signal.
+   *
+   * @returns a contextless `WikiGraphNodeOwnershipConflict` instance. See the
+   *   class-level JSDoc for the privacy rationale.
+   */
+  constructor() {
+    super("Graph write rejected because a node ID is unavailable for this entity.");
+    this.code = "WIKI_GRAPH_NODE_OWNERSHIP_CONFLICT";
+    this.name = "WikiGraphNodeOwnershipConflict";
+  }
+};
 var WikiTransactionError = class extends Error {
   constructor(message, options) {
     super(message, options);
@@ -1942,6 +1957,36 @@ var IngestionService = class {
       releaseIngestLocks();
     }
   }
+  /**
+   * Reject the whole write when any incoming node ID is already owned by a
+   * different entity. Runs entirely inside the supplied `tx`, through the
+   * repository abstraction, and — being the first thing `upsertGraphCore`
+   * does — before ontology resolution, which can itself persist a configured
+   * seed manifest.
+   *
+   * The lookup has no deleted-row filter, so a soft-deleted foreign row keeps
+   * its ID reserved. Only the lookup IDs are deduplicated; `params.nodes` and
+   * the later write loops keep their ordering and counts.
+   *
+   * The error is deliberately contextless — see WikiGraphNodeOwnershipConflict.
+   *
+   * @param entityId - the entity the caller is writing on behalf of. Foreign
+   *   rows under a different entity trigger the rejection.
+   * @param nodes - incoming node set; only the IDs are inspected, so callers
+   *   may pass the public `params.nodes` shape directly without slicing.
+   * @param tx - the open transaction. Reuses the same handle every later
+   *   statement in `upsertGraphCore` runs against, so atomicity is enforced
+   *   by the host transaction's commit/rollback, not by this method.
+   */
+  async assertGraphNodeOwnership(entityId, nodes, tx) {
+    const ids = [...new Set(nodes.map((node) => node.id))];
+    const existing = await this.entryRepo.findExistingMetadataByIds(ids, tx);
+    for (const row of existing) {
+      if (row.entity_id !== entityId) {
+        throw new WikiGraphNodeOwnershipConflict();
+      }
+    }
+  }
   /**
    * Implements spec §2 data flow steps a–j with the host-facing
    * `{sourceRef, sourceHash, nodes, edges}` parameter shape. Shared between
@@ -1960,8 +2005,19 @@ var IngestionService = class {
    * @returns Counts: nodesWritten (validated nodes persisted), edgesWritten
    *   (manifest-valid edges persisted), superseded (prior facts soft-deleted
    *   plus prior source-ref edges hard-deleted).
+   *
+   * Node-ownership pre-flight (spec §3, REQ-GRAPH-01): the first statement
+   * is `assertGraphNodeOwnership(entityId, params.nodes, tx)`, which runs
+   * before ontology resolution, seed-manifest persistence, and every other
+   * write. A foreign-owned ID throws `WikiGraphNodeOwnershipConflict` with
+   * no disclosed owner, node ID, or content; the caller's transaction
+   * remains open and must be rolled back by the host. Soft-deleted foreign
+   * rows keep their IDs reserved. Duplicate incoming IDs are deduplicated
+   * only for the lookup; `params.nodes` and the write loops keep their
+   * ordering and counts so success counts match the pre-change contract.
    */
   async upsertGraphCore(entityId, params, tx, opts) {
+    await this.assertGraphNodeOwnership(entityId, params.nodes, tx);
     const now = Date.now();
     const ontologyState = await this.ontologyService?.getEffectiveState(entityId, tx) ?? { mode: "off", manifest: { node_types: [], edge_types: [] } };
     let { mode, manifest } = ontologyState;
@@ -4913,6 +4969,6 @@ var WriteService = class {
   }
 };
 
-export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDuplicateHashError, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
-//# sourceMappingURL=chunk-ZU7K6NAU.mjs.map
-//# sourceMappingURL=chunk-ZU7K6NAU.mjs.map
+export { BaseRepository, DEFAULT_CHUNK_OVERLAP, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, EmbeddingService, HEAL_ANCHORS_PER_CANDIDATE, HEAL_BATCH_SIZE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, HEAL_RECHECK_MS, HOOK_TIMEOUT_MARKER, ImportExportService, IngestionService, JobManager, MaintenanceService, MetadataRepository, ONTOLOGY_BACKFILL_BATCH_SIZE, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, ONTOLOGY_BACKFILL_RECHECK_MS, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, PromptService, PrunePartialFailureError, RetrievalService, SearchService, WikiBusyError, WikiDuplicateHashError, WikiGraphNodeOwnershipConflict, WikiIngestEmptyError, WikiInvalidReadOptions, WikiParseError, WikiSourceRefHashCollision, WikiStrictOntologyViolation, WikiTransactionError, WriteService, __privateAdd, __privateGet, __privateSet, chunkText, configureRandomSource, emptyManifest, entitySummaryMetaKey, extractSqliteCode, generateId, normalizeSourceHash, normalizeSourceRef, normalizeTitleKey, parseEmbedding, resolveEdgeDefinitions, resolveNodeType, safeSlice, typeSatisfies, validateInlineEdges, validateManifest };
+//# sourceMappingURL=chunk-TTECJ3S3.mjs.map
+//# sourceMappingURL=chunk-TTECJ3S3.mjs.map