# thought stream specification

This directory is the binding design contract. The implementation now uses the producer/consumer process topology: source-local event sequences, narrow Jazz queries and subscriptions, durable per-consumer progress, and deterministic execution evidence. It does not contain the superseded central matcher/scheduler/lease path.

The core local milestone is implemented and exercised in `test/agent-runtime.test.ts` and `test/acceptance.test.ts`. The broader capability gates in `testing.md`, especially edge-durability, permission, fault-injection, and independent-process proofs, remain requirements rather than implied accomplishments.

## Documents

- [`vision.md`](vision.md): product boundary and success conditions.
- [`architecture.md`](architecture.md): components, authority, and data flow.
- [`events.md`](events.md): canonical event envelope, lineage, registry, and semantics.
- [`jazz.md`](jazz.md): Jazz-first responsibility boundary, capability gates, persistence, coordination, permissions, and synchronization contract.
- [`connectors.md`](connectors.md): shared ingress contract and source-specific behavior.
- [`x-webhook.md`](x-webhook.md): X Activity webhook lanes, admission, management authority, recovery, cost custody, and model separation.
- [`filesystem-charter.md`](filesystem-charter.md): filesystem/Obsidian diffs and Charter integration.
- [`agents.md`](agents.md): consumer declarations, subscriptions, execution, outputs, and traces.
- [`compaction.md`](compaction.md): reciprocal compactor agents, recursive typed conversation boundaries, exact-tail selection, and fail-closed lineage.
- [`agent-messages.md`](agent-messages.md): private typed agent-to-agent messages, thread reconstruction, and the bounded local send/wait/read capability.
- [`focuses.md`](focuses.md): governed focus declarations, policy-DAG semantics, proposal authority, actor-model boundary, and producer expansion map.
- [`harnesses.md`](harnesses.md): generic container-harness contract, isolation profiles, persistent workspace/session leases, and the Pi coding reference adapter.
- [`repairs.md`](repairs.md): deterministic repair eligibility, sandboxed correction proposals, judgment authority, effective-output rebuilding, and training boundaries.
- [`proposals.md`](proposals.md): The Stream's fixed memory/correction proposal tools, snapshot binding, human decisions, materialization, and private training custody.
- [`public-knowledge.md`](public-knowledge.md): Coil admission, proposal-only Co/Luna execution through one controller-owned tool, typed private diff proposals, and the separate reviewed-materializer boundary.
- [`review.md`](review.md): complete review prompts, blinded candidate pairs, judgeability, append-only human decisions, OAuth-only browser writes, and training-data custody.
- [`incidents.md`](incidents.md): content-dark operational incident projection, private ledger, and independent Telegram alert policy.
- [`artifacts.md`](artifacts.md): immutable self-rooted content-addressed thought artifacts, artifact-catalog projection, and private inspector rendering.
- [`documents.md`](documents.md): operator-owned working documents: identity, source links, version identity, head projection, proposal state with stale-base failure, access, judgment lineage, and the deterministic runner seam.
- [`courses.md`](courses.md): private interactive lessons and the OAuth-only, receipt-backed course-question path.
- [`tinker.md`](tinker.md): Tinker model and adapter boundary.
- [`security.md`](security.md): privacy, credentials, authority, and prompt-injection boundaries.
- [`recovery.md`](recovery.md): producer cursors, consumer progress, retries, replay, and terminal evidence.
- [`ui.md`](ui.md): thin root-activity interface.
- [`web-auth.md`](web-auth.md): public/private route matrix, OAuth boundary, threat model, and activation proof.
- [`testing.md`](testing.md): required tests and acceptance scenario.

## First implementation milestone

The milestone is complete only when an ordinary file edit produces this verified chain in a real local Jazz database:

`producer observes source → event and source sequence settle in Jazz (with an external cursor where the source has one) → consumer subscription receives event → execution starts → trace captured → typed result and consumer progress settle in Jazz → root activity projection updates`

The first runner may use a deterministic test model. The production boundary must already be Pi-shaped and Tinker-configurable so replacing the model does not alter event semantics.