# Pi Team Bright contract source map

Pi Team Bright is in hardening. Exact contract truth therefore lives in executable
types, schemas, implementations, and tests rather than a second prose copy.
This page is a one-hop map to those sources; it is intentionally not an
exhaustive parameter reference.

## Public agent interface

- The DAG-native leader surface is the nine-tool catalog in
  [`src/model-tool-contract/catalog.ts`](../src/model-tool-contract/catalog.ts),
  registered by [`pi-registration.ts`](../src/model-tool-contract/pi-registration.ts).
  [`ProjectedTool`](../src/model-tool-contract/result-projection.ts)
  and [`tui-projection.ts`](../src/model-tool-contract/tui-projection.ts) own
  the model result and TUI projection boundaries.
- [`extensions/index.ts`](../extensions/index.ts) owns each tool's TypeBox
  parameter schema, agent-facing description, authorization, execution, and
  semantic result content.
- [`skills/pi-team-bright/SKILL.md`](../skills/pi-team-bright/SKILL.md) is operating
  procedure, not another schema. Pi presents the executable tool schemas to the
  agent directly.
- [`src/utils/tool-surface.test.ts`](https://github.com/deephbz/pi-team-bright/blob/main/src/utils/tool-surface.test.ts)
  verifies the nine-tool selection and the irreducible Task, Worker, sync, and
  Alert distinctions.

## Team synchronization

- [`observation-service.ts`](../src/coordination/observation-service.ts) owns
  immediate observation, Task reconciliation, and bounded in-memory reservation.
  [`branch-observation.ts`](../src/coordination/branch-observation.ts) derives the
  cursor from the selected native branch.
- [`sync-nudge-conductor.ts`](../src/utils/sync-nudge-conductor.ts) owns batch
  scheduling. [`sync-liveness-settings.ts`](../src/utils/sync-liveness-settings.ts)
  resolves its global policy and deprecated setting fallbacks.
- [`pi-team-session-adapter.ts`](../extensions/pi-team-session-adapter.ts) owns
  `/ptb sync` and automatic delivery.
  [`team-update.ts`](../extensions/team-update.ts) publishes native
  `ptb.team-update` messages only while the Session is idle.
- [Decision 0016](decisions/0016-framework-team-synchronization.md) records intent.
  The [work record](projects/team-sync-continuity.md) records real Pi evidence.

## Delivery around compaction

- [`compaction-delivery-gate.ts`](../extensions/compaction-delivery-gate.ts)
  holds every Pi Team Bright model message while the Pi Session compacts.
  The Session adapter routes Task, Alert, team_sync, and doctor sends through it.
- [`compaction-delivery-adapter.test.ts`](../extensions/compaction-delivery-adapter.test.ts)
  checks the adapter hooks. `npm run e2e:compaction-delivery` runs a real Pi
  Team through manual compaction; `PI_TEAM_SYNC_TEST_PI_CLI` selects the Pi CLI.

## Read-only status diagnosis

- [`src/utils/team-status.ts`](../src/utils/team-status.ts) owns the `pi-teams-status/1` read-only TeamConfig/graph diagnostic model and human projection.
- [`pi-team-session-adapter.ts`](../extensions/pi-team-session-adapter.ts) registers `/ptb`; the command grammar lives in [`ptb-command.ts`](../src/utils/ptb-command.ts).

## Read-only Task views

- [`source.ts`](../src/task-graph-view/source.ts) validates the shared Task view
  source and projects recorded Attempt intervals from graph authority events.
- [`component.ts`](../src/task-graph-view/component.ts) owns the DAG/Timeline
  toggle and shared Task selection. [`layout.ts`](../src/task-graph-view/layout.ts)
  renders dependencies; [`timeline.ts`](../src/task-graph-view/timeline.ts)
  renders elapsed Attempt time.
- [`graph-control.ts`](../src/task-authority/graph-control.ts) owns recorded
  transition times. Team journal publication times remain observed activity.

## Result and projection contract

- [`result-projection.ts`](../src/model-tool-contract/result-projection.ts)
  validates raw semantic results, derives the schema-checked model projection,
  and assembles raw machine details with serialized model content.
- [`tui-projection.ts`](../src/model-tool-contract/tui-projection.ts) produces
  exhaustive collapsed and expanded allowlisted human projections.
- QA retains raw semantic details, model content, and both TUI modes. Operational
  trace records remain payload-free.

## Domain and authority

- [`src/team-authority/contracts.ts`](../src/team-authority/contracts.ts) owns
  Team and Membership types. [`src/coordination/contracts.ts`](../src/coordination/contracts.ts)
  owns event types. [`src/alert-authority/contracts.ts`](../src/alert-authority/contracts.ts)
  and [`delivery-contracts.ts`](../src/alert-authority/delivery-contracts.ts) own
  Alert and inbox contracts.
- [`@hypercarrier/pi-team-bright/observation`](../src/public/observation.ts) exports the one
  read-only `pi-teams-observation/1` projector, canonical types, and JSON
  Schema; its authority and privacy boundary are enforced by that executable
  contract. The same entry point exports `readTaskSnapshot` from
  [`tasks.ts`](../src/public/tasks.ts): read-only cards, dependencies, and the
  authoritative ready frontier, without runtime or delivery effects.
- [`src/utils/teams.ts`](../src/utils/teams.ts) owns Team configuration and
  current Membership generations.
- [`src/utils/automatic-summary-policy.ts`](../src/utils/automatic-summary-policy.ts)
  answers only Rarebit's versioned automatic-Summary inhibition query, using
  the exact current teammate Membership-generation and durable-Session resolver
  in `teams.ts`; it exposes no general policy registry.
- [`src/task-authority/task-domain.ts`](../src/task-authority/task-domain.ts)
  owns bounded Task card schemas and historical native-record decoding.
  [`task-version-ref.ts`](../src/task-authority/task-version-ref.ts) owns opaque
  public TaskVersionRef values.
- [`src/task-authority/graph-control.ts`](../src/task-authority/graph-control.ts)
  owns graph revisions, derived state, immutable Attempts, bounded failure
  traversal, replay, recovery, and trace output. Its TypeBox public contract is
  [`graph-control-schemas.ts`](../src/task-authority/graph-control-schemas.ts).
  [`durable-graph-task-authority.ts`](../src/adapters/durable-graph-task-authority.ts)
  owns the Team-scoped snapshot, while
  [`graph-orchestration.ts`](../src/task-authority/graph-orchestration.ts) owns
  publication and ready delivery. Graph authority initializes new Teams with
  an explicit empty snapshot and refuses missing or corrupt established stores.
- [`publication.ts`](../src/task-authority/publication.ts)
  owns Task mutation publication contracts.
  [`durable-task-mutation-publication.ts`](../src/adapters/durable-task-mutation-publication.ts)
  implements the Coordination and delivery bridge.
  [`graph-recovery-records.test.ts`](../src/task-authority/graph-recovery-records.test.ts)
  checks graph-owned startup recovery and exact recipient fences.
- [`src/coordination/event-journal.ts`](../src/coordination/event-journal.ts) owns cursor ordering,
  waits, filters, bounded pages, and snapshot continuations.
- [`src/utils/worker-resource-projection.ts`](../src/utils/worker-resource-projection.ts)
  owns Worker-only prompt and tool projection.
  [`src/utils/model-role-settings.ts`](../src/utils/model-role-settings.ts) owns
  model-role settings, reference resolution, and structured diagnostics.
  [`src/team-authority/contracts.ts`](../src/team-authority/contracts.ts) and
  [`worker-launch-bridge.ts`](../src/team-authority/worker-launch-bridge.ts)
  own the configured Worker binding and initial-launch/same-Session recovery
  boundary. [Decision 0015](decisions/0015-model-role-settings.md) records intent.
  The [canonical example](examples/pi-team-bright.settings.json) is shipped with the package.
  Focused settings anchors are `worker-resource-projection.test.ts` and
  `worker-resource-extension.contract.test.ts`.
- [`src/utils/worker-startup-observation.ts`](../src/utils/worker-startup-observation.ts)
  owns the bounded exact-Membership startup observation used after a new or
  recovered carrier launch; `session_bound` generation evidence correlates the
  exact runtime process tuple, and it is not a readiness or progress protocol.
- [`src/alert-authority/alerts.ts`](../src/alert-authority/alerts.ts) owns typed
  exceptional Alert acceptance through injected Membership and publication ports.
- [`src/adapters/terminal-registry.ts`](../src/adapters/terminal-registry.ts)
  selects the terminal lifecycle adapter; adapter implementations own their
  platform capabilities and stop evidence.

## Verification and reproduction

- `npm run typecheck` checks the executable type contract.
- `npm test` runs only the fast deterministic lane; `test:exhaustive-only` is
  its CI complement, `test:full` runs all tests, `test:external` is the external
  runtime diagnostic subset, `qa:agent-surface` is the artifact lane,
  `qa:tool-results` is receipt QA, and `test:lanes` checks closure.
- `npm run verify:package` packs the public artifact and probes the scoped
  observation import from a clean temporary project.

For human setup and a minimal example, start at the [repository README](../README.md).
For current stage, decisions, constraints, and next steps, read the
[evergreen context](current/README.md).


## Test lanes

`npm test` is fast and non-exhaustive; `test:exhaustive-only` is its CI complement, `test:full` runs everything, and `test:lanes` verifies closure. Use `test:external` for external runtime diagnostics, `qa:agent-surface` for the agent-surface artifact, and `qa:tool-results` for receipt QA. CI on Node 22/24 runs fast plus the complement and package verification; publishing on Node 24 runs full plus package verification.