@atomicmemory/core 1.0.0

package/dist/db/agent-trust-repository.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Repository for agent trust levels and memory conflict tracking.
+ * Supports trust-aware AUDN conflict resolution and CLARIFY escalation.
+ */
+import pg from 'pg';
+export interface AgentTrustRecord {
+    agent_id: string;
+    user_id: string;
+    trust_level: number;
+    display_name: string | null;
+}
+export interface MemoryConflict {
+    id: string;
+    user_id: string;
+    new_memory_id: string | null;
+    existing_memory_id: string | null;
+    new_agent_id: string | null;
+    existing_agent_id: string | null;
+    new_trust_level: number | null;
+    existing_trust_level: number | null;
+    contradiction_confidence: number;
+    clarification_note: string | null;
+    status: string;
+    resolution_policy: string | null;
+    resolved_at: Date | null;
+    created_at: Date;
+    auto_resolve_after: Date | null;
+}
+export interface ConflictInput {
+    userId: string;
+    newMemoryId: string | null;
+    existingMemoryId: string | null;
+    newAgentId: string | null;
+    existingAgentId: string | null;
+    newTrustLevel: number | null;
+    existingTrustLevel: number | null;
+    contradictionConfidence: number;
+    clarificationNote: string | null;
+}
+export declare class AgentTrustRepository {
+    private pool;
+    constructor(pool: pg.Pool);
+    getTrustLevel(agentId: string, userId: string): Promise<number>;
+    setTrustLevel(agentId: string, userId: string, trustLevel: number, displayName?: string): Promise<void>;
+    recordConflict(input: ConflictInput): Promise<string>;
+    listOpenConflicts(userId: string): Promise<MemoryConflict[]>;
+    resolveConflict(conflictId: string, resolution: 'resolved_new' | 'resolved_existing' | 'resolved_both'): Promise<void>;
+    autoResolveExpiredConflicts(userId: string): Promise<number>;
+}

package/dist/db/agent-trust-repository.js

@@ -0,0 +1,66 @@
+/**
+ * Repository for agent trust levels and memory conflict tracking.
+ * Supports trust-aware AUDN conflict resolution and CLARIFY escalation.
+ */
+import { config } from '../config.js';
+const DEFAULT_TRUST_LEVEL = 0.5;
+export class AgentTrustRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async getTrustLevel(agentId, userId) {
+        const result = await this.pool.query('SELECT trust_level FROM agent_trust WHERE agent_id = $1 AND user_id = $2', [agentId, userId]);
+        return result.rows[0]?.trust_level ?? DEFAULT_TRUST_LEVEL;
+    }
+    async setTrustLevel(agentId, userId, trustLevel, displayName) {
+        await this.pool.query(`INSERT INTO agent_trust (agent_id, user_id, trust_level, display_name)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (agent_id) DO UPDATE SET
+         trust_level = EXCLUDED.trust_level,
+         display_name = COALESCE(EXCLUDED.display_name, agent_trust.display_name),
+         updated_at = NOW()`, [agentId, userId, trustLevel, displayName ?? null]);
+    }
+    async recordConflict(input) {
+        const autoResolveAfter = new Date(Date.now() + config.conflictAutoResolveMs);
+        const result = await this.pool.query(`INSERT INTO memory_conflicts
+       (user_id, new_memory_id, existing_memory_id, new_agent_id, existing_agent_id,
+        new_trust_level, existing_trust_level, contradiction_confidence, clarification_note,
+        auto_resolve_after)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+       RETURNING id`, [
+            input.userId,
+            input.newMemoryId,
+            input.existingMemoryId,
+            input.newAgentId,
+            input.existingAgentId,
+            input.newTrustLevel,
+            input.existingTrustLevel,
+            input.contradictionConfidence,
+            input.clarificationNote,
+            autoResolveAfter,
+        ]);
+        return result.rows[0].id;
+    }
+    async listOpenConflicts(userId) {
+        const result = await this.pool.query(`SELECT * FROM memory_conflicts
+       WHERE user_id = $1 AND status = 'open'
+       ORDER BY created_at DESC`, [userId]);
+        return result.rows;
+    }
+    async resolveConflict(conflictId, resolution) {
+        await this.pool.query(`UPDATE memory_conflicts
+       SET status = $2, resolved_at = NOW(), resolution_policy = 'manual'
+       WHERE id = $1`, [conflictId, resolution]);
+    }
+    async autoResolveExpiredConflicts(userId) {
+        const result = await this.pool.query(`UPDATE memory_conflicts
+       SET status = 'auto_resolved', resolved_at = NOW(), resolution_policy = 'trust_lww'
+       WHERE user_id = $1
+         AND status = 'open'
+         AND auto_resolve_after IS NOT NULL
+         AND auto_resolve_after <= NOW()
+       RETURNING id, existing_trust_level, new_trust_level, new_memory_id, existing_memory_id`, [userId]);
+        return result.rowCount ?? 0;
+    }
+}

package/dist/db/belief-edges-repository.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Repository for the typed belief graph (TBC Phase 3).
+ * Stores and queries edges produced by the EvidenceFor / Counter / Supersede /
+ * Promote / Demote operators of the typed belief calculus.
+ *
+ * Schema lives in src/db/schema.sql under "TBC Phase 3" section.
+ * Activated only when `TBC_ENABLED=true`; see docs/typed-belief-calculus.md.
+ */
+import pg from 'pg';
+export type BeliefEdgeType = 'evidence_for' | 'counter' | 'supersedes' | 'promotes' | 'demotes';
+export interface BeliefEdge {
+    id: string;
+    user_id: string;
+    source_id: string;
+    target_id: string;
+    edge_type: BeliefEdgeType;
+    weight: number;
+    rationale: string;
+    created_at: Date;
+    workspace_id: string | null;
+    agent_id: string | null;
+}
+export interface AppendEdgeInput {
+    userId: string;
+    sourceId: string;
+    targetId: string;
+    edgeType: BeliefEdgeType;
+    weight: number;
+    rationale: string;
+    workspaceId?: string | null;
+    agentId?: string | null;
+}
+export interface ConfidenceAggregate {
+    evidenceForCount: number;
+    counterCount: number;
+    evidenceForWeightSum: number;
+    counterWeightSum: number;
+    /** Net confidence delta = sum(evidence_for weights) - |sum(counter weights)|. Bounded [-1,1] by clamp. */
+    netDelta: number;
+}
+export declare class BeliefEdgesRepository {
+    private readonly pool;
+    constructor(pool: pg.Pool);
+    /** Insert a typed edge. Returns the new row's id. */
+    appendEdge(input: AppendEdgeInput): Promise<string>;
+    /** All edges pointing at a given target (for "what supports/contradicts X" queries). */
+    getEdgesForTarget(userId: string, targetId: string): Promise<BeliefEdge[]>;
+    /** All edges originating from a given source (for "what does this evidence affect" queries). */
+    getEdgesFromSource(userId: string, sourceId: string): Promise<BeliefEdge[]>;
+    /**
+     * Fold all evidence/counter edges pointing at a target into a single
+     * confidence-delta reading. Caller decides how to apply the delta to
+     * memories.confidence (e.g., max-cap at 1.0, floor at 0.0).
+     */
+    aggregateConfidenceDelta(userId: string, targetId: string): Promise<ConfidenceAggregate>;
+    /**
+     * Fetch COUNTER edges where at least one side (source or target) is in the
+     * given memory ID list. Used by the CR specialist to surface bilateral
+     * contradictions among the top-K retrieved set.
+     */
+    findCounterEdgesForMemories(userId: string, memoryIds: string[]): Promise<Array<{
+        sourceId: string;
+        targetId: string;
+        rationale: string;
+    }>>;
+    /** Test/dev helper: remove all edges for a user (e.g., between integration runs). */
+    deleteAllForUser(userId: string): Promise<void>;
+}

package/dist/db/belief-edges-repository.js

@@ -0,0 +1,124 @@
+/**
+ * Repository for the typed belief graph (TBC Phase 3).
+ * Stores and queries edges produced by the EvidenceFor / Counter / Supersede /
+ * Promote / Demote operators of the typed belief calculus.
+ *
+ * Schema lives in src/db/schema.sql under "TBC Phase 3" section.
+ * Activated only when `TBC_ENABLED=true`; see docs/typed-belief-calculus.md.
+ */
+export class BeliefEdgesRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /** Insert a typed edge. Returns the new row's id. */
+    async appendEdge(input) {
+        validateWeightForType(input.edgeType, input.weight);
+        const result = await this.pool.query(`INSERT INTO belief_edges
+        (user_id, source_id, target_id, edge_type, weight, rationale, workspace_id, agent_id)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+       RETURNING id`, [
+            input.userId,
+            input.sourceId,
+            input.targetId,
+            input.edgeType,
+            input.weight,
+            input.rationale,
+            input.workspaceId ?? null,
+            input.agentId ?? null,
+        ]);
+        return result.rows[0]?.id ?? '';
+    }
+    /** All edges pointing at a given target (for "what supports/contradicts X" queries). */
+    async getEdgesForTarget(userId, targetId) {
+        const result = await this.pool.query(`SELECT id, user_id, source_id, target_id, edge_type, weight, rationale,
+              created_at, workspace_id, agent_id
+       FROM belief_edges
+       WHERE user_id = $1 AND target_id = $2
+       ORDER BY created_at DESC`, [userId, targetId]);
+        return result.rows.map(rowToBeliefEdge);
+    }
+    /** All edges originating from a given source (for "what does this evidence affect" queries). */
+    async getEdgesFromSource(userId, sourceId) {
+        const result = await this.pool.query(`SELECT id, user_id, source_id, target_id, edge_type, weight, rationale,
+              created_at, workspace_id, agent_id
+       FROM belief_edges
+       WHERE user_id = $1 AND source_id = $2
+       ORDER BY created_at DESC`, [userId, sourceId]);
+        return result.rows.map(rowToBeliefEdge);
+    }
+    /**
+     * Fold all evidence/counter edges pointing at a target into a single
+     * confidence-delta reading. Caller decides how to apply the delta to
+     * memories.confidence (e.g., max-cap at 1.0, floor at 0.0).
+     */
+    async aggregateConfidenceDelta(userId, targetId) {
+        const result = await this.pool.query(`SELECT edge_type, COUNT(*)::int AS n, SUM(weight)::float AS sum_weight
+       FROM belief_edges
+       WHERE user_id = $1 AND target_id = $2
+         AND edge_type IN ('evidence_for', 'counter')
+       GROUP BY edge_type`, [userId, targetId]);
+        let evidenceForCount = 0;
+        let counterCount = 0;
+        let evidenceForWeightSum = 0;
+        let counterWeightSum = 0;
+        for (const row of result.rows) {
+            const sum = row.sum_weight === null ? 0 : Number(row.sum_weight);
+            if (row.edge_type === 'evidence_for') {
+                evidenceForCount = Number(row.n);
+                evidenceForWeightSum = sum;
+            }
+            else if (row.edge_type === 'counter') {
+                counterCount = Number(row.n);
+                counterWeightSum = sum;
+            }
+        }
+        const rawDelta = evidenceForWeightSum - Math.abs(counterWeightSum);
+        const netDelta = Math.max(-1, Math.min(1, rawDelta));
+        return {
+            evidenceForCount,
+            counterCount,
+            evidenceForWeightSum,
+            counterWeightSum,
+            netDelta,
+        };
+    }
+    /**
+     * Fetch COUNTER edges where at least one side (source or target) is in the
+     * given memory ID list. Used by the CR specialist to surface bilateral
+     * contradictions among the top-K retrieved set.
+     */
+    async findCounterEdgesForMemories(userId, memoryIds) {
+        if (memoryIds.length === 0)
+            return [];
+        const result = await this.pool.query(`SELECT source_id, target_id, rationale
+       FROM belief_edges
+       WHERE user_id = $1
+         AND edge_type = 'counter'
+         AND (source_id = ANY($2) OR target_id = ANY($2))`, [userId, memoryIds]);
+        return result.rows.map(r => ({
+            sourceId: r.source_id,
+            targetId: r.target_id,
+            rationale: r.rationale,
+        }));
+    }
+    /** Test/dev helper: remove all edges for a user (e.g., between integration runs). */
+    async deleteAllForUser(userId) {
+        await this.pool.query(`DELETE FROM belief_edges WHERE user_id = $1`, [userId]);
+    }
+}
+function rowToBeliefEdge(row) {
+    return { ...row };
+}
+/** Edge weight semantics by type. Schema check enforces [-1,1]; this enforces sign. */
+function validateWeightForType(edgeType, weight) {
+    if (!Number.isFinite(weight) || weight < -1 || weight > 1) {
+        throw new Error(`belief_edges weight must be in [-1, 1], got ${weight}`);
+    }
+    if (edgeType === 'evidence_for' && weight < 0) {
+        throw new Error(`evidence_for edge weight must be >= 0 (got ${weight})`);
+    }
+    if (edgeType === 'counter' && weight > 0) {
+        throw new Error(`counter edge weight must be <= 0 (got ${weight})`);
+    }
+}

package/dist/db/claim-repository.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Backward-compatible wrapper around the split claim repository module.
+ */
+export { ClaimRepository } from './repository-claims.js';
+export type { ClaimRow, ClaimVersionRow, } from './repository-types.js';
+export type { ClaimSlotInput, SlotBackfillCandidate, ClaimSlotTarget, } from './repository-claims.js';

package/dist/db/claim-repository.js

@@ -0,0 +1,4 @@
+/**
+ * Backward-compatible wrapper around the split claim repository module.
+ */
+export { ClaimRepository } from './repository-claims.js';

package/dist/db/contradictions-repository.d.ts

@@ -0,0 +1,56 @@
+/**
+ * ContradictionsRepository — bilateral preservation of contradictory memories.
+ *
+ * Phase: BEAM CR fix (2026-05-12). Instead of AUDN's DELETE/SUPERSEDE path
+ * discarding the older side of a contradiction, the bilateral path keeps
+ * both rows in `memories` and records the conflict here for analytics +
+ * retrieval-side enrichment.
+ *
+ * Pure SQL via pg.Pool. Mutations fail closed — errors propagate to the caller.
+ */
+import type pg from 'pg';
+export interface ContradictionRow {
+    id: string;
+    userId: string;
+    conversationId: string | null;
+    leftMemoryId: string;
+    rightMemoryId: string;
+    leftSummary: string;
+    rightSummary: string;
+    resolved: boolean;
+    resolutionNote: string | null;
+    detectedAt: Date;
+}
+interface RecordContradictionInput {
+    userId: string;
+    conversationId?: string | null;
+    leftMemoryId: string;
+    rightMemoryId: string;
+    leftSummary: string;
+    rightSummary: string;
+}
+export declare class ContradictionsRepository {
+    private readonly pool;
+    constructor(pool: pg.Pool);
+    /**
+     * Insert a new contradiction row. Returns the generated row id so callers
+     * (memory-audn bilateral path) can attach the id to both memory rows in
+     * the same transaction-style flow.
+     */
+    record(input: RecordContradictionInput): Promise<string>;
+    /**
+     * Find active (unresolved) contradiction rows for the given user whose
+     * left OR right memory id is in the provided list. Used by retrieval
+     * enrichment to fetch contradiction pairs when a `contradiction_active`
+     * memory appears in top-K.
+     */
+    findActiveByUserAndMemoryIds(userId: string, memoryIds: readonly string[]): Promise<ContradictionRow[]>;
+    /**
+     * Apply the bilateral contradiction flags to BOTH memory rows: each row's
+     * `contradicts_memory_id` is set to its counterpart and
+     * `contradiction_active=true`. Fails closed: errors propagate so the
+     * caller never silently falls back to ADD when the bilateral write fails.
+     */
+    markContradictionFlagsBilateral(userId: string, memoryIdA: string, memoryIdB: string): Promise<void>;
+}
+export {};

package/dist/db/contradictions-repository.js

@@ -0,0 +1,88 @@
+export class ContradictionsRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * Insert a new contradiction row. Returns the generated row id so callers
+     * (memory-audn bilateral path) can attach the id to both memory rows in
+     * the same transaction-style flow.
+     */
+    async record(input) {
+        const { rows } = await this.pool.query(`INSERT INTO memory_contradictions
+         (user_id, conversation_id, left_memory_id, right_memory_id,
+          left_summary, right_summary)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       RETURNING id`, [
+            input.userId,
+            input.conversationId ?? null,
+            input.leftMemoryId,
+            input.rightMemoryId,
+            input.leftSummary,
+            input.rightSummary,
+        ]);
+        if (rows.length === 0) {
+            throw new Error('ContradictionsRepository.record: insert returned no rows');
+        }
+        return rows[0].id;
+    }
+    /**
+     * Find active (unresolved) contradiction rows for the given user whose
+     * left OR right memory id is in the provided list. Used by retrieval
+     * enrichment to fetch contradiction pairs when a `contradiction_active`
+     * memory appears in top-K.
+     */
+    async findActiveByUserAndMemoryIds(userId, memoryIds) {
+        if (memoryIds.length === 0)
+            return [];
+        const { rows } = await this.pool.query(`SELECT id, user_id, conversation_id, left_memory_id, right_memory_id,
+              left_summary, right_summary, resolved, resolution_note, detected_at
+       FROM memory_contradictions
+       WHERE user_id = $1
+         AND resolved = false
+         AND (left_memory_id = ANY($2::uuid[]) OR right_memory_id = ANY($2::uuid[]))`, [userId, memoryIds]);
+        return rows.map(mapRow);
+    }
+    /**
+     * Apply the bilateral contradiction flags to BOTH memory rows: each row's
+     * `contradicts_memory_id` is set to its counterpart and
+     * `contradiction_active=true`. Fails closed: errors propagate so the
+     * caller never silently falls back to ADD when the bilateral write fails.
+     */
+    async markContradictionFlagsBilateral(userId, memoryIdA, memoryIdB) {
+        const existing = await this.pool.query(`SELECT COUNT(*)::int AS count
+       FROM memories
+       WHERE user_id = $1 AND id IN ($2::uuid, $3::uuid)`, [userId, memoryIdA, memoryIdB]);
+        const existingCount = Number(existing.rows[0]?.count ?? 0);
+        if (existingCount !== 2) {
+            throw new Error(`markContradictionFlagsBilateral: expected to update 2 rows, ` +
+                `updated ${existingCount} (userId=${userId}, ids=${memoryIdA},${memoryIdB})`);
+        }
+        const result = await this.pool.query(`UPDATE memories
+       SET contradicts_memory_id = CASE
+             WHEN id = $2 THEN $3::uuid
+             WHEN id = $3 THEN $2::uuid
+             ELSE contradicts_memory_id
+           END,
+           contradiction_active = true
+       WHERE user_id = $1 AND id IN ($2::uuid, $3::uuid)`, [userId, memoryIdA, memoryIdB]);
+        if (result.rowCount !== 2) {
+            throw new Error(`markContradictionFlagsBilateral: expected to update 2 rows, ` +
+                `updated ${result.rowCount ?? 0} (userId=${userId}, ids=${memoryIdA},${memoryIdB})`);
+        }
+    }
+}
+function mapRow(r) {
+    return {
+        id: r.id,
+        userId: r.user_id,
+        conversationId: r.conversation_id,
+        leftMemoryId: r.left_memory_id,
+        rightMemoryId: r.right_memory_id,
+        leftSummary: r.left_summary,
+        rightSummary: r.right_summary,
+        resolved: r.resolved,
+        resolutionNote: r.resolution_note,
+        detectedAt: r.detected_at,
+    };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * Postgres queries for document_chunks (Phase 2).
+ *
+ * Function-style module mirroring `raw-document-repository.ts`. The
+ * `*WithClient` deletion variant exists so `deleteBySource` can include
+ * chunk soft-deletion inside its single transaction, and the batch
+ * insert uses a multi-row INSERT (one round-trip per index call) so
+ * indexing a 50-chunk document is ~50× cheaper than per-row inserts.
+ */
+import pg from 'pg';
+import type { DocumentChunkRow, InsertDocumentChunkInput } from './document-chunk-types.js';
+/**
+ * Either a top-level `pg.Pool` (auto-checks-out a client per query) or a
+ * checked-out `pg.PoolClient` (used to keep a sequence of statements on
+ * the same DB connection — e.g., inside a BEGIN/COMMIT). Phase 2's
+ * indexer threads a `PoolClient` through every chunk-write helper so the
+ * idempotency check + chunk + memory mutations live in one transaction.
+ */
+type Querier = pg.Pool | pg.PoolClient;
+/**
+ * Insert a batch of chunks for one document. Single round-trip; the
+ * caller is expected to have already verified the active-unique slot
+ * is free (the indexer's idempotency check covers this).
+ */
+export declare function insertDocumentChunks(q: Querier, inputs: InsertDocumentChunkInput[]): Promise<DocumentChunkRow[]>;
+/**
+ * Active chunks for a document, ordered by chunk_index. Optionally
+ * filtered to a single chunker_version (the indexer needs that to
+ * decide whether re-index is required vs idempotent skip).
+ */
+export declare function listActiveChunksForDocument(q: Querier, rawDocumentId: string, options?: {
+    chunkerVersion?: string;
+}): Promise<DocumentChunkRow[]>;
+export declare function countActiveChunksForDocument(q: Querier, rawDocumentId: string, chunkerVersion: string): Promise<number>;
+/**
+ * Soft-delete every active chunk for a document. Used by the indexer
+ * when the input text changes (re-chunk path) and by the document
+ * delete route when the document is tombstoned.
+ */
+export declare function softDeleteChunksForDocument(q: Querier, userId: string, rawDocumentId: string): Promise<number>;
+/**
+ * Soft-delete every active chunk whose document belongs to the
+ * (user, source_site) pair. Used inside the existing
+ * `deleteBySource` transaction so source-reset stays one atomic
+ * operation across memories, episodes, documents, and chunks.
+ */
+export declare function deleteChunksBySourceWithClient(client: pg.PoolClient, userId: string, sourceSite: string): Promise<number>;
+export {};

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

@@ -0,0 +1,145 @@
+/**
+ * Postgres queries for document_chunks (Phase 2).
+ *
+ * Function-style module mirroring `raw-document-repository.ts`. The
+ * `*WithClient` deletion variant exists so `deleteBySource` can include
+ * chunk soft-deletion inside its single transaction, and the batch
+ * insert uses a multi-row INSERT (one round-trip per index call) so
+ * indexing a 50-chunk document is ~50× cheaper than per-row inserts.
+ */
+import pgvector from 'pgvector/pg';
+const DOCUMENT_CHUNK_COLUMNS = 'id, user_id, raw_document_id, chunk_index, content, content_hash, char_start, char_end, token_count, embedding, parser_version, chunker_version, metadata, created_at, deleted_at';
+const INSERT_COLUMNS = 'user_id, raw_document_id, chunk_index, content, content_hash, char_start, char_end, token_count, embedding, parser_version, chunker_version, metadata';
+// ---------------------------------------------------------------------------
+// Insert (batch)
+// ---------------------------------------------------------------------------
+/**
+ * Insert a batch of chunks for one document. Single round-trip; the
+ * caller is expected to have already verified the active-unique slot
+ * is free (the indexer's idempotency check covers this).
+ */
+export async function insertDocumentChunks(q, inputs) {
+    if (inputs.length === 0)
+        return [];
+    const { sql, params } = buildBatchInsertSql(inputs);
+    const result = await q.query(sql, params);
+    return result.rows.map(rowToDocumentChunk);
+}
+function buildBatchInsertSql(inputs) {
+    const params = [];
+    const placeholders = [];
+    for (const input of inputs) {
+        placeholders.push(buildOneRowPlaceholders(params.length));
+        pushOneRowParams(params, input);
+    }
+    const sql = `INSERT INTO document_chunks (${INSERT_COLUMNS}) VALUES ${placeholders.join(', ')} RETURNING ${DOCUMENT_CHUNK_COLUMNS}`;
+    return { sql, params };
+}
+function buildOneRowPlaceholders(start) {
+    const slots = [];
+    for (let i = 0; i < 12; i++)
+        slots.push(`$${start + i + 1}`);
+    // metadata is the 12th column — cast as jsonb on the wire.
+    slots[11] = `${slots[11]}::jsonb`;
+    return `(${slots.join(', ')})`;
+}
+function pushOneRowParams(params, input) {
+    params.push(input.userId, input.rawDocumentId, input.chunkIndex, input.content, input.contentHash, input.charStart, input.charEnd, input.tokenCount, pgvector.toSql(input.embedding), input.parserVersion, input.chunkerVersion, JSON.stringify(input.metadata ?? {}));
+}
+// ---------------------------------------------------------------------------
+// List / lookup
+// ---------------------------------------------------------------------------
+/**
+ * Active chunks for a document, ordered by chunk_index. Optionally
+ * filtered to a single chunker_version (the indexer needs that to
+ * decide whether re-index is required vs idempotent skip).
+ */
+export async function listActiveChunksForDocument(q, rawDocumentId, options = {}) {
+    const params = [rawDocumentId];
+    let where = 'raw_document_id = $1 AND deleted_at IS NULL';
+    if (options.chunkerVersion) {
+        params.push(options.chunkerVersion);
+        where += ' AND chunker_version = $2';
+    }
+    const result = await q.query(`SELECT ${DOCUMENT_CHUNK_COLUMNS}
+       FROM document_chunks
+      WHERE ${where}
+      ORDER BY chunk_index ASC`, params);
+    return result.rows.map(rowToDocumentChunk);
+}
+export async function countActiveChunksForDocument(q, rawDocumentId, chunkerVersion) {
+    const result = await q.query(`SELECT COUNT(*)::int AS n
+       FROM document_chunks
+      WHERE raw_document_id = $1 AND chunker_version = $2 AND deleted_at IS NULL`, [rawDocumentId, chunkerVersion]);
+    return Number(result.rows[0]?.n ?? 0);
+}
+// ---------------------------------------------------------------------------
+// Soft-delete + cascading deletion paths
+// ---------------------------------------------------------------------------
+/**
+ * Soft-delete every active chunk for a document. Used by the indexer
+ * when the input text changes (re-chunk path) and by the document
+ * delete route when the document is tombstoned.
+ */
+export async function softDeleteChunksForDocument(q, userId, rawDocumentId) {
+    const result = await q.query(`UPDATE document_chunks
+        SET deleted_at = NOW()
+      WHERE user_id = $1 AND raw_document_id = $2 AND deleted_at IS NULL`, [userId, rawDocumentId]);
+    return result.rowCount ?? 0;
+}
+/**
+ * Soft-delete every active chunk whose document belongs to the
+ * (user, source_site) pair. Used inside the existing
+ * `deleteBySource` transaction so source-reset stays one atomic
+ * operation across memories, episodes, documents, and chunks.
+ */
+export async function deleteChunksBySourceWithClient(client, userId, sourceSite) {
+    const result = await client.query(`UPDATE document_chunks c
+        SET deleted_at = NOW()
+       FROM raw_documents d
+       JOIN raw_sources s ON s.id = d.raw_source_id
+      WHERE c.raw_document_id = d.id
+        AND c.user_id = $1
+        AND s.source_site = $2
+        AND c.deleted_at IS NULL`, [userId, sourceSite]);
+    return result.rowCount ?? 0;
+}
+// ---------------------------------------------------------------------------
+// Row mapper
+// ---------------------------------------------------------------------------
+function rowToDocumentChunk(row) {
+    return {
+        id: row.id,
+        userId: row.user_id,
+        rawDocumentId: row.raw_document_id,
+        chunkIndex: row.chunk_index,
+        content: row.content,
+        contentHash: row.content_hash,
+        charStart: row.char_start,
+        charEnd: row.char_end,
+        tokenCount: row.token_count,
+        embedding: parseEmbedding(row.embedding),
+        parserVersion: row.parser_version,
+        chunkerVersion: row.chunker_version,
+        metadata: row.metadata ?? {},
+        createdAt: row.created_at,
+        deletedAt: row.deleted_at ?? null,
+    };
+}
+/**
+ * pgvector returns the column either as a string like `"[0.1,0.2,...]"`
+ * (default text protocol) or as an already-parsed array (when a custom
+ * type parser is registered). Handle both — the cast is cheap and
+ * avoids depending on a global type-parser registration here.
+ */
+function parseEmbedding(value) {
+    if (Array.isArray(value))
+        return value.map(Number);
+    if (typeof value === 'string') {
+        return value
+            .replace(/^\[|\]$/g, '')
+            .split(',')
+            .map((s) => Number(s));
+    }
+    return [];
+}