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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 deephbz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @hypercarrier/pi-team-durable
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pi Team Bright semantics on [pi-durable](https://www.npmjs.com/package/@earendil-works/pi-durable):
+one Task authority per Team, Workers as durable subthreads, accepted-then-delivered
+notices.
+
+## Status
+
+- **Prerelease.** The npm `next` tag carries it. This package has its own version
+  line, independent of Pi Team Bright. Pi Team Bright 0.25.1 is its contract pin.
+- **No standalone runtime.** The package needs a host that supplies the Team ports:
+  model roles or a `catalog`, `observationPort`, `abortRun` and `stop`. The runtime
+  builds Worker creation and stop settlement from them. Today the host is the AmPi
+  node.
+- **Exact peers.** The peer dependencies pin `@earendil-works/pi-durable`,
+  `@earendil-works/pi-ai` and `@earendil-works/chord` to 1.4.0. Other versions give
+  a peer conflict.
+- **First version without provenance.** The first version was published by hand.
+  Later versions publish from CI with npm provenance.
+- **Protocol value.** The persisted notice value `sender: 'durable-team'` is a
+  protocol value from the package's former name. It stays unchanged.
+- **Tests here.** CI runs the unit suites.
+  The SIGKILL crash suite and `bench/e2e.ts` stay in HyperCarrier (private).
+- **Store format.** This version stores version-1 documents. The next version
+  migrates them to version 2, and a downgrade cannot read a migrated store.
+
+Known issues:
+
+1. An Alert is lost when the recipient's model errors. It shows as unanswered. Pi
+   Team Bright retries it; this package does not.
+2. `team_sync` can replay pages that an earlier call released. Act only on
+   `task_read`, and never call `team_sync` from a nested tool call.
+3. Interrupt: a Worker can interrupt the lead, the run to stop is chosen when the
+   Alert is accepted, and the abort has no settle bound.
+4. An Alert can be admitted after its recipient is closed or fenced. After an owner
+   Close, a busy Worker can still run one tool call.
+
+## Install
+
+```sh
+npm install @hypercarrier/pi-team-durable@next
+```
+
+The package ships compiled JavaScript and type declarations under `dist`.
+Node 22.19 or newer. Install the three pinned peers beside it.
+
+## API
+
+`./authority` exports the runtime factory, authority documents, observation
+observer, and structural stop ports. A host adapter registers this runtime.
+
+- `ptb.team`, `ptb.graph`, `ptb.journal`, `ptb.outbox`, and `ptb.receipts` store
+  authority, graph history, recent events, delivery obligations, and replay results.
+  Each accepted command and its mechanics commit together.
+- Nine lead tools and three Worker tools use the rc.7 contract. Exact conversation
+  and generation bindings guard authority. A fork does not acquire an existing
+  Team's lead authority.
+- `ptb.worker-anchor` owns a Worker conversation and renews a durable sleep.
+  Lead Esc does not end it. Stops use stored target IDs through the node's single
+  mark-before-resume fence. Failed confirmation retains the intent.
+- `ptb.deliver` rechecks an obligation, submits with a stable request ID, records
+  admission, and waits for settlement. Notices use `team.notice` entries whose
+  data (`TeamNoticeData`) names the delivery kind and its sender: an Alert's
+  author, or `team-lead` for Tasks and stops. An interrupt Alert's data also
+  has `interrupt: true`. A reader names a notice from this data, never from its
+  text.
+  Interrupt Alerts persist the recipient run ID at acceptance. A separate phase
+  asks the host `abortRun` port to stop that exact run, then checkpoints before
+  normal admission. Queue identities stay native; no input is re-queued.
+  A failed interruption appears as unproved in the notice. Retry never selects
+  a replacement run. The node supplies a cancellable wait outside its admission lock.
+- `ptb.notify` reserves an automatic page before admission. A failed lead input
+  pauses notification. Explicit sync or a new owner input resumes it.
+- `team_sync` reserves successive bounded pages. It never waits for consumption.
+  The final request hook records exact page visibility. A later observer requires
+  a matching persisted native assistant entry and successful input settlement
+  before it advances the cursor. Compaction and failed runs release unseen pages.
+- The journal keeps 100 recent events in its document and immutable `ptb.event`
+  entries in native storage. This bound does not cover graph history, receipts,
+  outbox, observation proofs, or storage history.
+
+The host injects model roles: a static `modelRoles` list, or a `catalog(tx,
+lead)` resolver that gives each lead its own roles and default. The AmPi
+node's `default` role captures the authoritative lead model at each Worker
+generation. Unknown roles return a typed refusal.
+The package never reads Pi configuration. The observation commit port resolves
+its store for every hook; a registry can serve multiple stores.
+
+The executable contract snapshot comes from Pi Team Bright 0.24.0-rc.7 at
+`382950ce62bd38b6cd9f7fb80b91ef5b9140e15a` (unreleased Alert interrupt support).
+`scripts/rc7-contract.mjs` records source hashes. Pi Team Bright 0.25.1 is the
+contract pin: it ships the same source files, and a test compares their SHA-256
+values with the recorded ones. The tests regenerate the contract from the
+installed devDependency `@hypercarrier/pi-team-bright@0.25.1`.
+
+```sh
+npm ci
+npm test
+```
+
+Fast tests use MemoryStorage, a fixed clock, inert timers, and faux responses.
+The SIGKILL crash-recovery suite and `bench/e2e.ts` stay in HyperCarrier (private).
+They use the AmPi node's subprocess carrier. This repository's tests do not
+cover crash recovery.
+
+The C1 delivery hold remains unported. pi-durable places steers and follow-ups at
+turn boundaries. A stale admitted notice cannot grant authority: Task version and
+Worker generation checks still apply.
+
+## Development
+
+`npm run build` emits `dist`; `npm install` runs it through `prepare`.
+`npm run typecheck`, `npm test` and `npm run verify:package` are the CI checks.
+See [releasing](docs/maintainers/releasing.md) for the release procedure.
+
+## Provenance
+
+Extracted from HyperCarrier (private) at the certified port, renamed from
+`durable-team`, without its history.

package/dist/authority/anchor.d.ts

@@ -0,0 +1,10 @@
+import { type ConversationId, type TaskId, type Tx } from '@earendil-works/pi-durable';
+export declare const ANCHOR_SLEEP_MS: number;
+export declare const WorkerAnchor: import("@earendil-works/pi-durable").Task<null, {
+    phase: "hold";
+}, null, object>;
+/** The caller commits this binding with Membership in the same transaction. */
+export declare function createAnchoredConversation(tx: Tx, lead: ConversationId): Promise<{
+    conversationId: ConversationId;
+    anchorId: TaskId;
+}>;

package/dist/authority/anchor.js

@@ -0,0 +1,19 @@
+import { defineTask } from '@earendil-works/pi-durable';
+// A live background root owns the Worker conversation. A terminal placeholder
+// cannot be an abort boundary because abortTask returns early for terminal tasks.
+export const ANCHOR_SLEEP_MS = 24 * 60 * 60 * 1000;
+export const WorkerAnchor = defineTask({
+    name: 'ptb.worker-anchor', version: 1, initial: () => ({ phase: 'hold' }),
+    phases: { hold: async (_task, runtime, context) => {
+            await runtime.sleepUntil(runtime.now() + ANCHOR_SLEEP_MS, { phase: 'hold' }, context);
+        } },
+    abort: async (_task, runtime, context) => {
+        await runtime.commit(() => ({ status: 'terminal', outcome: { status: 'aborted' } }), context);
+    },
+});
+/** The caller commits this binding with Membership in the same transaction. */
+export async function createAnchoredConversation(tx, lead) {
+    const anchorId = await tx.createTask(WorkerAnchor, null, { conversationId: lead, ownership: { kind: 'conversation' }, background: true, abandonOnRestart: false });
+    const conversation = await tx.createConversation({ ownership: { kind: 'task', taskId: anchorId } });
+    return { conversationId: conversation.id, anchorId };
+}

package/dist/authority/card-types.d.ts

@@ -0,0 +1,152 @@
+import { Type, type Static } from "typebox";
+export declare const GraphVersionRefSchema: Type.TString;
+export declare const GraphTaskTransitionSchema: Type.TEnum<["claim", "block", "resume", "goal_achieved", "goal_failed", "cancel"]>;
+export declare const GraphFailureEdgeSchema: Type.TObject<{
+    target: Type.TString;
+    max_traversals: Type.TInteger;
+}>;
+export declare const GraphTaskStateSchema: Type.TUnion<[Type.TObject<{
+    kind: Type.TLiteral<"dependency_waiting">;
+    prerequisite_task_ids: Type.TArray<Type.TString>;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"ready">;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"in_progress">;
+    attempt_id: Type.TString;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"blocked">;
+    attempt_id: Type.TString;
+    evidence: Type.TString;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"goal_achieved">;
+    attempt_id: Type.TString;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"goal_failed">;
+    reason: Type.TLiteral<"criterion_failed">;
+    attempt_id: Type.TString;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"goal_failed">;
+    reason: Type.TLiteral<"failure_edge_exhausted">;
+    attempt_id: Type.TString;
+    target_task_id: Type.TString;
+    traversals: Type.TInteger;
+    exhaustion_reason: Type.TEnum<["limit_reached", "target_cancelled"]>;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"goal_failed">;
+    reason: Type.TEnum<["dependency_failed", "dependency_cancelled"]>;
+    prerequisite_task_ids: Type.TArray<Type.TString>;
+}>, Type.TObject<{
+    kind: Type.TLiteral<"cancelled">;
+    reason: Type.TString;
+}>]>;
+export declare const GraphAttemptSummarySchema: Type.TObject<{
+    id: Type.TString;
+    ordinal: Type.TInteger;
+    input_attempt_ids: Type.TRecord<"^.*$", Type.TString>;
+}>;
+/** Canonical graph-native Task card used by tools, delivery, and Coordination. */
+export declare const GraphTaskCardSchema: Type.TObject<{
+    id: Type.TString;
+    title: Type.TString;
+    goal: Type.TString;
+    assignee: Type.TString;
+    needs: Type.TArray<Type.TString>;
+    on_goal_failed: Type.TOptional<Type.TObject<{
+        target: Type.TString;
+        max_traversals: Type.TInteger;
+    }>>;
+    status: Type.TEnum<["dependency_waiting", "ready", "in_progress", "blocked", "goal_failed", "goal_achieved", "cancelled"]>;
+    state: Type.TUnion<[Type.TObject<{
+        kind: Type.TLiteral<"dependency_waiting">;
+        prerequisite_task_ids: Type.TArray<Type.TString>;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"ready">;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"in_progress">;
+        attempt_id: Type.TString;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"blocked">;
+        attempt_id: Type.TString;
+        evidence: Type.TString;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"goal_achieved">;
+        attempt_id: Type.TString;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"goal_failed">;
+        reason: Type.TLiteral<"criterion_failed">;
+        attempt_id: Type.TString;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"goal_failed">;
+        reason: Type.TLiteral<"failure_edge_exhausted">;
+        attempt_id: Type.TString;
+        target_task_id: Type.TString;
+        traversals: Type.TInteger;
+        exhaustion_reason: Type.TEnum<["limit_reached", "target_cancelled"]>;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"goal_failed">;
+        reason: Type.TEnum<["dependency_failed", "dependency_cancelled"]>;
+        prerequisite_task_ids: Type.TArray<Type.TString>;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"cancelled">;
+        reason: Type.TString;
+    }>]>;
+    current_context: Type.TString;
+    version: Type.TString;
+    activation_key: Type.TOptional<Type.TString>;
+    accepted_attempt_id: Type.TOptional<Type.TString>;
+    current_attempt: Type.TOptional<Type.TObject<{
+        id: Type.TString;
+        ordinal: Type.TInteger;
+        input_attempt_ids: Type.TRecord<"^.*$", Type.TString>;
+    }>>;
+    attempts_started: Type.TInteger;
+    relations: Type.TOptional<Type.TArray<Type.TObject<{
+        relation: Type.TEnum<["blocked_by", "parent", "related"]>;
+        target_task_id: Type.TString;
+    }>>>;
+    dependency_state: Type.TOptional<Type.TUnion<[Type.TObject<{
+        kind: Type.TLiteral<"ready">;
+        active_blocker_ids: Type.TArray<Type.TString>;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"waiting">;
+        active_blocker_ids: Type.TArray<Type.TString>;
+    }>, Type.TObject<{
+        kind: Type.TLiteral<"terminal">;
+        active_blocker_ids: Type.TArray<Type.TString>;
+    }>]>>;
+    projection_warnings: Type.TOptional<Type.TArray<Type.TObject<{
+        task_id: Type.TString;
+        truncated_fields: Type.TArray<Type.TEnum<["title", "goal", "current_context"]>>;
+        incomplete_fields: Type.TArray<Type.TEnum<["title", "goal", "current_context"]>>;
+        message: Type.TString;
+    }>>>;
+}>;
+/** Breaking replacement for task_create. It applies one complete graph revision. */
+export declare const TaskGraphApplyParametersSchema: Type.TObject<{
+    operation_id: Type.TString;
+    expected_graph_version: Type.TOptional<Type.TString>;
+    tasks: Type.TArray<Type.TObject<{
+        key: Type.TString;
+        title: Type.TString;
+        goal: Type.TString;
+        assignee: Type.TString;
+        needs: Type.TOptional<Type.TArray<Type.TString>>;
+        on_goal_failed: Type.TOptional<Type.TObject<{
+            target: Type.TString;
+            max_traversals: Type.TInteger;
+        }>>;
+    }>>;
+}>;
+/** One graph-native Task command. Waiting and ready are derived, never authored. */
+export declare const GraphTaskUpdateParametersSchema: Type.TObject<{
+    task_id: Type.TString;
+    operation_id: Type.TString;
+    expected_version: Type.TString;
+    transition: Type.TOptional<Type.TEnum<["claim", "block", "resume", "goal_achieved", "goal_failed", "cancel"]>>;
+    current_context: Type.TOptional<Type.TString>;
+    evidence: Type.TOptional<Type.TString>;
+}>;
+export type GraphTaskCard = Static<typeof GraphTaskCardSchema>;
+export type GraphTaskStateCard = Static<typeof GraphTaskStateSchema>;
+export type TaskGraphApplyParameters = Static<typeof TaskGraphApplyParametersSchema>;
+export type GraphTaskUpdateParameters = Static<typeof GraphTaskUpdateParametersSchema>;

package/dist/authority/card-types.js

@@ -0,0 +1,123 @@
+// Ported from Pi Team Bright 0.24.0-rc.4 src/task-authority/graph-control-schemas.ts (MIT). Limits inlined.
+import { Type } from "typebox";
+import { TaskVersionRefSchema } from "./limits.js";
+import { TASK_CARD_GOAL_MAX_LENGTH } from "./limits.js";
+import { TASK_CARD_CONTEXT_MAX_LENGTH, TASK_CARD_TITLE_MAX_LENGTH, TASK_ID_MAX_LENGTH } from "./limits.js";
+const TaskId = Type.String({ minLength: 1, maxLength: TASK_ID_MAX_LENGTH });
+const TaskKey = Type.String({ minLength: 1, maxLength: 64, pattern: "^[A-Za-z0-9_-]+$" });
+const WorkerName = Type.String({ minLength: 1, maxLength: 64 });
+const OperationId = Type.String({ minLength: 1, maxLength: 128 });
+export const GraphVersionRefSchema = Type.String({ pattern: "^g_[0-9a-f]{16}$", minLength: 18, maxLength: 18 });
+export const GraphTaskTransitionSchema = Type.Enum(["claim", "block", "resume", "goal_achieved", "goal_failed", "cancel"]);
+export const GraphFailureEdgeSchema = Type.Object({
+    target: TaskKey,
+    max_traversals: Type.Integer({ minimum: 1, maximum: 8 }),
+}, { additionalProperties: false });
+export const GraphTaskStateSchema = Type.Union([
+    Type.Object({
+        kind: Type.Literal("dependency_waiting"),
+        prerequisite_task_ids: Type.Array(TaskId, { minItems: 1 }),
+    }, { additionalProperties: false }),
+    Type.Object({ kind: Type.Literal("ready") }, { additionalProperties: false }),
+    Type.Object({ kind: Type.Literal("in_progress"), attempt_id: Type.String({ minLength: 1 }) }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("blocked"),
+        attempt_id: Type.String({ minLength: 1 }),
+        evidence: Type.String({ minLength: 1 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("goal_achieved"),
+        attempt_id: Type.String({ minLength: 1 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("goal_failed"),
+        reason: Type.Literal("criterion_failed"),
+        attempt_id: Type.String({ minLength: 1 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("goal_failed"),
+        reason: Type.Literal("failure_edge_exhausted"),
+        attempt_id: Type.String({ minLength: 1 }),
+        target_task_id: TaskId,
+        traversals: Type.Integer({ minimum: 0 }),
+        exhaustion_reason: Type.Enum(["limit_reached", "target_cancelled"]),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("goal_failed"),
+        reason: Type.Enum(["dependency_failed", "dependency_cancelled"]),
+        prerequisite_task_ids: Type.Array(TaskId, { minItems: 1 }),
+    }, { additionalProperties: false }),
+    Type.Object({
+        kind: Type.Literal("cancelled"),
+        reason: Type.String({ minLength: 1 }),
+    }, { additionalProperties: false }),
+]);
+export const GraphAttemptSummarySchema = Type.Object({
+    id: Type.String({ minLength: 1 }),
+    ordinal: Type.Integer({ minimum: 1 }),
+    input_attempt_ids: Type.Record(TaskId, Type.String({ minLength: 1 })),
+}, { additionalProperties: false });
+/** Canonical graph-native Task card used by tools, delivery, and Coordination. */
+export const GraphTaskCardSchema = Type.Object({
+    id: TaskId,
+    title: Type.String({ minLength: 1, maxLength: TASK_CARD_TITLE_MAX_LENGTH }),
+    goal: Type.String({ minLength: 1, maxLength: TASK_CARD_GOAL_MAX_LENGTH }),
+    assignee: WorkerName,
+    needs: Type.Array(TaskId),
+    on_goal_failed: Type.Optional(GraphFailureEdgeSchema),
+    status: Type.Enum(["dependency_waiting", "ready", "in_progress", "blocked", "goal_failed", "goal_achieved", "cancelled"]),
+    state: GraphTaskStateSchema,
+    current_context: Type.String({ minLength: 1, maxLength: TASK_CARD_CONTEXT_MAX_LENGTH }),
+    version: TaskVersionRefSchema,
+    activation_key: Type.Optional(Type.String({ minLength: 1 })),
+    accepted_attempt_id: Type.Optional(Type.String({ minLength: 1 })),
+    current_attempt: Type.Optional(GraphAttemptSummarySchema),
+    attempts_started: Type.Integer({ minimum: 0 }),
+    // Optional compatibility coordinates let generic read-only consumers accept
+    // both legacy and graph-native cards without making them graph authority.
+    relations: Type.Optional(Type.Array(Type.Object({
+        relation: Type.Enum(["blocked_by", "parent", "related"]),
+        target_task_id: TaskId,
+    }, { additionalProperties: false }))),
+    dependency_state: Type.Optional(Type.Union([
+        Type.Object({ kind: Type.Literal("ready"), active_blocker_ids: Type.Array(TaskId, { maxItems: 0 }) }, { additionalProperties: false }),
+        Type.Object({ kind: Type.Literal("waiting"), active_blocker_ids: Type.Array(TaskId, { minItems: 1 }) }, { additionalProperties: false }),
+        Type.Object({ kind: Type.Literal("terminal"), active_blocker_ids: Type.Array(TaskId) }, { additionalProperties: false }),
+    ])),
+    projection_warnings: Type.Optional(Type.Array(Type.Object({
+        task_id: TaskId,
+        truncated_fields: Type.Array(Type.Enum(["title", "goal", "current_context"])),
+        incomplete_fields: Type.Array(Type.Enum(["title", "goal", "current_context"])),
+        message: Type.String({ minLength: 1 }),
+    }, { additionalProperties: false }))),
+}, { additionalProperties: false });
+const GraphTaskItemSchema = Type.Object({
+    key: TaskKey,
+    title: Type.String({ minLength: 1, maxLength: TASK_CARD_TITLE_MAX_LENGTH }),
+    goal: Type.String({ minLength: 1, maxLength: TASK_CARD_GOAL_MAX_LENGTH, description: "Desired outcome and external success signal." }),
+    assignee: WorkerName,
+    needs: Type.Optional(Type.Array(TaskKey, { uniqueItems: true })),
+    on_goal_failed: Type.Optional(GraphFailureEdgeSchema),
+}, { additionalProperties: false });
+/** Breaking replacement for task_create. It applies one complete graph revision. */
+export const TaskGraphApplyParametersSchema = Type.Object({
+    operation_id: OperationId,
+    expected_graph_version: Type.Optional(GraphVersionRefSchema),
+    tasks: Type.Array(GraphTaskItemSchema, { minItems: 1 }),
+}, {
+    additionalProperties: false,
+    description: "Atomically apply the complete assigned Task graph. Omit expected_graph_version only for its first revision.",
+});
+/** One graph-native Task command. Waiting and ready are derived, never authored. */
+export const GraphTaskUpdateParametersSchema = Type.Object({
+    task_id: TaskId,
+    operation_id: OperationId,
+    expected_version: TaskVersionRefSchema,
+    transition: Type.Optional(GraphTaskTransitionSchema),
+    current_context: Type.Optional(Type.String({ minLength: 1, maxLength: TASK_CARD_CONTEXT_MAX_LENGTH })),
+    evidence: Type.Optional(Type.String({ minLength: 1 })),
+}, {
+    additionalProperties: false,
+    minProperties: 4,
+    description: "Apply one explicit Task transition or record current context. dependency_waiting and ready cannot be authored.",
+});

package/dist/authority/contracts.d.ts

@@ -0,0 +1,12 @@
+import type { TSchema } from 'typebox';
+import type { Result } from './state.ts';
+export declare const TOOL_NAMES: readonly ["team_create", "team_sync", "ensure_worker", "task_graph_apply", "task_read", "task_update", "worker_stop", "team_shutdown", "alert_send"];
+export type ToolName = typeof TOOL_NAMES[number];
+export type Role = 'lead' | 'worker';
+export interface Contract {
+    lead: Record<ToolName, TSchema>;
+    worker: Partial<Record<ToolName, TSchema>>;
+    results: Record<ToolName, TSchema>;
+}
+export declare function contracts(goalMaxLength?: number): Contract;
+export declare function checkResult(contract: Contract, name: ToolName, value: Result): Result;

package/dist/authority/contracts.js

@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs';
+import { Check } from 'typebox/value';
+export const TOOL_NAMES = ['team_create', 'team_sync', 'ensure_worker', 'task_graph_apply', 'task_read', 'task_update', 'worker_stop', 'team_shutdown', 'alert_send'];
+// Generated from the pinned executable rc.7 contract, not the stale agent surface.
+const source = JSON.parse(readFileSync(new URL('./rc7-contract.json', import.meta.url), 'utf8'));
+export function contracts(goalMaxLength = 1600) {
+    if (!Number.isSafeInteger(goalMaxLength) || goalMaxLength < 1)
+        throw new Error('goalMaxLength must be a positive safe integer');
+    const copy = structuredClone(source);
+    function patch(value) {
+        if (!value || typeof value !== 'object')
+            return;
+        const node = value;
+        if (node.properties && typeof node.properties === 'object') {
+            const goal = node.properties.goal;
+            if (goal && typeof goal === 'object')
+                goal.maxLength = goalMaxLength;
+        }
+        for (const child of Object.values(node))
+            patch(child);
+    }
+    patch(copy);
+    return copy;
+}
+export function checkResult(contract, name, value) {
+    if (!Check(contract.results[name], value))
+        throw new Error(`PTB ${name} produced a result outside the rc.7 contract: ${JSON.stringify(value)}`);
+    return value;
+}

package/dist/authority/delivery.d.ts

@@ -0,0 +1,59 @@
+import type { AbortRun, InterruptTarget } from './interrupt.ts';
+import { type SubmissionId, type Tx } from '@earendil-works/pi-durable';
+import { type State, type Obligation } from './state.ts';
+/** `kind` and `sender` name the delivery in its queue entry; inputs persisted before they existed lack them. */
+export interface DeliveryInput extends InterruptTarget {
+    interrupt?: true;
+    epoch: string;
+    content: string;
+    whenBusy: 'steer' | 'followUp';
+    kind?: Obligation['kind'];
+    sender?: string;
+}
+/**
+ * The structured data of a Team input's `team.notice` entry. A reader names the input from these fields, never from
+ * its text: `delivery` is the kind (`update` for a notifier page), `sender` the author, at most SENDER_LIMIT characters.
+ * `interrupt` marks an Alert sent to interrupt the recipient's run; the interruption outcome stays in the model-facing content.
+ * Entries written before `delivery` existed carry only `source` and `deliveryId` or `pageId`.
+ */
+export type TeamNoticeData = {
+    source: 'team';
+    epoch: string;
+    deliveryId?: string;
+    pageId?: string;
+    delivery?: Obligation['kind'] | 'update';
+    sender?: string;
+    interrupt?: true;
+};
+export declare const SENDER_LIMIT = 64;
+export declare function eligible(s: State, o: Obligation): boolean;
+export declare function deliveryInput(s: State, o: Obligation): DeliveryInput;
+/** The input a delivery submits. The request ID names the Obligation, so a retry reacquires the same admission. */
+export declare function deliveryDraft(input: DeliveryInput, interruption?: Obligation['interruption']): {
+    type: "input";
+    content: string;
+    whenBusy: "steer" | "followUp";
+    requestId: string;
+    entry: {
+        kind: string;
+        data: TeamNoticeData;
+    };
+};
+export declare const Deliver: import("@earendil-works/pi-durable").Task<DeliveryInput, {
+    phase: "interrupt";
+} | {
+    phase: "submit";
+} | {
+    phase: "settle";
+    submissionId: SubmissionId;
+}, null, object>;
+/** Keep the shared submit/settle mechanics; only the host-owned interruption needs a port. */
+export declare function createDeliver(abortRun: AbortRun): import("@earendil-works/pi-durable").Task<DeliveryInput, {
+    phase: "interrupt";
+} | {
+    phase: "submit";
+} | {
+    phase: "settle";
+    submissionId: SubmissionId;
+}, null, object>;
+export declare function scheduleDeliveries(tx: Tx, s: State, delivery: typeof Deliver): Promise<void>;