@sgtbeatdown/pi-tasks 0.1.5 → 0.1.7

package/src/task-core.ts

@@ -4,6 +4,8 @@ import {
 	PARENT_ACKNOWLEDGMENT_OPERATION,
 	TASK_PROTOCOL_VERSION,
 	TERMINAL_INTENT_OPERATION,
+	TaskDeliveryEvidenceState,
+	TaskDeliveryStage,
 	TaskEnvelopeKind,
 	TaskOutboxDeliveryError,
 	TaskProtocolError,
@@ -21,6 +23,7 @@ import type {
 import type { TaskStore } from "./task-store";
 
 const RECEIVE_PAGE_SIZE = 100;
+const DELIVERY_EVIDENCE_OPERATION = "delivery_evidence";
 const TARGET_NOT_REGISTERED_CODE = "TARGET_NOT_REGISTERED";
 const TERMINAL_STATUSES = new Set<TaskRecord["status"]>(["completed", "failed", "cancelled", "timed_out"]);
 const TERMINAL_EVENTS = new Set(["task.completed", "task.failed", "task.cancelled", "task.timed_out"]);
@@ -53,6 +56,10 @@ export interface SubmitIntentInput {
 	readonly payload: Record<string, unknown>;
 }
 
+export type SubmitIntentOutcome =
+	| { readonly authority: "origin"; readonly canonicalEvent: { readonly type: string; readonly reused: boolean } }
+	| { readonly authority: "receiver" };
+
 export interface TaskCore {
 	readonly endpoint: TaskEndpoint;
 	connect(signal?: AbortSignal): Promise<void>;
@@ -63,6 +70,7 @@ export interface TaskCore {
 	receive(signal?: AbortSignal): Promise<readonly RelayDelivery[]>;
 	acknowledgeRelayDelivery(cursor: string, signal?: AbortSignal): Promise<void>;
 	submitIntent(input: SubmitIntentInput, signal?: AbortSignal): Promise<void>;
+	submitIntentWithOutcome?(input: SubmitIntentInput, signal?: AbortSignal): Promise<SubmitIntentOutcome>;
 	recordInsertion(input: { readonly taskId: string; readonly eventId: string }, signal?: AbortSignal): Promise<void>;
 	evaluateTimeouts(signal?: AbortSignal): Promise<void>;
 	acknowledgeParent(taskId: string, signal?: AbortSignal): Promise<void>;
@@ -76,6 +84,36 @@ type ReceivedEnvelope =
 export function createTaskCore(options: TaskCoreOptions): TaskCore {
 	const clock = options.clock ?? { now: (): number => Date.now() };
 	const ids = options.ids ?? (() => crypto.randomUUID());
+	const submitIntentWithOutcome = async (input: SubmitIntentInput, signal?: AbortSignal): Promise<SubmitIntentOutcome> => {
+		if (!RECEIVER_INTENT_TYPES.has(input.type) || !isRecord(input.payload)) throw new TaskProtocolError("INVALID_INTENT", "intent type or payload is invalid");
+		let persistedEnvelopeIds: readonly string[] = [];
+		let outcome: SubmitIntentOutcome | undefined;
+		let receiverTerminal = false;
+		let originCancellation = false;
+		const evidence = deliveryEvidence(input);
+		options.store.transaction(() => {
+			const task = requiredTask(options.store, input.taskId);
+			receiverTerminal = !sameEndpoint(options.endpoint, task.origin) && TERMINAL_EVENTS.has(input.type);
+			originCancellation = sameEndpoint(options.endpoint, task.origin) && input.type === "task.cancelled";
+			const persisted = persistIntent(options, clock.now, ids, task, input, evidence === undefined ? undefined : deliveryEvidenceOperation(evidence));
+			persistedEnvelopeIds = persisted.envelopeIds;
+			outcome = persisted.outcome;
+		});
+		if (evidence !== undefined) {
+			await flushDeliveryEvidence(options, signal, input.taskId, persistedEnvelopeIds, evidence);
+		} else {
+			try {
+				await flush(options, signal, new Set(persistedEnvelopeIds));
+			} catch (error) {
+				if (originCancellation) throwIfCancellationDeliveryBlocked(options, input.taskId, persistedEnvelopeIds);
+				throw error;
+			}
+			if (originCancellation) throwIfCancellationDeliveryBlocked(options, input.taskId, persistedEnvelopeIds);
+		}
+		if (receiverTerminal) throwIfTerminalDeliveryBlocked(options.store, input.taskId);
+		if (outcome === undefined) throw new TaskProtocolError("INVALID_INTENT", "task intent outcome was not persisted");
+		return outcome;
+	};
 
 	return {
 		endpoint: options.endpoint,
@@ -138,35 +176,21 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 			await options.relay.acknowledgeDelivery({ endpoint: options.endpoint, cursor }, signal);
 			options.store.transaction(() => { options.store.setReceiveCursor(cursor); });
 		},
-		async submitIntent(input, signal) {
-			if (!RECEIVER_INTENT_TYPES.has(input.type) || !isRecord(input.payload)) throw new TaskProtocolError("INVALID_INTENT", "intent type or payload is invalid");
-			let persistedEnvelopeIds: readonly string[] = [];
-			let receiverTerminal = false;
-			let originCancellation = false;
-			options.store.transaction(() => {
-				const task = requiredTask(options.store, input.taskId);
-				receiverTerminal = !sameEndpoint(options.endpoint, task.origin) && TERMINAL_EVENTS.has(input.type);
-				originCancellation = sameEndpoint(options.endpoint, task.origin) && input.type === "task.cancelled";
-				persistedEnvelopeIds = persistIntent(options, clock.now, ids, task, input);
-			});
-			try {
-				await flush(options, signal, new Set(persistedEnvelopeIds));
-			} catch (error) {
-				if (originCancellation) throwIfCancellationDeliveryBlocked(options, input.taskId, persistedEnvelopeIds);
-				throw error;
-			}
-			if (originCancellation) throwIfCancellationDeliveryBlocked(options, input.taskId, persistedEnvelopeIds);
-			if (receiverTerminal) throwIfTerminalDeliveryBlocked(options.store, input.taskId);
-		},
+		async submitIntent(input, signal) { await submitIntentWithOutcome(input, signal); },
+		submitIntentWithOutcome,
 		async recordInsertion(input, signal) {
 			const task = requiredTask(options.store, input.taskId);
+			const evidence: DeliveryEvidence = { eventId: input.eventId, stage: TaskDeliveryStage.piInserted, state: TaskDeliveryEvidenceState.confirmed };
 			let persistedEnvelopeIds: readonly string[] = [];
 			options.store.transaction(() => {
-				if (options.store.putInsertionReceipt(input.taskId, input.eventId)) {
-					persistedEnvelopeIds = persistIntent(options, clock.now, ids, task, { taskId: input.taskId, type: "task.delivery_receipt", payload: { eventId: input.eventId } });
-				}
+				options.store.putInsertionReceipt(input.taskId, input.eventId);
+				persistedEnvelopeIds = persistIntent(options, clock.now, ids, task, {
+					taskId: input.taskId,
+					type: "task.delivery_receipt",
+					payload: { eventId: input.eventId, stage: evidence.stage, state: evidence.state },
+				}, deliveryEvidenceOperation(evidence)).envelopeIds;
 			});
-			if (persistedEnvelopeIds.length > 0) await flush(options, signal, new Set(persistedEnvelopeIds));
+			await flushDeliveryEvidence(options, signal, input.taskId, persistedEnvelopeIds, evidence);
 		},
 		async evaluateTimeouts(signal) {
 			const persistedEnvelopeIds: string[] = [];
@@ -175,7 +199,7 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 				options.store.transaction(() => {
 					const task = options.store.getTask(candidate.taskId);
 					if (!task || !sameEndpoint(task.origin, options.endpoint) || TERMINAL_STATUSES.has(task.status) || task.expiresAt > clock.now()) return;
-					persistedEnvelopeIds.push(...canonicalize(options, clock.now, ids, task, { intentId: ids(), taskId: task.taskId, type: "task.cancelled", payload: {} }, "task.timed_out"));
+					persistedEnvelopeIds.push(...canonicalize(options, clock.now, ids, task, { intentId: ids(), taskId: task.taskId, type: "task.cancelled", payload: {} }, "task.timed_out").envelopeIds);
 				});
 			}
 			if (persistedEnvelopeIds.length > 0) await flush(options, signal, new Set(persistedEnvelopeIds));
@@ -186,7 +210,7 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 				const task = requiredTask(options.store, taskId);
 				if (!sameEndpoint(task.origin, options.endpoint)) throw new TaskProtocolError("NOT_ORIGIN", "only origin may acknowledge a task");
 				if (!TERMINAL_STATUSES.has(task.status)) throw new TaskProtocolError("TASK_NOT_TERMINAL", "only a terminal task may be acknowledged", { retryable: false });
-				persistedEnvelopeIds = canonicalize(options, clock.now, ids, task, { intentId: ids(), taskId, type: "task.information", payload: {} }, "task.parent_acknowledged", PARENT_ACKNOWLEDGMENT_OPERATION);
+				persistedEnvelopeIds = canonicalize(options, clock.now, ids, task, { intentId: ids(), taskId, type: "task.information", payload: {} }, "task.parent_acknowledged", PARENT_ACKNOWLEDGMENT_OPERATION).envelopeIds;
 			});
 			await flush(options, signal, new Set(persistedEnvelopeIds));
 		},
@@ -244,42 +268,80 @@ function persistReceivedEnvelope(options: TaskCoreOptions, now: () => number, id
 		options.store.appendEvent(received.event);
 		return [];
 	}
-	if (received.kind === "intent") return canonicalize(options, now, ids, received.task, received.intent, received.intent.type);
+	if (received.kind === "intent") return canonicalize(options, now, ids, received.task, received.intent, received.intent.type).envelopeIds;
 	if (options.store.appendEvent(received.event) && TERMINAL_EVENTS.has(received.event.type)) options.store.setStatus(received.task.taskId, statusFor(received.event.type));
 	return [];
 }
 
-function persistIntent(options: TaskCoreOptions, now: () => number, ids: () => string, task: TaskRecord, input: SubmitIntentInput): readonly string[] {
+interface PersistedIntent {
+	readonly envelopeIds: readonly string[];
+	readonly outcome: SubmitIntentOutcome;
+}
+
+function persistIntent(options: TaskCoreOptions, now: () => number, ids: () => string, task: TaskRecord, input: SubmitIntentInput, reservedOperation?: string): PersistedIntent {
 	if (sameEndpoint(options.endpoint, task.origin)) {
-		const operation = input.type === "task.cancelled" ? ORIGIN_CANCELLATION_OPERATION : undefined;
-		return canonicalize(options, now, ids, task, { intentId: ids(), taskId: input.taskId, type: input.type, payload: input.payload }, input.type, operation);
+		const operation = input.type === "task.cancelled" ? ORIGIN_CANCELLATION_OPERATION : reservedOperation;
+		const canonical = canonicalize(options, now, ids, task, { intentId: ids(), taskId: input.taskId, type: input.type, payload: input.payload }, input.type, operation);
+		return { envelopeIds: canonical.envelopeIds, outcome: { authority: "origin", canonicalEvent: { type: canonical.eventType, reused: canonical.reused } } };
 	}
 	const envelopeId = ids();
 	const intent: TaskIntent = { intentId: ids(), taskId: input.taskId, type: input.type, payload: input.payload };
-	if (TERMINAL_EVENTS.has(input.type)) {
+	const operation = TERMINAL_EVENTS.has(input.type) ? TERMINAL_INTENT_OPERATION : reservedOperation;
+	if (operation !== undefined) {
 		const reservation = options.store.reserveTaskOperation({
 			taskId: input.taskId,
-			operation: TERMINAL_INTENT_OPERATION,
+			operation,
 			logicalId: intent.intentId,
 			logicalType: intent.type,
 			envelopeIds: [envelopeId],
 		});
 		if (!reservation.created) {
-			if (reservation.record.logicalType !== intent.type) {
+			if (operation === TERMINAL_INTENT_OPERATION && reservation.record.logicalType !== intent.type) {
 				throw new TaskProtocolError("TERMINAL_INTENT_CONFLICT", "terminal task intent conflicts with the existing terminal action", {
 					retryable: false,
 					details: { taskId: input.taskId, existingType: reservation.record.logicalType, requestedType: intent.type },
 				});
 			}
-			return reservation.record.envelopeIds;
+			return { envelopeIds: reservation.record.envelopeIds, outcome: { authority: "receiver" } };
 		}
 	}
 	options.store.putIntent(intent.intentId, input.taskId, envelopeId);
 	options.store.putOutbox(envelope(envelopeId, options.endpoint, task.origin, input.taskId, TaskEnvelopeKind.intent, intent));
-	return [envelopeId];
+	return { envelopeIds: [envelopeId], outcome: { authority: "receiver" } };
+}
+
+interface DeliveryEvidence {
+	readonly eventId: string;
+	readonly stage: TaskDeliveryStage;
+	readonly state: TaskDeliveryEvidenceState;
+	readonly retryable?: true;
+}
+
+function deliveryEvidence(input: SubmitIntentInput): DeliveryEvidence | undefined {
+	if (input.type !== "task.delivery_receipt" || typeof input.payload.eventId !== "string") return undefined;
+	const stage = input.payload.stage;
+	const state = input.payload.state;
+	if (stage === TaskDeliveryStage.piInsertion && state === TaskDeliveryEvidenceState.blocked && input.payload.retryable === true) {
+		return { eventId: input.payload.eventId, stage, state, retryable: true };
+	}
+	if ((stage === TaskDeliveryStage.receiverPersisted || stage === TaskDeliveryStage.piInserted || stage === TaskDeliveryStage.wakeRequested || stage === TaskDeliveryStage.wakeAccepted)
+		&& state === TaskDeliveryEvidenceState.confirmed) {
+		return { eventId: input.payload.eventId, stage, state };
+	}
+	return undefined;
+}
+
+function deliveryEvidenceOperation(input: DeliveryEvidence): string {
+	return `${DELIVERY_EVIDENCE_OPERATION}:${input.eventId}:${input.stage}:${input.state}`;
 }
 
-function canonicalize(options: TaskCoreOptions, now: () => number, ids: () => string, task: TaskRecord, intent: TaskIntent, requestedType: string, operation?: string): readonly string[] {
+interface Canonicalization {
+	readonly envelopeIds: readonly string[];
+	readonly eventType: string;
+	readonly reused: boolean;
+}
+
+function canonicalize(options: TaskCoreOptions, now: () => number, ids: () => string, task: TaskRecord, intent: TaskIntent, requestedType: string, operation?: string): Canonicalization {
 	const terminal = TERMINAL_EVENTS.has(requestedType);
 	const type = terminal && TERMINAL_STATUSES.has(task.status) ? "task.late_terminal" : requestedType;
 	const sequence = String(task.events.length + 1);
@@ -289,13 +351,23 @@ function canonicalize(options: TaskCoreOptions, now: () => number, ids: () => st
 	const persistedEnvelopeIds = originEnvelope === undefined ? [targetEnvelope.envelopeId] : [targetEnvelope.envelopeId, originEnvelope.envelopeId];
 	if (operation !== undefined) {
 		const reservation = options.store.reserveTaskOperation({ taskId: task.taskId, operation, logicalId: canonical.eventId, logicalType: canonical.type, envelopeIds: persistedEnvelopeIds });
-		if (!reservation.created) return reservation.record.envelopeIds;
+		if (!reservation.created) return { envelopeIds: reservation.record.envelopeIds, eventType: reservation.record.logicalType, reused: true };
 	}
 	options.store.appendEvent(canonical);
 	if (TERMINAL_EVENTS.has(type)) options.store.setStatus(task.taskId, statusFor(type));
 	options.store.putOutbox(targetEnvelope);
 	if (originEnvelope !== undefined) options.store.putOutbox(originEnvelope);
-	return persistedEnvelopeIds;
+	return { envelopeIds: persistedEnvelopeIds, eventType: type, reused: false };
+}
+
+async function flushDeliveryEvidence(options: TaskCoreOptions, signal: AbortSignal | undefined, taskId: string, envelopeIds: readonly string[], evidence: DeliveryEvidence): Promise<void> {
+	try {
+		if (envelopeIds.length > 0) await flush(options, signal, new Set(envelopeIds));
+	} catch (error) {
+		throwIfDeliveryEvidenceBlocked(options.store, taskId, envelopeIds, evidence);
+		throw error;
+	}
+	throwIfDeliveryEvidenceBlocked(options.store, taskId, envelopeIds, evidence);
 }
 
 async function flush(options: TaskCoreOptions, signal: AbortSignal | undefined, reportedEnvelopeIds?: ReadonlySet<string>): Promise<void> {
@@ -359,6 +431,24 @@ function throwIfCancellationDeliveryBlocked(options: TaskCoreOptions, taskId: st
 	});
 }
 
+function throwIfDeliveryEvidenceBlocked(store: TaskStore, taskId: string, envelopeIds: readonly string[], evidence: DeliveryEvidence): void {
+	const blocked = store.quarantinedOutbox().find((record) => envelopeIds.includes(record.envelope.envelopeId));
+	if (blocked === undefined) return;
+	throw new TaskOutboxDeliveryError(blocked.errorCode, "task delivery evidence is blocked", {
+		retryable: false,
+		details: {
+			...blocked.details,
+			taskId,
+			eventId: evidence.eventId,
+			stage: evidence.stage,
+			state: evidence.state,
+			envelopeId: blocked.envelope.envelopeId,
+			target: blocked.envelope.target,
+			blockedAt: blocked.quarantinedAt,
+		},
+	});
+}
+
 function throwIfTerminalDeliveryBlocked(store: TaskStore, taskId: string): void {
 	const delivery = requiredTask(store, taskId).terminalDelivery;
 	if (delivery.state !== "delivery_blocked") return;

package/src/task-inbox.ts

@@ -1,17 +1,22 @@
 import type { TaskCore } from "./task-core";
-import { TaskEnvelopeKind, TaskProtocolError } from "./task-protocol";
+import { TaskDeliveryEvidenceState, TaskDeliveryStage, TaskEnvelopeKind, TaskProtocolError } from "./task-protocol";
 import type { RelayDelivery, TaskEvent } from "./task-protocol";
 
 const TASK_EVENT_CUSTOM_TYPE = "pi-tasks-event";
+const TASK_WAKE_CUSTOM_TYPE = "pi-tasks-wake";
 const TASK_CURSOR_CUSTOM_TYPE = "pi-tasks-relay-cursor";
 
 interface InboxContext {
+	readonly isIdle: () => boolean;
 	readonly hasPendingMessages: () => boolean;
 	readonly sessionManager: { readonly getEntries: () => readonly unknown[] };
 }
 
 interface InboxPi {
-	sendMessage(message: { readonly customType: string; readonly content: string; readonly display: boolean; readonly details: TaskEventDetails }, options: { readonly triggerTurn: true; readonly deliverAs: "followUp" }): void;
+	sendMessage(
+		message: { readonly customType: string; readonly content: string; readonly display: boolean; readonly details: TaskEventDetails },
+		options: { readonly triggerTurn: false } | { readonly triggerTurn: true; readonly deliverAs: "followUp" },
+	): void;
 	appendEntry(customType: string, data: { readonly cursor: string }): void;
 }
 
@@ -20,8 +25,12 @@ export interface TaskEventDetails {
 	readonly eventId: string;
 }
 
-/** Inserts durable Pi evidence before allowing the relay mailbox cursor to advance. */
-export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: InboxContext, pendingInsertions: Set<string>, signal?: AbortSignal): Promise<void> {
+type DeliveryEvidencePayload =
+	| { readonly stage: typeof TaskDeliveryStage.receiverPersisted | typeof TaskDeliveryStage.wakeRequested | typeof TaskDeliveryStage.wakeAccepted; readonly state: typeof TaskDeliveryEvidenceState.confirmed }
+	| { readonly stage: typeof TaskDeliveryStage.piInsertion; readonly state: typeof TaskDeliveryEvidenceState.blocked; readonly retryable: true };
+
+/** Persists model-visible Pi evidence before advancing the relay cursor, then starts one separate turn. */
+export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: InboxContext, signal?: AbortSignal): Promise<void> {
 	if (context.hasPendingMessages()) return;
 	const deliveries = await core.receive(signal);
 	for (const delivery of deliveries) {
@@ -33,28 +42,52 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 		const event = inboxEvent(delivery);
 		if (!isKnownEvent(event.type)) throw new TaskProtocolError("UNKNOWN_EVENT", `unknown task inbox event type: ${event.type}`);
 		if (context.hasPendingMessages()) return;
+		const eventDetails = { taskId: event.taskId, eventId: event.eventId };
 		const eventKey = key(event.taskId, event.eventId);
-		const incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
-		if (incorporated) pendingInsertions.delete(eventKey);
+		if (event.type === "task.created") {
+			await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.receiverPersisted, state: TaskDeliveryEvidenceState.confirmed }, signal);
+		}
+		let incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
 		if (!incorporated && isModelVisible(event.type)) {
-			if (!pendingInsertions.has(eventKey)) {
+			if (!context.isIdle()) return;
+			pi.sendMessage({
+				customType: TASK_EVENT_CUSTOM_TYPE,
+				content: renderTaskEvent(event),
+				display: true,
+				details: eventDetails,
+			}, { triggerTurn: false });
+			incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
+			if (!incorporated) {
+				await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.piInsertion, state: TaskDeliveryEvidenceState.blocked, retryable: true }, signal);
+				return;
+			}
+		}
+		if (isModelVisible(event.type)) {
+			await core.recordInsertion(eventDetails, signal);
+			let wakeAccepted = taskMessageKeys(context.sessionManager.getEntries(), TASK_WAKE_CUSTOM_TYPE).has(eventKey);
+			if (!wakeAccepted) {
+				if (!context.isIdle()) return;
+				await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeRequested, state: TaskDeliveryEvidenceState.confirmed }, signal);
 				pi.sendMessage({
-					customType: TASK_EVENT_CUSTOM_TYPE,
-					content: renderTaskEvent(event),
-					display: true,
-					details: { taskId: event.taskId, eventId: event.eventId },
+					customType: TASK_WAKE_CUSTOM_TYPE,
+					content: "Process the pending Pi task event.",
+					display: false,
+					details: eventDetails,
 				}, { triggerTurn: true, deliverAs: "followUp" });
-				pendingInsertions.add(eventKey);
+				wakeAccepted = taskMessageKeys(context.sessionManager.getEntries(), TASK_WAKE_CUSTOM_TYPE).has(eventKey);
+				if (!wakeAccepted) return;
 			}
-			if (!incorporatedEvents(context.sessionManager.getEntries()).has(eventKey)) return;
-			pendingInsertions.delete(eventKey);
+			await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeAccepted, state: TaskDeliveryEvidenceState.confirmed }, signal);
 		}
-		if (isModelVisible(event.type)) await core.recordInsertion({ taskId: event.taskId, eventId: event.eventId }, signal);
 		await core.acknowledgeRelayDelivery(delivery.cursor, signal);
 		pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor: delivery.cursor });
 	}
 }
 
+async function recordDeliveryEvidence(core: TaskCore, event: TaskEventDetails, evidence: DeliveryEvidencePayload, signal?: AbortSignal): Promise<void> {
+	await core.submitIntent({ taskId: event.taskId, type: "task.delivery_receipt", payload: { eventId: event.eventId, ...evidence } }, signal);
+}
+
 function inboxEvent(delivery: RelayDelivery): TaskEvent {
 	try {
 		const payload = JSON.parse(delivery.envelope.payload) as unknown;
@@ -81,16 +114,24 @@ function renderTaskEvent(event: TaskEvent): string {
 }
 
 export function incorporatedTaskEvents(entries: readonly unknown[]): readonly TaskEventDetails[] {
+	return taskMessageDetails(entries, TASK_EVENT_CUSTOM_TYPE);
+}
+
+function taskMessageDetails(entries: readonly unknown[], customType: string): readonly TaskEventDetails[] {
 	const events: TaskEventDetails[] = [];
 	for (const entry of entries) {
-		if (!isRecord(entry) || entry.type !== "custom_message" || entry.customType !== TASK_EVENT_CUSTOM_TYPE || !isRecord(entry.details) || typeof entry.details.taskId !== "string" || typeof entry.details.eventId !== "string") continue;
+		if (!isRecord(entry) || entry.type !== "custom_message" || entry.customType !== customType || !isRecord(entry.details) || typeof entry.details.taskId !== "string" || typeof entry.details.eventId !== "string") continue;
 		events.push({ taskId: entry.details.taskId, eventId: entry.details.eventId });
 	}
 	return events;
 }
 
+function taskMessageKeys(entries: readonly unknown[], customType: string): Set<string> {
+	return new Set(taskMessageDetails(entries, customType).map((event) => key(event.taskId, event.eventId)));
+}
+
 function incorporatedEvents(entries: readonly unknown[]): Set<string> {
-	return new Set(incorporatedTaskEvents(entries).map((event) => key(event.taskId, event.eventId)));
+	return taskMessageKeys(entries, TASK_EVENT_CUSTOM_TYPE);
 }
 
 function isTaskEvent(value: unknown): value is TaskEvent {

package/src/task-protocol.ts

@@ -4,6 +4,19 @@ export const ORIGIN_CANCELLATION_OPERATION = "origin_cancellation";
 export const PARENT_ACKNOWLEDGMENT_OPERATION = "parent_acknowledgment";
 export const TERMINAL_INTENT_OPERATION = "terminal_intent";
 
+export const TaskDeliveryStage = {
+	receiverPersisted: "receiver_persisted",
+	piInsertion: "pi_insertion",
+	piInserted: "pi_inserted",
+	wakeRequested: "wake_requested",
+	wakeAccepted: "wake_accepted",
+} as const;
+
+export const TaskDeliveryEvidenceState = {
+	confirmed: "confirmed",
+	blocked: "blocked",
+} as const;
+
 export interface TaskEndpoint {
 	readonly relay: string;
 	readonly id: string;
@@ -105,6 +118,9 @@ export interface TaskRecord {
 
 export type TerminalTaskIntentType = "task.completed" | "task.failed" | "task.cancelled";
 
+export type TaskDeliveryStage = (typeof TaskDeliveryStage)[keyof typeof TaskDeliveryStage];
+export type TaskDeliveryEvidenceState = (typeof TaskDeliveryEvidenceState)[keyof typeof TaskDeliveryEvidenceState];
+
 export interface TaskIntent {
 	readonly intentId: string;
 	readonly taskId: string;

package/src/task-store.ts

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 
 import { openSqliteDatabase } from "./sqlite-database";
 import type { SqliteDatabase } from "./sqlite-database";
-import { PARENT_ACKNOWLEDGMENT_OPERATION, TERMINAL_INTENT_OPERATION } from "./task-protocol";
+import { TERMINAL_INTENT_OPERATION } from "./task-protocol";
 import type { RelayEnvelope, TaskEndpoint, TaskEvent, TaskRecord, TaskSnapshot, TerminalDeliveryState, TerminalTaskIntentType } from "./task-protocol";
 
 const SCHEMA_VERSION = 5;
@@ -71,8 +71,13 @@ export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
 	const path = options.path ?? join(homedir(), ".pi", "tasks", "v2", "tasks.sqlite");
 	preparePath(path);
 	const database = openSqliteDatabase(path);
-	database.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
-	migrate(database);
+	try {
+		initializeSchema(database);
+		database.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
+	} catch (error) {
+		database.close();
+		throw error;
+	}
 
 	const store: TaskStore = {
 		transaction(operation) {
@@ -213,17 +218,6 @@ interface TaskOperationRow {
 	readonly envelope_ids: string;
 }
 
-interface LegacyIntentRow {
-	readonly intent_id: string;
-	readonly task_id: string;
-	readonly envelope_id: string;
-}
-
-interface LegacyEnvelopeRow {
-	readonly envelope_id: string;
-	readonly envelope: string;
-}
-
 interface EventRow {
 	readonly event_id: string;
 	readonly task_id: string;
@@ -237,10 +231,11 @@ interface EventRow {
 	readonly payload: string;
 }
 
-function migrate(database: SqliteDatabase): void {
+function initializeSchema(database: SqliteDatabase): void {
 	const version = database.query("PRAGMA user_version").get() as { readonly user_version: number };
-	if (version.user_version > SCHEMA_VERSION) throw new Error("task store schema is newer than this pi-tasks version");
-	if (version.user_version === 0) {
+	if (version.user_version === SCHEMA_VERSION) return;
+	if (version.user_version !== 0) throw new Error("task store schema version is unsupported");
+	database.transaction(() => {
 		database.exec(`
 			CREATE TABLE tasks (task_id TEXT PRIMARY KEY, protocol_version TEXT NOT NULL, origin_relay TEXT NOT NULL, origin_id TEXT NOT NULL, target_relay TEXT NOT NULL, target_id TEXT NOT NULL, task TEXT NOT NULL, created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, status TEXT NOT NULL);
 			CREATE TABLE events (event_id TEXT PRIMARY KEY, task_id TEXT NOT NULL REFERENCES tasks(task_id), type TEXT NOT NULL, sequence TEXT NOT NULL, source_relay TEXT NOT NULL, source_id TEXT NOT NULL, target_relay TEXT NOT NULL, target_id TEXT NOT NULL, occurred_at INTEGER NOT NULL, payload TEXT NOT NULL);
@@ -248,137 +243,29 @@ function migrate(database: SqliteDatabase): void {
 			CREATE TABLE inbox (envelope_id TEXT PRIMARY KEY, cursor TEXT NOT NULL, envelope TEXT NOT NULL);
 			CREATE TABLE intents (intent_id TEXT PRIMARY KEY, task_id TEXT NOT NULL, envelope_id TEXT NOT NULL);
 			CREATE TABLE relay_state (name TEXT PRIMARY KEY, value TEXT NOT NULL);
-			PRAGMA user_version = 1;
-		`);
-	}
-	if (version.user_version <= 1) {
-		database.exec(`
-			CREATE INDEX IF NOT EXISTS tasks_origin_expiry ON tasks (origin_relay, origin_id, status, expires_at);
-			CREATE INDEX IF NOT EXISTS inbox_cursor ON inbox (cursor);
-			PRAGMA user_version = 2;
-		`);
-	}
-	if (version.user_version <= 2) {
-		database.exec(`
 			CREATE TABLE insertion_receipts (task_id TEXT NOT NULL REFERENCES tasks(task_id), event_id TEXT NOT NULL, PRIMARY KEY (task_id, event_id));
-			PRAGMA user_version = 3;
-		`);
-	}
-	if (version.user_version <= 3) {
-		database.exec(`CREATE TABLE IF NOT EXISTS outbox_quarantine (
-			envelope_id TEXT PRIMARY KEY,
-			envelope TEXT NOT NULL,
-			reason TEXT NOT NULL,
-			quarantined_at INTEGER NOT NULL,
-			error_code TEXT NOT NULL DEFAULT 'UNKNOWN',
-			details TEXT NOT NULL DEFAULT '{}',
-			prior_state TEXT NOT NULL DEFAULT 'pending'
-		);`);
-		ensureColumn(database, "outbox_quarantine", "envelope", "TEXT NOT NULL DEFAULT '{}'");
-		ensureColumn(database, "outbox_quarantine", "reason", "TEXT NOT NULL DEFAULT 'operator quarantine'");
-		ensureColumn(database, "outbox_quarantine", "quarantined_at", "INTEGER NOT NULL DEFAULT 0");
-		ensureColumn(database, "outbox_quarantine", "error_code", "TEXT NOT NULL DEFAULT 'UNKNOWN'");
-		ensureColumn(database, "outbox_quarantine", "details", "TEXT NOT NULL DEFAULT '{}'");
-		ensureColumn(database, "outbox_quarantine", "prior_state", "TEXT NOT NULL DEFAULT 'pending'");
-		database.exec("PRAGMA user_version = 4;");
-	}
-	if (version.user_version <= 4) {
-		database.transaction(() => {
-			database.exec(`CREATE TABLE IF NOT EXISTS task_operations (
+			CREATE TABLE outbox_quarantine (
+				envelope_id TEXT PRIMARY KEY,
+				envelope TEXT NOT NULL,
+				reason TEXT NOT NULL,
+				quarantined_at INTEGER NOT NULL,
+				error_code TEXT NOT NULL,
+				details TEXT NOT NULL,
+				prior_state TEXT NOT NULL
+			);
+			CREATE TABLE task_operations (
 				task_id TEXT NOT NULL REFERENCES tasks(task_id),
 				operation TEXT NOT NULL,
 				logical_id TEXT NOT NULL,
 				logical_type TEXT NOT NULL,
 				envelope_ids TEXT NOT NULL,
 				PRIMARY KEY (task_id, operation)
-			);`);
-			backfillTaskOperations(database);
-			database.exec("PRAGMA user_version = 5;");
-		})();
-	}
-}
-
-function backfillTaskOperations(database: SqliteDatabase): void {
-	const envelopes = legacyEnvelopes(database);
-	const terminalTasks = new Set<string>();
-	const intents = database.query("SELECT intent_id, task_id, envelope_id FROM intents ORDER BY rowid").all() as LegacyIntentRow[];
-	for (const intent of intents) {
-		if (terminalTasks.has(intent.task_id)) continue;
-		const serializedEnvelope = envelopes.get(intent.envelope_id);
-		if (!serializedEnvelope) throw new Error(`legacy intent ${intent.intent_id} has no durable envelope`);
-		const envelope = legacyEnvelope(intent.envelope_id, serializedEnvelope);
-		const payload = legacyEnvelopePayload(envelope);
-		if (envelope.kind !== "intent" || envelope.taskId !== intent.task_id || !isRecord(payload) || payload.intentId !== intent.intent_id || payload.taskId !== intent.task_id || typeof payload.type !== "string") {
-			throw new Error(`legacy intent ${intent.intent_id} has malformed structured state`);
-		}
-		if (!isTerminalIntentType(payload.type)) continue;
-		insertTaskOperation(database, { taskId: intent.task_id, operation: TERMINAL_INTENT_OPERATION, logicalId: intent.intent_id, logicalType: payload.type, envelopeIds: [intent.envelope_id] });
-		terminalTasks.add(intent.task_id);
-	}
-
-	const acknowledgments = database.query("SELECT * FROM events WHERE type = 'task.parent_acknowledged' ORDER BY task_id, CAST(sequence AS INTEGER), rowid").all() as EventRow[];
-	const acknowledgedTasks = new Set<string>();
-	for (const acknowledgment of acknowledgments) {
-		if (acknowledgedTasks.has(acknowledgment.task_id)) continue;
-		const envelopeIds = [...envelopes]
-			.flatMap(([envelopeId, serializedEnvelope]) => {
-				const envelope = optionalLegacyEnvelope(envelopeId, serializedEnvelope);
-				return envelope?.kind === "canonical_event" && envelope.taskId === acknowledgment.task_id && eventIdFromLegacyEnvelope(envelope) === acknowledgment.event_id ? [envelopeId] : [];
-			})
-			.sort();
-		if (envelopeIds.length === 0) throw new Error(`legacy parent acknowledgment ${acknowledgment.event_id} has no durable envelope`);
-		insertTaskOperation(database, { taskId: acknowledgment.task_id, operation: PARENT_ACKNOWLEDGMENT_OPERATION, logicalId: acknowledgment.event_id, logicalType: acknowledgment.type, envelopeIds });
-		acknowledgedTasks.add(acknowledgment.task_id);
-	}
-}
-
-function legacyEnvelopes(database: SqliteDatabase): Map<string, string> {
-	const envelopes = new Map<string, string>();
-	const live = database.query("SELECT envelope_id, envelope FROM outbox ORDER BY rowid").all() as LegacyEnvelopeRow[];
-	const quarantined = database.query("SELECT envelope_id, envelope FROM outbox_quarantine ORDER BY rowid").all() as LegacyEnvelopeRow[];
-	for (const row of [...live, ...quarantined]) {
-		if (row.envelope_id.length === 0) throw new Error("legacy durable envelope identity is malformed");
-		if (!envelopes.has(row.envelope_id)) envelopes.set(row.envelope_id, row.envelope);
-	}
-	return envelopes;
-}
-
-function legacyEnvelope(envelopeId: string, serializedEnvelope: string): RelayEnvelope {
-	const envelope = parseEnvelope(serializedEnvelope);
-	if (envelope.envelopeId !== envelopeId) throw new Error(`legacy envelope ${envelopeId} identity is malformed`);
-	return envelope;
-}
-
-function optionalLegacyEnvelope(envelopeId: string, serializedEnvelope: string): RelayEnvelope | undefined {
-	try {
-		return legacyEnvelope(envelopeId, serializedEnvelope);
-	} catch {
-		// Unrelated operator quarantine rows are audit data, not lifecycle state.
-		return undefined;
-	}
-}
-
-function legacyEnvelopePayload(envelope: RelayEnvelope): unknown {
-	try {
-		return JSON.parse(envelope.payload) as unknown;
-	} catch {
-		throw new Error(`legacy envelope ${envelope.envelopeId} payload is malformed`);
-	}
-}
-
-function eventIdFromLegacyEnvelope(envelope: RelayEnvelope): string | undefined {
-	const payload = legacyEnvelopePayload(envelope);
-	return isRecord(payload) && typeof payload.eventId === "string" ? payload.eventId : undefined;
-}
-
-function insertTaskOperation(database: SqliteDatabase, input: TaskOperationRecord): void {
-	database.query(`INSERT INTO task_operations (task_id, operation, logical_id, logical_type, envelope_ids)
-		VALUES (?, ?, ?, ?, ?) ON CONFLICT(task_id, operation) DO NOTHING`).run(input.taskId, input.operation, input.logicalId, input.logicalType, JSON.stringify(input.envelopeIds));
-}
-
-function ensureColumn(database: SqliteDatabase, table: string, name: string, definition: string): void {
-	const columns = database.query(`PRAGMA table_info(${table})`).all() as Array<{ readonly name: string }>;
-	if (!columns.some((column) => column.name === name)) database.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${definition}`);
+			);
+			CREATE INDEX tasks_origin_expiry ON tasks (origin_relay, origin_id, status, expires_at);
+			CREATE INDEX inbox_cursor ON inbox (cursor);
+			PRAGMA user_version = 5;
+		`);
+	})();
 }
 
 function preparePath(path: string): void {