@hypercarrier/pi-team-durable 0.0.0-stage → 0.1.0-rc.2

package/dist/authority/sync.d.ts

@@ -0,0 +1,13 @@
+import { type Tx, type EntryId } from '@earendil-works/pi-durable';
+import type { CoreApi } from './tools.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[]): 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: () => Promise<Result>): Promise<Result>;

package/dist/authority/sync.js

@@ -0,0 +1,78 @@
+import { LiveDoc } from '@earendil-works/pi-durable';
+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 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.' })),
+        task_changes: ids.flatMap(id => { const current = cards.find(t => t.id === id); return current ? [{ task_id: id, change_kinds: ['status'], journal_entries: events.filter(e => e.taskId === id && e.at && e.text).map(e => ({ id: `${e.epoch}:${e.seq}`, at: e.at, actor: e.actor, kind: 'note', text: e.text })), current }] : []; }),
+        alerts: [], };
+}
+/** Page native history without making the journal document an unbounded cache. */
+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 = 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);
+    const events = [];
+    let scanThrough = after;
+    for (const entry of native.items) {
+        if (after !== undefined && entry.id <= after)
+            continue;
+        scanThrough = entry.id;
+        if (entry.kind === 'ptb.event') {
+            const event = entry.data;
+            if (event.epoch === s.team.current.epoch && event.seq > from)
+                events.push({ ...event, entryId: entry.id });
+        }
+        if (events.length >= UPDATE_PAGE_EVENTS)
+            break;
+    }
+    return { events, scanThrough };
+}
+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 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 = 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 = (await pages(o, 'releasedPages', true)).find(p => p.epoch === team.epoch);
+    if (released) {
+        const result = JSON.parse(released.body);
+        released.state = 'replaced';
+        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 = 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 = await snapshot();
+        through = s.journal.seq;
+        scanThrough = s.journal.events.at(-1)?.entryId;
+    }
+    else {
+        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;
+    }
+    await reserve(o, { id, epoch: team.epoch, lead: team.lead, run, from, through, carrier, ...(scanThrough ? { scanThrough } : {}) }, result);
+    return result;
+}

package/dist/authority/task-version-ref.d.ts

@@ -0,0 +1,3 @@
+export type TaskVersionRef = `v_${string}`;
+/** Stable model-facing version token. */
+export declare function taskVersionRef(sourceRevision: string): TaskVersionRef;

package/dist/authority/task-version-ref.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+/** Stable model-facing version token. */
+export function taskVersionRef(sourceRevision) {
+    return `v_${createHash("sha256").update(sourceRevision).digest("hex").slice(0, 16)}`;
+}

package/dist/authority/tools.d.ts

@@ -0,0 +1,105 @@
+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 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[];
+    defaultModelRole?: string;
+    goalMaxLength?: number;
+    createWorker?: (tx: Tx, role: ModelRole) => Promise<Binding>;
+    resolveModelRole?: (tx: Tx, role: ModelRole) => Promise<ModelRole>;
+    catalog?: (tx: Tx, lead: ConversationId) => Promise<ModelRoleCatalog>;
+    stopWorker?: (binding: Binding, context: Context) => Promise<boolean>;
+    settleStops?: (stops: {
+        key: string;
+        intent: StopIntent;
+    }[], context: Context, api: CoreApi) => Promise<boolean[]>;
+    afterCommand?: (tx: Tx, s: State, name: ToolName, result: Result | {
+        stops: string[];
+        epoch: string;
+    }, api: CoreApi) => Promise<void>;
+    sync?: (tx: Tx, s: State, view: Args['view'], api: CoreApi, snapshot: () => Promise<Result>) => Promise<Result>;
+}
+interface Args {
+    name?: string;
+    purpose?: string;
+    scope?: string;
+    model_role?: string;
+    worker?: string;
+    view?: 'snapshot' | 'updates';
+    task_id?: string;
+    task_ids?: string[];
+    operation_id?: string;
+    expected_graph_version?: GraphVersionRef;
+    expected_version?: TaskVersionRef;
+    transition?: GraphTaskTransition;
+    current_context?: string;
+    evidence?: string;
+    tasks?: {
+        key: string;
+        title: string;
+        goal: string;
+        assignee: string;
+        needs?: string[];
+        on_goal_failed?: {
+            target: string;
+            max_traversals: number;
+        };
+    }[];
+    to?: string;
+    kind?: string;
+    text?: string;
+    task_version?: string;
+    interrupt?: boolean;
+}
+/** 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: {
+        label: string;
+        name: string;
+        description: string;
+        parameters: import("typebox").TSchema;
+        constrainedSampling?: false | import("@earendil-works/pi-ai").ConstrainedSamplingConfig;
+        replay?: "safe" | "unsafe";
+        executionMode?: import("@earendil-works/pi-durable").ToolExecutionMode;
+        prepareArguments?(args: unknown): unknown;
+        structuredOutputSchema?: import("typebox").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: import("typebox").TSchema;
+        constrainedSampling?: false | import("@earendil-works/pi-ai").ConstrainedSamplingConfig;
+        replay?: "safe" | "unsafe";
+        executionMode?: import("@earendil-works/pi-durable").ToolExecutionMode;
+        prepareArguments?(args: unknown): unknown;
+        structuredOutputSchema?: import("typebox").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;
+};
+export {};

package/dist/authority/tools.js

@@ -0,0 +1,302 @@
+import { defineTool, LiveDoc } 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 { 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';
+class Declined extends Error {
+    result;
+    constructor(result) { super(String(result.message ?? result.reason)); this.result = result; }
+}
+const decline = (result) => { throw new Declined(result); };
+function unavailable(name, args, reason, message) {
+    return decline({ kind: 'unavailable', reason, message,
+        ...(['task_graph_apply', 'task_update'].includes(name) ? { operation_id: args.operation_id } : {}),
+        ...(name === 'task_update' ? { task_id: args.task_id } : {}),
+    });
+}
+function failureReason(name) {
+    return ['task_read', 'task_update', 'task_graph_apply'].includes(name) ? 'task_authority_unavailable' : name === 'team_sync' ? 'team_state_unavailable' : 'team_authority_unavailable';
+}
+function caller(s, api, role, name, args) {
+    const team = s.team.current;
+    if (!team || (team.lifecycle !== 'active' && !(name === 'team_shutdown' && role === 'lead' && team.lead === api.conversationId)))
+        return unavailable(name, args, 'no_active_team', 'No active Team.');
+    if (role === 'lead' && team.lead === api.conversationId)
+        return LEAD;
+    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.head.graph || s.head.epoch !== s.team.current?.epoch)
+        return unavailable(name, args, failureReason(name), 'Established graph authority is missing.');
+    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 } : {}) };
+}
+/** 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 } : {}) };
+}
+/** Authority commands commit intent and replay receipts; injected ports own effects. */
+export function createAuthorityTools(options) {
+    const contract = contracts(options.goalMaxLength);
+    const rolesOf = catalogOf(options);
+    const catalog = (c) => ({ model_roles: c.modelRoles.map(r => ({ name: r.name, use: r.use })), ...(c.defaultModelRole ? { default_model_role: c.defaultModelRole } : {}) });
+    async function command(name, role, a, api, tx, s) {
+        if (name === 'team_create') {
+            if (role !== 'lead')
+                return unavailable(name, a, 'team_authority_unavailable', 'Worker cannot create a Team.');
+            if (s.team.current?.lifecycle === 'active')
+                return decline({ kind: 'refused', reason: 'active_team_exists', message: 'An active Team already owns this store.' });
+            if (!/^[A-Za-z0-9_-]{1,64}$/.test(a.name))
+                return decline({ kind: 'refused', reason: 'name_unavailable', message: 'Invalid Team name.' });
+            if (s.team.current) {
+                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));
+            }
+            s.team.current = { epoch: `team:${api.taskId}`, name: a.name, purpose: a.purpose, lead: api.conversationId, lifecycle: 'active', workers: {}, createdAt: api.now() };
+            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() });
+            return { kind: 'team_created', team: { name: a.name, lifecycle: 'active' }, ...catalog(await rolesOf(tx, api.conversationId)) };
+        }
+        const actor = caller(s, api, role, name, a), team = s.team.current;
+        if (name === 'ensure_worker') {
+            if (team.shutdownPending)
+                return unavailable(name, a, 'carrier_unavailable', 'Team shutdown is pending.');
+            if (a.name === LEAD || !/^[A-Za-z0-9_-]{1,64}$/.test(a.name))
+                return unavailable(name, a, 'team_authority_unavailable', 'Invalid or reserved Worker name.');
+            const prior = Object.hasOwn(team.workers, a.name) ? team.workers[a.name] : undefined;
+            const existing = prior ? { name: prior.name, scope: prior.scope, carrier: prior.state === 'active' ? 'connected' : 'absent', model_role: prior.role.name } : undefined;
+            if (prior && prior.scope !== a.scope)
+                return decline({ kind: 'refused', reason: 'name_scope_conflict', existing_worker: existing });
+            if (prior && a.model_role && prior.role.name !== a.model_role)
+                return decline({ kind: 'refused', reason: 'model_conflict', existing_worker: existing });
+            if (prior?.state === 'stopping')
+                return unavailable(name, a, 'carrier_unavailable', 'The exact Worker stop is pending.');
+            if (prior?.state === 'active')
+                return { kind: 'worker_ensured', effect: 'reused', worker: { name: prior.name, carrier: 'connected', model_role: prior.role.name } };
+            const roles = prior ? undefined : await rolesOf(tx, team.lead);
+            let selected = prior?.role ?? roles.modelRoles.find(r => r.name === (a.model_role ?? roles.defaultModelRole));
+            if (!selected)
+                return decline({ kind: 'refused', reason: 'invalid_model_role', valid_model_roles: catalog(roles).model_roles, message: 'Select a configured model role.' });
+            if (!options.createWorker)
+                return unavailable(name, a, 'carrier_unavailable', 'Worker anchor adapter is not installed.');
+            if (options.resolveModelRole)
+                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 } };
+        }
+        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: await unfinished(s) };
+        if (name === 'task_read') {
+            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 = 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 = 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() });
+            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 = 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 });
+            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;
+            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}`;
+            await addAlert(s, 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 }));
+            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;
+                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(), ...(a.interrupt ? { interrupt: true, ...(run !== undefined ? { interruptRun: run } : {}) } : {}) });
+            }
+            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 } : {}) };
+        }
+        if (name === 'team_sync') {
+            // Never consume a page on a tool call alone.
+            if (!options.sync && s.journal.reservation)
+                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();
+        }
+        // Lifecycle effects happen after the committed stop intent, outside this transaction.
+        let workers;
+        if (name === 'worker_stop') {
+            if (a.worker === LEAD)
+                return decline({ kind: 'refused', reason: 'leader_reserved', worker: a.worker });
+            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 = 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')
+                return { kind: 'worker_stopped', worker: worker.name };
+            workers = [worker];
+        }
+        else
+            workers = Object.values(team.workers).filter(w => w.state !== 'stopped');
+        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 await allObligations(s))
+            if (obligation.epoch === team.epoch && workers.some(w => w.name === obligation.recipient))
+                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 || !checkSchema(schema, input))
+            throw new Error(`Invalid ${role} ${name} parameters`);
+        const a = input;
+        const fingerprint = JSON.stringify({ name, role, input, conversation: api.conversationId });
+        try {
+            const result = await api.commit(async (tx) => {
+                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)
+                        throw new Error('Durable tool identity reused with changed input');
+                    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')
+                    await options.afterCommand?.(tx, s, name, r, api);
+                if ('kind' in r) {
+                    const clean = plain(checkResult(contract, name, r));
+                    if (name !== 'task_read')
+                        await saveCall(s, api.taskId, { fingerprint, result: clean });
+                    return clean;
+                }
+                await saveCall(s, api.taskId, { fingerprint, stops: r.stops, epoch: r.epoch });
+                return plain(r);
+            }, context);
+            if ('kind' in result)
+                return result;
+            const pending = (await api.commit(async (tx) => { const s = await open(tx); return result.stops.map(key => ({ key, intent: plain(s.team.stops[key]) })); }, context)).filter(p => !p.intent.confirmed);
+            const settled = options.settleStops ? await options.settleStops(pending, context, api) : await Promise.all(pending.map(p => p.intent.binding ? options.stopWorker(p.intent.binding, context) : false));
+            for (const [i, { key: stop, intent }] of pending.entries()) {
+                if (settled[i])
+                    await api.commit(async (tx) => {
+                        const s = await open(tx), w = intent.worker ? s.team.current?.workers[intent.worker] : undefined;
+                        if (s.team.current?.epoch !== intent.epoch || (intent.binding && (!w || w.generation !== intent.generation || w.anchorId !== intent.binding.anchorId)))
+                            throw new Error('Stop binding changed');
+                        if (!s.team.stops[stop].confirmed) {
+                            s.team.stops[stop].confirmed = true;
+                            if (w) {
+                                w.state = 'stopped';
+                                await event(tx, s, LEAD, 'worker_stopped', { worker: w.name, at: new Date(api.now()).toISOString() });
+                            }
+                        }
+                    }, context);
+            }
+            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);
+                let r;
+                if (name === 'worker_stop')
+                    r = failed.length ? { kind: 'refused', reason: 'stop_not_confirmed', worker: a.worker } : { kind: 'worker_stopped', worker: a.worker };
+                else {
+                    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: 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));
+                await saveCall(s, api.taskId, { fingerprint, result: clean });
+                return clean;
+            }, context);
+        }
+        catch (error) {
+            let refusal;
+            if (error instanceof Declined)
+                refusal = plain(error.result);
+            else if (error instanceof GraphControlRefusal) {
+                const reason = error.code === 'task_version_conflict' ? 'version_conflict' : error.code;
+                refusal = { kind: 'refused', operation_id: a.operation_id, ...(name === 'task_update' ? { task_id: a.task_id } : {}), reason, message: error.message };
+            }
+            else
+                throw error;
+            const clean = checkResult(contract, name, refusal);
+            // The failed transaction rolls back all mutations. Persist its model result separately.
+            if (name !== 'task_read')
+                await api.commit(async (tx) => {
+                    const s = await open(tx);
+                    await saveCall(s, api.taskId, { fingerprint, result: clean });
+                }, context);
+            return clean;
+        }
+    }
+    function tools(role) {
+        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,65 @@
 {
   "name": "@hypercarrier/pi-team-durable",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.2",
+  "description": "Pi Team Bright semantics on pi-durable: one Task authority per Team, Workers as durable subthreads, accepted-then-delivered notices.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deephbz/pi-team-durable.git"
+  },
+  "homepage": "https://github.com/deephbz/pi-team-durable#readme",
+  "bugs": {
+    "url": "https://github.com/deephbz/pi-team-durable/issues"
+  },
+  "author": "deephbz",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "exports": {
+    "./authority": {
+      "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": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/authority/rc7-contract.json dist/authority/",
+    "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": {
+    "typebox": "1.3.27"
+  },
+  "peerDependencies": {
+    "@earendil-works/chord": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-durable": "1.4.0"
+  },
+  "devDependencies": {
+    "@earendil-works/chord": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-durable": "1.4.0",
+    "@hypercarrier/pi-team-bright": "0.25.1",
+    "@types/node": "^22.19.0",
+    "jiti": "2.7.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  }
+}