@interocitor/core 0.0.0-beta.10

package/dist/core/compaction.js

@@ -0,0 +1,190 @@
+/**
+ * Compaction — snapshot + manifest rotation + change file pruning.
+ *
+ * Concurrency note:
+ * - No built-in lock or CAS on manifest pointer.
+ * - Concurrent compaction can race and overwrite the pointer.
+ * - Recommended: acquire a remote lease (e.g. mainline/compact-lock.json)
+ *   and abort if another compactor is active, or if manifest generation
+ *   changes after the lease is acquired.
+ *
+ * Extracted from Interocitor. Not part of the public API.
+ */
+import { hlcSerialize, hlcCompareStr } from "./hlc.js";
+import { paths, textEncoder, textDecoder, generateId, computeContentHash, log } from "./internals.js";
+import { encodeSnapshotPayload, decodeSnapshotPayload } from "./codec.js";
+import { readJsonIfExists, writeJson } from "./manifest.js";
+import { hlcParse } from "./hlc.js";
+async function computeGcFloor(ctx, nowMs) {
+    const p = paths(ctx.remotePath);
+    const graceMs = ctx.offlineGraceMs ?? 7 * 24 * 60 * 60000;
+    const cutoffMs = nowMs - graceMs;
+    const floors = [];
+    try {
+        const files = await ctx.adapter.listFiles(p.devicesFolder);
+        for (const file of files) {
+            if (!file.name.endsWith('.json'))
+                continue;
+            const deviceId = file.name.slice(0, -'.json'.length);
+            const meta = await readJsonIfExists(ctx.adapter, p.deviceFile(deviceId));
+            if (!meta || meta.retired)
+                continue;
+            const lastSeen = Date.parse(meta.lastSeenAt || '');
+            if (Number.isFinite(lastSeen) && lastSeen < cutoffMs)
+                continue;
+            // Active devices that have not yet acknowledged a watermark block
+            // advancement. They are still inside the offline grace window.
+            if (!meta.observedWatermarkHlc)
+                return ctx.manifest.gcFloorHlc ?? '';
+            floors.push(meta.observedWatermarkHlc);
+        }
+    }
+    catch {
+        return ctx.manifest.gcFloorHlc ?? '';
+    }
+    if (floors.length === 0)
+        return ctx.manifest.gcFloorHlc ?? '';
+    floors.sort(hlcCompareStr);
+    const candidate = floors[0];
+    const existing = ctx.manifest.gcFloorHlc ?? '';
+    if (existing && hlcCompareStr(existing, candidate) > 0)
+        return existing;
+    return candidate;
+}
+export async function compact(ctx) {
+    const { adapter, local, remotePath, manifest, codecState, deviceId, serverId } = ctx;
+    if (manifest.server.managed && deviceId !== serverId) {
+        throw new Error('Compaction is allowed only for the authorized server writer');
+    }
+    // Ensure the compactor has merged latest remote changes before snapshotting.
+    await ctx.pull();
+    const p = paths(remotePath);
+    const nowDate = new Date();
+    const now = nowDate.toISOString();
+    const gcFloorHlc = await computeGcFloor(ctx, nowDate.getTime());
+    const nextEpoch = manifest.epoch + 1;
+    const nextGeneration = manifest.generation + 1;
+    const snapshotPath = `${p.mainlineFolder}/snapshot-${nextEpoch}-${serverId}.json`;
+    // Build a full snapshot from IDB — the in-memory cache is partial.
+    const allRows = await local.getAllRows();
+    const snapshotTables = {};
+    for (const row of allRows) {
+        if (gcFloorHlc
+            && row._meta.deleted
+            && row._meta.deletedHlc
+            && hlcCompareStr(row._meta.deletedHlc, gcFloorHlc) <= 0) {
+            continue;
+        }
+        const t = row._meta.table;
+        if (!snapshotTables[t])
+            snapshotTables[t] = {};
+        snapshotTables[t][row._meta.rowId] = row;
+    }
+    const snapshot = {
+        snapshotId: generateId('snap'),
+        timestamp: now,
+        hlc: hlcSerialize(ctx.hlc),
+        epoch: nextEpoch,
+        schemaVersion: manifest.schema,
+        tables: snapshotTables,
+    };
+    const snapshotPayload = await encodeSnapshotPayload(codecState, snapshot);
+    await adapter.writeFile(snapshotPath, textEncoder.encode(snapshotPayload));
+    const manifestPayload = {
+        generation: nextGeneration,
+        parentGeneration: manifest.generation,
+        writtenBy: serverId,
+        writtenAt: now,
+        version: 3,
+        meshId: manifest.meshId,
+        schema: manifest.schema,
+        encrypted: manifest.encrypted,
+        server: manifest.server,
+        createdAt: manifest.createdAt,
+        epoch: nextEpoch,
+        watermarkHlc: hlcSerialize(ctx.hlc),
+        snapshotPath,
+        deltaPath: null,
+        gcFloorHlc,
+        gcEpoch: gcFloorHlc ? nextEpoch : manifest.gcEpoch,
+        gcCreatedAt: gcFloorHlc ? now : manifest.gcCreatedAt,
+        offlineGraceMs: ctx.offlineGraceMs,
+    };
+    const nextManifest = {
+        ...manifestPayload,
+        contentHash: await computeContentHash(manifestPayload),
+    };
+    const manifestFile = `manifest-${nextGeneration}.json`;
+    await writeJson(adapter, p.manifestFile(nextGeneration), nextManifest);
+    await writeJson(adapter, p.manifestPointer, {
+        currentGeneration: nextGeneration,
+        file: manifestFile,
+    });
+    await local.setMeta('epoch', nextEpoch);
+    // Prune all change files captured in the snapshot.
+    const watermarkHlc = nextManifest.watermarkHlc;
+    log('debug', 'compact() — pruning change files ≤ watermark', { watermarkHlc });
+    try {
+        const files = await adapter.listFiles(p.changesFolder);
+        for (const file of files) {
+            if (file.name === 'head.json')
+                continue;
+            const chgIdx = file.name.lastIndexOf('-chg_');
+            if (chgIdx === -1)
+                continue;
+            const fileHlc = file.name.slice(0, chgIdx);
+            if (hlcCompareStr(fileHlc, watermarkHlc) <= 0) {
+                await adapter.deleteFile(file.path);
+            }
+        }
+        log('debug', 'compact() — pruning complete');
+    }
+    catch (err) {
+        log('warn', 'compact() — pruning failed (non-fatal, snapshot is still valid)', err);
+    }
+    return nextManifest;
+}
+/** Returns the updated HLC after rehydration. */
+export async function rehydrate(ctx) {
+    let hlc = ctx.hlc;
+    ctx.emit({ type: 'rehydrate:start' });
+    const snapshotPath = ctx.manifest?.snapshotPath;
+    if (!snapshotPath) {
+        ctx.emit({ type: 'rehydrate:complete', rowCount: 0 });
+        await ctx.pull();
+        return hlc;
+    }
+    try {
+        const data = await ctx.adapter.readFile(snapshotPath);
+        const snapshot = await decodeSnapshotPayload(ctx.codecState, ctx.local, textDecoder.decode(data), snapshotPath);
+        // Clear local state
+        await ctx.local.clearAll();
+        ctx.tables = {};
+        ctx.knownTables.clear();
+        // Write snapshot rows to IDB
+        let rowCount = 0;
+        for (const [tableName, rows] of Object.entries(snapshot.tables)) {
+            ctx.knownTables.add(tableName);
+            for (const row of Object.values(rows)) {
+                await ctx.local.putRow(row);
+                rowCount++;
+            }
+        }
+        // Restore HLC
+        if (snapshot.hlc) {
+            hlc = hlcParse(snapshot.hlc);
+            hlc.nodeId = ctx.deviceId;
+        }
+        await ctx.local.setMeta('epoch', snapshot.epoch);
+        ctx.emit({ type: 'rehydrate:complete', rowCount });
+    }
+    catch (err) {
+        ctx.emit({ type: 'decode:error', error: err instanceof Error ? err : new Error(String(err)), path: snapshotPath, context: { stage: 'rehydrate' } });
+        const poisoned = await ctx.poisonRemote(err, snapshotPath);
+        ctx.emit({ type: 'sync:error', error: poisoned });
+        throw poisoned;
+    }
+    // Pull any changes since the snapshot
+    await ctx.pull();
+    return hlc;
+}

package/dist/core/connected-stores.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Connected Stores — credentials for derived sub-stores of this Interocitor.
+ *
+ * Scope: this module only **stores** credentials for other Interocitor
+ * stores that this one owns conceptually (sub-stores). It does NOT
+ * construct child engines, run them, pair them, or know about adapters.
+ * Apps read credentials and build whatever Interocitor they want.
+ *
+ * Persistence: a single JSON list under a dedicated meta key in the parent
+ * LocalStore. No rows, no tables — sub-store credentials never appear in
+ * the parent's data model.
+ *
+ * Direction: one-way by construction. The parent stores credentials for
+ * sub-stores; sub-stores have no awareness of the parent.
+ *
+ * Security stance: anyone with read access to the parent inherits read
+ * access to every sub-store's credentials. That is the intended model
+ * for derived sub-stores.
+ */
+import type { LocalStoreAdapter } from './types.ts';
+/** Adapter pointer. Opaque to the engine; apps interpret `kind` and `config`. */
+export interface ConnectedStoreAdapterRef {
+    kind: string;
+    config?: string;
+}
+/**
+ * Credentials for a sub-store. Just enough for an app to construct the
+ * corresponding child Interocitor; the engine never reads these fields.
+ */
+export interface ConnectedStoreCredentials {
+    /** Stable id for the sub-store. Required and unique within parent. */
+    id: string;
+    /** Optional human-readable label. */
+    alias?: string;
+    /** Remote folder path inside the adapter for the sub-store. */
+    remotePath: string;
+    /** Sub-store passphrase, or null for unencrypted sub-stores. */
+    passphrase: string | null;
+    /** Whether the sub-store uses encryption. */
+    encrypted: boolean;
+    /** Suggested local IndexedDB name for the sub-store. */
+    dbName: string;
+    /** Optional adapter pointer the app can use to materialize a StorageAdapter. */
+    adapter?: ConnectedStoreAdapterRef;
+    /** Optional human-readable app name. */
+    appName?: string;
+    /** Free-form metadata for app UI. */
+    metadata?: Record<string, unknown>;
+    /** ISO timestamp the credentials were first stored. Set by the registry. */
+    createdAt?: string;
+    /** ISO timestamp of the most recent update. Set by the registry. */
+    updatedAt?: string;
+}
+/**
+ * Credential vault for connected (sub-)stores.
+ *
+ * No `connect()`, no factories, no adapter resolution. Apps read what they
+ * need and build their own engines.
+ */
+export interface ConnectedStoresApi {
+    list(): Promise<ConnectedStoreCredentials[]>;
+    get(id: string): Promise<ConnectedStoreCredentials | null>;
+    put(credentials: ConnectedStoreCredentials): Promise<ConnectedStoreCredentials>;
+    remove(id: string): Promise<boolean>;
+}
+/** LocalStore-backed implementation. JSON list under a single meta key. */
+export declare class LocalStoreConnectedStoresApi implements ConnectedStoresApi {
+    private readonly local;
+    constructor(local: LocalStoreAdapter);
+    private readAll;
+    private writeAll;
+    list(): Promise<ConnectedStoreCredentials[]>;
+    get(id: string): Promise<ConnectedStoreCredentials | null>;
+    put(credentials: ConnectedStoreCredentials): Promise<ConnectedStoreCredentials>;
+    remove(id: string): Promise<boolean>;
+}
+//# sourceMappingURL=connected-stores.d.ts.map

package/dist/core/connected-stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connected-stores.d.ts","sourceRoot":"","sources":["../../src/core/connected-stores.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAIpD,iFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,IAAI,OAAO,CAAC,yBAAyB,EAAE,CAAC,CAAC;IAC7C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAAC;IAC3D,GAAG,CAAC,WAAW,EAAE,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAChF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED,2EAA2E;AAC3E,qBAAa,4BAA6B,YAAW,kBAAkB;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,iBAAiB;YAEvC,OAAO;YAeP,QAAQ;IAIhB,IAAI,IAAI,OAAO,CAAC,yBAAyB,EAAE,CAAC;IAI5C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC;IAK1D,GAAG,CAAC,WAAW,EAAE,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAe/E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAO3C"}

package/dist/core/connected-stores.js

@@ -0,0 +1,76 @@
+/**
+ * Connected Stores — credentials for derived sub-stores of this Interocitor.
+ *
+ * Scope: this module only **stores** credentials for other Interocitor
+ * stores that this one owns conceptually (sub-stores). It does NOT
+ * construct child engines, run them, pair them, or know about adapters.
+ * Apps read credentials and build whatever Interocitor they want.
+ *
+ * Persistence: a single JSON list under a dedicated meta key in the parent
+ * LocalStore. No rows, no tables — sub-store credentials never appear in
+ * the parent's data model.
+ *
+ * Direction: one-way by construction. The parent stores credentials for
+ * sub-stores; sub-stores have no awareness of the parent.
+ *
+ * Security stance: anyone with read access to the parent inherits read
+ * access to every sub-store's credentials. That is the intended model
+ * for derived sub-stores.
+ */
+const REGISTRY_META_KEY = 'interocitor:connected-stores';
+/** LocalStore-backed implementation. JSON list under a single meta key. */
+export class LocalStoreConnectedStoresApi {
+    constructor(local) {
+        this.local = local;
+    }
+    async readAll() {
+        const raw = await this.local.getMeta(REGISTRY_META_KEY);
+        if (!raw)
+            return [];
+        if (Array.isArray(raw))
+            return raw;
+        if (typeof raw === 'string') {
+            try {
+                const parsed = JSON.parse(raw);
+                return Array.isArray(parsed) ? parsed : [];
+            }
+            catch {
+                return [];
+            }
+        }
+        return [];
+    }
+    async writeAll(creds) {
+        await this.local.setMeta(REGISTRY_META_KEY, JSON.stringify(creds));
+    }
+    async list() {
+        return this.readAll();
+    }
+    async get(id) {
+        const all = await this.readAll();
+        return all.find(c => c.id === id) ?? null;
+    }
+    async put(credentials) {
+        if (!credentials.id)
+            throw new Error('ConnectedStoreCredentials.id is required');
+        const now = new Date().toISOString();
+        const all = await this.readAll();
+        const existing = all.find(c => c.id === credentials.id);
+        const stamped = {
+            ...credentials,
+            createdAt: existing?.createdAt ?? credentials.createdAt ?? now,
+            updatedAt: now,
+        };
+        const next = [...all.filter(c => c.id !== credentials.id), stamped];
+        await this.writeAll(next);
+        return stamped;
+    }
+    async remove(id) {
+        const all = await this.readAll();
+        const next = all.filter(c => c.id !== id);
+        if (next.length === all.length)
+            return false;
+        await this.writeAll(next);
+        return true;
+    }
+}

package/dist/core/crdt.d.ts

@@ -0,0 +1,36 @@
+/**
+ * CRDT Merge Engine — configurable per-column merge strategy.
+ *
+ * Each column in each row carries its own HLC.
+ * The merge strategy determines which value wins on conflict:
+ *
+ *  - `'remote-wins'` — Remote always overwrites local. (Default)
+ *  - `'lww'`         — Last-Writer-Wins. Highest HLC wins.
+ *  - `'local-wins'`  — Keep local value when both exist.
+ *  - custom function  — `(local, remote, ctx) => ColumnEntry`
+ *
+ * Deletes are soft (tombstone with HLC) and always use LWW.
+ *
+ * Row shape (`{_meta, payload}`) keeps user payload fully isolated from
+ * engine metadata. The merge loop only touches `row.payload`; `row._meta`
+ * is never indexed by user-controlled keys.
+ */
+import type { Row, Op, ChangeEntry, DatabaseSchemaDefinition } from './types.ts';
+/**
+ * Apply a single op to the in-memory state.
+ * Returns the affected row (mutated in place) or null if no change.
+ */
+export declare function applyOp(tables: Record<string, Record<string, Row>>, op: Op, schemaVersion: number, schema?: DatabaseSchemaDefinition): Row | null;
+/**
+ * Apply a full change entry (potentially multiple ops).
+ * Returns list of affected rows.
+ */
+export declare function applyChangeEntry(tables: Record<string, Record<string, Row>>, entry: ChangeEntry, schemaVersion: number, schema?: DatabaseSchemaDefinition): Row[];
+/** Read a column value from a row, unwrapping the ColumnEntry. */
+export declare function readColumn(row: Row, column: string): unknown;
+/**
+ * Build a plain object from a row (strip HLC metadata).
+ * Returns user-facing fields with `_meta` projection (table, rowId, deleted).
+ */
+export declare function rowToPlain(row: Row): Record<string, unknown>;
+//# sourceMappingURL=crdt.d.ts.map

package/dist/core/crdt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crdt.d.ts","sourceRoot":"","sources":["../../src/core/crdt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,GAAG,EACH,EAAE,EAEF,WAAW,EACX,wBAAwB,EAGzB,MAAM,YAAY,CAAC;AAoEpB;;;GAGG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAC3C,EAAE,EAAE,EAAE,EACN,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,wBAAwB,GAChC,GAAG,GAAG,IAAI,CAuEZ;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAC3C,KAAK,EAAE,WAAW,EAClB,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,wBAAwB,GAChC,GAAG,EAAE,CAOP;AAED,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAU5D"}

package/dist/core/crdt.js

@@ -0,0 +1,174 @@
+/**
+ * CRDT Merge Engine — configurable per-column merge strategy.
+ *
+ * Each column in each row carries its own HLC.
+ * The merge strategy determines which value wins on conflict:
+ *
+ *  - `'remote-wins'` — Remote always overwrites local. (Default)
+ *  - `'lww'`         — Last-Writer-Wins. Highest HLC wins.
+ *  - `'local-wins'`  — Keep local value when both exist.
+ *  - custom function  — `(local, remote, ctx) => ColumnEntry`
+ *
+ * Deletes are soft (tombstone with HLC) and always use LWW.
+ *
+ * Row shape (`{_meta, payload}`) keeps user payload fully isolated from
+ * engine metadata. The merge loop only touches `row.payload`; `row._meta`
+ * is never indexed by user-controlled keys.
+ */
+import { hlcCompareStr } from "./hlc.js";
+/**
+ * Resolve the merge strategy for a specific column.
+ *
+ * Resolution order (first defined wins):
+ *   field-level → table-level → database-level → 'lww'
+ */
+function resolveStrategy(schema, table, field) {
+    const tableDef = schema?.tables[table];
+    if (tableDef?.merge) {
+        const m = tableDef.merge;
+        if (typeof m === 'object' && 'fields' in m) {
+            const config = m;
+            if (config.fields?.[field])
+                return config.fields[field];
+            if (config.strategy)
+                return config.strategy;
+        }
+        else {
+            return m;
+        }
+    }
+    if (!schema)
+        return 'lww';
+    return schema.mergeStrategy ?? 'remote-wins';
+}
+/**
+ * Decide which column entry wins given a strategy.
+ *
+ * `local` may be undefined (new column). In that case, remote always wins
+ * regardless of strategy — there's no conflict.
+ */
+function mergeColumn(local, remote, strategy, table, rowId, field) {
+    if (!local || !local.hlc)
+        return remote;
+    if (typeof strategy === 'function') {
+        const result = strategy(local, remote, { table, rowId, field });
+        return result.hlc !== local.hlc || result.value !== local.value ? result : null;
+    }
+    switch (strategy) {
+        case 'remote-wins':
+            return remote;
+        case 'local-wins':
+            return null;
+        default:
+            return hlcCompareStr(remote.hlc, local.hlc) > 0 ? remote : null;
+    }
+}
+/** Build a fresh row stub. */
+function blankRow(table, rowId, schemaVersion, deleted = false, deletedHlc) {
+    return {
+        _meta: { table, rowId, deleted, deletedHlc, schemaVersion },
+        payload: {},
+    };
+}
+/**
+ * Apply a single op to the in-memory state.
+ * Returns the affected row (mutated in place) or null if no change.
+ */
+export function applyOp(tables, op, schemaVersion, schema) {
+    if (!tables[op.table]) {
+        tables[op.table] = {};
+    }
+    const table = tables[op.table];
+    if (op.type === 'delete') {
+        const existing = table[op.rowId];
+        if (existing) {
+            // Stale delete (older than current tombstone)?
+            if (existing._meta.deletedHlc && hlcCompareStr(op.hlc, existing._meta.deletedHlc) <= 0) {
+                return null;
+            }
+            // Any payload column newer than this delete? Then delete loses.
+            const hasNewerColumn = Object.values(existing.payload).some(entry => {
+                return entry?.hlc && hlcCompareStr(entry.hlc, op.hlc) > 0;
+            });
+            if (hasNewerColumn)
+                return null;
+            existing._meta.deleted = true;
+            existing._meta.deletedHlc = op.hlc;
+            // A tombstone only needs deletedHlc for future conflict checks. Keeping
+            // payload columns wastes storage and can leak pre-delete values into
+            // future row incarnations.
+            existing.payload = {};
+            return existing;
+        }
+        // Tombstone for unseen row.
+        const row = blankRow(op.table, op.rowId, schemaVersion, true, op.hlc);
+        table[op.rowId] = row;
+        return row;
+    }
+    // Upsert.
+    let row = table[op.rowId];
+    let changed = false;
+    if (!row) {
+        row = blankRow(op.table, op.rowId, schemaVersion);
+        table[op.rowId] = row;
+        changed = true;
+    }
+    let columnsToApply = Object.entries(op.columns);
+    // Resurrection creates a new row incarnation. The tombstone wins over every
+    // payload column at or before deletedHlc, including columns retained on the
+    // local tombstone and stale columns bundled in a remote upsert. Otherwise a
+    // partial insert after delete can republish pre-delete fields forever.
+    if (row._meta.deleted && row._meta.deletedHlc) {
+        const deletedHlc = row._meta.deletedHlc;
+        columnsToApply = columnsToApply.filter(([, entry]) => hlcCompareStr(entry.hlc, deletedHlc) > 0);
+        if (columnsToApply.length === 0)
+            return null;
+        row.payload = {};
+        row._meta.deleted = false;
+        row._meta.deletedHlc = undefined;
+        changed = true;
+    }
+    for (const [col, entry] of columnsToApply) {
+        const existing = row.payload[col];
+        const strategy = resolveStrategy(schema, op.table, col);
+        const winner = mergeColumn(existing, entry, strategy, op.table, op.rowId, col);
+        if (winner) {
+            row.payload[col] = winner;
+            changed = true;
+        }
+    }
+    return changed ? row : null;
+}
+/**
+ * Apply a full change entry (potentially multiple ops).
+ * Returns list of affected rows.
+ */
+export function applyChangeEntry(tables, entry, schemaVersion, schema) {
+    const affected = [];
+    for (const op of entry.ops) {
+        const row = applyOp(tables, op, schemaVersion, schema);
+        if (row)
+            affected.push(row);
+    }
+    return affected;
+}
+/** Read a column value from a row, unwrapping the ColumnEntry. */
+export function readColumn(row, column) {
+    const entry = row.payload?.[column];
+    return entry?.value;
+}
+/**
+ * Build a plain object from a row (strip HLC metadata).
+ * Returns user-facing fields with `_meta` projection (table, rowId, deleted).
+ */
+export function rowToPlain(row) {
+    const result = {
+        _table: row._meta.table,
+        _rowId: row._meta.rowId,
+        _deleted: row._meta.deleted,
+    };
+    for (const [key, entry] of Object.entries(row.payload)) {
+        result[key] = entry.value;
+    }
+    return result;
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Typed error classes for the Interocitor engine.
+ *
+ * Callers should prefer `instanceof` over message/code string matching.
+ * Every typed error keeps its `code` field stable across releases — it
+ * is part of the public contract.
+ */
+/**
+ * Thrown by `connect()` when the engine's `encrypted` flag does not
+ * match the encryption mode the remote mesh was bootstrapped with.
+ *
+ * Common cause: the app constructs the engine with `encrypted: false`
+ * on first run (e.g. before the user supplies a passphrase) and later
+ * reconnects with `encrypted: true`. The remote is healthy and is
+ * NOT poisoned by this error — the local engine config is wrong.
+ *
+ * Recovery: rebuild the engine with `encrypted` set to `expectedMode`
+ * and supply the matching passphrase when `expectedMode === true`.
+ */
+/**
+ * Thrown by `connect()` when the credential store has a record under the
+ * engine's `dbName` but the stored `meshId` does not match the live mesh
+ * the engine is connecting to.
+ *
+ * Common cause: app reuses the same `dbName` for "create new mesh" — the
+ * old record (passphrase + deviceId for the previous mesh) survives the
+ * recreate. Silently reusing the old key would either fail to decrypt
+ * the new mesh's files or, worse, encrypt new writes under the wrong
+ * key and poison the remote.
+ *
+ * Recovery: the caller decides — either `clearCredentials()` and retry,
+ * or change `dbName` so the two meshes have isolated credential stores.
+ */
+export declare class MeshCredentialMismatchError extends Error {
+    readonly code: "MESH_CREDENTIAL_MISMATCH";
+    readonly dbName: string;
+    readonly storedMeshId: string;
+    readonly activeMeshId: string;
+    constructor(dbName: string, storedMeshId: string, activeMeshId: string);
+}
+export declare class MeshEncryptionMismatchError extends Error {
+    readonly code: "MESH_ENCRYPTION_MISMATCH";
+    readonly expectedMode: boolean;
+    readonly actualMode: boolean;
+    constructor(expectedMode: boolean, actualMode: boolean);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;;;GAaG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAavE;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;IACpD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;gBAEjB,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO;CAavD"}

package/dist/core/errors.js

@@ -0,0 +1,61 @@
+/**
+ * Typed error classes for the Interocitor engine.
+ *
+ * Callers should prefer `instanceof` over message/code string matching.
+ * Every typed error keeps its `code` field stable across releases — it
+ * is part of the public contract.
+ */
+/**
+ * Thrown by `connect()` when the engine's `encrypted` flag does not
+ * match the encryption mode the remote mesh was bootstrapped with.
+ *
+ * Common cause: the app constructs the engine with `encrypted: false`
+ * on first run (e.g. before the user supplies a passphrase) and later
+ * reconnects with `encrypted: true`. The remote is healthy and is
+ * NOT poisoned by this error — the local engine config is wrong.
+ *
+ * Recovery: rebuild the engine with `encrypted` set to `expectedMode`
+ * and supply the matching passphrase when `expectedMode === true`.
+ */
+/**
+ * Thrown by `connect()` when the credential store has a record under the
+ * engine's `dbName` but the stored `meshId` does not match the live mesh
+ * the engine is connecting to.
+ *
+ * Common cause: app reuses the same `dbName` for "create new mesh" — the
+ * old record (passphrase + deviceId for the previous mesh) survives the
+ * recreate. Silently reusing the old key would either fail to decrypt
+ * the new mesh's files or, worse, encrypt new writes under the wrong
+ * key and poison the remote.
+ *
+ * Recovery: the caller decides — either `clearCredentials()` and retry,
+ * or change `dbName` so the two meshes have isolated credential stores.
+ */
+export class MeshCredentialMismatchError extends Error {
+    constructor(dbName, storedMeshId, activeMeshId) {
+        super(`Stored credentials under dbName="${dbName}" belong to meshId="${storedMeshId}" ` +
+            `but the active mesh is meshId="${activeMeshId}". ` +
+            `Refusing to silently reuse the wrong key. ` +
+            `Call engine.clearCredentials() to drop the stale record, ` +
+            `or use a different dbName for the new mesh.`);
+        this.code = 'MESH_CREDENTIAL_MISMATCH';
+        this.name = 'MeshCredentialMismatchError';
+        this.dbName = dbName;
+        this.storedMeshId = storedMeshId;
+        this.activeMeshId = activeMeshId;
+    }
+}
+export class MeshEncryptionMismatchError extends Error {
+    constructor(expectedMode, actualMode) {
+        super(`Mesh encryption mode mismatch: remote mesh was bootstrapped with ` +
+            `encrypted=${expectedMode} but this engine was created with ` +
+            `encrypted=${actualMode}. Recreate the Interocitor instance with ` +
+            `encrypted=${expectedMode}` +
+            (expectedMode ? ' and supply the matching passphrase' : '') +
+            `, or join a fresh mesh. Remote was NOT poisoned.`);
+        this.code = 'MESH_ENCRYPTION_MISMATCH';
+        this.name = 'MeshEncryptionMismatchError';
+        this.expectedMode = expectedMode;
+        this.actualMode = actualMode;
+    }
+}