@interocitor/core 0.0.0-beta.10

package/dist/core/flush.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Flush — push queued local outbox entries to remote cloud.
+ *
+ * Extracted from Interocitor. Not part of the public API.
+ */
+import type { StorageAdapter, ChangeEntry, SyncEvent } from './types.ts';
+import type { CodecState } from './codec.ts';
+export declare function flushToAdapter(adapter: StorageAdapter, remotePath: string, entries: ChangeEntry[], isPrimary: boolean, codecState: CodecState, deviceId: string, emit?: (event: SyncEvent) => void): Promise<void>;
+//# sourceMappingURL=flush.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flush.d.ts","sourceRoot":"","sources":["../../src/core/flush.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EAEX,SAAS,EACV,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,wBAAsB,cAAc,CAClC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,WAAW,EAAE,EACtB,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAe,GAC1C,OAAO,CAAC,IAAI,CAAC,CAqGf"}

package/dist/core/flush.js

@@ -0,0 +1,98 @@
+/**
+ * Flush — push queued local outbox entries to remote cloud.
+ *
+ * Extracted from Interocitor. Not part of the public API.
+ */
+import { hlcCompareStr } from "./hlc.js";
+import { paths, textEncoder, textDecoder } from "./internals.js";
+import { encodeChangePayload } from "./codec.js";
+import { upsertDeviceMetadata } from "./manifest.js";
+export async function flushToAdapter(adapter, remotePath, entries, isPrimary, codecState, deviceId, emit = () => { }) {
+    const p = paths(remotePath);
+    await adapter.ensureFolder(p.changesFolder);
+    let lastWrittenHlc = '';
+    for (const entry of entries) {
+        const fileName = `${entry.hlc}-${entry.id}.json`;
+        const payload = await encodeChangePayload(codecState, entry);
+        console.log('[interocitor:write] flush.changeFile', { path: p.changeFile(fileName), deviceId, isPrimary, entryId: entry.id, hlc: entry.hlc });
+        await adapter.writeFile(p.changeFile(fileName), textEncoder.encode(payload));
+        if (!lastWrittenHlc || hlcCompareStr(entry.hlc, lastWrittenHlc) > 0) {
+            lastWrittenHlc = entry.hlc;
+        }
+    }
+    // Update global head — monotonic HLC hint for fast poll skipping.
+    // Tracing rules (see SyncEvent `trace:head`):
+    //  - read → emit { op: 'read', reason: 'flush', priorHlc }
+    //  - write strictly forward → emit { op: 'write', priorHlc, nextHlc }
+    //  - write where nextHlc <= priorHlc → emit
+    //    { op: 'write', regressed: true } AND skip the writeFile
+    //    (regression = bug signal; never let head go backwards on disk).
+    //  - no entries to flush → emit { op: 'skip-no-change' } and don't touch head.
+    if (!lastWrittenHlc) {
+        emit({
+            type: 'trace:head',
+            op: 'skip-no-change',
+            reason: 'flush',
+            path: p.changesHead,
+            nextHlc: null,
+        });
+        if (isPrimary) {
+            await upsertDeviceMetadata(adapter, remotePath, deviceId);
+        }
+        return;
+    }
+    const readHeadIfExists = async () => {
+        try {
+            const data = await adapter.readFile(p.changesHead);
+            return JSON.parse(textDecoder.decode(data));
+        }
+        catch {
+            return null;
+        }
+    };
+    const priorHead = await readHeadIfExists();
+    const priorHlc = priorHead?.latestHlc ?? null;
+    emit({
+        type: 'trace:head',
+        op: 'read',
+        reason: 'flush',
+        path: p.changesHead,
+        priorHlc,
+    });
+    // Already-current short-circuit. Nothing to write — head already at or
+    // beyond what we just wrote (replica catching up, retried flush, etc.).
+    if (priorHlc && hlcCompareStr(priorHlc, lastWrittenHlc) >= 0) {
+        emit({
+            type: 'trace:head',
+            op: 'skip-no-change',
+            reason: 'flush',
+            path: p.changesHead,
+            priorHlc,
+            nextHlc: lastWrittenHlc,
+        });
+        if (isPrimary) {
+            await upsertDeviceMetadata(adapter, remotePath, deviceId);
+        }
+        return;
+    }
+    // Defensive: if priorHlc somehow > our lastWritten (shouldn't happen
+    // after the >= short-circuit) flag as regression and don't write.
+    const regressed = priorHlc !== null && hlcCompareStr(priorHlc, lastWrittenHlc) > 0;
+    const bestHlc = regressed ? priorHlc : lastWrittenHlc;
+    emit({
+        type: 'trace:head',
+        op: 'write',
+        reason: 'flush',
+        path: p.changesHead,
+        priorHlc,
+        nextHlc: bestHlc,
+        regressed,
+    });
+    if (!regressed) {
+        console.log('[interocitor:write] flush.head', { path: p.changesHead, deviceId, isPrimary, priorHlc, nextHlc: bestHlc });
+        await adapter.writeFile(p.changesHead, textEncoder.encode(JSON.stringify({ latestHlc: bestHlc }, null, 2)));
+    }
+    if (isPrimary) {
+        await upsertDeviceMetadata(adapter, remotePath, deviceId);
+    }
+}

package/dist/core/hlc.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hybrid Logical Clock
+ *
+ * Combines wall-clock time with a logical counter to produce
+ * a total order across distributed devices without coordination.
+ *
+ * Format when serialized: "{ts}-{counter:04x}-{nodeId}"
+ * Example: "1711785600000-0000-dev_x1"
+ */
+import type { HLC } from './types.ts';
+export declare const HLC_MAX_FUTURE_SKEW_MS: number;
+export declare function hlcInit(nodeId: string): HLC;
+/** Tick the local clock forward for a new local event. */
+export declare function hlcNow(local: HLC): HLC;
+/** Merge a remote HLC into the local clock (called on receive). */
+export declare function hlcReceive(local: HLC, remote: HLC): HLC;
+/** Total ordering: -1 if a < b, 0 if equal, 1 if a > b */
+export declare function hlcCompare(a: HLC, b: HLC): number;
+/** Compare two serialized HLC strings without parsing (fast path). */
+export declare function hlcCompareStr(a: string, b: string): number;
+/** Serialize HLC to a string that sorts lexicographically. */
+export declare function hlcSerialize(hlc: HLC): string;
+/** Parse a serialized HLC string back to an HLC object. */
+export declare function hlcParse(s: string): HLC;
+//# sourceMappingURL=hlc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hlc.d.ts","sourceRoot":"","sources":["../../src/core/hlc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAGtC,eAAO,MAAM,sBAAsB,QAAgB,CAAC;AAEpD,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAE3C;AAED,0DAA0D;AAC1D,wBAAgB,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAMtC;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAG,GAAG,CAiBvD;AAED,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAMjD;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAK7C;AAED,2DAA2D;AAC3D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAQvC"}

package/dist/core/hlc.js

@@ -0,0 +1,75 @@
+/**
+ * Hybrid Logical Clock
+ *
+ * Combines wall-clock time with a logical counter to produce
+ * a total order across distributed devices without coordination.
+ *
+ * Format when serialized: "{ts}-{counter:04x}-{nodeId}"
+ * Example: "1711785600000-0000-dev_x1"
+ */
+// Guard against poisoned/misconfigured peers that report far-future clocks.
+export const HLC_MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
+export function hlcInit(nodeId) {
+    return { ts: Date.now(), counter: 0, nodeId };
+}
+/** Tick the local clock forward for a new local event. */
+export function hlcNow(local) {
+    const wall = Date.now();
+    if (wall > local.ts) {
+        return { ts: wall, counter: 0, nodeId: local.nodeId };
+    }
+    return { ts: local.ts, counter: local.counter + 1, nodeId: local.nodeId };
+}
+/** Merge a remote HLC into the local clock (called on receive). */
+export function hlcReceive(local, remote) {
+    const wall = Date.now();
+    const safeRemoteTs = Math.min(remote.ts, wall + HLC_MAX_FUTURE_SKEW_MS);
+    const maxTs = Math.max(wall, local.ts, safeRemoteTs);
+    let counter;
+    if (maxTs === local.ts && maxTs === remote.ts) {
+        counter = Math.max(local.counter, remote.counter) + 1;
+    }
+    else if (maxTs === local.ts) {
+        counter = local.counter + 1;
+    }
+    else if (maxTs === safeRemoteTs) {
+        counter = remote.counter + 1;
+    }
+    else {
+        counter = 0;
+    }
+    return { ts: maxTs, counter, nodeId: local.nodeId };
+}
+/** Total ordering: -1 if a < b, 0 if equal, 1 if a > b */
+export function hlcCompare(a, b) {
+    if (a.ts !== b.ts)
+        return a.ts - b.ts;
+    if (a.counter !== b.counter)
+        return a.counter - b.counter;
+    if (a.nodeId < b.nodeId)
+        return -1;
+    if (a.nodeId > b.nodeId)
+        return 1;
+    return 0;
+}
+/** Compare two serialized HLC strings without parsing (fast path). */
+export function hlcCompareStr(a, b) {
+    return hlcCompare(hlcParse(a), hlcParse(b));
+}
+/** Serialize HLC to a string that sorts lexicographically. */
+export function hlcSerialize(hlc) {
+    // Zero-pad ts to 15 digits (covers until year 2286)
+    const ts = hlc.ts.toString().padStart(15, '0');
+    const counter = hlc.counter.toString(16).padStart(4, '0');
+    return `${ts}-${counter}-${hlc.nodeId}`;
+}
+/** Parse a serialized HLC string back to an HLC object. */
+export function hlcParse(s) {
+    const firstDash = s.indexOf('-');
+    const secondDash = s.indexOf('-', firstDash + 1);
+    return {
+        ts: parseInt(s.slice(0, firstDash), 10),
+        counter: parseInt(s.slice(firstDash + 1, secondDash), 16),
+        nodeId: s.slice(secondDash + 1),
+    };
+}

package/dist/core/ids.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Structured ID generation and validation.
+ *
+ * Device IDs: UUIDv7 — timestamp + random, client-generated.
+ * Mesh IDs:   UUIDv7 + HMAC tag — timestamp + random + MAC, worker-issued.
+ * Row IDs:    UUID v4/v7 with optional prefix — client-generated.
+ */
+/**
+ * Generate a UUIDv7: 48-bit ms timestamp + 74 bits random, RFC 9562.
+ * Sortable by creation time. Globally unique without coordination.
+ */
+export declare function uuidv7(): string;
+/** Generate a device ID. UUIDv7 — sortable, globally unique. */
+export declare function createDeviceId(): string;
+/** Validate a device ID (must be UUIDv7). */
+export declare function isValidDeviceId(id: unknown): id is string;
+/**
+ * Issue a mesh/team ID with embedded HMAC tag.
+ *
+ * Layout (opaque string):
+ *   <uuidv7>.<tag>
+ *
+ * Where tag = base64url(HMAC-SHA256(secret, uuidv7))[0..10]
+ *
+ * Only workers with the secret can mint valid mesh IDs.
+ * Clients and workers validate with `isValidMeshId(id, secret)`.
+ *
+ * @param secret — HMAC key (CryptoKey or raw bytes). Workers hold this.
+ */
+export declare function issueMeshId(secret: CryptoKey): Promise<string>;
+/**
+ * Validate a mesh ID: format check + HMAC tag verification.
+ *
+ * @param id     — the full mesh ID string (uuid.tag)
+ * @param secret — same HMAC key used to issue
+ */
+export declare function isValidMeshId(id: unknown, secret: CryptoKey): Promise<boolean>;
+/**
+ * Parse a mesh ID into its parts. Does NOT verify tag.
+ */
+export declare function parseMeshId(id: string): {
+    uuid: string;
+    tag: string;
+} | null;
+/**
+ * Create a mesh HMAC secret key for use with issueMeshId / isValidMeshId.
+ */
+export declare function createMeshSecret(): Promise<CryptoKey>;
+//# sourceMappingURL=ids.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/core/ids.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;GAGG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAiC/B;AAID,gEAAgE;AAChE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAID,6CAA6C;AAC7C,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAEzD;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAIpE;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CASpF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO5E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,SAAS,CAAC,CAM3D"}

package/dist/core/ids.js

@@ -0,0 +1,132 @@
+/**
+ * Structured ID generation and validation.
+ *
+ * Device IDs: UUIDv7 — timestamp + random, client-generated.
+ * Mesh IDs:   UUIDv7 + HMAC tag — timestamp + random + MAC, worker-issued.
+ * Row IDs:    UUID v4/v7 with optional prefix — client-generated.
+ */
+// ─── UUIDv7 ──────────────────────────────────────────────────────────
+/**
+ * Generate a UUIDv7: 48-bit ms timestamp + 74 bits random, RFC 9562.
+ * Sortable by creation time. Globally unique without coordination.
+ */
+export function uuidv7() {
+    const now = Date.now();
+    // 6 bytes timestamp (48-bit ms)
+    const tsBytes = new Uint8Array(6);
+    let ts = now;
+    for (let i = 5; i >= 0; i--) {
+        tsBytes[i] = ts & 0xff;
+        ts = Math.floor(ts / 256);
+    }
+    // 10 bytes random
+    const randBytes = crypto.getRandomValues(new Uint8Array(10));
+    // Assemble 16 bytes
+    const bytes = new Uint8Array(16);
+    bytes.set(tsBytes, 0);
+    bytes.set(randBytes, 6);
+    // Set version 7 (bits 48-51)
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    // Set variant 10xx (bits 64-65)
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    // Format as UUID string
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32),
+    ].join('-');
+}
+// ─── Device IDs ──────────────────────────────────────────────────────
+/** Generate a device ID. UUIDv7 — sortable, globally unique. */
+export function createDeviceId() {
+    return uuidv7();
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Validate a device ID (must be UUIDv7). */
+export function isValidDeviceId(id) {
+    return typeof id === 'string' && UUID_RE.test(id);
+}
+// ─── Mesh / Team IDs ─────────────────────────────────────────────────
+/**
+ * Issue a mesh/team ID with embedded HMAC tag.
+ *
+ * Layout (opaque string):
+ *   <uuidv7>.<tag>
+ *
+ * Where tag = base64url(HMAC-SHA256(secret, uuidv7))[0..10]
+ *
+ * Only workers with the secret can mint valid mesh IDs.
+ * Clients and workers validate with `isValidMeshId(id, secret)`.
+ *
+ * @param secret — HMAC key (CryptoKey or raw bytes). Workers hold this.
+ */
+export async function issueMeshId(secret) {
+    const id = uuidv7();
+    const tag = await computeTag(id, secret);
+    return `${id}.${tag}`;
+}
+/**
+ * Validate a mesh ID: format check + HMAC tag verification.
+ *
+ * @param id     — the full mesh ID string (uuid.tag)
+ * @param secret — same HMAC key used to issue
+ */
+export async function isValidMeshId(id, secret) {
+    if (typeof id !== 'string')
+        return false;
+    const dot = id.lastIndexOf('.');
+    if (dot === -1)
+        return false;
+    const uuid = id.slice(0, dot);
+    const tag = id.slice(dot + 1);
+    if (!UUID_RE.test(uuid) || !tag)
+        return false;
+    const expected = await computeTag(uuid, secret);
+    return timingSafeEqual(tag, expected);
+}
+/**
+ * Parse a mesh ID into its parts. Does NOT verify tag.
+ */
+export function parseMeshId(id) {
+    const dot = id.lastIndexOf('.');
+    if (dot === -1)
+        return null;
+    const uuid = id.slice(0, dot);
+    const tag = id.slice(dot + 1);
+    if (!UUID_RE.test(uuid) || !tag)
+        return null;
+    return { uuid, tag };
+}
+/**
+ * Create a mesh HMAC secret key for use with issueMeshId / isValidMeshId.
+ */
+export async function createMeshSecret() {
+    return crypto.subtle.generateKey({ name: 'HMAC', hash: 'SHA-256' }, true, ['sign', 'verify']);
+}
+// ─── Internal helpers ────────────────────────────────────────────────
+const encoder = new TextEncoder();
+async function computeTag(data, secret) {
+    const sig = await crypto.subtle.sign('HMAC', secret, encoder.encode(data));
+    // Take first 8 bytes (64 bits) → base64url (11 chars)
+    const bytes = new Uint8Array(sig, 0, 8);
+    return base64url(bytes);
+}
+function base64url(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCodePoint(bytes[i]);
+    return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');
+}
+/** Constant-time string comparison to prevent timing attacks on tag. */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.codePointAt(i) ^ b.codePointAt(i);
+    }
+    return result === 0;
+}

package/dist/core/internals.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Internal helpers shared across sync-engine modules.
+ *
+ * Not part of the public API.
+ */
+export interface CloudPaths {
+    manifestPointer: string;
+    manifestFile: (generation: number) => string;
+    devicesFolder: string;
+    deviceFile: (deviceId: string) => string;
+    mainlineFolder: string;
+    changesFolder: string;
+    changesHead: string;
+    changeFile: (fileName: string) => string;
+}
+export declare function paths(root: string): CloudPaths;
+declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+export declare function logAtLevel(currentLevel: LogLevel, level: LogLevel, ...args: unknown[]): void;
+export declare function log(level: LogLevel, ...args: unknown[]): void;
+export declare function normalizeLogLevel(level: string | null | undefined): LogLevel;
+export { LOG_LEVELS };
+/**
+ * Generate a prefixed ID for internal use (change entries, snapshots, etc).
+ * Uses UUIDv7 for sortability.
+ */
+export declare function generateId(prefix: string): string;
+export declare function getDeviceId(override?: string): string;
+export declare const textEncoder: TextEncoder;
+export declare const textDecoder: TextDecoder;
+export declare function hexFromBytes(bytes: Uint8Array): string;
+export declare function computeContentHash(payload: unknown): Promise<string>;
+//# sourceMappingURL=internals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.ts","sourceRoot":"","sources":["../../src/core/internals.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1C;AAED,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAY9C;AAKD,QAAA,MAAM,UAAU,6CAA8C,CAAC;AAE/D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAMnD,wBAAgB,UAAU,CAAC,YAAY,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAI5F;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAE7D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,CAE5E;AAED,OAAO,EAAE,UAAU,EAAE,CAAC;AAOtB;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAUrD;AAID,eAAO,MAAM,WAAW,aAAoB,CAAC;AAC7C,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEtD;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAI1E"}

package/dist/core/internals.js

@@ -0,0 +1,72 @@
+/**
+ * Internal helpers shared across sync-engine modules.
+ *
+ * Not part of the public API.
+ */
+export function paths(root) {
+    const changesFolder = `${root}/changes`;
+    return {
+        manifestPointer: `${root}/manifest.json`,
+        manifestFile: (generation) => `${root}/manifest-${generation}.json`,
+        devicesFolder: `${root}/devices`,
+        deviceFile: (deviceId) => `${root}/devices/${deviceId}.json`,
+        mainlineFolder: `${root}/mainline`,
+        changesFolder,
+        changesHead: `${changesFolder}/head.json`,
+        changeFile: (fileName) => `${changesFolder}/${fileName}`,
+    };
+}
+// ─── Logger ──────────────────────────────────────────────────────────
+const LOG_PREFIX = '[interocitor]';
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+function shouldLog(currentLevel, messageLevel) {
+    return LOG_LEVELS.indexOf(messageLevel) >= LOG_LEVELS.indexOf(currentLevel);
+}
+export function logAtLevel(currentLevel, level, ...args) {
+    if (!shouldLog(currentLevel, level))
+        return;
+    // eslint-disable-next-line no-console
+    console[level](LOG_PREFIX, ...args);
+}
+export function log(level, ...args) {
+    logAtLevel('debug', level, ...args);
+}
+export function normalizeLogLevel(level) {
+    return LOG_LEVELS.includes(level ?? '') ? level : 'info';
+}
+export { LOG_LEVELS };
+// ─── ID generation ───────────────────────────────────────────────────
+import { uuidv7, createDeviceId } from "./ids.js";
+/**
+ * Generate a prefixed ID for internal use (change entries, snapshots, etc).
+ * Uses UUIDv7 for sortability.
+ */
+export function generateId(prefix) {
+    return `${prefix}_${uuidv7()}`;
+}
+export function getDeviceId(override) {
+    if (override)
+        return override;
+    const KEY = 'interocitor-device-id';
+    const storage = typeof localStorage === 'undefined' ? null : localStorage;
+    let id = storage?.getItem(KEY) ?? null;
+    if (!id) {
+        id = createDeviceId();
+        try {
+            storage?.setItem(KEY, id);
+        }
+        catch { /* ok */ }
+    }
+    return id;
+}
+// ─── Encoding / Hashing ─────────────────────────────────────────────
+export const textEncoder = new TextEncoder();
+export const textDecoder = new TextDecoder();
+export function hexFromBytes(bytes) {
+    return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+export async function computeContentHash(payload) {
+    const json = JSON.stringify(payload);
+    const digest = await crypto.subtle.digest('SHA-256', textEncoder.encode(json));
+    return `sha256:${hexFromBytes(new Uint8Array(digest))}`;
+}

package/dist/core/manifest.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Manifest — reading, writing, creating, and validating cloud manifests.
+ *
+ * Extracted from Interocitor. Not part of the public API.
+ */
+import type { StorageAdapter, Manifest, ManifestPointer, DatabaseSchemaDefinition, SyncEvent } from './types.ts';
+import type { CodecState } from './codec.ts';
+export interface ManifestContext {
+    adapter: StorageAdapter;
+    remotePath: string;
+    serverId: string;
+    serverManaged: boolean;
+    deviceId: string;
+    encrypted: boolean;
+    schema?: DatabaseSchemaDefinition;
+    emit: (event: SyncEvent) => void;
+}
+export declare function readJson<T>(adapter: StorageAdapter, path: string): Promise<T>;
+export declare function readJsonIfExists<T>(adapter: StorageAdapter, path: string): Promise<T | null>;
+export declare function assertServerAuth(manifest: {
+    writtenBy: string;
+}, serverId: string): void;
+export declare function validateManifestHash(manifest: {
+    contentHash: string;
+    [key: string]: unknown;
+}): Promise<void>;
+export declare function writeJson(adapter: StorageAdapter, path: string, value: unknown): Promise<void>;
+export declare function createBootstrapManifest(ctx: ManifestContext, meshId?: string): Promise<{
+    pointer: ManifestPointer;
+    manifest: Manifest;
+}>;
+export declare function loadOrCreateManifest(ctx: ManifestContext, codecState: CodecState, local: import('./types.ts').LocalStoreAdapter, poisonRemote: (error: unknown, path?: string) => Promise<Error>, reason?: string): Promise<{
+    manifest: Manifest;
+    bootstrapped: boolean;
+}>;
+export declare function upsertDeviceMetadata(adapter: StorageAdapter, remotePath: string, deviceId: string, opts?: {
+    displayName?: string;
+    deviceType?: import('./types.ts').DeviceType;
+    observedManifestGeneration?: number;
+    observedEpoch?: number;
+    observedWatermarkHlc?: string;
+    observedGcFloorHlc?: string;
+    /**
+     * When true, skip the read-merge step. Use only when the caller knows
+     * no prior device record exists (e.g. immediately after bootstrap of
+     * a fresh mesh). Saves one round-trip per connect on first run.
+     */
+    bootstrap?: boolean;
+    /**
+     * When true, preserve existing timestamps and skip the write entirely if
+     * the merged metadata would be identical. Use for reconnect acknowledgements
+     * where observability matters more than heartbeats.
+     */
+    skipTouchIfUnchanged?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/core/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,eAAe,EAEf,wBAAwB,EACxB,SAAS,EACV,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAClC;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAGnF;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAMlG;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIxF;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GACxD,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpG;AAED,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,eAAe,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,CAsD3D;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,eAAe,EACpB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,OAAO,YAAY,EAAE,iBAAiB,EAC7C,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,EAC/D,MAAM,GAAE,MAAkB,GACzB,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC,CA2DxD;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE;IACL,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,YAAY,EAAE,UAAU,CAAC;IAC7C,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,GACA,OAAO,CAAC,IAAI,CAAC,CAyDf"}