@astragenie/astramemory-local 0.7.2

package/dist/sync/conflict-resolve.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Scoped projection-recompute (ADR-011 multi-device conflict policy,
+ * FEAT-407 pull merge slice).
+ *
+ * Only atom_ids that received a NEW remote event during a pull round need
+ * their projection recomputed — atoms with no incoming remote event keep
+ * the existing single-device fast path in memory-events.ts, unchanged
+ * (ADR-011 "Implications for FEAT-407" point 3). This module is that
+ * recompute function: a deterministic, order-independent reduce over the
+ * FULL local event set for one atom_id, implementing conflict classes
+ * A (concurrent-edit), B (edit-vs-supersede), C (edit-vs-erase).
+ *
+ * Deterministic tie-break key everywhere below: (created_at, event_id) —
+ * created_at first, event_id (immutable, globally-unique) breaks ties. No
+ * device is structurally favored (ADR-011).
+ */
+import type { DB } from '../storage/db.js';
+/**
+ * Recompute the materialized `memories` projection for one atom_id from its
+ * full local event set (local ∪ pulled-remote, already deduped by
+ * event_id). Order-independent: computed as a set-wise reduce, not a
+ * fold-in-arrival-order apply, so calling this any number of times, in any
+ * order relative to sibling atoms, converges to the same result (ADR-011
+ * convergence property).
+ */
+export declare function recomputeProjection(db: DB, atomId: string): void;

package/dist/sync/conflict-resolve.js

@@ -0,0 +1,139 @@
+/**
+ * Scoped projection-recompute (ADR-011 multi-device conflict policy,
+ * FEAT-407 pull merge slice).
+ *
+ * Only atom_ids that received a NEW remote event during a pull round need
+ * their projection recomputed — atoms with no incoming remote event keep
+ * the existing single-device fast path in memory-events.ts, unchanged
+ * (ADR-011 "Implications for FEAT-407" point 3). This module is that
+ * recompute function: a deterministic, order-independent reduce over the
+ * FULL local event set for one atom_id, implementing conflict classes
+ * A (concurrent-edit), B (edit-vs-supersede), C (edit-vs-erase).
+ *
+ * Deterministic tie-break key everywhere below: (created_at, event_id) —
+ * created_at first, event_id (immutable, globally-unique) breaks ties. No
+ * device is structurally favored (ADR-011).
+ */
+import { randomUUID } from 'node:crypto';
+function loadEvents(db, atomId) {
+    return db
+        .prepare('SELECT * FROM memory_events WHERE atom_id = ? ORDER BY created_at ASC, event_id ASC')
+        .all(atomId);
+}
+function rowExists(db, atomId) {
+    return db.prepare('SELECT 1 FROM memories WHERE id = ?').get(atomId) !== undefined;
+}
+/** Rule C materialization: hard-delete the memories row + its vec row, mirroring MemoryEventRepo.erase()'s row-side effect. */
+function hardDeleteAtom(db, atomId) {
+    const row = db.prepare('SELECT rowid FROM memories WHERE id = ?').get(atomId);
+    if (!row)
+        return false;
+    db.prepare('DELETE FROM memories_vec WHERE rowid = ?').run(BigInt(row.rowid));
+    db.prepare('DELETE FROM memories WHERE id = ?').run(atomId); // FTS trigger fires
+    return true;
+}
+function supersedeTarget(e) {
+    const payload = e.payload_json !== null ? JSON.parse(e.payload_json) : {};
+    const target = payload.superseded_by;
+    if (!target)
+        throw new Error(`supersede event ${e.event_id} on atom ${e.atom_id} is missing payload.superseded_by`);
+    return target;
+}
+/** max by (created_at, event_id) — the ADR-011 canonical tie-break. */
+function maxByTieBreak(events) {
+    return events.reduce((best, e) => {
+        if (e.created_at > best.created_at)
+            return e;
+        if (e.created_at < best.created_at)
+            return best;
+        return e.event_id > best.event_id ? e : best;
+    });
+}
+/**
+ * Class A fork resolution: append a synthetic supersede event chaining the
+ * losing successor atom to the winning one, idempotent on replay (checks
+ * for an existing conflict_merge event with the same target before
+ * inserting). Reuses the exact event_type/payload shape the ordinary
+ * supersede() path uses (ADR-011: "using the exact same event type and
+ * materialization path memory-events.ts already has").
+ */
+function chainLoserToWinner(db, loserAtomId, winnerAtomId, at) {
+    const already = db
+        .prepare(`SELECT 1 FROM memory_events
+       WHERE atom_id = ? AND event_type = 'supersede'
+         AND json_extract(payload_json, '$.superseded_by') = ?
+         AND json_extract(payload_json, '$.reason') = 'conflict_merge'`)
+        .get(loserAtomId, winnerAtomId);
+    if (!already) {
+        db.prepare(`INSERT INTO memory_events (event_id, event_type, atom_id, payload_json, content_hash, created_at)
+       VALUES (?, 'supersede', ?, ?, NULL, ?)`).run(randomUUID(), loserAtomId, JSON.stringify({ superseded_by: winnerAtomId, reason: 'conflict_merge' }), at);
+    }
+    // Recompute the loser's own projection (not just poke its row) so the
+    // loser's full rule set (e.g. its own concurrent erase_request, Rule C)
+    // still takes precedence over this synthetic chaining — recomputeProjection
+    // is idempotent and safe to call from within an already-open transaction
+    // (better-sqlite3 nests via SAVEPOINT).
+    recomputeProjection(db, loserAtomId);
+}
+/**
+ * Recompute the materialized `memories` projection for one atom_id from its
+ * full local event set (local ∪ pulled-remote, already deduped by
+ * event_id). Order-independent: computed as a set-wise reduce, not a
+ * fold-in-arrival-order apply, so calling this any number of times, in any
+ * order relative to sibling atoms, converges to the same result (ADR-011
+ * convergence property).
+ */
+export function recomputeProjection(db, atomId) {
+    const tx = db.transaction(() => {
+        const events = loadEvents(db, atomId);
+        // Rule C: erasure always wins, unconditionally, regardless of any
+        // concurrent invalidate/supersede on the same atom_id.
+        if (events.some(e => e.event_type === 'erase_request')) {
+            hardDeleteAtom(db, atomId);
+            return;
+        }
+        if (!rowExists(db, atomId)) {
+            // Row already gone (erased earlier by this device, or never
+            // materialized) — nothing left to project onto.
+            return;
+        }
+        const supersedes = events.filter(e => e.event_type === 'supersede');
+        const invalidates = events.filter(e => e.event_type === 'invalidate');
+        if (supersedes.length === 0 && invalidates.length === 0) {
+            // Only create/promote_scope/usefulness events, or archive/restore —
+            // none need reconciliation here. archive/restore are intentionally
+            // NOT synced (shipper.ts listUnsynced excludes them: archival is a
+            // per-device retention decision, not a semantic memory change), so
+            // recomputeProjection — which only ever runs on atoms that received a
+            // NEW REMOTE event during a pull round — never sees them.
+            return;
+        }
+        const now = Date.now();
+        if (supersedes.length > 0) {
+            // Rule B (supersede beats invalidate) composed with Rule A (fork
+            // tie-break): resolve the fork first, then supersede wins regardless
+            // of any concurrent invalidate — so invalidates are simply not
+            // consulted once any supersede event exists.
+            const winner = maxByTieBreak(supersedes);
+            const winnerTarget = supersedeTarget(winner);
+            const validTo = Math.min(...supersedes.map(e => e.created_at));
+            db.prepare('UPDATE memories SET valid_to = ?, superseded_by = ?, updated_at = ? WHERE id = ?')
+                .run(validTo, winnerTarget, now, atomId);
+            for (const loser of supersedes) {
+                if (loser === winner)
+                    continue;
+                const loserTarget = supersedeTarget(loser);
+                if (loserTarget === winnerTarget)
+                    continue; // two devices happened to pick the same successor — nothing to chain
+                chainLoserToWinner(db, loserTarget, winnerTarget, Math.max(loser.created_at, now));
+            }
+        }
+        else {
+            // Rule A, invalidate-vs-invalidate: order-independent, first-invalidated-wins.
+            const validTo = Math.min(...invalidates.map(e => e.created_at));
+            db.prepare('UPDATE memories SET valid_to = ?, updated_at = ? WHERE id = ?').run(validTo, now, atomId);
+        }
+    });
+    tx();
+}
+//# sourceMappingURL=conflict-resolve.js.map

package/dist/sync/conflict-resolve.js.map

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

package/dist/sync/puller.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Sync puller (FEAT-407, ADR-011) — cloud/remote-device -> local merge.
+ * The mirror image of shipper.ts: shipper is local -> cloud (push, ADR-003,
+ * one-way); this module is cloud -> local (pull, additive, no push-side
+ * changes — ADR-011 point (e): "synthetic conflict events ride the existing
+ * shipper", no new push-side code).
+ *
+ * Merge shape (ADR-011 "Implications for FEAT-407"):
+ *   1. dedup-insert pulled events by event_id (AC-2 idempotent replay),
+ *   2. scoped projection-recompute (conflict-resolve.ts) for exactly the
+ *      atom_ids that received a NEW event this round,
+ *   3. persist the watermark/cursor in the SAME transaction as (1)+(2), so
+ *      a crash mid-pull cannot advance the watermark past events that were
+ *      not actually durably merged (AC-4: resumable, no gap, no re-pull
+ *      from zero).
+ *
+ * WIRE CONTRACT CAVEAT (be conservative — no live SaaS repo to consult):
+ * astramem-sync@1 (ADR-003) ships `memory_events` metadata ONLY — no atom
+ * body (text/type/hash/scope). That is sufficient for push (the cloud
+ * ledger materializes state from events it already trusts) but a `create`
+ * event pulled onto a device that has never seen this atom_id has nothing
+ * to materialize a `memories` row FROM. Real cross-service pull will need a
+ * cloud-side answer to "where does the atom body come from" that this repo
+ * does not currently define (ADR-003 explicitly scoped pull out: "NOT in
+ * v1: bidirectional sync, cross-device pull"). Rather than block on that,
+ * this module defines `atom_snapshot` as an OPTIONAL, additive field on the
+ * pulled event carrying just enough of the atom body to materialize a new
+ * row locally. This is a LOCAL, FEAT-407-side design choice, not a verified
+ * live cloud contract — flagged explicitly in the FEAT-407 completion
+ * report. `PullFetcher` is injectable specifically so tests can simulate
+ * this without a real cloud.
+ */
+import type { DB } from '../storage/db.js';
+import type { MemoryScope, MemoryType } from '../contracts/memory.js';
+import type { WireSyncEvent } from './shipper.js';
+/** Minimal atom body needed to materialize a brand-new `memories` row on pull. See file header caveat. */
+export interface AtomSnapshot {
+    type: MemoryType;
+    text: string;
+    normalized_text: string;
+    hash: string;
+    scope: MemoryScope;
+    repo?: string | null;
+    project?: string | null;
+    branch?: string | null;
+    agent?: string | null;
+    session_id?: string | null;
+    importance?: number;
+    confidence?: number;
+    source_hash?: string | null;
+    evidence?: string | null;
+}
+export interface RemotePullEvent extends WireSyncEvent {
+    /** Required on pull (unlike push, where it's additive-optional) — it is the dedup key merge correctness depends on. */
+    event_id: string;
+    /** Present only for 'create' events the sender knows the puller may not have seen yet. See file header caveat. */
+    atom_snapshot?: AtomSnapshot | null;
+}
+export interface PullBatch {
+    events: RemotePullEvent[];
+    /** Opaque resume token. null means "no further pages" (nothing beyond this batch). */
+    next_cursor: string | null;
+}
+/** Injectable — the real implementation talks to the cloud; tests supply an in-memory fake event source. */
+export type PullFetcher = (cursor: string | null, limit: number) => Promise<PullBatch>;
+export interface PullOpts {
+    db: DB;
+    fetcher: PullFetcher;
+    batchSize?: number;
+}
+export interface PullOnceResult {
+    /** Events returned by the fetcher this round (before dedup). */
+    fetched: number;
+    /** Events actually newly inserted (post dedup-by-event_id). */
+    inserted: number;
+    /** Distinct atom_ids whose projection was recomputed this round. */
+    atomsRecomputed: number;
+    /** Cursor persisted at the end of this round. */
+    cursor: string | null;
+    /** true when the fetcher returned nothing to pull. */
+    idle: boolean;
+}
+/** Current persisted pull watermark, or null if pull has never run. */
+export declare function getPullWatermark(db: DB): string | null;
+/**
+ * One pull round: fetch a batch from `cursor`, dedup-insert by event_id,
+ * materialize any brand-new atoms, scoped-recompute touched atoms'
+ * projections, and persist the new watermark — all durably: the fetch
+ * itself is outside any transaction (network I/O can't hold a DB lock
+ * across a hung socket), but the merge + watermark advance is one atomic
+ * transaction (AC-4: a crash between fetch and merge simply re-fetches the
+ * same batch next round, which is safe because merge is idempotent).
+ */
+export declare function pullOnce(opts: PullOpts): Promise<PullOnceResult>;
+export interface DrainPullResult {
+    rounds: number;
+    totalFetched: number;
+    totalInserted: number;
+    cursor: string | null;
+}
+/**
+ * Drain every available page: calls pullOnce repeatedly until the fetcher
+ * reports idle (or a `next_cursor` of null after a non-empty batch). Bounds
+ * the number of rounds so a misbehaving fetcher can't loop forever.
+ */
+export declare function drainPull(opts: PullOpts, maxRounds?: number): Promise<DrainPullResult>;
+/**
+ * Real HTTP pull fetcher: GET <url>/sync/pull?cursor=&limit=. NOT exercised
+ * against a live cloud in this slice's tests (no SaaS repo available
+ * locally) — see the completion report's "requires-live-cloud" section.
+ * Response shape assumed to mirror SyncEnvelope's event shape plus
+ * `next_cursor`; this is this daemon's expectation of the pull contract,
+ * not a verified cloud implementation.
+ */
+export declare function httpPullFetcher(url: string, token: string, fetchImpl?: typeof fetch): PullFetcher;

package/dist/sync/puller.js

@@ -0,0 +1,173 @@
+/**
+ * Sync puller (FEAT-407, ADR-011) — cloud/remote-device -> local merge.
+ * The mirror image of shipper.ts: shipper is local -> cloud (push, ADR-003,
+ * one-way); this module is cloud -> local (pull, additive, no push-side
+ * changes — ADR-011 point (e): "synthetic conflict events ride the existing
+ * shipper", no new push-side code).
+ *
+ * Merge shape (ADR-011 "Implications for FEAT-407"):
+ *   1. dedup-insert pulled events by event_id (AC-2 idempotent replay),
+ *   2. scoped projection-recompute (conflict-resolve.ts) for exactly the
+ *      atom_ids that received a NEW event this round,
+ *   3. persist the watermark/cursor in the SAME transaction as (1)+(2), so
+ *      a crash mid-pull cannot advance the watermark past events that were
+ *      not actually durably merged (AC-4: resumable, no gap, no re-pull
+ *      from zero).
+ *
+ * WIRE CONTRACT CAVEAT (be conservative — no live SaaS repo to consult):
+ * astramem-sync@1 (ADR-003) ships `memory_events` metadata ONLY — no atom
+ * body (text/type/hash/scope). That is sufficient for push (the cloud
+ * ledger materializes state from events it already trusts) but a `create`
+ * event pulled onto a device that has never seen this atom_id has nothing
+ * to materialize a `memories` row FROM. Real cross-service pull will need a
+ * cloud-side answer to "where does the atom body come from" that this repo
+ * does not currently define (ADR-003 explicitly scoped pull out: "NOT in
+ * v1: bidirectional sync, cross-device pull"). Rather than block on that,
+ * this module defines `atom_snapshot` as an OPTIONAL, additive field on the
+ * pulled event carrying just enough of the atom body to materialize a new
+ * row locally. This is a LOCAL, FEAT-407-side design choice, not a verified
+ * live cloud contract — flagged explicitly in the FEAT-407 completion
+ * report. `PullFetcher` is injectable specifically so tests can simulate
+ * this without a real cloud.
+ */
+import { recomputeProjection } from './conflict-resolve.js';
+const DEFAULT_PULL_BATCH = 200;
+/** Current persisted pull watermark, or null if pull has never run. */
+export function getPullWatermark(db) {
+    const row = db.prepare('SELECT cursor FROM sync_pull_state WHERE id = 1').get();
+    return row?.cursor ?? null;
+}
+function setPullWatermark(db, cursor, at) {
+    db.prepare(`INSERT INTO sync_pull_state (id, cursor, updated_at) VALUES (1, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET cursor = excluded.cursor, updated_at = excluded.updated_at`).run(cursor, at);
+}
+/**
+ * Dedup-insert one pulled event: `INSERT ... WHERE NOT EXISTS` on event_id
+ * (AC-2). Returns true iff a new row was actually inserted — callers use
+ * this to build the scoped "touched atom_ids" set for recompute (ADR-011
+ * point 3: recompute is scoped, not global).
+ */
+function dedupInsertEvent(db, event) {
+    const payloadJson = event.payload_json !== null ? JSON.stringify(event.payload_json) : null;
+    const result = db
+        .prepare(`INSERT INTO memory_events (event_id, event_type, atom_id, payload_json, content_hash, created_at)
+       SELECT ?, ?, ?, ?, ?, ?
+       WHERE NOT EXISTS (SELECT 1 FROM memory_events WHERE event_id = ?)`)
+        .run(event.event_id, event.event_type, event.atom_id, payloadJson, event.content_hash, event.created_at, event.event_id);
+    return result.changes > 0;
+}
+/**
+ * Materialize a brand-new `memories` row for a pulled 'create' event whose
+ * atom_id this device has never seen, using the atom_id from the event as
+ * the row id (so later events referencing this atom_id line up). No-op
+ * (returns false) if the row already exists (idempotent) or no snapshot was
+ * provided (event predates atom_snapshot support, or the sender assumed the
+ * receiver already had it — nothing this module can materialize from).
+ */
+function materializeAtomIfMissing(db, atomId, snapshot, createdAt) {
+    const exists = db.prepare('SELECT 1 FROM memories WHERE id = ?').get(atomId);
+    if (exists)
+        return false;
+    const now = Date.now();
+    db.prepare(`INSERT INTO memories
+       (id, type, text, normalized_text, repo, project, branch, agent, session_id,
+        importance, confidence, hash, created_at, updated_at, source_hash, evidence, valid_from, scope)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(atomId, snapshot.type, snapshot.text, snapshot.normalized_text, snapshot.repo ?? null, snapshot.project ?? null, snapshot.branch ?? null, snapshot.agent ?? null, snapshot.session_id ?? null, snapshot.importance ?? 0.5, snapshot.confidence ?? 0.5, snapshot.hash, createdAt, now, snapshot.source_hash ?? null, snapshot.evidence ?? null, createdAt, snapshot.scope);
+    return true;
+}
+/**
+ * One pull round: fetch a batch from `cursor`, dedup-insert by event_id,
+ * materialize any brand-new atoms, scoped-recompute touched atoms'
+ * projections, and persist the new watermark — all durably: the fetch
+ * itself is outside any transaction (network I/O can't hold a DB lock
+ * across a hung socket), but the merge + watermark advance is one atomic
+ * transaction (AC-4: a crash between fetch and merge simply re-fetches the
+ * same batch next round, which is safe because merge is idempotent).
+ */
+export async function pullOnce(opts) {
+    const batchSize = opts.batchSize ?? DEFAULT_PULL_BATCH;
+    const watermark = getPullWatermark(opts.db);
+    const batch = await opts.fetcher(watermark, batchSize);
+    if (batch.events.length === 0) {
+        return { fetched: 0, inserted: 0, atomsRecomputed: 0, cursor: watermark, idle: true };
+    }
+    let inserted = 0;
+    const touchedAtomIds = new Set();
+    const tx = opts.db.transaction(() => {
+        for (const event of batch.events) {
+            const wasInserted = dedupInsertEvent(opts.db, event);
+            if (!wasInserted)
+                continue;
+            inserted++;
+            touchedAtomIds.add(event.atom_id);
+            if (event.event_type === 'create' && event.atom_snapshot) {
+                materializeAtomIfMissing(opts.db, event.atom_id, event.atom_snapshot, event.created_at);
+            }
+        }
+        for (const atomId of touchedAtomIds) {
+            recomputeProjection(opts.db, atomId);
+        }
+        setPullWatermark(opts.db, batch.next_cursor, Date.now());
+    });
+    tx();
+    return {
+        fetched: batch.events.length,
+        inserted,
+        atomsRecomputed: touchedAtomIds.size,
+        cursor: batch.next_cursor,
+        idle: false,
+    };
+}
+/**
+ * Drain every available page: calls pullOnce repeatedly until the fetcher
+ * reports idle (or a `next_cursor` of null after a non-empty batch). Bounds
+ * the number of rounds so a misbehaving fetcher can't loop forever.
+ */
+export async function drainPull(opts, maxRounds = 1000) {
+    let rounds = 0;
+    let totalFetched = 0;
+    let totalInserted = 0;
+    let cursor = getPullWatermark(opts.db);
+    while (rounds < maxRounds) {
+        const result = await pullOnce(opts);
+        rounds++;
+        totalFetched += result.fetched;
+        totalInserted += result.inserted;
+        cursor = result.cursor;
+        if (result.idle || result.cursor === null)
+            break;
+    }
+    return { rounds, totalFetched, totalInserted, cursor };
+}
+/**
+ * Real HTTP pull fetcher: GET <url>/sync/pull?cursor=&limit=. NOT exercised
+ * against a live cloud in this slice's tests (no SaaS repo available
+ * locally) — see the completion report's "requires-live-cloud" section.
+ * Response shape assumed to mirror SyncEnvelope's event shape plus
+ * `next_cursor`; this is this daemon's expectation of the pull contract,
+ * not a verified cloud implementation.
+ */
+export function httpPullFetcher(url, token, fetchImpl = fetch) {
+    return async (cursor, limit) => {
+        const qs = new URLSearchParams({ limit: String(limit) });
+        if (cursor !== null)
+            qs.set('cursor', cursor);
+        const res = await fetchImpl(`${url.replace(/\/$/, '')}/sync/pull?${qs.toString()}`, {
+            method: 'GET',
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok) {
+            throw new Error(`sync pull failed: HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        if (!Array.isArray(body.events)) {
+            throw new Error('sync pull failed: response missing events[]');
+        }
+        return {
+            events: body.events,
+            next_cursor: typeof body.next_cursor === 'string' ? body.next_cursor : null,
+        };
+    };
+}
+//# sourceMappingURL=puller.js.map

package/dist/sync/puller.js.map

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

package/dist/sync/shipper.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Sync shipper (Wave 3d, ADR-003) — one-way, append-only, idempotent log
+ * shipping: local memory_events -> cloud POST /sync/events.
+ *
+ * The log IS the queue: unsynced rows are `synced_at IS NULL`; a batch is
+ * acked by the cloud's `{ acked_seq }` and marked in one UPDATE. Crash-safe
+ * by construction — replaying a batch is always safe (cloud dedups on
+ * content_hash and (device_id, seq)).
+ *
+ * Scope filter (ADR-009): only events whose atom is team/org-scoped ship.
+ * `personal` atoms never leave the machine. erase_request events for atoms
+ * whose row is already hard-deleted ship when their payload carries a
+ * team/org scope (3f writes the scope into the erase payload for exactly
+ * this reason).
+ *
+ * Offline: unlimited — failures leave rows unsynced; retry with exponential
+ * backoff capped at BACKOFF_CAP_MS.
+ */
+import type { DB } from '../storage/db.js';
+export declare const SYNC_PROTOCOL: "astramem-sync@1";
+export interface WireSyncEvent {
+    seq: number;
+    event_type: string;
+    atom_id: string;
+    payload_json: Record<string, unknown> | null;
+    content_hash: string | null;
+    created_at: number;
+    /**
+     * Globally-unique event identity (ADR-011, migration 010). Additive field
+     * — no astramem-sync@1 version bump (ADR-001's additive-field evolution
+     * rule): older push clients that omit it are still valid envelopes; this
+     * daemon always populates it (migration 010 backfills every pre-existing
+     * row, and MemoryEventRepo.append() always assigns one going forward).
+     * It is the pull-side dedup key (FEAT-407 AC-2) and the ADR-011 conflict
+     * tie-break key (created_at, event_id).
+     */
+    event_id: string;
+}
+export interface SyncEnvelope {
+    protocol: typeof SYNC_PROTOCOL;
+    device_id: string;
+    workspace_id: string;
+    cursor: number;
+    events: WireSyncEvent[];
+}
+export interface ShipperOpts {
+    db: DB;
+    /** Cloud base URL, e.g. https://memory.example.com — POSTs to <url>/sync/events. */
+    url: string;
+    workspaceId: string;
+    deviceId: string;
+    /** Bearer for the cloud (device token). */
+    token: string;
+    batchSize?: number;
+    intervalMs?: number;
+    /** Injectable fetch for tests. */
+    fetchImpl?: typeof fetch;
+}
+export interface ShipperHandle {
+    /** Stop the loop. Resolves after any in-flight ship completes. */
+    stop(): Promise<void>;
+}
+/**
+ * Stable per-install device id, persisted as a plain file in the config dir
+ * (an identifier, not a secret — the device TOKEN lives in the keystore).
+ */
+export declare function getOrCreateDeviceId(configDir: string): string;
+interface UnsyncedRow {
+    seq: number;
+    event_id: string;
+    event_type: string;
+    atom_id: string;
+    payload_json: string | null;
+    content_hash: string | null;
+    created_at: number;
+}
+/**
+ * Unsynced, ship-eligible events in seq order (ADR-009 scope filter).
+ * LEFT JOIN: an erase_request may outlive its memories row — it ships when
+ * its payload records a team/org scope.
+ *
+ * `archive`/`restore` (FEAT-404) are excluded unconditionally, regardless of
+ * scope: archival is a per-device retention/storage-hygiene decision (one
+ * device's local SQLite-growth mitigation), not a semantic memory change,
+ * so it must never leave the machine. The sync wire schema
+ * (contracts/schemas/sync-envelope.v1.schema.json) also never lists these
+ * two types in its event_type enum — shipping one would fail schema
+ * validation on the wire, on top of being the wrong policy.
+ */
+export declare function listUnsynced(db: DB, batchSize: number): UnsyncedRow[];
+/** Last acked seq = highest synced event seq (0 when nothing has shipped). */
+export declare function lastAckedSeq(db: DB): number;
+export declare function buildEnvelope(deviceId: string, workspaceId: string, cursor: number, rows: UnsyncedRow[]): SyncEnvelope;
+export interface ShipOnceResult {
+    shipped: number;
+    acked: number;
+    /** true when there was nothing eligible to ship. */
+    idle: boolean;
+}
+/**
+ * One shipping round: read a batch, POST it, mark acked rows synced.
+ * Throws on transport/HTTP failure — the caller owns retry/backoff.
+ */
+export declare function shipOnce(opts: ShipperOpts): Promise<ShipOnceResult>;
+/** Pure backoff schedule: base * 2^failures, capped. Exported for tests. */
+export declare function backoffDelay(baseMs: number, consecutiveFailures: number): number;
+/**
+ * Start the periodic shipper loop. Ships immediately, then every intervalMs;
+ * on failure the next attempt is delayed by exponential backoff.
+ */
+export declare function startShipper(opts: ShipperOpts): ShipperHandle;
+export {};