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

package/dist/core/internals.js

@@ -18,31 +18,50 @@ export function paths(root) {
 }
 // ─── Logger ──────────────────────────────────────────────────────────
 const LOG_PREFIX = '[interocitor]';
-export function log(level, ...args) {
+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) {
-    const rand = crypto.getRandomValues(new Uint8Array(8));
-    const hex = Array.from(rand).map(b => b.toString(16).padStart(2, '0')).join('');
-    return `${prefix}_${hex}`;
+    return `${prefix}_${uuidv7()}`;
 }
 export function getDeviceId(override) {
     if (override)
         return override;
     const KEY = 'interocitor-device-id';
-    let id = localStorage.getItem(KEY);
+    const storage = typeof localStorage !== 'undefined' ? localStorage : null;
+    let id = storage?.getItem(KEY) ?? null;
     if (!id) {
-        id = generateId('dev');
-        localStorage.setItem(KEY, 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 const ROW_META_KEYS = new Set(['_table', '_rowId', '_deleted', '_deletedHlc', '_schemaVersion']);
 export function hexFromBytes(bytes) {
     return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
 }
@@ -51,4 +70,3 @@ export async function computeContentHash(payload) {
     const digest = await crypto.subtle.digest('SHA-256', textEncoder.encode(json));
     return `sha256:${hexFromBytes(new Uint8Array(digest))}`;
 }
-//# sourceMappingURL=internals.js.map

package/dist/core/manifest.d.ts

@@ -1,9 +1,9 @@
 /**
  * Manifest — reading, writing, creating, and validating cloud manifests.
  *
- * Extracted from SyncEngine. Not part of the public API.
+ * Extracted from Interocitor. Not part of the public API.
  */
-import type { StorageAdapter, Manifest, DatabaseSchemaDefinition, SyncEvent } from './types.ts';
+import type { StorageAdapter, Manifest, ManifestPointer, DatabaseSchemaDefinition, SyncEvent } from './types.ts';
 import type { CodecState } from './codec.ts';
 export interface ManifestContext {
     adapter: StorageAdapter;
@@ -25,7 +25,22 @@ export declare function validateManifestHash(manifest: {
     [key: string]: unknown;
 }): Promise<void>;
 export declare function writeJson(adapter: StorageAdapter, path: string, value: unknown): Promise<void>;
-export declare function createBootstrapManifest(ctx: ManifestContext): Promise<void>;
-export declare function loadOrCreateManifest(ctx: ManifestContext, codecState: CodecState, local: import('./types.ts').LocalStoreAdapter, poisonRemote: (error: unknown, path?: string) => Promise<Error>): Promise<Manifest>;
-export declare function upsertDeviceMetadata(adapter: StorageAdapter, remotePath: string, deviceId: string): Promise<void>;
+export declare function createBootstrapManifest(ctx: ManifestContext): 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;
+    /**
+     * 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;
+}): Promise<void>;
 //# sourceMappingURL=manifest.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/core/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EAGR,wBAAwB,EACxB,SAAS,EACV,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,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,CAEpG;AAED,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAqCjF;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,GAC9D,OAAO,CAAC,QAAQ,CAAC,CA8BnB;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAaf"}
+{"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,GACnB,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,CA0DxD;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;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GACA,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/core/manifest.js

@@ -1,10 +1,11 @@
 /**
  * Manifest — reading, writing, creating, and validating cloud manifests.
  *
- * Extracted from SyncEngine. Not part of the public API.
+ * Extracted from Interocitor. Not part of the public API.
  */
 import { paths, textEncoder, textDecoder, generateId, computeContentHash } from "./internals.js";
 import { assertExpectedMeshId } from "./codec.js";
+import { MeshEncryptionMismatchError } from "./errors.js";
 export async function readJson(adapter, path) {
     const data = await adapter.readFile(path);
     return JSON.parse(textDecoder.decode(data));
@@ -30,6 +31,7 @@ export async function validateManifestHash(manifest) {
     }
 }
 export async function writeJson(adapter, path, value) {
+    console.log('[interocitor:write] manifest.writeJson', { path, kind: path.endsWith('/manifest.json') ? 'pointer' : path.includes('/manifest-') ? 'manifest' : path.includes('/devices/') ? 'device' : path.includes('/changes/') ? 'changes' : 'other' });
     await adapter.writeFile(path, textEncoder.encode(JSON.stringify(value, null, 2)));
 }
 export async function createBootstrapManifest(ctx) {
@@ -60,21 +62,51 @@ export async function createBootstrapManifest(ctx) {
         contentHash: await computeContentHash(payload),
     };
     const manifestFile = `manifest-${manifest.generation}.json`;
-    await writeJson(ctx.adapter, p.manifestFile(manifest.generation), manifest);
-    await writeJson(ctx.adapter, p.manifestPointer, {
+    const pointer = {
         currentGeneration: manifest.generation,
         file: manifestFile,
+    };
+    await writeJson(ctx.adapter, p.manifestFile(manifest.generation), manifest);
+    ctx.emit({
+        type: 'trace:manifest',
+        op: 'write',
+        reason: 'bootstrap',
+        generation: manifest.generation,
+        path: p.manifestFile(manifest.generation),
     });
+    await writeJson(ctx.adapter, p.manifestPointer, pointer);
+    ctx.emit({
+        type: 'trace:manifest',
+        op: 'write',
+        reason: 'bootstrap-pointer',
+        generation: manifest.generation,
+        path: p.manifestPointer,
+    });
+    return { pointer, manifest };
 }
-export async function loadOrCreateManifest(ctx, codecState, local, poisonRemote) {
+export async function loadOrCreateManifest(ctx, codecState, local, poisonRemote, reason = 'unknown') {
     const p = paths(ctx.remotePath);
+    ctx.emit({ type: 'trace:manifest', op: 'read', reason, path: p.manifestPointer });
     const globalPointer = await readJsonIfExists(ctx.adapter, p.manifestPointer);
+    let pointer;
+    let manifest;
+    let bootstrapped = false;
     if (!globalPointer) {
-        await createBootstrapManifest(ctx);
+        bootstrapped = true;
+        ctx.emit({ type: 'trace:manifest', op: 'bootstrap-create', reason, path: p.manifestPointer });
+        const bootstrap = await createBootstrapManifest(ctx);
+        // Skip the read-after-write — we just minted both files in this process,
+        // they are exactly what's on disk. No GETs needed.
+        pointer = bootstrap.pointer;
+        manifest = bootstrap.manifest;
+    }
+    else {
+        pointer = globalPointer;
+        const manifestPath = `${ctx.remotePath}/${pointer.file}`;
+        ctx.emit({ type: 'trace:manifest', op: 'read', reason, path: manifestPath, generation: pointer.currentGeneration });
+        manifest = await readJson(ctx.adapter, manifestPath);
     }
-    const pointer = await readJson(ctx.adapter, p.manifestPointer);
     const manifestPath = `${ctx.remotePath}/${pointer.file}`;
-    const manifest = await readJson(ctx.adapter, manifestPath);
     await validateManifestHash(manifest);
     try {
         await assertExpectedMeshId(local, codecState.manifest, manifest.meshId);
@@ -92,20 +124,42 @@ export async function loadOrCreateManifest(ctx, codecState, local, poisonRemote)
     if (manifest.server.managed) {
         assertServerAuth(manifest, ctx.serverId);
     }
-    return manifest;
+    // Encryption-mode parity check.
+    //
+    // The remote manifest pins the mesh's encryption mode at bootstrap.
+    // If the engine reconnects with a different `encrypted` flag (typical
+    // app bug: passphrase loaded asynchronously, so the first session
+    // wrote plaintext and the next session derives a key and tries to
+    // decrypt), every change file would fail decode and poison the remote.
+    //
+    // Surface this as an actionable error *before* any decode runs and
+    // *without* poisoning. The remote is not corrupt — the local config
+    // is wrong.
+    if (typeof manifest.encrypted === 'boolean' && manifest.encrypted !== ctx.encrypted) {
+        throw new MeshEncryptionMismatchError(manifest.encrypted, ctx.encrypted);
+    }
+    return { manifest, bootstrapped };
 }
-export async function upsertDeviceMetadata(adapter, remotePath, deviceId) {
+export async function upsertDeviceMetadata(adapter, remotePath, deviceId, opts) {
     const p = paths(remotePath);
     const now = new Date().toISOString();
-    const existing = await readJsonIfExists(adapter, p.deviceFile(deviceId));
+    // Bootstrap fast-path: caller asserts no prior record. Skip the GET.
+    // Worst case if caller is wrong: we clobber displayName/deviceType the
+    // user set on a different device — which would itself indicate the
+    // bootstrap flag was misused. Sync engine only sets bootstrap=true
+    // when it just minted the manifest in this same connect cycle.
+    const existing = opts?.bootstrap
+        ? null
+        : await readJsonIfExists(adapter, p.deviceFile(deviceId));
     const next = {
         deviceId,
         registeredAt: existing?.registeredAt ?? now,
         lastSeenAt: now,
         userId: existing?.userId,
         name: existing?.name,
+        displayName: opts?.displayName ?? existing?.displayName,
+        deviceType: opts?.deviceType ?? existing?.deviceType,
         retired: existing?.retired,
     };
     await writeJson(adapter, p.deviceFile(deviceId), next);
 }
-//# sourceMappingURL=manifest.js.map

package/dist/core/pull.d.ts

@@ -1,7 +1,7 @@
 /**
  * Pull — download remote changes and merge into local state.
  *
- * Extracted from SyncEngine. Not part of the public API.
+ * Extracted from Interocitor. Not part of the public API.
  */
 import type { StorageAdapter, LocalStoreAdapter, Row, Op, SyncEvent, DatabaseSchemaDefinition } from './types.ts';
 import type { HLC } from './types.ts';

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

@@ -1 +1 @@
-{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../src/core/pull.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,GAAG,EACH,EAAE,EAEF,SAAS,EACT,wBAAwB,EACzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAKtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5C,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACjC,gBAAgB,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IAChE,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAiBD,0CAA0C;AAC1C,wBAAsB,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAiFzD"}
+{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../src/core/pull.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,GAAG,EACH,EAAE,EAEF,SAAS,EACT,wBAAwB,EACzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAKtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;IACvB,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5C,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACjC,gBAAgB,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,YAAY,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;IAChE,oBAAoB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAiBD,0CAA0C;AAC1C,wBAAsB,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAiGzD"}

package/dist/core/pull.js

@@ -1,7 +1,7 @@
 /**
  * Pull — download remote changes and merge into local state.
  *
- * Extracted from SyncEngine. Not part of the public API.
+ * Extracted from Interocitor. Not part of the public API.
  */
 import { hlcParse, hlcReceive, hlcCompareStr, hlcSerialize } from "./hlc.js";
 import { applyChangeEntry } from "./crdt.js";
@@ -10,12 +10,12 @@ import { decodeChangePayload } from "./codec.js";
 import { readJsonIfExists } from "./manifest.js";
 function emitAffectedRows(affected, knownTables, emit) {
     for (const row of affected) {
-        knownTables.add(row._table);
-        if (row._deleted) {
-            emit({ type: 'delete', table: row._table, rowId: row._rowId });
+        knownTables.add(row._meta.table);
+        if (row._meta.deleted) {
+            emit({ type: 'delete', table: row._meta.table, rowId: row._meta.rowId });
         }
         else {
-            emit({ type: 'change', table: row._table, rowId: row._rowId, row });
+            emit({ type: 'change', table: row._meta.table, rowId: row._meta.rowId, row });
         }
     }
 }
@@ -32,8 +32,23 @@ export async function pull(ctx) {
         const cursor = typeof cursorRaw === 'string' ? cursorRaw : '';
         // Fast path: if global head hasn't advanced past cursor, skip listing.
         const head = await readJsonIfExists(adapter, p.changesHead);
+        emit({
+            type: 'trace:head',
+            op: 'read',
+            reason: 'pull-fast-path',
+            path: p.changesHead,
+            priorHlc: head?.latestHlc ?? null,
+        });
         if (head?.latestHlc && cursor && hlcCompareStr(head.latestHlc, cursor) <= 0) {
             log('debug', 'pull() — head unchanged, skipping');
+            emit({
+                type: 'trace:head',
+                op: 'skip-no-change',
+                reason: 'pull-fast-path',
+                path: p.changesHead,
+                priorHlc: head.latestHlc,
+                nextHlc: cursor,
+            });
             emit({ type: 'sync:complete', entriesMerged: 0 });
             return hlc;
         }
@@ -78,6 +93,7 @@ export async function pull(ctx) {
                 }
             }
             catch (err) {
+                emit({ type: 'decode:error', error: err instanceof Error ? err : new Error(String(err)), path: file.path, context: { stage: 'pull', name: file.name } });
                 throw await ctx.poisonRemote(err, file.path);
             }
         }
@@ -95,4 +111,3 @@ export async function pull(ctx) {
         throw err;
     }
 }
-//# sourceMappingURL=pull.js.map

package/dist/core/row-id.js

@@ -9,4 +9,3 @@ export function createRowId(options = {}) {
         : `${randomHex(8)}-${randomHex(4)}-${randomHex(4)}-${randomHex(4)}-${randomHex(12)}`;
     return options.prefix ? `${options.prefix}_${base}` : base;
 }
-//# sourceMappingURL=row-id.js.map

package/dist/core/schema-types.d.ts

@@ -1,15 +1,26 @@
-import type { IndexableSchemaField, SchemaField } from './types.ts';
+import type { IndexableSchemaField, OptionalSchemaField, SchemaField } from './types.ts';
+type BaseField<T, K extends import('./types.ts').SchemaFieldKind> = SchemaField<T, K> & {
+    readonly optional: OptionalSchemaField<T, K>;
+};
+type BaseIndexableField<T> = IndexableSchemaField<T> & {
+    readonly optional: OptionalSchemaField<T, import('./types.ts').IndexableSchemaFieldKind>;
+};
 export declare const types: {
-    string: IndexableSchemaField<string>;
-    number: IndexableSchemaField<number>;
-    boolean: IndexableSchemaField<boolean>;
-    date: IndexableSchemaField<Date>;
-    Date: IndexableSchemaField<Date>;
-    json: SchemaField<unknown>;
+    string: BaseIndexableField<string>;
+    number: BaseIndexableField<number>;
+    boolean: BaseIndexableField<boolean>;
+    date: BaseIndexableField<Date>;
+    Date: BaseIndexableField<Date>;
+    json: BaseField<unknown, "json">;
     /** Type a JSON field explicitly: `types.typed<MyType[]>('json')` */
-    typed<T>(kind: "json"): SchemaField<T>;
-    enum<const T extends string>(..._values: T[]): IndexableSchemaField<T>;
-    index<T>(field: IndexableSchemaField<T>): IndexableSchemaField<T>;
-    unique<T>(field: IndexableSchemaField<T>): IndexableSchemaField<T>;
+    typed<T>(kind: "json"): BaseField<T, "json">;
+    enum<const T extends string>(..._values: T[]): BaseIndexableField<T>;
+    index<T>(field: IndexableSchemaField<T> & {
+        __optional?: never;
+    }): IndexableSchemaField<T>;
+    unique<T>(field: IndexableSchemaField<T> & {
+        __optional?: never;
+    }): IndexableSchemaField<T>;
 };
+export {};
 //# sourceMappingURL=schema-types.d.ts.map

package/dist/core/schema-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-types.d.ts","sourceRoot":"","sources":["../../src/core/schema-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpE,eAAO,MAAM,KAAK;YACgB,oBAAoB,CAAC,MAAM,CAAC;YAC5B,oBAAoB,CAAC,MAAM,CAAC;aAC5B,oBAAoB,CAAC,OAAO,CAAC;UAC7B,oBAAoB,CAAC,IAAI,CAAC;UAC1B,oBAAoB,CAAC,IAAI,CAAC;UAC1B,WAAW,CAAC,OAAO,CAAC;IAEpD,oEAAoE;UAC9D,CAAC,QAAQ,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC;eAI3B,CAAC,SAAS,MAAM,cAAc,CAAC,EAAE,GAAG,oBAAoB,CAAC,CAAC,CAAC;UAIhE,CAAC,SAAS,oBAAoB,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC;WAI1D,CAAC,SAAS,oBAAoB,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC;CAGnE,CAAC"}
+{"version":3,"file":"schema-types.d.ts","sourceRoot":"","sources":["../../src/core/schema-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzF,KAAK,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,YAAY,EAAE,eAAe,IAAI,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IACtF,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC9C,CAAC;AAEF,KAAK,kBAAkB,CAAC,CAAC,IAAI,oBAAoB,CAAC,CAAC,CAAC,GAAG;IACrD,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC,EAAE,OAAO,YAAY,EAAE,wBAAwB,CAAC,CAAC;CAC1F,CAAC;AAaF,eAAO,MAAM,KAAK;YAC8D,kBAAkB,CAAC,MAAM,CAAC;YAC1B,kBAAkB,CAAC,MAAM,CAAC;aACzB,kBAAkB,CAAC,OAAO,CAAC;UAC9B,kBAAkB,CAAC,IAAI,CAAC;UACxB,kBAAkB,CAAC,IAAI,CAAC;UAC9B,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAEhG,oEAAoE;UAC9D,CAAC,QAAQ,MAAM,GAAG,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC;eAIjC,CAAC,SAAS,MAAM,cAAc,CAAC,EAAE,GAAG,kBAAkB,CAAC,CAAC,CAAC;UAI9D,CAAC,SAAS,oBAAoB,CAAC,CAAC,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,oBAAoB,CAAC,CAAC,CAAC;WAInF,CAAC,SAAS,oBAAoB,CAAC,CAAC,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,oBAAoB,CAAC,CAAC,CAAC;CAG5F,CAAC"}

package/dist/core/schema-types.js

@@ -1,16 +1,26 @@
+function withOptional(field) {
+    const base = field;
+    Object.defineProperty(base, 'optional', {
+        value: { ...field, optional: true, __optional: true },
+        enumerable: true,
+        configurable: false,
+        writable: false,
+    });
+    return base;
+}
 export const types = {
-    string: { kind: 'string' },
-    number: { kind: 'number' },
-    boolean: { kind: 'boolean' },
-    date: { kind: 'date' },
-    Date: { kind: 'date' },
-    json: { kind: 'json' },
+    string: withOptional({ kind: 'string' }),
+    number: withOptional({ kind: 'number' }),
+    boolean: withOptional({ kind: 'boolean' }),
+    date: withOptional({ kind: 'date' }),
+    Date: withOptional({ kind: 'date' }),
+    json: withOptional({ kind: 'json' }),
     /** Type a JSON field explicitly: `types.typed<MyType[]>('json')` */
     typed(kind) {
-        return { kind };
+        return withOptional({ kind });
     },
     enum(..._values) {
-        return { kind: 'enum' };
+        return withOptional({ kind: 'enum' });
     },
     index(field) {
         return { ...field, index: true };
@@ -19,4 +29,3 @@ export const types = {
         return { ...field, index: true, unique: true };
     },
 };
-//# sourceMappingURL=schema-types.js.map

package/dist/core/schema-types.type-test.js

@@ -139,11 +139,18 @@ const _badConfig = {
     },
 };
 void _badConfig;
-// table() with known key → Table<{ title: string; status: 'open'|'done'; priority: number }>
 const tasksTable = typedEngine.table('tasks');
-// _TasksGet should be { title: string; ... } | undefined — not Record<string,unknown>
-const _checkGet = { title: 'x', status: 'open', priority: 1 };
-void _checkGet;
+const _addOk = { title: 'x', status: 'open', priority: 1 };
+// @ts-expect-error — missing required field status
+const _addBad = { title: 'x', priority: 1 };
+const _replaceOk = { title: 'x', status: 'open', priority: 1 };
+// @ts-expect-error — missing required field priority
+const _replaceBad = { title: 'x', status: 'open' };
+void _addOk;
+void _replaceOk;
+// _TasksRow should be { title: string; ... } | undefined — not Record<string,unknown>
+const _checkRow = { title: 'x', status: 'open', priority: 1 };
+void _checkRow;
 // @ts-expect-error — 'nonexistent' is not keyof DB (no fallback overload)
 typedEngine.table('nonexistent');
 // ─── Regression: satisfies DatabaseSchemaDefinition infers correctly ─
@@ -173,4 +180,51 @@ void _r;
 // @ts-expect-error — number not assignable to string
 const _badWp = { weekId: 42, plan: {}, createdAt: new Date() };
 void _badWp;
-//# sourceMappingURL=schema-types.type-test.js.map
+// ─── _type phantom: no undefined bleeding into field types ───────────
+const _weekId = 'hello'; // string not string|undefined
+const _date = new Date(); // Date not Date|undefined
+const _num = 42; // number
+// @ts-expect-error — string is not number
+const _badNum = 'x';
+// ─── Optional fields ─────────────────────────────────────────────────
+const _optionalStringField = types.string.optional;
+const _optionalJsonField = types.typed('json').optional;
+// @ts-expect-error — optional fields cannot be indexed
+const _optionalIndexedString = types.index(types.string.optional);
+// @ts-expect-error — optional fields cannot be unique
+const _optionalUniqueString = types.unique(types.string.optional);
+const optionalSchema = {
+    version: 1,
+    tables: {
+        tasks: {
+            fields: {
+                title: types.string,
+                note: types.string.optional,
+                payload: types.typed('json').optional,
+            },
+        },
+    },
+};
+const _optionalOk1 = { title: 'x' };
+const _noteRead = _optRow.note;
+// @ts-expect-error — optional field is string | undefined, not string
+const _noteStrict = _optRow.note;
+void _noteRead;
+void _noteStrict;
+const _optionalOk2 = { title: 'x', note: 'hello', payload: { foo: 'bar' } };
+// @ts-expect-error — title required
+const _optionalBad1 = { note: 'hello' };
+// @ts-expect-error — note must be string when present
+const _optionalBad2 = { title: 'x', note: 42 };
+// @ts-expect-error — payload must match typed JSON payload
+const _optionalBad3 = { title: 'x', payload: { foo: 42 } };
+void _optionalStringField;
+void _optionalJsonField;
+void _optionalIndexedString;
+void _optionalUniqueString;
+void _optionalOk1;
+void _optionalOk2;
+void _weekId;
+void _date;
+void _num;
+void _badNum;