@atolis-hq/wake 0.2.97 → 0.3.1

package/dist/src/orchestration/application/start-workflow.js

@@ -0,0 +1,51 @@
+import { WorkStatus } from '../../work/index.js';
+import { WorkflowInstanceKind } from '../contracts/vocabulary.js';
+import { validateChildProvenance } from '../domain/child-policy.js';
+import { startInstance } from '../domain/interpreter.js';
+export class StartWorkflow {
+    repository;
+    claims;
+    work;
+    definitions;
+    constructor(repository, claims, work, definitions) {
+        this.repository = repository;
+        this.claims = claims;
+        this.work = work;
+        this.definitions = definitions;
+    }
+    async execute(command, context) {
+        const item = await this.work.get(command.workItemId);
+        if (item === null || item.state !== WorkStatus.Open)
+            throw new Error('WorkItem must exist and be open');
+        const definition = this.definition(command.workflowName);
+        const existing = await this.repository.load(command.workflowInstanceId);
+        if (existing.view !== null)
+            return existing.view;
+        const startKind = validateChildProvenance(command);
+        if (startKind === WorkflowInstanceKind.Primary) {
+            await this.claims.claimPrimary(command.workItemId, command.workflowInstanceId, context);
+        }
+        else {
+            const parent = await this.repository.loadRequired(command.parentWorkflowInstanceId);
+            if (parent.view.workItemId !== command.workItemId ||
+                parent.view.orchestrationGroupId !== command.orchestrationGroupId)
+                throw new Error('Child workflow must share its parent WorkItem and orchestration group');
+        }
+        const decision = startInstance({
+            ...command,
+            definition,
+            occurredAt: context.occurredAt,
+            correlationId: context.correlationId,
+            causationId: context.commandId,
+        });
+        if (decision.kind === 'append')
+            await this.repository.append(command.workflowInstanceId, 0, decision.events);
+        return (await this.repository.loadRequired(command.workflowInstanceId)).view;
+    }
+    definition(name) {
+        const definition = this.definitions[name];
+        if (definition === undefined)
+            throw new Error(`Unknown workflow: ${name}`);
+        return definition;
+    }
+}

package/dist/src/orchestration/application/watch-reactor.js

@@ -0,0 +1,82 @@
+import { selectRunExecutionEvent } from '../../execution/index.js';
+import { correlationId, EventActorKind, } from '../../kernel/index.js';
+import { selectOrchestrationEvent } from '../contracts/event-decoder.js';
+import { workflowInstanceId, workflowName, } from '../contracts/identifiers.js';
+const checkpoint = 'reactor:orchestration.watch';
+export function createWatchReactor(orchestration, journal, checkpoints, runs) {
+    return {
+        async react(event, context) {
+            const causalCycle = orchestrationCausalCycleId(selectOrchestrationEvent(event));
+            const sourceWorkflowInstanceId = await resolveRunWorkflowInstanceId(event, runs);
+            for (const match of await orchestration.listWatchMatches(event.eventType)) {
+                if (sourceWorkflowInstanceId !== undefined &&
+                    match.parent.workflowInstanceId !== sourceWorkflowInstanceId)
+                    continue;
+                const requestId = workflowInstanceId(`${match.parent.workflowInstanceId}:watch:${match.watch.id}:trigger:${event.eventId}`);
+                const request = {
+                    parentWorkflowInstanceId: match.parent.workflowInstanceId,
+                    watchId: match.watch.id,
+                    triggerId: event.eventId,
+                    workflowName: workflowName(match.watch.workflow),
+                    causalCycleId: causalCycle ?? requestId,
+                    requestId,
+                    maxPerGroup: match.watch.maxPerGroup,
+                };
+                const requestContext = {
+                    ...context,
+                    commandId: watchCommandId(context, match, event),
+                };
+                if ((await orchestration.isCausalRepeat?.(match.parent.workflowInstanceId, event.eventId, causalCycle, request.requestId)) === true) {
+                    await orchestration.rejectCausalActivation(request, requestContext);
+                    continue;
+                }
+                const result = await orchestration.requestChild(request, requestContext);
+                if (result === undefined || result === null)
+                    throw new Error(`Watch child request ${request.requestId} did not complete durably`);
+            }
+        },
+        async runOnce(limit = 100) {
+            if (journal === undefined || checkpoints === undefined)
+                throw new Error('WatchReactor journal and checkpoints are required to run');
+            const events = await journal.readAll(await checkpoints.load(checkpoint), limit);
+            for (const event of events) {
+                await this.react(event, commandContext(event));
+                await checkpoints.save(checkpoint, event.globalPosition);
+            }
+            return events.length;
+        },
+    };
+}
+function commandContext(event) {
+    return {
+        commandId: `${event.eventId}:watch`,
+        correlationId: correlationId(event.correlationId),
+        occurredAt: event.occurredAt,
+        actor: { kind: EventActorKind.System, id: 'watch-reactor' },
+    };
+}
+/**
+ * A run-lifecycle event (e.g. `execution.run-succeeded`) fires for every run
+ * in the system, including a watch's own spawned child re-running its own
+ * activity on retry. Without this, `listWatchMatches` would treat any
+ * currently-eligible parent's declared event type as a match regardless of
+ * which run actually produced it, causing a child's own retry (or an
+ * unrelated workflow's run) to spuriously re-trigger the same watch.
+ */
+async function resolveRunWorkflowInstanceId(event, runs) {
+    if (runs === undefined)
+        return undefined;
+    const runEvent = selectRunExecutionEvent(event);
+    if (runEvent === null)
+        return undefined;
+    const run = (await runs.load(runEvent.stream.id)).view;
+    return run?.workflowInstanceId;
+}
+function orchestrationCausalCycleId(event) {
+    return event !== null && 'causalCycleId' in event.payload
+        ? event.payload.causalCycleId
+        : undefined;
+}
+function watchCommandId(context, match, event) {
+    return `${context.commandId}:parent:${match.parent.workflowInstanceId}:watch:${match.watch.id}:trigger:${event.eventId}`;
+}

package/dist/src/orchestration/contracts/activity-outcome.js

@@ -0,0 +1,18 @@
+import { ActivityOutcomeKind, } from '../../activities/index.js';
+import { signalName } from './identifiers.js';
+export function orchestrationActivityOutcome(outcome) {
+    if (outcome.kind !== ActivityOutcomeKind.Waiting)
+        return outcome;
+    if (typeof outcome.data !== 'object' || outcome.data === null)
+        throw new Error('Waiting Activity outcome lacks expectation');
+    const intentEventId = Reflect.get(outcome.data, 'intentEventId');
+    const rawSignalKind = Reflect.get(outcome.data, 'signalKind');
+    if (typeof intentEventId !== 'string' || intentEventId.length === 0)
+        throw new Error('Waiting Activity outcome requires intentEventId');
+    if (typeof rawSignalKind !== 'string' || rawSignalKind.length === 0)
+        throw new Error('Waiting Activity outcome requires signalKind');
+    return {
+        kind: ActivityOutcomeKind.Waiting,
+        data: { intentEventId, signalKind: signalName(rawSignalKind) },
+    };
+}

package/dist/src/orchestration/contracts/commands.js

@@ -0,0 +1 @@
+export {};

package/dist/src/orchestration/contracts/config.js

@@ -0,0 +1,128 @@
+import { z } from 'zod';
+import { ApprovalAuthorityKind, WorkflowStatus } from './vocabulary.js';
+import { WorkspaceMode } from '../../execution/index.js';
+import { MatchMode } from '../../kernel/index.js';
+const identifier = z.string().trim().min(1);
+const bound = z.object({ max: z.number().int().positive() }).strict();
+const approvalAuthorityKind = z.enum([
+    ApprovalAuthorityKind.Human,
+    ApprovalAuthorityKind.Auto,
+    ApprovalAuthorityKind.Watch,
+]);
+// Shorthand: a bare `human`/`auto` string, or an explicit `{ kind: watch, id }` reference.
+const approvalAuthorityConfigSchema = z.union([
+    z.literal(ApprovalAuthorityKind.Human),
+    z.literal(ApprovalAuthorityKind.Auto),
+    z.object({ kind: z.literal(ApprovalAuthorityKind.Watch), id: identifier }).strict(),
+]);
+export const awaitConfigSchema = z
+    .object({
+    signal: identifier,
+    from: z.array(approvalAuthorityConfigSchema).min(1).readonly(),
+})
+    .strict();
+const watchGateConfigSchema = z.union([
+    identifier,
+    z
+        .object({
+        watch: identifier,
+        onReject: z.object({ then: identifier }).strict().optional(),
+    })
+        .strict(),
+]);
+const commandName = z.string().regex(/^\/[a-z][a-z0-9-]*$/);
+const canonicalEventName = z.string().regex(/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/);
+const watchStatus = z.enum([WorkflowStatus.Active, WorkflowStatus.Waiting, WorkflowStatus.Blocked]);
+export const watchConfigSchema = z
+    .object({
+    id: identifier,
+    while: z
+        .object({
+        stages: z.array(identifier).min(1).readonly(),
+        statuses: z.array(watchStatus).min(1).readonly(),
+    })
+        .strict(),
+    on: z
+        .object({ events: z.array(canonicalEventName).min(1).readonly() })
+        .strict()
+        .optional(),
+    schedule: z.object({ cron: identifier }).strict().optional(),
+    workflow: identifier,
+    maxPerGroup: z.number().int().positive(),
+})
+    .strict()
+    .refine((value) => value.on !== undefined || value.schedule !== undefined, {
+    message: 'Watch requires on or schedule',
+});
+export const followOnActivityConfigSchema = z
+    .object({
+    use: identifier,
+    with: z.unknown().optional(),
+})
+    .strict();
+export const outcomeRouteConfigSchema = z
+    .object({
+    activities: z.array(followOnActivityConfigSchema).readonly().optional(),
+    then: identifier,
+    repeat: bound.optional(),
+    retry: bound.optional(),
+    await: awaitConfigSchema.optional(),
+    watchGates: z.array(watchGateConfigSchema).optional(),
+})
+    .strict();
+export const stageConfigSchema = z
+    .object({
+    activity: identifier,
+    with: z.unknown().optional(),
+    execution: z
+        .object({
+        workspace: z
+            .enum([WorkspaceMode.None, WorkspaceMode.ReadOnly, WorkspaceMode.Branch])
+            .optional(),
+        runnerPool: identifier.optional(),
+    })
+        .strict()
+        .optional(),
+    on: z
+        .record(identifier, outcomeRouteConfigSchema)
+        .refine((value) => Object.keys(value).length > 0),
+    requiresApproval: z.boolean().optional(),
+})
+    .strict();
+export const supplementalCommandConfigSchema = z
+    .object({
+    activity: identifier,
+    with: z.unknown().optional(),
+    allowedActors: z.array(approvalAuthorityKind).min(1).readonly(),
+})
+    .strict();
+export const workflowDefinitionConfigSchema = z
+    .object({
+    entry: identifier.optional(),
+    commands: z.record(commandName, supplementalCommandConfigSchema).optional(),
+    watches: z.array(watchConfigSchema).readonly().optional(),
+    stages: z
+        .record(identifier, stageConfigSchema)
+        .refine((value) => Object.keys(value).length > 0),
+})
+    .strict();
+// A single identifier is shorthand for a one-entry list, so every facet is matched the same way.
+const selectorValues = z
+    .union([identifier, z.array(identifier).min(1)])
+    .transform((value) => (typeof value === 'string' ? [value] : value));
+export const workflowSelectorConfigSchema = z
+    .object({
+    match: z
+        .object({
+        tags: selectorValues.optional(),
+        kind: selectorValues.optional(),
+        adapter: selectorValues.optional(),
+    })
+        .strict()
+        .refine((value) => Object.values(value).some((facet) => facet !== undefined), {
+        message: 'Workflow selector match requires at least one of tags, kind, or adapter',
+    }),
+    matchMode: z.enum([MatchMode.Any, MatchMode.All]).default(MatchMode.Any),
+    workflow: identifier,
+})
+    .strict();

package/dist/src/orchestration/contracts/event-decoder.js

@@ -0,0 +1,263 @@
+import { z } from 'zod';
+import { activationId, activityName, ActivityOutcomeKind } from '../../activities/index.js';
+import { WorkspaceMode } from '../../execution/index.js';
+import { brandedStringSchema, eventEnvelopeSchema, } from '../../kernel/index.js';
+import { workItemId } from '../../work/index.js';
+import { orchestrationActivityOutcome, } from './activity-outcome.js';
+import { OrchestrationEventType, } from './events.js';
+import { orchestrationGroupId, signalName, stageName, watchId, workflowInstanceId, workflowName, } from './identifiers.js';
+import { childOrchestrationGroupStreamId, OrchestrationStreamKind, primaryOrchestrationGroupStreamId, } from './streams.js';
+import { ApprovalAuthorityKind, TransitionTargetKind } from './vocabulary.js';
+export const workflowInstanceIdSchema = brandedStringSchema(workflowInstanceId);
+export const workflowStreamSchema = z
+    .object({
+    kind: z.literal(OrchestrationStreamKind.WorkflowInstance),
+    id: workflowInstanceIdSchema,
+})
+    .strict();
+const primaryGroupIdSchema = brandedStringSchema(primaryOrchestrationGroupStreamId);
+export const childGroupIdSchema = brandedStringSchema(childOrchestrationGroupStreamId);
+export const primaryGroupStreamSchema = z
+    .object({
+    kind: z.literal(OrchestrationStreamKind.Group),
+    id: primaryGroupIdSchema,
+})
+    .strict();
+export const childGroupStreamSchema = z
+    .object({
+    kind: z.literal(OrchestrationStreamKind.Group),
+    id: childGroupIdSchema,
+})
+    .strict();
+export const childMetadataShape = {
+    parentWorkflowInstanceId: workflowInstanceIdSchema,
+    watchId: z.string().min(1),
+    triggerId: z.string().min(1),
+    orchestrationGroupId: brandedStringSchema(orchestrationGroupId),
+    causalCycleId: z.string().min(1),
+    requestId: z.string().min(1),
+    childWorkflowInstanceId: workflowInstanceIdSchema,
+};
+export const childMetadataSchema = z.object(childMetadataShape).strict();
+export const outcomeSchema = z
+    .object({ kind: z.string().min(1), data: z.unknown().optional() })
+    .strict();
+export const waitingOutcomeSchema = z
+    .object({
+    kind: z.literal(ActivityOutcomeKind.Waiting),
+    data: z
+        .object({
+        intentEventId: z.string().min(1),
+        signalKind: brandedStringSchema(signalName),
+    })
+        .strict(),
+})
+    .strict()
+    .transform((outcome) => orchestrationActivityOutcome(outcome));
+const executionSchema = z
+    .object({
+    workspace: z
+        .enum([WorkspaceMode.None, WorkspaceMode.ReadOnly, WorkspaceMode.Branch])
+        .optional(),
+    runnerPool: z.string().min(1).optional(),
+})
+    .strict();
+export const activityRequestedSchema = z
+    .object({
+    activationId: brandedStringSchema(activationId),
+    ordinal: z.number().int().positive(),
+    activity: brandedStringSchema(activityName),
+    stage: brandedStringSchema(stageName).optional(),
+    input: z.unknown(),
+    execution: executionSchema.optional(),
+    followOnIndex: z.number().int().nonnegative().optional(),
+    supplemental: z.literal(true).optional(),
+})
+    .strict();
+const approvalAuthoritySchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal(ApprovalAuthorityKind.Human) }).strict(),
+    z.object({ kind: z.literal(ApprovalAuthorityKind.Auto) }).strict(),
+    z
+        .object({ kind: z.literal(ApprovalAuthorityKind.Watch), watch: brandedStringSchema(watchId) })
+        .strict(),
+]);
+const transitionTargetSchema = z.discriminatedUnion('kind', [
+    z
+        .object({ kind: z.literal(TransitionTargetKind.Stage), stage: brandedStringSchema(stageName) })
+        .strict(),
+    z.object({ kind: z.literal(TransitionTargetKind.Complete) }).strict(),
+    z
+        .object({
+        kind: z.literal(TransitionTargetKind.AwaitSignal),
+        signal: brandedStringSchema(signalName),
+    })
+        .strict(),
+]);
+export const expectationSchema = z
+    .object({
+    signalKind: brandedStringSchema(signalName),
+    resourceId: z.string().optional(),
+    revision: z.string().optional(),
+    from: z.array(approvalAuthoritySchema).min(1).optional(),
+    resume: transitionTargetSchema.optional(),
+    onRejectResume: transitionTargetSchema.optional(),
+})
+    .strict();
+export const signalSchema = z
+    .object({
+    kind: brandedStringSchema(signalName),
+    resourceId: z.string().optional(),
+    revision: z.string().optional(),
+    actorId: z.string().min(1),
+    actorDecision: z.object({ authorized: z.boolean(), evidenceId: z.string().min(1) }).strict(),
+    providerEventId: z.string().min(1),
+    childWorkflowInstanceId: workflowInstanceIdSchema.optional(),
+    requestId: z.string().optional(),
+    authority: approvalAuthoritySchema.optional(),
+    outcome: z
+        .enum([
+        ActivityOutcomeKind.Done,
+        ActivityOutcomeKind.Rejected,
+        ActivityOutcomeKind.Blocked,
+        ActivityOutcomeKind.Failed,
+    ])
+        .optional(),
+})
+    .strict();
+export const emptySchema = z.object({}).strict();
+export const workflowEnvelope = (eventType, payload) => eventEnvelopeSchema.extend({
+    eventType: z.literal(eventType),
+    stream: workflowStreamSchema,
+    payload,
+});
+export const primaryGroupEnvelope = (eventType, payload) => eventEnvelopeSchema.extend({
+    eventType: z.literal(eventType),
+    stream: primaryGroupStreamSchema,
+    payload,
+});
+export const childGroupEnvelope = (eventType, payload) => eventEnvelopeSchema.extend({
+    eventType: z.literal(eventType),
+    stream: childGroupStreamSchema,
+    payload,
+});
+const primaryClaimedEnvelope = primaryGroupEnvelope(OrchestrationEventType.PrimaryClaimed, z
+    .object({
+    workItemId: brandedStringSchema(workItemId),
+    workflowInstanceId: workflowInstanceIdSchema,
+})
+    .strict()).superRefine((event, context) => {
+    if (event.stream.id !== `primary:${event.payload.workItemId}`)
+        context.addIssue({
+            code: 'custom',
+            path: ['payload', 'workItemId'],
+            message: 'Primary claim work item must identify its stream',
+        });
+});
+const groupClaimedEnvelope = childGroupEnvelope(OrchestrationEventType.GroupClaimed, z.object({ key: childGroupIdSchema, requestId: z.string().min(1) }).strict()).superRefine((event, context) => {
+    if (event.payload.key !== event.stream.id)
+        context.addIssue({
+            code: 'custom',
+            path: ['payload', 'key'],
+            message: 'Group claim key must identify its stream',
+        });
+});
+const eventSchema = z.discriminatedUnion('eventType', [
+    workflowEnvelope(OrchestrationEventType.InstanceStarted, z.union([
+        z
+            .object({
+            workItemId: brandedStringSchema(workItemId),
+            workflowName: brandedStringSchema(workflowName),
+            orchestrationGroupId: brandedStringSchema(orchestrationGroupId),
+            entry: brandedStringSchema(stageName),
+        })
+            .strict(),
+        z
+            .object({
+            workItemId: brandedStringSchema(workItemId),
+            workflowName: brandedStringSchema(workflowName),
+            entry: brandedStringSchema(stageName),
+            ...childMetadataShape,
+        })
+            .strict(),
+    ])),
+    workflowEnvelope(OrchestrationEventType.StageEntered, z.object({ stage: brandedStringSchema(stageName) }).strict()),
+    workflowEnvelope(OrchestrationEventType.ActivityRequested, activityRequestedSchema),
+    workflowEnvelope(OrchestrationEventType.ActivityStarted, z.object({ activationId: brandedStringSchema(activationId) }).strict()),
+    workflowEnvelope(OrchestrationEventType.ActivityOutcomeAccepted, z
+        .object({
+        activationId: brandedStringSchema(activationId),
+        outcome: outcomeSchema,
+    })
+        .strict()),
+    workflowEnvelope(OrchestrationEventType.ActivityExecutionFailed, z
+        .object({
+        activationId: brandedStringSchema(activationId),
+        runId: z.string().min(1),
+        reason: z.string().min(1),
+    })
+        .strict()),
+    workflowEnvelope(OrchestrationEventType.ActivityWaiting, z
+        .object({
+        activationId: brandedStringSchema(activationId),
+        outcome: waitingOutcomeSchema,
+    })
+        .strict()),
+    workflowEnvelope(OrchestrationEventType.SignalWaitStarted, expectationSchema),
+    workflowEnvelope(OrchestrationEventType.SignalAccepted, signalSchema),
+    workflowEnvelope(OrchestrationEventType.SupplementalActivityQueued, z
+        .object({
+        activity: brandedStringSchema(activityName),
+        input: z.unknown(),
+        requestedBy: z.string().min(1),
+    })
+        .strict()),
+    workflowEnvelope(OrchestrationEventType.SupplementalActivityDequeued, z
+        .object({
+        activity: brandedStringSchema(activityName),
+        requestedBy: z.string().min(1),
+    })
+        .strict()),
+    workflowEnvelope(OrchestrationEventType.RepeatCounted, z.object({ routeId: z.string().min(1), count: z.number().int().positive() }).strict()),
+    workflowEnvelope(OrchestrationEventType.RetryCounted, z.object({ retryKey: z.string().min(1), count: z.number().int().positive() }).strict()),
+    workflowEnvelope(OrchestrationEventType.InstanceCompleted, emptySchema),
+    workflowEnvelope(OrchestrationEventType.InstanceBlocked, z.object({ reason: z.string() }).strict()),
+    workflowEnvelope(OrchestrationEventType.OperatorRetryRequested, z
+        .object({
+        activationId: brandedStringSchema(activationId),
+        commandId: z.string().min(1),
+    })
+        .strict()),
+    workflowEnvelope(OrchestrationEventType.InstanceSuperseded, emptySchema),
+    workflowEnvelope(OrchestrationEventType.ChildRequested, z.object({ ...childMetadataShape, workflowName: brandedStringSchema(workflowName) }).strict()),
+    workflowEnvelope(OrchestrationEventType.ChildStarted, childMetadataSchema),
+    workflowEnvelope(OrchestrationEventType.ChildCompleted, childMetadataSchema),
+    workflowEnvelope(OrchestrationEventType.ChildCompletionConsumed, childMetadataSchema),
+    workflowEnvelope(OrchestrationEventType.CausalActivationRejected, childMetadataSchema),
+    workflowEnvelope(OrchestrationEventType.GroupBudgetExhausted, z.object({ ...childMetadataShape, maxPerGroup: z.number().int().positive() }).strict()),
+    primaryClaimedEnvelope,
+    groupClaimedEnvelope,
+]);
+export function decodeOrchestrationEvent(event) {
+    const result = eventSchema.safeParse(event);
+    if (!result.success)
+        throw invalidOrchestrationEvent(event, result.error);
+    return result.data;
+}
+export function selectOrchestrationEvent(event) {
+    return event.eventType.startsWith('orchestration.') ? decodeOrchestrationEvent(event) : null;
+}
+export function selectWorkflowOrchestrationEvent(event) {
+    const owned = selectOrchestrationEvent(event);
+    if (owned === null)
+        return null;
+    switch (owned.eventType) {
+        case OrchestrationEventType.PrimaryClaimed:
+        case OrchestrationEventType.GroupClaimed:
+            return null;
+        default:
+            return owned;
+    }
+}
+function invalidOrchestrationEvent(event, cause) {
+    return new Error(`Invalid Orchestration event ${event.eventId} at global position ${event.globalPosition} (${event.eventType}): ${cause.message}`, { cause });
+}

package/dist/src/orchestration/contracts/events.js

@@ -0,0 +1,41 @@
+import { signalName } from './identifiers.js';
+export const OrchestrationEventType = {
+    InstanceStarted: 'orchestration.instance-started',
+    StageEntered: 'orchestration.stage-entered',
+    ActivityRequested: 'orchestration.activity-requested',
+    ActivityStarted: 'orchestration.activity-started',
+    ActivityOutcomeAccepted: 'orchestration.activity-outcome-accepted',
+    ActivityExecutionFailed: 'orchestration.activity-execution-failed',
+    ActivityWaiting: 'orchestration.activity-waiting',
+    SignalWaitStarted: 'orchestration.signal-wait-started',
+    SignalAccepted: 'orchestration.signal-accepted',
+    SupplementalActivityQueued: 'orchestration.supplemental-activity-queued',
+    SupplementalActivityDequeued: 'orchestration.supplemental-activity-dequeued',
+    RepeatCounted: 'orchestration.repeat-counted',
+    RetryCounted: 'orchestration.retry-counted',
+    InstanceCompleted: 'orchestration.instance-completed',
+    InstanceBlocked: 'orchestration.instance-blocked',
+    OperatorRetryRequested: 'orchestration.operator-retry-requested',
+    InstanceSuperseded: 'orchestration.instance-superseded',
+    ChildRequested: 'orchestration.child-requested',
+    ChildStarted: 'orchestration.child-started',
+    ChildCompleted: 'orchestration.child-completed',
+    ChildCompletionConsumed: 'orchestration.child-completion-consumed',
+    CausalActivationRejected: 'orchestration.causal-activation-rejected',
+    GroupBudgetExhausted: 'orchestration.group-budget-exhausted',
+    PrimaryClaimed: 'orchestration.primary-claimed',
+    GroupClaimed: 'orchestration.group-claimed',
+};
+export const WatchGateVerdictSignal = signalName('orchestration.watch-gate-verdict');
+export const ApprovedSignal = signalName('approved');
+/**
+ * Every consumer that needs to know whether a wait renders as "awaiting
+ * approval" externally (GitHub labels, the operator board, the agent-run
+ * comment footer) must derive it from this single predicate, or it silently
+ * falls out of sync whenever a new approval-style signal kind is added —
+ * exactly what happened when the watchGate verdict channel shipped and only
+ * some of those consumers were updated to recognize it.
+ */
+export function isApprovalAwaitingSignalKind(signalKind) {
+    return signalKind === ApprovedSignal || signalKind === WatchGateVerdictSignal;
+}

package/dist/src/orchestration/contracts/identifiers.js

@@ -0,0 +1,35 @@
+export const workflowName = (value) => {
+    if (!/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(value))
+        throw new Error(`Invalid workflow name: ${value}`);
+    return value;
+};
+export const stageName = (value) => {
+    if (!/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(value))
+        throw new Error(`Invalid stage name: ${value}`);
+    return value;
+};
+export const signalName = (value) => {
+    if (!/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(value))
+        throw new Error(`Invalid signal name: ${value}`);
+    return value;
+};
+export const commandName = (value) => {
+    if (!/^\/[a-z][a-z0-9-]*$/.test(value))
+        throw new Error(`Invalid command name: ${value}`);
+    return value;
+};
+export const workflowInstanceId = (value) => {
+    if (value.trim().length === 0)
+        throw new Error('WorkflowInstance id must not be empty');
+    return value;
+};
+export const orchestrationGroupId = (value) => {
+    if (value.trim().length === 0)
+        throw new Error('Orchestration group id must not be empty');
+    return value;
+};
+export const watchId = (value) => {
+    if (!/^[a-z][a-z0-9-]*$/.test(value))
+        throw new Error(`Invalid WatchId: ${value}`);
+    return value;
+};

package/dist/src/orchestration/contracts/streams.js

@@ -0,0 +1,38 @@
+export const OrchestrationStreamKind = {
+    WorkflowInstance: 'workflow-instance',
+    Group: 'orchestration-group',
+};
+export const orchestrationGroupStreamId = (value) => {
+    return value.startsWith('primary:')
+        ? primaryOrchestrationGroupStreamId(value)
+        : childOrchestrationGroupStreamId(value);
+};
+export const primaryOrchestrationGroupStreamId = (value) => {
+    if (!/^primary:work-[a-z0-9-]+$/.test(value))
+        throw new Error(`Invalid primary orchestration group stream key: ${value}`);
+    return value;
+};
+export const childOrchestrationGroupStreamId = (value) => {
+    if (!/^group:[^:]+:watch:[^:]+$/.test(value))
+        throw new Error(`Invalid child orchestration group stream key: ${value}`);
+    return value;
+};
+export const workflowInstanceStream = (id) => ({
+    kind: OrchestrationStreamKind.WorkflowInstance,
+    id,
+});
+export const primaryOrchestrationGroupStream = (workItemId) => ({
+    kind: OrchestrationStreamKind.Group,
+    id: primaryOrchestrationGroupStreamId(`primary:${workItemId}`),
+});
+export const childOrchestrationGroupStream = (orchestrationGroupId, watchId) => ({
+    kind: OrchestrationStreamKind.Group,
+    id: childOrchestrationGroupStreamId(`group:${component(orchestrationGroupId)}:watch:${component(watchId)}`),
+});
+export const isWorkflowInstanceStream = (stream) => stream.kind === OrchestrationStreamKind.WorkflowInstance;
+export const isOrchestrationGroupStream = (stream) => stream.kind === OrchestrationStreamKind.Group;
+function component(value) {
+    if (value.trim().length === 0)
+        throw new Error('Orchestration group key part must not be empty');
+    return encodeURIComponent(value);
+}

package/dist/src/orchestration/contracts/views.js

@@ -0,0 +1 @@
+export {};