@equationalapplications/core-llm-wiki 5.3.0 → 5.4.0

package/dist/{testing-zf3Jp_RL.d.mts → testing-C71mnMxq.d.mts}

@@ -1,3 +1,4 @@
+import { OkfSource, OkfVerifiedEntry, OkfSourceUsageWindow } from '@equationalapplications/core-okf';
 import { SearchResult } from 'minisearch';
 
 /**
@@ -250,6 +251,38 @@ interface WikiFact {
      * OKF import. Distinct from `source_type`, which governs immutability rules.
      */
     okf_type?: string | null;
+    /** OKF v0.2 lifecycle state. Defaults to 'stable' on the SQL side. */
+    lifecycle_status?: 'draft' | 'stable' | 'deprecated';
+    /** Absolute YYYY-MM-DD cutoff for staleness. NULL = never stale. */
+    stale_after?: number | null;
+    /** Actor string per OKF v0.2 §7 (`<producer>/<version>`, `human:<id>`, `process:<id>`). */
+    generated_by?: string | null;
+    /** Full list of OKF v0.2 sources (provenance). */
+    okf_sources?: OkfSource[];
+    /** Chronological list of verification events. */
+    okf_verified?: OkfVerifiedEntry[];
+    /** Sibling-of-sources usage window object. */
+    okf_usage_window?: OkfSourceUsageWindow | null;
+    /** Convenience: epoch ms of the latest verifier. Derived; mirrored for query speed. */
+    last_verified_at?: number | null;
+    /** Convenience: actor string of the latest verifier. Derived; mirrored for query speed. */
+    last_verified_by?: string | null;
+    /**
+     * Hydrated at read time: `isStaleAfter(stale_after, now)`. `true` once the
+     * absolute stale_after cutoff has passed; `false` otherwise (including when
+     * stale_after is null). Surfaced per spec §2.7 + §5.3 so hosts can render
+     * staleness without recomputing. Always present on read paths that go
+     * through `mapRowToFact` / `mapRowToTask`.
+     */
+    isStale?: boolean;
+    /**
+     * Hydrated at read time: `deriveTrustTier(okf_verified)`. `'human-reviewed'`
+     * when any entry has `by: 'human:...'`, `'machine-confirmed'` when entries
+     * exist without a human verifier, `'unverified'` when okf_verified is empty.
+     * Surfaced per spec §2.7 + §5.3. Always present on read paths that go through
+     * `mapRowToFact` / `mapRowToTask`.
+     */
+    trustTier?: 'unverified' | 'machine-confirmed' | 'human-reviewed';
 }
 interface WikiTask {
     id: string;
@@ -263,6 +296,27 @@ interface WikiTask {
     deleted_at: number | null;
     /** Verbatim OKF `type:` frontmatter value when this task originated from an OKF bundle. */
     okf_type?: string | null;
+    lifecycle_status?: 'draft' | 'stable' | 'deprecated';
+    stale_after?: number | null;
+    generated_by?: string | null;
+    okf_sources?: OkfSource[];
+    okf_verified?: OkfVerifiedEntry[];
+    okf_usage_window?: OkfSourceUsageWindow | null;
+    last_verified_at?: number | null;
+    last_verified_by?: string | null;
+    /**
+     * Hydrated at read time: `isStaleAfter(stale_after, now)`. Mirrors
+     * {@link WikiFact.isStale} (spec §2.5 + §5.3 treat stale_after symmetrically
+     * for tasks and facts). Always present on read paths that go through
+     * `mapRowToTask`.
+     */
+    isStale?: boolean;
+    /**
+     * Hydrated at read time: `deriveTrustTier(okf_verified)`. Mirrors
+     * {@link WikiFact.trustTier}. Always present on read paths that go through
+     * `mapRowToTask`.
+     */
+    trustTier?: 'unverified' | 'machine-confirmed' | 'human-reviewed';
 }
 interface WikiEvent {
     id: string;
@@ -697,6 +751,21 @@ declare class EntryRepository extends BaseRepository {
      * Upsert a WikiFact. Nullable fields set to null when fact value is null.
      * Returns { changes, lastInsertRowId }.
      * `tx` is REQUIRED to ensure atomic outbox staging.
+     *
+     * OKF metadata discipline (spec §2.5 + DAO checklist §8): content writes
+     * MUST NOT silently overwrite OKF metadata that a caller didn't supply. The
+     * previous CASE WHEN IS NULL guards around `lifecycle_status`, etc. were
+     * dead because the bind always supplied a non-null value (notably
+     * `fact.lifecycle_status ?? 'stable'`), so excluded.X was never NULL and
+     * an UPDATE rewrote an existing `deprecated` row to `stable`. We now omit
+     * these columns from the SET clause entirely — SQLite's ON CONFLICT UPDATE
+     * leaves untouched columns at their existing row value, which is exactly
+     * the preservation semantics we want for content writes. Callers that
+     * intentionally want to overwrite OKF metadata should use
+     * {@link upsertForImport} (always-replace semantics for that path).
+     * New-row INSERTs still bind a value so the column is populated; if the
+     * caller supplied nothing, the schema DEFAULT 'stable' applies when the
+     * bind is bound as 'stable' explicitly here.
      */
     upsert(fact: WikiFact, tx: SQLiteAdapter): Promise<{
         changes: number;
@@ -1494,6 +1563,12 @@ declare class TaskRepository extends BaseRepository {
      * Uses ON CONFLICT(id) DO UPDATE (not INSERT OR REPLACE).
      * Stages an outbox entry in the same transaction.
      * `tx` is REQUIRED.
+     *
+     * OKF metadata (lifecycle_status, sources, etc.) is intentionally excluded
+     * from the SET clause so content writes preserve any existing row values.
+     * See {@link EntryRepository.upsert} for the rationale — the same applies
+     * symmetrically to tasks (spec §2.5). Callers that need to overwrite OKF
+     * metadata should use {@link upsertForImport}.
      */
     upsert(task: WikiTask, tx: SQLiteAdapter, updatedAt?: number): Promise<void>;
     upsertForImport(task: WikiTask, tx: SQLiteAdapter, updatedAt?: number): Promise<void>;
@@ -1835,6 +1910,7 @@ declare class WikiMemory {
     private promptService;
     private ontologyService;
     private graphTraversalService;
+    private readonly okfTrustWrites;
     constructor(db: SQLiteAdapter, options: WikiOptions);
     /**
      * Explicit escape hatch for test suites: typed access to composed services for mocks/spies.
@@ -2101,6 +2177,34 @@ declare class WikiMemory {
     setOntologyManifest(entityId: string, manifest: OntologyManifest, options?: {
         mode?: OntologyMode;
     }): Promise<void>;
+    /** Append a verification event to a fact. Does NOT touch `updated_at`. */
+    writeOkfTrust(entryId: string, entityId: string, verified: {
+        by: string;
+        at: string;
+    }[]): Promise<void>;
+    /** Replace a fact's source list. Does NOT touch `updated_at`. */
+    writeOkfSources(entryId: string, entityId: string, sources: Array<{
+        resource: string;
+        [k: string]: unknown;
+    }>): Promise<void>;
+    /** Set a fact's OKF v0.2 lifecycle status. Does NOT touch `updated_at`. */
+    setLifecycleStatus(entryId: string, entityId: string, status: 'draft' | 'stable' | 'deprecated'): Promise<void>;
+    /** Set a fact's stale_after (epoch ms) or clear it. Does NOT touch `updated_at`. */
+    setStaleAfter(entryId: string, entityId: string, date: number | null): Promise<void>;
+    /** Set a fact's generated_by actor string. Does NOT touch `updated_at`. */
+    setGeneratedBy(entryId: string, entityId: string, actor: string): Promise<void>;
+    /** Task variants of the same five DAO methods. Symmetric per spec §2.5. */
+    writeOkfTrustTask(taskId: string, entityId: string, verified: {
+        by: string;
+        at: string;
+    }[]): Promise<void>;
+    writeOkfSourcesTask(taskId: string, entityId: string, sources: Array<{
+        resource: string;
+        [k: string]: unknown;
+    }>): Promise<void>;
+    setLifecycleStatusTask(taskId: string, entityId: string, status: 'draft' | 'stable' | 'deprecated'): Promise<void>;
+    setStaleAfterTask(taskId: string, entityId: string, date: number | null): Promise<void>;
+    setGeneratedByTask(taskId: string, entityId: string, actor: string): Promise<void>;
 }
 
 export { ImportExportService as $, WikiBusyError as A, type WikiBusyOperation as B, type WikiCheckpoint as C, type WikiConfig as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, WikiDuplicateHashError as I, type WikiEdge as J, type WikiEvent as K, type LLMProvider as L, type MemoryBundle as M, type WikiFact as N, type OntologyManifest as O, type PromptOverrides as P, type WikiMemoryTestAccess as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiOutboxEvent as T, WikiSourceRefHashCollision as U, type VectorRanker as V, type WikiOptions as W, WikiStrictOntologyViolation as X, type WikiTask as Y, WikiTransactionError as Z, EmbeddingService as _, type MemoryDump as a, IngestionService as a0, JobManager as a1, MaintenanceService as a2, RetrievalService as a3, SearchService as a4, WriteService as a5, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };

package/dist/{testing-zf3Jp_RL.d.ts → testing-C71mnMxq.d.ts}

@@ -1,3 +1,4 @@
+import { OkfSource, OkfVerifiedEntry, OkfSourceUsageWindow } from '@equationalapplications/core-okf';
 import { SearchResult } from 'minisearch';
 
 /**
@@ -250,6 +251,38 @@ interface WikiFact {
      * OKF import. Distinct from `source_type`, which governs immutability rules.
      */
     okf_type?: string | null;
+    /** OKF v0.2 lifecycle state. Defaults to 'stable' on the SQL side. */
+    lifecycle_status?: 'draft' | 'stable' | 'deprecated';
+    /** Absolute YYYY-MM-DD cutoff for staleness. NULL = never stale. */
+    stale_after?: number | null;
+    /** Actor string per OKF v0.2 §7 (`<producer>/<version>`, `human:<id>`, `process:<id>`). */
+    generated_by?: string | null;
+    /** Full list of OKF v0.2 sources (provenance). */
+    okf_sources?: OkfSource[];
+    /** Chronological list of verification events. */
+    okf_verified?: OkfVerifiedEntry[];
+    /** Sibling-of-sources usage window object. */
+    okf_usage_window?: OkfSourceUsageWindow | null;
+    /** Convenience: epoch ms of the latest verifier. Derived; mirrored for query speed. */
+    last_verified_at?: number | null;
+    /** Convenience: actor string of the latest verifier. Derived; mirrored for query speed. */
+    last_verified_by?: string | null;
+    /**
+     * Hydrated at read time: `isStaleAfter(stale_after, now)`. `true` once the
+     * absolute stale_after cutoff has passed; `false` otherwise (including when
+     * stale_after is null). Surfaced per spec §2.7 + §5.3 so hosts can render
+     * staleness without recomputing. Always present on read paths that go
+     * through `mapRowToFact` / `mapRowToTask`.
+     */
+    isStale?: boolean;
+    /**
+     * Hydrated at read time: `deriveTrustTier(okf_verified)`. `'human-reviewed'`
+     * when any entry has `by: 'human:...'`, `'machine-confirmed'` when entries
+     * exist without a human verifier, `'unverified'` when okf_verified is empty.
+     * Surfaced per spec §2.7 + §5.3. Always present on read paths that go through
+     * `mapRowToFact` / `mapRowToTask`.
+     */
+    trustTier?: 'unverified' | 'machine-confirmed' | 'human-reviewed';
 }
 interface WikiTask {
     id: string;
@@ -263,6 +296,27 @@ interface WikiTask {
     deleted_at: number | null;
     /** Verbatim OKF `type:` frontmatter value when this task originated from an OKF bundle. */
     okf_type?: string | null;
+    lifecycle_status?: 'draft' | 'stable' | 'deprecated';
+    stale_after?: number | null;
+    generated_by?: string | null;
+    okf_sources?: OkfSource[];
+    okf_verified?: OkfVerifiedEntry[];
+    okf_usage_window?: OkfSourceUsageWindow | null;
+    last_verified_at?: number | null;
+    last_verified_by?: string | null;
+    /**
+     * Hydrated at read time: `isStaleAfter(stale_after, now)`. Mirrors
+     * {@link WikiFact.isStale} (spec §2.5 + §5.3 treat stale_after symmetrically
+     * for tasks and facts). Always present on read paths that go through
+     * `mapRowToTask`.
+     */
+    isStale?: boolean;
+    /**
+     * Hydrated at read time: `deriveTrustTier(okf_verified)`. Mirrors
+     * {@link WikiFact.trustTier}. Always present on read paths that go through
+     * `mapRowToTask`.
+     */
+    trustTier?: 'unverified' | 'machine-confirmed' | 'human-reviewed';
 }
 interface WikiEvent {
     id: string;
@@ -697,6 +751,21 @@ declare class EntryRepository extends BaseRepository {
      * Upsert a WikiFact. Nullable fields set to null when fact value is null.
      * Returns { changes, lastInsertRowId }.
      * `tx` is REQUIRED to ensure atomic outbox staging.
+     *
+     * OKF metadata discipline (spec §2.5 + DAO checklist §8): content writes
+     * MUST NOT silently overwrite OKF metadata that a caller didn't supply. The
+     * previous CASE WHEN IS NULL guards around `lifecycle_status`, etc. were
+     * dead because the bind always supplied a non-null value (notably
+     * `fact.lifecycle_status ?? 'stable'`), so excluded.X was never NULL and
+     * an UPDATE rewrote an existing `deprecated` row to `stable`. We now omit
+     * these columns from the SET clause entirely — SQLite's ON CONFLICT UPDATE
+     * leaves untouched columns at their existing row value, which is exactly
+     * the preservation semantics we want for content writes. Callers that
+     * intentionally want to overwrite OKF metadata should use
+     * {@link upsertForImport} (always-replace semantics for that path).
+     * New-row INSERTs still bind a value so the column is populated; if the
+     * caller supplied nothing, the schema DEFAULT 'stable' applies when the
+     * bind is bound as 'stable' explicitly here.
      */
     upsert(fact: WikiFact, tx: SQLiteAdapter): Promise<{
         changes: number;
@@ -1494,6 +1563,12 @@ declare class TaskRepository extends BaseRepository {
      * Uses ON CONFLICT(id) DO UPDATE (not INSERT OR REPLACE).
      * Stages an outbox entry in the same transaction.
      * `tx` is REQUIRED.
+     *
+     * OKF metadata (lifecycle_status, sources, etc.) is intentionally excluded
+     * from the SET clause so content writes preserve any existing row values.
+     * See {@link EntryRepository.upsert} for the rationale — the same applies
+     * symmetrically to tasks (spec §2.5). Callers that need to overwrite OKF
+     * metadata should use {@link upsertForImport}.
      */
     upsert(task: WikiTask, tx: SQLiteAdapter, updatedAt?: number): Promise<void>;
     upsertForImport(task: WikiTask, tx: SQLiteAdapter, updatedAt?: number): Promise<void>;
@@ -1835,6 +1910,7 @@ declare class WikiMemory {
     private promptService;
     private ontologyService;
     private graphTraversalService;
+    private readonly okfTrustWrites;
     constructor(db: SQLiteAdapter, options: WikiOptions);
     /**
      * Explicit escape hatch for test suites: typed access to composed services for mocks/spies.
@@ -2101,6 +2177,34 @@ declare class WikiMemory {
     setOntologyManifest(entityId: string, manifest: OntologyManifest, options?: {
         mode?: OntologyMode;
     }): Promise<void>;
+    /** Append a verification event to a fact. Does NOT touch `updated_at`. */
+    writeOkfTrust(entryId: string, entityId: string, verified: {
+        by: string;
+        at: string;
+    }[]): Promise<void>;
+    /** Replace a fact's source list. Does NOT touch `updated_at`. */
+    writeOkfSources(entryId: string, entityId: string, sources: Array<{
+        resource: string;
+        [k: string]: unknown;
+    }>): Promise<void>;
+    /** Set a fact's OKF v0.2 lifecycle status. Does NOT touch `updated_at`. */
+    setLifecycleStatus(entryId: string, entityId: string, status: 'draft' | 'stable' | 'deprecated'): Promise<void>;
+    /** Set a fact's stale_after (epoch ms) or clear it. Does NOT touch `updated_at`. */
+    setStaleAfter(entryId: string, entityId: string, date: number | null): Promise<void>;
+    /** Set a fact's generated_by actor string. Does NOT touch `updated_at`. */
+    setGeneratedBy(entryId: string, entityId: string, actor: string): Promise<void>;
+    /** Task variants of the same five DAO methods. Symmetric per spec §2.5. */
+    writeOkfTrustTask(taskId: string, entityId: string, verified: {
+        by: string;
+        at: string;
+    }[]): Promise<void>;
+    writeOkfSourcesTask(taskId: string, entityId: string, sources: Array<{
+        resource: string;
+        [k: string]: unknown;
+    }>): Promise<void>;
+    setLifecycleStatusTask(taskId: string, entityId: string, status: 'draft' | 'stable' | 'deprecated'): Promise<void>;
+    setStaleAfterTask(taskId: string, entityId: string, date: number | null): Promise<void>;
+    setGeneratedByTask(taskId: string, entityId: string, actor: string): Promise<void>;
 }
 
 export { ImportExportService as $, WikiBusyError as A, type WikiBusyOperation as B, type WikiCheckpoint as C, type WikiConfig as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, WikiDuplicateHashError as I, type WikiEdge as J, type WikiEvent as K, type LLMProvider as L, type MemoryBundle as M, type WikiFact as N, type OntologyManifest as O, type PromptOverrides as P, type WikiMemoryTestAccess as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiOutboxEvent as T, WikiSourceRefHashCollision as U, type VectorRanker as V, type WikiOptions as W, WikiStrictOntologyViolation as X, type WikiTask as Y, WikiTransactionError as Z, EmbeddingService as _, type MemoryDump as a, IngestionService as a0, JobManager as a1, MaintenanceService as a2, RetrievalService as a3, SearchService as a4, WriteService as a5, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };

package/dist/testing.d.mts

@@ -1,2 +1,3 @@
-export { _ as EmbeddingService, $ as ImportExportService, a0 as IngestionService, a1 as JobManager, a1 as JobManagerType, a2 as MaintenanceService, a3 as RetrievalService, a4 as SearchService, a4 as SearchServiceType, Q as WikiMemoryTestAccess, a5 as WriteService } from './testing-zf3Jp_RL.mjs';
+export { _ as EmbeddingService, $ as ImportExportService, a0 as IngestionService, a1 as JobManager, a1 as JobManagerType, a2 as MaintenanceService, a3 as RetrievalService, a4 as SearchService, a4 as SearchServiceType, Q as WikiMemoryTestAccess, a5 as WriteService } from './testing-C71mnMxq.mjs';
+import '@equationalapplications/core-okf';
 import 'minisearch';

package/dist/testing.d.ts

@@ -1,2 +1,3 @@
-export { _ as EmbeddingService, $ as ImportExportService, a0 as IngestionService, a1 as JobManager, a1 as JobManagerType, a2 as MaintenanceService, a3 as RetrievalService, a4 as SearchService, a4 as SearchServiceType, Q as WikiMemoryTestAccess, a5 as WriteService } from './testing-zf3Jp_RL.js';
+export { _ as EmbeddingService, $ as ImportExportService, a0 as IngestionService, a1 as JobManager, a1 as JobManagerType, a2 as MaintenanceService, a3 as RetrievalService, a4 as SearchService, a4 as SearchServiceType, Q as WikiMemoryTestAccess, a5 as WriteService } from './testing-C71mnMxq.js';
+import '@equationalapplications/core-okf';
 import 'minisearch';

package/dist/testing.js

@@ -1,5 +1,6 @@
 'use strict';
 
+var coreOkf = require('@equationalapplications/core-okf');
 var MiniSearch = require('minisearch');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -459,8 +460,6 @@ function normalizeTitleKey(title) {
 function entitySummaryMetaKey(entityId) {
   return `entity_summary:${entityId}`;
 }
-
-// src/services/ImportExportService.ts
 var MAX_EMBEDDING_BLOB_BYTES = 32 * 1024;
 var IMPORT_TITLE_MAX = 500;
 var IMPORT_BODY_MAX = 8e3;
@@ -680,7 +679,23 @@ var ImportExportService = class {
           access_count: fact.access_count,
           deleted_at: fact.deleted_at,
           embedding_blob: blobData ?? void 0,
-          okf_type: fact.okf_type ?? null
+          okf_type: fact.okf_type ?? null,
+          // OKF v0.2 — forwarded as-is; parseOkfBundle / the caller is responsible for
+          // populating these per spec, importDump does not derive or validate them.
+          lifecycle_status: fact.lifecycle_status ?? "stable",
+          stale_after: fact.stale_after ?? null,
+          generated_by: fact.generated_by ?? null,
+          okf_sources: fact.okf_sources ?? [],
+          okf_verified: fact.okf_verified ?? [],
+          okf_usage_window: fact.okf_usage_window ?? null,
+          // last_verified_at/_by are DERIVED mirrors of `okf_verified` per spec
+          // §5.3. Recomputing here (instead of trusting the payload field) closes
+          // the invariant that a raw importDump cannot carry a
+          // last_verified_by that contradicts its own okf_verified list.
+          ...(() => {
+            const latest = coreOkf.latestVerified(fact.okf_verified ?? [], Date.now());
+            return { last_verified_at: latest?.at ?? null, last_verified_by: latest?.by ?? null };
+          })()
         };
         await this.entryRepo.upsertForImport(factObj, tx);
         if (blobData != null) {
@@ -730,7 +745,19 @@ var ImportExportService = class {
             updated_at: safeUpdatedAt,
             resolved_at: task.resolved_at,
             deleted_at: task.deleted_at,
-            okf_type: task.okf_type ?? null
+            okf_type: task.okf_type ?? null,
+            // OKF v0.2
+            lifecycle_status: task.lifecycle_status ?? "stable",
+            stale_after: task.stale_after ?? null,
+            generated_by: task.generated_by ?? null,
+            okf_sources: task.okf_sources ?? [],
+            okf_verified: task.okf_verified ?? [],
+            okf_usage_window: task.okf_usage_window ?? null,
+            // Derived mirrors — see fact branch above; same invariant.
+            ...(() => {
+              const latest = coreOkf.latestVerified(task.okf_verified ?? [], Date.now());
+              return { last_verified_at: latest?.at ?? null, last_verified_by: latest?.by ?? null };
+            })()
           },
           tx,
           safeUpdatedAt