@equationalapplications/core-llm-wiki 6.4.0 → 6.5.1

package/dist/{testing-DWpAgNLt.d.mts → testing-BtsN1pTK.d.mts}

@@ -104,6 +104,26 @@ interface OntologyBackfillResult {
      * Stamped with the recheck cooldown, so they reappear as `deferred` next pass. */
     skipped: number;
 }
+/** Result of a single `runReembed` sweep. */
+interface ReembedResult {
+    /** Facts successfully (re-)embedded this sweep. */
+    embedded: number;
+    /** Facts with a valid existing embedding left untouched because
+     * `skipExisting` was in effect (and no dimension mismatch forced a re-embed). */
+    skipped: number;
+    /** Facts whose embed attempt ran and failed this sweep. Includes
+     * `storage_error` failures, which are not backoff-tracked (a marker is
+     * itself a DB write — see the reembed README section). Convergence loops
+     * should test this counter, never `deferred`. */
+    failed: number;
+    /** Previously failed facts still inside their exponential backoff window
+     * (60s doubling, capped at 24h), not attempted this sweep. Not an error;
+     * a later sweep retries them once the window elapses. */
+    deferred: number;
+    /** Facts excluded for good: a `float32_overflow` failure or 5 failed
+     * lifetime attempts. `{ force: true }` retries these anyway. */
+    permanentlyFailed: number;
+}
 /**
  * L3 heal-success record: a fact the model emitted a verdict for under a
  * truncated view of its own body. `originalBodyChars` lets an operator flag
@@ -743,6 +763,14 @@ declare class PrunePartialFailureError extends Error {
     constructor(deleted: number, failedAt: string, remaining: number, cause: Error, deletedTasks?: number, deletedEvents?: number);
 }
 declare const HOOK_TIMEOUT_MARKER: unique symbol;
+/**
+ * Failure kinds eligible for a persisted embedding failure marker (spec §3.3).
+ * `no_provider` never marks (nothing to retry against), and `storage_error`
+ * never marks (D3 — a marker is itself a DB write). Defined here, neutral
+ * between repositories and services, so EntryRepository can type-narrow the
+ * marker kind without importing from services.
+ */
+type EmbeddingMarkerKind = 'invalid_vector' | 'float32_overflow' | 'provider_error';
 /**
  * Failure record for a single chunk that could not be ingested. Produced by
  * `IngestionService.ingestDocument` and surfaced on the result's `parseFailures`
@@ -890,6 +918,18 @@ type EntryRowWithEmbeddings = EntryRowMetadata & {
     embedding_blob: Uint8Array | null;
     embedding: string | null;
 };
+/**
+ * One row of the reembed candidate scan. `findAllForReembed` does `SELECT *`,
+ * so the marker columns come back at runtime; naming them here makes that
+ * dependency visible to the compiler instead of hiding it behind a cast in
+ * MaintenanceService.runReembed (spec §4.4).
+ */
+type ReembedCandidateRow = WikiFact & {
+    embedding_blob?: Uint8Array | null;
+    embedding_failed_at?: number | null;
+    embedding_failure_kind?: string | null;
+    embedding_attempts?: number | null;
+};
 declare class EntryRepository extends BaseRepository {
     private outbox;
     private chunkSize;
@@ -918,6 +958,13 @@ declare class EntryRepository extends BaseRepository {
      * 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.
+     *
+     * Marker discipline (spec §4.1): a conflict carrying a real
+     * `embedding_blob` clears the embedding failure markers, because the row now
+     * HAS a valid embedding and a surviving marker would be a self-contradictory
+     * diagnostic that inflates runReembed's permanentlyFailed counter. A conflict
+     * with no blob leaves marker state alone, matching the "absent means don't
+     * touch" semantics used for embedding_blob itself.
      */
     upsert(fact: WikiFact, tx: SQLiteAdapter): Promise<{
         changes: number;
@@ -1066,11 +1113,31 @@ declare class EntryRepository extends BaseRepository {
         tags: string;
     }>>;
     updateEmbeddingBlob(id: string, blob: Uint8Array, tx?: SQLiteAdapter): Promise<void>;
+    /**
+     * Record a failed embedding attempt. Deliberately does NOT touch updated_at
+     * (import merge is last-write-wins on it) and pushes no outbox event —
+     * embedding lifecycle is local state, not replicated. Same discipline as
+     * updateEmbeddingBlob. See spec §3.5.
+     *
+     * Only marker-eligible kinds (spec §3.3) are accepted: `no_provider` never
+     * marks and `storage_error` never marks, so retry/permanent-failure policy
+     * built on these rows only ever sees real embed failures.
+     */
+    markEmbeddingFailure(id: string, kind: EmbeddingMarkerKind, now: number, tx?: SQLiteAdapter): Promise<void>;
+    /**
+     * Clear marker state for every marked row. Called when the embedding
+     * dimension is promoted: a new model produces different vectors, so past
+     * failures — including `float32_overflow`, which is otherwise terminal —
+     * no longer predict future ones (spec §2.3).
+     *
+     * Same discipline as markEmbeddingFailure: no `updated_at` touch and no
+     * outbox event, because embedding lifecycle is local state, not replicated.
+     * Returns the number of rows cleared.
+     */
+    clearEmbeddingFailureMarkers(tx?: SQLiteAdapter): Promise<number>;
     hasLegacySourceTypes(tx?: SQLiteAdapter): Promise<boolean>;
     countLegacySourceTypes(tx?: SQLiteAdapter): Promise<number>;
-    findAllForReembed(entityId?: string, tx?: SQLiteAdapter): Promise<Array<WikiFact & {
-        embedding_blob?: Uint8Array | null;
-    }>>;
+    findAllForReembed(entityId?: string, tx?: SQLiteAdapter): Promise<ReembedCandidateRow[]>;
     findRowsForSourceRefMigration(tx?: SQLiteAdapter): Promise<Array<{
         rowid: number;
         source_ref: string;
@@ -1540,6 +1607,14 @@ declare class EdgeRepository extends BaseRepository {
     }>;
 }
 
+type EmbedFailureKind = EmbeddingMarkerKind | 'no_provider' | 'storage_error';
+type EmbedFactResult = {
+    ok: true;
+    dimension: number;
+} | {
+    ok: false;
+    kind: EmbedFailureKind;
+};
 declare class EmbeddingService {
     private db;
     private options;
@@ -1547,8 +1622,36 @@ declare class EmbeddingService {
     private metadataRepo;
     constructor(db: SQLiteAdapter, options: WikiOptions, entryRepo: EntryRepository, metadataRepo: MetadataRepository);
     storeEmbeddingDimension(dim: number): Promise<void>;
-    /** Promotes embedding_dimension_mismatch to canonical embedding_dimension when safe. */
+    /**
+     * Promotes embedding_dimension_mismatch to canonical embedding_dimension when
+     * safe, and clears embedding failure markers as part of the same event.
+     *
+     * Marker reset (spec §2.3): a promoted dimension means a different model is
+     * producing the vectors, so prior failures no longer predict future ones.
+     * `float32_overflow` is cleared too — it is terminal only because retrying is
+     * the same arithmetic on the same vector, and after a model change it is not.
+     *
+     * All three writes commit atomically; see the transaction note inline.
+     *
+     * Revived rows are NOT embedded here. They become eligible and are picked up
+     * by the NEXT sweep, because runReembed calls this after its candidates were
+     * already classified; same-sweep revival would be re-entrant.
+     */
     reconcileEmbeddingDimension(): Promise<void>;
+    tryEmbedFact(fact: {
+        id: string;
+        entity_id: string;
+        title: string;
+        body: string;
+        tags: string | string[];
+    }): Promise<EmbedFactResult>;
+    /** Marker writes must never fail the caller. Only marker-eligible kinds reach here. */
+    private markFailure;
+    /**
+     * Back-compatible boolean form. Kept because callers such as
+     * ImportExportService branch on `if (!embedded)`; a discriminated result
+     * object is always truthy and would silently disable that branch.
+     */
     embedFact(fact: {
         id: string;
         entity_id: string;
@@ -1911,14 +2014,23 @@ declare class MaintenanceService {
         promptOverride?: string;
         batchSize?: number;
     }): Promise<OntologyBackfillResult>;
+    /**
+     * Re-embed facts, honouring per-row failure markers and exponential backoff.
+     *
+     * Marker lifecycle (spec §2): markers are cleared by a successful embed, by
+     * an upsert carrying a valid blob, and by an embedding-dimension promotion.
+     * A promotion revives rows for the NEXT sweep, not this one — reconciliation
+     * runs after candidates were already classified.
+     *
+     * Residual, by design: swapping to a provider with the SAME dimension never
+     * sets embedding_dimension_mismatch, so promotion never fires and markers
+     * survive the swap. Use `runReembed({ force: true })` to clear that state —
+     * `force` bypasses classification entirely and retries every row.
+     */
     runReembed(entityId?: string, opts?: {
         force?: boolean;
         skipExisting?: boolean;
-    }): Promise<{
-        embedded: number;
-        skipped: number;
-        failed: number;
-    }>;
+    }): Promise<ReembedResult>;
     forget(entityId: string, params: {
         entryId?: string;
         taskId?: string;
@@ -2275,11 +2387,7 @@ declare class WikiMemory {
     runReembed(entityId?: string, opts?: {
         force?: boolean;
         skipExisting?: boolean;
-    }): Promise<{
-        embedded: number;
-        skipped: number;
-        failed: number;
-    }>;
+    }): Promise<ReembedResult>;
     getEntityStatus(entityId: string): EntityStatus;
     subscribeEntityStatus(entityId: string, callback: (status: EntityStatus) => void): () => void;
     clearVectorCache(): void;
@@ -2458,4 +2566,4 @@ declare class WikiMemory {
     setGeneratedByTask(taskId: string, entityId: string, actor: string): Promise<void>;
 }
 
-export { WikiParseError as $, WikiBusyError as A, type WikiBusyOperation as B, type ChunkFailure as C, type DegradedRecord as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type WikiCheckpoint as J, type WikiConfig as K, type LLMProvider as L, type MemoryBundle as M, WikiDuplicateHashError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiEdge as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiEvent as T, type WikiFact as U, type VectorRanker as V, type WikiOptions as W, WikiIngestEmptyError as X, WikiInvalidReadOptions as Y, type WikiMemoryTestAccess as Z, type WikiOutboxEvent as _, type MemoryDump as a, WikiSourceRefHashCollision as a0, WikiStrictOntologyViolation as a1, type WikiTask as a2, WikiTransactionError as a3, EmbeddingService as a4, ImportExportService as a5, IngestionService as a6, JobManager as a7, MaintenanceService as a8, RetrievalService as a9, SearchService as aa, WriteService as ab, 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 };
+export { WikiIngestEmptyError as $, type ReembedResult as A, type VectorRankerFallback as B, type ChunkFailure as C, type DegradedRecord as D, type EmbedFactResult as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type VectorRankerRankArgs as J, type VectorRankerSemanticResult as K, type LLMProvider as L, type MemoryBundle as M, WikiBusyError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiBusyOperation as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiCheckpoint as T, type WikiConfig as U, type VectorRanker as V, type WikiOptions as W, WikiDuplicateHashError as X, type WikiEdge as Y, type WikiEvent as Z, type WikiFact as _, type MemoryDump as a, WikiInvalidReadOptions as a0, type WikiMemoryTestAccess as a1, type WikiOutboxEvent as a2, WikiParseError as a3, WikiSourceRefHashCollision as a4, WikiStrictOntologyViolation as a5, type WikiTask as a6, WikiTransactionError as a7, EmbeddingService as a8, ImportExportService as a9, IngestionService as aa, JobManager as ab, MaintenanceService as ac, RetrievalService as ad, SearchService as ae, WriteService as af, type FormattedMemoryDump as b, WikiMemory as c, type EmbedFailureKind as d, type EmbeddingMarkerKind as e, type EntityStatus as f, type ExtractedFact as g, type ExtractedFactEdge as h, type ExtractedFactWithOntology as i, type ExtractedTask as j, type GraphTraversalOptions as k, HEAL_RECHECK_MS as l, HOOK_TIMEOUT_MARKER as m, type HealResult as n, ONTOLOGY_BACKFILL_BATCH_SIZE as o, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as p, ONTOLOGY_BACKFILL_RECHECK_MS as q, type OntologyBackfillResult as r, type OntologyConfig as s, type OntologyEdgeType as t, type OntologyMode as u, type OntologyNodeType as v, type OntologyPromptContext as w, type OntologyUpdates as x, PromptService as y, PrunePartialFailureError as z };

package/dist/{testing-DWpAgNLt.d.ts → testing-BtsN1pTK.d.ts}

@@ -104,6 +104,26 @@ interface OntologyBackfillResult {
      * Stamped with the recheck cooldown, so they reappear as `deferred` next pass. */
     skipped: number;
 }
+/** Result of a single `runReembed` sweep. */
+interface ReembedResult {
+    /** Facts successfully (re-)embedded this sweep. */
+    embedded: number;
+    /** Facts with a valid existing embedding left untouched because
+     * `skipExisting` was in effect (and no dimension mismatch forced a re-embed). */
+    skipped: number;
+    /** Facts whose embed attempt ran and failed this sweep. Includes
+     * `storage_error` failures, which are not backoff-tracked (a marker is
+     * itself a DB write — see the reembed README section). Convergence loops
+     * should test this counter, never `deferred`. */
+    failed: number;
+    /** Previously failed facts still inside their exponential backoff window
+     * (60s doubling, capped at 24h), not attempted this sweep. Not an error;
+     * a later sweep retries them once the window elapses. */
+    deferred: number;
+    /** Facts excluded for good: a `float32_overflow` failure or 5 failed
+     * lifetime attempts. `{ force: true }` retries these anyway. */
+    permanentlyFailed: number;
+}
 /**
  * L3 heal-success record: a fact the model emitted a verdict for under a
  * truncated view of its own body. `originalBodyChars` lets an operator flag
@@ -743,6 +763,14 @@ declare class PrunePartialFailureError extends Error {
     constructor(deleted: number, failedAt: string, remaining: number, cause: Error, deletedTasks?: number, deletedEvents?: number);
 }
 declare const HOOK_TIMEOUT_MARKER: unique symbol;
+/**
+ * Failure kinds eligible for a persisted embedding failure marker (spec §3.3).
+ * `no_provider` never marks (nothing to retry against), and `storage_error`
+ * never marks (D3 — a marker is itself a DB write). Defined here, neutral
+ * between repositories and services, so EntryRepository can type-narrow the
+ * marker kind without importing from services.
+ */
+type EmbeddingMarkerKind = 'invalid_vector' | 'float32_overflow' | 'provider_error';
 /**
  * Failure record for a single chunk that could not be ingested. Produced by
  * `IngestionService.ingestDocument` and surfaced on the result's `parseFailures`
@@ -890,6 +918,18 @@ type EntryRowWithEmbeddings = EntryRowMetadata & {
     embedding_blob: Uint8Array | null;
     embedding: string | null;
 };
+/**
+ * One row of the reembed candidate scan. `findAllForReembed` does `SELECT *`,
+ * so the marker columns come back at runtime; naming them here makes that
+ * dependency visible to the compiler instead of hiding it behind a cast in
+ * MaintenanceService.runReembed (spec §4.4).
+ */
+type ReembedCandidateRow = WikiFact & {
+    embedding_blob?: Uint8Array | null;
+    embedding_failed_at?: number | null;
+    embedding_failure_kind?: string | null;
+    embedding_attempts?: number | null;
+};
 declare class EntryRepository extends BaseRepository {
     private outbox;
     private chunkSize;
@@ -918,6 +958,13 @@ declare class EntryRepository extends BaseRepository {
      * 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.
+     *
+     * Marker discipline (spec §4.1): a conflict carrying a real
+     * `embedding_blob` clears the embedding failure markers, because the row now
+     * HAS a valid embedding and a surviving marker would be a self-contradictory
+     * diagnostic that inflates runReembed's permanentlyFailed counter. A conflict
+     * with no blob leaves marker state alone, matching the "absent means don't
+     * touch" semantics used for embedding_blob itself.
      */
     upsert(fact: WikiFact, tx: SQLiteAdapter): Promise<{
         changes: number;
@@ -1066,11 +1113,31 @@ declare class EntryRepository extends BaseRepository {
         tags: string;
     }>>;
     updateEmbeddingBlob(id: string, blob: Uint8Array, tx?: SQLiteAdapter): Promise<void>;
+    /**
+     * Record a failed embedding attempt. Deliberately does NOT touch updated_at
+     * (import merge is last-write-wins on it) and pushes no outbox event —
+     * embedding lifecycle is local state, not replicated. Same discipline as
+     * updateEmbeddingBlob. See spec §3.5.
+     *
+     * Only marker-eligible kinds (spec §3.3) are accepted: `no_provider` never
+     * marks and `storage_error` never marks, so retry/permanent-failure policy
+     * built on these rows only ever sees real embed failures.
+     */
+    markEmbeddingFailure(id: string, kind: EmbeddingMarkerKind, now: number, tx?: SQLiteAdapter): Promise<void>;
+    /**
+     * Clear marker state for every marked row. Called when the embedding
+     * dimension is promoted: a new model produces different vectors, so past
+     * failures — including `float32_overflow`, which is otherwise terminal —
+     * no longer predict future ones (spec §2.3).
+     *
+     * Same discipline as markEmbeddingFailure: no `updated_at` touch and no
+     * outbox event, because embedding lifecycle is local state, not replicated.
+     * Returns the number of rows cleared.
+     */
+    clearEmbeddingFailureMarkers(tx?: SQLiteAdapter): Promise<number>;
     hasLegacySourceTypes(tx?: SQLiteAdapter): Promise<boolean>;
     countLegacySourceTypes(tx?: SQLiteAdapter): Promise<number>;
-    findAllForReembed(entityId?: string, tx?: SQLiteAdapter): Promise<Array<WikiFact & {
-        embedding_blob?: Uint8Array | null;
-    }>>;
+    findAllForReembed(entityId?: string, tx?: SQLiteAdapter): Promise<ReembedCandidateRow[]>;
     findRowsForSourceRefMigration(tx?: SQLiteAdapter): Promise<Array<{
         rowid: number;
         source_ref: string;
@@ -1540,6 +1607,14 @@ declare class EdgeRepository extends BaseRepository {
     }>;
 }
 
+type EmbedFailureKind = EmbeddingMarkerKind | 'no_provider' | 'storage_error';
+type EmbedFactResult = {
+    ok: true;
+    dimension: number;
+} | {
+    ok: false;
+    kind: EmbedFailureKind;
+};
 declare class EmbeddingService {
     private db;
     private options;
@@ -1547,8 +1622,36 @@ declare class EmbeddingService {
     private metadataRepo;
     constructor(db: SQLiteAdapter, options: WikiOptions, entryRepo: EntryRepository, metadataRepo: MetadataRepository);
     storeEmbeddingDimension(dim: number): Promise<void>;
-    /** Promotes embedding_dimension_mismatch to canonical embedding_dimension when safe. */
+    /**
+     * Promotes embedding_dimension_mismatch to canonical embedding_dimension when
+     * safe, and clears embedding failure markers as part of the same event.
+     *
+     * Marker reset (spec §2.3): a promoted dimension means a different model is
+     * producing the vectors, so prior failures no longer predict future ones.
+     * `float32_overflow` is cleared too — it is terminal only because retrying is
+     * the same arithmetic on the same vector, and after a model change it is not.
+     *
+     * All three writes commit atomically; see the transaction note inline.
+     *
+     * Revived rows are NOT embedded here. They become eligible and are picked up
+     * by the NEXT sweep, because runReembed calls this after its candidates were
+     * already classified; same-sweep revival would be re-entrant.
+     */
     reconcileEmbeddingDimension(): Promise<void>;
+    tryEmbedFact(fact: {
+        id: string;
+        entity_id: string;
+        title: string;
+        body: string;
+        tags: string | string[];
+    }): Promise<EmbedFactResult>;
+    /** Marker writes must never fail the caller. Only marker-eligible kinds reach here. */
+    private markFailure;
+    /**
+     * Back-compatible boolean form. Kept because callers such as
+     * ImportExportService branch on `if (!embedded)`; a discriminated result
+     * object is always truthy and would silently disable that branch.
+     */
     embedFact(fact: {
         id: string;
         entity_id: string;
@@ -1911,14 +2014,23 @@ declare class MaintenanceService {
         promptOverride?: string;
         batchSize?: number;
     }): Promise<OntologyBackfillResult>;
+    /**
+     * Re-embed facts, honouring per-row failure markers and exponential backoff.
+     *
+     * Marker lifecycle (spec §2): markers are cleared by a successful embed, by
+     * an upsert carrying a valid blob, and by an embedding-dimension promotion.
+     * A promotion revives rows for the NEXT sweep, not this one — reconciliation
+     * runs after candidates were already classified.
+     *
+     * Residual, by design: swapping to a provider with the SAME dimension never
+     * sets embedding_dimension_mismatch, so promotion never fires and markers
+     * survive the swap. Use `runReembed({ force: true })` to clear that state —
+     * `force` bypasses classification entirely and retries every row.
+     */
     runReembed(entityId?: string, opts?: {
         force?: boolean;
         skipExisting?: boolean;
-    }): Promise<{
-        embedded: number;
-        skipped: number;
-        failed: number;
-    }>;
+    }): Promise<ReembedResult>;
     forget(entityId: string, params: {
         entryId?: string;
         taskId?: string;
@@ -2275,11 +2387,7 @@ declare class WikiMemory {
     runReembed(entityId?: string, opts?: {
         force?: boolean;
         skipExisting?: boolean;
-    }): Promise<{
-        embedded: number;
-        skipped: number;
-        failed: number;
-    }>;
+    }): Promise<ReembedResult>;
     getEntityStatus(entityId: string): EntityStatus;
     subscribeEntityStatus(entityId: string, callback: (status: EntityStatus) => void): () => void;
     clearVectorCache(): void;
@@ -2458,4 +2566,4 @@ declare class WikiMemory {
     setGeneratedByTask(taskId: string, entityId: string, actor: string): Promise<void>;
 }
 
-export { WikiParseError as $, WikiBusyError as A, type WikiBusyOperation as B, type ChunkFailure as C, type DegradedRecord as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type WikiCheckpoint as J, type WikiConfig as K, type LLMProvider as L, type MemoryBundle as M, WikiDuplicateHashError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiEdge as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiEvent as T, type WikiFact as U, type VectorRanker as V, type WikiOptions as W, WikiIngestEmptyError as X, WikiInvalidReadOptions as Y, type WikiMemoryTestAccess as Z, type WikiOutboxEvent as _, type MemoryDump as a, WikiSourceRefHashCollision as a0, WikiStrictOntologyViolation as a1, type WikiTask as a2, WikiTransactionError as a3, EmbeddingService as a4, ImportExportService as a5, IngestionService as a6, JobManager as a7, MaintenanceService as a8, RetrievalService as a9, SearchService as aa, WriteService as ab, 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 };
+export { WikiIngestEmptyError as $, type ReembedResult as A, type VectorRankerFallback as B, type ChunkFailure as C, type DegradedRecord as D, type EmbedFactResult as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type VectorRankerRankArgs as J, type VectorRankerSemanticResult as K, type LLMProvider as L, type MemoryBundle as M, WikiBusyError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiBusyOperation as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiCheckpoint as T, type WikiConfig as U, type VectorRanker as V, type WikiOptions as W, WikiDuplicateHashError as X, type WikiEdge as Y, type WikiEvent as Z, type WikiFact as _, type MemoryDump as a, WikiInvalidReadOptions as a0, type WikiMemoryTestAccess as a1, type WikiOutboxEvent as a2, WikiParseError as a3, WikiSourceRefHashCollision as a4, WikiStrictOntologyViolation as a5, type WikiTask as a6, WikiTransactionError as a7, EmbeddingService as a8, ImportExportService as a9, IngestionService as aa, JobManager as ab, MaintenanceService as ac, RetrievalService as ad, SearchService as ae, WriteService as af, type FormattedMemoryDump as b, WikiMemory as c, type EmbedFailureKind as d, type EmbeddingMarkerKind as e, type EntityStatus as f, type ExtractedFact as g, type ExtractedFactEdge as h, type ExtractedFactWithOntology as i, type ExtractedTask as j, type GraphTraversalOptions as k, HEAL_RECHECK_MS as l, HOOK_TIMEOUT_MARKER as m, type HealResult as n, ONTOLOGY_BACKFILL_BATCH_SIZE as o, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as p, ONTOLOGY_BACKFILL_RECHECK_MS as q, type OntologyBackfillResult as r, type OntologyConfig as s, type OntologyEdgeType as t, type OntologyMode as u, type OntologyNodeType as v, type OntologyPromptContext as w, type OntologyUpdates as x, PromptService as y, PrunePartialFailureError as z };

package/dist/testing.d.mts

@@ -1,3 +1,3 @@
-export { a4 as EmbeddingService, a5 as ImportExportService, a6 as IngestionService, a7 as JobManager, a7 as JobManagerType, a8 as MaintenanceService, a9 as RetrievalService, aa as SearchService, aa as SearchServiceType, Z as WikiMemoryTestAccess, ab as WriteService } from './testing-DWpAgNLt.mjs';
+export { a8 as EmbeddingService, a9 as ImportExportService, aa as IngestionService, ab as JobManager, ab as JobManagerType, ac as MaintenanceService, ad as RetrievalService, ae as SearchService, ae as SearchServiceType, a1 as WikiMemoryTestAccess, af as WriteService } from './testing-BtsN1pTK.mjs';
 import '@equationalapplications/core-okf';
 import 'minisearch';

package/dist/testing.d.ts

@@ -1,3 +1,3 @@
-export { a4 as EmbeddingService, a5 as ImportExportService, a6 as IngestionService, a7 as JobManager, a7 as JobManagerType, a8 as MaintenanceService, a9 as RetrievalService, aa as SearchService, aa as SearchServiceType, Z as WikiMemoryTestAccess, ab as WriteService } from './testing-DWpAgNLt.js';
+export { a8 as EmbeddingService, a9 as ImportExportService, aa as IngestionService, ab as JobManager, ab as JobManagerType, ac as MaintenanceService, ad as RetrievalService, ae as SearchService, ae as SearchServiceType, a1 as WikiMemoryTestAccess, af as WriteService } from './testing-BtsN1pTK.js';
 import '@equationalapplications/core-okf';
 import 'minisearch';

package/dist/testing.js

@@ -651,20 +651,37 @@ var EmbeddingService = class {
       await this.metadataRepo.setMeta("embedding_dimension", String(dim), this.db);
     }
   }
-  /** Promotes embedding_dimension_mismatch to canonical embedding_dimension when safe. */
+  /**
+   * Promotes embedding_dimension_mismatch to canonical embedding_dimension when
+   * safe, and clears embedding failure markers as part of the same event.
+   *
+   * Marker reset (spec §2.3): a promoted dimension means a different model is
+   * producing the vectors, so prior failures no longer predict future ones.
+   * `float32_overflow` is cleared too — it is terminal only because retrying is
+   * the same arithmetic on the same vector, and after a model change it is not.
+   *
+   * All three writes commit atomically; see the transaction note inline.
+   *
+   * Revived rows are NOT embedded here. They become eligible and are picked up
+   * by the NEXT sweep, because runReembed calls this after its candidates were
+   * already classified; same-sweep revival would be re-entrant.
+   */
   async reconcileEmbeddingDimension() {
     const mismatchValue = await this.metadataRepo.getMeta("embedding_dimension_mismatch");
     if (!mismatchValue) return;
     const newDim = parseInt(mismatchValue, 10);
     const residualCount = await this.entryRepo.countStaleEmbeddings(newDim);
     if (residualCount === 0) {
-      await this.metadataRepo.setMeta("embedding_dimension", mismatchValue, this.db);
-      await this.metadataRepo.clearDimensionMismatch(this.db);
+      await this.db.withTransactionAsync(async (tx) => {
+        await this.metadataRepo.setMeta("embedding_dimension", mismatchValue, tx);
+        await this.metadataRepo.clearDimensionMismatch(tx);
+        await this.entryRepo.clearEmbeddingFailureMarkers(tx);
+      });
     }
   }
-  async embedFact(fact) {
+  async tryEmbedFact(fact) {
     const embedFn = this.options.llmProvider.embed;
-    if (!embedFn) return false;
+    if (typeof embedFn !== "function") return { ok: false, kind: "no_provider" };
     let tagsStr;
     if (Array.isArray(fact.tags)) {
       tagsStr = fact.tags.join(" ");
@@ -679,13 +696,15 @@ var EmbeddingService = class {
     const configuredMaxEmbedChars = this.options.config?.maxEmbedChars;
     const maxEmbedChars = Number.isFinite(configuredMaxEmbedChars) ? Math.min(Math.max(0, Math.trunc(configuredMaxEmbedChars)), EMBED_CHARS_CEILING) : DEFAULT_MAX_EMBED_CHARS;
     const text = clip(`${fact.title} ${fact.body} ${tagsStr}`.trim(), maxEmbedChars);
+    let float32Vector;
     try {
       const vector = await embedFn(text);
       if (vector.length === 0 || !vector.every((v) => typeof v === "number" && isFinite(v))) {
         console.warn(`[WikiMemory] embedFact: embed() returned an invalid vector for ${fact.id}; skipping.`);
-        return false;
+        await this.markFailure(fact.id, "invalid_vector");
+        return { ok: false, kind: "invalid_vector" };
       }
-      const float32Vector = new Float32Array(vector);
+      float32Vector = new Float32Array(vector);
       let hasNonFinite = false;
       for (let i = 0; i < float32Vector.length; i++) {
         if (!isFinite(float32Vector[i])) {
@@ -695,22 +714,46 @@ var EmbeddingService = class {
       }
       if (hasNonFinite) {
         console.warn(`[WikiMemory] embedFact: embed() returned values that overflow float32 for ${fact.id}; skipping.`);
-        return false;
+        await this.markFailure(fact.id, "float32_overflow");
+        return { ok: false, kind: "float32_overflow" };
       }
+    } catch (err) {
+      console.warn(`[WikiMemory] embedFact failed for ${fact.id}:`, err);
+      await this.markFailure(fact.id, "provider_error");
+      return { ok: false, kind: "provider_error" };
+    }
+    try {
       await this.storeEmbeddingDimension(float32Vector.length);
       const blob = new Uint8Array(float32Vector.buffer);
       await this.entryRepo.updateEmbeddingBlob(fact.id, blob);
-      try {
-        await this.notifyEmbeddingPersisted(fact.entity_id, fact.id, float32Vector);
-      } catch (hookErr) {
-        console.warn(`[WikiMemory] onEmbeddingPersisted hook failed for ${fact.id}:`, hookErr);
-      }
-      return true;
     } catch (err) {
-      console.warn(`[WikiMemory] embedFact failed for ${fact.id}:`, err);
-      return false;
+      console.warn(`[WikiMemory] embedFact: persisting embedding failed for ${fact.id}:`, err);
+      return { ok: false, kind: "storage_error" };
+    }
+    try {
+      await this.notifyEmbeddingPersisted(fact.entity_id, fact.id, float32Vector);
+    } catch (hookErr) {
+      console.warn(`[WikiMemory] onEmbeddingPersisted hook failed for ${fact.id}:`, hookErr);
+    }
+    return { ok: true, dimension: float32Vector.length };
+  }
+  /** Marker writes must never fail the caller. Only marker-eligible kinds reach here. */
+  async markFailure(id, kind) {
+    try {
+      await this.entryRepo.markEmbeddingFailure(id, kind, Date.now());
+    } catch (err) {
+      console.warn(`[WikiMemory] failed to record embedding failure for ${id}:`, err);
     }
   }
+  /**
+   * Back-compatible boolean form. Kept because callers such as
+   * ImportExportService branch on `if (!embedded)`; a discriminated result
+   * object is always truthy and would silently disable that branch.
+   */
+  async embedFact(fact) {
+    const result = await this.tryEmbedFact(fact);
+    return result.ok;
+  }
   async notifyEmbeddingPersisted(entityId, factId, vector) {
     if (!this.options.vectorRanker?.onEmbeddingPersisted) return;
     const vectorCopy = vector ? vector.slice() : null;
@@ -2109,6 +2152,23 @@ var HEAL_ANCHOR_SEARCH_OVERFETCH = 4;
 var HEAL_MAX_PROMPT_CHARS = 4e4;
 var HEAL_BATCH_SIZE = 25;
 var HEAL_RECHECK_MS = 7 * 24 * 60 * 60 * 1e3;
+var MAX_EMBED_ATTEMPTS = 5;
+var EMBED_RETRY_BASE_MS = 6e4;
+var EMBED_RETRY_CAP_MS = 24 * 60 * 60 * 1e3;
+function embedRetryDelayMs(attempts) {
+  const n = Math.max(1, Math.trunc(attempts || 0));
+  const delay = EMBED_RETRY_BASE_MS * Math.pow(2, n - 1);
+  return Math.min(delay, EMBED_RETRY_CAP_MS);
+}
+function classifyReembedRow(row, now, force) {
+  if (force) return "attempt";
+  const failedAt = row.embedding_failed_at;
+  if (failedAt === null || failedAt === void 0) return "attempt";
+  if (row.embedding_failure_kind === "float32_overflow") return "permanent";
+  const attempts = row.embedding_attempts ?? 0;
+  if (attempts >= MAX_EMBED_ATTEMPTS) return "permanent";
+  return now - failedAt >= embedRetryDelayMs(attempts) ? "attempt" : "defer";
+}
 var SKIP_ERROR_LOG_CHARS = 4096;
 var formatSkipError = (err) => {
   let base;
@@ -2247,9 +2307,24 @@ var MaintenanceService = class {
       this.jobManager.releaseLock("ontologyBackfill", entityId);
     }
   }
+  /**
+   * Re-embed facts, honouring per-row failure markers and exponential backoff.
+   *
+   * Marker lifecycle (spec §2): markers are cleared by a successful embed, by
+   * an upsert carrying a valid blob, and by an embedding-dimension promotion.
+   * A promotion revives rows for the NEXT sweep, not this one — reconciliation
+   * runs after candidates were already classified.
+   *
+   * Residual, by design: swapping to a provider with the SAME dimension never
+   * sets embedding_dimension_mismatch, so promotion never fires and markers
+   * survive the swap. Use `runReembed({ force: true })` to clear that state —
+   * `force` bypasses classification entirely and retries every row.
+   */
   async runReembed(entityId, opts) {
     const embedFn = this.options.llmProvider.embed;
-    if (!embedFn) return { embedded: 0, skipped: 0, failed: 0 };
+    if (typeof embedFn !== "function") {
+      return { embedded: 0, skipped: 0, failed: 0, deferred: 0, permanentlyFailed: 0 };
+    }
     const op = entityId ? "reembed" : "global_reembed";
     this.jobManager.acquireLock(op, entityId ?? "*");
     try {
@@ -2272,6 +2347,10 @@ var MaintenanceService = class {
       let embedded = 0;
       let skipped = 0;
       let failed = 0;
+      let deferred = 0;
+      let permanentlyFailed = 0;
+      const force = opts?.force ?? false;
+      const now = Date.now();
       try {
         for (const row of rows) {
           const existingBlob = row.embedding_blob;
@@ -2283,8 +2362,17 @@ var MaintenanceService = class {
               continue;
             }
           }
-          const success = await this.embeddingService.embedFact(row);
-          if (success) embedded++;
+          const disposition = classifyReembedRow(row, now, force);
+          if (disposition === "defer") {
+            deferred++;
+            continue;
+          }
+          if (disposition === "permanent") {
+            permanentlyFailed++;
+            continue;
+          }
+          const result = await this.embeddingService.tryEmbedFact(row);
+          if (result.ok) embedded++;
           else failed++;
         }
         if (embedded > 0) {
@@ -2293,7 +2381,7 @@ var MaintenanceService = class {
       } finally {
         this.searchService.evictCache(entityId);
       }
-      return { embedded, skipped, failed };
+      return { embedded, skipped, failed, deferred, permanentlyFailed };
     } finally {
       this.jobManager.releaseLock(op, entityId ?? "*");
     }