Skip to content

Commit 21238f7

Browse files
redxzetaredxzeta
committed
test(architecture): document ownership evidence
1 parent 12c92a0 commit 21238f7

2 files changed

Lines changed: 24 additions & 0 deletions

File tree

‎.docs/architecture.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,4 +133,5 @@ These are current invariants where the corresponding mechanism exists and bindin
133133
- [Transport](./transport.md) — WebSocket negotiation, compatibility, compression, and replay-safe subscriptions.
134134
- [Runtime modes](./runtime-modes.md) — provider permission-mode mappings.
135135
- [Workspace layout](./workspace-layout.md) — workspace ownership map.
136+
- [State-ownership executable evidence](./ownership-evidence.md) — owner, representation class, and focused regression coverage.
136137
- [Historical plan status](../.plans/architecture-status.md) — disposition of plans that make architecture claims.

‎.docs/ownership-evidence.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# State-ownership executable evidence
2+
3+
This companion to the [canonical architecture](./architecture.md) records the current test evidence for each owner. It does not create a runtime registry or change the ownership matrix: source, contracts, migrations, and these tests remain the authority.
4+
5+
| State | Authoritative owner | Other representation | Executable evidence |
6+
| ------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7+
| Projects, threads, turns, and workflow-like lifecycle | `OrchestrationEngine` plus the orchestration event store | Projection/read model is derived; command receipts are durable idempotency state | `apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts` proves equal command retries append one event and rejects changed command-ID reuse. `ProjectionPipeline.test.ts` proves replay resumes from the durable projector cursor. |
8+
| Automation definitions, schedules, claims, and recovery | `AutomationService` and `AutomationRepository` | Scheduler/reactor are executors and caches, never a second scheduler truth | `apps/server/src/automation/Layers/AutomationService.test.ts` and `AutomationScheduler.test.ts` cover claim, recovery, and durable due-time behavior. |
9+
| Provider processes and native sessions | Concrete provider adapters | Thread/provider binding is durable compatibility metadata; normalized runtime events are canonical ingress | `ProviderRuntimeIngestion.test.ts` proves replayed native output is deduplicated and cannot duplicate finalized content. |
10+
| Environments and worktrees | Orchestration selection metadata and `GitCore`; the checkout is the resource truth | Projection fields describe a selected environment, not task-exclusive ownership | `GitCore.test.ts` proves Forkara-owned worktree markers are verified. Durable task-exclusive ownership remains #177 work. |
11+
| Git and checkpoints | `GitCore` and `CheckpointStore` | Event/projection metadata is an activity catalog, not Git-ref truth | `CheckpointReactor.test.ts` and `GitCore.test.ts` exercise server-owned mutation paths. |
12+
| Validation and delivery evidence | Owning side-effect service and durable event-delivery records | `RuntimeReceiptBus` is transient; model completion is neither validation nor delivery truth | `OrchestrationEventDeliveries.test.ts` covers durable delivery identities. Full validation receipts remain #178 work. |
13+
| Server projections and client-only state | `ProjectionPipeline` for server views; browser stores for drafts/layout only | Client state is a cache/UI preference and cannot overwrite a newer server sequence | `apps/web/src/storeProjection.test.ts` fences stale snapshots with `snapshotSequence` and preserves deletion tombstones. |
14+
| External MCP scopes, requests, audit, and task limits | `ExternalMcpService` and `ExternalMcpRepository` | Gateway is an interface adapter; operation records support recovery | `ExternalMcpGateway.e2e.test.ts` and `ExternalMcpRepository.test.ts` prove normal service admission and request-id replay. |
15+
16+
## Boundary audit
17+
18+
- Interface adapters call application services. The #181 `architecture:check` rejects raw persistence layers and migrations from WebSocket and MCP HTTP adapters.
19+
- `ProviderRuntimeIngestion` is the server's native-provider ingress; adapters normalize before durable orchestration commands and events are emitted.
20+
- Projection rebuild consumes the event journal and cannot independently issue provider or Git side effects. Reactors own those effects and durable command receipts make repeated commands replay-safe.
21+
- Migrations and explicit projection-repair code may write derived tables; they are recovery code, not competing business authority.
22+
23+
Current limitations are intentionally explicit: #177 owns a durable task-exclusive environment contract and #178 owns identity-bound validation and delivery receipts. This evidence does not pre-implement either epic.

0 commit comments

Comments
 (0)