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

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,210 @@
-# 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 and a 100-seed differential oracle run.
+  Run 500 or more seeds by hand before a release.
+  The SIGKILL crash suite and `bench/e2e.ts` stay in HyperCarrier (private).
+- **Before deploy.** The first open migrates the store to the indexed format. The
+  migration is one-way: rollback means restoring a backup. Back up the store, and
+  stop every older node process first. 0.1.0-rc.1 stores version-1 documents.
+  This 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.
+
+`./testing` exports named internals for a host's own tests. It is unstable test support:
+its names can change in any release. Production code imports `./authority` only.
+
+## API
+
+`./authority` exports the runtime factory, authority documents, observation
+observer, and structural stop ports. A host adapter registers this runtime.
+
+- `ptb.team` owns membership and lifecycle. `ptb.head` holds current graph
+  coordinates, readiness, occupancy, attention, and bounded recent references.
+  Task family members hold current facts, retained Attempts, cards, and operator
+  projections. Immutable graph indexes hold topology. Worker indexes hold
+  nonterminal Task IDs. Each changed document is stored as a base.
+- A controller-only conversation holds graph revision diffs and controller
+  events. Commands restore the incremental engine from current Task records.
+  They commit changed facts, indexes, receipts, obligations, and history together.
+- Operation receipts retain exact result strings per epoch. Native tool-call
+  receipts use task scope and retire with the tool. Direct callers use permanent
+  family members. Obligations retain their identity after settlement; bounded
+  hash partitions index pending and unscheduled keys.
+- 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 head keeps references to 100 recent journal events. Their immutable
+  `ptb.event` entries stay in the lead conversation, so sync page boundaries stay
+  unchanged.
+- Observation indexes, page metadata, immutable page bodies, and open proofs
+  use separate base-checkpointed documents. Requests check active pages from
+  the newest message backward. They do not hash transcript history.
+- The observer retires a proof after its run settles and it processes the
+  evidence. It retires a page body only when the page is acknowledged or
+  replaced and the contiguous cursor covers it. Unsettled proofs and notifier
+  submit/settle checkpoints keep referenced bodies. Unknown notifier ownership
+  keeps the body. Page metadata and the exact replay receipts remain.
+- `observations(tx)` and `observationStats(tx)` are diagnostic readers. The
+  latter reports current-record counts and UTF-8 JSON bytes. Production hooks
+  and the observer read current indexes.
+- `/ptb` reads one acknowledged scan anchor for the current epoch. This anchor
+  differs from the runtime reservation anchor in `scanByEpoch`. Cursor advance
+  folds eligible waiting-page anchors before removing their waiting entries.
+  Body retirement retains the anchor; epoch change removes it.
+- `readTeamPanel` reads current Task projections and recent records.
+  `readTeamSummary` reads head indexes. `state.open()` is a full-history diagnostic
+  adapter; runtime paths do not use it.
+
+The first authority open migrates rc.7 documents in one transaction. It checks
+current facts against the reference controller and writes the new records and
+log. The same transaction raises all six shared PTB document kinds to version 2:
+`ptb.team`, `ptb.graph`, `ptb.journal`, `ptb.outbox`, `ptb.receipts`, and
+`ptb.observation`. `ptb.team` keeps its data. The other five retain only
+`{fence:"ptb-authority-v2"}`. Current commands use the new authority records.
+These occupied addresses prevent old code from creating fresh version-1
+documents. pi-durable rejects old typed reads before mutation. Fresh stores
+receive the same fence. Native pi-durable documents keep their own versions.
+
+A migrated operation receipt receives its original projection check on its
+first replay. Downgrade is not supported.
+
+The fence covers stopped and reopened stores, not an old process that is still
+running. Before the first open with this build, stop every node process that
+runs older code, and back up the whole store directory. To roll back, restore
+that backup and run the older build on it. A rollback discards all Team work
+accepted after the migration.
+
+Known hazard until the next contract change: `team_sync` can replay a stale
+page. This occurred with a direct snapshot call as well as nested calls. Leads
+use `task_read` for any Task state they act on. A direct `team_sync` call does
+not establish current Task state.
+
+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`.
+
+Each role's tool labels and descriptions come from Pi Team Bright's own
+registration. `scripts/pi-registration.mjs` captures it per role through an
+inert host. The parity test compares every durable tool with the installed
+`@hypercarrier/pi-team-bright`. Known gap: Pi's Worker `alert_send` requires
+non-empty `text` and `task_id`; the durable schema does not yet.
+
+```sh
+npm ci
+npm test
+```
+
+The hardening oracle freezes `src/authority` at
+certified P, the 0.1.0-rc.1 port, in `test/oracle/authority`.
+Do not update that copy when optimizing the runtime. The seeded differential
+harness compares exact tool results or error messages, all public Task cards,
+and created `ptb.deliver` inputs after every command. Each runtime has its own
+MemoryStorage Harness. Both schedulers stay paused. The stop port returns fake
+settlement. A synthetic persisted lead run permits snapshot and update reads.
+Delivery execution and observation acknowledgement have separate tests.
+
+```sh
+# From the repository root: N seeds over K processes (defaults: 500 and 4).
+npm run test:oracle -- --seeds 500 --shards 4
+# Replay one failing seed. Failures print its full command trace.
+npm run test:oracle -- --seed 42 --seeds 1 --shards 1
+# Run only the deterministic boundary cases.
+npm run test:oracle -- --targeted-only
+```
+
+Each seed runs about 70 commands over at most seven Tasks. It combines a fixed
+lifecycle and transition prefix with 30 random commands, then starts a new Team
+epoch. Use `--steps` to change the random command count. A separate deterministic
+sequence covers prerequisite repair, superseded dependents, removed and
+reintroduced keys, stale lineage, blocked Worker capacity, reorder-only
+restatement, and stop notices after Worker reconnection. The normal Vitest suite
+runs these cases and three smoke seeds. This oracle detects behavior drift from the frozen
+runtime; it does not prove that the frozen behavior is correct.
+
+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,19 @@
+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';
+/** The label and description Pi Team Bright registers for one role's tool. */
+export interface ToolPresentation {
+    label: string;
+    description: string;
+}
+export interface Contract {
+    lead: Record<ToolName, TSchema>;
+    worker: Partial<Record<ToolName, TSchema>>;
+    results: Record<ToolName, TSchema>;
+    presentation: Record<Role, Partial<Record<ToolName, ToolPresentation>>>;
+}
+export declare function checkSchema(schema: TSchema, value: unknown): boolean;
+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,45 @@
+import { readFileSync } from 'node:fs';
+import { Compile } from 'typebox/compile';
+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 = readFileSync(new URL('./rc7-contract.json', import.meta.url), 'utf8');
+const patchedContracts = new Map();
+const validators = new Map();
+export function checkSchema(schema, value) {
+    const key = JSON.stringify(schema, (_key, value) => value && typeof value === 'object' && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : value);
+    let validator = validators.get(key);
+    if (!validator) {
+        validator = Compile(JSON.parse(key));
+        validators.set(key, validator);
+    }
+    return validator.Check(value);
+}
+export function contracts(goalMaxLength = 1600) {
+    if (!Number.isSafeInteger(goalMaxLength) || goalMaxLength < 1)
+        throw new Error('goalMaxLength must be a positive safe integer');
+    const cached = patchedContracts.get(goalMaxLength);
+    if (cached !== undefined)
+        return JSON.parse(cached);
+    const copy = JSON.parse(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);
+    patchedContracts.set(goalMaxLength, JSON.stringify(copy));
+    return copy;
+}
+export function checkResult(contract, name, value) {
+    if (!checkSchema(contract.results[name], value))
+        throw new Error(`PTB ${name} produced a result outside the rc.7 contract: ${JSON.stringify(value)}`);
+    return value;
+}