@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/sync/v3/entityEventLegacyAdoptionService.js

@@ -0,0 +1,180 @@
+import { fingerprintWorkspaceSyncPayload, WORKSPACE_SYNC_CONTRACT_VERSION, WorkspaceSyncRevisionConflictError, } from './syncDurabilityStore.js';
+import { serializeWorkspaceSyncV3EntityEventPayload, validateWorkspaceSyncV3EntityEventPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { isLegacyEntityEventAdoptionIdentity, LEGACY_ENTITY_EVENT_ADOPTION_MAX_PAYLOAD_BYTES, } from './entityEventLegacyAdoptionContract.js';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+export class EntityEventLegacyAdoptionError extends Error {
+    code = 'WORKSPACE_SYNC_LEGACY_ENTITY_EVENT_ADOPTION_INVALID';
+    statusCode = 409;
+    constructor(message) {
+        super(message);
+        this.name = 'EntityEventLegacyAdoptionError';
+    }
+}
+function invalidateWorkspaceRepairSnapshots(core, tenantId, workspaceId) {
+    const db = core.getDatabaseAdapter();
+    db.prepare(`
+        DELETE FROM workspace_sync_repair_snapshot_entries
+        WHERE tenant_id = ? AND workspace_id = ?
+    `).run(tenantId, workspaceId);
+    db.prepare(`
+        DELETE FROM workspace_sync_repair_snapshots
+        WHERE tenant_id = ? AND workspace_id = ?
+    `).run(tenantId, workspaceId);
+}
+export function validateEntityEventLegacyAdoptionBatch(input) {
+    if (!Array.isArray(input.events) || input.events.length < 1 || input.events.length > 100) {
+        throw new EntityEventLegacyAdoptionError('Legacy entity-event adoption requires 1-100 events.');
+    }
+    const events = input.events.map((event) => {
+        try {
+            return validateWorkspaceSyncV3EntityEventPayload(event);
+        }
+        catch (error) {
+            throw new EntityEventLegacyAdoptionError(error instanceof Error ? error.message : 'Legacy entity event is invalid.');
+        }
+    });
+    const identities = new Set();
+    for (const event of events) {
+        if (event.workspaceId !== input.workspaceId) {
+            throw new EntityEventLegacyAdoptionError('Legacy entity event belongs to a different workspace.');
+        }
+        if (identities.has(event.id)) {
+            throw new EntityEventLegacyAdoptionError(`Legacy entity-event adoption contains duplicate identity ${event.id}.`);
+        }
+        identities.add(event.id);
+    }
+    if (Buffer.byteLength(canonicalWorkspaceSyncJson({ events }), 'utf8')
+        > LEGACY_ENTITY_EVENT_ADOPTION_MAX_PAYLOAD_BYTES) {
+        throw new EntityEventLegacyAdoptionError('Legacy entity-event adoption payload exceeds the transport-safe byte limit.');
+    }
+    return events;
+}
+export function runDurableEntityEventLegacyAdoption(input) {
+    if (String(input.baseLifecycleRevision) !== '0') {
+        throw new EntityEventLegacyAdoptionError('Legacy entity-event adoption lifecycle revision must be 0.');
+    }
+    const baseEntityRevision = String(input.baseEntityRevision);
+    if (!/^(0|[1-9]\d*)$/.test(baseEntityRevision)) {
+        throw new EntityEventLegacyAdoptionError('Legacy entity-event adoption entity revision is invalid.');
+    }
+    if (!isLegacyEntityEventAdoptionIdentity(input)) {
+        throw new EntityEventLegacyAdoptionError('Legacy entity-event adoption identity is invalid.');
+    }
+    const events = validateEntityEventLegacyAdoptionBatch({
+        workspaceId: input.workspaceId,
+        events: input.events,
+    });
+    const identity = {
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+        clientId: input.clientId,
+        operationId: input.operationId,
+    };
+    const requestFingerprint = fingerprintWorkspaceSyncPayload({
+        contractVersion: WORKSPACE_SYNC_CONTRACT_VERSION,
+        identity,
+        operation: {
+            domain: 'entity-event',
+            entityId: events[0].id,
+            mutationKind: 'adopt-legacy-batch',
+            baseEntityRevision,
+            baseLifecycleRevision: '0',
+            events,
+        },
+    });
+    const existingOperation = input.store.readOperation({
+        identity,
+        requestFingerprint,
+    });
+    if (existingOperation?.state === 'committed') {
+        return {
+            state: 'committed',
+            replayed: true,
+            responseJson: existingOperation.responseJson,
+            response: JSON.parse(existingOperation.responseJson),
+        };
+    }
+    const reservation = input.store.reserveOperation({
+        identity,
+        requestFingerprint,
+        now: input.now,
+        leaseExpiresAt: input.leaseExpiresAt,
+        leaseOwner: input.leaseOwner,
+    });
+    if (reservation.state === 'in_progress')
+        return reservation;
+    if (reservation.state === 'committed') {
+        return {
+            state: 'committed',
+            replayed: true,
+            responseJson: reservation.responseJson,
+            response: JSON.parse(reservation.responseJson),
+        };
+    }
+    const accepted = input.store.acceptReservedOperationBatch({
+        identity,
+        requestFingerprint,
+        leaseOwner: reservation.leaseOwner,
+        now: input.now,
+        entries: events.map((event, index) => ({
+            domain: 'entity-event',
+            entityId: event.id,
+            mutationKind: 'append',
+            revisionKind: 'metadata',
+            baseEntityRevision: index === 0 ? baseEntityRevision : '0',
+            baseLifecycleRevision: '0',
+            baseRevisionPolicy: 'current',
+            buildCanonicalFingerprint: () => fingerprintWorkspaceSyncPayload(event),
+            buildAuthoritativePayload: () => event,
+        })),
+        applyMutation: () => {
+            for (const event of events) {
+                const current = input.core.getEntityEventForSync({
+                    workspaceId: input.workspaceId,
+                    eventId: event.id,
+                });
+                if (current
+                    && fingerprintWorkspaceSyncPayload(serializeWorkspaceSyncV3EntityEventPayload(current)) !== fingerprintWorkspaceSyncPayload(event)) {
+                    throw new WorkspaceSyncRevisionConflictError({
+                        stage: 'legacy-entity-event-adoption-conflict',
+                        domain: 'entity-event',
+                        entityId: event.id,
+                    });
+                }
+            }
+            for (const event of events) {
+                input.core.upsertEntityEventForSync(event, { allowAuthoritativeReplacement: true });
+            }
+            // Adoption can restore a canonical body against an existing
+            // journal coordinate. Since the sequence does not advance, any
+            // immutable repair snapshot created before that body existed must
+            // be invalidated explicitly.
+            invalidateWorkspaceRepairSnapshots(input.core, input.tenantId, input.workspaceId);
+            return events;
+        },
+        buildResponse: (acceptedEvents, revisions) => ({
+            success: true,
+            contractVersion: WORKSPACE_SYNC_CONTRACT_VERSION,
+            workspaceId: input.workspaceId,
+            clientId: input.clientId,
+            operationId: input.operationId,
+            acceptedSequence: revisions.at(-1).sequence,
+            authoritative: revisions.map((revision, index) => ({
+                domain: 'entity-event',
+                entityId: revision.entityId,
+                mutationKind: index === 0 ? 'adopt-legacy-batch' : 'append',
+                sequence: revision.sequence,
+                entityRevision: revision.entityRevision,
+                lifecycleRevision: revision.lifecycleRevision,
+                payload: acceptedEvents[index],
+            })),
+        }),
+    });
+    const response = JSON.parse(accepted.responseJson);
+    return {
+        state: 'committed',
+        replayed: false,
+        responseJson: accepted.responseJson,
+        response,
+    };
+}

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

@@ -0,0 +1,11 @@
+import { type WorkspaceSyncActivityRevision } from './taskActivityJournal.js';
+export declare function validateInitiativeActivityAuthoritativeRevision(input: {
+    response: Record<string, unknown>;
+    authoritative: Record<string, unknown>;
+    activityId: string;
+    invalid: (message: string) => Error;
+}): {
+    initiativeSequence: string;
+    operationHighWatermark: string;
+    activityRevision: WorkspaceSyncActivityRevision;
+};

package/dist/sync/v3/initiativeActivityAuthoritativeRevision.js

@@ -0,0 +1,23 @@
+import { WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN, } from './taskActivityJournal.js';
+const SEQUENCE_PATTERN = /^[1-9]\d*$/;
+export function validateInitiativeActivityAuthoritativeRevision(input) {
+    const acceptedSequence = input.response.acceptedSequence;
+    const operationHighWatermark = input.response.operationHighWatermark;
+    const initiativeSequence = input.authoritative.sequence;
+    const activityRevision = input.response.activityRevision;
+    if (typeof acceptedSequence !== 'string' || !SEQUENCE_PATTERN.test(acceptedSequence)
+        || typeof initiativeSequence !== 'string' || !SEQUENCE_PATTERN.test(initiativeSequence)
+        || acceptedSequence !== initiativeSequence
+        || typeof operationHighWatermark !== 'string' || !SEQUENCE_PATTERN.test(operationHighWatermark)
+        || !activityRevision || typeof activityRevision !== 'object'
+        || activityRevision.domain !== WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN
+        || activityRevision.entityId !== input.activityId
+        || typeof activityRevision.sequence !== 'string' || !SEQUENCE_PATTERN.test(activityRevision.sequence)
+        || activityRevision.entityRevision !== '1'
+        || activityRevision.lifecycleRevision !== '0'
+        || operationHighWatermark !== activityRevision.sequence
+        || BigInt(activityRevision.sequence) !== BigInt(initiativeSequence) + 1n) {
+        throw input.invalid('Authoritative initiative and activity revisions are not in canonical sequence order.');
+    }
+    return { initiativeSequence, operationHighWatermark, activityRevision };
+}

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

@@ -0,0 +1,8 @@
+import type { WorkspaceSyncPlanningMutationKind } from '../workspaceSyncModel.js';
+export declare function buildInitiativeActivityEventId(input: {
+    workspaceId: string;
+    clientId: string;
+    operationId: string;
+    initiativeId: string;
+    mutationKind: WorkspaceSyncPlanningMutationKind;
+}): string;

package/dist/sync/v3/initiativeActivityIdentity.js

@@ -0,0 +1,14 @@
+import { createHash } from 'crypto';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+export function buildInitiativeActivityEventId(input) {
+    const digest = createHash('sha256').update(canonicalWorkspaceSyncJson({
+        contractVersion: 3,
+        domain: 'initiative',
+        mutationKind: input.mutationKind,
+        workspaceId: String(input.workspaceId || '').trim(),
+        clientId: String(input.clientId || '').trim(),
+        operationId: String(input.operationId || '').trim(),
+        initiativeId: String(input.initiativeId || '').trim(),
+    }), 'utf8').digest('hex');
+    return `entity-event-sync-v3-${digest}`;
+}

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

@@ -0,0 +1,26 @@
+import type { InitiativeItem } from '../../core/Taskforce.js';
+import type { WorkspaceSyncInitiativeSnapshot } from '../workspaceSyncModel.js';
+import { WorkspaceSyncDurabilityStore, type WorkspaceSyncTaskMetadataCoexistenceDirection } from './syncDurabilityStore.js';
+export interface InitiativeCoexistenceCore {
+    getInitiative(id: string, workspaceId?: string): InitiativeItem | null;
+    upsertInitiativeForSync(initiative: InitiativeItem, workspaceId?: string | null): InitiativeItem;
+    installDurableInitiativeAuthoritativeForSync(initiative: InitiativeItem, workspaceId: string): InitiativeItem;
+    notifyDurableInitiativeCommitted(workspaceId: string, initiativeId: string): void;
+}
+export declare function applyInitiativeSyncChangesWithCoexistence(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: InitiativeCoexistenceCore;
+    tenantId: string;
+    workspaceId: string;
+    direction: WorkspaceSyncTaskMetadataCoexistenceDirection;
+    incomingInitiatives: Map<string, WorkspaceSyncInitiativeSnapshot>;
+    assertedActiveInitiativeIds?: ReadonlySet<string>;
+    requiredProjectionOwner?: 'v2' | 'v3';
+    deferNotifications?: boolean;
+    now: string;
+}): {
+    appliedIds: string[];
+    protectedIds: string[];
+    notificationIds: string[];
+    revisionStates: Record<string, 'applied' | 'current' | 'stale'>;
+};

package/dist/sync/v3/initiativeCoexistence.js

@@ -0,0 +1,148 @@
+import { serializeInitiativeForSync } from '../planningSyncPayload.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncRevisionConflictError, } from './syncDurabilityStore.js';
+const OWNERSHIP_PAGE_SIZE = 100;
+function withoutRevision(initiative) {
+    const { durableRevision: _durableRevision, ...body } = initiative;
+    return body;
+}
+function readOwnershipById(input) {
+    const result = new Map();
+    for (let offset = 0; offset < input.entityIds.length; offset += OWNERSHIP_PAGE_SIZE) {
+        const page = input.entityIds.slice(offset, offset + OWNERSHIP_PAGE_SIZE);
+        for (const ownership of input.store.listWorkspaceDomainOwnership({
+            tenantId: input.tenantId,
+            workspaceId: input.workspaceId,
+            domain: 'initiative',
+            entityIds: page,
+        }))
+            result.set(ownership.entityId, ownership);
+    }
+    return result;
+}
+function assertCanonicalMarker(initiative, marker) {
+    const body = withoutRevision(initiative);
+    const canonical = serializeInitiativeForSync(body);
+    if (fingerprintWorkspaceSyncPayload(canonical) !== marker.canonicalFingerprint) {
+        throw new WorkspaceSyncRevisionConflictError();
+    }
+    return canonical;
+}
+export function applyInitiativeSyncChangesWithCoexistence(input) {
+    const entityIds = Array.from(input.incomingInitiatives.keys()).map((id) => String(id || '').trim()).filter(Boolean).sort();
+    if (entityIds.length === 0)
+        return { appliedIds: [], protectedIds: [], notificationIds: [], revisionStates: {} };
+    const appliedIds = [];
+    const protectedIds = [];
+    const durableAppliedIds = [];
+    const revisionStates = {};
+    input.store.runWorkspaceDomainCoexistenceTransaction({
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+        direction: input.direction,
+        targets: entityIds.map((entityId) => ({ domain: 'initiative', entityId })),
+        now: input.now,
+        apply: () => {
+            if (input.requiredProjectionOwner) {
+                const projection = input.store.readInitiativeProjectionOwnership({
+                    tenantId: input.tenantId,
+                    workspaceId: input.workspaceId,
+                });
+                if (projection.owner !== input.requiredProjectionOwner) {
+                    protectedIds.push(...entityIds);
+                    return;
+                }
+            }
+            const ownershipById = readOwnershipById({ ...input, entityIds });
+            for (const entityId of entityIds) {
+                const initiative = input.incomingInitiatives.get(entityId);
+                const marker = initiative.durableRevision;
+                const ownership = ownershipById.get(entityId);
+                if (!ownership)
+                    throw new Error(`Initiative ownership projection is missing ${entityId}.`);
+                if (input.direction === 'cloud-push') {
+                    if (marker)
+                        throw new WorkspaceSyncRevisionConflictError();
+                    if (ownership.activeOperation || ownership.owned || input.assertedActiveInitiativeIds?.has(entityId)) {
+                        protectedIds.push(entityId);
+                        continue;
+                    }
+                    input.core.upsertInitiativeForSync(withoutRevision(initiative), input.workspaceId);
+                    appliedIds.push(entityId);
+                    continue;
+                }
+                if (ownership.activeOperation) {
+                    protectedIds.push(entityId);
+                    continue;
+                }
+                if (!marker) {
+                    if (ownership.owned) {
+                        protectedIds.push(entityId);
+                        continue;
+                    }
+                    input.core.upsertInitiativeForSync(withoutRevision(initiative), input.workspaceId);
+                    appliedIds.push(entityId);
+                    continue;
+                }
+                const canonical = assertCanonicalMarker(initiative, marker);
+                const incomingRevision = BigInt(marker.entityRevision);
+                const currentRevision = BigInt(ownership.entityRevision);
+                if (incomingRevision === currentRevision) {
+                    if (ownership.lifecycleRevision !== marker.lifecycleRevision
+                        || ownership.lastSequence !== marker.sequence
+                        || ownership.canonicalFingerprint !== marker.canonicalFingerprint)
+                        throw new WorkspaceSyncRevisionConflictError();
+                    const existing = input.core.getInitiative(entityId, input.workspaceId);
+                    if (!existing || fingerprintWorkspaceSyncPayload(serializeInitiativeForSync(existing)) !== marker.canonicalFingerprint) {
+                        throw new WorkspaceSyncRevisionConflictError();
+                    }
+                    revisionStates[entityId] = 'current';
+                    protectedIds.push(entityId);
+                    continue;
+                }
+                if (incomingRevision < currentRevision) {
+                    revisionStates[entityId] = 'stale';
+                    protectedIds.push(entityId);
+                    continue;
+                }
+                const replicated = input.store.applyReplicatedEntityRevision({
+                    tenantId: input.tenantId,
+                    workspaceId: input.workspaceId,
+                    domain: 'initiative',
+                    entityId,
+                    sequence: marker.sequence,
+                    entityRevision: marker.entityRevision,
+                    lifecycleRevision: marker.lifecycleRevision,
+                    canonicalFingerprint: marker.canonicalFingerprint,
+                    now: input.now,
+                    applyMutation: () => {
+                        const installed = input.core.installDurableInitiativeAuthoritativeForSync(canonical, input.workspaceId);
+                        if (fingerprintWorkspaceSyncPayload(serializeInitiativeForSync(installed)) !== marker.canonicalFingerprint) {
+                            throw new WorkspaceSyncRevisionConflictError();
+                        }
+                        return installed;
+                    },
+                });
+                if (replicated.state === 'deferred') {
+                    throw new WorkspaceSyncRevisionConflictError();
+                }
+                revisionStates[entityId] = replicated.state;
+                if (replicated.state === 'applied') {
+                    appliedIds.push(entityId);
+                    durableAppliedIds.push(entityId);
+                }
+                else {
+                    protectedIds.push(entityId);
+                }
+            }
+        },
+    });
+    if (!input.deferNotifications) {
+        for (const initiativeId of durableAppliedIds) {
+            try {
+                input.core.notifyDurableInitiativeCommitted(input.workspaceId, initiativeId);
+            }
+            catch { /* authoritative body and revision are already committed */ }
+        }
+    }
+    return { appliedIds, protectedIds, notificationIds: durableAppliedIds, revisionStates };
+}

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

@@ -0,0 +1,6 @@
+export declare function resolveInitiativeFeedActivationCapability(input: {
+    runtimeMode: 'local' | 'cloud';
+    env?: NodeJS.ProcessEnv;
+}): {
+    initiativeFeedActivation: boolean;
+};

package/dist/sync/v3/initiativeFeedActivationCapability.js

@@ -0,0 +1,16 @@
+import { isWorkspaceSyncV3InitiativeLegacyPushDisabled, isWorkspaceSyncV3PlanningActivationEnabled, isWorkspaceSyncV3PlanningCaptureEnabled } from './planningActivation.js';
+function isEnabled(value) {
+    return /^(1|true|on|yes)$/i.test(String(value || '').trim());
+}
+export function resolveInitiativeFeedActivationCapability(input) {
+    const env = input.env || process.env;
+    return {
+        initiativeFeedActivation: input.runtimeMode === 'local'
+            && isEnabled(env.TASKFORCE_SYNC_V3_INITIATIVE_FEED_ACTIVATION_ENABLED)
+            && isEnabled(env.TASKFORCE_SYNC_V3_LOCAL_FEED_APPLY_ENABLED)
+            && isWorkspaceSyncV3InitiativeLegacyPushDisabled(env)
+            && isWorkspaceSyncV3PlanningCaptureEnabled('initiative', env)
+            && isWorkspaceSyncV3PlanningActivationEnabled({ domain: 'initiative', surface: 'http', runtimeMode: 'local', env })
+            && isWorkspaceSyncV3PlanningActivationEnabled({ domain: 'initiative', surface: 'mcp', runtimeMode: 'local', env }),
+    };
+}

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

@@ -0,0 +1,26 @@
+import type { WorkspaceSyncPlanningComment } from '../workspaceSyncModel.js';
+import { type CanonicalPlanningAttachmentLink } from '../planningCanonicalFields.js';
+import type { WorkspaceSyncV3InitiativeMetadataPatch } from './workspaceSyncV3OperationProtocol.js';
+export type DurableInitiativeCreatePayload = {
+    title: string;
+    description: string | null;
+    ownerId: string | null;
+    order: number | null;
+    attachments: CanonicalPlanningAttachmentLink[];
+    createdAt: string;
+};
+export declare class DurableInitiativeMutationError extends Error {
+    readonly code: 'INITIATIVE_MUTATION_INVALID' | 'INITIATIVE_NOT_FOUND' | 'INITIATIVE_ID_CONFLICT' | 'INITIATIVE_STATE_CONFLICT' | 'INITIATIVE_OWNER_INVALID' | 'INITIATIVE_COMMENT_AUTHOR_INVALID' | 'INITIATIVE_ATTACHMENT_NOT_READY' | 'INITIATIVE_ATTACHMENT_INVALID';
+    readonly statusCode: number;
+    constructor(message: string, code: 'INITIATIVE_MUTATION_INVALID' | 'INITIATIVE_NOT_FOUND' | 'INITIATIVE_ID_CONFLICT' | 'INITIATIVE_STATE_CONFLICT' | 'INITIATIVE_OWNER_INVALID' | 'INITIATIVE_COMMENT_AUTHOR_INVALID' | 'INITIATIVE_ATTACHMENT_NOT_READY' | 'INITIATIVE_ATTACHMENT_INVALID', statusCode: number);
+}
+export declare function validateDurableInitiativeCreatePayload(value: unknown): DurableInitiativeCreatePayload;
+export declare function validateDurableInitiativeMetadataPatch(value: unknown): WorkspaceSyncV3InitiativeMetadataPatch;
+export declare function validateDurableInitiativeComment(value: unknown): WorkspaceSyncPlanningComment;
+export declare function validateDurableInitiativeMetadataPayload(value: unknown): {
+    patch: WorkspaceSyncV3InitiativeMetadataPatch;
+};
+export declare function validateDurableInitiativeCommentPayload(value: unknown): {
+    comment: WorkspaceSyncPlanningComment;
+};
+export declare function validateEmptyInitiativePayload(value: unknown, label: string): Record<string, never>;

package/dist/sync/v3/initiativeMutationPayload.js

@@ -0,0 +1,144 @@
+import { normalizePlanningComments, validateCanonicalPlanningAttachmentLinks, } from '../planningCanonicalFields.js';
+export class DurableInitiativeMutationError extends Error {
+    code;
+    statusCode;
+    constructor(message, code, statusCode) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.name = 'DurableInitiativeMutationError';
+    }
+}
+function fail(message) {
+    throw new DurableInitiativeMutationError(message, 'INITIATIVE_MUTATION_INVALID', 400);
+}
+function requireExactKeys(value, allowed, label) {
+    const actual = Object.keys(value).sort();
+    const expected = [...allowed].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        fail(`${label} contains missing or unsupported fields.`);
+    }
+}
+function requireObject(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail(`${label} must be an object.`);
+    return value;
+}
+function normalizeNullableString(value, label) {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string')
+        fail(`${label} must be a string or null.`);
+    return value;
+}
+function normalizeNullableId(value, label) {
+    const normalized = normalizeNullableString(value, label);
+    if (normalized === null)
+        return null;
+    const trimmed = normalized.trim();
+    if (!trimmed)
+        fail(`${label} must be a non-empty string or null.`);
+    return trimmed;
+}
+function normalizeOrder(value, label) {
+    if (value === null)
+        return null;
+    if (!Number.isInteger(value))
+        fail(`${label} must be an integer or null.`);
+    return Number(value);
+}
+function normalizeIso(value, label) {
+    if (typeof value !== 'string')
+        fail(`${label} must be an ISO timestamp.`);
+    const parsed = Date.parse(value.trim());
+    if (!Number.isFinite(parsed))
+        fail(`${label} must be an ISO timestamp.`);
+    return new Date(parsed).toISOString();
+}
+function normalizeAttachments(value) {
+    try {
+        return validateCanonicalPlanningAttachmentLinks(value);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : 'Initiative attachments are invalid.');
+    }
+}
+export function validateDurableInitiativeCreatePayload(value) {
+    const source = requireObject(value, 'Initiative create payload');
+    requireExactKeys(source, ['title', 'description', 'ownerId', 'order', 'attachments', 'createdAt'], 'Initiative create payload');
+    const title = typeof source.title === 'string' ? source.title.trim() : '';
+    if (!title)
+        fail('Initiative title is required.');
+    return {
+        title,
+        description: normalizeNullableString(source.description, 'Initiative description'),
+        ownerId: normalizeNullableId(source.ownerId, 'Initiative ownerId'),
+        order: normalizeOrder(source.order, 'Initiative order'),
+        attachments: normalizeAttachments(source.attachments),
+        createdAt: normalizeIso(source.createdAt, 'Initiative createdAt'),
+    };
+}
+export function validateDurableInitiativeMetadataPatch(value) {
+    const source = requireObject(value, 'Initiative metadata patch');
+    const keys = Object.keys(source);
+    const allowed = new Set(['title', 'description', 'ownerId', 'order', 'attachments']);
+    if (keys.length === 0 || keys.some((key) => !allowed.has(key))) {
+        fail('Initiative metadata patch must contain only supported fields and cannot be empty.');
+    }
+    const patch = {};
+    if (Object.prototype.hasOwnProperty.call(source, 'title')) {
+        const title = typeof source.title === 'string' ? source.title.trim() : '';
+        if (!title)
+            fail('Initiative title is required.');
+        patch.title = title;
+    }
+    if (Object.prototype.hasOwnProperty.call(source, 'description')) {
+        patch.description = normalizeNullableString(source.description, 'Initiative description');
+    }
+    if (Object.prototype.hasOwnProperty.call(source, 'ownerId')) {
+        patch.ownerId = normalizeNullableId(source.ownerId, 'Initiative ownerId');
+    }
+    if (Object.prototype.hasOwnProperty.call(source, 'order')) {
+        patch.order = normalizeOrder(source.order, 'Initiative order');
+    }
+    if (Object.prototype.hasOwnProperty.call(source, 'attachments')) {
+        patch.attachments = normalizeAttachments(source.attachments);
+    }
+    return patch;
+}
+export function validateDurableInitiativeComment(value) {
+    const source = requireObject(value, 'Initiative comment');
+    const allowed = source.submittedAuthor === undefined
+        ? ['id', 'author', 'text', 'timestamp']
+        : ['id', 'author', 'submittedAuthor', 'text', 'timestamp'];
+    requireExactKeys(source, allowed, 'Initiative comment');
+    if (typeof source.text !== 'string' || !source.text.trim()) {
+        fail('Initiative comment text is required.');
+    }
+    try {
+        const normalized = normalizePlanningComments([source]);
+        if (!normalized?.[0])
+            fail('Initiative comment is invalid.');
+        return { ...normalized[0], timestamp: normalizeIso(normalized[0].timestamp, 'Initiative comment timestamp') };
+    }
+    catch (error) {
+        if (error instanceof DurableInitiativeMutationError)
+            throw error;
+        fail(error instanceof Error ? error.message : 'Initiative comment is invalid.');
+    }
+}
+export function validateDurableInitiativeMetadataPayload(value) {
+    const source = requireObject(value, 'Initiative metadata payload');
+    requireExactKeys(source, ['patch'], 'Initiative metadata payload');
+    return { patch: validateDurableInitiativeMetadataPatch(source.patch) };
+}
+export function validateDurableInitiativeCommentPayload(value) {
+    const source = requireObject(value, 'Initiative comment payload');
+    requireExactKeys(source, ['comment'], 'Initiative comment payload');
+    return { comment: validateDurableInitiativeComment(source.comment) };
+}
+export function validateEmptyInitiativePayload(value, label) {
+    const source = requireObject(value, label);
+    requireExactKeys(source, [], label);
+    return {};
+}