@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/sync/v3/workflowRuntimeSync.js

@@ -0,0 +1,485 @@
+import { projectWorkflowExecutionEvents } from '../../storage/workflowStore.js';
+import { normalizeWorkflowExecutionEventSyncRecord, normalizeWorkflowExecutionSyncRecord, normalizeWorkflowStepSyncRecord, normalizeWorkflowVersionSyncRecord, WorkflowAssignmentSyncError, } from './workflowAssignmentSync.js';
+import { normalizeTaskSyncPayload, } from '../taskSyncPayload.js';
+import { fingerprintWorkspaceSyncPayload, WORKSPACE_SYNC_CONTRACT_VERSION, } from './syncDurabilityStore.js';
+export const WORKFLOW_RUNTIME_SYNC_SCHEMA_VERSION = 1;
+export const WORKFLOW_PUBLISHED_DEFINITION_SYNC_SCHEMA_VERSION = 2;
+/**
+ * Dark projection inventory for T-1295. These descriptors are intentionally
+ * absent from the active coverage registry until the workflow runtime has
+ * complete writer, feed, repair, and apply support.
+ */
+export const WORKSPACE_SYNC_V3_WORKFLOW_RUNTIME_PROJECTIONS = Object.freeze([
+    Object.freeze({
+        projectionId: 'workflow-published-definition/full-v2',
+        domain: 'workflow-published-definition',
+        schemaVersion: WORKFLOW_PUBLISHED_DEFINITION_SYNC_SCHEMA_VERSION,
+        mutationKinds: Object.freeze(['publish']),
+        fields: Object.freeze(['template', 'version', 'steps']),
+        dependencies: Object.freeze([]),
+        operationAtomic: true,
+    }),
+    Object.freeze({
+        projectionId: 'workflow-execution/root-v1',
+        domain: 'workflow-execution',
+        schemaVersion: WORKFLOW_RUNTIME_SYNC_SCHEMA_VERSION,
+        mutationKinds: Object.freeze(['create', 'transition', 'complete-step']),
+        fields: Object.freeze(['execution']),
+        dependencies: Object.freeze([
+            'task/root-v1',
+            'workflow-published-definition/full-v2',
+        ]),
+        operationAtomic: true,
+    }),
+    Object.freeze({
+        projectionId: 'workflow-execution-event/full-v1',
+        domain: 'workflow-execution-event',
+        schemaVersion: WORKFLOW_RUNTIME_SYNC_SCHEMA_VERSION,
+        mutationKinds: Object.freeze(['append']),
+        fields: Object.freeze(['event']),
+        dependencies: Object.freeze([
+            'workflow-published-definition/full-v2',
+            'workflow-execution/root-v1',
+        ]),
+        operationAtomic: true,
+    }),
+]);
+function object(value, field) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new WorkflowAssignmentSyncError(`${field} must be an object.`);
+    }
+    return value;
+}
+function text(value, field) {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    if (!normalized)
+        throw new WorkflowAssignmentSyncError(`${field} is required.`);
+    return normalized;
+}
+function assertSame(value, expected, field) {
+    if (value !== expected) {
+        throw new WorkflowAssignmentSyncError(`${field} does not match its workflow dependency.`);
+    }
+}
+function canonicalSteps(raw) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new WorkflowAssignmentSyncError('workflowDefinition.steps are required.');
+    }
+    const steps = raw.map(normalizeWorkflowStepSyncRecord)
+        .sort((left, right) => left.position - right.position || left.id.localeCompare(right.id));
+    const ids = new Set();
+    const positions = new Set();
+    for (const step of steps) {
+        if (ids.has(step.id))
+            throw new WorkflowAssignmentSyncError('Workflow definition has a duplicate step id.');
+        if (positions.has(step.position)) {
+            throw new WorkflowAssignmentSyncError('Workflow definition has a duplicate step position.');
+        }
+        ids.add(step.id);
+        positions.add(step.position);
+    }
+    return steps;
+}
+function normalizePublishedTemplateIdentity(raw) {
+    const value = object(raw, 'workflowDefinition.template');
+    return {
+        id: text(value.id, 'workflowDefinition.template.id'),
+        tenantId: text(value.tenantId, 'workflowDefinition.template.tenantId'),
+        workspaceId: text(value.workspaceId, 'workflowDefinition.template.workspaceId'),
+    };
+}
+export function serializeWorkflowPublishedDefinitionSyncPayload(input) {
+    return validateWorkflowPublishedDefinitionSyncPayload(input, { requireCanonicalOrder: false });
+}
+export function validateWorkflowPublishedDefinitionSyncPayload(raw, options = {}) {
+    const value = object(raw, 'workflowDefinition');
+    const template = normalizePublishedTemplateIdentity(value.template);
+    const version = normalizeWorkflowVersionSyncRecord(value.version);
+    const sourceSteps = Array.isArray(value.steps)
+        ? value.steps.map(normalizeWorkflowStepSyncRecord)
+        : [];
+    const steps = canonicalSteps(value.steps);
+    assertSame(version.tenantId, template.tenantId, 'workflowDefinition.version.tenantId');
+    assertSame(version.workspaceId, template.workspaceId, 'workflowDefinition.version.workspaceId');
+    assertSame(version.workflowTemplateId, template.id, 'workflowDefinition.version.workflowTemplateId');
+    for (const step of steps) {
+        assertSame(step.tenantId, template.tenantId, `workflowDefinition step ${step.id} tenantId`);
+        assertSame(step.workspaceId, template.workspaceId, `workflowDefinition step ${step.id} workspaceId`);
+        assertSame(step.workflowVersionId, version.id, `workflowDefinition step ${step.id} workflowVersionId`);
+    }
+    if (options.requireCanonicalOrder !== false
+        && sourceSteps.some((step, index) => step.id !== steps[index]?.id)) {
+        throw new WorkflowAssignmentSyncError('Workflow definition steps are not canonically ordered.');
+    }
+    return { template, version, steps };
+}
+export function serializeWorkflowExecutionRootSyncPayload(execution) {
+    return validateWorkflowExecutionRootSyncPayload({ execution });
+}
+export function validateWorkflowExecutionRootSyncPayload(raw) {
+    const value = object(raw, 'workflowExecutionRoot');
+    return { execution: normalizeWorkflowExecutionSyncRecord(value.execution) };
+}
+export function serializeWorkflowExecutionEventSyncPayload(event) {
+    return validateWorkflowExecutionEventSyncPayload({ event });
+}
+export function validateWorkflowExecutionEventSyncPayload(raw) {
+    const value = object(raw, 'workflowExecutionEvent');
+    const rawEvent = object(value.event, 'workflowExecutionEvent.event');
+    object(rawEvent.details, 'workflowExecutionEvent.event.details');
+    const event = normalizeWorkflowExecutionEventSyncRecord(value.event, 0);
+    // Canonical JSON validation rejects unsupported values in event details.
+    fingerprintWorkspaceSyncPayload(event);
+    return { event };
+}
+export function validateWorkflowRuntimeEventHistory(input) {
+    const execution = normalizeWorkflowExecutionSyncRecord(input.execution);
+    if (!Array.isArray(input.events) || input.events.length === 0) {
+        throw new WorkflowAssignmentSyncError('Workflow execution history is required.');
+    }
+    for (const [index, rawEvent] of input.events.entries()) {
+        const eventValue = object(rawEvent, `workflowExecutionHistory.events[${index}]`);
+        object(eventValue.details, `workflowExecutionHistory.events[${index}].details`);
+    }
+    const sourceEvents = input.events.map(normalizeWorkflowExecutionEventSyncRecord);
+    const events = [...sourceEvents]
+        .sort((left, right) => left.sequenceNumber - right.sequenceNumber || left.id.localeCompare(right.id));
+    if (sourceEvents.some((event, index) => event.id !== events[index]?.id)) {
+        throw new WorkflowAssignmentSyncError('Workflow history events are not canonically ordered.');
+    }
+    const ids = new Set();
+    const idempotencyKeys = new Set();
+    for (const [index, event] of events.entries()) {
+        assertSame(event.tenantId, execution.tenantId, `workflow event ${event.id} tenantId`);
+        assertSame(event.workspaceId, execution.workspaceId, `workflow event ${event.id} workspaceId`);
+        assertSame(event.workflowExecutionId, execution.id, `workflow event ${event.id} workflowExecutionId`);
+        if (ids.has(event.id))
+            throw new WorkflowAssignmentSyncError('Workflow history has a duplicate event id.');
+        if (event.sequenceNumber !== index) {
+            throw new WorkflowAssignmentSyncError('Workflow history event sequence must be contiguous from zero.');
+        }
+        if (event.idempotencyKey && idempotencyKeys.has(event.idempotencyKey)) {
+            throw new WorkflowAssignmentSyncError('Workflow history has a duplicate idempotency key.');
+        }
+        ids.add(event.id);
+        if (event.idempotencyKey)
+            idempotencyKeys.add(event.idempotencyKey);
+    }
+    let projection;
+    try {
+        projection = projectWorkflowExecutionEvents(events);
+    }
+    catch {
+        throw new WorkflowAssignmentSyncError('Workflow execution history has an invalid transition chain.');
+    }
+    const rootProjection = {
+        status: execution.status,
+        currentStepId: execution.currentStepId || null,
+        startedAt: execution.startedAt || null,
+        completedAt: execution.completedAt || null,
+        endedAt: execution.endedAt || null,
+        updatedAt: execution.updatedAt,
+    };
+    const historyProjection = {
+        status: projection.status,
+        currentStepId: projection.currentStepId || null,
+        startedAt: projection.startedAt || null,
+        completedAt: projection.completedAt || null,
+        endedAt: projection.endedAt || null,
+        updatedAt: projection.updatedAt,
+    };
+    if (fingerprintWorkspaceSyncPayload(rootProjection) !== fingerprintWorkspaceSyncPayload(historyProjection)) {
+        throw new WorkflowAssignmentSyncError('Workflow execution root does not match its event history.');
+    }
+    return events;
+}
+export function fingerprintWorkflowRuntimePayload(payload) {
+    return fingerprintWorkspaceSyncPayload(payload);
+}
+const TRANSITION_ACTIONS = new Set([
+    'start', 'pause', 'resume', 'complete', 'fail', 'end',
+]);
+const TRANSITION_EXPECTED_STATUSES = {
+    start: new Set(['pending']),
+    pause: new Set(['running']),
+    resume: new Set(['paused']),
+    complete: new Set(['running']),
+    fail: new Set(['pending', 'running', 'paused']),
+    end: new Set(['pending', 'running', 'paused']),
+};
+const EXECUTION_STATUSES = new Set([
+    'pending', 'running', 'paused', 'completed', 'failed', 'ended',
+]);
+export function validateWorkflowRuntimeMutationCommand(raw) {
+    const value = object(raw, 'workflowRuntimeCommand');
+    if (value.contractVersion !== WORKSPACE_SYNC_CONTRACT_VERSION) {
+        throw new WorkflowAssignmentSyncError('Workflow runtime command contract version is invalid.');
+    }
+    const executionId = text(value.executionId, 'workflowRuntimeCommand.executionId');
+    const actorId = text(value.actorId, 'workflowRuntimeCommand.actorId');
+    const actorType = value.actorType === 'agent' ? 'agent' : value.actorType === 'user' ? 'user' : null;
+    if (!actorType)
+        throw new WorkflowAssignmentSyncError('Workflow runtime command actor type is invalid.');
+    const idempotencyKey = text(value.idempotencyKey, 'workflowRuntimeCommand.idempotencyKey');
+    const occurredAt = text(value.occurredAt, 'workflowRuntimeCommand.occurredAt');
+    if (!Number.isFinite(Date.parse(occurredAt)) || new Date(occurredAt).toISOString() !== occurredAt) {
+        throw new WorkflowAssignmentSyncError('Workflow runtime command occurredAt is invalid.');
+    }
+    const expectedStatus = text(value.expectedStatus, 'workflowRuntimeCommand.expectedStatus');
+    if (!EXECUTION_STATUSES.has(expectedStatus)) {
+        throw new WorkflowAssignmentSyncError('Workflow runtime command expected status is invalid.');
+    }
+    if (value.kind === 'transition') {
+        const action = text(value.action, 'workflowRuntimeCommand.action');
+        if (!TRANSITION_ACTIONS.has(action)) {
+            throw new WorkflowAssignmentSyncError('Workflow runtime transition action is invalid.');
+        }
+        if (!TRANSITION_EXPECTED_STATUSES[action].has(expectedStatus)) {
+            throw new WorkflowAssignmentSyncError('Workflow runtime transition action does not allow the expected status.');
+        }
+        const details = value.details === undefined ? {} : object(value.details, 'workflowRuntimeCommand.details');
+        fingerprintWorkspaceSyncPayload(details);
+        return {
+            contractVersion: WORKSPACE_SYNC_CONTRACT_VERSION,
+            kind: 'transition',
+            executionId,
+            action,
+            expectedStatus,
+            actorId,
+            actorType,
+            idempotencyKey,
+            occurredAt,
+            details,
+        };
+    }
+    if (value.kind === 'complete-step') {
+        if (expectedStatus !== 'running') {
+            throw new WorkflowAssignmentSyncError('Workflow step completion requires running status.');
+        }
+        const rawTaskTarget = object(value.taskTarget, 'workflowRuntimeCommand.taskTarget');
+        return {
+            contractVersion: WORKSPACE_SYNC_CONTRACT_VERSION,
+            kind: 'complete-step',
+            executionId,
+            expectedStatus: 'running',
+            expectedStepId: text(value.expectedStepId, 'workflowRuntimeCommand.expectedStepId'),
+            actorId,
+            actorType,
+            idempotencyKey,
+            occurredAt,
+            ...(value.evidenceCommentId == null ? {} : {
+                evidenceCommentId: text(value.evidenceCommentId, 'workflowRuntimeCommand.evidenceCommentId'),
+            }),
+            taskTarget: {
+                taskId: text(rawTaskTarget.taskId, 'workflowRuntimeCommand.taskTarget.taskId'),
+                baseEntityRevision: revision(rawTaskTarget.baseEntityRevision, 'workflowRuntimeCommand.taskTarget.baseEntityRevision'),
+                baseLifecycleRevision: revision(rawTaskTarget.baseLifecycleRevision, 'workflowRuntimeCommand.taskTarget.baseLifecycleRevision'),
+            },
+        };
+    }
+    throw new WorkflowAssignmentSyncError('Workflow runtime command kind is invalid.');
+}
+function revision(value, field) {
+    const normalized = text(value, field);
+    if (!/^\d+$/.test(normalized)) {
+        throw new WorkflowAssignmentSyncError(`${field} must be an unsigned decimal revision.`);
+    }
+    return BigInt(normalized).toString(10);
+}
+function positiveSequence(value, field) {
+    const normalized = revision(value, field);
+    if (BigInt(normalized) < 1n) {
+        throw new WorkflowAssignmentSyncError(`${field} must be positive.`);
+    }
+    return normalized;
+}
+function fingerprint(value, field) {
+    const normalized = text(value, field).toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(normalized)) {
+        throw new WorkflowAssignmentSyncError(`${field} must be a SHA-256 fingerprint.`);
+    }
+    return normalized;
+}
+function canonicalIso(value, field) {
+    const normalized = text(value, field);
+    const timestamp = Date.parse(normalized);
+    if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== normalized) {
+        throw new WorkflowAssignmentSyncError(`${field} must be a canonical ISO timestamp.`);
+    }
+    return normalized;
+}
+function validateWorkflowRuntimeTaskResult(raw) {
+    const value = object(raw, 'workflowRuntimeResult.task');
+    const payload = normalizeTaskSyncPayload(value.payload);
+    if (!payload) {
+        throw new WorkflowAssignmentSyncError('workflowRuntimeResult.task.payload is invalid.');
+    }
+    const rawActivity = object(value.activity, 'workflowRuntimeResult.task.activity');
+    const actorType = text(rawActivity.actorType, 'workflowRuntimeResult.task.activity.actorType');
+    if (!['human', 'ai', 'system'].includes(actorType)) {
+        throw new WorkflowAssignmentSyncError('workflowRuntimeResult.task.activity.actorType is invalid.');
+    }
+    const details = rawActivity.details;
+    if (details !== undefined && (!details || typeof details !== 'object' || Array.isArray(details))) {
+        throw new WorkflowAssignmentSyncError('workflowRuntimeResult.task.activity.details must be an object.');
+    }
+    const activity = {
+        id: text(rawActivity.id, 'workflowRuntimeResult.task.activity.id'),
+        workspaceId: text(rawActivity.workspaceId, 'workflowRuntimeResult.task.activity.workspaceId'),
+        entityType: 'task',
+        entityId: text(rawActivity.entityId, 'workflowRuntimeResult.task.activity.entityId'),
+        taskId: text(rawActivity.taskId, 'workflowRuntimeResult.task.activity.taskId'),
+        action: text(rawActivity.action, 'workflowRuntimeResult.task.activity.action'),
+        actor: text(rawActivity.actor, 'workflowRuntimeResult.task.activity.actor'),
+        actorType,
+        ...(details === undefined ? {} : { details: details }),
+        createdAt: canonicalIso(rawActivity.createdAt, 'workflowRuntimeResult.task.activity.createdAt'),
+    };
+    if (rawActivity.entityType !== 'task'
+        || activity.entityId !== payload.id
+        || activity.taskId !== payload.id
+        || activity.workspaceId.trim().length === 0
+        || activity.action !== 'task-updated'
+        || activity.createdAt !== payload.updatedAt) {
+        throw new WorkflowAssignmentSyncError('Workflow runtime task activity does not match its authoritative task.');
+    }
+    const changes = activity.details?.changes;
+    const assigneeChange = changes?.assignee;
+    const assignee = typeof payload.assignee === 'string' ? payload.assignee.trim() : '';
+    const validAssigneeValue = (candidate) => (candidate === null || typeof candidate === 'string');
+    if (!assignee || assignee.toLowerCase() === 'unassigned'
+        || !assigneeChange || typeof assigneeChange !== 'object' || Array.isArray(assigneeChange)
+        || !validAssigneeValue(assigneeChange.from)
+        || !validAssigneeValue(assigneeChange.to)
+        || String(assigneeChange.to || '').trim() !== assignee) {
+        throw new WorkflowAssignmentSyncError('Workflow runtime task activity assignee provenance is invalid.');
+    }
+    return { payload, activity };
+}
+export function validateWorkflowRuntimeAuthoritativeResult(raw) {
+    const value = object(raw, 'workflowRuntimeResult');
+    if (typeof value.replayed !== 'boolean') {
+        throw new WorkflowAssignmentSyncError('workflowRuntimeResult.replayed must be a boolean.');
+    }
+    const execution = validateWorkflowExecutionRootSyncPayload(value.execution);
+    if (!Array.isArray(value.events) || value.events.length === 0) {
+        throw new WorkflowAssignmentSyncError('workflowRuntimeResult.events are required.');
+    }
+    const events = value.events.map(validateWorkflowExecutionEventSyncPayload);
+    validateWorkflowRuntimeEventHistory({
+        execution: execution.execution,
+        events: events.map((entry) => entry.event),
+    });
+    if (!Array.isArray(value.acceptedEventIds) || value.acceptedEventIds.length === 0) {
+        throw new WorkflowAssignmentSyncError('workflowRuntimeResult.acceptedEventIds are required.');
+    }
+    const acceptedEventIds = value.acceptedEventIds.map((eventId, index) => (text(eventId, `workflowRuntimeResult.acceptedEventIds[${index}]`)));
+    if (new Set(acceptedEventIds).size !== acceptedEventIds.length) {
+        throw new WorkflowAssignmentSyncError('Workflow runtime result has duplicate accepted event ids.');
+    }
+    const terminalEventIds = events
+        .slice(events.length - acceptedEventIds.length)
+        .map((entry) => entry.event.id);
+    if (acceptedEventIds.some((eventId, index) => eventId !== terminalEventIds[index])) {
+        throw new WorkflowAssignmentSyncError('Workflow runtime accepted events must be the contiguous terminal history suffix.');
+    }
+    const definition = value.definition === undefined
+        ? undefined
+        : validateWorkflowPublishedDefinitionSyncPayload(value.definition);
+    if (definition) {
+        assertSame(definition.template.id, execution.execution.workflowTemplateId, 'workflowRuntimeResult definition template id');
+        assertSame(definition.version.id, execution.execution.workflowVersionId, 'workflowRuntimeResult definition version id');
+        assertSame(definition.template.tenantId, execution.execution.tenantId, 'workflowRuntimeResult definition tenantId');
+        assertSame(definition.template.workspaceId, execution.execution.workspaceId, 'workflowRuntimeResult definition workspaceId');
+    }
+    let task;
+    if (value.task !== undefined) {
+        task = validateWorkflowRuntimeTaskResult(value.task);
+        assertSame(task.payload.id, execution.execution.taskId, 'workflowRuntimeResult task id');
+        assertSame(task.activity.workspaceId, execution.execution.workspaceId, 'workflowRuntimeResult task activity workspace id');
+    }
+    if (!Array.isArray(value.revisions) || value.revisions.length === 0) {
+        throw new WorkflowAssignmentSyncError('workflowRuntimeResult.revisions are required.');
+    }
+    const revisions = value.revisions.map((rawRevision, index) => {
+        const entry = object(rawRevision, `workflowRuntimeResult.revisions[${index}]`);
+        const projection = text(entry.projection, `workflowRuntimeResult.revisions[${index}].projection`);
+        const supported = new Set([
+            'workflow-published-definition/full-v2',
+            'workflow-execution/root-v1',
+            'workflow-execution-event/full-v1',
+            'task/root-v1',
+            'entity-event/full-v1',
+        ]);
+        if (!supported.has(projection)) {
+            throw new WorkflowAssignmentSyncError('Workflow runtime result revision projection is invalid.');
+        }
+        const normalized = {
+            projection,
+            entityId: text(entry.entityId, `workflowRuntimeResult.revisions[${index}].entityId`),
+            sequence: positiveSequence(entry.sequence, `workflowRuntimeResult.revisions[${index}].sequence`),
+            entityRevision: positiveSequence(entry.entityRevision, `workflowRuntimeResult.revisions[${index}].entityRevision`),
+            lifecycleRevision: revision(entry.lifecycleRevision, `workflowRuntimeResult.revisions[${index}].lifecycleRevision`),
+            canonicalFingerprint: fingerprint(entry.canonicalFingerprint, `workflowRuntimeResult.revisions[${index}].canonicalFingerprint`),
+        };
+        if (BigInt(normalized.lifecycleRevision) > BigInt(normalized.entityRevision)) {
+            throw new WorkflowAssignmentSyncError('Workflow runtime result lifecycle revision cannot exceed entity revision.');
+        }
+        if ((projection === 'workflow-published-definition/full-v2'
+            || projection === 'workflow-execution-event/full-v1'
+            || projection === 'entity-event/full-v1')
+            && (normalized.entityRevision !== '1' || normalized.lifecycleRevision !== '0')) {
+            throw new WorkflowAssignmentSyncError('Immutable workflow runtime projections require revision coordinates 1/0.');
+        }
+        return normalized;
+    });
+    for (let index = 1; index < revisions.length; index += 1) {
+        if (BigInt(revisions[index].sequence) !== BigInt(revisions[index - 1].sequence) + 1n) {
+            throw new WorkflowAssignmentSyncError('Workflow runtime result revisions must be a contiguous canonical sequence.');
+        }
+    }
+    const requiredRevisions = new Map();
+    const eventFingerprints = new Map();
+    if (definition) {
+        requiredRevisions.set(`workflow-published-definition/full-v2\u0000${definition.version.id}`, fingerprintWorkflowRuntimePayload(definition));
+    }
+    requiredRevisions.set(`workflow-execution/root-v1\u0000${execution.execution.id}`, fingerprintWorkflowRuntimePayload(execution));
+    for (const event of events) {
+        eventFingerprints.set(`workflow-execution-event/full-v1\u0000${event.event.id}`, fingerprintWorkflowRuntimePayload(event));
+    }
+    for (const eventId of acceptedEventIds) {
+        const key = `workflow-execution-event/full-v1\u0000${eventId}`;
+        requiredRevisions.set(key, eventFingerprints.get(key));
+    }
+    if (task) {
+        requiredRevisions.set(`task/root-v1\u0000${task.payload.id}`, fingerprintWorkspaceSyncPayload(task.payload));
+        requiredRevisions.set(`entity-event/full-v1\u0000${task.activity.id}`, fingerprintWorkspaceSyncPayload(task.activity));
+    }
+    const seenRevisions = new Set();
+    for (const entry of revisions) {
+        const key = `${entry.projection}\u0000${entry.entityId}`;
+        if (seenRevisions.has(key)) {
+            throw new WorkflowAssignmentSyncError('Workflow runtime result has a duplicate revision target.');
+        }
+        seenRevisions.add(key);
+        const expectedFingerprint = requiredRevisions.get(key);
+        if (!expectedFingerprint || expectedFingerprint !== entry.canonicalFingerprint) {
+            throw new WorkflowAssignmentSyncError('Workflow runtime result revision does not match its authoritative projection.');
+        }
+    }
+    if ([...requiredRevisions.keys()].some((key) => !seenRevisions.has(key))) {
+        throw new WorkflowAssignmentSyncError('Workflow runtime result is missing an authoritative projection revision.');
+    }
+    return {
+        ...(definition ? { definition } : {}),
+        execution,
+        events,
+        acceptedEventIds,
+        ...(task ? { task } : {}),
+        revisions,
+        replayed: value.replayed,
+    };
+}
+export function fingerprintWorkflowRuntimeAuthoritativeResult(result) {
+    return fingerprintWorkspaceSyncPayload(validateWorkflowRuntimeAuthoritativeResult(result));
+}

package/dist/sync/v3/workspaceSyncJournalReader.d.ts

@@ -0,0 +1,43 @@
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
+export interface WorkspaceSyncJournalCoordinates {
+    entityRevision: string;
+    lifecycleRevision: string;
+}
+export interface WorkspaceSyncJournalBounds {
+    highWatermark: string;
+    minRetainedSequence: string | null;
+}
+export interface WorkspaceSyncJournalRow extends WorkspaceSyncJournalCoordinates {
+    sequence: string;
+    contractVersion: number;
+    clientId: string;
+    operationId: string;
+    domain: string;
+    entityId: string;
+    mutationKind: string;
+    contentSha256: string | null;
+    sizeBytes: string | null;
+    payloadJson: string;
+    occurredAt: string;
+}
+export declare class WorkspaceSyncJournalReader {
+    private readonly db;
+    constructor(db: DatabaseAdapter);
+    readEntityRevisionCoordinates(input: {
+        tenantId: string;
+        workspaceId: string;
+        domain: string;
+        entityId: string;
+    }): WorkspaceSyncJournalCoordinates;
+    readBounds(input: {
+        tenantId: string;
+        workspaceId: string;
+    }): WorkspaceSyncJournalBounds;
+    scan(input: {
+        tenantId: string;
+        workspaceId: string;
+        afterSequence: string;
+        throughSequence: string;
+        limit: number;
+    }): WorkspaceSyncJournalRow[];
+}

package/dist/sync/v3/workspaceSyncJournalReader.js

@@ -0,0 +1,45 @@
+function sequence(value) {
+    const text = String(value ?? '').trim();
+    if (!/^\d+$/.test(text))
+        throw new Error('Workspace sync journal sequence is invalid.');
+    return BigInt(text).toString(10);
+}
+export class WorkspaceSyncJournalReader {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    readEntityRevisionCoordinates(input) {
+        const row = this.db.prepare(`SELECT CAST(entity_revision AS TEXT) AS entity_revision,
+            CAST(lifecycle_revision AS TEXT) AS lifecycle_revision FROM workspace_sync_entity_revisions
+            WHERE tenant_id = ? AND workspace_id = ? AND domain = ? AND entity_id = ?`).get(input.tenantId, input.workspaceId, input.domain, input.entityId);
+        return { entityRevision: sequence(row?.entity_revision ?? 0), lifecycleRevision: sequence(row?.lifecycle_revision ?? 0) };
+    }
+    readBounds(input) {
+        const high = this.db.prepare(`SELECT CAST(last_sequence AS TEXT) AS last_sequence FROM workspace_sync_sequences
+            WHERE tenant_id = ? AND workspace_id = ?`).get(input.tenantId, input.workspaceId);
+        const retained = this.db.prepare(`SELECT CAST(MIN(sequence) AS TEXT) AS min_sequence FROM workspace_sync_journal
+            WHERE tenant_id = ? AND workspace_id = ?`).get(input.tenantId, input.workspaceId);
+        return {
+            highWatermark: sequence(high?.last_sequence ?? 0),
+            minRetainedSequence: retained?.min_sequence == null ? null : sequence(retained.min_sequence),
+        };
+    }
+    scan(input) {
+        const rows = this.db.prepare(`SELECT CAST(sequence AS TEXT) AS sequence, contract_version, client_id, operation_id, domain, entity_id,
+            mutation_kind, CAST(entity_revision AS TEXT) AS entity_revision,
+            CAST(lifecycle_revision AS TEXT) AS lifecycle_revision, content_sha256,
+            CAST(size_bytes AS TEXT) AS size_bytes, payload_json, occurred_at FROM workspace_sync_journal
+            WHERE tenant_id = ? AND workspace_id = ? AND sequence > ? AND sequence <= ?
+            ORDER BY sequence ASC LIMIT ?`).all(input.tenantId, input.workspaceId, sequence(input.afterSequence), sequence(input.throughSequence), Math.max(1, Math.min(10_101, Math.floor(input.limit))));
+        return rows.map((row) => ({
+            sequence: sequence(row.sequence), contractVersion: Number(row.contract_version), clientId: String(row.client_id || ''),
+            operationId: String(row.operation_id || ''), domain: String(row.domain || ''),
+            entityId: String(row.entity_id || ''), mutationKind: String(row.mutation_kind || ''),
+            entityRevision: sequence(row.entity_revision), lifecycleRevision: sequence(row.lifecycle_revision),
+            contentSha256: row.content_sha256 == null ? null : String(row.content_sha256),
+            sizeBytes: row.size_bytes == null ? null : sequence(row.size_bytes), payloadJson: String(row.payload_json || ''),
+            occurredAt: String(row.occurred_at || ''),
+        }));
+    }
+}

package/dist/sync/v3/workspaceSyncLocalOwnershipSnapshot.d.ts

@@ -0,0 +1,28 @@
+import type { TaskforceCore } from '../../core/Taskforce.js';
+export declare function readWorkspaceSyncLocalOwnershipSnapshot(input: {
+    core: TaskforceCore;
+    workspaceId: string;
+}): {
+    success: true;
+    contractVersion: 3;
+    workspaceId: string;
+    tasks: import("./syncDurabilityStore.js").WorkspaceSyncTaskMetadataOwnership[];
+    activeTaskRelationshipIds: string[];
+    initiatives: import("./syncDurabilityStore.js").WorkspaceSyncDomainOwnership[];
+    workstreams: import("./syncDurabilityStore.js").WorkspaceSyncDomainOwnership[];
+    initiativeProjection: import("./syncDurabilityStore.js").WorkspaceSyncProjectionOwnership;
+    combinedProjection: {
+        owner: "v2" | "v3";
+        epoch: string;
+        coverageProfileId: string;
+        coverageVersion: number;
+        coverageDigest: string;
+    };
+    taxonomy: {
+        activeOperation: boolean;
+        owned: boolean;
+        entityRevision: string;
+        lifecycleRevision: string;
+        lastSequence: string | null;
+    };
+};