@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/v3/programScaffoldService.js

@@ -0,0 +1,478 @@
+import { createHash } from 'crypto';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { WORKSPACE_SYNC_CONTRACT_VERSION, WorkspaceSyncDurabilityStore, } from './syncDurabilityStore.js';
+const KEY_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
+const MAX_CANONICAL_BYTES = 128 * 1024;
+const OPERATION_LEASE_MS = 30_000;
+export class ProgramScaffoldInvalidError extends Error {
+    code = 'PROGRAM_SCAFFOLD_INVALID';
+    statusCode = 400;
+    constructor(message) {
+        super(message);
+        this.name = 'ProgramScaffoldInvalidError';
+    }
+}
+export class ProgramScaffoldDisabledError extends Error {
+    code = 'PROGRAM_SCAFFOLD_DISABLED';
+    statusCode = 409;
+    constructor() {
+        super('Program scaffolding is disabled for this runtime.');
+        this.name = 'ProgramScaffoldDisabledError';
+    }
+}
+export class ProgramScaffoldInProgressError extends Error {
+    retryAt;
+    code = 'WORKSPACE_SYNC_OPERATION_IN_PROGRESS';
+    statusCode = 409;
+    constructor(retryAt) {
+        super('The program scaffold operation is already in progress.');
+        this.retryAt = retryAt;
+        this.name = 'ProgramScaffoldInProgressError';
+    }
+}
+export class ProgramScaffoldCommittedResponseInvalidError extends Error {
+    code = 'WORKSPACE_SYNC_COMMITTED_RESPONSE_INVALID';
+    statusCode = 500;
+    constructor() {
+        super('The committed program scaffold response is invalid.');
+        this.name = 'ProgramScaffoldCommittedResponseInvalidError';
+    }
+}
+function invalid(message) {
+    throw new ProgramScaffoldInvalidError(message);
+}
+function exactObject(value, allowed, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        invalid(`${label} must be an object.`);
+    const source = value;
+    const extra = Object.keys(source).filter((key) => !allowed.includes(key));
+    if (extra.length > 0)
+        invalid(`${label} contains unsupported fields.`);
+    return source;
+}
+function requiredString(value, label) {
+    if (typeof value !== 'string' || !value.trim())
+        invalid(`${label} is required.`);
+    return value.trim();
+}
+function optionalString(source, key, label) {
+    if (!Object.prototype.hasOwnProperty.call(source, key))
+        return undefined;
+    if (typeof source[key] !== 'string')
+        invalid(`${label} must be a string.`);
+    return String(source[key]);
+}
+function optionalNumber(source, key, label) {
+    if (!Object.prototype.hasOwnProperty.call(source, key))
+        return undefined;
+    if (!Number.isInteger(source[key]))
+        invalid(`${label} must be an integer.`);
+    return source[key];
+}
+function key(value, label) {
+    const normalized = requiredString(value, label);
+    if (!KEY_PATTERN.test(normalized))
+        invalid(`${label} must match ${KEY_PATTERN.source}.`);
+    return normalized;
+}
+function date(value, label) {
+    const normalized = requiredString(value, label);
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(normalized);
+    const parsed = match ? new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]))) : null;
+    if (!match || !parsed
+        || parsed.getUTCFullYear() !== Number(match[1])
+        || parsed.getUTCMonth() !== Number(match[2]) - 1
+        || parsed.getUTCDate() !== Number(match[3])) {
+        invalid(`${label} must use YYYY-MM-DD.`);
+    }
+    return normalized;
+}
+function canonicalize(input) {
+    const root = exactObject(input, ['dryRun', 'idempotencyKey', 'initiative', 'workstreams', 'dependencies'], 'Program scaffold');
+    if (typeof root.dryRun !== 'boolean')
+        invalid('dryRun must be a boolean.');
+    if (!root.dryRun) {
+        const idempotencyKey = requiredString(root.idempotencyKey, 'idempotencyKey');
+        if (idempotencyKey.length > 128)
+            invalid('idempotencyKey must contain at most 128 characters.');
+    }
+    else if (root.idempotencyKey !== undefined && typeof root.idempotencyKey !== 'string') {
+        invalid('idempotencyKey must be a string when supplied.');
+    }
+    const initiativeSource = exactObject(root.initiative, ['title', 'description', 'ownerId', 'order'], 'Initiative');
+    const initiativeDescription = optionalString(initiativeSource, 'description', 'Initiative description');
+    const initiativeOwnerId = optionalString(initiativeSource, 'ownerId', 'Initiative ownerId');
+    const initiativeOrder = optionalNumber(initiativeSource, 'order', 'Initiative order');
+    const initiative = {
+        title: requiredString(initiativeSource.title, 'Initiative title'),
+        ...(initiativeDescription !== undefined ? { description: initiativeDescription } : {}),
+        ...(initiativeOwnerId !== undefined ? { ownerId: initiativeOwnerId } : {}),
+        ...(initiativeOrder !== undefined ? { order: initiativeOrder } : {}),
+    };
+    if (!Array.isArray(root.workstreams))
+        invalid('workstreams must be an array.');
+    if (root.workstreams.length > 12)
+        invalid('A program supports at most 12 workstreams.');
+    const workstreamKeys = new Set();
+    const taskKeys = new Set();
+    let taskCount = 0;
+    const workstreams = root.workstreams.map((candidate, workstreamIndex) => {
+        const source = exactObject(candidate, ['key', 'title', 'description', 'ownerId', 'order', 'tasks'], `Workstream ${workstreamIndex + 1}`);
+        const workstreamKey = key(source.key, `Workstream ${workstreamIndex + 1} key`);
+        if (workstreamKeys.has(workstreamKey))
+            invalid(`Workstream ${workstreamIndex + 1} duplicates an earlier workstream key.`);
+        workstreamKeys.add(workstreamKey);
+        if (!Array.isArray(source.tasks))
+            invalid(`Workstream ${workstreamIndex + 1} tasks must be an array.`);
+        const tasks = source.tasks.map((candidateTask, taskIndex) => {
+            const taskSource = exactObject(candidateTask, [
+                'key', 'title', 'description', 'assignee', 'category', 'type', 'priority',
+                'complexity', 'scheduledDate', 'dueDate',
+            ], `Task ${taskIndex + 1} in workstream ${workstreamIndex + 1}`);
+            const taskKey = key(taskSource.key, `Task ${taskIndex + 1} key`);
+            if (taskKeys.has(taskKey))
+                invalid(`Task ${taskIndex + 1} in workstream ${workstreamIndex + 1} duplicates an earlier task key.`);
+            taskKeys.add(taskKey);
+            taskCount += 1;
+            if (taskCount > 50)
+                invalid('A program supports at most 50 tasks.');
+            const normalized = {
+                key: taskKey,
+                title: requiredString(taskSource.title, `Task ${taskIndex + 1} in workstream ${workstreamIndex + 1} title`),
+            };
+            for (const field of ['description', 'assignee', 'category', 'type']) {
+                const value = optionalString(taskSource, field, `Task ${taskIndex + 1} in workstream ${workstreamIndex + 1} ${field}`);
+                if (value !== undefined)
+                    normalized[field] = value;
+            }
+            for (const field of ['priority', 'complexity']) {
+                const value = optionalNumber(taskSource, field, `Task ${taskIndex + 1} in workstream ${workstreamIndex + 1} ${field}`);
+                if (value !== undefined)
+                    normalized[field] = value;
+            }
+            for (const field of ['scheduledDate', 'dueDate']) {
+                if (taskSource[field] !== undefined)
+                    normalized[field] = date(taskSource[field], `Task ${taskIndex + 1} in workstream ${workstreamIndex + 1} ${field}`);
+            }
+            return normalized;
+        });
+        const description = optionalString(source, 'description', `Workstream ${workstreamIndex + 1} description`);
+        const ownerId = optionalString(source, 'ownerId', `Workstream ${workstreamIndex + 1} ownerId`);
+        const order = optionalNumber(source, 'order', `Workstream ${workstreamIndex + 1} order`);
+        return {
+            key: workstreamKey,
+            title: requiredString(source.title, `Workstream ${workstreamIndex + 1} title`),
+            ...(description !== undefined ? { description } : {}),
+            ...(ownerId !== undefined ? { ownerId } : {}),
+            ...(order !== undefined ? { order } : {}),
+            tasks,
+        };
+    });
+    if (!Array.isArray(root.dependencies))
+        invalid('dependencies must be an array.');
+    if (root.dependencies.length > 100)
+        invalid('A program supports at most 100 dependencies.');
+    const edgeKeys = new Set();
+    const dependencies = root.dependencies.map((candidate, index) => {
+        const source = exactObject(candidate, ['taskKey', 'dependsOnTaskKey'], `Dependency ${index + 1}`);
+        const taskKey = key(source.taskKey, `Dependency ${index + 1} taskKey`);
+        const dependsOnTaskKey = key(source.dependsOnTaskKey, `Dependency ${index + 1} dependsOnTaskKey`);
+        if (taskKey === dependsOnTaskKey)
+            invalid(`Dependency ${index + 1} cannot reference the same task twice.`);
+        if (!taskKeys.has(taskKey) || !taskKeys.has(dependsOnTaskKey))
+            invalid(`Dependency ${index + 1} references a missing task.`);
+        const edgeKey = `${taskKey}\u0000${dependsOnTaskKey}`;
+        if (edgeKeys.has(edgeKey))
+            invalid(`Dependency ${index + 1} duplicates an earlier dependency.`);
+        edgeKeys.add(edgeKey);
+        return { taskKey, dependsOnTaskKey };
+    }).sort((left, right) => (left.taskKey < right.taskKey ? -1 : left.taskKey > right.taskKey ? 1
+        : left.dependsOnTaskKey < right.dependsOnTaskKey ? -1
+            : left.dependsOnTaskKey > right.dependsOnTaskKey ? 1 : 0));
+    const adjacency = new Map();
+    for (const dependency of dependencies) {
+        const edges = adjacency.get(dependency.taskKey) || [];
+        edges.push(dependency.dependsOnTaskKey);
+        adjacency.set(dependency.taskKey, edges);
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (taskKey) => {
+        if (visiting.has(taskKey))
+            invalid('Program dependencies contain a cycle.');
+        if (visited.has(taskKey))
+            return;
+        visiting.add(taskKey);
+        for (const dependencyKey of adjacency.get(taskKey) || [])
+            visit(dependencyKey);
+        visiting.delete(taskKey);
+        visited.add(taskKey);
+    };
+    for (const taskKey of taskKeys)
+        visit(taskKey);
+    const graph = { initiative, workstreams, dependencies };
+    if (Buffer.byteLength(canonicalWorkspaceSyncJson(graph), 'utf8') > MAX_CANONICAL_BYTES) {
+        invalid('The canonical program payload exceeds 128 KiB.');
+    }
+    return graph;
+}
+function digestId(prefix, values) {
+    const digest = createHash('sha256').update(canonicalWorkspaceSyncJson(values), 'utf8').digest('hex').slice(0, 32);
+    return `${prefix}-${digest}`;
+}
+function snapshot(result, id, _label) {
+    const source = result && typeof result === 'object' ? result : {};
+    const entity = source.authoritativeInitiative || source.provisionalInitiative
+        || source.authoritativeWorkstream || source.provisionalWorkstream
+        || source.authoritativeTask || source.provisionalTask || source;
+    const referenceLabel = typeof entity?.referenceLabel === 'string' && entity.referenceLabel.trim()
+        ? entity.referenceLabel.trim() : null;
+    return { id, referenceLabel };
+}
+function relationshipOutcome(result) {
+    const outcome = result && typeof result === 'object' ? result.outcome : undefined;
+    return outcome === 'existing' ? 'existing' : 'created';
+}
+export function createProgramScaffoldService(config) {
+    const store = config.store || new WorkspaceSyncDurabilityStore(config.db);
+    const now = config.now || (() => new Date());
+    const resolveIdentity = (idempotencyKey, operationId) => {
+        if (config.deriveAggregateIdentity) {
+            const identity = config.deriveAggregateIdentity({ idempotencyKey, operationId });
+            if (identity.operationId !== operationId)
+                invalid('Aggregate identity operationId does not match the derived operation id.');
+            requiredString(identity.tenantId, 'Aggregate tenantId');
+            requiredString(identity.workspaceId, 'Aggregate workspaceId');
+            requiredString(identity.clientId, 'Aggregate clientId');
+            return identity;
+        }
+        const tenantId = requiredString(config.tenantId, 'tenantId');
+        const workspaceId = requiredString(config.workspaceId, 'workspaceId');
+        const clientId = requiredString(config.clientId, 'clientId');
+        return { tenantId, workspaceId, clientId, operationId };
+    };
+    return {
+        scaffold(input) {
+            if (config.enabled === false)
+                throw new ProgramScaffoldDisabledError();
+            const callerScope = requiredString(config.callerScope, 'callerScope');
+            const graph = canonicalize(input);
+            const graphJson = canonicalWorkspaceSyncJson(graph);
+            const graphFingerprint = createHash('sha256').update(graphJson, 'utf8').digest('hex');
+            const idempotencyKey = input.dryRun ? graphFingerprint : requiredString(input.idempotencyKey, 'idempotencyKey');
+            const aggregateOperationId = digestId('operation', [callerScope, idempotencyKey, 'program-scaffold']);
+            const createdAt = now().toISOString();
+            const routerContext = {
+                createdAt,
+                now: () => new Date(createdAt),
+                deferPostCommitNotification: () => { },
+            };
+            const initiativeId = digestId('initiative', [callerScope, idempotencyKey, 'initiative']);
+            const workstreamIds = new Map(graph.workstreams.map((workstream) => [
+                workstream.key,
+                digestId('workstream', [callerScope, idempotencyKey, 'workstream', workstream.key]),
+            ]));
+            const taskIds = new Map(graph.workstreams.flatMap((workstream) => workstream.tasks.map((task) => [
+                task.key,
+                digestId('task', [callerScope, idempotencyKey, 'task', task.key]),
+            ])));
+            const counts = {
+                workstreams: graph.workstreams.length,
+                tasks: taskIds.size,
+                dependencies: graph.dependencies.length,
+            };
+            const order = {
+                workstreamKeys: graph.workstreams.map((workstream) => workstream.key),
+                taskKeys: graph.workstreams.flatMap((workstream) => workstream.tasks.map((task) => task.key)),
+            };
+            const parseCommittedResponse = (responseJson) => {
+                let response;
+                try {
+                    response = JSON.parse(responseJson);
+                }
+                catch {
+                    throw new ProgramScaffoldCommittedResponseInvalidError();
+                }
+                if (!response || typeof response !== 'object' || Array.isArray(response)) {
+                    throw new ProgramScaffoldCommittedResponseInvalidError();
+                }
+                const value = response;
+                const keys = Object.keys(value).sort();
+                const expectedKeys = [
+                    'counts', 'dependencies', 'initiative', 'mode', 'operationId', 'order', 'tasks', 'workstreams',
+                ].sort();
+                const exactKeys = keys.length === expectedKeys.length
+                    && keys.every((candidate, index) => candidate === expectedKeys[index]);
+                const exactBase = value.mode === (config.runtimeMode === 'cloud' ? 'committed' : 'pending')
+                    && value.operationId === aggregateOperationId
+                    && canonicalWorkspaceSyncJson(value.counts) === canonicalWorkspaceSyncJson(counts)
+                    && canonicalWorkspaceSyncJson(value.order) === canonicalWorkspaceSyncJson(order);
+                const validMapping = (candidate, expectedId, expectedKey) => {
+                    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
+                        return false;
+                    const mapping = candidate;
+                    const mappingKeys = Object.keys(mapping).sort();
+                    const expectedMappingKeys = expectedKey === undefined
+                        ? ['id', 'referenceLabel'] : ['id', 'key', 'referenceLabel'];
+                    return mappingKeys.length === expectedMappingKeys.length
+                        && mappingKeys.every((candidateKey, index) => candidateKey === expectedMappingKeys[index])
+                        && mapping.id === expectedId
+                        && (expectedKey === undefined || mapping.key === expectedKey)
+                        && (mapping.referenceLabel === null
+                            || (typeof mapping.referenceLabel === 'string' && Boolean(mapping.referenceLabel.trim())));
+                };
+                const validInitiative = validMapping(value.initiative, initiativeId);
+                const validWorkstreams = Array.isArray(value.workstreams)
+                    && value.workstreams.length === graph.workstreams.length
+                    && value.workstreams.every((mapping, index) => validMapping(mapping, workstreamIds.get(graph.workstreams[index].key), graph.workstreams[index].key));
+                const orderedTasks = graph.workstreams.flatMap((workstream) => workstream.tasks);
+                const validTasks = Array.isArray(value.tasks)
+                    && value.tasks.length === orderedTasks.length
+                    && value.tasks.every((mapping, index) => validMapping(mapping, taskIds.get(orderedTasks[index].key), orderedTasks[index].key));
+                const validDependencies = Array.isArray(value.dependencies)
+                    && value.dependencies.length === graph.dependencies.length
+                    && value.dependencies.every((dependency, index) => {
+                        if (!dependency || typeof dependency !== 'object' || Array.isArray(dependency))
+                            return false;
+                        const mapping = dependency;
+                        const dependencyKeys = Object.keys(mapping).sort();
+                        const expected = graph.dependencies[index];
+                        return dependencyKeys.length === 3
+                            && dependencyKeys[0] === 'dependsOnTaskKey'
+                            && dependencyKeys[1] === 'outcome'
+                            && dependencyKeys[2] === 'taskKey'
+                            && mapping.taskKey === expected.taskKey
+                            && mapping.dependsOnTaskKey === expected.dependsOnTaskKey
+                            && (mapping.outcome === 'created' || mapping.outcome === 'existing');
+                    });
+                if (!exactKeys || !exactBase || !validInitiative || !validWorkstreams || !validTasks || !validDependencies) {
+                    throw new ProgramScaffoldCommittedResponseInvalidError();
+                }
+                return value;
+            };
+            const applyGraph = () => {
+                const initiativeRouter = config.createInitiativeRouter(digestId('operation', [aggregateOperationId, 'initiative']), routerContext);
+                if (initiativeRouter.enabled === false)
+                    throw new ProgramScaffoldDisabledError();
+                const initiative = snapshot(initiativeRouter.create(initiativeId, {
+                    title: graph.initiative.title,
+                    description: graph.initiative.description ?? null,
+                    ownerId: graph.initiative.ownerId ?? null,
+                    order: graph.initiative.order ?? null,
+                    attachments: [],
+                    createdAt,
+                }), initiativeId, 'Initiative');
+                const workstreamMappings = [];
+                const taskMappings = [];
+                for (const workstream of graph.workstreams) {
+                    const workstreamId = workstreamIds.get(workstream.key);
+                    const router = config.createWorkstreamRouter(digestId('operation', [aggregateOperationId, 'workstream', workstream.key]), routerContext);
+                    if (router.enabled === false)
+                        throw new ProgramScaffoldDisabledError();
+                    workstreamMappings.push({ key: workstream.key, ...snapshot(router.create(workstreamId, {
+                            initiativeId,
+                            title: workstream.title,
+                            description: workstream.description ?? null,
+                            ownerId: workstream.ownerId ?? null,
+                            order: workstream.order ?? null,
+                            attachments: [],
+                            createdAt,
+                        }), workstreamId, `Workstream ${workstream.key}`) });
+                    for (const task of workstream.tasks) {
+                        const taskId = taskIds.get(task.key);
+                        const taskRouter = config.createTaskRouter(digestId('operation', [aggregateOperationId, 'task', task.key]), routerContext);
+                        if (taskRouter.enabled === false)
+                            throw new ProgramScaffoldDisabledError();
+                        const { key: _key, ...taskPayload } = task;
+                        taskMappings.push({ key: task.key, ...snapshot(taskRouter.create({
+                                id: taskId,
+                                workstreamId,
+                                ...taskPayload,
+                            }), taskId, `Task ${task.key}`) });
+                    }
+                }
+                const dependencyMappings = graph.dependencies.map((dependency) => {
+                    const router = config.createRelationshipRouter(digestId('operation', [
+                        aggregateOperationId, 'dependency', dependency.taskKey, dependency.dependsOnTaskKey,
+                    ]), routerContext);
+                    if (router.enabled === false)
+                        throw new ProgramScaffoldDisabledError();
+                    const result = router.mutate({
+                        sourceTaskId: taskIds.get(dependency.taskKey),
+                        targetTaskId: taskIds.get(dependency.dependsOnTaskKey),
+                        type: 'depends_on',
+                        mutationKind: 'link',
+                        actorRef: config.actorRef,
+                    });
+                    return { ...dependency, outcome: relationshipOutcome(result) };
+                });
+                return { counts, order, initiative, workstreams: workstreamMappings, tasks: taskMappings, dependencies: dependencyMappings };
+            };
+            if (input.dryRun) {
+                const sentinel = {};
+                try {
+                    config.db.transaction(() => {
+                        sentinel.preview = applyGraph();
+                        throw sentinel;
+                    })();
+                }
+                catch (error) {
+                    if (error !== sentinel)
+                        throw error;
+                }
+                if (!sentinel.preview)
+                    throw new Error('Program scaffold preview did not complete.');
+                return {
+                    mode: 'preview', operationId: null, counts, order,
+                    dependencies: graph.dependencies.map((dependency) => ({ ...dependency, outcome: 'validated' })),
+                };
+            }
+            const identity = resolveIdentity(idempotencyKey, aggregateOperationId);
+            const requestFingerprint = createHash('sha256').update(canonicalWorkspaceSyncJson({
+                contractVersion: WORKSPACE_SYNC_CONTRACT_VERSION,
+                identity,
+                graph,
+            }), 'utf8').digest('hex');
+            let didCommit = false;
+            const result = config.db.transaction(() => {
+                const reservation = store.reserveOperation({
+                    identity,
+                    requestFingerprint,
+                    now: createdAt,
+                    leaseExpiresAt: new Date(Date.parse(createdAt) + OPERATION_LEASE_MS).toISOString(),
+                });
+                if (reservation.state === 'in_progress')
+                    throw new ProgramScaffoldInProgressError(reservation.retryAt);
+                if (reservation.state === 'committed')
+                    return parseCommittedResponse(reservation.responseJson);
+                const applied = applyGraph();
+                const response = {
+                    mode: config.runtimeMode === 'cloud' ? 'committed' : 'pending',
+                    operationId: aggregateOperationId,
+                    ...applied,
+                };
+                store.commitReservedOperationResponse({
+                    identity,
+                    requestFingerprint,
+                    leaseOwner: reservation.leaseOwner,
+                    now: createdAt,
+                    response,
+                });
+                didCommit = true;
+                return response;
+            })();
+            if (didCommit && config.onPostCommit) {
+                try {
+                    config.onPostCommit(result);
+                }
+                catch (error) {
+                    try {
+                        config.onPostCommitError?.(error);
+                    }
+                    catch { /* the aggregate is already committed */ }
+                }
+            }
+            return result;
+        },
+    };
+}