cloudaxe-opencode/specs/v2/README.md

# V2 Specifications

These documents explain V2 behavior that is difficult to recover from one source file. They are not API reference or a backlog.

## Authority

Authority follows the concern:

| Concern                                          | Owner                                                                                      |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| HTTP operations and transport errors             | [Protocol](../../packages/protocol/src) endpoint definitions assembled by Server `HttpApi` |
| Public domain shapes and durable event payloads  | [Schema](../../packages/schema/src)                                                        |
| Runtime behavior and persistence                 | [Core](../../packages/core/src)                                                            |
| Canonical vocabulary and cross-domain invariants | Root [CONTEXT.md](../../CONTEXT.md)                                                        |
| Contributor-critical regression guardrails       | Root [AGENTS.md](../../AGENTS.md)                                                          |

Current specifications explain cross-module contracts without copying exact types. Decision records explain why a design was selected. Historical documents describe earlier states and may use obsolete names.

Generated clients follow the assembled public `HttpApi`. GitHub issues own active work; Git history preserves removed plans and scratchpads.

## Current Contracts

| Document                | Job                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------- |
| [Session](./session.md) | Explain prompt admission, execution, instructions, compaction, and recovery boundaries. |
| [Tools](./tools.md)     | Explain tool construction, registration, execution, and outcome laws.                   |

## Decisions And Proposals

| Document                                                          | Status                     | Job                                                                          |
| ----------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------- |
| [Event stream](./event-stream-architecture.md)                    | Accepted and implemented   | Record why public events use one encoded feed with independent queues.       |
| [Managed restart continuation](./session-restart-continuation.md) | Accepted and implemented   | Record why graceful managed-service restart uses private Session suspension. |
| [Instruction sync](./instruction-sync-proposal.md)                | Accepted and implemented   | Record why instruction state is value deltas plus derived rendering.         |
| [Provider policy](./provider-policy.md)                           | Proposed and unimplemented | Explore provider authorization independently from provider configuration.    |

## Historical Context

| Document                                                                | Job                                                                                                 |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [Schema changelog](./schema-changelog.md)                               | Preserve the pre-release compatibility ledger. Names in older entries are intentionally historical. |
| [Catalog/config/plugin lifecycle](./catalog-config-plugin-lifecycle.md) | Preserve the option comparison that led to replayable Location-scoped catalog transforms.           |

Do not add implementation checklists here. Put actionable work in GitHub issues and package-specific contributor guidance next to the code it governs.
docs(v2): consolidate specifications (#36186) 2026-07-10 02:47:37 +00:00			`# V2 Specifications`

			`These documents explain V2 behavior that is difficult to recover from one source file. They are not API reference or a backlog.`

			`## Authority`

			`Authority follows the concern:`

			`\| Concern \| Owner \|`
			`\| ------------------------------------------------ \| ------------------------------------------------------------------------------------------ \|`
			\| HTTP operations and transport errors \| [Protocol](../../packages/protocol/src) endpoint definitions assembled by Server `HttpApi` \|
			`\| Public domain shapes and durable event payloads \| [Schema](../../packages/schema/src) \|`
			`\| Runtime behavior and persistence \| [Core](../../packages/core/src) \|`
			`\| Canonical vocabulary and cross-domain invariants \| Root [CONTEXT.md](../../CONTEXT.md) \|`
			`\| Contributor-critical regression guardrails \| Root [AGENTS.md](../../AGENTS.md) \|`

			`Current specifications explain cross-module contracts without copying exact types. Decision records explain why a design was selected. Historical documents describe earlier states and may use obsolete names.`

			Generated clients follow the assembled public `HttpApi`. GitHub issues own active work; Git history preserves removed plans and scratchpads.

			`## Current Contracts`

			`\| Document \| Job \|`
			`\| ----------------------- \| --------------------------------------------------------------------------------------- \|`
			`\| [Session](./session.md) \| Explain prompt admission, execution, instructions, compaction, and recovery boundaries. \|`
refactor(tools): unify tool APIs and result handling (#38367) 2026-07-23 21:13:31 +00:00			`\| [Tools](./tools.md) \| Explain tool construction, registration, execution, and outcome laws. \|`
docs(v2): consolidate specifications (#36186) 2026-07-10 02:47:37 +00:00
			`## Decisions And Proposals`

			`\| Document \| Status \| Job \|`
			`\| ----------------------------------------------------------------- \| -------------------------- \| ---------------------------------------------------------------------------- \|`
refactor(server): share event stream encoding (#36484) 2026-07-12 15:48:52 +00:00			`\| [Event stream](./event-stream-architecture.md) \| Accepted and implemented \| Record why public events use one encoded feed with independent queues. \|`
docs(v2): consolidate specifications (#36186) 2026-07-10 02:47:37 +00:00			`\| [Managed restart continuation](./session-restart-continuation.md) \| Accepted and implemented \| Record why graceful managed-service restart uses private Session suspension. \|`
feat(core): replace instruction checkpoints with value-delta sync (#36254) 2026-07-10 17:26:25 +00:00			`\| [Instruction sync](./instruction-sync-proposal.md) \| Accepted and implemented \| Record why instruction state is value deltas plus derived rendering. \|`
docs(v2): consolidate specifications (#36186) 2026-07-10 02:47:37 +00:00			`\| [Provider policy](./provider-policy.md) \| Proposed and unimplemented \| Explore provider authorization independently from provider configuration. \|`

			`## Historical Context`

			`\| Document \| Job \|`
			`\| ----------------------------------------------------------------------- \| --------------------------------------------------------------------------------------------------- \|`
			`\| [Schema changelog](./schema-changelog.md) \| Preserve the pre-release compatibility ledger. Names in older entries are intentionally historical. \|`
			`\| [Catalog/config/plugin lifecycle](./catalog-config-plugin-lifecycle.md) \| Preserve the option comparison that led to replayable Location-scoped catalog transforms. \|`

			`Do not add implementation checklists here. Put actionable work in GitHub issues and package-specific contributor guidance next to the code it governs.`