@interocitor/core 0.0.0-beta.3 → 0.0.0-beta.5

package/dist/core/crdt.js

@@ -10,10 +10,12 @@
  *  - 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";
-/** Reserved keys that are not user columns */
-const META_KEYS = new Set(['_table', '_rowId', '_deleted', '_deletedHlc', '_schemaVersion']);
 /**
  * Resolve the merge strategy for a specific column.
  *
@@ -25,7 +27,6 @@ function resolveStrategy(schema, table, field) {
     if (tableDef?.merge) {
         const m = tableDef.merge;
         if (typeof m === 'object' && 'fields' in m) {
-            // TableMergeConfig
             const config = m;
             if (config.fields?.[field])
                 return config.fields[field];
@@ -33,12 +34,9 @@ function resolveStrategy(schema, table, field) {
                 return config.strategy;
         }
         else {
-            // bare MergeStrategy (string or function) on the table
             return m;
         }
     }
-    // No schema at all → LWW (backwards compat for raw applyOp callers).
-    // Schema present but no mergeStrategy → remote-wins (sensible default).
     if (!schema)
         return 'lww';
     return schema.mergeStrategy ?? 'remote-wins';
@@ -50,26 +48,28 @@ function resolveStrategy(schema, table, field) {
  * regardless of strategy — there's no conflict.
  */
 function mergeColumn(local, remote, strategy, table, rowId, field) {
-    // No local value → accept remote unconditionally
     if (!local || !local.hlc)
         return remote;
     if (typeof strategy === 'function') {
         const result = strategy(local, remote, { table, rowId, field });
-        // Only count as changed if the result differs from local
         return result.hlc !== local.hlc || result.value !== local.value ? result : null;
     }
     switch (strategy) {
         case 'remote-wins':
             return remote;
         case 'local-wins':
-            // Only accept remote if it's strictly newer (no conflict — local
-            // hasn't written this column yet at this HLC).
-            // When both have values, local keeps its value.
             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.
@@ -82,63 +82,58 @@ export function applyOp(tables, op, schemaVersion, schema) {
     if (op.type === 'delete') {
         const existing = table[op.rowId];
         if (existing) {
-            // Only apply delete if its HLC is newer than all column HLCs
-            if (existing._deletedHlc && hlcCompareStr(op.hlc, existing._deletedHlc) <= 0) {
-                return null; // stale delete
+            // Stale delete (older than current tombstone)?
+            if (existing._meta.deletedHlc && hlcCompareStr(op.hlc, existing._meta.deletedHlc) <= 0) {
+                return null;
             }
-            // Check if any column has a newer HLC than this delete
-            const hasNewerColumn = Object.entries(existing).some(([key, val]) => {
-                if (META_KEYS.has(key))
-                    return false;
-                const entry = val;
+            // 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._deleted = true;
-            existing._deletedHlc = op.hlc;
+            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 a row we haven't seen — create it
-        const row = {
-            _table: op.table,
-            _rowId: op.rowId,
-            _deleted: true,
-            _deletedHlc: op.hlc,
-            _schemaVersion: schemaVersion,
-        };
+        // Tombstone for unseen row.
+        const row = blankRow(op.table, op.rowId, schemaVersion, true, op.hlc);
         table[op.rowId] = row;
         return row;
     }
-    // Upsert
+    // Upsert.
     let row = table[op.rowId];
     let changed = false;
     if (!row) {
-        row = {
-            _table: op.table,
-            _rowId: op.rowId,
-            _deleted: false,
-            _schemaVersion: schemaVersion,
-        };
+        row = blankRow(op.table, op.rowId, schemaVersion);
         table[op.rowId] = row;
         changed = true;
     }
-    for (const [col, entry] of Object.entries(op.columns)) {
-        const existing = row[col];
+    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[col] = winner;
-            changed = true;
-        }
-    }
-    // An upsert that's newer than a delete revives the row
-    if (row._deleted && row._deletedHlc) {
-        const newestOpHlc = Object.values(op.columns).reduce((max, entry) => {
-            return !max || hlcCompareStr(entry.hlc, max) > 0 ? entry.hlc : max;
-        }, '');
-        if (newestOpHlc && hlcCompareStr(newestOpHlc, row._deletedHlc) > 0) {
-            row._deleted = false;
+            row.payload[col] = winner;
             changed = true;
         }
     }
@@ -157,32 +152,23 @@ export function applyChangeEntry(tables, entry, schemaVersion, schema) {
     }
     return affected;
 }
-/**
- * Read a column value from a row, unwrapping the ColumnEntry.
- */
+/** Read a column value from a row, unwrapping the ColumnEntry. */
 export function readColumn(row, column) {
-    const entry = row[column];
-    if (entry && typeof entry === 'object' && 'value' in entry && 'hlc' in entry) {
-        return entry.value;
-    }
-    return undefined;
+    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._table,
-        _rowId: row._rowId,
-        _deleted: row._deleted,
+        _table: row._meta.table,
+        _rowId: row._meta.rowId,
+        _deleted: row._meta.deleted,
     };
-    for (const [key, val] of Object.entries(row)) {
-        if (META_KEYS.has(key))
-            continue;
-        if (val && typeof val === 'object' && 'value' in val && 'hlc' in val) {
-            result[key] = val.value;
-        }
+    for (const [key, entry] of Object.entries(row.payload)) {
+        result[key] = entry.value;
     }
     return result;
 }
-//# sourceMappingURL=crdt.js.map

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;
+    }
+}

package/dist/core/flush.d.ts

@@ -1,9 +1,9 @@
 /**
  * Flush — push queued local outbox entries to remote cloud.
  *
- * Extracted from SyncEngine. Not part of the public API.
+ * Extracted from Interocitor. Not part of the public API.
  */
-import type { StorageAdapter, ChangeEntry } from './types.ts';
+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): Promise<void>;
+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

@@ -1 +1 @@
-{"version":3,"file":"flush.d.ts","sourceRoot":"","sources":["../../src/core/flush.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EAEZ,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,GACf,OAAO,CAAC,IAAI,CAAC,CAsCf"}
+{"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

@@ -1,25 +1,46 @@
 /**
  * Flush — push queued local outbox entries to remote cloud.
  *
- * Extracted from SyncEngine. Not part of the public API.
+ * 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) {
+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);
@@ -30,12 +51,48 @@ export async function flushToAdapter(adapter, remotePath, entries, isPrimary, co
         }
     };
     const priorHead = await readHeadIfExists();
-    const bestHlc = (priorHead?.latestHlc && hlcCompareStr(priorHead.latestHlc, lastWrittenHlc) > 0)
-        ? priorHead.latestHlc
-        : lastWrittenHlc;
-    await adapter.writeFile(p.changesHead, textEncoder.encode(JSON.stringify({ latestHlc: bestHlc }, null, 2)));
+    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);
     }
 }
-//# sourceMappingURL=flush.js.map

package/dist/core/hlc.js

@@ -73,4 +73,3 @@ export function hlcParse(s) {
         nodeId: s.slice(secondDash + 1),
     };
 }
-//# sourceMappingURL=hlc.js.map

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.fromCharCode(bytes[i]);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').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.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}

package/dist/core/internals.d.ts

@@ -14,12 +14,20 @@ export interface CloudPaths {
     changeFile: (fileName: string) => string;
 }
 export declare function paths(root: string): CloudPaths;
-export declare function log(level: 'debug' | 'info' | 'warn' | 'error', ...args: unknown[]): void;
+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 const ROW_META_KEYS: Set<string>;
 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

@@ -1 +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;AAMD,wBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAGxF;AAID,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED,wBAAgB,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CASrD;AAID,eAAO,MAAM,WAAW,aAAoB,CAAC;AAC7C,eAAO,MAAM,WAAW,aAAoB,CAAC;AAE7C,eAAO,MAAM,aAAa,aAA6E,CAAC;AAExG,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAEtD;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAI1E"}
+{"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"}