docs: clarify server store roles

2026-06-06 17:34:50 +07:00
parent f137b8fcb2
commit bc3f4c94dd
4 changed files with 86 additions and 2 deletions
@@ -202,6 +202,25 @@ WorkflowApi
 The context must pass `require_workflow_stores()` before being exposed through
 the long-lived API.

+Current config exposes one default `server.store` root. The server then fans it
+out into workflow stores, auth records, source registry state, and catalog/cache
+state. That is acceptable for the first durable server path, but the boundary
+should not assume every persistence role always shares one backend.
+
+Future config should support optional role-specific store overrides:
+
+```text
+server.store              default for every missing role
+server.stores.workflow    artifacts, deployments, drafts, runs, traces
+server.stores.auth        auth records or secret-manager references
+server.stores.sources     desired source registry entries
+server.stores.catalog     source catalog/cache snapshots
+```
+
+The compatibility rule is: if a role store is absent, use `server.store`. First
+implementation should keep overrides filesystem-only; SQL, object storage, and
+secret-manager adapters are later backend implementations.
+
 The first server runtime may reuse existing implementation classes when they do
 not require MCP-specific behavior. If reuse would require constructing
 `WfMcpService`, that is the wrong dependency direction.
@@ -173,7 +173,7 @@ sources.

 `server.store` answers: where does the server persist workflow platform state?

-The current implementation can start with a filesystem store:
+The current implementation uses one default filesystem store root:

 ```json
 {
@@ -186,6 +186,13 @@ The current implementation can start with a filesystem store:
 }
 ```

+That single root fans out internally into role-specific files/directories:
+
+- workflow records: artifacts, deployments, draft workspaces, runs, and traces
+- source registry desired state
+- source catalog/cache snapshots
+- auth records for local/dev MCP-compatible credentials
+
 Recommended Pydantic shape for the first slice:

 ```python
@@ -211,7 +218,52 @@ the config does not bake the store concept into a single `store_root` field.
 Relative filesystem paths should resolve relative to the config file directory.
 SQL-backed stores are future work.

-The store should eventually own mutable workflow platform registries:
+### Store Roles
+
+`server.store` is the default store for every role. Future configs should allow
+optional role-specific overrides without breaking existing files:
+
+```json
+{
+  "server": {
+    "store": {
+      "kind": "filesystem",
+      "root": ".wf_store"
+    },
+    "stores": {
+      "workflow": {
+        "kind": "filesystem",
+        "root": ".wf_store"
+      },
+      "auth": {
+        "kind": "filesystem",
+        "root": ".wf_auth"
+      },
+      "source_registry": {
+        "kind": "filesystem",
+        "root": ".wf_sources"
+      },
+      "catalog_cache": {
+        "kind": "filesystem",
+        "root": ".wf_catalog"
+      }
+    }
+  }
+}
+```
+
+Resolution rule:
+
+```text
+effective_store(role) = server.stores[role] if present else server.store
+```
+
+The first implementation should keep all role overrides optional and filesystem
+only. This preserves the current single-root config while making the boundary
+ready for secret-manager auth stores, database-backed workflow records, and
+separate catalog/cache storage.
+
+The store layer should own mutable workflow platform registries:

 - artifact records
 - deployment records