@vibesdotdev/storage 0.0.2 → 1.0.0-rc.3

package/dist/sync/sync-bridge.js

@@ -11,61 +11,175 @@
  * 4. Push new/updated local items, pull new/updated remote items
  * 5. Track state in sync-state.json alongside storage manifests
  */
-import { getRuntimeEnv } from '@vibesdotdev/runtime';
-import { loadSyncState, saveSyncState, getManifestSyncState, markSynced, markLocalAhead, markConflict, markError, markRemoteAhead, computeHash } from './sync-state.consumer.js';
+import { CapabilityError, CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
+import { SyncEntitySchema } from "../schemas/sync-bridge-descriptor.js";
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/kernel/schemas/descriptor';
+import { loadSyncState, saveSyncState, getManifestSyncState, markSynced, markLocalAhead, markConflict, markError, markRemoteAhead, computeHash, HASH_VERSION } from "./sync-state.consumer.js";
+import { getLogger } from '@vibesdotdev/logging';
+const DEFAULT_REMOTE_PAGE_SIZE = 100;
+const MAX_REMOTE_PAGES = 10_000;
+/** The longest one remote request may take before it is refused `TIMEOUT sync-remote-timeout`. */
+export const SYNC_REMOTE_REQUEST_TIMEOUT_MS = 30_000;
+/** The code an HTTP failure status projects to. */
+function codeForStatus(status) {
+    if (status === 401)
+        return 'AUTH_REQUIRED';
+    if (status === 403)
+        return 'PERMISSION_DENIED';
+    if (status === 404 || status === 410)
+        return 'NOT_FOUND';
+    if (status === 408 || status === 504)
+        return 'TIMEOUT';
+    if (status === 409 || status === 412)
+        return 'CONFLICT';
+    if (status === 429)
+        return 'RATE_LIMITED';
+    return status >= 500 ? 'UNAVAILABLE' : 'INVALID_INPUT';
+}
+/** A remote answer that is not a success: status-classified, value-free (no body, reason phrase or URL). */
+function remoteStatusFailure(operation, status) {
+    return new CapabilityError(`The sync remote refused the ${operation} request (HTTP ${status}).`, codeForStatus(status), {
+        reason: 'sync-remote-status',
+        retryable: status >= 500 || status === 429,
+        details: { operation, status }
+    });
+}
+/** A remote page: a bare entity array, or an envelope object holding one. */
+const RemotePageSchema = z.union([z.array(z.unknown()), z.record(z.string(), z.unknown())]);
+/** A remote page's entity list: every item a record. */
+const RemoteEntityListSchema = z.array(SyncEntitySchema);
+/** An envelope's declared page count, number or numeric string; anything else is undeclared. */
+const PaginationSchema = z.object({
+    pagination: z.object({ totalPages: z.union([z.number(), z.string()]).optional().catch(undefined) }).optional().catch(undefined)
+});
+/** An entity's timestamps, each read on its own (a non-string field is absent, never a failure). */
+const EntityTimestampsSchema = z.object({
+    deletedAt: z.string().optional().catch(undefined),
+    updatedAt: z.string().optional().catch(undefined),
+    createdAt: z.string().optional().catch(undefined)
+});
+/** An entity's id under the bridge's id field: a string or a number; anything else refuses typed. */
+function entityIdOf(entity, idField) {
+    const parsed = z.union([z.string().min(1), z.number()]).safeParse(entity[idField]);
+    if (!parsed.success) {
+        throw new CapabilityError('A sync entity has no usable id.', 'INVALID_INPUT', {
+            reason: 'sync-entity-id-invalid',
+            retryable: false,
+            details: { idField }
+        });
+    }
+    return String(parsed.data);
+}
+/** A remote whose pagination cannot be trusted (it ignores pages, or never ends): typed, value-free. */
+function paginationRefusal(message) {
+    return new CapabilityError(message, 'INVALID_INPUT', { reason: 'sync-remote-pagination-invalid', retryable: false });
+}
+/**
+ * What a sync failure is recorded as (the sync-state file, `vibes storage sync
+ * status`, result details): the job's prefix and the failure's value-free
+ * facts (class, code, reason), never a thrown text that may echo a body, URL
+ * or token.
+ */
+function syncFailureText(prefix, failure) {
+    const facts = valueFreeFailure(failure);
+    return [prefix, facts.name, facts.code, facts.reason].filter((part) => part !== undefined).join(' ');
+}
+/** Run `work`; its failure's value-free facts, or undefined when it succeeded. */
+async function failureOf(work) {
+    try {
+        await work();
+        return undefined;
+    }
+    catch (error) {
+        return valueFreeFailure(CaughtFailureSchema.parse(error));
+    }
+}
+/** A sync failure's recorded line from its value-free facts. */
+function syncFailureLine(prefix, facts) {
+    return [prefix, facts.name, facts.code, facts.reason].filter((part) => part !== undefined).join(' ');
+}
+/**
+ * Register one pulled descriptor with the runtime. A pulled item that is not
+ * a descriptor, or that the runtime refuses (already registered, invalid), is
+ * skipped and reported once with its value-free facts, never thrown over the
+ * rest of the pull.
+ */
+function registerPulledDescriptor(runtime, kindId, item) {
+    const logger = getLogger('storage:sync-bridge', runtime);
+    try {
+        runtime.registerDescriptor(kindId, RuntimeDescriptorSchema.loose().parse(item));
+    }
+    catch (error) {
+        logger.warn('Skipped pulled descriptor that could not be registered', {
+            kindId,
+            error: valueFreeFailure(CaughtFailureSchema.parse(error))
+        });
+    }
+}
 /**
  * Default SyncBridge implementation.
  * Constructed by the runtime with (descriptor, context).
  */
 export class SyncBridge {
     descriptor;
-    constructor(descriptor, _context) {
+    /** The runtime that constructed this bridge (`context.runtime`); every read goes through it. */
+    runtime;
+    constructor(descriptor, context) {
         this.descriptor = descriptor;
+        this.runtime = context.runtime;
     }
     get id() {
         return this.descriptor.id;
     }
-    /** Cached h2 fetch for HTTPS local endpoints */
-    _h2Fetch = null;
     /**
-     * Get an HTTP/2-aware fetch function.
-     * Local HTTPS endpoints (vite dev) require h2 since Bun's fetch is h1 only.
+     * One remote request, bounded: the runtime lifecycle's deadline
+     * ({@link SYNC_REMOTE_REQUEST_TIMEOUT_MS}) and its disposal abort it. A
+     * transport failure refuses `UNAVAILABLE sync-remote-unreachable` (its
+     * cause kept, its message naming no URL); the deadline refuses
+     * `TIMEOUT sync-remote-timeout`. Certificate verification is never
+     * switched off here: a local endpoint with a self-signed certificate is
+     * trusted by the host, not by this bridge.
      */
-    async getFetch(apiEndpoint) {
-        if (this._h2Fetch)
-            return this._h2Fetch;
-        const isHttps = apiEndpoint.startsWith('https://');
-        const isLocal = apiEndpoint.includes('.local') ||
-            apiEndpoint.includes('localhost') ||
-            apiEndpoint.includes('127.0.0.1');
-        if (isHttps && isLocal) {
-            try {
-                // Set REJECT_UNAUTHORIZED=false for local self-signed certs
-                if (!getRuntimeEnv('REJECT_UNAUTHORIZED')) {
-                    globalThis.process?.['env'] && (globalThis.process.env.REJECT_UNAUTHORIZED = 'false');
-                }
-                // h2 fetch lives in the app layer; local HTTP/2 dev servers fall through to regular fetch.
-            }
-            catch {
-                // Fall through to regular fetch
+    /** The descriptor's per-request deadline, or the default. */
+    get requestTimeoutMs() {
+        return this.descriptor.target.requestTimeoutMs ?? SYNC_REMOTE_REQUEST_TIMEOUT_MS;
+    }
+    boundedFetch = async (input, init) => {
+        try {
+            return await this.runtime.lifecycle.wait((signal) => fetch(input, { ...init, signal }), {
+                timeoutMs: this.requestTimeoutMs,
+                reason: 'storage-sync-remote-request'
+            });
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            if (failure instanceof Error && 'code' in failure && failure.code === 'TIMEOUT') {
+                throw new CapabilityError('The sync remote did not answer within its deadline.', 'TIMEOUT', {
+                    reason: 'sync-remote-timeout',
+                    retryable: true,
+                    details: { timeoutMs: this.requestTimeoutMs },
+                    cause: failure
+                });
             }
+            throw new CapabilityError('The sync remote could not be reached.', 'UNAVAILABLE', {
+                reason: 'sync-remote-unreachable',
+                retryable: true,
+                cause: failure
+            });
         }
-        this._h2Fetch = (input, init) => fetch(input, init);
-        return this._h2Fetch;
-    }
+    };
     /**
      * Collect local descriptors from the runtime.
      */
     async collectLocal() {
         if (this.descriptor.collect) {
-            return this.descriptor.collect();
+            return this.descriptor.collect({ runtime: this.runtime });
         }
-        const { getVibesRuntime } = await import('@vibesdotdev/runtime');
-        const runtime = getVibesRuntime();
-        const descriptors = runtime
+        return this.runtime
             .query(this.descriptor.source.runtimeKind)
-            .descriptors();
-        return descriptors;
+            .descriptors()
+            .map((descriptor) => SyncEntitySchema.parse(descriptor));
     }
     stripSensitiveFields(entity) {
         const sanitized = { ...entity };
@@ -74,24 +188,19 @@ export class SyncBridge {
         }
         return sanitized;
     }
-    buildPushShape(entity) {
+    toPushedEntity(entity) {
         const transformed = this.descriptor.toRemote ? this.descriptor.toRemote(entity) : entity;
         return this.stripSensitiveFields(transformed);
     }
     buildComparableRemote(entity) {
-        const localShape = this.descriptor.fromRemote ? this.descriptor.fromRemote(entity) : entity;
-        return this.buildPushShape(localShape);
+        const asLocal = this.descriptor.fromRemote ? this.descriptor.fromRemote(entity) : entity;
+        return this.toPushedEntity(asLocal);
     }
     getEntityTimestamp(entity) {
         if (!entity)
             return null;
-        const value = typeof entity.deletedAt === 'string'
-            ? entity.deletedAt
-            : typeof entity.updatedAt === 'string'
-                ? entity.updatedAt
-                : typeof entity.createdAt === 'string'
-                    ? entity.createdAt
-                    : null;
+        const stamps = EntityTimestampsSchema.parse(entity);
+        const value = stamps.deletedAt ?? stamps.updatedAt ?? stamps.createdAt;
         if (!value)
             return null;
         const timestamp = new Date(value).getTime();
@@ -121,24 +230,30 @@ export class SyncBridge {
         }
         return direction === 'push' ? 'conflict' : 'pull';
     }
+    /**
+     * The entity list of a remote page: the bare array, else the declared list
+     * field, else a known envelope field. Every item must be an object: a page
+     * whose list holds anything else refuses `sync-remote-body-invalid`
+     * (a malformed answer from the remote is a failure, never absence).
+     */
     extractList(data) {
-        if (!data || typeof data !== 'object') {
+        const candidates = Array.isArray(data)
+            ? [data]
+            : [this.descriptor.target.listField, 'items', 'data', 'results', 'benchmarks', 'scenarios']
+                .filter((key) => key !== undefined)
+                .map((key) => data[key]);
+        const list = candidates.find((candidate) => Array.isArray(candidate));
+        if (list === undefined)
             return [];
+        const parsed = RemoteEntityListSchema.safeParse(list);
+        if (!parsed.success) {
+            throw new CapabilityError('The sync remote answered with a list whose items are not records.', 'INTERNAL', {
+                reason: 'sync-remote-body-invalid',
+                retryable: false,
+                cause: parsed.error
+            });
         }
-        const record = data;
-        const listField = this.descriptor.target.listField;
-        if (listField && Array.isArray(record[listField])) {
-            return record[listField];
-        }
-        if (Array.isArray(data)) {
-            return data;
-        }
-        for (const key of ['items', 'data', 'results', 'benchmarks', 'scenarios']) {
-            if (Array.isArray(record[key])) {
-                return record[key];
-            }
-        }
-        return [];
+        return parsed.data;
     }
     /**
      * Fetch remote entities from the cloud CRUD API.
@@ -147,18 +262,19 @@ export class SyncBridge {
         const { target } = this.descriptor;
         const url = `${apiEndpoint}${target.apiPath}`;
         try {
-            const headers = {
-                'Content-Type': 'application/json'
-            };
-            if (apiToken) {
-                headers['Authorization'] = `Bearer ${apiToken}`;
-            }
-            const doFetch = await this.getFetch(apiEndpoint);
+            const headers = new Headers({ 'Content-Type': 'application/json' });
+            if (apiToken)
+                headers.set('Authorization', `Bearer ${apiToken}`);
+            const doFetch = this.boundedFetch;
+            const configuredPageSize = Number.parseInt(new URL(url).searchParams.get('perPage') ?? String(DEFAULT_REMOTE_PAGE_SIZE), 10);
+            const pageSize = Number.isFinite(configuredPageSize) && configuredPageSize > 0
+                ? configuredPageSize
+                : DEFAULT_REMOTE_PAGE_SIZE;
             const fetchPage = async (page) => {
                 const pageUrl = new URL(url);
                 pageUrl.searchParams.set('page', String(page));
                 if (!pageUrl.searchParams.has('perPage')) {
-                    pageUrl.searchParams.set('perPage', '100');
+                    pageUrl.searchParams.set('perPage', String(pageSize));
                 }
                 if (target.includeDeleted && !pageUrl.searchParams.has('includeDeleted')) {
                     pageUrl.searchParams.set('includeDeleted', 'true');
@@ -168,33 +284,58 @@ export class SyncBridge {
                     if (response.status === 404) {
                         return { items: [], totalPages: 0 };
                     }
-                    throw new Error(`API ${response.status}: ${response.statusText}`);
+                    throw remoteStatusFailure('fetch', response.status);
                 }
-                const data = await response.json();
-                const items = this.extractList(data);
-                const pagination = data && typeof data === 'object' && 'pagination' in data
-                    ? data.pagination
-                    : null;
-                const totalPages = typeof pagination?.totalPages === 'number'
-                    ? pagination.totalPages
-                    : typeof pagination?.totalPages === 'string'
-                        ? Number.parseInt(pagination.totalPages, 10)
-                        : 1;
-                return { items, totalPages: Number.isNaN(totalPages) ? 1 : totalPages };
+                let body;
+                try {
+                    body = RemotePageSchema.parse(await response.json());
+                }
+                catch (error) {
+                    throw new CapabilityError('The sync remote answered with a body that is not a JSON page.', 'INTERNAL', {
+                        reason: 'sync-remote-body-invalid',
+                        retryable: false,
+                        cause: CaughtFailureSchema.parse(error)
+                    });
+                }
+                const items = this.extractList(body);
+                const declared = Array.isArray(body) ? undefined : PaginationSchema.parse(body).pagination?.totalPages;
+                const totalPages = declared === undefined ? null : Number.parseInt(String(declared), 10);
+                return { items, totalPages: totalPages === null || Number.isNaN(totalPages) ? null : totalPages };
             };
             const firstPage = await fetchPage(1);
-            if (firstPage.totalPages <= 1) {
-                return firstPage.items;
-            }
             const items = [...firstPage.items];
-            for (let page = 2; page <= firstPage.totalPages; page++) {
+            if (firstPage.totalPages !== null) {
+                if (firstPage.totalPages > MAX_REMOTE_PAGES) {
+                    throw paginationRefusal(`Remote pagination exceeds the ${MAX_REMOTE_PAGES}-page safety limit`);
+                }
+                for (let page = 2; page <= firstPage.totalPages; page++) {
+                    const nextPage = await fetchPage(page);
+                    items.push(...nextPage.items);
+                }
+                return items;
+            }
+            let previousPageFirstId = firstPage.items[0]?.[this.descriptor.sync.idField] ?? firstPage.items[0]?.id;
+            for (let page = 2; items.length >= pageSize * (page - 1); page++) {
+                if (page > MAX_REMOTE_PAGES) {
+                    throw paginationRefusal(`Remote pagination reached the ${MAX_REMOTE_PAGES}-page safety limit without a short page`);
+                }
                 const nextPage = await fetchPage(page);
+                const nextPageFirstId = nextPage.items[0]?.[this.descriptor.sync.idField] ?? nextPage.items[0]?.id;
+                if (previousPageFirstId !== undefined &&
+                    nextPageFirstId !== undefined &&
+                    nextPageFirstId === previousPageFirstId) {
+                    throw paginationRefusal(`Remote pagination repeated the first item on page ${page}`);
+                }
                 items.push(...nextPage.items);
+                if (nextPage.items.length < pageSize)
+                    return items;
+                previousPageFirstId = nextPageFirstId;
             }
             return items;
         }
         catch (error) {
-            throw new Error(`Failed to fetch remote from ${url}: ${error.message}`);
+            // Typed failures pass through; anything else is carried, never echoed (the URL can hold a token).
+            throw CapabilityError.from(CaughtFailureSchema.parse(error));
         }
     }
     /**
@@ -202,16 +343,13 @@ export class SyncBridge {
      */
     async pushEntity(entity, apiEndpoint, apiToken) {
         const { target, sync } = this.descriptor;
-        const entityId = entity[sync.idField];
+        const entityId = entityIdOf(entity, sync.idField);
         const entityPath = target.entityPath ?? `${target.apiPath}/:id`;
         const url = `${apiEndpoint}${entityPath.replace(':id', encodeURIComponent(entityId))}`;
-        const headers = {
-            'Content-Type': 'application/json'
-        };
-        if (apiToken) {
-            headers['Authorization'] = `Bearer ${apiToken}`;
-        }
-        const doFetch = await this.getFetch(apiEndpoint);
+        const headers = new Headers({ 'Content-Type': 'application/json' });
+        if (apiToken)
+            headers.set('Authorization', `Bearer ${apiToken}`);
+        const doFetch = this.boundedFetch;
         // Try PUT first (upsert), fall back to POST
         let response = await doFetch(url, {
             method: 'PUT',
@@ -226,23 +364,21 @@ export class SyncBridge {
                 body: JSON.stringify(entity)
             });
         }
-        if (!response.ok) {
-            const body = await response.text().catch(() => '');
-            throw new Error(`Push failed (${response.status}): ${body}`);
-        }
+        if (!response.ok)
+            throw remoteStatusFailure('push', response.status);
     }
     async deleteEntity(entity, apiEndpoint, apiToken) {
         const { target, sync } = this.descriptor;
-        const entityId = entity[sync.idField];
+        const entityId = entityIdOf(entity, sync.idField);
         const entityPath = target.entityPath ?? `${target.apiPath}/:id`;
         const url = `${apiEndpoint}${entityPath.replace(':id', encodeURIComponent(entityId))}`;
-        const headers = {};
-        if (apiToken) {
-            headers['Authorization'] = `Bearer ${apiToken}`;
-        }
-        const doFetch = await this.getFetch(apiEndpoint);
+        const headers = new Headers();
+        if (apiToken)
+            headers.set('Authorization', `Bearer ${apiToken}`);
+        const doFetch = this.boundedFetch;
         if (this.descriptor.deleteRemote) {
             await this.descriptor.deleteRemote(entity, {
+                runtime: this.runtime,
                 apiEndpoint,
                 apiToken,
                 fetch: doFetch
@@ -256,10 +392,8 @@ export class SyncBridge {
         if (response.status === 404) {
             return;
         }
-        if (!response.ok) {
-            const body = await response.text().catch(() => '');
-            throw new Error(`Delete failed (${response.status}): ${body}`);
-        }
+        if (!response.ok)
+            throw remoteStatusFailure('delete', response.status);
     }
     /**
      * Persist pulled items locally.
@@ -269,12 +403,12 @@ export class SyncBridge {
     async persistPulledItems(newItems, existingLocalItems, idField) {
         const { writePulled, storageManifestId } = this.descriptor;
         if (writePulled) {
-            await writePulled(newItems);
+            await writePulled(newItems, { runtime: this.runtime });
             return;
         }
         if (storageManifestId) {
-            const { StorageManifest } = await import('../manifest/base.js');
-            const manifest = StorageManifest.fromId(storageManifestId);
+            const { StorageManifest } = await import("../manifest/base.js");
+            const manifest = StorageManifest.fromId(storageManifestId, this.runtime);
             const existing = (await manifest.load()) ?? [];
             if (newItems.length > 0) {
                 const merged = new Map(existing.map((item) => [String(item[idField]), item]));
@@ -286,23 +420,48 @@ export class SyncBridge {
             return;
         }
         // Descriptor-only: register with runtime
-        const { getVibesRuntime } = await import('@vibesdotdev/runtime');
-        const runtime = getVibesRuntime();
+        const runtime = this.runtime;
         const kindId = this.descriptor.source.runtimeKind;
         if (!runtime.hasKind(kindId))
             return;
-        for (const item of newItems) {
-            try {
-                runtime.registerDescriptor(kindId, item);
-            }
-            catch {
-                // Descriptor already registered or invalid — skip
-            }
-        }
+        for (const item of newItems)
+            registerPulledDescriptor(runtime, kindId, item);
     }
     /**
      * Execute a full sync cycle.
      */
+    /**
+     * Push one local entity: the durable delivery of a single created record
+     * (D-RC11). Same `beforePush` hook, push shape and upsert as `execute`, and
+     * the same sync-state entry, without collecting or fetching the whole
+     * collection. A failure is recorded on the entity's sync state and thrown,
+     * so the delivering Workers job retries it.
+     */
+    async pushOne(localItem, apiEndpoint, apiToken) {
+        const entityId = String(localItem[this.descriptor.sync.idField]);
+        const stateKey = `${this.id}:${entityId}`;
+        const syncState = await loadSyncState(this.runtime);
+        const pushItem = this.toPushedEntity(localItem);
+        try {
+            if (this.descriptor.beforePush) {
+                await this.descriptor.beforePush(localItem, {
+                    runtime: this.runtime,
+                    apiEndpoint,
+                    apiToken,
+                    fetch: this.boundedFetch
+                });
+            }
+            await this.pushEntity(pushItem, apiEndpoint, apiToken);
+            markSynced(syncState, stateKey, computeHash(pushItem), 'push');
+        }
+        catch (error) {
+            const failure = CaughtFailureSchema.parse(error);
+            markError(syncState, stateKey, syncFailureText('Push failed:', failure));
+            await saveSyncState(syncState, this.runtime);
+            throw failure;
+        }
+        await saveSyncState(syncState, this.runtime);
+    }
     async execute(apiEndpoint, options = {}, apiToken) {
         const { sync } = this.descriptor;
         const { dryRun = false, force = false, direction = 'both' } = options;
@@ -316,7 +475,7 @@ export class SyncBridge {
             errors: 0,
             details: []
         };
-        const syncState = await loadSyncState();
+        const syncState = await loadSyncState(this.runtime);
         try {
             let localItems = await this.collectLocal();
             if (sync.ownershipFilter !== 'all' && this.descriptor.source.sourceTypeField) {
@@ -330,31 +489,33 @@ export class SyncBridge {
                     return true;
                 });
             }
-            let remoteItems = [];
+            let remoteItems;
             try {
                 remoteItems = await this.fetchRemote(apiEndpoint, apiToken);
             }
             catch (error) {
-                if (direction === 'pull') {
-                    result.errors++;
-                    result.details.push({
-                        entityId: '*',
-                        action: 'error',
-                        message: `Remote unreachable: ${error.message}`
-                    });
-                    return result;
-                }
+                // A remote that cannot be read is never treated as empty: pushing
+                // against an unknown remote would skip conflict detection.
+                const failure = CaughtFailureSchema.parse(error);
+                return {
+                    ...result,
+                    errors: result.errors + 1,
+                    details: [
+                        ...result.details,
+                        { entityId: '*', action: 'error', message: syncFailureText('Remote unreachable:', failure), failure: valueFreeFailure(failure) }
+                    ]
+                };
             }
             const pushAllowed = direction === 'push' || direction === 'both';
             const pullAllowed = direction === 'pull' || direction === 'both';
-            const doFetch = await this.getFetch(apiEndpoint);
+            const doFetch = this.boundedFetch;
             const localMap = new Map(localItems.map((item) => [String(item[idField]), item]));
             const remoteMap = new Map(remoteItems.map((item) => [String(item[idField] ?? item.id), item]));
             const allEntityIds = new Set([...localMap.keys(), ...remoteMap.keys()]);
             const pulledItems = [];
             const pushLocal = async (entityId, localItem, localHash) => {
                 const stateKey = `${this.id}:${entityId}`;
-                const pushItem = this.buildPushShape(localItem);
+                const pushItem = this.toPushedEntity(localItem);
                 if (dryRun) {
                     result.pushed++;
                     result.details.push({
@@ -364,27 +525,21 @@ export class SyncBridge {
                     });
                     return;
                 }
-                try {
+                const failure = await failureOf(async () => {
                     if (this.descriptor.beforePush) {
-                        await this.descriptor.beforePush(localItem, {
-                            apiEndpoint,
-                            apiToken,
-                            fetch: doFetch
-                        });
+                        await this.descriptor.beforePush(localItem, { runtime: this.runtime, apiEndpoint, apiToken, fetch: doFetch });
                     }
                     await this.pushEntity(pushItem, apiEndpoint, apiToken);
+                });
+                if (failure === undefined) {
                     result.pushed++;
                     result.details.push({ entityId, action: 'pushed' });
                     markSynced(syncState, stateKey, localHash, 'push');
                 }
-                catch (error) {
+                else {
                     result.errors++;
-                    result.details.push({
-                        entityId,
-                        action: 'error',
-                        message: `Push failed: ${error.message}`
-                    });
-                    markError(syncState, stateKey, error.message);
+                    result.details.push({ entityId, action: 'error', message: syncFailureLine('Push failed:', failure), failure });
+                    markError(syncState, stateKey, syncFailureLine('Push failed:', failure));
                 }
             };
             const deleteRemote = async (entityId, localItem, localHash) => {
@@ -398,24 +553,16 @@ export class SyncBridge {
                     });
                     return;
                 }
-                try {
-                    await this.deleteEntity(localItem, apiEndpoint, apiToken);
+                const failure = await failureOf(() => this.deleteEntity(localItem, apiEndpoint, apiToken));
+                if (failure === undefined) {
                     result.pushed++;
-                    result.details.push({
-                        entityId,
-                        action: 'pushed',
-                        message: 'Deleted remote via tombstone'
-                    });
+                    result.details.push({ entityId, action: 'pushed', message: 'Deleted remote via tombstone' });
                     markSynced(syncState, stateKey, localHash, 'push');
                 }
-                catch (error) {
+                else {
                     result.errors++;
-                    result.details.push({
-                        entityId,
-                        action: 'error',
-                        message: `Delete failed: ${error.message}`
-                    });
-                    markError(syncState, stateKey, error.message);
+                    result.details.push({ entityId, action: 'error', message: syncFailureLine('Delete failed:', failure), failure });
+                    markError(syncState, stateKey, syncFailureLine('Delete failed:', failure));
                 }
             };
             const pullRemote = (entityId, remoteItem, remoteHash) => {
@@ -446,19 +593,97 @@ export class SyncBridge {
                         ? this.descriptor.fromRemote(remoteItem)
                         : remoteItem
                     : null;
-                const localHash = localItem ? computeHash(this.buildPushShape(localItem)) : null;
+                const localHash = localItem ? computeHash(this.toPushedEntity(localItem)) : null;
                 const remoteHash = comparableRemote
-                    ? computeHash(this.buildPushShape(comparableRemote))
+                    ? computeHash(this.toPushedEntity(comparableRemote))
                     : null;
                 const prev = getManifestSyncState(syncState, stateKey);
+                const hasLegacyHashState = (prev.localHash !== null || prev.remoteHash !== null) &&
+                    prev.hashVersion !== HASH_VERSION;
                 const localDeleted = this.isDeleted(localItem);
                 const remoteDeleted = this.isDeleted(comparableRemote ?? undefined);
+                if (localItem &&
+                    remoteItem &&
+                    localHash &&
+                    remoteHash &&
+                    localDeleted !== remoteDeleted) {
+                    if (localDeleted) {
+                        if (pushAllowed) {
+                            await deleteRemote(entityId, localItem, localHash);
+                        }
+                        else {
+                            result.skipped++;
+                            result.details.push({
+                                entityId,
+                                action: 'skipped',
+                                message: 'Local tombstone pending remote delete'
+                            });
+                            markLocalAhead(syncState, stateKey, localHash);
+                        }
+                    }
+                    else if (pullAllowed) {
+                        pullRemote(entityId, remoteItem, remoteHash);
+                    }
+                    else {
+                        result.skipped++;
+                        result.details.push({
+                            entityId,
+                            action: 'skipped',
+                            message: 'Remote tombstone pending local pull'
+                        });
+                        markRemoteAhead(syncState, stateKey, remoteHash);
+                    }
+                    continue;
+                }
+                if (localItem && remoteItem && localDeleted && remoteDeleted) {
+                    // Both sides tombstoned: content hashes are irrelevant (servers bump
+                    // updatedAt on delete, so they never re-equalize) — the pair is
+                    // converged by deletion state alone. Without this, tombstone pairs
+                    // sit in a permanent changed-classification standoff.
+                    result.skipped++;
+                    result.details.push({ entityId, action: 'skipped', message: 'In sync (tombstone)' });
+                    markSynced(syncState, stateKey, localHash ?? remoteHash ?? '', direction === 'pull' ? 'pull' : 'push');
+                    continue;
+                }
                 if (localItem && remoteItem && localHash === remoteHash) {
+                    // Equal current-format hashes prove convergence regardless of the
+                    // persisted hash format — this MUST precede the legacy-hash guard,
+                    // or the first post-upgrade sync re-uploads every unchanged record
+                    // (and 'newest' strategies raise spurious conflict waves).
                     result.skipped++;
                     result.details.push({ entityId, action: 'skipped', message: 'In sync' });
                     markSynced(syncState, stateKey, localHash ?? remoteHash ?? '', direction === 'pull' ? 'pull' : 'push');
                     continue;
                 }
+                if (hasLegacyHashState && localItem && remoteItem && localHash && remoteHash) {
+                    if (!pushAllowed) {
+                        result.skipped++;
+                        result.details.push({
+                            entityId,
+                            action: 'skipped',
+                            message: 'Sync state predates hash upgrade; push required'
+                        });
+                        markLocalAhead(syncState, stateKey, localHash);
+                        continue;
+                    }
+                    const conflictAction = this.resolveConflictAction(localItem, remoteItem, direction);
+                    if (conflictAction === 'push') {
+                        await pushLocal(entityId, localItem, localHash);
+                        continue;
+                    }
+                    if (conflictAction === 'pull') {
+                        pullRemote(entityId, remoteItem, remoteHash);
+                        continue;
+                    }
+                    result.conflicts++;
+                    result.details.push({
+                        entityId,
+                        action: 'conflict',
+                        message: 'Both local and remote changed'
+                    });
+                    markConflict(syncState, stateKey, localHash, remoteHash);
+                    continue;
+                }
                 if (localItem && !remoteItem) {
                     if (localDeleted) {
                         result.skipped++;
@@ -508,35 +733,6 @@ export class SyncBridge {
                 if (!localItem || !remoteItem || !localHash || !remoteHash) {
                     continue;
                 }
-                if (localDeleted !== remoteDeleted) {
-                    if (localDeleted) {
-                        if (pushAllowed) {
-                            await deleteRemote(entityId, localItem, localHash);
-                        }
-                        else {
-                            result.skipped++;
-                            result.details.push({
-                                entityId,
-                                action: 'skipped',
-                                message: 'Local tombstone pending remote delete'
-                            });
-                            markLocalAhead(syncState, stateKey, localHash);
-                        }
-                    }
-                    else if (pullAllowed) {
-                        pullRemote(entityId, remoteItem, remoteHash);
-                    }
-                    else {
-                        result.skipped++;
-                        result.details.push({
-                            entityId,
-                            action: 'skipped',
-                            message: 'Remote tombstone pending local pull'
-                        });
-                        markRemoteAhead(syncState, stateKey, remoteHash);
-                    }
-                    continue;
-                }
                 const localChanged = force || localHash !== prev.localHash;
                 const remoteChanged = force || remoteHash !== prev.remoteHash;
                 if (pushAllowed && pullAllowed) {
@@ -550,6 +746,22 @@ export class SyncBridge {
                     }
                 }
                 if (pushAllowed && !pullAllowed) {
+                    if (localChanged && remoteChanged) {
+                        const conflictAction = this.resolveConflictAction(localItem, remoteItem, direction);
+                        if (conflictAction === 'push') {
+                            await pushLocal(entityId, localItem, localHash);
+                        }
+                        else {
+                            result.conflicts++;
+                            result.details.push({
+                                entityId,
+                                action: 'conflict',
+                                message: 'Remote record wins; pull before pushing'
+                            });
+                            markConflict(syncState, stateKey, localHash, remoteHash);
+                        }
+                        continue;
+                    }
                     if (localChanged) {
                         await pushLocal(entityId, localItem, localHash);
                     }
@@ -565,6 +777,22 @@ export class SyncBridge {
                     continue;
                 }
                 if (pullAllowed && !pushAllowed) {
+                    if (localChanged && remoteChanged) {
+                        const conflictAction = this.resolveConflictAction(localItem, remoteItem, direction);
+                        if (conflictAction === 'pull') {
+                            pullRemote(entityId, remoteItem, remoteHash);
+                        }
+                        else {
+                            result.conflicts++;
+                            result.details.push({
+                                entityId,
+                                action: 'conflict',
+                                message: 'Local record wins; push before pulling'
+                            });
+                            markConflict(syncState, stateKey, localHash, remoteHash);
+                        }
+                        continue;
+                    }
                     if (remoteChanged) {
                         pullRemote(entityId, remoteItem, remoteHash);
                     }
@@ -600,16 +828,19 @@ export class SyncBridge {
                 await this.persistPulledItems(pulledItems, localItems, idField);
             }
             if (!dryRun) {
-                await saveSyncState(syncState);
+                await saveSyncState(syncState, this.runtime);
             }
         }
         catch (error) {
-            result.errors++;
-            result.details.push({
-                entityId: '*',
-                action: 'error',
-                message: `Bridge sync failed: ${error.message}`
-            });
+            const failure = CaughtFailureSchema.parse(error);
+            return {
+                ...result,
+                errors: result.errors + 1,
+                details: [
+                    ...result.details,
+                    { entityId: '*', action: 'error', message: syncFailureText('Bridge sync failed:', failure), failure: valueFreeFailure(failure) }
+                ]
+            };
         }
         return result;
     }