@atomicmemory/core 1.0.0

package/dist/db/document-chunk-types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Row + input types for the document_chunks table (Phase 2).
+ *
+ * Mirrors the columns in `schema.sql`. The `embedding` field stays on
+ * the row (vs being held only in `memories.embedding`) so the chunk
+ * store supports raw chunk-level lookups for re-index and audit
+ * without round-tripping through the memory layer.
+ */
+/**
+ * Fields shared by the persisted row and the insert input. Extracted
+ * so the two shapes don't drift independently.
+ */
+interface DocumentChunkBody {
+    userId: string;
+    rawDocumentId: string;
+    chunkIndex: number;
+    content: string;
+    contentHash: string;
+    charStart: number;
+    charEnd: number;
+    tokenCount: number;
+    embedding: number[];
+    parserVersion: string;
+    chunkerVersion: string;
+}
+export interface DocumentChunkRow extends DocumentChunkBody {
+    id: string;
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    deletedAt: Date | null;
+}
+export interface InsertDocumentChunkInput extends DocumentChunkBody {
+    metadata?: Record<string, unknown>;
+}
+export {};

package/dist/db/document-chunk-types.js

@@ -0,0 +1,9 @@
+/**
+ * Row + input types for the document_chunks table (Phase 2).
+ *
+ * Mirrors the columns in `schema.sql`. The `embedding` field stays on
+ * the row (vs being held only in `memories.embedding`) so the chunk
+ * store supports raw chunk-level lookups for re-index and audit
+ * without round-tripping through the memory layer.
+ */
+export {};

package/dist/db/document-list-cursor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Phase D — opaque base64 cursor helpers for the document list /
+ * recovery / passport-feed endpoints.
+ *
+ * Cursor encodes `{ sortAt, sortId }`: a tuple that is strictly
+ * less-than-comparable in the underlying SQL using `(sortAt, sortId) <
+ * ($cursor.sortAt, $cursor.sortId)`. Callers pick which column drives
+ * the sort (`raw_documents.created_at` for the standalone-list and
+ * recovery feeds; the grouped passport-feed uses
+ * `MAX(memories.created_at)` for memory-backed rows and
+ * `raw_documents.created_at` for synthetic ones).
+ *
+ * The cursor is base64-url-encoded JSON so it round-trips through
+ * query strings cleanly. Callers must validate `decodeListCursor`'s
+ * `null` return as "malformed cursor" and 400 — the helper does NOT
+ * throw on bad input so route handlers can map invalid cursors to a
+ * 400 instead of a 500. ISO date strings on the wire keep the cursor
+ * human-readable in logs.
+ *
+ * Phase D review-fix: structural validation extends past "is a
+ * non-empty string" — `sortAt` MUST be a parseable ISO 8601 timestamp
+ * and `sortId` MUST be a UUID. Without that, a structurally valid
+ * base64url cursor like
+ * `{"sortAt":"not-a-date","sortId":"not-a-uuid"}` would slip past
+ * the cursor decoder and hit the underlying SQL cast (`$N::timestamptz`
+ * / `$N::uuid`), producing a 500 from Postgres instead of the
+ * intended 400 invalid_cursor.
+ */
+export interface DocumentListCursor {
+    sortAt: string;
+    sortId: string;
+}
+/**
+ * Encode a `(sortAt, sortId)` tuple to an opaque cursor string.
+ * `sortAt` should already be ISO 8601; the helper does not coerce
+ * Date instances on purpose, so callers see the formatting bug at
+ * source if they forget to `.toISOString()`.
+ */
+export declare function encodeListCursor(cursor: DocumentListCursor): string;
+/**
+ * Decode an opaque cursor string. Returns null on missing input,
+ * malformed base64, malformed JSON, or a payload that doesn't carry
+ * both fields with the right types.
+ */
+export declare function decodeListCursor(raw: string | undefined | null): DocumentListCursor | null;

package/dist/db/document-list-cursor.js

@@ -0,0 +1,111 @@
+/**
+ * Phase D — opaque base64 cursor helpers for the document list /
+ * recovery / passport-feed endpoints.
+ *
+ * Cursor encodes `{ sortAt, sortId }`: a tuple that is strictly
+ * less-than-comparable in the underlying SQL using `(sortAt, sortId) <
+ * ($cursor.sortAt, $cursor.sortId)`. Callers pick which column drives
+ * the sort (`raw_documents.created_at` for the standalone-list and
+ * recovery feeds; the grouped passport-feed uses
+ * `MAX(memories.created_at)` for memory-backed rows and
+ * `raw_documents.created_at` for synthetic ones).
+ *
+ * The cursor is base64-url-encoded JSON so it round-trips through
+ * query strings cleanly. Callers must validate `decodeListCursor`'s
+ * `null` return as "malformed cursor" and 400 — the helper does NOT
+ * throw on bad input so route handlers can map invalid cursors to a
+ * 400 instead of a 500. ISO date strings on the wire keep the cursor
+ * human-readable in logs.
+ *
+ * Phase D review-fix: structural validation extends past "is a
+ * non-empty string" — `sortAt` MUST be a parseable ISO 8601 timestamp
+ * and `sortId` MUST be a UUID. Without that, a structurally valid
+ * base64url cursor like
+ * `{"sortAt":"not-a-date","sortId":"not-a-uuid"}` would slip past
+ * the cursor decoder and hit the underlying SQL cast (`$N::timestamptz`
+ * / `$N::uuid`), producing a 500 from Postgres instead of the
+ * intended 400 invalid_cursor.
+ */
+const CURSOR_UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Server-emitted cursor `sortAt` is always `Date#toISOString()`, which
+ * produces ISO-8601 UTC with millisecond precision and a trailing `Z`
+ * (`YYYY-MM-DDTHH:mm:ss.sssZ`). Tightening the validator to this
+ * exact shape (plus a `Date` round-trip below) rejects parseable-but-
+ * non-server formats like `"2026-05-10"` or `"May 10 2026"` that
+ * `Date.parse` would otherwise admit. This stops a caller (or
+ * attacker) from crafting a cursor whose `sortAt` parses to a real
+ * timestamp but does not correspond to a value the cursor encoder
+ * could ever have emitted.
+ */
+const CURSOR_SORT_AT_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+/** Base64url encode a UTF-8 string (RFC 4648 §5; no padding). */
+function base64urlEncode(input) {
+    return Buffer.from(input, 'utf8')
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+/** Inverse of {@link base64urlEncode}. Returns null on malformed input. */
+function base64urlDecode(input) {
+    try {
+        const padded = input.replace(/-/g, '+').replace(/_/g, '/');
+        return Buffer.from(padded, 'base64').toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Encode a `(sortAt, sortId)` tuple to an opaque cursor string.
+ * `sortAt` should already be ISO 8601; the helper does not coerce
+ * Date instances on purpose, so callers see the formatting bug at
+ * source if they forget to `.toISOString()`.
+ */
+export function encodeListCursor(cursor) {
+    return base64urlEncode(JSON.stringify(cursor));
+}
+/**
+ * Decode an opaque cursor string. Returns null on missing input,
+ * malformed base64, malformed JSON, or a payload that doesn't carry
+ * both fields with the right types.
+ */
+export function decodeListCursor(raw) {
+    if (raw === undefined || raw === null || raw.length === 0)
+        return null;
+    const decoded = base64urlDecode(raw);
+    if (decoded === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const obj = parsed;
+    if (typeof obj.sortAt !== 'string' || typeof obj.sortId !== 'string')
+        return null;
+    if (obj.sortAt.length === 0 || obj.sortId.length === 0)
+        return null;
+    // Validate sortAt against the exact server-emitted ISO UTC
+    // millisecond shape AND a Date round-trip. The regex covers the
+    // syntactic shape; the round-trip catches values like
+    // `"2026-13-99T..."` that match the regex but don't represent
+    // real dates. Together this rejects every cursor that could not
+    // have come from this server's `Date#toISOString()`.
+    if (!CURSOR_SORT_AT_REGEX.test(obj.sortAt))
+        return null;
+    const sortAtDate = new Date(obj.sortAt);
+    if (Number.isNaN(sortAtDate.getTime()))
+        return null;
+    if (sortAtDate.toISOString() !== obj.sortAt)
+        return null;
+    // Validate sortId is a UUID the SQL `::uuid` cast will accept.
+    if (!CURSOR_UUID_REGEX.test(obj.sortId))
+        return null;
+    return { sortAt: obj.sortAt, sortId: obj.sortId };
+}

package/dist/db/document-list-repository.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Phase D — focused module for the cursor-paginated user-scoped
+ * document list helpers (`GET /v1/documents`,
+ * `GET /v1/documents/without-memories`).
+ *
+ * Split out from `raw-document-repository.ts` to keep that file
+ * under the 400 non-comment LOC workspace rule. The legacy
+ * offset/limit + source_site `listRawDocuments` helper still lives
+ * in `raw-document-repository.ts`; only the Phase D cursor-based
+ * surfaces are here.
+ *
+ * Imports `RAW_DOCUMENT_COLUMNS` + `rowToRawDocument` from the
+ * sibling repo so the canonical column set + projection stays in
+ * one place.
+ */
+import type pg from 'pg';
+import { type DocumentListCursor } from './document-list-cursor.js';
+import type { RawDocumentRow } from './raw-document-types.js';
+/**
+ * Phase D — coarse status-bucket filter for the standalone
+ * `GET /v1/documents` list endpoint. The buckets pivot on the new
+ * Phase B per-layer status columns; `'all'` returns every active
+ * row. The recovery-relevant buckets serve the UI's
+ * "what is broken / what needs attention" surfaces; the
+ * `'unsupported'` bucket lights up `.parquet` and similar
+ * stored-but-not-indexed files.
+ */
+export type DocumentListStatusFilter = 'failed' | 'unsupported' | 'pending' | 'all';
+export interface ListDocumentsForUserInput {
+    userId: string;
+    limit?: number;
+    cursor?: DocumentListCursor | null;
+    statusFilter?: DocumentListStatusFilter;
+}
+export interface ListDocumentsForUserResult {
+    documents: RawDocumentRow[];
+    nextCursor: string | null;
+}
+/**
+ * Phase D — cursor-paginated user-scoped document list with optional
+ * recovery-status bucket filter. Distinct from `listRawDocuments`
+ * (offset/limit + source_site filter) which backs the legacy
+ * `GET /v1/documents/list` route.
+ *
+ * Cursor semantics: stable ordering on `(created_at DESC, id DESC)`.
+ * Standard `+1 over-fetch` pattern; `nextCursor` only when more
+ * rows exist beyond the current page.
+ *
+ * Status filter expressions:
+ *   - 'failed' — any layer is failed (extraction OR semantic_index OR
+ *     raw_storage)
+ *   - 'unsupported' — extraction_status = 'unsupported' (the
+ *     deliberately-not-indexed bucket)
+ *   - 'pending' — extraction or semantic_index is pending/running.
+ *     Forward-compatible with the future async-worker PR; in this
+ *     PR's synchronous flow `running` matches only manually seeded
+ *     rows (the Phase B indexer never commits 'running').
+ *   - 'all' — no status filter.
+ */
+export declare function listDocumentsForUser(pool: pg.Pool, input: ListDocumentsForUserInput): Promise<ListDocumentsForUserResult>;
+/**
+ * Phase D — layer-aware recovery filter consumed by
+ * {@link listDocumentsWithoutMemoriesForUser}. Each layer's array (when
+ * supplied) narrows that layer to one of the values; rows match when
+ * ANY layer's value is in its array. An empty array on a layer means
+ * "do not match this layer at all" (deliberate — the layer can be
+ * scoped out by passing `[]` rather than omitting the key).
+ */
+export interface DocumentRecoveryStatusFilter {
+    extraction?: Array<'pending' | 'running' | 'failed' | 'unsupported'>;
+    semantic_index?: Array<'pending' | 'running' | 'failed' | 'stale'>;
+    /**
+     * Filecoin lifecycle refactor (Slice 2): includes `blob_pending`
+     * (eventual provider still propagating) and `blob_archival_failed`
+     * (Phase 3 reconciler's permanent-failure terminal) so a row stuck
+     * in either state surfaces to `/without-memories`. `blob_available`
+     * and `blob_tombstoned` are terminal-OK / no-longer-managed and
+     * deliberately NOT recovery targets.
+     */
+    raw_storage?: Array<'raw_storage_failed' | 'pointer_recorded' | 'blob_pending' | 'blob_archival_failed'>;
+}
+export interface ListDocumentsWithoutMemoriesInput {
+    userId: string;
+    limit?: number;
+    cursor?: DocumentListCursor | null;
+    statusFilter?: DocumentRecoveryStatusFilter;
+}
+/**
+ * Phase D — list active documents with ZERO non-deleted memories AND
+ * matching the layer-aware recovery filter. Backs
+ * `GET /v1/documents/without-memories` and the document-only stream
+ * of the passport server-side merge.
+ *
+ * Visibility: a row appears when it is the user's, not soft-deleted,
+ * has no memories pointing to it (strict `NOT EXISTS` over
+ * `memories.raw_document_id`), and at least one layer status sits in
+ * its filter array. Default filter is recovery-relevant — failed,
+ * pending, or unsupported across the three layers — so happy-path
+ * pointer-only documents that simply have no chunks (e.g., future
+ * Drive listings) do NOT surface in the passport synthetic-row
+ * stream.
+ */
+export declare function listDocumentsWithoutMemoriesForUser(pool: pg.Pool, input: ListDocumentsWithoutMemoriesInput): Promise<ListDocumentsForUserResult>;

package/dist/db/document-list-repository.js

@@ -0,0 +1,204 @@
+/**
+ * Phase D — focused module for the cursor-paginated user-scoped
+ * document list helpers (`GET /v1/documents`,
+ * `GET /v1/documents/without-memories`).
+ *
+ * Split out from `raw-document-repository.ts` to keep that file
+ * under the 400 non-comment LOC workspace rule. The legacy
+ * offset/limit + source_site `listRawDocuments` helper still lives
+ * in `raw-document-repository.ts`; only the Phase D cursor-based
+ * surfaces are here.
+ *
+ * Imports `RAW_DOCUMENT_COLUMNS` + `rowToRawDocument` from the
+ * sibling repo so the canonical column set + projection stays in
+ * one place.
+ */
+import { encodeListCursor, } from './document-list-cursor.js';
+import { RAW_DOCUMENT_COLUMNS, rowToRawDocument, } from './raw-document-repository.js';
+const LIST_DEFAULT_LIMIT = 50;
+const LIST_MAX_LIMIT = 100;
+/**
+ * Phase D — cursor-paginated user-scoped document list with optional
+ * recovery-status bucket filter. Distinct from `listRawDocuments`
+ * (offset/limit + source_site filter) which backs the legacy
+ * `GET /v1/documents/list` route.
+ *
+ * Cursor semantics: stable ordering on `(created_at DESC, id DESC)`.
+ * Standard `+1 over-fetch` pattern; `nextCursor` only when more
+ * rows exist beyond the current page.
+ *
+ * Status filter expressions:
+ *   - 'failed' — any layer is failed (extraction OR semantic_index OR
+ *     raw_storage)
+ *   - 'unsupported' — extraction_status = 'unsupported' (the
+ *     deliberately-not-indexed bucket)
+ *   - 'pending' — extraction or semantic_index is pending/running.
+ *     Forward-compatible with the future async-worker PR; in this
+ *     PR's synchronous flow `running` matches only manually seeded
+ *     rows (the Phase B indexer never commits 'running').
+ *   - 'all' — no status filter.
+ */
+export async function listDocumentsForUser(pool, input) {
+    const limit = clampListLimit(input.limit);
+    const overFetch = limit + 1;
+    const params = [input.userId, overFetch];
+    const wheres = ['user_id = $1', 'deleted_at IS NULL'];
+    const statusClause = buildStatusFilterSql(input.statusFilter ?? 'all', params);
+    if (statusClause !== null)
+        wheres.push(statusClause);
+    if (input.cursor) {
+        params.push(input.cursor.sortAt, input.cursor.sortId);
+        wheres.push(`(created_at, id) < ($${params.length - 1}::timestamptz, $${params.length}::uuid)`);
+    }
+    const sql = `SELECT ${RAW_DOCUMENT_COLUMNS}
+                 FROM raw_documents
+                WHERE ${wheres.join(' AND ')}
+                ORDER BY created_at DESC, id DESC
+                LIMIT $2`;
+    const result = await pool.query(sql, params);
+    return slicePageWithCursor(result.rows.map(rowToRawDocument), limit);
+}
+function clampListLimit(raw) {
+    if (raw === undefined)
+        return LIST_DEFAULT_LIMIT;
+    if (!Number.isFinite(raw))
+        return LIST_DEFAULT_LIMIT;
+    return Math.max(1, Math.min(LIST_MAX_LIMIT, Math.floor(raw)));
+}
+/**
+ * Append the parameterised SQL that narrows the document list to one
+ * recovery-status bucket. Returns the WHERE fragment (without leading
+ * AND), or null when the filter is `'all'`.
+ *
+ * Mutates `params` to push the literal status values; this keeps each
+ * value explicitly bound rather than embedded in the SQL string, so
+ * the query is fully prepared-statement friendly.
+ *
+ * Lifecycle awareness (Filecoin refactor):
+ *   - `failed` matches `extraction_status='failed'` OR
+ *     `semantic_index_status='failed'` OR `raw_storage_status` in
+ *     `{raw_storage_failed, blob_archival_failed}`. The two raw-storage
+ *     failure terminals are equivalent surfaces for "the bytes never
+ *     made it" — immediate-provider catch path vs Phase 3
+ *     reconciler's permanent-failure terminal — and both belong in
+ *     the same recovery bucket.
+ *   - `pending` matches extraction/semantic_index pending/running OR
+ *     `raw_storage_status='blob_pending'`. The eventual-provider
+ *     in-flight state belongs in the pending bucket alongside the
+ *     extraction/index pending/running rows.
+ *   - `unsupported` is raw-storage-agnostic.
+ */
+function buildStatusFilterSql(filter, params) {
+    if (filter === 'all')
+        return null;
+    if (filter === 'failed') {
+        params.push('failed', 'failed', 'raw_storage_failed', 'blob_archival_failed');
+        return `(extraction_status = $${params.length - 3}
+            OR semantic_index_status = $${params.length - 2}
+            OR raw_storage_status IN ($${params.length - 1}, $${params.length}))`;
+    }
+    if (filter === 'unsupported') {
+        params.push('unsupported');
+        return `extraction_status = $${params.length}`;
+    }
+    // 'pending' — extraction OR semantic_index OR raw_storage is in a
+    // pre-completion state. `running` is included for forward
+    // compatibility with the future async-worker PR; `blob_pending`
+    // is the Filecoin/eventual-provider in-flight state.
+    params.push('pending', 'running', 'pending', 'running', 'blob_pending');
+    return `(extraction_status IN ($${params.length - 4}, $${params.length - 3})
+          OR semantic_index_status IN ($${params.length - 2}, $${params.length - 1})
+          OR raw_storage_status = $${params.length})`;
+}
+/**
+ * Cursor-aware page slicer. The repository over-fetches by one row;
+ * if we got the full `limit + 1`, the last consumed row's
+ * `(created_at, id)` becomes the next cursor. Otherwise the page
+ * exhausts the stream and `nextCursor === null`.
+ */
+function slicePageWithCursor(candidates, limit) {
+    if (candidates.length <= limit) {
+        return { documents: candidates, nextCursor: null };
+    }
+    const documents = candidates.slice(0, limit);
+    const last = documents[documents.length - 1];
+    const sortAt = last.createdAt instanceof Date
+        ? last.createdAt.toISOString()
+        : String(last.createdAt);
+    return {
+        documents,
+        nextCursor: encodeListCursor({ sortAt, sortId: last.id }),
+    };
+}
+const DEFAULT_RECOVERY_STATUS_FILTER = {
+    extraction: ['pending', 'failed', 'unsupported'],
+    semantic_index: ['pending', 'failed'],
+    // `blob_pending` and `blob_archival_failed` join the default so a
+    // freshly-uploaded eventual-provider doc surfaces in the recovery
+    // feed until the Phase 3 reconciler promotes it (or marks it
+    // failed). `raw_storage_failed` stays for the existing upload-
+    // failure path. `pointer_recorded` is NOT in the default — its
+    // mere presence isn't a recovery signal — but the schema allows
+    // callers to request it explicitly.
+    raw_storage: ['raw_storage_failed', 'blob_pending', 'blob_archival_failed'],
+};
+/**
+ * Phase D — list active documents with ZERO non-deleted memories AND
+ * matching the layer-aware recovery filter. Backs
+ * `GET /v1/documents/without-memories` and the document-only stream
+ * of the passport server-side merge.
+ *
+ * Visibility: a row appears when it is the user's, not soft-deleted,
+ * has no memories pointing to it (strict `NOT EXISTS` over
+ * `memories.raw_document_id`), and at least one layer status sits in
+ * its filter array. Default filter is recovery-relevant — failed,
+ * pending, or unsupported across the three layers — so happy-path
+ * pointer-only documents that simply have no chunks (e.g., future
+ * Drive listings) do NOT surface in the passport synthetic-row
+ * stream.
+ */
+export async function listDocumentsWithoutMemoriesForUser(pool, input) {
+    const limit = clampListLimit(input.limit);
+    const overFetch = limit + 1;
+    const filter = mergeRecoveryFilter(input.statusFilter);
+    const params = [
+        input.userId,
+        overFetch,
+        filter.extraction,
+        filter.semantic_index,
+        filter.raw_storage,
+    ];
+    const wheres = [
+        'rd.user_id = $1',
+        'rd.deleted_at IS NULL',
+        'NOT EXISTS (SELECT 1 FROM memories m WHERE m.raw_document_id = rd.id AND m.deleted_at IS NULL)',
+        `(rd.extraction_status     = ANY($3::text[])
+     OR rd.semantic_index_status = ANY($4::text[])
+     OR rd.raw_storage_status    = ANY($5::text[]))`,
+    ];
+    if (input.cursor) {
+        params.push(input.cursor.sortAt, input.cursor.sortId);
+        wheres.push(`(rd.created_at, rd.id) < ($${params.length - 1}::timestamptz, $${params.length}::uuid)`);
+    }
+    const sql = `SELECT ${RAW_DOCUMENT_COLUMNS.split(', ').map((c) => `rd.${c}`).join(', ')}
+                 FROM raw_documents rd
+                WHERE ${wheres.join(' AND ')}
+                ORDER BY rd.created_at DESC, rd.id DESC
+                LIMIT $2`;
+    const result = await pool.query(sql, params);
+    return slicePageWithCursor(result.rows.map(rowToRawDocument), limit);
+}
+/**
+ * Apply the recovery-status default to any layer the caller omitted.
+ * Empty arrays passed by the caller are kept verbatim so callers can
+ * scope a layer out by passing `[]`.
+ */
+function mergeRecoveryFilter(override) {
+    if (!override)
+        return DEFAULT_RECOVERY_STATUS_FILTER;
+    return {
+        extraction: override.extraction ?? DEFAULT_RECOVERY_STATUS_FILTER.extraction,
+        semantic_index: override.semantic_index ?? DEFAULT_RECOVERY_STATUS_FILTER.semantic_index,
+        raw_storage: override.raw_storage ?? DEFAULT_RECOVERY_STATUS_FILTER.raw_storage,
+    };
+}

package/dist/db/entity-cards-repository.d.ts

@@ -0,0 +1,37 @@
+/**
+ * EntityCardsRepository — upsert + read for the always-on ENTITY_CARD channel.
+ *
+ * One row per (user_id, conversation_id, entity_name) holds a durable LLM-
+ * synthesized summary card for that entity. The Reflect worker re-synthesizes
+ * the card from new observations + prior card text on every run; the search
+ * pipeline injects all cards for the active conversation under `## ENTITY_STATE`.
+ *
+ * Pure SQL via pg.Pool. Mutations fail closed — errors propagate to the caller.
+ */
+import type pg from 'pg';
+export interface EntityCard {
+    id: string;
+    userId: string;
+    conversationId: string;
+    entityName: string;
+    cardText: string;
+    sourceObservationIds: string[];
+    version: number;
+    updatedAt: Date;
+}
+export interface UpsertEntityCardInput {
+    userId: string;
+    conversationId: string;
+    entityName: string;
+    cardText: string;
+    sourceObservationIds: string[];
+    version: number;
+}
+export declare class EntityCardsRepository {
+    private readonly pool;
+    constructor(pool: pg.Pool);
+    /** Upsert a card by (userId, conversationId, entityName). Increments version on update. */
+    upsert(input: UpsertEntityCardInput): Promise<void>;
+    /** Find cards for a (userId, conversationId), most recently updated first. */
+    findByConversation(userId: string, conversationId: string, limit: number): Promise<EntityCard[]>;
+}

package/dist/db/entity-cards-repository.js

@@ -0,0 +1,46 @@
+export class EntityCardsRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /** Upsert a card by (userId, conversationId, entityName). Increments version on update. */
+    async upsert(input) {
+        await this.pool.query(`INSERT INTO entity_cards
+         (user_id, conversation_id, entity_name, card_text, source_observation_ids, version, updated_at)
+       VALUES ($1, $2, $3, $4, $5, $6, now())
+       ON CONFLICT (user_id, conversation_id, entity_name) DO UPDATE
+         SET card_text = EXCLUDED.card_text,
+             source_observation_ids = EXCLUDED.source_observation_ids,
+             version = entity_cards.version + 1,
+             updated_at = now()`, [
+            input.userId,
+            input.conversationId,
+            input.entityName,
+            input.cardText,
+            input.sourceObservationIds,
+            input.version,
+        ]);
+    }
+    /** Find cards for a (userId, conversationId), most recently updated first. */
+    async findByConversation(userId, conversationId, limit) {
+        const { rows } = await this.pool.query(`SELECT id, user_id, conversation_id, entity_name, card_text,
+              source_observation_ids, version, updated_at
+       FROM entity_cards
+       WHERE user_id = $1 AND conversation_id = $2
+       ORDER BY updated_at DESC
+       LIMIT $3`, [userId, conversationId, limit]);
+        return rows.map(mapRow);
+    }
+}
+function mapRow(r) {
+    return {
+        id: r.id,
+        userId: r.user_id,
+        conversationId: r.conversation_id,
+        entityName: r.entity_name,
+        cardText: r.card_text,
+        sourceObservationIds: r.source_observation_ids,
+        version: r.version,
+        updatedAt: r.updated_at,
+    };
+}

package/dist/db/entity-values-repository.d.ts

@@ -0,0 +1,26 @@
+/**
+ * EntityValuesRepository — CRUD for the entity_values table populated at
+ * ingest. Used by the IE/KU literal-value specialist at retrieval.
+ */
+import pg from 'pg';
+export type ValueType = 'date' | 'number' | 'string' | 'duration' | 'list';
+export interface NewEntityValue {
+    userId: string;
+    entity: string;
+    attribute: string;
+    value: string;
+    valueType: ValueType;
+    observedAt: Date;
+    factId: string;
+}
+export interface EntityValue extends NewEntityValue {
+    id: string;
+    createdAt: Date;
+}
+export declare class EntityValuesRepository {
+    private readonly pool;
+    constructor(pool: pg.Pool);
+    insertMany(rows: readonly NewEntityValue[]): Promise<void>;
+    /** Fuzzy lookup: case-insensitive match on (entity, attribute), most recent first. */
+    findLatest(userId: string, entity: string, attribute: string): Promise<EntityValue | null>;
+}

package/dist/db/entity-values-repository.js

@@ -0,0 +1,57 @@
+export class EntityValuesRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async insertMany(rows) {
+        if (rows.length === 0)
+            return;
+        const sql = `
+      INSERT INTO entity_values
+        (user_id, entity, attribute, value, value_type, observed_at, fact_id)
+      VALUES ($1, $2, $3, $4, $5, $6, $7)
+    `;
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            for (const r of rows) {
+                await client.query(sql, [
+                    r.userId, r.entity, r.attribute, r.value, r.valueType,
+                    r.observedAt, r.factId,
+                ]);
+            }
+            await client.query('COMMIT');
+        }
+        catch (e) {
+            await client.query('ROLLBACK');
+            throw e;
+        }
+        finally {
+            client.release();
+        }
+    }
+    /** Fuzzy lookup: case-insensitive match on (entity, attribute), most recent first. */
+    async findLatest(userId, entity, attribute) {
+        const { rows } = await this.pool.query(`SELECT id, user_id, entity, attribute, value, value_type, observed_at, fact_id, created_at
+       FROM entity_values
+       WHERE user_id = $1
+         AND lower(entity) = lower($2)
+         AND lower(attribute) = lower($3)
+       ORDER BY observed_at DESC
+       LIMIT 1`, [userId, entity, attribute]);
+        return rows[0] ? mapRow(rows[0]) : null;
+    }
+}
+function mapRow(r) {
+    return {
+        id: r.id,
+        userId: r.user_id,
+        entity: r.entity,
+        attribute: r.attribute,
+        value: r.value,
+        valueType: r.value_type,
+        observedAt: r.observed_at,
+        factId: r.fact_id,
+        createdAt: r.created_at,
+    };
+}