You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by as...@apache.org on 2026/08/25 03:58:42 UTC
(maka) branch main updated: docs: refresh Astryx surface inventory (#3742)
This is an automated email from the ASF dual-hosted git repository.
Astro-Han pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/maka.git
The following commit(s) were added to refs/heads/main by this push:
new 81a811975 docs: refresh Astryx surface inventory (#3742)
81a811975 is described below
commit 81a811975dc1d0359408a9eec18106a033fd6a43
Author: ChengBo Zhang <66...@users.noreply.github.com>
AuthorDate: Tue Aug 25 11:58:37 2026 +0800
docs: refresh Astryx surface inventory (#3742)
* docs(workhub): record coordination session architecture
Generated-by: Codex
* docs(workhub): clarify coordination authority tradeoffs
Generated-by: Codex
* docs(workhub): preserve coordination routing exclusion
Generated-by: Codex
---
docs/README.md | 2 +
.../workhub-coordination-session-adr.md | 148 +++++++++++++++++++++
docs/workhub-domain-language.md | 49 ++++---
3 files changed, 183 insertions(+), 16 deletions(-)
diff --git a/docs/README.md b/docs/README.md
index 8b3db10d5..cd6f59fdf 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 000000000..4df652967
--- /dev/null
+++ b/docs/architecture/workhub-coordination-session-adr.md
@@ -0,0 +1,148 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# 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 ef1467b47..ac0821e6b 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
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org