@hypercarrier/pi-team-durable 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/authority/sync.d.ts

@@ -1,12 +1,13 @@
 import { type Tx, type EntryId } from '@earendil-works/pi-durable';
 import type { CoreApi } from './tools.ts';
-import { type State, type Event, type Result } from './state.ts';
+import { type Event, type Result } from './state.ts';
+import { type Authority as State } from './store.ts';
 export declare const UPDATE_PAGE_EVENTS = 50;
 export declare const UPDATE_SCAN_ENTRIES = 100;
-export declare function updates(s: State, events: Event[]): Result;
+export declare function updates(s: State, events: Event[]): Promise<Result>;
 /** Page native history without making the journal document an unbounded cache. */
 export declare function pageEvents(tx: Tx, s: State, from: number, after?: EntryId): Promise<{
     events: Event[];
     scanThrough?: EntryId;
 }>;
-export declare function sync(tx: Tx, s: State, view: 'snapshot' | 'updates' | undefined, api: CoreApi, snapshot: Result): Promise<Result>;
+export declare function sync(tx: Tx, s: State, view: 'snapshot' | 'updates' | undefined, api: CoreApi, snapshot: () => Promise<Result>): Promise<Result>;

package/dist/authority/sync.js

@@ -1,13 +1,12 @@
 import { LiveDoc } from '@earendil-works/pi-durable';
-import { GraphTaskController } from "./graph-control.js";
-import { projectGraphTaskCards } from "./graph-card.js";
-import { observations, reservationHead, reserve } from "./observation.js";
-import { plain } from "./state.js";
+import { openObservations, reservationHead, reserve, pages, savePage } from "./observation-store.js";
+import { taskCards, recentEvents } from "./store.js";
 export const UPDATE_PAGE_EVENTS = 50;
 export const UPDATE_SCAN_ENTRIES = 100;
-export function updates(s, events) {
-    const team = s.team.current, cards = projectGraphTaskCards(GraphTaskController.recover(plain(s.graph.snapshot)));
+export async function updates(s, events) {
+    const team = s.team.current;
     const ids = [...new Set(events.flatMap(e => e.taskIds ?? (e.taskId ? [e.taskId] : [])))];
+    const cards = await taskCards(s, ids);
     return { kind: 'updates',
         team_changes: events.filter(e => e.kind === 'team_created' || e.kind === 'team_stopped').map(e => ({ kind: e.kind === 'team_created' ? 'created' : 'lifecycle', text: e.kind === 'team_created' ? team.purpose : 'Team stopped.' })),
         worker_changes: events.filter(e => e.worker && ['worker_created', 'worker_stopped'].includes(e.kind)).map(e => ({ worker: e.worker, scope: team.workers[e.worker]?.scope ?? 'Historical Worker', kind: e.kind === 'worker_created' ? 'created' : 'stopped', text: e.kind === 'worker_created' ? 'Worker created.' : 'Worker stopped.' })),
@@ -18,7 +17,7 @@ export function updates(s, events) {
 export async function pageEvents(tx, s, from, after) {
     const recent = s.journal.events.filter(e => e.seq > from);
     if (recent.length && s.journal.events[0].seq <= from + 1) {
-        const events = recent.slice(0, UPDATE_PAGE_EVENTS);
+        const events = await recentEvents(s, recent.slice(0, UPDATE_PAGE_EVENTS));
         return { events, scanThrough: events.at(-1)?.entryId };
     }
     const native = await tx.scanEntries({ conversationId: s.team.current.lead, order: 'ascending', ...(after ? { minEntryId: after } : {}) }, UPDATE_SCAN_ENTRIES);
@@ -42,36 +41,38 @@ export async function sync(tx, s, view, api, snapshot) {
     const team = s.team.current, live = await tx.doc(LiveDoc, api.conversationId), run = live.run?.inputs[0];
     if (run === undefined)
         return { kind: 'unavailable', reason: 'team_state_unavailable', message: 'Observation requires a persisted lead run.' };
-    const o = await observations(tx);
-    o.paused = false;
-    if (Object.values(o.pages).some(p => p.epoch === team.epoch && p.run !== run && ['reserved', 'presented'].includes(p.state)))
+    const o = await openObservations(tx);
+    o.head.paused = false;
+    const active = await pages(o, 'openPages');
+    if (active.some(p => p.epoch === team.epoch && p.run !== run))
         return { kind: 'refused', reason: 'observation_in_progress', message: 'Another run or automatic delivery owns an unacknowledged page.', state_changed: false, observation_advanced: false };
-    const id = `${team.epoch}:sync:${api.taskId}`, from = reservationHead(o, team.epoch, run);
+    const id = `${team.epoch}:sync:${api.taskId}`, from = await reservationHead(o, team.epoch, run);
     const carrier = { kind: 'tool', callId: api.callId ?? String(api.taskId) };
     // Failed-run pages reappear once in order; the old replay receipt remains immutable.
-    const released = Object.values(o.pages).find(p => p.epoch === team.epoch && p.state === 'released');
+    const released = (await pages(o, 'releasedPages', true)).find(p => p.epoch === team.epoch);
     if (released) {
         const result = JSON.parse(released.body);
         released.state = 'replaced';
-        reserve(o, { id, epoch: team.epoch, lead: team.lead, run, from: released.from, through: released.through, carrier, ...(released.scanThrough ? { scanThrough: released.scanThrough } : {}) }, result);
+        await savePage(o, released);
+        await reserve(o, { id, epoch: team.epoch, lead: team.lead, run, from: released.from, through: released.through, carrier, ...(released.scanThrough ? { scanThrough: released.scanThrough } : {}) }, result);
         return result;
     }
-    const outstanding = Object.values(o.pages).filter(p => p.epoch === team.epoch && p.run === run && ['reserved', 'presented'].includes(p.state));
+    const outstanding = active.filter(p => p.epoch === team.epoch && p.run === run);
     if ((view !== 'snapshot' || outstanding.length > 0) && from >= s.journal.seq)
         return { kind: 'caught_up', head: s.journal.seq, epoch_id: team.epoch };
     let result, through, scanThrough;
     if (!outstanding.length && (view === 'snapshot' || from === 0)) {
-        result = snapshot;
+        result = await snapshot();
         through = s.journal.seq;
         scanThrough = s.journal.events.at(-1)?.entryId;
     }
     else {
-        const previous = Object.values(o.pages).filter(p => p.epoch === team.epoch && p.scanThrough !== undefined && (p.state === 'acknowledged' || p.run === run && ['reserved', 'presented'].includes(p.state))).sort((a, b) => Number(b.scanThrough) - Number(a.scanThrough))[0];
-        const page = await pageEvents(tx, s, from, previous?.scanThrough);
-        result = updates(s, page.events);
+        const previous = Math.max(o.head.scanByEpoch[team.epoch] ?? 0, ...outstanding.map(p => p.scanThrough ?? 0));
+        const page = await pageEvents(tx, s, from, previous || undefined);
+        result = await updates(s, page.events);
         through = page.events.at(-1)?.seq ?? from;
         scanThrough = page.scanThrough;
     }
-    reserve(o, { id, epoch: team.epoch, lead: team.lead, run, from, through, carrier, ...(scanThrough ? { scanThrough } : {}) }, result);
+    await reserve(o, { id, epoch: team.epoch, lead: team.lead, run, from, through, carrier, ...(scanThrough ? { scanThrough } : {}) }, result);
     return result;
 }

package/dist/authority/tools.d.ts

@@ -1,10 +1,12 @@
+import type { TSchema } from 'typebox';
 import type { Context } from '@earendil-works/chord/context';
 import { type ToolExecutionApi, type Tx } from '@earendil-works/pi-durable';
 import { type Role, type ToolName } from './contracts.ts';
 import { type GraphTaskTransition, type GraphVersionRef } from './graph-control.ts';
 import type { TaskVersionRef } from './task-version-ref.ts';
 import type { ConversationId } from '@earendil-works/pi-durable';
-import { type Binding, type ModelRole, type ModelRoleCatalog, type Result, type State, type StopIntent } from './state.ts';
+import { type Binding, type ModelRole, type ModelRoleCatalog, type Result, type StopIntent } from './state.ts';
+import { type Authority as State } from './store.ts';
 export type CoreApi = Pick<ToolExecutionApi, 'taskId' | 'conversationId' | 'commit' | 'now'> & Partial<Pick<ToolExecutionApi, 'callId'>>;
 export interface CoreOptions {
     modelRoles: ModelRole[];
@@ -22,7 +24,7 @@ export interface CoreOptions {
         stops: string[];
         epoch: string;
     }, api: CoreApi) => Promise<void>;
-    sync?: (tx: Tx, s: State, view: Args['view'], api: CoreApi, snapshot: Result) => Promise<Result>;
+    sync?: (tx: Tx, s: State, view: Args['view'], api: CoreApi, snapshot: () => Promise<Result>) => Promise<Result>;
 }
 interface Args {
     name?: string;
@@ -56,12 +58,54 @@ interface Args {
     task_version?: string;
     interrupt?: boolean;
 }
+interface ParameterSchema extends TSchema {
+    properties?: Record<string, ParameterSchema>;
+    items?: ParameterSchema;
+}
+/** The input a role tool acts on. Pi's role adapters forward declared fields, including nested Task definitions. */
+export declare function declaredParameters(schema: ParameterSchema, value: unknown): unknown;
 /** The catalog resolver that options select: the host's per-lead port, else the static list. */
 export declare function catalogOf(options: Pick<CoreOptions, 'modelRoles' | 'defaultModelRole' | 'catalog'>): (tx: Tx, lead: ConversationId) => Promise<ModelRoleCatalog>;
 /** Authority commands commit intent and replay receipts; injected ports own effects. */
 export declare function createAuthorityTools(options: CoreOptions): {
-    lead: import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>[];
-    worker: import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>[];
+    lead: {
+        label: string;
+        name: string;
+        description: string;
+        parameters: TSchema;
+        constrainedSampling?: false | import("@earendil-works/pi-ai").ConstrainedSamplingConfig;
+        replay?: "safe" | "unsafe";
+        executionMode?: import("@earendil-works/pi-durable").ToolExecutionMode;
+        prepareArguments?(args: unknown): unknown;
+        structuredOutputSchema?: TSchema;
+        callers?: readonly ("model" | "tools")[];
+        deferred?: true;
+        outputLimits?: {
+            readonly maxBytes?: number;
+            readonly maxLines?: number;
+            readonly retain?: "head" | "tail";
+        };
+        execute(args: unknown, api: ToolExecutionApi<import("@earendil-works/chord").JsonValue>, context: Context): Promise<import("@earendil-works/pi-durable").ToolExecutionResult<import("@earendil-works/chord").JsonValue>>;
+    }[];
+    worker: {
+        label: string;
+        name: string;
+        description: string;
+        parameters: TSchema;
+        constrainedSampling?: false | import("@earendil-works/pi-ai").ConstrainedSamplingConfig;
+        replay?: "safe" | "unsafe";
+        executionMode?: import("@earendil-works/pi-durable").ToolExecutionMode;
+        prepareArguments?(args: unknown): unknown;
+        structuredOutputSchema?: TSchema;
+        callers?: readonly ("model" | "tools")[];
+        deferred?: true;
+        outputLimits?: {
+            readonly maxBytes?: number;
+            readonly maxLines?: number;
+            readonly retain?: "head" | "tail";
+        };
+        execute(args: unknown, api: ToolExecutionApi<import("@earendil-works/chord").JsonValue>, context: Context): Promise<import("@earendil-works/pi-durable").ToolExecutionResult<import("@earendil-works/chord").JsonValue>>;
+    }[];
     execute: (name: ToolName, role: Role, input: unknown, api: CoreApi, context: Context) => Promise<Result>;
     contract: import("./contracts.ts").Contract;
 };

package/dist/authority/tools.js

@@ -1,12 +1,20 @@
-import { defineTool, LiveDoc } from '@earendil-works/pi-durable';
-import { Check } from 'typebox/value';
-import { contracts, checkResult, TOOL_NAMES } from "./contracts.js";
-import { GraphTaskController, GraphControlRefusal } from "./graph-control.js";
+import { defineTool } from '@earendil-works/pi-durable';
+import { contracts, checkSchema, checkResult, TOOL_NAMES } from "./contracts.js";
+import { GraphControlRefusal } from "./graph-control.js";
 import { projectGraphTaskCards } from "./graph-card.js";
 import { snapshotResult } from "./projection.js";
-import { open, plain, event } from "./state.js";
-const terminal = (kind) => ['goal_achieved', 'goal_failed', 'cancelled'].includes(kind);
+import { plain, event } from "./state.js";
+import { openAuthority as open, startEpoch, taskCards, unfinished, graphCommand, hasOperation, addAlert, addObligation, callReceipt, saveCall, allObligations, setObligationState } from "./store.js";
 const LEAD = 'team-lead';
+/** The input a role tool acts on. Pi's role adapters forward declared fields, including nested Task definitions. */
+export function declaredParameters(schema, value) {
+    const { items, properties } = schema;
+    if (Array.isArray(value) && items)
+        return value.map(item => declaredParameters(items, item));
+    if (value !== null && typeof value === 'object' && !Array.isArray(value) && properties)
+        return Object.fromEntries(Object.entries(value).filter(([key]) => Object.hasOwn(properties, key)).map(([key, item]) => [key, declaredParameters(properties[key], item)]));
+    return value;
+}
 class Declined extends Error {
     result;
     constructor(result) { super(String(result.message ?? result.reason)); this.result = result; }
@@ -27,53 +35,24 @@ function caller(s, api, role, name, args) {
         return unavailable(name, args, 'no_active_team', 'No active Team.');
     if (role === 'lead' && team.lead === api.conversationId)
         return LEAD;
-    const worker = Object.values(team.workers).find(w => w.state === 'active' && w.conversationId === api.conversationId);
+    const workerName = s.head.workerBindings[String(api.conversationId)];
+    const candidate = workerName ? team.workers[workerName] : undefined;
+    const worker = candidate?.state === 'active' && candidate.conversationId === api.conversationId ? candidate : undefined;
     if (role === 'worker' && worker)
         return worker.name;
     return unavailable(name, args, failureReason(name), 'Caller is not the exact current Team binding.');
 }
-function controller(s, api, name, args) {
-    if (!s.graph.snapshot || s.graph.epoch !== s.team.current?.epoch)
+function controller(s, _api, name, args) {
+    if (!s.head.graph || s.head.epoch !== s.team.current?.epoch)
         return unavailable(name, args, failureReason(name), 'Established graph authority is missing.');
-    try {
-        return GraphTaskController.recover(plain(s.graph.snapshot), () => new Date(api.now()));
-    }
-    catch {
+    if (!Number.isSafeInteger(s.head.graph.sequence) || !s.head.graph.ready || !s.head.graph.occupied)
         return unavailable(name, args, failureReason(name), 'Established graph authority is corrupt.');
-    }
 }
 function modelTask(t) {
     const [card] = projectGraphTaskCards({ readTasks: () => [t], readAttempts: () => [], selectReadyFrontier: () => [] });
     return { id: t.id, status: t.state.kind, assignee: t.assignee, needs: t.needs, state: card.state, attempts_started: t.attemptsStarted, version: t.version,
         ...('attemptId' in t.state ? { current_attempt_id: t.state.attemptId } : {}), ...(t.acceptedAttemptId ? { accepted_attempt_id: t.acceptedAttemptId } : {}) };
 }
-function reconcile(s, graph, now) {
-    const team = s.team.current;
-    const byId = new Map(graph.readTasks().map(t => [t.id, t]));
-    for (const obligation of Object.values(s.outbox.obligations)) {
-        if (obligation.epoch !== team.epoch || obligation.kind !== 'task' || obligation.state !== 'pending')
-            continue;
-        const t = byId.get(obligation.taskId);
-        if (!t || t.version !== obligation.version || t.assignee !== obligation.recipient || t.state.kind !== 'ready')
-            obligation.state = 'retired';
-    }
-    for (const t of graph.selectReadyFrontier()) {
-        const w = team.workers[t.assignee];
-        if (!w || w.state !== 'active')
-            continue;
-        const key = `${team.epoch}:task:${t.id}:${t.version}:g${w.generation}`;
-        if (!Object.hasOwn(s.outbox.obligations, key))
-            s.outbox.obligations[key] = { key, epoch: team.epoch, kind: 'task', recipient: w.name, conversationId: w.conversationId, generation: w.generation, taskId: t.id, version: t.version, state: 'pending', acceptedAt: now };
-    }
-    for (const attempt of graph.readAttempts().filter(a => a.state === 'superseded' || a.state === 'cancelled')) {
-        const w = team.workers[attempt.assignee];
-        if (!w || w.state !== 'active')
-            continue;
-        const key = `${team.epoch}:stop:${attempt.id}:g${w.generation}`;
-        if (!Object.hasOwn(s.outbox.obligations, key))
-            s.outbox.obligations[key] = { key, epoch: team.epoch, kind: 'stop', recipient: w.name, conversationId: w.conversationId, generation: w.generation, taskId: attempt.taskId, state: 'pending', acceptedAt: now };
-    }
-}
 /** The catalog resolver that options select: the host's per-lead port, else the static list. */
 export function catalogOf(options) {
     return async (tx, lead) => options.catalog ? options.catalog(tx, lead) : { modelRoles: options.modelRoles, ...(options.defaultModelRole ? { defaultModelRole: options.defaultModelRole } : {}) };
@@ -95,12 +74,9 @@ export function createAuthorityTools(options) {
                 if (s.team.current.lead !== api.conversationId)
                     return unavailable(name, a, 'team_authority_unavailable', 'Only the established lead can create the next Team.');
                 s.team.history.push(plain(s.team.current));
-                if (s.graph.snapshot)
-                    s.graph.history = { ...s.graph.history, [s.team.current.epoch]: plain(s.graph.snapshot) };
             }
             s.team.current = { epoch: `team:${api.taskId}`, name: a.name, purpose: a.purpose, lead: api.conversationId, lifecycle: 'active', workers: {}, createdAt: api.now() };
-            s.graph.epoch = s.team.current.epoch;
-            s.graph.snapshot = new GraphTaskController(undefined, () => new Date(api.now())).snapshot();
+            await startEpoch(s, s.team.current.epoch);
             delete s.journal.reservation;
             s.journal.acknowledged = 0;
             await event(tx, s, LEAD, 'team_created', { at: new Date(api.now()).toISOString() });
@@ -132,56 +108,54 @@ export function createAuthorityTools(options) {
                 selected = await options.resolveModelRole(tx, plain(selected));
             const binding = await options.createWorker(tx, plain(selected));
             team.workers = { ...plain(team.workers), [a.name]: { ...binding, name: a.name, scope: a.scope, generation: (prior?.generation ?? 0) + 1, state: 'active', role: plain(selected), createdAt: api.now() } };
+            if (prior) {
+                delete s.head.workerBindings[String(prior.conversationId)];
+                s.head.stopRefresh = true;
+            }
+            s.head.workerBindings[String(binding.conversationId)] = a.name;
             await event(tx, s, actor, 'worker_created', { worker: a.name, at: new Date(api.now()).toISOString() });
             return { kind: 'worker_ensured', effect: prior ? 'reconnected' : 'created', worker: { name: a.name, carrier: 'connected', model_role: selected.name } };
         }
-        const graph = controller(s, api, name, a);
+        controller(s, api, name, a);
         if (name === 'team_shutdown' && team.lifecycle === 'stopped')
-            return { kind: 'team_shutdown', lifecycle: 'stopped', stopped_workers: Object.values(team.workers).filter(w => w.state === 'stopped').map(w => w.name), unfinished_task_ids: graph.readTasks().filter(t => !terminal(t.state.kind)).map(t => t.id) };
+            return { kind: 'team_shutdown', lifecycle: 'stopped', stopped_workers: Object.values(team.workers).filter(w => w.state === 'stopped').map(w => w.name), unfinished_task_ids: await unfinished(s) };
         if (name === 'task_read') {
-            const cards = new Map(projectGraphTaskCards(graph).map(t => [t.id, t]));
+            const cards = new Map((await taskCards(s, role === 'worker' ? [a.task_id] : a.task_ids)).map(t => [t.id, t]));
             if (role === 'worker')
                 return cards.has(a.task_id) ? { kind: 'found', task: cards.get(a.task_id) } : { kind: 'missing', task_id: a.task_id, reason: 'task_not_found' };
             return { kind: 'task_read_batch', outcomes: a.task_ids.map((id, input_index) => cards.has(id) ? { kind: 'found', input_index, task_id: id, task: cards.get(id) } : { kind: 'missing', input_index, task_id: id, reason: 'task_not_found' }) };
         }
         if (name === 'task_graph_apply') {
             // The controller owns replay identity. Check current assignees only for a new operation.
-            const already = graph.snapshot().receipts.some(r => r.operationId === a.operation_id);
+            const already = await hasOperation(s, a.operation_id);
             if (!already && a.tasks.some(t => !Object.hasOwn(team.workers, t.assignee) || team.workers[t.assignee].state !== 'active'))
                 return decline({ kind: 'refused', operation_id: a.operation_id, reason: 'worker_unavailable', message: 'Every assignee must be a current Worker.' });
             const tasks = a.tasks.map(t => ({ key: t.key, title: t.title, goal: t.goal, assignee: t.assignee, needs: t.needs, ...(t.on_goal_failed ? { onGoalFailed: { target: t.on_goal_failed.target, maxTraversals: t.on_goal_failed.max_traversals } } : {}) }));
-            const r = graph.applyGraph({ operationId: a.operation_id, expectedGraphVersion: a.expected_graph_version, tasks });
-            if (!r.replayed) {
-                s.graph.snapshot = graph.snapshot();
+            const r = await graphCommand(s, { kind: 'apply', input: { operationId: a.operation_id, expectedGraphVersion: a.expected_graph_version, tasks } }, api.now);
+            if (!r.replayed)
                 await event(tx, s, actor, 'graph_applied', { taskIds: r.tasks.map(t => t.id), at: new Date(api.now()).toISOString() });
-                reconcile(s, graph, api.now());
-            }
             return { kind: 'task_graph_applied', operation_id: r.operationId, graph_version: r.graphVersion, replayed: r.replayed, tasks_by_key: Object.fromEntries(r.tasks.map(t => [t.id, modelTask(t)])), ready_task_ids: r.readyTaskIds };
         }
         if (name === 'task_update') {
             if (role === 'worker' && a.transition === 'cancel')
                 return decline({ kind: 'refused', task_id: a.task_id, operation_id: a.operation_id, reason: 'worker_mismatch', message: 'Only the lead cancels Tasks.' });
-            const r = graph.transition({ taskId: a.task_id, operationId: a.operation_id, expectedVersion: a.expected_version, transition: a.transition, currentContext: a.current_context, evidence: a.evidence, worker: role === 'worker' ? actor : a.transition && a.transition !== 'cancel' ? LEAD : undefined });
-            if (!r.replayed) {
-                s.graph.snapshot = graph.snapshot();
+            const r = await graphCommand(s, { kind: 'transition', input: { taskId: a.task_id, operationId: a.operation_id, expectedVersion: a.expected_version, transition: a.transition, currentContext: a.current_context, evidence: a.evidence, worker: role === 'worker' ? actor : a.transition && a.transition !== 'cancel' ? LEAD : undefined } }, api.now);
+            if (!r.replayed)
                 await event(tx, s, actor, 'task_transitioned', { taskId: r.task.id, at: new Date(api.now()).toISOString(), text: a.evidence ?? a.current_context ?? r.transition });
-                reconcile(s, graph, api.now());
-            }
             return { kind: 'updated', operation_id: r.operationId, replayed: r.replayed, transition: r.transition, task: { id: r.task.id, status: r.task.state.kind, assignee: r.task.assignee, version: r.task.version }, ready_task_ids: r.readyTaskIds, ...(r.failureTraversal ? { failure_traversal: { source_task_id: r.failureTraversal.sourceTaskId, target_task_id: r.failureTraversal.targetTaskId, traversal: r.failureTraversal.traversal } } : {}) };
         }
         if (name === 'alert_send') {
-            const to = role === 'worker' ? LEAD : a.to;
+            const to = role === 'worker' ? LEAD : a.to, interrupt = role === 'lead' && a.interrupt === true;
             if (!a.text?.trim() || a.task_version && !a.task_id || (to === '*') !== (a.kind === 'announcement'))
                 return decline({ kind: 'refused', reason: 'invalid_fanout', message: 'Invalid Alert text, Task reference or announcement target.' });
             const recipients = to === LEAD ? [{ name: LEAD, conversationId: team.lead, generation: 0 }] : Object.values(team.workers).filter(w => w.state === 'active' && (to === '*' || w.name === to)).map(w => ({ name: w.name, conversationId: w.conversationId, generation: w.generation }));
             if (!recipients.length)
                 return decline({ kind: 'refused', reason: to === '*' ? 'no_eligible_recipients' : 'recipient_not_current', message: 'No current recipient.' });
             const id = `${team.epoch}:alert:${api.taskId}`;
-            s.outbox.alerts[id] = plain({ id, from: actor, kind: a.kind, text: a.text.trim(), ...(a.interrupt ? { interrupt: true } : {}), task_id: a.task_id, task_version: a.task_version, receivedAt: new Date(api.now()).toISOString(), recipients });
+            await addAlert(s, plain({ id, from: actor, kind: a.kind, text: a.text.trim(), ...(interrupt ? { interrupt: true } : {}), task_id: a.task_id, task_version: a.task_version, receivedAt: new Date(api.now()).toISOString(), recipients }));
             for (const recipient of recipients) {
                 const key = `${id}:${recipient.name}:g${recipient.generation}`;
-                const run = a.interrupt ? (await tx.doc(LiveDoc, recipient.conversationId)).run?.taskId : undefined;
-                s.outbox.obligations[key] = { key, epoch: team.epoch, kind: 'alert', recipient: recipient.name, conversationId: recipient.conversationId, generation: recipient.generation, alertId: id, state: 'pending', acceptedAt: api.now(), ...(a.interrupt ? { interrupt: true, ...(run !== undefined ? { interruptRun: run } : {}) } : {}) };
+                await addObligation(s, { key, epoch: team.epoch, kind: 'alert', recipient: recipient.name, conversationId: recipient.conversationId, generation: recipient.generation, alertId: id, state: 'pending', acceptedAt: api.now(), ...(interrupt ? { interrupt: true, interruptAt: 'delivery' } : {}) });
             }
             await event(tx, s, actor, 'alert_accepted', { at: new Date(api.now()).toISOString() });
             return { kind: 'alert_sent', accepted_recipients: recipients.map(r => r.name), failed_recipients: [], ...(a.task_id ? { task_id: a.task_id } : {}), ...(a.task_version ? { task_version: a.task_version } : {}) };
@@ -192,8 +166,8 @@ export function createAuthorityTools(options) {
                 return { kind: 'refused', reason: 'observation_in_progress', message: 'An observation awaits presentation acknowledgement.', state_changed: false, observation_advanced: false };
             if (!options.sync)
                 s.journal.reservation = { epoch: team.epoch, call: String(api.taskId), through: s.journal.seq };
-            const roles = await rolesOf(tx, team.lead), snapshot = snapshotResult(s, roles.modelRoles, roles.defaultModelRole);
-            return options.sync ? options.sync(tx, s, a.view, api, snapshot) : snapshot;
+            const roles = await rolesOf(tx, team.lead), snapshot = () => snapshotResult(s, roles.modelRoles, roles.defaultModelRole);
+            return options.sync ? options.sync(tx, s, a.view, api, snapshot) : snapshot();
         }
         // Lifecycle effects happen after the committed stop intent, outside this transaction.
         let workers;
@@ -203,7 +177,7 @@ export function createAuthorityTools(options) {
             const worker = Object.hasOwn(team.workers, a.worker) ? team.workers[a.worker] : undefined;
             if (!worker)
                 return decline({ kind: 'refused', reason: 'worker_not_found', worker: a.worker });
-            const held = graph.readTasks().filter(t => t.assignee === worker.name && !terminal(t.state.kind)).map(t => t.id);
+            const held = await unfinished(s, worker.name);
             if (held.length)
                 return decline({ kind: 'refused', reason: 'nonterminal_tasks_assigned', worker: worker.name, guarding_task_ids: held });
             if (worker.state === 'stopped')
@@ -215,26 +189,32 @@ export function createAuthorityTools(options) {
         if (workers.length && !options.stopWorker && !options.settleStops)
             return unavailable(name, a, name === 'worker_stop' ? 'carrier_unavailable' : 'team_authority_unavailable', 'Anchor stop adapter is not installed.');
         const stops = workers.map(w => { const key = `${team.epoch}:stop:${w.name}:g${w.generation}`; w.state = 'stopping'; s.team.stops[key] ??= { epoch: team.epoch, worker: w.name, binding: { conversationId: w.conversationId, anchorId: w.anchorId }, generation: w.generation, tasks: [w.anchorId], conversations: [w.conversationId], confirmed: false }; return key; });
-        for (const obligation of Object.values(s.outbox.obligations))
+        for (const obligation of await allObligations(s))
             if (obligation.epoch === team.epoch && workers.some(w => w.name === obligation.recipient))
-                obligation.state = 'retired';
+                await setObligationState(s, obligation, 'retired');
         if (name === 'team_shutdown')
             team.shutdownPending = true;
         return { stops, epoch: team.epoch };
     }
     async function execute(name, role, input, api, context) {
         const schema = contract[role][name];
-        if (!schema || !Check(schema, input))
+        // Earlier receipts hashed raw arguments. Their exact input must still replay without executing again.
+        const rawFingerprint = JSON.stringify({ name, role, input, conversation: api.conversationId });
+        if (schema)
+            input = declaredParameters(schema, input);
+        if (!schema || !checkSchema(schema, input))
             throw new Error(`Invalid ${role} ${name} parameters`);
         const a = input;
-        const key = String(api.taskId), fingerprint = JSON.stringify({ name, role, input, conversation: api.conversationId });
+        const fingerprint = JSON.stringify({ name, role, input, conversation: api.conversationId });
         try {
             const result = await api.commit(async (tx) => {
-                const s = await open(tx), saved = Object.hasOwn(s.receipts.calls, key) ? s.receipts.calls[key] : undefined;
+                const native = (await tx.task(api.taskId))?.kind === 'pi.tool';
+                const s = await open(tx), receipt = await callReceipt(s, api.taskId, native), saved = receipt.fingerprint ? receipt : undefined;
+                s.deferFlush = true;
                 if (saved) {
-                    if (saved.fingerprint !== fingerprint)
+                    if (saved.fingerprint !== fingerprint && saved.fingerprint !== rawFingerprint)
                         throw new Error('Durable tool identity reused with changed input');
-                    return plain(saved.result ?? { stops: saved.stops, epoch: saved.epoch });
+                    return saved.result ? JSON.parse(saved.result) : plain({ stops: saved.stops, epoch: saved.epoch });
                 }
                 const r = await command(name, role, a, api, tx, s);
                 if (name !== 'task_read')
@@ -242,10 +222,10 @@ export function createAuthorityTools(options) {
                 if ('kind' in r) {
                     const clean = plain(checkResult(contract, name, r));
                     if (name !== 'task_read')
-                        s.receipts.calls[key] = { fingerprint, result: clean };
+                        await saveCall(s, api.taskId, { fingerprint, result: clean });
                     return clean;
                 }
-                s.receipts.calls[key] = { fingerprint, stops: r.stops, epoch: r.epoch };
+                await saveCall(s, api.taskId, { fingerprint, stops: r.stops, epoch: r.epoch });
                 return plain(r);
             }, context);
             if ('kind' in result)
@@ -269,6 +249,7 @@ export function createAuthorityTools(options) {
             }
             return await api.commit(async (tx) => {
                 const s = await open(tx), team = s.team.current;
+                await callReceipt(s, api.taskId);
                 if (team.epoch !== result.epoch)
                     throw new Error('Team epoch changed during stop');
                 const stopped = result.stops.filter(id => s.team.stops[id].confirmed && s.team.stops[id].worker).map(id => s.team.stops[id].worker), failed = result.stops.filter(id => !s.team.stops[id].confirmed).map(id => s.team.stops[id].worker ?? LEAD);
@@ -276,15 +257,16 @@ export function createAuthorityTools(options) {
                 if (name === 'worker_stop')
                     r = failed.length ? { kind: 'refused', reason: 'stop_not_confirmed', worker: a.worker } : { kind: 'worker_stopped', worker: a.worker };
                 else {
-                    const unfinished = controller(s, api, name, a).readTasks().filter(t => !terminal(t.state.kind)).map(t => t.id);
+                    controller(s, api, name, a);
+                    const remaining = await unfinished(s);
                     if (!failed.length && team.lifecycle !== 'stopped') {
                         team.lifecycle = 'stopped';
                         await event(tx, s, LEAD, 'team_stopped', { at: new Date(api.now()).toISOString() });
                     }
-                    r = failed.length ? { kind: 'partial', lifecycle: 'active', stopped_workers: stopped, failed_workers: failed, unfinished_task_ids: unfinished, recovery: { action: 'retry_team_shutdown' } } : { kind: 'team_shutdown', lifecycle: 'stopped', stopped_workers: stopped, unfinished_task_ids: unfinished };
+                    r = failed.length ? { kind: 'partial', lifecycle: 'active', stopped_workers: stopped, failed_workers: failed, unfinished_task_ids: remaining, recovery: { action: 'retry_team_shutdown' } } : { kind: 'team_shutdown', lifecycle: 'stopped', stopped_workers: stopped, unfinished_task_ids: remaining };
                 }
                 const clean = plain(checkResult(contract, name, r));
-                s.receipts.calls[key] = { fingerprint, result: clean };
+                await saveCall(s, api.taskId, { fingerprint, result: clean });
                 return clean;
             }, context);
         }
@@ -303,24 +285,30 @@ export function createAuthorityTools(options) {
             if (name !== 'task_read')
                 await api.commit(async (tx) => {
                     const s = await open(tx);
-                    s.receipts.calls[key] = { fingerprint, result: clean };
+                    await saveCall(s, api.taskId, { fingerprint, result: clean });
                 }, context);
             return clean;
         }
     }
     function tools(role) {
-        return TOOL_NAMES.filter(name => contract[role][name]).map(name => defineTool({
-            name, description: `${name}: PTB rc.7 authority operation.`, parameters: contract[role][name], replay: 'safe',
-            execute: async (args, api, context) => {
-                const result = await execute(name, role, args, api, context);
-                const pending = options.settleStops && (result.kind === 'partial' || result.reason === 'stop_not_confirmed');
-                const names = result.kind === 'partial' ? result.failed_workers.map(n => n === LEAD ? 'Team delivery and notification tasks' : n).join(', ') : String(result.worker);
-                const output = [{ type: 'text', text: JSON.stringify(result) }];
-                if (pending)
-                    output.push({ type: 'text', text: `Still stopping: ${names}. The stop is recorded and no new work starts. Settlement continues in the background. A later ${name} confirms completion.` });
-                return { output };
-            },
-        }));
+        return TOOL_NAMES.filter(name => contract[role][name]).map(name => {
+            const presentation = contract.presentation[role][name];
+            if (!presentation)
+                throw new Error(`The rc.7 contract has no ${role} ${name} label and description`);
+            // pi-durable registers no label. It stays on the tool for hosts that show one, as Pi does.
+            return { ...defineTool({
+                    name, description: presentation.description, parameters: contract[role][name], replay: 'safe',
+                    execute: async (args, api, context) => {
+                        const result = await execute(name, role, args, api, context);
+                        const pending = options.settleStops && (result.kind === 'partial' || result.reason === 'stop_not_confirmed');
+                        const names = result.kind === 'partial' ? result.failed_workers.map(n => n === LEAD ? 'Team delivery and notification tasks' : n).join(', ') : String(result.worker);
+                        const output = [{ type: 'text', text: JSON.stringify(result) }];
+                        if (pending)
+                            output.push({ type: 'text', text: `Still stopping: ${names}. The stop is recorded and no new work starts. Settlement continues in the background. A later ${name} confirms completion.` });
+                        return { output };
+                    },
+                }), label: presentation.label };
+        });
     }
     return { lead: tools('lead'), worker: tools('worker'), execute, contract };
 }

package/dist/testing.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Unstable test support for hosts that exercise authority internals.
+ * It names only the internals HyperCarrier's AmPi tests import. Production code must use `./authority`.
+ * Names and behavior can change in any release without a major version.
+ */
+export { Deliver } from './authority/delivery.ts';
+export { createAuthorityTools, type CoreApi } from './authority/tools.ts';
+export { addAlert, addObligation, flushAuthority, graphCommand, obligation, setObligationState, taskRecord, type Authority } from './authority/store.ts';
+export type { Alert, Obligation } from './authority/state.ts';
+export { ObservationHeadDoc, PageDoc, PageBodyDoc, reserve, startObservationEpoch } from './authority/observation.ts';
+export { advanceAcknowledged, page, retireBody, savePage } from './authority/observation-store.ts';

package/dist/testing.js

@@ -0,0 +1,10 @@
+/**
+ * Unstable test support for hosts that exercise authority internals.
+ * It names only the internals HyperCarrier's AmPi tests import. Production code must use `./authority`.
+ * Names and behavior can change in any release without a major version.
+ */
+export { Deliver } from "./authority/delivery.js";
+export { createAuthorityTools } from "./authority/tools.js";
+export { addAlert, addObligation, flushAuthority, graphCommand, obligation, setObligationState, taskRecord } from "./authority/store.js";
+export { ObservationHeadDoc, PageDoc, PageBodyDoc, reserve, startObservationEpoch } from "./authority/observation.js";
+export { advanceAcknowledged, page, retireBody, savePage } from "./authority/observation-store.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercarrier/pi-team-durable",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.3",
   "description": "Pi Team Bright semantics on pi-durable: one Task authority per Team, Workers as durable subthreads, accepted-then-delivered notices.",
   "repository": {
     "type": "git",
@@ -21,6 +21,11 @@
       "types": "./dist/authority/index.d.ts",
       "import": "./dist/authority/index.js",
       "default": "./dist/authority/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
     }
   },
   "files": [
@@ -36,6 +41,7 @@
     "prepare": "npm run build",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:oracle": "node test/oracle-run.ts",
     "verify:package": "node scripts/verify-package.mjs"
   },
   "dependencies": {