hippo-memory 1.69.0 → 1.71.0

package/dist/store/rejected-values.js

@@ -0,0 +1,150 @@
+// Reject, unreject and list rejected values, each on one handle of its own.
+// A file apart from rejection.ts: store/open.ts imports that one, so an open there would be an import cycle.
+import { closeHippoDb, openHippoDb, withWriteScope } from '../db/index.js';
+import { heldTexts } from '../util/same-text.js';
+import { audit } from './audit-event.js';
+import { deleteEntryCore } from './delete-and-batch.js';
+import { deleteDormantRow, listDormantSnapshots, purgeDormantByDigest, replaceDormantEntry } from './dormant.js';
+import { entryRejectRowAt, selectAllEntries } from './entry-reads.js';
+import { stampOriginProject } from './entry-row.js';
+import { writeEntryDbOnly, writeEntryMirrors } from './entry-writes.js';
+import { purgeMirrorBestEffort } from './mirrors.js';
+import { onHandle, openStore } from './open.js';
+import { archiveRawMemory, markMirrorCleaned } from './raw-archive.js';
+import { RejectedValueError, checkRejectionGuard, deleteRejectedValue, insertRejectedValue, listRejectedValues, normalizeValueForRejection, rejectionDigest, } from './rejection.js';
+function removeLiveRows(db, hippoRoot, rejection, holdsValue, removal) {
+    const { tenantId, actor, reason } = rejection;
+    const { removedIds, removedRawIds, successors } = removal;
+    const merged = [];
+    for (const row of selectAllEntries(db, tenantId)) {
+        if (!rejection.inReach(row.scope))
+            continue;
+        if (!holdsValue(row.content)) {
+            if (heldTexts(row).some(holdsValue))
+                merged.push(row);
+            continue;
+        }
+        if (row.kind === 'raw') {
+            // A raw row is append-only: archiving is its one removal path, and its savepoint nests in this write scope.
+            archiveRawMemory(db, row.id, { reason, who: actor });
+            removedRawIds.push(row.id);
+        }
+        else {
+            // The one reject_value row is the trail for these removals, so no forget row each.
+            deleteEntryCore(db, row.id, { actor, suppressForgetAudit: true });
+        }
+        removedIds.push(row.id);
+    }
+    for (const row of merged) {
+        const successor = rejection.successorOf(row, holdsValue, new Set(removedIds));
+        deleteEntryCore(db, row.id, { actor, suppressForgetAudit: true });
+        removedIds.push(row.id);
+        if (!successor)
+            continue;
+        const kept = stampOriginProject(hippoRoot, successor);
+        writeEntryDbOnly(db, kept, { actor });
+        successors.push(kept);
+    }
+}
+// Dormant copies go in the same write scope, so `hippo dormant restore` cannot bring the text back. They have no mirror to purge.
+function removeDormantCopies(db, rejection, digest, holdsValue, removal) {
+    const { tenantId } = rejection;
+    const { removedIds, dormantSuccessorIds } = removal;
+    removedIds.push(...purgeDormantByDigest(db, tenantId, digest, rejection.inReach));
+    for (const dormant of listDormantSnapshots(db, tenantId)) {
+        if (!rejection.inReach(dormant.entry.scope))
+            continue;
+        const successor = rejection.successorOf(dormant.entry, holdsValue, new Set(removedIds));
+        if (successor === undefined)
+            continue;
+        removedIds.push(dormant.entry.id);
+        if (!successor) {
+            deleteDormantRow(db, tenantId, dormant.entry.id);
+            continue;
+        }
+        replaceDormantEntry(db, tenantId, dormant.entry.id, successor);
+        dormantSuccessorIds.push(successor.id);
+    }
+}
+// After the commit, on the same handle: a purged raw mirror is stamped so the reaper skips it, and one that stays is logged.
+function purgeRemovedMirrors(db, hippoRoot, removal) {
+    for (const id of removal.removedIds) {
+        const isRaw = removal.removedRawIds.includes(id);
+        const mirrorOk = purgeMirrorBestEffort(hippoRoot, id, isRaw, 'hippo reject');
+        if (mirrorOk && isRaw)
+            markMirrorCleaned(db, id, new Date().toISOString());
+    }
+    for (const successor of removal.successors)
+        writeEntryMirrors(hippoRoot, successor);
+}
+/** Applies one rejection on one handle and in one write scope: the rejected-value row, the removal of every row in reach that holds the
+ *  text (live or dormant, whole or inside a merged row) and one reject_value audit row. Markdown mirrors follow the commit. */
+export function applyRejection(hippoRoot, rejection) {
+    const { tenantId, actor, reason, memoryId } = rejection;
+    return onHandle(hippoRoot, (db) => {
+        const content = rejection.textOf(memoryId === undefined ? undefined : entryRejectRowAt(db, memoryId));
+        const digest = rejectionDigest(content);
+        const rejectedAt = new Date().toISOString();
+        const removal = { removedIds: [], removedRawIds: [], successors: [], dormantSuccessorIds: [] };
+        withWriteScope(db, 'reject_value', () => {
+            insertRejectedValue(db, {
+                tenantId,
+                digest,
+                reason,
+                rejectedBy: actor,
+                rejectedAt,
+                sourceMemoryId: memoryId ?? null,
+                normalizedChars: normalizeValueForRejection(content).length,
+            });
+            // SHORTCUT: scans every row of the tenant, fine for a human-run command; a digest column on memories if stores grow a hundredfold.
+            const holdsValue = (text) => rejectionDigest(text) === digest;
+            removeLiveRows(db, hippoRoot, rejection, holdsValue, removal);
+            removeDormantCopies(db, rejection, digest, holdsValue, removal);
+            // Still inside the write scope: a failed audit row is reported and the reject commits without it.
+            const { removedIds } = removal;
+            audit(db, 'reject_value', { tenantId, actor, targetId: memoryId, metadata: { digest, removedIds, count: removedIds.length } });
+        });
+        purgeRemovedMirrors(db, hippoRoot, removal);
+        const { removedIds, removedRawIds, successors, dormantSuccessorIds } = removal;
+        return { digest, content, removedIds, removedRawIds, successorIds: successors.map((s) => s.id), dormantSuccessorIds };
+    }, openStore);
+}
+/** Deletes the tenant's one rejected value whose digest starts with `digestPrefix` and writes its unreject_value audit row.
+ *  No match, or more than one, writes nothing. */
+export function liftRejection(hippoRoot, tenantId, digestPrefix, actor) {
+    return onHandle(hippoRoot, (db) => {
+        const matches = listRejectedValues(db, tenantId).filter((r) => r.digest.startsWith(digestPrefix));
+        const target = matches[0];
+        if (target === undefined)
+            return { status: 'not_found' };
+        if (matches.length > 1)
+            return { status: 'ambiguous', candidates: matches };
+        deleteRejectedValue(db, tenantId, target.digest);
+        audit(db, 'unreject_value', { tenantId, actor, targetId: target.sourceMemoryId ?? undefined, metadata: { digest: target.digest, reason: target.reason } });
+        return { status: 'ok', digest: target.digest, reason: target.reason };
+    }, openStore);
+}
+/** The tenant's rejected values, newest first. */
+export function loadRejectedValues(hippoRoot, tenantId) {
+    return onHandle(hippoRoot, (db) => {
+        return listRejectedValues(db, tenantId);
+    }, openStore);
+}
+/** Whether the write guard would refuse `content` under `entryId`, as a write of that row would find it. Reads on a plain open
+ *  and writes nothing, so a dry run counts the values a real run refuses. */
+export function rejectionGuardRefuses(hippoRoot, tenantId, entryId, content) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        checkRejectionGuard(db, tenantId, entryId, content);
+        return false;
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError)
+            return true;
+        throw err;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=rejected-values.js.map

package/dist/store/rejection.d.ts

@@ -0,0 +1,54 @@
+/** Rejected-value tombstone: a human can refuse byte-stable re-ingestion of a rejected fact (exact normalized value); paraphrase matching is out of scope.
+ * db-agnostic (helpers take a `DatabaseSyncLike`) and imports nothing from the store layer above it, which imports this (the reverse is a cycle). */
+import type { DatabaseSyncLike } from '../db/index.js';
+import { BadRequestError } from '../core/api-errors.js';
+/** Normalize content for rejection digests: NFC, lowercase, collapse whitespace runs, trim. No punctuation stripping: over-normalizing causes false
+ * refusals, worse than misses. */
+export declare function normalizeValueForRejection(content: string): string;
+/** Full 64-char sha256 hex of the normalized content: a tombstone key needs collision resistance, not the 16-char redaction hash used for query hashing. */
+export declare function rejectionDigest(content: string): string;
+/** Thrown by the write-path guard (checkRejectionGuard, via upsertEntryRow) when a write would introduce a tombstoned value; carries what the
+ * transaction-owner catch blocks (writeEntry, api.supersede) need to write the post-rollback `reject_refusal` audit row via `auditRejectionRefusal`. */
+export declare class RejectedValueError extends BadRequestError {
+    readonly digest: string;
+    readonly tenantId: string;
+    readonly entryId: string;
+    readonly reason: string | null;
+    readonly rejectedAt: string;
+    constructor(opts: {
+        digest: string;
+        tenantId: string;
+        entryId: string;
+        reason: string | null;
+        rejectedAt: string;
+    });
+}
+export interface RejectedValueRow {
+    tenantId: string;
+    digest: string;
+    reason: string | null;
+    rejectedBy: string | null;
+    rejectedAt: string;
+    sourceMemoryId: string | null;
+    normalizedChars: number | null;
+}
+/** Look up a tombstone by tenant + digest: one indexed point query, the guard's common-case cost; a miss ends the guard. */
+export declare function findRejectedValue(db: DatabaseSyncLike, tenantId: string, digest: string): RejectedValueRow | null;
+/** Insert (or refresh) a tombstone row; the caller owns the transaction (used by the `reject` verb and `resolveConflict`'s `rejectLoserValue`). */
+export declare function insertRejectedValue(db: DatabaseSyncLike, opts: {
+    tenantId: string;
+    digest: string;
+    reason: string;
+    rejectedBy: string;
+    rejectedAt: string;
+    sourceMemoryId?: string | null;
+    normalizedChars: number;
+}): void;
+/** Delete a tombstone by tenant + exact digest: the `unreject` verb, the only escape hatch. */
+export declare function deleteRejectedValue(db: DatabaseSyncLike, tenantId: string, digest: string): boolean;
+/** List tombstones for a tenant, newest first: the `rejections` verb. */
+export declare function listRejectedValues(db: DatabaseSyncLike, tenantId: string): RejectedValueRow[];
+/** Write-path guard check: fires when the digest matches a tombstone AND the write introduces that content (a new row, or a same-id UPSERT changing it).
+ * Unchanged same-id re-persists (recall boost, decay, star toggle) are exempt. A miss costs ONE indexed point query; only a hit SELECTs the stored row. */
+export declare function checkRejectionGuard(db: DatabaseSyncLike, tenantId: string, entryId: string, content: string): void;
+//# sourceMappingURL=rejection.d.ts.map

package/dist/{rejection.js → store/rejection.js}

@@ -1,42 +1,19 @@
-/**
- * Rejected-value tombstone: core invariant.
- *
- * Exact-normalized-value semantics: a human who rejects a fact can refuse
- * byte-stable re-ingestion of the same value across remember/capture/import/
- * sync surfaces. Paraphrase/semantic matching is explicitly out of scope
- * (documented limitation, plan "Design").
- *
- * Kept db-agnostic (helpers take a `DatabaseSyncLike` handle) and does NOT
- * import from store.ts — store.ts imports from here, and the reverse would
- * be a cycle.
- */
+/** Rejected-value tombstone: a human can refuse byte-stable re-ingestion of a rejected fact (exact normalized value); paraphrase matching is out of scope.
+ * db-agnostic (helpers take a `DatabaseSyncLike`) and imports nothing from the store layer above it, which imports this (the reverse is a cycle). */
 import { createHash } from 'node:crypto';
-import { BadRequestError } from './api-errors.js';
-/**
- * Normalize content for rejection-digest comparisons: Unicode NFC →
- * lowercase → collapse whitespace runs to a single space → trim. No
- * punctuation stripping — over-normalization creates false refusals, which
- * are worse than misses (plan §1).
- */
+import { BadRequestError } from '../core/api-errors.js';
+import { DIGEST_DISPLAY_CHARS } from '../util/token-text.js';
+/** Normalize content for rejection digests: NFC, lowercase, collapse whitespace runs, trim. No punctuation stripping: over-normalizing causes false
+ * refusals, worse than misses. */
 export function normalizeValueForRejection(content) {
     return content.normalize('NFC').toLowerCase().replace(/\s+/g, ' ').trim();
 }
-/**
- * Full sha256 hex (64 chars) of the normalized content. Reuses the strong-
- * identity convention (importers.ts:814 content-hash tag), NOT the privacy-
- * lossy 16-char convention (recall-trace query hashing) — a tombstone lookup
- * key needs collision resistance, not redaction (plan §1).
- */
+/** Full 64-char sha256 hex of the normalized content: a tombstone key needs collision resistance, not the 16-char redaction hash used for query hashing. */
 export function rejectionDigest(content) {
     return createHash('sha256').update(normalizeValueForRejection(content)).digest('hex');
 }
-/**
- * Thrown by the write-path guard (checkRejectionGuard, called from
- * upsertEntryRow) when an incoming write would introduce a value matching a
- * tombstoned digest. Carries enough context for the transaction-owner catch
- * blocks (writeEntry, api.supersede) to write a post-rollback
- * `reject_refusal` audit row via `auditRejectionRefusal` (plan §3).
- */
+/** Thrown by the write-path guard (checkRejectionGuard, via upsertEntryRow) when a write would introduce a tombstoned value; carries what the
+ * transaction-owner catch blocks (writeEntry, api.supersede) need to write the post-rollback `reject_refusal` audit row via `auditRejectionRefusal`. */
 export class RejectedValueError extends BadRequestError {
     digest;
     tenantId;
@@ -44,7 +21,7 @@ export class RejectedValueError extends BadRequestError {
     reason;
     rejectedAt;
     constructor(opts) {
-        super(`Memory value refused: matches a rejected value (digest ${opts.digest.slice(0, 12)}..., ` +
+        super(`Memory value refused: matches a rejected value (digest ${opts.digest.slice(0, DIGEST_DISPLAY_CHARS)}..., ` +
             `reason: ${opts.reason ?? 'none given'}). Run "hippo unreject" to allow it again.`);
         this.name = 'RejectedValueError';
         this.digest = opts.digest;
@@ -65,10 +42,7 @@ function rowToRejectedValue(row) {
         normalizedChars: row.normalized_chars,
     };
 }
-/**
- * Look up a tombstone by tenant + digest. One indexed point query — the
- * guard's common-case cost, a miss ends the guard (plan §3).
- */
+/** Look up a tombstone by tenant + digest: one indexed point query, the guard's common-case cost; a miss ends the guard. */
 export function findRejectedValue(db, tenantId, digest) {
     // SAFETY: row's shape matches the columns named in the SELECT above.
     const row = db
@@ -77,10 +51,7 @@ export function findRejectedValue(db, tenantId, digest) {
         .get(tenantId, digest);
     return row ? rowToRejectedValue(row) : null;
 }
-/**
- * Insert (or refresh) a tombstone row. Caller owns the transaction — used by
- * the `reject` verb and `resolveConflict`'s `rejectLoserValue` path.
- */
+/** Insert (or refresh) a tombstone row; the caller owns the transaction (used by the `reject` verb and `resolveConflict`'s `rejectLoserValue`). */
 export function insertRejectedValue(db, opts) {
     db.prepare(`INSERT INTO rejected_values(tenant_id, digest, reason, rejected_by, rejected_at, source_memory_id, normalized_chars)
      VALUES (?, ?, ?, ?, ?, ?, ?)
@@ -91,10 +62,7 @@ export function insertRejectedValue(db, opts) {
        source_memory_id = excluded.source_memory_id,
        normalized_chars = excluded.normalized_chars`).run(opts.tenantId, opts.digest, opts.reason, opts.rejectedBy, opts.rejectedAt, opts.sourceMemoryId ?? null, opts.normalizedChars);
 }
-/**
- * Delete a tombstone by tenant + exact digest: the `unreject` verb, the
- * only escape hatch.
- */
+/** Delete a tombstone by tenant + exact digest: the `unreject` verb, the only escape hatch. */
 export function deleteRejectedValue(db, tenantId, digest) {
     const result = db.prepare(`DELETE FROM rejected_values WHERE tenant_id = ? AND digest = ?`).run(tenantId, digest);
     return (result.changes ?? 0) > 0;
@@ -108,33 +76,14 @@ export function listRejectedValues(db, tenantId) {
         .all(tenantId);
     return rows.map(rowToRejectedValue);
 }
-/**
- * The write-path guard's check helper, called from `upsertEntryRow`
- * (store.ts). Fires when the incoming content's digest matches a tombstone
- * AND the write *introduces* that content: the row is new, OR the stored
- * row's content digest differs from the incoming one — an UPSERT editing a
- * same-id row TO a rejected value is a content introduction and must be
- * refused. Unchanged same-id re-persists (recall boost, decay, star toggle)
- * are exempt by construction (plan §3).
- *
- * Ordering minimizes queries on the common (miss) path: (a) caller has
- * already computed nothing yet — this does the digest + point lookup first;
- * (b) a miss returns immediately (ONE indexed point query); (c) only on a
- * tombstone hit does it SELECT the stored row's content to classify
- * new-row vs content-introduction (+1 query, rare path).
- */
+/** Write-path guard check: fires when the digest matches a tombstone AND the write introduces that content (a new row, or a same-id UPSERT changing it).
+ * Unchanged same-id re-persists (recall boost, decay, star toggle) are exempt. A miss costs ONE indexed point query; only a hit SELECTs the stored row. */
 export function checkRejectionGuard(db, tenantId, entryId, content) {
     const incomingDigest = rejectionDigest(content);
     const tombstone = findRejectedValue(db, tenantId, incomingDigest);
     if (!tombstone)
         return; // miss ends the guard — the overwhelmingly common case
-    // Deliberately id-only (no tenant filter): memory ids are globally unique
-    // ULIDs, this lookup only classifies new-row vs same-id re-persist for the
-    // id the caller is already writing, and the tombstone lookup above is the
-    // tenant-scoped decision. Matches deleteEntry's own by-id SELECT.
-    //
-    // Also read tenant_id: a same-id upsert that only changes tenantId introduces the
-    // content into the destination tenant, exactly as if the row were new there.
+    // Id-only on purpose (ids are global ULIDs; the tombstone lookup is tenant-scoped); tenant_id is read as a tenantId-only upsert introduces content there.
     // SAFETY: storedRow's shape matches the two columns named in the SELECT above.
     const storedRow = db.prepare(`SELECT content, tenant_id FROM memories WHERE id = ?`).get(entryId);
     const isNewRow = storedRow === undefined;

package/dist/store/report-reads.d.ts

@@ -0,0 +1,6 @@
+import type { MemoryEntry } from '../core/memory.js';
+/** Every superseded row, the row that replaced it and that row's extraction source, in loadAllEntries' order: all a correction-latency report reads. */
+export declare function loadCorrectionEntries(hippoRoot: string): MemoryEntry[];
+/** The kind='raw' rows in loadAllEntries' order: all a provenance-coverage report reads. */
+export declare function loadRawEntries(hippoRoot: string): MemoryEntry[];
+//# sourceMappingURL=report-reads.d.ts.map

package/dist/store/report-reads.js

@@ -0,0 +1,29 @@
+import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
+import { onHandle, openStore } from './open.js';
+/** Every superseded row, the row that replaced it and that row's extraction source, in loadAllEntries' order: all a correction-latency report reads. */
+export function loadCorrectionEntries(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        const superseded = `superseded_by IS NOT NULL AND superseded_by != ''`;
+        // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+        const rows = db.prepare(`
+      SELECT ${MEMORY_SELECT_COLUMNS} FROM memories
+      WHERE (${superseded})
+        OR id IN (SELECT superseded_by FROM memories WHERE ${superseded})
+        OR id IN (
+          SELECT extracted_from FROM memories
+          WHERE extracted_from IS NOT NULL AND id IN (SELECT superseded_by FROM memories WHERE ${superseded})
+        )
+      ORDER BY created ASC, id ASC
+    `).all();
+        return rows.map(rowToEntry);
+    }, openStore);
+}
+/** The kind='raw' rows in loadAllEntries' order: all a provenance-coverage report reads. */
+export function loadRawEntries(hippoRoot) {
+    return onHandle(hippoRoot, (db) => {
+        // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+        const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE kind = 'raw' ORDER BY created ASC, id ASC`).all();
+        return rows.map(rowToEntry);
+    }, openStore);
+}
+//# sourceMappingURL=report-reads.js.map

package/dist/store/rows.d.ts

@@ -1,5 +1,6 @@
-import { Layer, type MemoryEntry, type ConfidenceLevel } from '../memory.js';
-import type { JsonValue } from '../json.js';
+import { Layer, type MemoryEntry, type ConfidenceLevel } from '../core/memory.js';
+import { type JsonValue } from '../util/json.js';
+import { type StoredJsonSite } from '../util/stored-json.js';
 export interface IndexEntry {
     id: string;
     file: string;
@@ -134,29 +135,17 @@ export interface SessionEvent {
     created_at: string;
 }
 export declare const INDEX_VERSION = 3;
-export declare const MEMORY_SELECT_COLUMNS = "id, created, last_retrieved, retrieval_count, strength, half_life_days, layer, tags_json, emotional_valence, schema_fit, source, outcome_score, outcome_positive, outcome_negative, conflicts_with_json, pinned, confidence, content, parents_json, starred, trace_outcome, source_session_id, valid_from, superseded_by, extracted_from, dag_level, dag_parent_id, kind, scope, owner, artifact_ref, tenant_id, origin_project, descendant_count, earliest_at, latest_at, summary_dirty, last_rebuilt_at, rebuild_count, dag_level_3_built_at";
-export declare const MEMORY_SEARCH_COLUMNS = "m.id AS id, m.created AS created, m.last_retrieved AS last_retrieved, m.retrieval_count AS retrieval_count, m.strength AS strength, m.half_life_days AS half_life_days, m.layer AS layer, m.tags_json AS tags_json, m.emotional_valence AS emotional_valence, m.schema_fit AS schema_fit, m.source AS source, m.outcome_score AS outcome_score, m.outcome_positive AS outcome_positive, m.outcome_negative AS outcome_negative, m.conflicts_with_json AS conflicts_with_json, m.pinned AS pinned, m.confidence AS confidence, m.content AS content, m.parents_json AS parents_json, m.starred AS starred, m.trace_outcome AS trace_outcome, m.source_session_id AS source_session_id, m.valid_from AS valid_from, m.superseded_by AS superseded_by, m.extracted_from AS extracted_from, m.dag_level AS dag_level, m.dag_parent_id AS dag_parent_id, m.kind AS kind, m.scope AS scope, m.owner AS owner, m.artifact_ref AS artifact_ref, m.tenant_id AS tenant_id, m.origin_project AS origin_project, m.descendant_count AS descendant_count, m.earliest_at AS earliest_at, m.latest_at AS latest_at, m.summary_dirty AS summary_dirty, m.last_rebuilt_at AS last_rebuilt_at, m.rebuild_count AS rebuild_count, m.dag_level_3_built_at AS dag_level_3_built_at, bm25(memories_fts) AS bm25_score";
-/**
- * Default candidate-pool size for `loadSearchEntries` when called with
- * `limit === undefined`. Single source of truth; `api.recall` imports
- * this for `RecallResult.windowSize` reporting so the two cannot drift.
- */
+export declare const MEMORY_SELECT_COLUMNS: string;
+export declare const MEMORY_SEARCH_COLUMNS: string;
+/** Default candidate-pool size for `loadSearchEntries` when `limit` is undefined; `api.recall` imports it for `RecallResult.windowSize` so the two cannot
+ * drift. */
 export declare const DEFAULT_SEARCH_CANDIDATE_LIMIT = 200;
 export declare function rowToEntry(row: MemoryRow): MemoryEntry;
-export declare function parseJsonArray(raw: string | null | undefined): string[];
-/**
- * Strict parse for the `last_trace_id` meta value.
- * A bare Number(raw) would turn '', whitespace, or garbage into a
- * usable-looking 0/NaN — a consumer INSERTing recall_trace_outcomes with
- * trace_id=0 would hit a masked FK violation (row id 0 never exists).
- * Require a clean positive integer string; anything else is treated as
- * unset. This is the ONE place that decides "clean" — every consumer of
- * `HippoIndex.last_trace_id` (outcomeForLastRecall, tests) reads the
- * already-validated value out of `buildIndexFromDb`'s result and never
- * re-parses the raw meta string itself.
- */
+/** A column that is not JSON reads as empty. With `site` the row is named at warn once; without it no row is known and the line stays at debug. */
+export declare function parseJsonArray(raw: string | null | undefined, site?: StoredJsonSite): string[];
+/** Strict parse for `last_trace_id`: Number(raw) turns '' or garbage into 0/NaN (a masked FK violation); require a clean positive integer string, else unset.
+ * The ONE place that decides 'clean'; consumers read the validated value from `buildIndexFromDb`'s result and never re-parse. */
 export declare function parseLastTraceId(raw: string | null | undefined): string | null;
-export declare function isPlainJsonObject(x: JsonValue): x is Record<string, JsonValue>;
 export declare function rowToTaskSnapshot(row: TaskSnapshotRow): TaskSnapshot;
 export declare function rowToMemoryConflict(row: MemoryConflictRow): MemoryConflict;
 export declare function rowToSessionEvent(row: SessionEventRow): SessionEvent;

package/dist/store/rows.js

@@ -1,42 +1,56 @@
-import { log } from '../log.js';
+import { DEFAULT_TENANT_ID } from '../util/env.js';
+import { FALLBACK_HALF_LIFE_DAYS, DEFAULT_SCHEMA_FIT } from '../core/memory.js';
+import { errorMessage, log } from '../util/log.js';
+import { isJsonObject } from '../util/json.js';
+import { warnDamagedColumn } from '../util/stored-json.js';
 export const INDEX_VERSION = 3;
-export const MEMORY_SELECT_COLUMNS = `id, created, last_retrieved, retrieval_count, strength, half_life_days, layer, tags_json, emotional_valence, schema_fit, source, outcome_score, outcome_positive, outcome_negative, conflicts_with_json, pinned, confidence, content, parents_json, starred, trace_outcome, source_session_id, valid_from, superseded_by, extracted_from, dag_level, dag_parent_id, kind, scope, owner, artifact_ref, tenant_id, origin_project, descendant_count, earliest_at, latest_at, summary_dirty, last_rebuilt_at, rebuild_count, dag_level_3_built_at`;
-// FTS-join columns for loadSearchRows: each is `m.<col> AS <col>` so rowToEntry's unqualified
-// reads still work, and the trailing bm25(memories_fts) AS bm25_score carries the FTS rank.
-export const MEMORY_SEARCH_COLUMNS = `m.id AS id, m.created AS created, m.last_retrieved AS last_retrieved, m.retrieval_count AS retrieval_count, m.strength AS strength, m.half_life_days AS half_life_days, m.layer AS layer, m.tags_json AS tags_json, m.emotional_valence AS emotional_valence, m.schema_fit AS schema_fit, m.source AS source, m.outcome_score AS outcome_score, m.outcome_positive AS outcome_positive, m.outcome_negative AS outcome_negative, m.conflicts_with_json AS conflicts_with_json, m.pinned AS pinned, m.confidence AS confidence, m.content AS content, m.parents_json AS parents_json, m.starred AS starred, m.trace_outcome AS trace_outcome, m.source_session_id AS source_session_id, m.valid_from AS valid_from, m.superseded_by AS superseded_by, m.extracted_from AS extracted_from, m.dag_level AS dag_level, m.dag_parent_id AS dag_parent_id, m.kind AS kind, m.scope AS scope, m.owner AS owner, m.artifact_ref AS artifact_ref, m.tenant_id AS tenant_id, m.origin_project AS origin_project, m.descendant_count AS descendant_count, m.earliest_at AS earliest_at, m.latest_at AS latest_at, m.summary_dirty AS summary_dirty, m.last_rebuilt_at AS last_rebuilt_at, m.rebuild_count AS rebuild_count, m.dag_level_3_built_at AS dag_level_3_built_at, bm25(memories_fts) AS bm25_score`;
-/**
- * Default candidate-pool size for `loadSearchEntries` when called with
- * `limit === undefined`. Single source of truth; `api.recall` imports
- * this for `RecallResult.windowSize` reporting so the two cannot drift.
- */
+const MEMORY_COLUMN_NAMES = [
+    'id', 'created', 'last_retrieved', 'retrieval_count', 'strength', 'half_life_days', 'layer', 'tags_json',
+    'emotional_valence', 'schema_fit', 'source', 'outcome_score', 'outcome_positive', 'outcome_negative',
+    'conflicts_with_json', 'pinned', 'confidence', 'content', 'parents_json', 'starred', 'trace_outcome',
+    'source_session_id', 'valid_from', 'superseded_by', 'extracted_from', 'dag_level', 'dag_parent_id', 'kind', 'scope',
+    'owner', 'artifact_ref', 'tenant_id', 'origin_project', 'descendant_count', 'earliest_at', 'latest_at',
+    'summary_dirty', 'last_rebuilt_at', 'rebuild_count', 'dag_level_3_built_at',
+];
+// FTS-join columns for loadSearchRows: `m.<col> AS <col>` keeps rowToEntry's unqualified reads working.
+export const MEMORY_SELECT_COLUMNS = MEMORY_COLUMN_NAMES.join(', ');
+export const MEMORY_SEARCH_COLUMNS = [
+    ...MEMORY_COLUMN_NAMES.map((c) => `m.${c} AS ${c}`),
+    'bm25(memories_fts) AS bm25_score',
+].join(', ');
+/** Default candidate-pool size for `loadSearchEntries` when `limit` is undefined; `api.recall` imports it for `RecallResult.windowSize` so the two cannot
+ * drift. */
 export const DEFAULT_SEARCH_CANDIDATE_LIMIT = 200;
-export function rowToEntry(row) {
-    // SAFETY: every `as X` below narrows a SQLite column value to an
-    // enum/union member of MemoryEntry; `row` comes from MEMORY_SELECT_COLUMNS
-    // / MEMORY_SEARCH_COLUMNS, which are the only queries producing MemoryRow,
-    // and the DB layer only ever writes these columns from the same enums.
-    const entry = {
+function rowToRetrievalFields(row) {
+    // SAFETY: every `as X` narrows a SQLite column to a MemoryEntry enum/union member; `row` comes from MEMORY_SELECT_COLUMNS / MEMORY_SEARCH_COLUMNS,
+    // the only queries producing MemoryRow, and the DB layer writes these columns only from the same enums.
+    return {
         id: row.id,
         created: row.created,
         last_retrieved: row.last_retrieved,
         retrieval_count: Number(row.retrieval_count ?? 0),
         strength: Number(row.strength ?? 1),
-        half_life_days: Number(row.half_life_days ?? 7),
+        half_life_days: Number(row.half_life_days ?? FALLBACK_HALF_LIFE_DAYS),
         layer: row.layer,
-        tags: parseJsonArray(row.tags_json),
+        tags: parseJsonArray(row.tags_json, { table: 'memories', id: row.id, column: 'tags_json' }),
         emotional_valence: row.emotional_valence ?? 'neutral',
-        schema_fit: Number(row.schema_fit ?? 0.5),
+        schema_fit: Number(row.schema_fit ?? DEFAULT_SCHEMA_FIT),
         source: row.source ?? 'cli',
         outcome_score: row.outcome_score === null || row.outcome_score === undefined ? null : Number(row.outcome_score),
         outcome_positive: Number(row.outcome_positive ?? 0),
         outcome_negative: Number(row.outcome_negative ?? 0),
-        conflicts_with: parseJsonArray(row.conflicts_with_json),
+        conflicts_with: parseJsonArray(row.conflicts_with_json, { table: 'memories', id: row.id, column: 'conflicts_with_json' }),
         pinned: Boolean(row.pinned),
         confidence: row.confidence ?? 'observed',
         content: row.content,
-        parents: parseJsonArray(row.parents_json),
+        parents: parseJsonArray(row.parents_json, { table: 'memories', id: row.id, column: 'parents_json' }),
         starred: Boolean(row.starred),
         trace_outcome: row.trace_outcome ?? null,
+    };
+}
+function rowToPlacementFields(row) {
+    // SAFETY: the `as MemoryKind` narrows a column the DB layer only writes from that enum.
+    return {
         source_session_id: row.source_session_id ?? null,
         valid_from: row.valid_from ?? row.created,
         superseded_by: row.superseded_by ?? null,
@@ -47,7 +61,7 @@ export function rowToEntry(row) {
         scope: row.scope ?? null,
         owner: row.owner ?? null,
         artifact_ref: row.artifact_ref ?? null,
-        tenantId: row.tenant_id ?? 'default',
+        tenantId: row.tenant_id ?? DEFAULT_TENANT_ID,
         origin_project: row.origin_project ?? null,
         descendant_count: Number(row.descendant_count ?? 0),
         earliest_at: row.earliest_at ?? null,
@@ -57,6 +71,9 @@ export function rowToEntry(row) {
         rebuild_count: Number(row.rebuild_count ?? 0),
         dag_level_3_built_at: row.dag_level_3_built_at ?? null,
     };
+}
+export function rowToEntry(row) {
+    const entry = { ...rowToRetrievalFields(row), ...rowToPlacementFields(row) };
     // Preserve bm25_score from the FTS path; `'bm25_score' in row` tells an absent column
     // (non-FTS path) from a present one.
     if ('bm25_score' in row && row.bm25_score !== undefined && row.bm25_score !== null) {
@@ -64,7 +81,8 @@ export function rowToEntry(row) {
     }
     return entry;
 }
-export function parseJsonArray(raw) {
+/** A column that is not JSON reads as empty. With `site` the row is named at warn once; without it no row is known and the line stays at debug. */
+export function parseJsonArray(raw, site) {
     if (!raw)
         return [];
     try {
@@ -72,42 +90,33 @@ export function parseJsonArray(raw) {
         return Array.isArray(parsed) ? parsed.map((item) => String(item)) : [];
     }
     catch (err) {
-        log.debug(`store: corrupt JSON array column read as empty: ${err instanceof Error ? err.message : String(err)}`);
+        if (site)
+            warnDamagedColumn(site, 'not valid JSON');
+        else
+            log.debug(`store: corrupt JSON array column read as empty: ${errorMessage(err)}`);
         return [];
     }
 }
-/**
- * Strict parse for the `last_trace_id` meta value.
- * A bare Number(raw) would turn '', whitespace, or garbage into a
- * usable-looking 0/NaN — a consumer INSERTing recall_trace_outcomes with
- * trace_id=0 would hit a masked FK violation (row id 0 never exists).
- * Require a clean positive integer string; anything else is treated as
- * unset. This is the ONE place that decides "clean" — every consumer of
- * `HippoIndex.last_trace_id` (outcomeForLastRecall, tests) reads the
- * already-validated value out of `buildIndexFromDb`'s result and never
- * re-parses the raw meta string itself.
- */
+/** Strict parse for `last_trace_id`: Number(raw) turns '' or garbage into 0/NaN (a masked FK violation); require a clean positive integer string, else unset.
+ * The ONE place that decides 'clean'; consumers read the validated value from `buildIndexFromDb`'s result and never re-parse. */
 export function parseLastTraceId(raw) {
     const trimmed = (raw ?? '').trim();
     if (!/^\d+$/.test(trimmed) || Number(trimmed) <= 0)
         return null;
     return trimmed;
 }
-export function isPlainJsonObject(x) {
-    return x !== null && typeof x === 'object' && !Array.isArray(x);
-}
-function parseJsonObject(raw) {
+function parseJsonObject(raw, site) {
     if (!raw)
         return {};
     try {
         const parsed = JSON.parse(raw);
-        if (isPlainJsonObject(parsed)) {
+        if (isJsonObject(parsed)) {
             return parsed;
         }
         return {};
     }
-    catch (err) {
-        log.debug(`store: corrupt JSON object column read as empty: ${err instanceof Error ? err.message : String(err)}`);
+    catch {
+        warnDamagedColumn(site, 'not valid JSON');
         return {};
     }
 }
@@ -146,7 +155,7 @@ export function rowToSessionEvent(row) {
         content: row.content,
         source: row.source,
         scope: row.scope ?? null,
-        metadata: parseJsonObject(row.metadata_json),
+        metadata: parseJsonObject(row.metadata_json, { table: 'session_events', id: row.id, column: 'metadata_json' }),
         created_at: row.created_at,
     };
 }

package/dist/store/rule-sql.d.ts

@@ -0,0 +1,5 @@
+/** calculateStrength's clock-basis formula as SQL over `memories` columns, flags and multipliers baked in; keep in step.
+ *  An unparseable date scores NULL here and 0 in JS, so sums agree. */
+export declare function strengthSql(now: Date): string;
+export declare const AUTO_DELETABLE_SQL: string;
+//# sourceMappingURL=rule-sql.d.ts.map