@atomicmemory/core 1.0.0

package/dist/db/repository-claims.js

@@ -0,0 +1,376 @@
+/**
+ * Structured claim/version history repository.
+ */
+import pgvector from 'pgvector/pg';
+import { clampImportance, normalizeSearchRow, normalizeVersionRow, } from './repository-types.js';
+export class ClaimRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async createClaim(userId, claimType, validAt, slot) {
+        return this.createClaimWithClient(this.pool, userId, claimType, validAt, slot);
+    }
+    async createClaimWithClient(client, userId, claimType, validAt, slot) {
+        const result = await client.query(`INSERT INTO memory_claims (
+         user_id, claim_type, slot_key, subject_entity_id, relation_type, object_entity_id, valid_at
+       )
+       VALUES ($1, $2, $3, $4, $5, $6, $7)
+       RETURNING id`, [
+            userId,
+            claimType,
+            slot?.slotKey ?? null,
+            slot?.subjectEntityId ?? null,
+            slot?.relationType ?? null,
+            slot?.objectEntityId ?? null,
+            validAt ?? new Date(),
+        ]);
+        return result.rows[0].id;
+    }
+    async getClaim(id, userId) {
+        const result = await this.pool.query(`SELECT * FROM memory_claims WHERE id = $1 AND user_id = $2`, [id, userId]);
+        return result.rows[0] ?? null;
+    }
+    async getActiveClaimTargetBySlot(userId, slotKey) {
+        const result = await this.pool.query(`SELECT
+         c.id AS claim_id,
+         cv.id AS version_id,
+         cv.memory_id
+       FROM memory_claims c
+       JOIN memory_claim_versions cv ON cv.id = c.current_version_id
+       WHERE c.user_id = $1
+         AND c.slot_key = $2
+         AND c.status = 'active'
+         AND c.invalid_at IS NULL
+         AND cv.memory_id IS NOT NULL
+       ORDER BY c.updated_at DESC
+       LIMIT 1`, [userId, slotKey]);
+        if (result.rows.length === 0)
+            return null;
+        return {
+            claimId: result.rows[0].claim_id,
+            versionId: result.rows[0].version_id,
+            memoryId: result.rows[0].memory_id,
+        };
+    }
+    async listClaimsMissingSlots(userId) {
+        const result = await this.pool.query(`SELECT
+         c.id AS claim_id,
+         c.user_id,
+         cv.memory_id
+       FROM memory_claims c
+       JOIN memory_claim_versions cv ON cv.id = c.current_version_id
+       WHERE c.user_id = $1
+         AND c.slot_key IS NULL
+         AND c.status = 'active'
+         AND c.invalid_at IS NULL
+         AND cv.memory_id IS NOT NULL
+       ORDER BY c.created_at ASC`, [userId]);
+        return result.rows.map((row) => ({
+            claimId: row.claim_id,
+            userId: row.user_id,
+            memoryId: row.memory_id,
+        }));
+    }
+    async updateClaimSlot(userId, claimId, slot) {
+        await this.pool.query(`UPDATE memory_claims
+       SET slot_key = $1,
+           subject_entity_id = $2,
+           relation_type = $3,
+           object_entity_id = $4,
+           updated_at = NOW()
+       WHERE id = $5
+         AND user_id = $6
+         AND slot_key IS NULL`, [
+            slot.slotKey,
+            slot.subjectEntityId,
+            slot.relationType,
+            slot.objectEntityId,
+            claimId,
+            userId,
+        ]);
+    }
+    async setClaimCurrentVersion(claimId, versionId, status = 'active', validAt) {
+        await this.setClaimCurrentVersionWithClient(this.pool, claimId, versionId, status, validAt);
+    }
+    async setClaimCurrentVersionWithClient(client, claimId, versionId, status = 'active', validAt) {
+        await client.query(`UPDATE memory_claims
+       SET current_version_id = $1,
+           status = $2,
+           valid_at = CASE
+             WHEN $4::timestamptz IS NULL THEN valid_at
+             ELSE LEAST(valid_at, $4::timestamptz)
+           END,
+           invalid_at = NULL,
+           invalidated_at = NULL,
+           invalidated_by_version_id = NULL,
+           updated_at = NOW()
+       WHERE id = $3`, [versionId, status, claimId, validAt ?? null]);
+    }
+    async invalidateClaim(userId, claimId, invalidAt = new Date(), invalidatedByVersionId = null, status = 'deleted') {
+        await this.invalidateClaimWithClient(this.pool, userId, claimId, invalidAt, invalidatedByVersionId, status);
+    }
+    async invalidateClaimWithClient(client, userId, claimId, invalidAt = new Date(), invalidatedByVersionId = null, status = 'deleted') {
+        await client.query(`UPDATE memory_claims
+       SET current_version_id = NULL,
+           status = $1,
+           invalid_at = $2,
+           invalidated_at = NOW(),
+           invalidated_by_version_id = $3,
+           updated_at = NOW()
+       WHERE id = $4 AND user_id = $5`, [status, invalidAt, invalidatedByVersionId, claimId, userId]);
+    }
+    async createClaimVersion(input) {
+        return this.createClaimVersionWithClient(this.pool, input);
+    }
+    async createClaimVersionWithClient(client, input) {
+        const p = input.provenance;
+        const validFrom = input.validFrom ?? new Date();
+        const result = await client.query(`INSERT INTO memory_claim_versions
+       (claim_id, user_id, memory_id, content, embedding, importance, source_site, source_url, episode_id, valid_from,
+        mutation_type, mutation_reason, previous_version_id, actor_model, contradiction_confidence)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15) RETURNING id`, [
+            input.claimId,
+            input.userId,
+            input.memoryId ?? null,
+            input.content,
+            pgvector.toSql(input.embedding),
+            clampImportance(input.importance),
+            input.sourceSite,
+            input.sourceUrl ?? '',
+            input.episodeId ?? null,
+            validFrom,
+            p?.mutationType ?? null,
+            p?.mutationReason ?? null,
+            p?.previousVersionId ?? null,
+            p?.actorModel ?? null,
+            p?.contradictionConfidence ?? null,
+        ]);
+        await client.query(`UPDATE memory_claims
+       SET valid_at = LEAST(valid_at, $1::timestamptz), updated_at = NOW()
+       WHERE id = $2 AND user_id = $3`, [validFrom, input.claimId, input.userId]);
+        return result.rows[0].id;
+    }
+    async getClaimVersionByMemoryId(userId, memoryId) {
+        return this.getClaimVersionByMemoryIdWithClient(this.pool, userId, memoryId);
+    }
+    async getClaimVersionByMemoryIdWithClient(client, userId, memoryId) {
+        const result = await client.query(`SELECT * FROM memory_claim_versions
+       WHERE user_id = $1 AND memory_id = $2`, [userId, memoryId]);
+        return result.rows[0] ? normalizeVersionRow(result.rows[0]) : null;
+    }
+    async getClaimVersion(versionId, userId) {
+        const result = await this.pool.query(`SELECT * FROM memory_claim_versions WHERE id = $1 AND user_id = $2`, [versionId, userId]);
+        return result.rows[0] ? normalizeVersionRow(result.rows[0]) : null;
+    }
+    async getClaimVersionAtTime(claimId, userId, asOf) {
+        const result = await this.pool.query(`SELECT cv.*
+       FROM memory_claims c
+       JOIN memory_claim_versions cv ON cv.claim_id = c.id
+       WHERE c.id = $1
+         AND c.user_id = $2
+         AND c.valid_at <= $3::timestamptz
+         AND (c.invalid_at IS NULL OR c.invalid_at > $3::timestamptz)
+         AND cv.valid_from <= $3::timestamptz
+         AND (cv.valid_to IS NULL OR cv.valid_to > $3::timestamptz)
+       ORDER BY cv.valid_from DESC, cv.created_at DESC
+       LIMIT 1`, [claimId, userId, asOf]);
+        return result.rows[0] ? normalizeVersionRow(result.rows[0]) : null;
+    }
+    async listClaimVersions(claimId) {
+        const result = await this.pool.query(`SELECT * FROM memory_claim_versions
+       WHERE claim_id = $1 ORDER BY valid_from ASC`, [claimId]);
+        return result.rows.map(normalizeVersionRow);
+    }
+    /**
+     * Create a new version for an UPDATE mutation, preserving the old version
+     * in the version history. The old version gets valid_to set and the new
+     * version becomes current.
+     */
+    async createUpdateVersion(input) {
+        const validFrom = input.validFrom ?? new Date();
+        // Close old version and release its memory_id (UNIQUE constraint)
+        await this.supersedeClaimVersion(input.userId, input.oldVersionId, null, validFrom);
+        await this.pool.query(`UPDATE memory_claim_versions SET memory_id = NULL WHERE id = $1`, [input.oldVersionId]);
+        // Create new version with provenance
+        const newVersionId = await this.createClaimVersion({
+            claimId: input.claimId,
+            userId: input.userId,
+            memoryId: input.memoryId,
+            content: input.content,
+            embedding: input.embedding,
+            importance: input.importance,
+            sourceSite: input.sourceSite,
+            sourceUrl: input.sourceUrl,
+            episodeId: input.episodeId,
+            validFrom,
+            provenance: {
+                mutationType: 'update',
+                mutationReason: input.mutationReason,
+                previousVersionId: input.oldVersionId,
+                actorModel: input.actorModel,
+            },
+        });
+        // Link old → new
+        await this.pool.query(`UPDATE memory_claim_versions SET superseded_by_version_id = $1 WHERE id = $2`, [newVersionId, input.oldVersionId]);
+        // Update claim pointer
+        await this.setClaimCurrentVersion(input.claimId, newVersionId, 'active', validFrom);
+        return newVersionId;
+    }
+    async supersedeClaimVersion(userId, versionId, supersededByVersionId, validTo = new Date()) {
+        await this.supersedeClaimVersionWithClient(this.pool, userId, versionId, supersededByVersionId, validTo);
+    }
+    async supersedeClaimVersionWithClient(client, userId, versionId, supersededByVersionId, validTo = new Date()) {
+        await client.query(`UPDATE memory_claim_versions
+       SET valid_to = $1, superseded_by_version_id = $2
+       WHERE id = $3 AND user_id = $4`, [validTo, supersededByVersionId, versionId, userId]);
+    }
+    async addEvidence(input) {
+        await this.addEvidenceWithClient(this.pool, input);
+    }
+    async addEvidenceWithClient(client, input) {
+        await client.query(`INSERT INTO memory_evidence (claim_version_id, episode_id, memory_id, quote_text, speaker)
+       VALUES ($1, $2, $3, $4, $5)`, [input.claimVersionId, input.episodeId ?? null, input.memoryId ?? null, input.quoteText ?? '', input.speaker ?? null]);
+    }
+    async searchClaimVersions(userId, queryEmbedding, limit, asOf, sourceSite) {
+        const result = await this.pool.query(`SELECT
+         COALESCE(cv.memory_id::text, cv.id::text) AS id,
+         cv.user_id,
+         cv.content,
+         cv.embedding,
+         'semantic' AS memory_type,
+         cv.importance,
+         cv.source_site,
+         cv.source_url,
+         cv.episode_id,
+         cv.valid_from AS created_at,
+         cv.valid_from AS last_accessed_at,
+         0::int AS access_count,
+         'active'::text AS status,
+         '{}'::jsonb AS metadata,
+         NULL::timestamptz AS deleted_at,
+         1 - (cv.embedding <=> $1) AS similarity,
+         (
+           2.0 * (1 - (cv.embedding <=> $1))
+           + 1.0 * cv.importance
+           + 1.0 * EXP(-EXTRACT(EPOCH FROM ($4::timestamptz - cv.valid_from)) / 2592000.0)
+         ) AS score
+       FROM memory_claim_versions cv
+       JOIN memory_claims c ON c.id = cv.claim_id
+       WHERE cv.user_id = $2
+         AND c.user_id = $2
+         AND c.valid_at <= $4::timestamptz
+         AND (c.invalid_at IS NULL OR c.invalid_at > $4::timestamptz)
+         AND cv.valid_from <= $4::timestamptz
+         AND (cv.valid_to IS NULL OR cv.valid_to > $4::timestamptz)
+         ${sourceSite ? 'AND cv.source_site = $5' : ''}
+       ORDER BY score DESC
+       LIMIT $3`, buildHistoricalParams(queryEmbedding, userId, limit, asOf, sourceSite));
+        return result.rows.map(normalizeSearchRow);
+    }
+    async countClaims(userId) {
+        const result = await this.pool.query(`SELECT COUNT(*)::int AS count FROM memory_claims WHERE user_id = $1`, [userId]);
+        return result.rows[0].count;
+    }
+    async countOpenClaimVersions(claimId) {
+        const result = await this.pool.query(`SELECT COUNT(*)::int AS count
+       FROM memory_claim_versions WHERE claim_id = $1 AND valid_to IS NULL`, [claimId]);
+        return result.rows[0].count;
+    }
+    /**
+     * Get the full mutation history for a claim, ordered chronologically.
+     * Returns all versions including superseded ones, with provenance metadata.
+     */
+    async getMutationHistory(claimId) {
+        const result = await this.pool.query(`SELECT * FROM memory_claim_versions
+       WHERE claim_id = $1
+       ORDER BY valid_from ASC`, [claimId]);
+        return result.rows.map(normalizeVersionRow);
+    }
+    /**
+     * Find the claim associated with a memory ID (even if the memory is deleted).
+     */
+    async findClaimByMemoryId(userId, memoryId) {
+        const versionResult = await this.pool.query(`SELECT claim_id FROM memory_claim_versions
+       WHERE user_id = $1 AND (memory_id = $2 OR id IN (
+         SELECT previous_version_id FROM memory_claim_versions WHERE memory_id = $2
+       ))
+       LIMIT 1`, [userId, memoryId]);
+        if (versionResult.rows.length === 0)
+            return null;
+        const claimId = versionResult.rows[0].claim_id;
+        const versions = await this.getMutationHistory(claimId);
+        return { claimId, versions };
+    }
+    /**
+     * Get aggregate mutation stats for a user: counts by mutation type,
+     * total versions, active vs superseded counts. Used for mutation audit trail.
+     */
+    async getUserMutationSummary(userId) {
+        const [typeCounts, totals] = await Promise.all([
+            this.pool.query(`SELECT mutation_type, COUNT(*)::int AS count
+         FROM memory_claim_versions WHERE user_id = $1 AND mutation_type IS NOT NULL
+         GROUP BY mutation_type ORDER BY count DESC`, [userId]),
+            this.pool.query(`SELECT
+           COUNT(*)::int AS total_versions,
+           COUNT(*) FILTER (WHERE valid_to IS NULL)::int AS active_versions,
+           COUNT(*) FILTER (WHERE valid_to IS NOT NULL)::int AS superseded_versions,
+           COUNT(DISTINCT claim_id)::int AS total_claims
+         FROM memory_claim_versions WHERE user_id = $1`, [userId]),
+        ]);
+        const byType = {};
+        for (const row of typeCounts.rows) {
+            byType[row.mutation_type] = row.count;
+        }
+        const t = totals.rows[0];
+        return {
+            totalVersions: t.total_versions,
+            activeVersions: t.active_versions,
+            supersededVersions: t.superseded_versions,
+            totalClaims: t.total_claims,
+            byMutationType: byType,
+        };
+    }
+    /**
+     * Trace the supersession chain forward from a given version ID.
+     * Returns the sequence of versions that replaced each other,
+     * enabling "why did this memory change?" debugging.
+     */
+    async getReversalChain(userId, startVersionId, maxDepth = 20) {
+        const chain = [];
+        let currentId = startVersionId;
+        while (currentId && chain.length < maxDepth) {
+            const result = await this.pool.query(`SELECT * FROM memory_claim_versions WHERE id = $1 AND user_id = $2`, [currentId, userId]);
+            if (result.rows.length === 0)
+                break;
+            const version = normalizeVersionRow(result.rows[0]);
+            chain.push(version);
+            currentId = version.superseded_by_version_id;
+        }
+        return chain;
+    }
+    /**
+     * Get recent mutations across all claims for a user, ordered newest first.
+     * Useful for "what changed recently?" debugging.
+     */
+    async getRecentMutations(userId, limit = 20) {
+        const result = await this.pool.query(`SELECT * FROM memory_claim_versions
+       WHERE user_id = $1 AND mutation_type IS NOT NULL
+       ORDER BY created_at DESC
+       LIMIT $2`, [userId, Math.max(1, Math.min(100, limit))]);
+        return result.rows.map(normalizeVersionRow);
+    }
+    async deleteAll(userId) {
+        const params = userId ? [userId] : [];
+        const where = userId ? ' WHERE user_id = $1' : '';
+        await this.pool.query(`DELETE FROM memory_evidence WHERE claim_version_id IN (SELECT id FROM memory_claim_versions${where})`, params);
+        await this.pool.query(`DELETE FROM memory_claim_versions${where}`, params);
+        await this.pool.query(`DELETE FROM memory_claims${where}`, params);
+    }
+}
+function buildHistoricalParams(queryEmbedding, userId, limit, asOf, sourceSite) {
+    const params = [pgvector.toSql(queryEmbedding), userId, Math.max(1, Math.min(100, limit)), asOf];
+    if (sourceSite)
+        params.push(sourceSite);
+    return params;
+}

package/dist/db/repository-deferred-audn.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Repository operations for deferred AUDN reconciliation.
+ *
+ * When deferred AUDN is enabled, facts with conflict candidates in the
+ * 0.7–0.95 similarity range are stored as ADD immediately and marked
+ * with deferred_audn=true + serialized candidates. A background
+ * reconciliation pass resolves these via the full LLM AUDN pipeline.
+ */
+import type pg from 'pg';
+/** Serialized candidate stored alongside a deferred memory. */
+export interface DeferredCandidate {
+    id: string;
+    content: string;
+    similarity: number;
+}
+/** A memory that needs deferred AUDN reconciliation. */
+export interface DeferredMemory {
+    id: string;
+    userId: string;
+    content: string;
+    candidates: DeferredCandidate[];
+    createdAt: Date;
+}
+/** Store a memory as deferred: set flag and serialize candidates. */
+export declare function markMemoryDeferred(pool: pg.Pool, memoryId: string, candidates: DeferredCandidate[]): Promise<void>;
+/** Find up to `limit` memories pending deferred AUDN for a user. */
+export declare function findDeferredMemories(pool: pg.Pool, userId: string, limit: number): Promise<DeferredMemory[]>;
+/** Find deferred memories across all users (for batch job). */
+export declare function findAllDeferredMemories(pool: pg.Pool, limit: number): Promise<DeferredMemory[]>;
+/** Clear the deferred flag after reconciliation. */
+export declare function clearDeferredFlag(pool: pg.Pool, memoryId: string): Promise<void>;
+/** Count memories pending deferred reconciliation for a user. */
+export declare function countDeferredMemories(pool: pg.Pool, userId: string): Promise<number>;

package/dist/db/repository-deferred-audn.js

@@ -0,0 +1,69 @@
+/**
+ * Repository operations for deferred AUDN reconciliation.
+ *
+ * When deferred AUDN is enabled, facts with conflict candidates in the
+ * 0.7–0.95 similarity range are stored as ADD immediately and marked
+ * with deferred_audn=true + serialized candidates. A background
+ * reconciliation pass resolves these via the full LLM AUDN pipeline.
+ */
+/** Store a memory as deferred: set flag and serialize candidates. */
+export async function markMemoryDeferred(pool, memoryId, candidates) {
+    await pool.query(`UPDATE memories SET deferred_audn = true, audn_candidates = $2
+     WHERE id = $1`, [memoryId, JSON.stringify(candidates)]);
+}
+/** Find up to `limit` memories pending deferred AUDN for a user. */
+export async function findDeferredMemories(pool, userId, limit) {
+    const result = await pool.query(`SELECT id, user_id, content, audn_candidates, created_at
+     FROM memories
+     WHERE user_id = $1 AND deferred_audn = true AND deleted_at IS NULL
+     ORDER BY created_at ASC
+     LIMIT $2`, [userId, limit]);
+    return result.rows.map((row) => ({
+        id: row.id,
+        userId: row.user_id,
+        content: row.content,
+        candidates: parseCandidates(row.audn_candidates),
+        createdAt: row.created_at,
+    }));
+}
+/** Find deferred memories across all users (for batch job). */
+export async function findAllDeferredMemories(pool, limit) {
+    const result = await pool.query(`SELECT id, user_id, content, audn_candidates, created_at
+     FROM memories
+     WHERE deferred_audn = true AND deleted_at IS NULL
+     ORDER BY created_at ASC
+     LIMIT $1`, [limit]);
+    return result.rows.map((row) => ({
+        id: row.id,
+        userId: row.user_id,
+        content: row.content,
+        candidates: parseCandidates(row.audn_candidates),
+        createdAt: row.created_at,
+    }));
+}
+/** Clear the deferred flag after reconciliation. */
+export async function clearDeferredFlag(pool, memoryId) {
+    await pool.query(`UPDATE memories SET deferred_audn = false, audn_candidates = NULL
+     WHERE id = $1`, [memoryId]);
+}
+/** Count memories pending deferred reconciliation for a user. */
+export async function countDeferredMemories(pool, userId) {
+    const result = await pool.query(`SELECT COUNT(*) as count FROM memories
+     WHERE user_id = $1 AND deferred_audn = true AND deleted_at IS NULL`, [userId]);
+    return parseInt(result.rows[0].count, 10);
+}
+function parseCandidates(raw) {
+    if (!raw)
+        return [];
+    if (typeof raw === 'string') {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (Array.isArray(raw))
+        return raw;
+    return [];
+}

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

@@ -0,0 +1,53 @@
+/**
+ * @file Document-scoped delete cascades.
+ *
+ * Owns `softDeleteDocumentCascade` (single-document) and
+ * `deleteBySource` (source-reset), plus the Step-7 helpers that
+ * soft-delete linked `storage_artifacts` rows in the same
+ * transaction. Extracted from `repository-write.ts` to keep that
+ * module under the workspace 400-non-comment-LOC cap.
+ */
+import type pg from 'pg';
+import { type ManagedBlobRefRow } from './raw-document-blob-repository.js';
+export interface SoftDeleteDocumentCascadeResult {
+    removed: boolean;
+    memoriesDeleted: number;
+    chunksDeleted: number;
+    /**
+     * Managed-blob refs (with `rawDocumentId`) the caller should hand
+     * to `cleanupManagedBlobs()` after the transaction commits. Empty
+     * when the document was pointer-only or already deleted.
+     */
+    blobs: ManagedBlobRefRow[];
+}
+/**
+ * Soft-delete a document together with the chunks + provenance-linked
+ * memories materialized from it (Phase 2). Runs in one transaction
+ * with a per-document advisory lock so a concurrent index call
+ * serializes cleanly. Idempotent: returns `{ removed: false }` when
+ * the document was already missing/deleted/owned by a different user.
+ *
+ * Step 7 — when the document has no managed blob to clean up
+ * (pointer-only, or already-terminal managed), the linked
+ * `storage_artifacts` row is soft-deleted in the same transaction.
+ * The cleanup path handles the managed case via the paired
+ * `markCleanupSuccessAndSyncArtifact` helper.
+ */
+export declare function softDeleteDocumentCascade(pool: pg.Pool, userId: string, documentId: string): Promise<SoftDeleteDocumentCascadeResult>;
+export interface DeleteBySourceResult {
+    deletedMemories: number;
+    deletedEpisodes: number;
+    deletedDocuments: number;
+    /** Managed-blob refs the caller hands to `cleanupManagedBlobs()`. */
+    blobs: ManagedBlobRefRow[];
+}
+/**
+ * Delete all data for a given user + source_site combination.
+ * Hard-deletes across memory-side tables and soft-deletes
+ * (tombstones) matching `raw_documents` in safe referential order
+ * within a single transaction. Step 7 — soft-deletes the linked
+ * `storage_artifacts` rows for pointer-only / terminal-managed
+ * docs in the same transaction, so a source reset cannot leave
+ * orphan active artifact links.
+ */
+export declare function deleteBySource(pool: pg.Pool, userId: string, sourceSite: string): Promise<DeleteBySourceResult>;