@atolis-hq/wake 0.2.97 → 0.3.0

package/dist/src/integrations/delivery/application/delivery-projector.js

@@ -0,0 +1,165 @@
+import { ActivityEventType, selectActivityEvent } from '../../../activities/index.js';
+import { IntegrationStreamKind } from '../../contracts/streams.js';
+import { DeliveryEventType, selectDeliveryEvent } from '../contracts/events.js';
+import { DeliveryIntentEventType, selectDeliveryIntentEvent } from '../contracts/intents.js';
+import { DeliveryIntentKind, DeliveryResultKind, DeliveryState } from '../contracts/vocabulary.js';
+export function projectDeliveries(events) {
+    const views = new Map();
+    for (const event of [...events].sort((left, right) => left.globalPosition - right.globalPosition)) {
+        const key = deliveryProjection.select(event)?.key;
+        if (key === undefined)
+            continue;
+        const next = deliveryProjection.project(views.get(key) ?? null, event);
+        if (next !== null)
+            views.set(key, next);
+    }
+    return [...views.values()]
+        .filter((view) => (view.state === DeliveryState.Pending || view.state === DeliveryState.Ambiguous) &&
+        view.escalation === undefined)
+        .sort((left, right) => left.globalPosition - right.globalPosition);
+}
+export const deliveryProjection = {
+    name: IntegrationStreamKind.Delivery,
+    select(event) {
+        const intent = intentView(event);
+        if (intent !== null)
+            return { key: intent.eventId };
+        const delivery = selectDeliveryEvent(event);
+        return delivery === null ? null : { key: delivery.stream.id };
+    },
+    initial: () => null,
+    project(previous, event) {
+        const projectedIntent = intentView(event);
+        if (projectedIntent !== null)
+            return projectedIntent.view;
+        return foldDeliveryFact(previous, selectDeliveryEvent(event));
+    },
+};
+export const deliveryProjectionDefinitions = [deliveryProjection];
+function intentView(event) {
+    const activityIntent = activityIntentView(event);
+    if (activityIntent !== null)
+        return activityIntent;
+    const integrationIntent = selectDeliveryIntentEvent(event);
+    return integrationIntent === null ? null : integrationIntentView(integrationIntent);
+}
+function activityIntentView(event) {
+    const intent = selectActivityEvent(event);
+    if (intent?.eventType === ActivityEventType.PrApproveRequested)
+        return {
+            eventId: intent.eventId,
+            view: {
+                intentEventId: intent.eventId,
+                globalPosition: intent.globalPosition,
+                workflowInstanceId: intent.payload.workflowInstanceId,
+                activationId: intent.payload.activationId,
+                kind: DeliveryIntentKind.PrApprove,
+                resourceId: intent.payload.resourceId,
+                payload: {
+                    kind: DeliveryIntentKind.PrApprove,
+                    revision: intent.payload.revision,
+                    ...(intent.payload.body === null ? {} : { body: intent.payload.body }),
+                },
+                state: DeliveryState.Pending,
+                attempts: 0,
+                occurrenceOrdinal: 0,
+                reconciliationAttempts: 0,
+            },
+        };
+    if (intent?.eventType === ActivityEventType.PrMergeRequested)
+        return {
+            eventId: intent.eventId,
+            view: {
+                intentEventId: intent.eventId,
+                globalPosition: intent.globalPosition,
+                workflowInstanceId: intent.payload.workflowInstanceId,
+                activationId: intent.payload.activationId,
+                kind: DeliveryIntentKind.PrMerge,
+                resourceId: intent.payload.resourceId,
+                payload: {
+                    kind: DeliveryIntentKind.PrMerge,
+                    revision: intent.payload.revision,
+                    method: intent.payload.method,
+                    autoMerge: intent.payload.autoMerge,
+                },
+                state: DeliveryState.Pending,
+                attempts: 0,
+                occurrenceOrdinal: 0,
+                reconciliationAttempts: 0,
+            },
+        };
+    return null;
+}
+function integrationIntentView(integrationIntent) {
+    if (integrationIntent.eventType === DeliveryIntentEventType.AgentRunPublishRequested)
+        return {
+            eventId: integrationIntent.eventId,
+            view: {
+                intentEventId: integrationIntent.eventId,
+                globalPosition: integrationIntent.globalPosition,
+                workflowInstanceId: integrationIntent.payload.workflowInstanceId,
+                activationId: integrationIntent.payload.activationId,
+                kind: DeliveryIntentKind.AgentRunPublish,
+                resourceId: integrationIntent.payload.resourceId,
+                payload: {
+                    kind: DeliveryIntentKind.AgentRunPublish,
+                    report: integrationIntent.payload.report,
+                },
+                state: DeliveryState.Pending,
+                attempts: 0,
+                occurrenceOrdinal: 0,
+            },
+        };
+    const status = integrationIntent.eventType === DeliveryIntentEventType.StatusPublishRequested;
+    return {
+        eventId: integrationIntent.eventId,
+        view: {
+            intentEventId: integrationIntent.eventId,
+            globalPosition: integrationIntent.globalPosition,
+            workflowInstanceId: integrationIntent.payload.workflowInstanceId,
+            activationId: integrationIntent.payload.activationId,
+            kind: status ? DeliveryIntentKind.StatusPublish : DeliveryIntentKind.ReplyPublish,
+            resourceId: integrationIntent.payload.resourceId,
+            payload: status
+                ? { kind: DeliveryIntentKind.StatusPublish, body: integrationIntent.payload.body }
+                : { kind: DeliveryIntentKind.ReplyPublish, body: integrationIntent.payload.body },
+            state: DeliveryState.Pending,
+            attempts: 0,
+            occurrenceOrdinal: 0,
+        },
+    };
+}
+// eslint-disable-next-line complexity
+function foldDeliveryFact(previous, delivery) {
+    if (delivery === null || previous === null)
+        return previous;
+    if (delivery.payload.intentEventId !== previous.intentEventId ||
+        delivery.payload.intentGlobalPosition !== previous.globalPosition)
+        return previous;
+    const current = {
+        ...previous,
+        occurrenceOrdinal: Math.max(previous.occurrenceOrdinal, delivery.payload.occurrenceOrdinal),
+    };
+    switch (delivery.eventType) {
+        case DeliveryEventType.AttemptStarted:
+            return { ...current, attempts: current.attempts + 1 };
+        case DeliveryEventType.Confirmed:
+            return { ...current, state: DeliveryState.Confirmed };
+        case DeliveryEventType.Failed:
+            return { ...current, state: DeliveryState.Failed };
+        case DeliveryEventType.Ambiguous:
+            return {
+                ...current,
+                state: DeliveryState.Ambiguous,
+                reconciliationKey: delivery.payload.reconciliationKey,
+            };
+        case DeliveryEventType.Escalated:
+            return { ...current, escalation: { reason: delivery.payload.reason } };
+        case DeliveryEventType.Reconciled:
+            if (delivery.payload.result === DeliveryResultKind.Confirmed)
+                return { ...current, state: DeliveryState.Confirmed, escalation: undefined };
+            return delivery.payload.result === DeliveryResultKind.Unknown
+                ? { ...current, reconciliationAttempts: (current.reconciliationAttempts ?? 0) + 1 }
+                : current;
+    }
+}

package/dist/src/integrations/delivery/application/delivery-service.js

@@ -0,0 +1,173 @@
+/* eslint-disable complexity */
+import { EventActorKind, EventSourceKind, } from '../../../kernel/index.js';
+import { deliveryStream, IntegrationStreamKind } from '../../contracts/streams.js';
+import { createDeliveryEventDraft, } from '../contracts/event-factory.js';
+import { DeliveryEventType } from '../contracts/events.js';
+import { DeliveryResultKind, DeliveryState } from '../contracts/vocabulary.js';
+export class DeliveryService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async resolveDelivery(intentId, resolution, context) {
+        if (context.actor.kind !== EventActorKind.Operator)
+            throw new Error('Delivery resolution requires an operator actor');
+        const intent = (await this.dependencies.intents()).find((item) => item.intentEventId === intentId);
+        if (intent === undefined)
+            throw new Error(`Delivery intent ${intentId} does not exist`);
+        if (intent.state !== DeliveryState.Ambiguous || intent.escalation === undefined)
+            throw new Error(`Delivery intent ${intentId} is not escalated`);
+        const occurrence = { ordinal: intent.occurrenceOrdinal + 1 };
+        const metadata = {
+            eventId: `${context.commandId}:delivery-resolution`,
+            occurredAt: context.occurredAt,
+            correlationId: context.correlationId,
+            causationId: context.commandId,
+            actor: context.actor,
+            source: { kind: EventSourceKind.Internal, id: IntegrationStreamKind.Delivery },
+            stream: deliveryStream(intent.intentEventId),
+        };
+        const draft = resolution.kind === DeliveryResultKind.Confirmed
+            ? {
+                ...metadata,
+                eventType: DeliveryEventType.Confirmed,
+                payload: { ...this.correlation(intent, occurrence), externalId: resolution.externalId },
+            }
+            : {
+                ...metadata,
+                eventType: DeliveryEventType.Failed,
+                payload: {
+                    ...this.correlation(intent, occurrence),
+                    code: resolution.code,
+                    message: resolution.message,
+                },
+            };
+        try {
+            await this.append(draft);
+        }
+        catch {
+            // A concurrent operator or automatic confirmation wins; return the projected state.
+        }
+        return ((await this.dependencies.intents()).find((item) => item.intentEventId === intentId) ?? intent);
+    }
+    async deliverNext(signal) {
+        const intent = (await this.dependencies.intents()).find((item) => (item.state === DeliveryState.Pending || item.state === DeliveryState.Ambiguous) &&
+            item.escalation === undefined);
+        if (intent === undefined)
+            return null;
+        const resource = await this.dependencies.resource(intent.resourceId);
+        if (resource === null)
+            throw new Error(`Delivery resource not found: ${intent.resourceId}`);
+        const adapter = this.dependencies.adapter(resource.adapter);
+        const occurrence = { ordinal: intent.occurrenceOrdinal + 1 };
+        if (intent.state === DeliveryState.Ambiguous || intent.attempts > 0) {
+            const reconciled = await adapter.reconcile(intent.reconciliationKey ?? intent.intentEventId, signal);
+            await this.append(this.reconciled(intent, occurrence, reconciled));
+            if (reconciled.kind === DeliveryResultKind.Unknown) {
+                const count = (intent.reconciliationAttempts ?? 0) + 1;
+                if (count >= (this.dependencies.maxAmbiguityReconciliationAttempts ?? 3))
+                    await this.append(this.escalated(intent, occurrence, count));
+                return intent;
+            }
+            if (reconciled.kind !== DeliveryResultKind.NotFound)
+                return intent;
+        }
+        await this.append(this.attemptStarted(intent, occurrence));
+        const result = await adapter.deliver(intent, signal);
+        switch (result.kind) {
+            case DeliveryResultKind.Confirmed:
+                await this.append(this.confirmed(intent, occurrence, result.externalId));
+                break;
+            case DeliveryResultKind.Failed:
+                await this.append(this.failed(intent, occurrence, result.code, result.message));
+                break;
+            case DeliveryResultKind.Ambiguous:
+                await this.append(this.ambiguous(intent, occurrence, result.reconciliationKey));
+                break;
+        }
+        return intent;
+    }
+    async append(draft) {
+        const sequence = (await this.dependencies.journal.readStream(draft.stream)).length;
+        await this.dependencies.journal.append(draft.stream, sequence, [
+            createDeliveryEventDraft(draft),
+        ]);
+    }
+    metadata(intent, occurrence, eventType) {
+        return {
+            eventId: `${intent.intentEventId}:${eventType}:${occurrence.ordinal}`,
+            occurredAt: this.dependencies.now(),
+            correlationId: intent.intentEventId,
+            causationId: intent.intentEventId,
+            actor: { kind: EventActorKind.System, id: IntegrationStreamKind.Delivery },
+            source: { kind: EventSourceKind.Internal, id: IntegrationStreamKind.Delivery },
+            stream: deliveryStream(intent.intentEventId),
+        };
+    }
+    correlation(intent, occurrence) {
+        return {
+            intentEventId: intent.intentEventId,
+            intentGlobalPosition: intent.globalPosition,
+            workflowInstanceId: intent.workflowInstanceId,
+            activationId: intent.activationId,
+            occurrenceOrdinal: occurrence.ordinal,
+        };
+    }
+    attemptStarted(intent, occurrence) {
+        return {
+            ...this.metadata(intent, occurrence, DeliveryEventType.AttemptStarted),
+            eventType: DeliveryEventType.AttemptStarted,
+            payload: this.correlation(intent, occurrence),
+        };
+    }
+    confirmed(intent, occurrence, externalId) {
+        return {
+            ...this.metadata(intent, occurrence, DeliveryEventType.Confirmed),
+            eventType: DeliveryEventType.Confirmed,
+            payload: { ...this.correlation(intent, occurrence), externalId },
+        };
+    }
+    failed(intent, occurrence, code, message) {
+        return {
+            ...this.metadata(intent, occurrence, DeliveryEventType.Failed),
+            eventType: DeliveryEventType.Failed,
+            payload: { ...this.correlation(intent, occurrence), code, message },
+        };
+    }
+    ambiguous(intent, occurrence, reconciliationKey) {
+        return {
+            ...this.metadata(intent, occurrence, DeliveryEventType.Ambiguous),
+            eventType: DeliveryEventType.Ambiguous,
+            payload: { ...this.correlation(intent, occurrence), reconciliationKey },
+        };
+    }
+    escalated(intent, occurrence, attempt) {
+        return {
+            ...this.metadata(intent, occurrence, DeliveryEventType.Escalated),
+            eventType: DeliveryEventType.Escalated,
+            payload: {
+                ...this.correlation(intent, occurrence),
+                reason: `delivery-ambiguous-after-${attempt}-attempts`,
+            },
+        };
+    }
+    reconciled(intent, occurrence, result) {
+        const metadata = this.metadata(intent, occurrence, DeliveryEventType.Reconciled);
+        const correlation = this.correlation(intent, occurrence);
+        switch (result.kind) {
+            case DeliveryResultKind.Confirmed:
+                return {
+                    ...metadata,
+                    eventType: DeliveryEventType.Reconciled,
+                    payload: { ...correlation, result: result.kind, externalId: result.externalId },
+                };
+            case DeliveryResultKind.NotFound:
+            case DeliveryResultKind.Unknown:
+                return {
+                    ...metadata,
+                    eventType: DeliveryEventType.Reconciled,
+                    payload: { ...correlation, result: result.kind },
+                };
+        }
+    }
+}

package/dist/src/integrations/delivery/contracts/commands.js

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

package/dist/src/integrations/delivery/contracts/config.js

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

package/dist/src/integrations/delivery/contracts/event-factory.js

@@ -0,0 +1,18 @@
+import { createEventDraft } from '../../../kernel/index.js';
+import { DeliveryEventType, } from './events.js';
+export function createDeliveryEventDraft(input) {
+    switch (input.eventType) {
+        case DeliveryEventType.AttemptStarted:
+            return createEventDraft(input);
+        case DeliveryEventType.Confirmed:
+            return createEventDraft(input);
+        case DeliveryEventType.Failed:
+            return createEventDraft(input);
+        case DeliveryEventType.Ambiguous:
+            return createEventDraft(input);
+        case DeliveryEventType.Escalated:
+            return createEventDraft(input);
+        case DeliveryEventType.Reconciled:
+            return createEventDraft(input);
+    }
+}

package/dist/src/integrations/delivery/contracts/events.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { brandedStringSchema, eventEnvelopeSchema, eventId, } from '../../../kernel/index.js';
+import { IntegrationStreamKind } from '../../contracts/streams.js';
+import { DeliveryResultKind } from './vocabulary.js';
+export const DeliveryEventType = {
+    AttemptStarted: 'delivery.attempt-started',
+    Confirmed: 'delivery.confirmed',
+    Failed: 'delivery.failed',
+    Ambiguous: 'delivery.ambiguous',
+    Reconciled: 'delivery.reconciled',
+    Escalated: 'delivery.escalated',
+};
+export const DeliveryEventNamespace = 'delivery.';
+const correlationSchema = z
+    .object({
+    intentEventId: brandedStringSchema(eventId),
+    intentGlobalPosition: z.number().int().positive(),
+    workflowInstanceId: z.string().min(1),
+    activationId: z.string().min(1),
+    occurrenceOrdinal: z.number().int().positive(),
+})
+    .strict();
+const deliveryStreamSchema = z
+    .object({
+    kind: z.literal(IntegrationStreamKind.Delivery),
+    id: brandedStringSchema(eventId),
+})
+    .strict();
+const reconciledPayloadSchema = z.discriminatedUnion('result', [
+    correlationSchema.extend({
+        result: z.literal(DeliveryResultKind.Confirmed),
+        externalId: z.string().min(1),
+    }),
+    correlationSchema.extend({ result: z.literal(DeliveryResultKind.NotFound) }),
+    correlationSchema.extend({ result: z.literal(DeliveryResultKind.Unknown) }),
+]);
+const eventSchema = z
+    .discriminatedUnion('eventType', [
+    eventEnvelopeSchema.extend({
+        eventType: z.literal(DeliveryEventType.AttemptStarted),
+        stream: deliveryStreamSchema,
+        payload: correlationSchema,
+    }),
+    eventEnvelopeSchema.extend({
+        eventType: z.literal(DeliveryEventType.Confirmed),
+        stream: deliveryStreamSchema,
+        payload: correlationSchema.extend({ externalId: z.string().min(1) }),
+    }),
+    eventEnvelopeSchema.extend({
+        eventType: z.literal(DeliveryEventType.Failed),
+        stream: deliveryStreamSchema,
+        payload: correlationSchema.extend({ code: z.string().min(1), message: z.string().min(1) }),
+    }),
+    eventEnvelopeSchema.extend({
+        eventType: z.literal(DeliveryEventType.Ambiguous),
+        stream: deliveryStreamSchema,
+        payload: correlationSchema.extend({ reconciliationKey: z.string().min(1) }),
+    }),
+    eventEnvelopeSchema.extend({
+        eventType: z.literal(DeliveryEventType.Escalated),
+        stream: deliveryStreamSchema,
+        payload: correlationSchema.extend({ reason: z.string().min(1) }),
+    }),
+    eventEnvelopeSchema.extend({
+        eventType: z.literal(DeliveryEventType.Reconciled),
+        stream: deliveryStreamSchema,
+        payload: reconciledPayloadSchema,
+    }),
+])
+    .superRefine((event, context) => {
+    if (event.stream.id !== event.payload.intentEventId)
+        context.addIssue({
+            code: 'custom',
+            path: ['payload', 'intentEventId'],
+            message: 'Delivery intent payload id must identify its stream',
+        });
+});
+export function decodeDeliveryEvent(event) {
+    const result = eventSchema.safeParse(event);
+    if (!result.success)
+        throw new Error(`Invalid Delivery event ${event.eventId} at global position ${event.globalPosition} (${event.eventType}): ${result.error.message}`, { cause: result.error });
+    return result.data;
+}
+export function selectDeliveryEvent(event) {
+    return event.eventType.startsWith(DeliveryEventNamespace) ? decodeDeliveryEvent(event) : null;
+}

package/dist/src/integrations/delivery/contracts/intents.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import { brandedStringSchema, eventEnvelopeSchema, } from '../../../kernel/index.js';
+import { ResourceStreamKind, resourceId, } from '../../../resources/index.js';
+export const DeliveryIntentEventType = {
+    StatusPublishRequested: 'status.publish-requested',
+    ReplyPublishRequested: 'reply.publish-requested',
+    AgentRunPublishRequested: 'agent-run.publish-requested',
+};
+export const DeliveryIntentEventNamespace = { Status: 'status.', Reply: 'reply.' };
+const resourceStreamSchema = z
+    .object({ kind: z.literal(ResourceStreamKind.Resource), id: brandedStringSchema(resourceId) })
+    .strict();
+const publishSchema = z
+    .object({
+    workflowInstanceId: z.string().min(1),
+    activationId: z.string().min(1),
+    resourceId: brandedStringSchema(resourceId),
+    body: z.string(),
+})
+    .strict();
+const reportSchema = z
+    .object({
+    runId: z.string().min(1),
+    stage: z.string().min(1).optional(),
+    runner: z.string().min(1).optional(),
+    runnerPool: z.string().min(1).optional(),
+    cli: z.string().min(1).optional(),
+    model: z.string().min(1).optional(),
+    startedAt: z.string().min(1),
+    finishedAt: z.string().min(1),
+    displayBody: z.string(),
+    outcome: z.enum(['DONE', 'REJECTED', 'BLOCKED', 'FAILED']),
+    sessionId: z.string().min(1).optional(),
+    workspacePath: z.string().min(1).optional(),
+    metadata: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])),
+    awaitingApproval: z.boolean().optional(),
+    watchGateVerdict: z
+        .object({ runId: z.string().min(1) })
+        .strict()
+        .optional(),
+})
+    .strict();
+const agentSchema = z
+    .object({
+    workflowInstanceId: z.string().min(1),
+    activationId: z.string().min(1),
+    resourceId: brandedStringSchema(resourceId),
+    report: reportSchema,
+})
+    .strict();
+const intentEventSchema = z
+    .discriminatedUnion('eventType', [
+    eventEnvelopeSchema.extend({
+        eventType: z.literal(DeliveryIntentEventType.StatusPublishRequested),
+        stream: resourceStreamSchema,
+        payload: publishSchema,
+    }),
+    eventEnvelopeSchema.extend({
+        eventType: z.literal(DeliveryIntentEventType.ReplyPublishRequested),
+        stream: resourceStreamSchema,
+        payload: publishSchema,
+    }),
+    eventEnvelopeSchema.extend({
+        eventType: z.literal(DeliveryIntentEventType.AgentRunPublishRequested),
+        stream: resourceStreamSchema,
+        payload: agentSchema,
+    }),
+])
+    .superRefine((event, ctx) => {
+    if (event.stream.id !== event.payload.resourceId)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['payload', 'resourceId'],
+            message: 'Delivery intent resource id must identify its stream',
+        });
+});
+export function decodeDeliveryIntentEvent(event) {
+    const result = intentEventSchema.safeParse(event);
+    if (!result.success)
+        throw new Error(`Invalid Delivery intent event ${event.eventId} at global position ${event.globalPosition} (${event.eventType}): ${result.error.message}`, { cause: result.error });
+    return result.data;
+}
+export function selectDeliveryIntentEvent(event) {
+    return event.eventType.startsWith(DeliveryIntentEventNamespace.Status) ||
+        event.eventType.startsWith(DeliveryIntentEventNamespace.Reply) ||
+        event.eventType === DeliveryIntentEventType.AgentRunPublishRequested
+        ? decodeDeliveryIntentEvent(event)
+        : null;
+}

package/dist/src/integrations/delivery/contracts/views.js

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

package/dist/src/integrations/delivery/contracts/vocabulary.js

@@ -0,0 +1,22 @@
+import { BuiltInActivityName } from '../../../activities/index.js';
+import { defineClosedVocabulary } from '../../../kernel/index.js';
+export const DeliveryState = defineClosedVocabulary({
+    Pending: 'pending',
+    Confirmed: 'confirmed',
+    Failed: 'failed',
+    Ambiguous: 'ambiguous',
+});
+export const DeliveryResultKind = defineClosedVocabulary({
+    Confirmed: 'confirmed',
+    Failed: 'failed',
+    Ambiguous: 'ambiguous',
+    NotFound: 'not-found',
+    Unknown: 'unknown',
+});
+export const DeliveryIntentKind = {
+    PrApprove: BuiltInActivityName.PullRequestApprove,
+    PrMerge: BuiltInActivityName.PullRequestMerge,
+    StatusPublish: 'status.publish',
+    ReplyPublish: 'reply.publish',
+    AgentRunPublish: 'agent-run.publish',
+};

package/dist/src/integrations/fake/durable-delivery-provider.js

@@ -0,0 +1,48 @@
+import { rename, writeFile } from 'node:fs/promises';
+import { DeliveryResultKind } from '../delivery/contracts/vocabulary.js';
+export class DurableFakeDeliveryProvider {
+    effects;
+    deliveryCalls = 0;
+    ambiguous = new Map();
+    crashAfterEffect = false;
+    constructor(options = {}) {
+        this.effects = new Map(Object.entries(options.effects ?? {}));
+        this.effectsFile = options.effectsFile;
+    }
+    effectsFile;
+    crashAfterNextEffect() {
+        this.crashAfterEffect = true;
+    }
+    async deliver(intent) {
+        this.deliveryCalls += 1;
+        const existing = this.effects.get(intent.intentEventId);
+        if (existing !== undefined)
+            return { kind: DeliveryResultKind.Confirmed, externalId: existing };
+        const externalId = `external-${this.effects.size + 1}`;
+        this.effects.set(intent.intentEventId, externalId);
+        await this.persistEffects();
+        if (this.crashAfterEffect) {
+            this.crashAfterEffect = false;
+            throw new Error('simulated provider crash after accepted effect');
+        }
+        return { kind: DeliveryResultKind.Confirmed, externalId };
+    }
+    rememberAmbiguous(intentEventId, reconciliationKey) {
+        this.ambiguous.set(reconciliationKey, intentEventId);
+    }
+    async reconcile(reconciliationKey) {
+        const intentEventId = this.ambiguous.get(reconciliationKey) ?? reconciliationKey;
+        const externalId = this.effects.get(intentEventId);
+        return externalId === undefined
+            ? { kind: DeliveryResultKind.NotFound }
+            : { kind: DeliveryResultKind.Confirmed, externalId };
+    }
+    async persistEffects() {
+        if (this.effectsFile === undefined)
+            return;
+        const temporary = `${this.effectsFile}.next`;
+        const body = `${JSON.stringify(Object.fromEntries(this.effects), null, 2)}\n`;
+        await writeFile(temporary, body);
+        await rename(temporary, this.effectsFile);
+    }
+}

package/dist/src/integrations/fake/external-sink.js

@@ -0,0 +1,9 @@
+export class FakeExternalSink {
+    delivered = [];
+    idempotencyKeys = [];
+    async deliver(effect, idempotencyKey) {
+        this.delivered.push(effect);
+        if (idempotencyKey !== undefined)
+            this.idempotencyKeys.push(idempotencyKey);
+    }
+}

package/dist/src/integrations/fake/external-source.js

@@ -0,0 +1,44 @@
+import { PullRequestCheckState } from '../../activities/index.js';
+import { causationId, correlationId, EventActorKind, eventId, EventSourceKind, } from '../../kernel/index.js';
+import { integrationStream } from '../contracts/streams.js';
+export const FakeEventType = {
+    WorkObserved: 'fake.work-observed',
+    ReviewRequested: 'fake.review-requested',
+};
+const missingIdentityPart = '_';
+export class FakeExternalEventSource {
+    adapter;
+    events;
+    constructor(adapter, events) {
+        this.adapter = adapter;
+        this.events = events;
+    }
+    async poll(signal) {
+        void signal;
+        return this.events.flatMap((payload, ordinal) => {
+            const identity = `fake:${this.adapter}:${payload.key}:${payload.revision ?? missingIdentityPart}:${payload.checks ?? PullRequestCheckState.Unknown}:${payload.watchEvent ?? missingIdentityPart}:${ordinal}`;
+            const metadata = {
+                schemaVersion: 1,
+                occurredAt: '2026-08-01T00:00:00.000Z',
+                correlationId: correlationId(`fake:${this.adapter}:${payload.key}`),
+                causationId: causationId(`fake:${this.adapter}:${payload.key}`),
+                actor: { kind: EventActorKind.Integration, id: this.adapter },
+                source: { kind: EventSourceKind.Adapter, id: this.adapter },
+                stream: integrationStream(this.adapter),
+            };
+            return [
+                { ...metadata, eventId: eventId(identity), eventType: FakeEventType.WorkObserved, payload },
+                ...(payload.watchEvent === undefined
+                    ? []
+                    : [
+                        {
+                            ...metadata,
+                            eventId: eventId(`${identity}:watch`),
+                            eventType: payload.watchEvent,
+                            payload: { key: payload.key },
+                        },
+                    ]),
+            ];
+        });
+    }
+}