@taskforcehq/taskforce 0.3.328 → 0.3.329

package/dist/storage/postgresAdapter.js

@@ -3,13 +3,30 @@ import { Worker } from 'worker_threads';
 import { performance } from 'node:perf_hooks';
 import { assertSynchronousTransactionResult, } from './databaseAdapter.js';
 import { recordPostgresWorkerWait } from './postgresRequestDiagnostics.js';
+import { resolvePostgresWorkerDeadlines, } from './postgresWorkerProtocol.js';
 const RESPONSE_STATUS_INDEX = 0;
 const RESPONSE_LENGTH_INDEX = 1;
 const RESPONSE_READY = 1;
 const RESPONSE_INITIAL = 0;
-const RESPONSE_TIMEOUT_MS = 20_000;
 const RESPONSE_BUFFER_BYTES = 2 * 1024 * 1024;
 const MAX_RESPONSE_BUFFER_BYTES = 64 * 1024 * 1024;
+export class PostgresWorkerOutcomeUnknownError extends Error {
+    code = 'POSTGRES_WORKER_OUTCOME_UNKNOWN';
+    operation;
+    constructor(operation, detail = 'response deadline exceeded') {
+        super(`[Taskforce] Postgres worker ${operation} outcome is unknown (${detail}). `
+            + 'Do not retry a write without the same idempotency identity.');
+        this.name = 'PostgresWorkerOutcomeUnknownError';
+        this.operation = operation;
+    }
+}
+export class PostgresWorkerUnavailableError extends Error {
+    code = 'POSTGRES_WORKER_UNAVAILABLE';
+    constructor() {
+        super('[Taskforce] Postgres worker is recovering after a failed operation.');
+        this.name = 'PostgresWorkerUnavailableError';
+    }
+}
 function isPlainObject(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
@@ -62,39 +79,102 @@ function toRowCount(result) {
 }
 export class PostgresAdapter {
     provider = 'postgres';
-    open = true;
-    worker;
+    worker = null;
+    connectionString;
+    deadlines;
+    retiringWorkers = new WeakSet();
+    consecutiveUnexpectedExits = 0;
+    closed = false;
     encoder = new TextEncoder();
     decoder = new TextDecoder();
     txId = null;
     savepointCounter = 0;
-    constructor(connectionString) {
+    constructor(connectionString, deadlineOptions = {}) {
         if (!connectionString || !connectionString.trim()) {
             throw new Error('[Taskforce] Postgres adapter requires a non-empty connection string.');
         }
-        this.worker = new Worker(new URL('./postgresWorker.js', import.meta.url), {
+        this.connectionString = connectionString;
+        this.deadlines = resolvePostgresWorkerDeadlines(deadlineOptions);
+        this.worker = this.createWorker();
+    }
+    get open() {
+        return !this.closed;
+    }
+    createWorker() {
+        const worker = new Worker(new URL('./postgresWorker.js', import.meta.url), {
             workerData: {
-                connectionString
+                connectionString: this.connectionString,
+                deadlines: this.deadlines,
+            }
+        });
+        worker.on('error', () => {
+            // The exit handler replaces an unexpectedly failed worker. Keeping an error
+            // listener here also prevents Worker from escalating it as an uncaught error.
+        });
+        worker.on('exit', () => {
+            if (this.closed || this.retiringWorkers.has(worker) || this.worker !== worker)
+                return;
+            this.worker = null;
+            if (this.consecutiveUnexpectedExits >= 1)
+                return;
+            this.consecutiveUnexpectedExits += 1;
+            try {
+                this.worker = this.createWorker();
+            }
+            catch {
+                // Leave the adapter unavailable instead of creating an unbounded restart loop.
+            }
+        });
+        return worker;
+    }
+    quarantineWorker(worker) {
+        if (this.worker === worker)
+            this.worker = null;
+        this.txId = null;
+        this.retiringWorkers.add(worker);
+        void worker.terminate()
+            .catch(() => undefined)
+            .finally(() => {
+            if (this.closed || this.worker)
+                return;
+            try {
+                this.worker = this.createWorker();
+            }
+            catch {
+                // A later process-level health check can restart a persistently broken runtime.
             }
         });
     }
     callWorker(payload, responseBufferBytes = RESPONSE_BUFFER_BYTES) {
+        if (this.closed)
+            throw new Error('[Taskforce] Postgres adapter is closed.');
+        const worker = this.worker;
+        if (!worker)
+            throw new PostgresWorkerUnavailableError();
         const statusBuffer = new SharedArrayBuffer(8);
         const status = new Int32Array(statusBuffer);
         status[RESPONSE_STATUS_INDEX] = RESPONSE_INITIAL;
         status[RESPONSE_LENGTH_INDEX] = 0;
         const responseBuffer = new SharedArrayBuffer(responseBufferBytes);
         const responseBytes = new Uint8Array(responseBuffer);
-        this.worker.postMessage({
-            payload,
-            statusBuffer,
-            responseBuffer
-        });
+        try {
+            worker.postMessage({
+                payload,
+                statusBuffer,
+                responseBuffer
+            });
+        }
+        catch (error) {
+            this.quarantineWorker(worker);
+            const detail = error instanceof Error ? error.message : 'worker transport failed';
+            throw new PostgresWorkerOutcomeUnknownError(payload.op, detail);
+        }
         const waitStartedAt = performance.now();
-        const waitResult = Atomics.wait(status, RESPONSE_STATUS_INDEX, RESPONSE_INITIAL, RESPONSE_TIMEOUT_MS);
+        const waitResult = Atomics.wait(status, RESPONSE_STATUS_INDEX, RESPONSE_INITIAL, this.deadlines.responseTimeoutMs);
         recordPostgresWorkerWait(payload.op, performance.now() - waitStartedAt);
         if (waitResult === 'timed-out') {
-            throw new Error('[Taskforce] Postgres worker timed out.');
+            this.quarantineWorker(worker);
+            throw new PostgresWorkerOutcomeUnknownError(payload.op);
         }
         const responseLength = status[RESPONSE_LENGTH_INDEX];
         if (!Number.isFinite(responseLength) || responseLength <= 0 || responseLength > responseBufferBytes) {
@@ -102,6 +182,7 @@ export class PostgresAdapter {
         }
         const body = this.decoder.decode(responseBytes.subarray(0, responseLength));
         const parsed = JSON.parse(body);
+        this.consecutiveUnexpectedExits = 0;
         if (!parsed.ok && parsed.errorCode === 'RESPONSE_BUFFER_TOO_SMALL') {
             const requiredBytes = Number(parsed.requiredBytes);
             const responseToken = String(parsed.responseToken || '').trim();
@@ -230,11 +311,22 @@ export class PostgresAdapter {
         return options?.simple ? null : [];
     }
     close() {
+        if (this.closed)
+            return;
+        const worker = this.worker;
+        if (!worker) {
+            this.closed = true;
+            return;
+        }
         try {
             this.callWorker({ op: 'close' });
         }
         finally {
-            this.worker.terminate();
+            this.closed = true;
+            if (this.worker === worker)
+                this.worker = null;
+            this.retiringWorkers.add(worker);
+            void worker.terminate();
         }
     }
 }

package/dist/storage/postgresWorker.js

@@ -14,11 +14,16 @@ function pruneRetainedResponses(now = Date.now()) {
             retainedResponses.delete(token);
     }
 }
-function createPool(connectionString) {
+function createPool(connectionString, deadlines) {
     const require = createRequire(import.meta.url);
     try {
         const pg = require('pg');
-        return new pg.Pool({ connectionString });
+        return new pg.Pool({
+            connectionString,
+            connectionTimeoutMillis: deadlines.connectionTimeoutMs,
+            statement_timeout: deadlines.statementTimeoutMs,
+            idle_in_transaction_session_timeout: deadlines.idleTransactionTimeoutMs,
+        });
     }
     catch (error) {
         const detail = error instanceof Error ? ` (${error.message})` : '';
@@ -96,11 +101,15 @@ function writeRetainedResponse(statusBuffer, responseBuffer, responseToken) {
     Atomics.store(status, RESPONSE_STATUS_INDEX, RESPONSE_READY);
     Atomics.notify(status, RESPONSE_STATUS_INDEX, 1);
 }
-const connectionString = String(workerData?.connectionString || '').trim();
+const runtimeOptions = workerData;
+const connectionString = String(runtimeOptions?.connectionString || '').trim();
 if (!connectionString) {
     throw new Error('[Taskforce] Postgres worker requires connection string.');
 }
-const pool = createPool(connectionString);
+if (!runtimeOptions.deadlines) {
+    throw new Error('[Taskforce] Postgres worker requires deadline configuration.');
+}
+const pool = createPool(connectionString, runtimeOptions.deadlines);
 const txClients = new Map();
 async function handleMessage(message) {
     const { payload } = message;

package/dist/storage/postgresWorkerProtocol.d.ts

@@ -0,0 +1,29 @@
+export type PostgresWorkerOperation = 'query' | 'begin' | 'commit' | 'rollback' | 'close' | 'read-response';
+export type PostgresWorkerRequestPayload = {
+    op: PostgresWorkerOperation;
+    sql?: string;
+    values?: unknown[];
+    txId?: string;
+    responseToken?: string;
+};
+export type PostgresWorkerQueryResult = {
+    rows: Record<string, unknown>[];
+    rowCount?: number;
+};
+export type PostgresWorkerResponsePayload = {
+    ok: boolean;
+    result?: PostgresWorkerQueryResult;
+    error?: string;
+    errorCode?: 'RESPONSE_BUFFER_TOO_SMALL';
+    requiredBytes?: number;
+    responseToken?: string;
+};
+export type PostgresWorkerDeadlines = {
+    responseTimeoutMs: number;
+    statementTimeoutMs: number;
+    connectionTimeoutMs: number;
+    idleTransactionTimeoutMs: number;
+};
+export type PostgresAdapterDeadlineOptions = Partial<PostgresWorkerDeadlines>;
+export declare const DEFAULT_POSTGRES_WORKER_DEADLINES: PostgresWorkerDeadlines;
+export declare function resolvePostgresWorkerDeadlines(options?: PostgresAdapterDeadlineOptions): PostgresWorkerDeadlines;

package/dist/storage/postgresWorkerProtocol.js

@@ -0,0 +1,30 @@
+export const DEFAULT_POSTGRES_WORKER_DEADLINES = {
+    responseTimeoutMs: 20_000,
+    statementTimeoutMs: 15_000,
+    connectionTimeoutMs: 3_000,
+    idleTransactionTimeoutMs: 60_000,
+};
+const MIN_RESPONSE_MARGIN_MS = 100;
+function positiveInteger(value, name) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new Error(`[Taskforce] ${name} must be a positive integer.`);
+    }
+    return parsed;
+}
+export function resolvePostgresWorkerDeadlines(options = {}) {
+    const deadlines = {
+        responseTimeoutMs: positiveInteger(options.responseTimeoutMs ?? DEFAULT_POSTGRES_WORKER_DEADLINES.responseTimeoutMs, 'Postgres worker response timeout'),
+        statementTimeoutMs: positiveInteger(options.statementTimeoutMs ?? DEFAULT_POSTGRES_WORKER_DEADLINES.statementTimeoutMs, 'Postgres statement timeout'),
+        connectionTimeoutMs: positiveInteger(options.connectionTimeoutMs ?? DEFAULT_POSTGRES_WORKER_DEADLINES.connectionTimeoutMs, 'Postgres connection timeout'),
+        idleTransactionTimeoutMs: positiveInteger(options.idleTransactionTimeoutMs ?? DEFAULT_POSTGRES_WORKER_DEADLINES.idleTransactionTimeoutMs, 'Postgres idle transaction timeout'),
+    };
+    if (deadlines.connectionTimeoutMs
+        + deadlines.statementTimeoutMs
+        + MIN_RESPONSE_MARGIN_MS
+        > deadlines.responseTimeoutMs) {
+        throw new Error('[Taskforce] Postgres connection and statement timeouts must together leave at least '
+            + `${MIN_RESPONSE_MARGIN_MS}ms before the worker response timeout.`);
+    }
+    return deadlines;
+}

package/dist/sync/cloudSyncApi.d.ts

@@ -23,10 +23,13 @@ export type WorkspaceContentRequest = Pick<WorkspaceContentManifestEntry, 'kind'
     kind: 'asset';
     assetId: string;
 };
+export type WorkspaceContentMissingRequest = WorkspaceContentRequest & {
+    disposition?: 'retryable' | 'terminal-unavailable';
+};
 export interface WorkspaceContentPullResponse {
     success?: boolean;
     changes?: WorkspaceSyncChange[];
-    missing?: WorkspaceContentRequest[];
+    missing?: WorkspaceContentMissingRequest[];
     remaining?: WorkspaceContentRequest[];
     contentMetadata?: Array<{
         kind: 'document' | 'asset';

package/dist/sync/cloudSyncApi.js

@@ -1,4 +1,4 @@
-import { partitionWorkspaceSyncV2LegacyChanges } from './v3/workspaceSyncV2ProjectionExclusions.js';
+import { normalizeWorkspaceSyncV2ProjectionExclusions, partitionWorkspaceSyncV2LegacyChanges, } from './v3/workspaceSyncV2ProjectionExclusions.js';
 import { validateWorkspaceSyncEngineTransferCompletionGroup, } from './engine/workspaceSyncEngineTransferCompletion.js';
 import { WORKSPACE_SYNC_V3_COMBINED_COVERAGE_SELECTOR, resolveWorkspaceSyncV3CombinedCoverageForExclusions, resolveWorkspaceSyncV3CombinedWireContract } from './v3/workspaceSyncV3CombinedWireContract.js';
 const WORKSPACE_PULL_TIMEOUT_MS = 45_000;
@@ -696,12 +696,17 @@ export async function bootstrapPushWorkspaceSnapshot(resolveCloudAuthUrl, input)
     }));
 }
 export async function applyLocalWorkspaceChanges(workspaceId, changes, options) {
+    const excludedProjections = normalizeWorkspaceSyncV2ProjectionExclusions(options?.excludedProjections || []);
+    const combinedCoverage = excludedProjections.length
+        ? resolveWorkspaceSyncV3CombinedCoverageForExclusions(excludedProjections)
+        : null;
     const applyPayload = JSON.stringify({
         workspaceId,
         changes,
         workspaceMembers: Array.isArray(options?.workspaceMembers) ? options.workspaceMembers : undefined,
         ...(options?.repairMode === true ? { repair: true } : {}),
-        excludedProjections: options?.excludedProjections,
+        excludedProjections,
+        ...(combinedCoverage ? { combinedCoverage } : {}),
         contentPullObligations: options?.contentPullObligations,
         contentPullResolutionClaims: options?.contentPullResolutionClaims,
         ...localBrowserApplyPermitContext(workspaceId, options),

package/dist/sync/contentSyncState.d.ts

@@ -130,7 +130,7 @@ export declare function createContentSyncState(deps: ContentSyncStateDeps): {
         activeLinks: WorkspaceAssetLinkEntry[];
         effectiveUpdatedAt: string;
     };
-    getCanonicalSyncDocumentMetadata: (relativePath: string, workspaceId: string) => Omit<DocumentSyncPayload, "path" | "updatedAt" | "content">;
+    getCanonicalSyncDocumentMetadata: (relativePath: string, workspaceId: string) => Omit<DocumentSyncPayload, "updatedAt" | "path" | "content">;
     hasDocumentSyncMetadataDrift: (workspaceId: string, doc: DocumentSyncPayload, _options?: {
         allowReferenceNumberReassignment?: boolean;
     }) => boolean;

package/dist/sync/coordinator/localSyncExecutionPermitStore.d.ts

@@ -152,6 +152,7 @@ export declare class LocalSyncExecutionPermitStore {
         coordinatorGeneration: number;
         serverInstanceId: string;
         errorCode?: string;
+        readResponseUnavailableBeforeApply?: boolean;
     }): LocalSyncExecutionPermit;
     recoverExpiredPermits(input: {
         currentServerInstanceId: string;

package/dist/sync/coordinator/localSyncExecutionPermitStore.js

@@ -619,9 +619,15 @@ export class LocalSyncExecutionPermitStore {
             if (current.state === 'local-commit-entered') {
                 throw new LocalSyncExecutionPermitError(`Execution permit ${input.permitId} is owned by the server local commit.`, 'SYNC_COORDINATOR_PERMIT_STATE_CONFLICT');
             }
+            const cleanReadFailure = input.readResponseUnavailableBeforeApply === true
+                && input.errorCode === 'SYNC_COORDINATOR_GATEWAY_REQUEST_FAILED'
+                && current.state === 'gateway-complete-awaiting-apply'
+                && current.upstreamDisposition === 'unknown'
+                && (current.operationClass === 'pull' || current.operationClass === 'repair');
             const clean = current.state === 'issued-idle'
                 || (current.state === 'gateway-complete-awaiting-apply'
-                    && current.upstreamDisposition === 'rejected');
+                    && current.upstreamDisposition === 'rejected')
+                || cleanReadFailure;
             const disposition = current.upstreamDisposition === 'accepted'
                 ? 'accepted'
                 : current.upstreamDisposition === 'rejected'

package/dist/sync/coordinator/localWorkspaceSyncRunner.js

@@ -17,6 +17,10 @@ const RUNNER_COMMANDS = new Set([
 ]);
 const SCHEDULED_RETRY_BASE_DELAY_MS = 1_000;
 const SCHEDULED_RETRY_MAX_DELAY_MS = 5 * 60_000;
+const CONTENT_PREREQUISITE_BYPASSED_RETRY_KINDS = new Set([
+    'pull',
+    'repair',
+]);
 function cloneCheckpoint(checkpoint) {
     return JSON.parse(canonicalWorkspaceSyncJson(checkpoint));
 }
@@ -159,7 +163,7 @@ export class LocalWorkspaceSyncRunner {
         if (!this.context || this.terminated || !this.acceptingWork) {
             return Promise.resolve();
         }
-        return this.enqueue(async () => this.runInspection(this.options.operations.pushContentPrerequisite, { bypassRetryKind: 'repair' }));
+        return this.enqueue(async () => this.runInspection(this.options.operations.pushContentPrerequisite, { bypassRetryKinds: CONTENT_PREREQUISITE_BYPASSED_RETRY_KINDS }));
     }
     observeRemoteHint(observedAt = this.now()) {
         if (!this.context || this.terminated || !this.acceptingWork) {
@@ -476,7 +480,7 @@ export class LocalWorkspaceSyncRunner {
         if (!state.checkpoint.syncEnabled || !this.hasExactCapability(context))
             return;
         if (state.checkpoint.retry
-            && state.checkpoint.retry.kind !== options.bypassRetryKind
+            && !options.bypassRetryKinds?.has(state.checkpoint.retry.kind)
             && Date.parse(state.checkpoint.retry.retryAt) > Date.parse(this.now())) {
             this.schedulePersistedRetry(state, this.lifecycleToken);
             return;

package/dist/sync/engine/workspaceSyncEngineBrowserGatewayRemoteServices.js

@@ -40,6 +40,18 @@ function v3Boundary(input) {
         ...(input.coverage ? { coverage: { ...input.coverage } } : {}),
     };
 }
+function independentContentBoundary(identity) {
+    const normalizedIdentity = String(identity || '').trim();
+    if (!normalizedIdentity) {
+        throw new TypeError('Independent content transfer identity is required.');
+    }
+    return {
+        version: 1,
+        projection: 'independent-content',
+        cursor: null,
+        identity: normalizedIdentity,
+    };
+}
 async function decodeGatewayResponse(response, nowMs) {
     const rawText = await response.text();
     let data = {};
@@ -405,10 +417,12 @@ export function createBrowserGatewayWorkspaceSyncEngineRemoteServices(options) {
             });
         },
         pullWorkspaceContent: (input) => {
-            const { previousCursor, ...request } = input;
+            const { previousCursor, independentCompletionIdentity, ...request } = input;
             return execute({
                 operation: { type: 'content-pull', ...request },
-                previousBoundary: v2Boundary(previousCursor),
+                previousBoundary: independentCompletionIdentity
+                    ? independentContentBoundary(independentCompletionIdentity)
+                    : v2Boundary(previousCursor),
                 applying: true,
             });
         },
@@ -510,6 +524,10 @@ export function createBrowserGatewayWorkspaceSyncEngineRemoteServices(options) {
             }));
         },
         buildV2ApplyCompletionGroup: ({ workspaceId, previousCursor, nextCursor, receipts, }) => completionGroup(workspaceId, receipts, v2Boundary(previousCursor), v2Boundary(nextCursor)),
+        buildIndependentContentApplyCompletionGroup: ({ workspaceId, identity, receipts, }) => {
+            const boundary = independentContentBoundary(identity);
+            return completionGroup(workspaceId, receipts, boundary, boundary);
+        },
         buildV2PushApplyCompletionGroup: ({ workspaceId, pushBoundary, receipts, }) => completionGroup(workspaceId, receipts, parseWorkspaceSyncEngineV2PushBoundary(pushBoundary), parseWorkspaceSyncEngineV2PushBoundary(pushBoundary)),
         buildV3ApplyCompletionGroup: ({ workspaceId, apply, receipts }) => {
             const metadata = readReceipts(workspaceId, receipts);

package/dist/sync/engine/workspaceSyncEngineLocalServices.d.ts

@@ -24,6 +24,10 @@ export interface WorkspaceSyncEngineV2ApplyOptions {
 export interface WorkspaceSyncEngineV3ApplyOptions {
     completionGroup?: WorkspaceSyncEngineTransferCompletionGroup;
 }
+export declare function authoritativeV2ApplyFailureMessage(input: {
+    status?: number;
+    data?: unknown;
+}): string;
 /**
  * Local-runtime operations used by the workspace sync engine.
  *

package/dist/sync/engine/workspaceSyncEngineLocalServices.js

@@ -1,5 +1,16 @@
 import { applyLocalWorkspaceChanges, applyLocalWorkspaceSyncV3CombinedProjection, applyLocalWorkspaceSyncV3Projection, applyLocalWorkspaceSyncV3TaskCommentAudit, completeLocalSyncAuthoritativeRepair, getLocalWorkspaceContentPullObligations, recordLocalWorkspaceContentPullObligationFailures, getLocalTaskMetadataOwnership, getLocalWorkspaceContentManifest, getLocalWorkspaceSyncV3CombinedProjection, getLocalWorkspaceSyncV3Projection, getLocalWorkspaceSyncV3TaskCommentAudit, } from '../cloudSyncApi.js';
 import { prepareLocalTaskRootOutboxRecovery, } from '../v3/localOutboxRecoveryClient.js';
+export function authoritativeV2ApplyFailureMessage(input) {
+    const data = input.data && typeof input.data === 'object' && !Array.isArray(input.data)
+        ? input.data
+        : {};
+    const detail = String(data.error || '').trim();
+    const code = String(data.code || '').trim();
+    const status = Number(input.status) || 0;
+    return detail
+        ? `Authoritative V2 push echo apply failed (${status}): ${detail}${code ? ` [${code}]` : ''}`
+        : `Authoritative V2 push echo apply failed (${status}).`;
+}
 /**
  * Same-origin HTTP implementation used while the browser owns orchestration.
  */

package/dist/sync/engine/workspaceSyncEngineRemoteServices.d.ts

@@ -37,6 +37,12 @@ export type WorkspaceSyncEngineContentPullInput = Parameters<typeof pullWorkspac
      * commit against one exact prior boundary.
      */
     previousCursor: string | null;
+    /**
+     * Separates an independent content lookup from a V2 feed page. The
+     * identity becomes an apply boundary that settles the transfer
+     * without advancing or validating the runner's V2 cursor.
+     */
+    independentCompletionIdentity?: string;
 };
 type RemoteResult<Result> = Awaited<Result> & {
     transferReceipt?: WorkspaceSyncEngineRemoteTransferReceipt;
@@ -94,6 +100,11 @@ export interface WorkspaceSyncEngineRemoteServices {
         nextCursor: string | null;
         receipts: readonly WorkspaceSyncEngineRemoteTransferReceipt[];
     }): WorkspaceSyncEngineTransferCompletionGroup | undefined;
+    buildIndependentContentApplyCompletionGroup(input: {
+        workspaceId: string;
+        identity: string;
+        receipts: readonly WorkspaceSyncEngineRemoteTransferReceipt[];
+    }): WorkspaceSyncEngineTransferCompletionGroup | undefined;
     buildV2PushApplyCompletionGroup(input: {
         workspaceId: string;
         pushBoundary: WorkspaceSyncEngineV2PushBoundary;

package/dist/sync/engine/workspaceSyncEngineRemoteServices.js

@@ -6,7 +6,7 @@ export function createBrowserWorkspaceSyncEngineRemoteServices(resolveCloudAuthU
         provisionWorkspace: (input) => provisionWorkspace(resolveCloudAuthUrl, input),
         pushWorkspaceChanges: ({ ownership: _ownership, pushBoundary: _pushBoundary, ...input }) => (pushWorkspaceChanges(resolveCloudAuthUrl, input)),
         pullWorkspaceChanges: (input) => pullWorkspaceChanges(resolveCloudAuthUrl, input),
-        pullWorkspaceContent: ({ previousCursor: _previousCursor, ...input }) => (pullWorkspaceContent(resolveCloudAuthUrl, input)),
+        pullWorkspaceContent: ({ previousCursor: _previousCursor, independentCompletionIdentity: _independentCompletionIdentity, ...input }) => (pullWorkspaceContent(resolveCloudAuthUrl, input)),
         pullInitiativeFeed: (input) => pullWorkspaceSyncV3Feed(resolveCloudAuthUrl, input),
         pullInitiativeRepair: (input) => pullWorkspaceInitiativeRepair(resolveCloudAuthUrl, input),
         pullCombinedFeed: (input) => pullWorkspaceSyncV3CombinedFeed(resolveCloudAuthUrl, input),
@@ -15,6 +15,7 @@ export function createBrowserWorkspaceSyncEngineRemoteServices(resolveCloudAuthU
         abandonTransferReceipts: () => undefined,
         acknowledgeNonApplyingTransferReceipts: () => undefined,
         buildV2ApplyCompletionGroup: () => undefined,
+        buildIndependentContentApplyCompletionGroup: () => undefined,
         buildV2PushApplyCompletionGroup: () => undefined,
         buildV3ApplyCompletionGroup: () => undefined,
     };

package/dist/sync/engine/workspaceSyncEngineServerRemoteServices.js

@@ -40,6 +40,18 @@ function v3Boundary(input) {
         ...(input.coverage ? { coverage: { ...input.coverage } } : {}),
     };
 }
+function independentContentBoundary(identity) {
+    const normalizedIdentity = String(identity || '').trim();
+    if (!normalizedIdentity) {
+        throw new TypeError('Independent content transfer identity is required.');
+    }
+    return {
+        version: 1,
+        projection: 'independent-content',
+        cursor: null,
+        identity: normalizedIdentity,
+    };
+}
 function decodeGatewayResult(result, nowMs) {
     const rawText = new TextDecoder().decode(result.body);
     let data = {};
@@ -96,12 +108,15 @@ export function createServerWorkspaceSyncEngineRemoteServices(options) {
             throw new TypeError('The server sync operation workspace does not match its runner.');
         }
     };
-    const abandon = (permitId, errorCode) => (options.permitStore.abandonPermit({
+    const abandon = (permitId, errorCode, readResponseUnavailableBeforeApply = false) => (options.permitStore.abandonPermit({
         permitId,
         workspaceId: options.workspaceId,
         coordinatorGeneration: options.coordinatorGeneration,
         serverInstanceId: options.serverInstanceId,
         errorCode,
+        ...(readResponseUnavailableBeforeApply
+            ? { readResponseUnavailableBeforeApply: true }
+            : {}),
     }));
     const execute = async (input) => {
         assertWorkspace(input.operation.workspaceId);
@@ -131,7 +146,7 @@ export function createServerWorkspaceSyncEngineRemoteServices(options) {
             });
         }
         catch (error) {
-            abandon(permit.permitId, 'SYNC_COORDINATOR_GATEWAY_REQUEST_FAILED');
+            abandon(permit.permitId, 'SYNC_COORDINATOR_GATEWAY_REQUEST_FAILED', operationClass === 'pull' || operationClass === 'repair');
             throw error;
         }
         const decoded = decodeGatewayResult(gatewayResult, issuedAt.getTime());
@@ -171,6 +186,12 @@ export function createServerWorkspaceSyncEngineRemoteServices(options) {
             abandon(permit.permitId, 'SYNC_COORDINATOR_APPLYING_REJECTED');
             return result;
         }
+        if (!result.ok
+            && completedPermit.upstreamDisposition === 'unknown'
+            && (operationClass === 'pull' || operationClass === 'repair')) {
+            abandon(permit.permitId, 'SYNC_COORDINATOR_GATEWAY_REQUEST_FAILED', true);
+            return result;
+        }
         if (!input.previousBoundary) {
             abandon(permit.permitId, 'SYNC_COORDINATOR_APPLY_BOUNDARY_MISSING');
             throw new Error('A server applying request did not declare its prior boundary.');
@@ -319,10 +340,12 @@ export function createServerWorkspaceSyncEngineRemoteServices(options) {
             });
         },
         pullWorkspaceContent: (input) => {
-            const { previousCursor, ...request } = input;
+            const { previousCursor, independentCompletionIdentity, ...request } = input;
             return execute({
                 operation: { type: 'content-pull', ...request },
-                previousBoundary: v2Boundary(previousCursor),
+                previousBoundary: independentCompletionIdentity
+                    ? independentContentBoundary(independentCompletionIdentity)
+                    : v2Boundary(previousCursor),
                 applying: true,
             });
         },
@@ -433,6 +456,10 @@ export function createServerWorkspaceSyncEngineRemoteServices(options) {
             }
         },
         buildV2ApplyCompletionGroup: ({ workspaceId, previousCursor, nextCursor, receipts, }) => completionGroup(workspaceId, receipts, v2Boundary(previousCursor), v2Boundary(nextCursor)),
+        buildIndependentContentApplyCompletionGroup: ({ workspaceId, identity, receipts, }) => {
+            const boundary = independentContentBoundary(identity);
+            return completionGroup(workspaceId, receipts, boundary, boundary);
+        },
         buildV2PushApplyCompletionGroup: ({ workspaceId, pushBoundary, receipts, }) => completionGroup(workspaceId, receipts, parseWorkspaceSyncEngineV2PushBoundary(pushBoundary), parseWorkspaceSyncEngineV2PushBoundary(pushBoundary)),
         buildV3ApplyCompletionGroup: ({ workspaceId, apply, receipts }) => {
             const metadata = readReceipts(workspaceId, receipts);

package/dist/sync/engine/workspaceSyncEngineServerRunnerOperations.d.ts

@@ -2,7 +2,7 @@ import type { LocalWorkspaceSyncRunnerOperations } from '../coordinator/localWor
 import { type EnsureWorkspaceReadyResult } from '../syncService.js';
 import type { WorkspaceSyncV2ProjectionExclusion } from '../v3/workspaceSyncV2ProjectionExclusions.js';
 import type { WorkspaceSyncV3CombinedCoverageSelector } from '../v3/workspaceSyncV3CombinedWireContract.js';
-import type { WorkspaceSyncEngineLocalServices } from './workspaceSyncEngineLocalServices.js';
+import { type WorkspaceSyncEngineLocalServices } from './workspaceSyncEngineLocalServices.js';
 import type { WorkspaceSyncEngineRemoteServices } from './workspaceSyncEngineRemoteServices.js';
 import type { WorkspaceSyncEngineServerPushCandidateProvider } from './workspaceSyncEngineServerSnapshotReader.js';
 import type { WorkspaceSyncEngineServerCheckpointPort } from './workspaceSyncEngineServerApplyBoundary.js';
@@ -46,11 +46,13 @@ export interface WorkspaceSyncEngineServerAttachmentApplyPort {
         } | {
             success: false;
             error: string;
+            disposition?: 'retryable' | 'terminal-unavailable';
         }>;
     }): Promise<{
         attempted: number;
         resolved: number;
         remaining: number;
+        terminal: number;
         nextAttemptAt: string | null;
         lastError: string | null;
     }>;