@seanhogg/builderforce-memory 2026.9.34 → 2026.10.2

package/dist/storage/ScopedFactRepository.d.ts

@@ -0,0 +1,156 @@
+/**
+ * storage/ScopedFactRepository.ts – Scoped, journaled, revision-tracked fact
+ * repository over a {@link FactStoragePort}.
+ *
+ * This is the unit-of-work owner the offline-memory scope requires:
+ *
+ *   - Scope partitions (M03): every operation takes an explicit
+ *     {@link MemoryScope}; records are physically partitioned by scoped record
+ *     id and logically filtered by partition, so no code path can recall across
+ *     account/tenant/project/repository/chat boundaries. The unbound scope is
+ *     an explicit partition for personal, never-connected memory.
+ *   - Atomic commits (M02): fact mutation + provenance + tombstone + sync
+ *     journal + durable counters commit in ONE storage transaction.
+ *   - Durable identity (M04): every record carries a durable `revision` (the
+ *     store generation that wrote it) and `opId`; deletes write tombstones;
+ *     writes may be compare-and-set against a base revision, so concurrent
+ *     evidence conflicts surface as explicit conflicts instead of unconditional
+ *     last-write-wins.
+ *   - Sync-aware retention (M06): facts with `pendingSync` are never evicted by
+ *     caps and are never dropped by import; TTL expiry is an intentional
+ *     deletion and writes a tombstone when sync is enabled.
+ *
+ * The shared write rules live in `factMutations.ts`, retention in
+ * `factRetention.ts`, import in `factImport.ts`, sync acknowledgement in
+ * `syncJournal.ts`.
+ */
+import { type ImportResult } from './factImport.js';
+import { type ConsistencyNote, type FactProvenance, type FactStoragePort, type JournalEntry, type MemoryScope, type StoredFactRecord, type TombstoneRecord } from './types.js';
+export interface ScopedFactRepositoryOptions {
+    /**
+     * When true, mutations are journaled (unsynced) until {@link markSynced}
+     * acknowledges and prunes them, deletes write tombstones, and cap eviction
+     * skips unsynced facts. When false (default — no sync target configured)
+     * nothing is journaled and retention behaves exactly like the legacy store.
+     */
+    syncEnabled?: boolean;
+    /** Identity of this repository context for opIds and change notes. */
+    contextId?: string;
+    /** Injectable clock (ms). Default: Date.now. */
+    now?: () => number;
+}
+export interface RememberRecordInput {
+    content: string;
+    /** Explicit source time (import). Default: now. */
+    timestamp?: number;
+    /** Explicit source sequence (import). Default: next durable sequence. */
+    seq?: number;
+    ttlMs?: number;
+    type?: StoredFactRecord['type'];
+    tags?: string[];
+    importance?: number;
+    provenance?: FactProvenance;
+    /**
+     * Compare-and-set base: `null` asserts the record does not exist; a number
+     * asserts the current revision; undefined is a blind write (legacy).
+     */
+    expectedRevision?: number | null;
+    /** Explicit op identity (import/replay). Default: generated from the durable op counter. */
+    opId?: string;
+}
+export interface WriteOutcome {
+    record: StoredFactRecord;
+    /** True when an existing tombstone for this key was cleared by the write. */
+    resurrected: boolean;
+}
+export type { ImportResult };
+export declare class ScopedFactRepository {
+    private readonly _storage;
+    private readonly _ctx;
+    constructor(storage: FactStoragePort, opts?: ScopedFactRepositoryOptions);
+    get storage(): FactStoragePort;
+    get contextId(): string;
+    get syncEnabled(): boolean;
+    /** Current durable store generation (0 on a fresh store). */
+    revision(): Promise<number>;
+    /**
+     * Fetches one record by (scope, key), or undefined. Tombstoned = absent.
+     * Uses the `byKey` index when the adapter has it; falls back to the primary
+     * key (itself an index on the scoped id) only when that index is missing.
+     */
+    get(scope: MemoryScope | undefined, key: string): Promise<StoredFactRecord | undefined>;
+    /**
+     * Facts in `scope` carrying `tag`. Uses the multi-entry `byTag` index when
+     * present. A full scan runs only when the index is missing (legacy schema).
+     */
+    getByTag(scope: MemoryScope | undefined, tag: string): Promise<StoredFactRecord[]>;
+    /**
+     * All records in exactly this scope partition — never a wider or narrower
+     * set. Expired records are included; TTL filtering is the caller's policy.
+     */
+    getAll(scope: MemoryScope | undefined): Promise<StoredFactRecord[]>;
+    /** Tombstones, optionally narrowed to one scope partition. */
+    tombstones(scope?: MemoryScope): Promise<TombstoneRecord[]>;
+    /** Journal entries not yet acknowledged by sync — the pending operation set. */
+    pendingOps(): Promise<JournalEntry[]>;
+    /**
+     * Stores or overwrites a fact in `scope`. With `expectedRevision` set this
+     * is a compare-and-set: a mismatch throws a STORAGE_CONFLICT error carrying
+     * the current record, so a concurrent writer's evidence is never silently
+     * overwritten (M04/M05).
+     */
+    remember(scope: MemoryScope | undefined, key: string, input: RememberRecordInput): Promise<WriteOutcome>;
+    /**
+     * Deletes a fact. With sync enabled the delete is a durable tombstone +
+     * journal entry committed in the same transaction, so the deletion
+     * propagates and a stale replica cannot resurrect the fact (M04). Without
+     * sync this is the legacy hard delete. Deleting an absent key is a no-op.
+     */
+    forget(scope: MemoryScope | undefined, key: string, opts?: {
+        expectedRevision?: number;
+    }): Promise<boolean>;
+    /** Removes every fact in the scope. Tombstones each deletion when sync is enabled. */
+    clear(scope: MemoryScope | undefined): Promise<number>;
+    /**
+     * Imports records INTO `scope`, preserving each record's source timestamp,
+     * sequence, tags, importance, TTL and provenance. `importedFrom` is stamped
+     * onto the provenance so the snapshot origin survives. 'merge' keeps the
+     * record with the newer source timestamp; 'overwrite' always writes.
+     * Imported facts are pendingSync when sync is enabled — they are new to
+     * THIS replica even if another store already had them.
+     */
+    importRecords(scope: MemoryScope | undefined, records: StoredFactRecord[], strategy: 'merge' | 'overwrite', importedFrom?: string): Promise<ImportResult>;
+    /** Exports every record in the scope, with scope/revision/provenance intact (M03). */
+    exportRecords(scope: MemoryScope | undefined): Promise<StoredFactRecord[]>;
+    /**
+     * Acknowledges synced operations: their journal entries are pruned and the
+     * facts/tombstones they produced clear `pendingSync`, making cap eviction
+     * eligible again. Only after this may retention touch those records.
+     */
+    markSynced(opIds: string[]): Promise<void>;
+    /**
+     * Local-only cap eviction: removes the lowest-value records past
+     * `maxEntries`, EXCLUDING records with unsynced operations — pending
+     * knowledge is never evicted to satisfy a cache cap. Eviction of synced
+     * records writes no tombstone and no journal entry by design: it is local
+     * cache management, not a deletion to propagate. Returns the evicted keys.
+     */
+    evictForCap(scope: MemoryScope | undefined, maxEntries: number, isExpired: (record: StoredFactRecord) => boolean): Promise<string[]>;
+    /**
+     * Intentional retention: removes expired records. With sync enabled each
+     * expiry is a scoped deletion — tombstone + journal in one transaction — so
+     * the expiry propagates instead of resurrecting from a replica. Returns the
+     * number of records purged.
+     */
+    purgeExpired(scope: MemoryScope | undefined, isExpired: (record: StoredFactRecord) => boolean): Promise<number>;
+    /**
+     * Subscribes to change notes committed by OTHER contexts sharing this
+     * storage (other tabs, extension windows, MCP processes). In-process
+     * serialization alone cannot be the distributed consistency boundary; this
+     * is the invalidation half of the seam, and compare-and-set is the
+     * write-conflict half.
+     */
+    subscribe(listener: (note: ConsistencyNote) => void): () => void;
+    private _publish;
+}
+//# sourceMappingURL=ScopedFactRepository.d.ts.map

package/dist/storage/ScopedFactRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopedFactRepository.d.ts","sourceRoot":"","sources":["../../src/storage/ScopedFactRepository.ts"],"names":[],"mappings":"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"}

package/dist/storage/ScopedFactRepository.js

@@ -0,0 +1,278 @@
+/**
+ * storage/ScopedFactRepository.ts – Scoped, journaled, revision-tracked fact
+ * repository over a {@link FactStoragePort}.
+ *
+ * This is the unit-of-work owner the offline-memory scope requires:
+ *
+ *   - Scope partitions (M03): every operation takes an explicit
+ *     {@link MemoryScope}; records are physically partitioned by scoped record
+ *     id and logically filtered by partition, so no code path can recall across
+ *     account/tenant/project/repository/chat boundaries. The unbound scope is
+ *     an explicit partition for personal, never-connected memory.
+ *   - Atomic commits (M02): fact mutation + provenance + tombstone + sync
+ *     journal + durable counters commit in ONE storage transaction.
+ *   - Durable identity (M04): every record carries a durable `revision` (the
+ *     store generation that wrote it) and `opId`; deletes write tombstones;
+ *     writes may be compare-and-set against a base revision, so concurrent
+ *     evidence conflicts surface as explicit conflicts instead of unconditional
+ *     last-write-wins.
+ *   - Sync-aware retention (M06): facts with `pendingSync` are never evicted by
+ *     caps and are never dropped by import; TTL expiry is an intentional
+ *     deletion and writes a tombstone when sync is enabled.
+ *
+ * The shared write rules live in `factMutations.ts`, retention in
+ * `factRetention.ts`, import in `factImport.ts`, sync acknowledgement in
+ * `syncJournal.ts`.
+ */
+import { factsInScope, indexedFacts } from './factQueries.js';
+import { WRITE_STORES, bumpOp, clearTombstone, deleteWithTombstone, journal, readCounters, writeCounters, } from './factMutations.js';
+import { importInto } from './factImport.js';
+import * as retention from './factRetention.js';
+import * as syncJournal from './syncJournal.js';
+import { FACT_KEY_INDEX, FACT_TAG_INDEX, MemoryStorageError, scopedRecordId, scopePartitionKey, } from './types.js';
+export class ScopedFactRepository {
+    _storage;
+    _ctx;
+    constructor(storage, opts = {}) {
+        this._storage = storage;
+        this._ctx = {
+            syncEnabled: opts.syncEnabled ?? false,
+            contextId: opts.contextId ?? 'repo',
+            now: opts.now ?? (() => Date.now()),
+        };
+    }
+    get storage() {
+        return this._storage;
+    }
+    get contextId() {
+        return this._ctx.contextId;
+    }
+    get syncEnabled() {
+        return this._ctx.syncEnabled;
+    }
+    // ── Reads ─────────────────────────────────────────────────────────────────
+    /** Current durable store generation (0 on a fresh store). */
+    async revision() {
+        return this._storage.transact(['meta'], 'readonly', async (tx) => (await readCounters(tx)).revision);
+    }
+    /**
+     * Fetches one record by (scope, key), or undefined. Tombstoned = absent.
+     * Uses the `byKey` index when the adapter has it; falls back to the primary
+     * key (itself an index on the scoped id) only when that index is missing.
+     */
+    async get(scope, key) {
+        const id = scopedRecordId(scope, key);
+        return this._storage.transact(['facts'], 'readonly', async (tx) => {
+            const indexed = await indexedFacts(tx, FACT_KEY_INDEX, key);
+            if (indexed !== undefined)
+                return indexed.find((r) => r.id === id);
+            return tx.get('facts', id);
+        });
+    }
+    /**
+     * Facts in `scope` carrying `tag`. Uses the multi-entry `byTag` index when
+     * present. A full scan runs only when the index is missing (legacy schema).
+     */
+    async getByTag(scope, tag) {
+        const partition = scopePartitionKey(scope);
+        return this._storage.transact(['facts'], 'readonly', async (tx) => {
+            const indexed = await indexedFacts(tx, FACT_TAG_INDEX, tag);
+            if (indexed !== undefined) {
+                return indexed.filter((r) => scopePartitionKey(r.scope) === partition);
+            }
+            return (await factsInScope(tx, scope)).filter((r) => r.tags?.includes(tag) ?? false);
+        });
+    }
+    /**
+     * All records in exactly this scope partition — never a wider or narrower
+     * set. Expired records are included; TTL filtering is the caller's policy.
+     */
+    async getAll(scope) {
+        return this._storage.transact(['facts'], 'readonly', (tx) => factsInScope(tx, scope));
+    }
+    /** Tombstones, optionally narrowed to one scope partition. */
+    async tombstones(scope) {
+        return this._storage.transact(['tombstones'], 'readonly', async (tx) => {
+            const all = await tx.getAll('tombstones');
+            if (scope === undefined)
+                return all;
+            const partition = scopePartitionKey(scope);
+            return all.filter((t) => scopePartitionKey(t.scope) === partition);
+        });
+    }
+    /** Journal entries not yet acknowledged by sync — the pending operation set. */
+    async pendingOps() {
+        return syncJournal.pendingOps(this._storage);
+    }
+    // ── Writes (unit of work: fact + journal + counters in one transaction) ───
+    /**
+     * Stores or overwrites a fact in `scope`. With `expectedRevision` set this
+     * is a compare-and-set: a mismatch throws a STORAGE_CONFLICT error carrying
+     * the current record, so a concurrent writer's evidence is never silently
+     * overwritten (M04/M05).
+     */
+    async remember(scope, key, input) {
+        const id = scopedRecordId(scope, key);
+        const outcome = await this._storage.transact(WRITE_STORES, 'readwrite', async (tx) => {
+            const counters = await readCounters(tx);
+            const existing = await tx.get('facts', id);
+            if (input.expectedRevision !== undefined) {
+                const current = existing?.revision ?? null;
+                if (current !== input.expectedRevision) {
+                    throw new MemoryStorageError('STORAGE_CONFLICT', `Conflict writing "${key}": expected revision ${String(input.expectedRevision)}, found ${String(current)}. Re-read and reconcile instead of overwriting.`);
+                }
+            }
+            const bumped = bumpOp(counters, this._ctx);
+            const opId = input.opId ?? bumped.opId;
+            const next = { ...bumped.counters, seq: Math.max(counters.seq + 1, input.seq ?? 0) };
+            const record = {
+                id,
+                key,
+                scope: { ...(scope ?? {}) },
+                content: input.content,
+                timestamp: input.timestamp ?? this._ctx.now(),
+                seq: next.seq,
+                revision: next.revision,
+                opId,
+                ttlMs: input.ttlMs,
+                type: input.type,
+                tags: input.tags,
+                importance: input.importance,
+                provenance: input.provenance,
+                pendingSync: this._ctx.syncEnabled,
+            };
+            await tx.put('facts', record);
+            const resurrected = await clearTombstone(tx, id);
+            await journal(tx, this._ctx, {
+                opId,
+                kind: 'remember',
+                id,
+                key,
+                scope: record.scope,
+                revision: next.revision,
+                baseRevision: input.expectedRevision ?? undefined,
+                timestamp: record.timestamp,
+            });
+            await writeCounters(tx, next);
+            return { record, resurrected };
+        });
+        this._publish(scope, outcome.record.revision);
+        return outcome;
+    }
+    /**
+     * Deletes a fact. With sync enabled the delete is a durable tombstone +
+     * journal entry committed in the same transaction, so the deletion
+     * propagates and a stale replica cannot resurrect the fact (M04). Without
+     * sync this is the legacy hard delete. Deleting an absent key is a no-op.
+     */
+    async forget(scope, key, opts = {}) {
+        const id = scopedRecordId(scope, key);
+        const revision = await this._storage.transact(WRITE_STORES, 'readwrite', async (tx) => {
+            const existing = await tx.get('facts', id);
+            if (!existing)
+                return 0;
+            if (opts.expectedRevision !== undefined && existing.revision !== opts.expectedRevision) {
+                throw new MemoryStorageError('STORAGE_CONFLICT', `Conflict deleting "${key}": expected revision ${opts.expectedRevision}, found ${existing.revision}.`);
+            }
+            const next = await deleteWithTombstone(tx, this._ctx, existing, await readCounters(tx), opts.expectedRevision);
+            await writeCounters(tx, next);
+            return next.revision;
+        });
+        if (revision > 0)
+            this._publish(scope, revision);
+        return revision > 0;
+    }
+    /** Removes every fact in the scope. Tombstones each deletion when sync is enabled. */
+    async clear(scope) {
+        const { removed, revision } = await this._storage.transact(WRITE_STORES, 'readwrite', async (tx) => {
+            const mine = await factsInScope(tx, scope);
+            if (mine.length === 0)
+                return { removed: 0, revision: 0 };
+            let counters = await readCounters(tx);
+            for (const record of mine)
+                counters = await deleteWithTombstone(tx, this._ctx, record, counters);
+            await writeCounters(tx, counters);
+            return { removed: mine.length, revision: counters.revision };
+        });
+        if (removed > 0)
+            this._publish(scope, revision);
+        return removed;
+    }
+    // ── Import / export (M03/M06: scope + source time + provenance preserved) ──
+    /**
+     * Imports records INTO `scope`, preserving each record's source timestamp,
+     * sequence, tags, importance, TTL and provenance. `importedFrom` is stamped
+     * onto the provenance so the snapshot origin survives. 'merge' keeps the
+     * record with the newer source timestamp; 'overwrite' always writes.
+     * Imported facts are pendingSync when sync is enabled — they are new to
+     * THIS replica even if another store already had them.
+     */
+    async importRecords(scope, records, strategy, importedFrom) {
+        const { written, skipped, revision } = await importInto(this._storage, this._ctx, scope, records, strategy, importedFrom);
+        if (written > 0)
+            this._publish(scope, revision);
+        return { written, skipped };
+    }
+    /** Exports every record in the scope, with scope/revision/provenance intact (M03). */
+    async exportRecords(scope) {
+        return this.getAll(scope);
+    }
+    // ── Sync acknowledgement (M04/M06) ────────────────────────────────────────
+    /**
+     * Acknowledges synced operations: their journal entries are pruned and the
+     * facts/tombstones they produced clear `pendingSync`, making cap eviction
+     * eligible again. Only after this may retention touch those records.
+     */
+    async markSynced(opIds) {
+        await syncJournal.markSynced(this._storage, opIds);
+    }
+    // ── Retention (M06) ───────────────────────────────────────────────────────
+    /**
+     * Local-only cap eviction: removes the lowest-value records past
+     * `maxEntries`, EXCLUDING records with unsynced operations — pending
+     * knowledge is never evicted to satisfy a cache cap. Eviction of synced
+     * records writes no tombstone and no journal entry by design: it is local
+     * cache management, not a deletion to propagate. Returns the evicted keys.
+     */
+    async evictForCap(scope, maxEntries, isExpired) {
+        return retention.evictForCap(this._storage, scope, maxEntries, isExpired);
+    }
+    /**
+     * Intentional retention: removes expired records. With sync enabled each
+     * expiry is a scoped deletion — tombstone + journal in one transaction — so
+     * the expiry propagates instead of resurrecting from a replica. Returns the
+     * number of records purged.
+     */
+    async purgeExpired(scope, isExpired) {
+        const { purged, revision } = await retention.purgeExpired(this._storage, this._ctx, scope, isExpired);
+        if (purged > 0)
+            this._publish(scope, revision);
+        return purged;
+    }
+    // ── Cross-context consistency seam (M05) ──────────────────────────────────
+    /**
+     * Subscribes to change notes committed by OTHER contexts sharing this
+     * storage (other tabs, extension windows, MCP processes). In-process
+     * serialization alone cannot be the distributed consistency boundary; this
+     * is the invalidation half of the seam, and compare-and-set is the
+     * write-conflict half.
+     */
+    subscribe(listener) {
+        if (!this._storage.subscribe)
+            return () => undefined;
+        return this._storage.subscribe((note) => {
+            if (note.origin === this._ctx.contextId)
+                return;
+            listener(note);
+        });
+    }
+    _publish(scope, revision) {
+        this._storage.publish?.({
+            kind: 'facts-changed',
+            scope: scope ? { ...scope } : undefined,
+            revision,
+            origin: this._ctx.contextId,
+        });
+    }
+}
+//# sourceMappingURL=ScopedFactRepository.js.map

package/dist/storage/ScopedFactRepository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopedFactRepository.js","sourceRoot":"","sources":["../../src/storage/ScopedFactRepository.ts"],"names":[],"mappings":"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"}

package/dist/storage/factImport.d.ts

@@ -0,0 +1,21 @@
+/**
+ * storage/factImport.ts – Import INTO a scope (M03/M06): source timestamp,
+ * sequence, tags, importance, TTL and provenance survive; `importedFrom` is
+ * stamped onto the provenance; imported facts are `pendingSync` when sync is
+ * enabled (new to THIS replica even if another store already had them).
+ */
+import { type MutationContext } from './factMutations.js';
+import { type FactStoragePort, type MemoryScope, type StoredFactRecord } from './types.js';
+export interface ImportResult {
+    written: number;
+    skipped: number;
+}
+/**
+ * Writes `records` into `scope` in one transaction. 'merge' keeps the record
+ * with the newer source timestamp; 'overwrite' always writes. Returns the
+ * counts plus the store revision after the import (0 when nothing was written).
+ */
+export declare function importInto(storage: FactStoragePort, ctx: MutationContext, scope: MemoryScope | undefined, records: StoredFactRecord[], strategy: 'merge' | 'overwrite', importedFrom?: string): Promise<ImportResult & {
+    revision: number;
+}>;
+//# sourceMappingURL=factImport.d.ts.map

package/dist/storage/factImport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factImport.d.ts","sourceRoot":"","sources":["../../src/storage/factImport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA8E,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACtI,OAAO,EAAkB,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE3G,MAAM,WAAW,YAAY;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC5B,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,WAAW,GAAG,SAAS,EAC9B,OAAO,EAAE,gBAAgB,EAAE,EAC3B,QAAQ,EAAE,OAAO,GAAG,WAAW,EAC/B,YAAY,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,YAAY,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA6C9C"}

package/dist/storage/factImport.js

@@ -0,0 +1,61 @@
+/**
+ * storage/factImport.ts – Import INTO a scope (M03/M06): source timestamp,
+ * sequence, tags, importance, TTL and provenance survive; `importedFrom` is
+ * stamped onto the provenance; imported facts are `pendingSync` when sync is
+ * enabled (new to THIS replica even if another store already had them).
+ */
+import { WRITE_STORES, bumpOp, clearTombstone, journal, readCounters, writeCounters } from './factMutations.js';
+import { scopedRecordId } from './types.js';
+/**
+ * Writes `records` into `scope` in one transaction. 'merge' keeps the record
+ * with the newer source timestamp; 'overwrite' always writes. Returns the
+ * counts plus the store revision after the import (0 when nothing was written).
+ */
+export async function importInto(storage, ctx, scope, records, strategy, importedFrom) {
+    return storage.transact(WRITE_STORES, 'readwrite', async (tx) => {
+        let counters = await readCounters(tx);
+        let written = 0;
+        let skipped = 0;
+        for (const incoming of records) {
+            const id = scopedRecordId(scope, incoming.key);
+            const existing = await tx.get('facts', id);
+            if (strategy === 'merge' && existing && existing.timestamp >= incoming.timestamp) {
+                skipped++;
+                continue;
+            }
+            const bumped = bumpOp(counters, ctx);
+            counters = { ...bumped.counters, seq: Math.max(counters.seq + 1, incoming.seq ?? 0) };
+            const record = {
+                ...incoming,
+                id,
+                key: incoming.key,
+                scope: { ...(scope ?? {}) },
+                seq: incoming.seq ?? counters.seq,
+                revision: counters.revision,
+                opId: bumped.opId,
+                provenance: {
+                    ...incoming.provenance,
+                    ...(importedFrom ? { importedFrom } : {}),
+                    originalTimestamp: incoming.provenance?.originalTimestamp ?? incoming.timestamp,
+                },
+                pendingSync: ctx.syncEnabled,
+            };
+            await tx.put('facts', record);
+            await clearTombstone(tx, id);
+            await journal(tx, ctx, {
+                opId: bumped.opId,
+                kind: 'remember',
+                id,
+                key: incoming.key,
+                scope: record.scope,
+                revision: counters.revision,
+                timestamp: record.timestamp,
+            });
+            written++;
+        }
+        if (written > 0)
+            await writeCounters(tx, counters);
+        return { written, skipped, revision: written > 0 ? counters.revision : 0 };
+    });
+}
+//# sourceMappingURL=factImport.js.map

package/dist/storage/factImport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factImport.js","sourceRoot":"","sources":["../../src/storage/factImport.ts"],"names":[],"mappings":"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"}

package/dist/storage/factMutations.d.ts

@@ -0,0 +1,46 @@
+/**
+ * storage/factMutations.ts – The write primitives every repository mutation
+ * shares, so the counter bump / tombstone / journal rules live in ONE place:
+ *
+ *   - {@link bumpOp}: next durable revision + operation id.
+ *   - {@link journal}: append a sync-journal entry — ONLY when sync is enabled.
+ *     Without a sync target there is nothing to acknowledge, so writing rows
+ *     already marked synced just grew the journal forever.
+ *   - {@link deleteWithTombstone}: delete a fact, tombstone it when sync is on,
+ *     journal the delete — one call for forget, clear and TTL purge.
+ *   - {@link clearTombstone}: a write resurrects a key (remember, import).
+ */
+import type { JournalEntry, MemoryScope, MetaCounters, StorageStoreName, StorageTransaction } from './types.js';
+export declare const COUNTERS_ID = "counters";
+/** The stores a mutating unit of work spans. */
+export declare const WRITE_STORES: StorageStoreName[];
+/** Who is writing, and under which retention rules. */
+export interface MutationContext {
+    readonly syncEnabled: boolean;
+    readonly contextId: string;
+    readonly now: () => number;
+}
+type CounterReader = Pick<StorageTransaction, 'get'>;
+export declare function readCounters(tx: CounterReader): Promise<MetaCounters>;
+export declare function writeCounters(tx: StorageTransaction, counters: MetaCounters): Promise<void>;
+/** The next revision + operation identity after `counters`. */
+export declare function bumpOp(counters: MetaCounters, ctx: MutationContext): {
+    counters: MetaCounters;
+    opId: string;
+};
+/** Appends an unsynced journal entry when sync is enabled; a no-op otherwise. */
+export declare function journal(tx: StorageTransaction, ctx: MutationContext, entry: Omit<JournalEntry, 'synced'>): Promise<void>;
+/** Clears any tombstone for `id`; true when one existed (the write resurrected the key). */
+export declare function clearTombstone(tx: StorageTransaction, id: string): Promise<boolean>;
+/**
+ * Deletes one fact as a durable, propagating deletion: bump the counters,
+ * delete, tombstone (sync on), journal (sync on). Returns the bumped counters;
+ * the caller persists them once per transaction with {@link writeCounters}.
+ */
+export declare function deleteWithTombstone(tx: StorageTransaction, ctx: MutationContext, record: {
+    id: string;
+    key: string;
+    scope: MemoryScope;
+}, counters: MetaCounters, baseRevision?: number): Promise<MetaCounters>;
+export {};
+//# sourceMappingURL=factMutations.d.ts.map

package/dist/storage/factMutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factMutations.d.ts","sourceRoot":"","sources":["../../src/storage/factMutations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACR,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAErB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,WAAW,aAAa,CAAC;AAEtC,gDAAgD;AAChD,eAAO,MAAM,YAAY,EAAE,gBAAgB,EAA+C,CAAC;AAE3F,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC9B;AAED,KAAK,aAAa,GAAG,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;AAErD,wBAAsB,YAAY,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAG3E;AAED,wBAAsB,aAAa,CAAC,EAAE,EAAE,kBAAkB,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjG;AAED,+DAA+D;AAC/D,wBAAgB,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,eAAe,GAAG;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAG7G;AAED,iFAAiF;AACjF,wBAAsB,OAAO,CACzB,EAAE,EAAE,kBAAkB,EACtB,GAAG,EAAE,eAAe,EACpB,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,4FAA4F;AAC5F,wBAAsB,cAAc,CAAC,EAAE,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAIzF;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACrC,EAAE,EAAE,kBAAkB,EACtB,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,EACvD,QAAQ,EAAE,YAAY,EACtB,YAAY,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,YAAY,CAAC,CA0BvB"}