diff --git a/docs/README.md b/docs/README.md index 8b3db10d5d..cd6f59fdf9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -46,6 +46,8 @@ This page is the authority map for Maka documentation. Code and contract tests r - [Session task ledger lifecycle](./session-task-ledger-lifecycle.md) - [Work Board contract](./work-board-contract.md) - [Work Board Phase 1 surface](./work-board-phase1.md) +- [WorkHub domain language](./workhub-domain-language.md) +- [WorkHub Coordination Session ADR](./architecture/workhub-coordination-session-adr.md) - [Runtime resume architecture](./architecture/runtime-resume-architecture.md) ([中文](./architecture/runtime-resume-architecture.zh-CN.md)) - [Runtime Host architecture](./architecture/runtime-host-architecture.md) ([中文](./architecture/runtime-host-architecture.zh-CN.md)) - [Remote Runtime Host setup](./runtime-host-remote-access.md) ([中文](./runtime-host-remote-access.zh-CN.md)) diff --git a/docs/architecture/workhub-coordination-session-adr.md b/docs/architecture/workhub-coordination-session-adr.md new file mode 100644 index 0000000000..4df6529674 --- /dev/null +++ b/docs/architecture/workhub-coordination-session-adr.md @@ -0,0 +1,148 @@ + + +# ADR: One WorkHub Coordination Session per Runtime Host + +- Status: Accepted +- Date: 2026-08-25 +- Scope: WorkHub architecture +- Decision source: [Discussion #3286](https://github.com/apache/maka/discussions/3286#discussioncomment-18135855) +- Delivery tracker: [Issue #3492](https://github.com/apache/maka/issues/3492) + +## Context + +WorkHub is intended to be one persistent conversational place where a user can ask +an ordinary question, clarify intent, continue existing work, or create new work. +R2.4 is a deterministic routing and context-continuity baseline that may also serve +as a future target resolver. It does not provide a persistent WorkHub conversation +and is not the final definition or authority boundary of WorkHub. + +A persistent coordinator needs durable conversational continuity without creating +a second WorkHub database, event store, transcript substrate, or lifecycle +authority alongside Session. + +## Decision + +Each Runtime Host independently owns one stable WorkHub **Coordination Session**. +The Coordination Session is a special role of the existing Session, not a new +durable entity type or storage system. It reuses the existing Session, Turn, +transcript, model, recovery, and event infrastructure. Session remains the only +durable conversation and execution substrate. + +The role is provisioned lazily when WorkHub first needs it and resolves to the same +Session after Runtime Host or application restarts. The representation, lookup, and +recovery mechanisms that enforce this contract are deferred to Slice 2. + +The per-Host boundary is intentional. A Coordination Session coordinates only the +ordinary Sessions belonging to the same Runtime Host. Switching Runtime Hosts +selects the other Host's Coordination Session; the first milestone does not support +cross-Host coordination or a global Coordination Session. + +The Coordination Session is hidden from the ordinary Session list and excluded +from every routing-candidate set. The Action Gate's self-route rejection remains a +defense in depth; it is not a substitute for keeping the Coordination Session out of +ordinary navigation and target discovery. + +## Durable authority boundaries + +| Concern | Durable authority | +| --- | --- | +| User messages sent in WorkHub, ordinary Q&A, clarification, coordination decisions, bounded delegation references, and coordination summaries | The active Runtime Host's Coordination Session | +| Concrete execution, project and filesystem scope, model and permission mode, root-Turn admission, tools, artifacts, recovery, archive/delete, and the authoritative execution transcript | The target ordinary Session | +| Aggregated WorkHub cards, filters, status summaries, and navigation aids | No durable authority; these are rebuildable projections of Session facts | + +The Coordination Session is authoritative only for the coordination conversation. +It never acquires authority over an ordinary Session's execution or lifecycle. + +## Dispositions and action admission + +Every WorkHub input resolves to exactly one proposed **disposition**: + +- `answer_here`: answer in the Coordination Session. +- `delegate_existing`: delegate concrete work to one bounded, valid ordinary + Session. +- `create_new`: create an ordinary Session, then delegate concrete work to it. +- `clarify`: continue clarification in the Coordination Session without guessing a + target or creating a Session. + +All model and routing output is advisory. Before any write, a deterministic +**Action Gate** admits or rejects the proposed disposition and operation. The gate +enforces Runtime Host and target validity, archive and waiting state, self-route +exclusion, explicit `create_new`, expected-Turn ownership for Stop, confirmation +requirements, and existing tool and permission ceilings. Neither a model nor a +routing policy can directly authorize a write or expand execution authority. + +## Delegation links rather than copies transcripts + +A delegation persists only a bounded link between the coordination and execution +transcripts, such as: + +```text +delegationId +coordinationTurnId +targetSessionId +targetTurnId +disposition +status +``` + +`status` describes only whether the coordination-owned link is `active` or +`superseded`; it never mirrors the target Turn's execution lifecycle. Target +acceptance, running, waiting, completion, failure, abort, and recovery state remain +ordinary Session facts. WorkHub derives those states as read-only projections and +does not persist them as independent Coordination Session truth. + +The ordinary Session records the delegated request, tools, side effects, and +authoritative result. WorkHub may display a bounded projection or record a +coordination summary, but it does not copy the ordinary Session's complete +transcript into the Coordination Session. + +## Consequences, costs, and reevaluation + +- WorkHub gains persistent conversational continuity without adding another + durable authority, database, event store, lifecycle, or transcript copy. +- Coordination and execution remain separately authoritative within the shared + Session substrate. +- The per-Host boundary fragments WorkHub continuity when a user switches Runtime + Hosts: each Host has a separate coordination transcript and cannot coordinate the + other Host's Sessions. +- The special Session role adds provisioning, lookup, recovery, retention, and UI + obligations even though it deliberately reuses the existing Session substrate. +- Whether Work is 1:1 with Session, 1:N over Sessions, or an independent durable + entity remains unresolved. +- Cross-Runtime-Host coordination remains deferred. +- Coordination Session kind/role representation, lazy creation, durable lookup, + recovery, UI treatment, and routing implementation belong to Slice 2 and later; + this ADR does not design or implement them. + +Reevaluate the per-Host decision if supported workflows require one WorkHub +conversation to coordinate ordinary Sessions on multiple Runtime Hosts, or if Host +switching creates user-visible continuity loss that rebuildable projections cannot +resolve. Reevaluate the special Session role if implementing its lifecycle requires +a second durable authority or exceptions that the ordinary Session substrate cannot +enforce safely. + +## Rejected alternatives + +- A second WorkHub database, event store, transcript substrate, or lifecycle + authority. +- One global Coordination Session spanning Runtime Hosts. +- Copying an ordinary Session's complete transcript into WorkHub. +- Allowing model or routing output to authorize writes without the deterministic + Action Gate. diff --git a/docs/workhub-domain-language.md b/docs/workhub-domain-language.md index ef1467b476..ac0821e6b0 100644 --- a/docs/workhub-domain-language.md +++ b/docs/workhub-domain-language.md @@ -25,7 +25,8 @@ Runtime Host while concrete execution remains authoritative in ordinary Sessions This document names the approved target architecture. The current R2.4 implementation is a transitional deterministic router and does not yet create the -Coordination Session described below. +Coordination Session described below. The decision and authority boundaries are +recorded in the [WorkHub Coordination Session ADR](./architecture/workhub-coordination-session-adr.md). ## Terms @@ -33,12 +34,16 @@ Coordination Session described below. and recovery substrate. A Session owns only the conversation or execution admitted to that Session. -**Coordination Session**: A special Session role used by WorkHub. Each Runtime Host -has at most one stable Coordination Session. It owns WorkHub user messages, ordinary -Q&A, clarification, coordination decisions, delegation references, and coordination -summaries. It is hidden from the ordinary Session list and never routes to itself. +**Coordination Session**: The stable special Session role owned independently by +each Runtime Host for its WorkHub conversation. It owns WorkHub user messages, +ordinary Q&A, clarification, coordination decisions, bounded delegation references, +and coordination summaries, but no ordinary Session execution or lifecycle facts. +It is not a separate database, event store, transcript substrate, or lifecycle +authority. It is hidden from the ordinary Session list and excluded from every +routing-candidate set, so it never routes to itself. Cross-Host coordination is not +supported in the first milestone. -**Ordinary Session**: A Session that owns concrete work execution, including its +**ordinary Session**: A Session that owns concrete work execution, including its project/filesystem scope, model and permissions, root-Turn admission, tools, artifacts, recovery, lifecycle, and authoritative execution transcript. @@ -49,18 +54,30 @@ artifacts, recovery, lifecycle, and authoritative execution transcript. the active Runtime Host's Coordination Session. It may answer locally, clarify, delegate to an existing ordinary Session, or create a new ordinary Session. -**Session projection**: A rebuildable view derived from Session facts for display and routing. It can be discarded and recreated without losing work. - -**Disposition**: The coordination outcome for one WorkHub input: -`answer_here`, `delegate_existing`, `create_new`, or `clarify`. - -**Delegation**: A reference from a Coordination Turn to a target ordinary Session -and Turn. Delegation links the two authoritative transcripts; it does not copy the -target execution transcript into WorkHub. +**projection**: A rebuildable, read-only view derived from Coordination Session and +ordinary Session facts. WorkHub cards, filters, status summaries, and navigation +aids are projections; they own no durable facts and can be discarded without losing +work. + +**disposition**: The single proposed coordination outcome for one WorkHub input: +`answer_here` answers in the Coordination Session; `delegate_existing` targets one +bounded, valid ordinary Session; `create_new` creates an ordinary Session before +delegating; and `clarify` continues in the Coordination Session without guessing or +creating. + +**delegation**: A bounded reference from a Coordination Turn to one target ordinary +Session and Turn, including only its identity, disposition, and coordination-owned +link status (`active` or `superseded`). Delegation links the separately authoritative +transcripts; it does not copy the target's complete execution transcript into +WorkHub. Target acceptance, running, waiting, completion, failure, abort, and +recovery state remain ordinary Session facts and appear in WorkHub only as read-only +projections. **Action Gate**: The deterministic Runtime boundary that validates a proposed -disposition, target, creation, Stop, confirmation, tools, and permissions. A model -or routing policy may propose an action but cannot authorize it. +disposition and operation before any write, including target/Host validity, +archive and waiting state, self-routing, explicit creation, expected-Turn Stop +ownership, confirmation, tools, and permissions. All model and routing output is +advisory and cannot authorize a write. **Route correction**: A user's decision that an input belongs to a different existing Session. R2.4 retains only bounded inference memory for later target