@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/core/WorkflowTaskActivationService.js

@@ -0,0 +1,63 @@
+export class WorkflowTaskActivationError extends Error {
+    code;
+    statusCode = 409;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkflowTaskActivationError';
+    }
+}
+function ownerMatchesType(actor, ownerType) {
+    return ownerType === 'agent' ? actor.kind === 'ai' : actor.kind === 'human';
+}
+export class WorkflowTaskActivationService {
+    store;
+    listAssignableActors;
+    constructor(store, listAssignableActors) {
+        this.store = store;
+        this.listAssignableActors = listAssignableActors;
+    }
+    prepare(input) {
+        if (input.targetTaskStatus !== 'in-progress')
+            return null;
+        const execution = this.store.getActiveExecutionForTask(input.workspaceId, input.taskId);
+        if (!execution || execution.status !== 'pending')
+            return null;
+        const steps = this.store.listSteps(input.workspaceId, execution.workflowVersionId);
+        const step = steps.find((candidate) => candidate.isRequired) || steps[0];
+        if (!step) {
+            throw new WorkflowTaskActivationError('workflow_step_missing', 'The pending workflow cannot start because its published version has no steps.');
+        }
+        if (!step.ownerId)
+            return { execution, step, ownerId: null };
+        if (!step.ownerType) {
+            throw new WorkflowTaskActivationError('workflow_step_owner_invalid', 'The first workflow step has an owner without an owner type.');
+        }
+        const owner = this.listAssignableActors(input.workspaceId).find((actor) => actor.id === step.ownerId);
+        if (!owner || owner.meta?.unresolved === true || !ownerMatchesType(owner, step.ownerType)) {
+            throw new WorkflowTaskActivationError('workflow_step_owner_invalid', 'The first workflow step owner is not an active assignable workspace actor.');
+        }
+        return { execution, step, ownerId: owner.id };
+    }
+    start(input) {
+        return this.store.appendExecutionTransition({
+            workspaceId: input.workspaceId,
+            executionId: input.activation.execution.id,
+            eventType: 'execution-started',
+            expectedFromStatuses: ['pending'],
+            toStatus: 'running',
+            actorId: input.actorId,
+            idempotencyKey: `${input.taskEventId}:workflow-start`,
+            eventId: input.eventId,
+            occurredAt: input.occurredAt,
+            stepId: input.activation.step.id,
+            details: {
+                trigger: 'task-entered-in-progress',
+                taskEventId: input.taskEventId,
+                stepName: input.activation.step.name,
+                ownerType: input.activation.step.ownerType || null,
+                ownerId: input.activation.ownerId,
+            },
+        }).execution;
+    }
+}

package/dist/core/WorkflowTemplateService.d.ts

@@ -0,0 +1,64 @@
+import { WorkflowStore, type WorkflowStepInput, type WorkflowStepRecord, type WorkflowTemplateRecord, type WorkflowVersionRecord } from '../storage/workflowStore.js';
+export type WorkflowTemplateServiceErrorCode = 'invalid_input' | 'workflow_not_found' | 'draft_not_found' | 'draft_already_exists' | 'steps_required' | 'published_version_immutable';
+export declare class WorkflowTemplateServiceError extends Error {
+    readonly code: WorkflowTemplateServiceErrorCode;
+    constructor(code: WorkflowTemplateServiceErrorCode, message: string);
+}
+export interface WorkflowVersionDetails {
+    version: WorkflowVersionRecord;
+    steps: WorkflowStepRecord[];
+}
+export interface WorkflowTemplateDetails {
+    template: WorkflowTemplateRecord;
+    draft: WorkflowVersionDetails | null;
+    publishedVersions: WorkflowVersionDetails[];
+}
+export interface WorkflowTemplateSummary {
+    template: WorkflowTemplateRecord;
+    draftVersionId: string | null;
+    latestPublishedVersion: Pick<WorkflowVersionRecord, 'id' | 'versionNumber' | 'publishedAt'> | null;
+}
+export declare class WorkflowTemplateService {
+    private readonly store;
+    constructor(store: WorkflowStore);
+    createWorkflow(input: {
+        workspaceId: string;
+        name: string;
+        description?: string;
+        steps?: WorkflowStepInput[];
+        actorId?: string | null;
+    }): WorkflowTemplateDetails;
+    listWorkflows(workspaceIdRaw: string): WorkflowTemplateSummary[];
+    getWorkflow(workspaceIdRaw: string, templateIdRaw: string): WorkflowTemplateDetails;
+    updateDraftMetadata(input: {
+        workspaceId: string;
+        templateId: string;
+        name: string;
+        description?: string;
+        actorId?: string | null;
+    }): WorkflowTemplateDetails;
+    saveDraft(input: {
+        workspaceId: string;
+        templateId: string;
+        name: string;
+        description?: string;
+        steps: WorkflowStepInput[];
+        actorId?: string | null;
+    }): WorkflowTemplateDetails;
+    replaceDraftSteps(input: {
+        workspaceId: string;
+        templateId: string;
+        steps: WorkflowStepInput[];
+    }): WorkflowTemplateDetails;
+    publishDraft(input: {
+        workspaceId: string;
+        templateId: string;
+        actorId?: string | null;
+    }): WorkflowTemplateDetails;
+    createDraft(input: {
+        workspaceId: string;
+        templateId: string;
+        actorId?: string | null;
+    }): WorkflowTemplateDetails;
+    private requireDraft;
+}

package/dist/core/WorkflowTemplateService.js

@@ -0,0 +1,223 @@
+export class WorkflowTemplateServiceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WorkflowTemplateServiceError';
+    }
+}
+function requireValue(value, field) {
+    if (typeof value !== 'string') {
+        throw new WorkflowTemplateServiceError('invalid_input', `${field} is required.`);
+    }
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new WorkflowTemplateServiceError('invalid_input', `${field} is required.`);
+    }
+    return normalized;
+}
+function normalizeSteps(value) {
+    if (!Array.isArray(value)) {
+        throw new WorkflowTemplateServiceError('invalid_input', 'Workflow steps must be an array.');
+    }
+    return value.map((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new WorkflowTemplateServiceError('invalid_input', `Workflow step ${index + 1} is invalid.`);
+        }
+        const step = entry;
+        const name = requireValue(step.name, `Workflow step ${index + 1} name`);
+        const ownerType = step.ownerType == null ? null : step.ownerType;
+        if (ownerType !== null && ownerType !== 'user' && ownerType !== 'agent') {
+            throw new WorkflowTemplateServiceError('invalid_input', `Workflow step ${index + 1} owner type is invalid.`);
+        }
+        if (step.ownerId != null && typeof step.ownerId !== 'string') {
+            throw new WorkflowTemplateServiceError('invalid_input', `Workflow step ${index + 1} owner id is invalid.`);
+        }
+        if (step.instructions != null && typeof step.instructions !== 'string') {
+            throw new WorkflowTemplateServiceError('invalid_input', `Workflow step ${index + 1} instructions are invalid.`);
+        }
+        if (step.expectedArtifact != null && typeof step.expectedArtifact !== 'string') {
+            throw new WorkflowTemplateServiceError('invalid_input', `Workflow step ${index + 1} expected artifact is invalid.`);
+        }
+        if (step.requiresCommentEvidence != null && typeof step.requiresCommentEvidence !== 'boolean') {
+            throw new WorkflowTemplateServiceError('invalid_input', `Workflow step ${index + 1} comment evidence state is invalid.`);
+        }
+        if (step.isRequired != null && typeof step.isRequired !== 'boolean') {
+            throw new WorkflowTemplateServiceError('invalid_input', `Workflow step ${index + 1} required state is invalid.`);
+        }
+        return {
+            name,
+            instructions: step.instructions,
+            ownerType,
+            ownerId: step.ownerId,
+            expectedArtifact: step.expectedArtifact,
+            requiresCommentEvidence: step.requiresCommentEvidence,
+            isRequired: step.isRequired,
+        };
+    });
+}
+function translateStoreError(error) {
+    if (error instanceof WorkflowTemplateServiceError)
+        throw error;
+    const message = String(error?.message || error);
+    if (message.includes('already has a draft')) {
+        throw new WorkflowTemplateServiceError('draft_already_exists', 'This workflow already has an editable draft.');
+    }
+    if (message.includes('idx_workflow_versions_single_draft')
+        || message.includes('workflow_versions.tenant_id, workflow_versions.workspace_id, workflow_versions.workflow_template_id')) {
+        throw new WorkflowTemplateServiceError('draft_already_exists', 'This workflow already has an editable draft.');
+    }
+    if (message.includes('immutable')) {
+        throw new WorkflowTemplateServiceError('published_version_immutable', 'Published workflow versions cannot be changed.');
+    }
+    if (message.includes('at least one step')) {
+        throw new WorkflowTemplateServiceError('steps_required', 'Add at least one workflow step before publishing.');
+    }
+    if (message.includes('Workflow step name is required') || message.includes('owner type and owner id')) {
+        throw new WorkflowTemplateServiceError('invalid_input', message);
+    }
+    throw error;
+}
+export class WorkflowTemplateService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    createWorkflow(input) {
+        const workspaceId = requireValue(input.workspaceId, 'Workspace id');
+        const name = requireValue(input.name, 'Workflow name');
+        try {
+            const created = this.store.createTemplate({
+                ...input,
+                workspaceId,
+                name,
+                steps: normalizeSteps(input.steps || []),
+            });
+            return this.getWorkflow(workspaceId, created.template.id);
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+    listWorkflows(workspaceIdRaw) {
+        const workspaceId = requireValue(workspaceIdRaw, 'Workspace id');
+        return this.store.listTemplates(workspaceId).map((template) => {
+            const versions = this.store.listVersions(workspaceId, template.id);
+            const draft = versions.find((version) => version.status === 'draft') || null;
+            const latestPublished = versions.find((version) => version.status === 'published') || null;
+            return {
+                template,
+                draftVersionId: draft?.id || null,
+                latestPublishedVersion: latestPublished
+                    ? {
+                        id: latestPublished.id,
+                        versionNumber: latestPublished.versionNumber,
+                        publishedAt: latestPublished.publishedAt,
+                    }
+                    : null,
+            };
+        });
+    }
+    getWorkflow(workspaceIdRaw, templateIdRaw) {
+        const workspaceId = requireValue(workspaceIdRaw, 'Workspace id');
+        const templateId = requireValue(templateIdRaw, 'Workflow template id');
+        const definition = this.store.getTemplateDefinition(workspaceId, templateId);
+        if (!definition) {
+            throw new WorkflowTemplateServiceError('workflow_not_found', 'Workflow not found.');
+        }
+        const draft = definition.versions.find(({ version }) => version.status === 'draft') || null;
+        return {
+            template: definition.template,
+            draft,
+            publishedVersions: definition.versions.filter(({ version }) => version.status === 'published'),
+        };
+    }
+    updateDraftMetadata(input) {
+        const workspaceId = requireValue(input.workspaceId, 'Workspace id');
+        const name = requireValue(input.name, 'Workflow name');
+        const workflow = this.getWorkflow(workspaceId, input.templateId);
+        const draft = this.requireDraft(workflow);
+        try {
+            this.store.updateDraftVersion({
+                workspaceId,
+                versionId: draft.version.id,
+                name,
+                description: input.description,
+                actorId: input.actorId,
+            });
+            return this.getWorkflow(workspaceId, workflow.template.id);
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+    saveDraft(input) {
+        const workspaceId = requireValue(input.workspaceId, 'Workspace id');
+        const name = requireValue(input.name, 'Workflow name');
+        const steps = normalizeSteps(input.steps);
+        const workflow = this.getWorkflow(workspaceId, input.templateId);
+        const draft = this.requireDraft(workflow);
+        try {
+            this.store.saveDraft({
+                workspaceId,
+                versionId: draft.version.id,
+                name,
+                description: input.description,
+                steps,
+                actorId: input.actorId,
+            });
+            return this.getWorkflow(workspaceId, workflow.template.id);
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+    replaceDraftSteps(input) {
+        const workspaceId = requireValue(input.workspaceId, 'Workspace id');
+        const steps = normalizeSteps(input.steps);
+        const workflow = this.getWorkflow(workspaceId, input.templateId);
+        const draft = this.requireDraft(workflow);
+        try {
+            this.store.replaceDraftSteps(workspaceId, draft.version.id, steps);
+            return this.getWorkflow(workspaceId, workflow.template.id);
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+    publishDraft(input) {
+        const workspaceId = requireValue(input.workspaceId, 'Workspace id');
+        const workflow = this.getWorkflow(workspaceId, input.templateId);
+        const draft = this.requireDraft(workflow);
+        if (draft.steps.length === 0) {
+            throw new WorkflowTemplateServiceError('steps_required', 'Add at least one workflow step before publishing.');
+        }
+        try {
+            this.store.publishVersion(workspaceId, draft.version.id, input.actorId);
+            return this.getWorkflow(workspaceId, workflow.template.id);
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+    createDraft(input) {
+        const workspaceId = requireValue(input.workspaceId, 'Workspace id');
+        const workflow = this.getWorkflow(workspaceId, input.templateId);
+        if (workflow.draft) {
+            throw new WorkflowTemplateServiceError('draft_already_exists', 'This workflow already has an editable draft.');
+        }
+        try {
+            this.store.createDraftVersion(workspaceId, workflow.template.id, input.actorId);
+            return this.getWorkflow(workspaceId, workflow.template.id);
+        }
+        catch (error) {
+            return translateStoreError(error);
+        }
+    }
+    requireDraft(workflow) {
+        if (!workflow.draft) {
+            throw new WorkflowTemplateServiceError('draft_not_found', 'Create an editable draft before changing this workflow.');
+        }
+        return workflow.draft;
+    }
+}

package/dist/core/WorkspaceLifecycleService.d.ts

@@ -3,6 +3,7 @@ import type { WorkspaceDeleteSummary } from './types.js';
 export interface WorkspaceLifecycleServiceDeps {
     db: DatabaseAdapter;
     tenantId: string;
+    runtimeMode: 'local' | 'cloud';
     createRuleError: (message: string, statusCode?: number, code?: string) => Error;
     revokeMcpCredentialsForWorkspace: (workspaceId: string, revokedByUserId?: string | null) => void;
 }

package/dist/core/WorkspaceLifecycleService.js

@@ -57,9 +57,27 @@ export function deleteWorkspaceService(deps, input) {
         };
         runDelete('comments', 'DELETE FROM comments WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
         runDelete('task_events', 'DELETE FROM task_events WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('entity_events', 'DELETE FROM entity_events WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
         runDelete('deleted_tasks', 'DELETE FROM deleted_tasks WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
         runDelete('workspace_sync_deletes', 'DELETE FROM workspace_sync_deletes WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
         runDelete('sync_idempotency', 'DELETE FROM sync_idempotency WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_outbox_targets', 'DELETE FROM workspace_sync_outbox_targets WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_task_taxonomy_ownership', 'DELETE FROM workspace_sync_task_taxonomy_ownership WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_outbox', 'DELETE FROM workspace_sync_outbox WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_operation_results', 'DELETE FROM workspace_sync_operation_results WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_coverage_repair_entries', 'DELETE FROM workspace_sync_coverage_repair_entries WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_projection_repair_entries', 'DELETE FROM workspace_sync_projection_repair_entries WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_projection_state', 'DELETE FROM workspace_sync_projection_state WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        if (deps.runtimeMode === 'local') {
+            runDelete('local_sync_legacy_adoption_state', 'DELETE FROM local_sync_legacy_adoption_state WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        }
+        runDelete('workspace_sync_repair_snapshot_entries', 'DELETE FROM workspace_sync_repair_snapshot_entries WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_repair_snapshots', 'DELETE FROM workspace_sync_repair_snapshots WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_journal', 'DELETE FROM workspace_sync_journal WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_entity_revisions', 'DELETE FROM workspace_sync_entity_revisions WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_sequences', 'DELETE FROM workspace_sync_sequences WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_task_create_guards', 'DELETE FROM workspace_sync_task_create_guards WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
+        runDelete('workspace_sync_domain_locks', 'DELETE FROM workspace_sync_domain_locks WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
         runDelete('sync_events', 'DELETE FROM sync_events WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
         runDelete('ui_state', 'DELETE FROM ui_state WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);
         runDelete('workspace_settings', 'DELETE FROM workspace_settings WHERE tenant_id = ? AND workspace_id = ?', deps.tenantId, normalizedWorkspaceId);

package/dist/core/WorkstreamDurableMutationService.d.ts

@@ -0,0 +1,90 @@
+import type { Comment, TaskActor, WorkstreamItem } from '../types.js';
+import type { WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+import { type CanonicalPlanningAttachmentLink } from '../sync/planningCanonicalFields.js';
+import type { DurableWorkstreamCreatePayload } from '../sync/v3/workstreamMutationPayload.js';
+import type { WorkspaceSyncV3WorkstreamMetadataPatch } from '../sync/v3/workspaceSyncV3OperationProtocol.js';
+export declare class DurableWorkstreamApplyError extends Error {
+    readonly code: 'WORKSTREAM_NOT_FOUND' | 'WORKSTREAM_ID_CONFLICT' | 'WORKSTREAM_STATE_CONFLICT' | 'WORKSTREAM_INITIATIVE_INVALID' | 'WORKSTREAM_OWNER_INVALID' | 'WORKSTREAM_COMMENT_AUTHOR_INVALID' | 'WORKSTREAM_ATTACHMENT_NOT_READY' | 'WORKSTREAM_ATTACHMENT_INVALID';
+    readonly statusCode: number;
+    readonly assetId?: string | undefined;
+    constructor(message: string, code: 'WORKSTREAM_NOT_FOUND' | 'WORKSTREAM_ID_CONFLICT' | 'WORKSTREAM_STATE_CONFLICT' | 'WORKSTREAM_INITIATIVE_INVALID' | 'WORKSTREAM_OWNER_INVALID' | 'WORKSTREAM_COMMENT_AUTHOR_INVALID' | 'WORKSTREAM_ATTACHMENT_NOT_READY' | 'WORKSTREAM_ATTACHMENT_INVALID', statusCode: number, assetId?: string | undefined);
+}
+export interface DurableWorkstreamMutationCore {
+    getWorkstream(id: string, workspaceId?: string): WorkstreamItem | null;
+    getInitiative(id: string, workspaceId?: string): unknown | null;
+    createWorkstream(input: Partial<WorkstreamItem>, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+        entityEventId?: string;
+        durableProvisionalCreate?: boolean;
+        allowV3OwnedWrite?: boolean;
+    }): WorkstreamItem;
+    updateWorkstream(id: string, patch: Partial<WorkstreamItem>, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+        entityEventId?: string;
+        allowV3OwnedWrite?: boolean;
+    }): WorkstreamItem;
+    archiveWorkstream(id: string, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+        entityEventId?: string;
+        updatedAt?: string;
+        allowV3OwnedWrite?: boolean;
+    }): WorkstreamItem;
+    unarchiveWorkstream(id: string, workspaceId?: string, options?: {
+        actorRef?: string;
+        skipEntityEvents?: boolean;
+        entityEventId?: string;
+        updatedAt?: string;
+        allowV3OwnedWrite?: boolean;
+    }): WorkstreamItem;
+    appendWorkstreamCommentForDurableSync(input: {
+        workstreamId: string;
+        workspaceId: string;
+        comment: Comment;
+        updatedAt: string;
+        actorRef: string;
+        entityEventId: string;
+    }): WorkstreamItem;
+    listAssignableActors(workspaceId: string): TaskActor[];
+    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTarget'>;
+}
+export declare function resolveWorkstreamAttachmentsForDurableSync(core: DurableWorkstreamMutationCore, workspaceId: string, workstreamId: string, attachments: CanonicalPlanningAttachmentLink[] | undefined): CanonicalPlanningAttachmentLink[] | undefined;
+export declare function applyWorkstreamCreateForDurableSync(input: {
+    core: DurableWorkstreamMutationCore;
+    workspaceId: string;
+    workstreamId: string;
+    payload: DurableWorkstreamCreatePayload;
+    updatedAt: string;
+    actorRef: string;
+    entityEventId: string;
+    provisional?: boolean;
+}): WorkstreamItem;
+export declare function applyWorkstreamMetadataForDurableSync(input: {
+    core: DurableWorkstreamMutationCore;
+    workspaceId: string;
+    workstreamId: string;
+    patch: WorkspaceSyncV3WorkstreamMetadataPatch;
+    updatedAt: string;
+    actorRef: string;
+    entityEventId: string;
+}): WorkstreamItem;
+export declare function applyWorkstreamCommentForDurableSync(input: {
+    core: DurableWorkstreamMutationCore;
+    workspaceId: string;
+    workstreamId: string;
+    comment: Comment;
+    updatedAt: string;
+    actorRef: string;
+    entityEventId: string;
+}): WorkstreamItem;
+export declare function applyWorkstreamLifecycleForDurableSync(input: {
+    core: DurableWorkstreamMutationCore;
+    workspaceId: string;
+    workstreamId: string;
+    mutationKind: 'archive' | 'unarchive';
+    updatedAt: string;
+    actorRef: string;
+    entityEventId: string;
+}): WorkstreamItem;

package/dist/core/WorkstreamDurableMutationService.js

@@ -0,0 +1,184 @@
+import { getDocumentReferenceLabel } from '../utils/documentReferences.js';
+import { getImageReferenceLabel } from '../utils/imageReferences.js';
+import { serializeCanonicalPlanningAttachmentLinks, } from '../sync/planningCanonicalFields.js';
+export class DurableWorkstreamApplyError extends Error {
+    code;
+    statusCode;
+    assetId;
+    constructor(message, code, statusCode, assetId) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.assetId = assetId;
+        this.name = 'DurableWorkstreamApplyError';
+    }
+}
+function fail(message, code, statusCode, assetId) {
+    throw new DurableWorkstreamApplyError(message, code, statusCode, assetId);
+}
+function assertOwner(core, workspaceId, ownerId) {
+    if (!ownerId)
+        return;
+    const actor = core.listAssignableActors(workspaceId).find((candidate) => candidate.id === ownerId);
+    if (!actor || actor.meta?.unresolved === true) {
+        fail('Workstream owner is not an active assignable workspace actor.', 'WORKSTREAM_OWNER_INVALID', 400);
+    }
+}
+function assertInitiative(core, workspaceId, initiativeId) {
+    if (!initiativeId)
+        return;
+    if (!core.getInitiative(initiativeId, workspaceId)) {
+        fail('Workstream initiative does not exist in this workspace.', 'WORKSTREAM_INITIATIVE_INVALID', 400);
+    }
+}
+function canonicalAssetPath(asset) {
+    if (asset.storageProvider === 'external') {
+        return /^https?:\/\//i.test(asset.storageKey)
+            ? asset.storageKey
+            : `/api/taskforce/context-link?path=${encodeURIComponent(asset.storageKey)}`;
+    }
+    return asset.kind === 'document'
+        ? `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`
+        : `/api/taskforce/context/${encodeURIComponent(asset.storageKey)}`;
+}
+function canonicalAssetRole(asset, path, requestedRole, existingLink) {
+    if (requestedRole === 'reference' || existingLink?.role === 'reference' || /^https?:\/\//i.test(path))
+        return 'reference';
+    return asset.kind === 'image' ? 'image' : 'attachment';
+}
+function canonicalAssetReference(asset) {
+    if (!asset.referenceNumber)
+        return {};
+    const referenceLabel = asset.kind === 'document'
+        ? getDocumentReferenceLabel({ referenceNumber: asset.referenceNumber })
+        : asset.kind === 'image'
+            ? getImageReferenceLabel({ referenceNumber: asset.referenceNumber })
+            : '';
+    return { referenceNumber: asset.referenceNumber, ...(referenceLabel ? { referenceLabel } : {}) };
+}
+export function resolveWorkstreamAttachmentsForDurableSync(core, workspaceId, workstreamId, attachments) {
+    if (!attachments)
+        return undefined;
+    if (attachments.length === 0)
+        return [];
+    const identities = new Set();
+    const store = core.getWorkspaceAssetStore();
+    const existingLinks = new Map(store.listLinksForTarget('workstream', workstreamId, workspaceId)
+        .map((link) => [`${link.assetId}\u0000${link.role}`, link]));
+    return attachments.map((attachment) => {
+        const asset = store.get(attachment.assetId, workspaceId);
+        if (!asset) {
+            fail(`Workstream attachment asset is unavailable because it has not reached this runtime: ${attachment.assetId}`, 'WORKSTREAM_ATTACHMENT_NOT_READY', 425, attachment.assetId);
+        }
+        if (asset.deletedAt)
+            fail(`Workstream attachment asset is unavailable: ${attachment.assetId}`, 'WORKSTREAM_ATTACHMENT_INVALID', 400);
+        const expectedPath = canonicalAssetPath(asset);
+        if (attachment.path !== expectedPath) {
+            fail(`Workstream attachment path does not match asset ${attachment.assetId}.`, 'WORKSTREAM_ATTACHMENT_INVALID', 400);
+        }
+        const existingLink = existingLinks.get(`${attachment.assetId}\u0000reference`)
+            || existingLinks.get(`${attachment.assetId}\u0000${asset.kind === 'image' ? 'image' : 'attachment'}`);
+        const role = canonicalAssetRole(asset, attachment.path, attachment.linkRole, existingLink);
+        if (attachment.linkRole !== undefined && attachment.linkRole !== role) {
+            fail(`Workstream attachment role does not match asset ${attachment.assetId}.`, 'WORKSTREAM_ATTACHMENT_INVALID', 400);
+        }
+        const identity = `${attachment.assetId}\u0000${role}`;
+        if (identities.has(identity)) {
+            fail('Workstream attachment links must have unique asset and role identities.', 'WORKSTREAM_ATTACHMENT_INVALID', 400);
+        }
+        identities.add(identity);
+        const { referenceNumber: _number, referenceLabel: _label, ...canonicalLink } = attachment;
+        return { ...canonicalLink, ...canonicalAssetReference(asset), linkRole: role };
+    });
+}
+function semanticValue(value) {
+    return JSON.stringify(value ?? null);
+}
+function isMetadataNoop(existing, patch) {
+    return Object.entries(patch).every(([field, value]) => {
+        if (field === 'attachments') {
+            try {
+                return semanticValue(serializeCanonicalPlanningAttachmentLinks(existing.attachments)) === semanticValue(value);
+            }
+            catch {
+                return false;
+            }
+        }
+        return semanticValue(existing[field]) === semanticValue(value);
+    });
+}
+export function applyWorkstreamCreateForDurableSync(input) {
+    if (input.core.getWorkstream(input.workstreamId, input.workspaceId)) {
+        fail('Workstream id already exists.', 'WORKSTREAM_ID_CONFLICT', 409);
+    }
+    assertInitiative(input.core, input.workspaceId, input.payload.initiativeId);
+    assertOwner(input.core, input.workspaceId, input.payload.ownerId);
+    const attachments = resolveWorkstreamAttachmentsForDurableSync(input.core, input.workspaceId, input.workstreamId, input.payload.attachments) || [];
+    const workstream = input.core.createWorkstream({
+        id: input.workstreamId,
+        initiativeId: input.payload.initiativeId,
+        title: input.payload.title,
+        description: input.payload.description,
+        ownerId: input.payload.ownerId,
+        order: input.payload.order,
+        attachments,
+        comments: [],
+        createdAt: input.payload.createdAt,
+        updatedAt: input.updatedAt,
+        isArchived: false,
+    }, input.workspaceId, {
+        actorRef: input.actorRef,
+        entityEventId: input.entityEventId,
+        durableProvisionalCreate: input.provisional === true,
+        allowV3OwnedWrite: true,
+    });
+    if (workstream.id !== input.workstreamId
+        || (input.provisional === true ? workstream.referenceNumber !== null : !workstream.referenceNumber)) {
+        fail('Workstream creation did not produce a canonical identity.', 'WORKSTREAM_STATE_CONFLICT', 500);
+    }
+    return workstream;
+}
+export function applyWorkstreamMetadataForDurableSync(input) {
+    const existing = input.core.getWorkstream(input.workstreamId, input.workspaceId);
+    if (!existing)
+        fail('Workstream not found.', 'WORKSTREAM_NOT_FOUND', 404);
+    const attachments = resolveWorkstreamAttachmentsForDurableSync(input.core, input.workspaceId, input.workstreamId, input.patch.attachments);
+    const patch = { ...input.patch, ...(attachments ? { attachments } : {}) };
+    if (isMetadataNoop(existing, patch)) {
+        fail('Workstream metadata patch does not change canonical state.', 'WORKSTREAM_STATE_CONFLICT', 409);
+    }
+    assertInitiative(input.core, input.workspaceId, patch.initiativeId);
+    assertOwner(input.core, input.workspaceId, patch.ownerId);
+    return input.core.updateWorkstream(input.workstreamId, { ...patch, updatedAt: input.updatedAt }, input.workspaceId, {
+        actorRef: input.actorRef, entityEventId: input.entityEventId, allowV3OwnedWrite: true,
+    });
+}
+export function applyWorkstreamCommentForDurableSync(input) {
+    const existing = input.core.getWorkstream(input.workstreamId, input.workspaceId);
+    if (!existing)
+        fail('Workstream not found.', 'WORKSTREAM_NOT_FOUND', 404);
+    if (input.comment.author !== 'user')
+        assertOwner(input.core, input.workspaceId, input.comment.author);
+    if (input.comment.author !== input.actorRef) {
+        fail('Workstream comment author must match the authenticated actor.', 'WORKSTREAM_COMMENT_AUTHOR_INVALID', 403);
+    }
+    if ((existing.comments || []).some((comment) => comment.id === input.comment.id)) {
+        fail('Workstream comment id already exists.', 'WORKSTREAM_STATE_CONFLICT', 409);
+    }
+    return input.core.appendWorkstreamCommentForDurableSync(input);
+}
+export function applyWorkstreamLifecycleForDurableSync(input) {
+    const existing = input.core.getWorkstream(input.workstreamId, input.workspaceId);
+    if (!existing)
+        fail('Workstream not found.', 'WORKSTREAM_NOT_FOUND', 404);
+    if ((input.mutationKind === 'archive') === Boolean(existing.isArchived)) {
+        fail(`Workstream is already ${input.mutationKind === 'archive' ? 'archived' : 'active'}.`, 'WORKSTREAM_STATE_CONFLICT', 409);
+    }
+    return input.mutationKind === 'archive'
+        ? input.core.archiveWorkstream(input.workstreamId, input.workspaceId, {
+            actorRef: input.actorRef, entityEventId: input.entityEventId, updatedAt: input.updatedAt, allowV3OwnedWrite: true,
+        })
+        : input.core.unarchiveWorkstream(input.workstreamId, input.workspaceId, {
+            actorRef: input.actorRef, entityEventId: input.entityEventId, updatedAt: input.updatedAt, allowV3OwnedWrite: true,
+        });
+}