aaronrene / knowtation public
docs flow feat/flow-projection-pilot #18 / 18
aaronrene · 3 days ago · Jun 20, 2026 · Diff

docs(flow): freeze 7A-10 Flow store + list/get parity contract

Contract-only (Thinking 7A-10a) on feat/flow-projection-pilot. Freezes the canonical Flow store API shape and the CLI = MCP = Hub REST read-parity contract before mechanical impl (7A-10b):

- lib/flow/flow-store.mjs module shape (Option A; event-store.mjs parity): load/save/getVault primitives, id/version regexes, idempotent starter seed from flows/starter/, read-only listFlows/getFlow + *ForClient projections. - Read ops: content-minimized scope/tag-filtered list; full ordered-steps get. - CLI: knowtation flow list / flow get (FLOW-V0-SPEC §3.1). - Hub REST: GET /api/v1/flows, GET /api/v1/flows/{id} (§3.3) + full OpenAPI wire shapes to land with the routes in 7A-10b (no docs-only PR to main). - Scope = authorization, server-side, deny-by-default; no existence leak. - Fail-closed: untrusted step text, no secrets, truncated list views, read-only. - Seven-tier test matrix proving store correctness and CLI=MCP=Hub JSON parity.

Ratified vs FLOW-V0-SPEC §1-3/6/9 and scooling FLOW-ADAPTERS-CONTRACT-7A-5. No impl, no routes, no CLI wiring, no Scooling changes, no posture flips.

sha256:316f778efe23e6739a042ee9f6a5fe432885aba8ce1f5ea90da73651ce124ead sha
sha256:8894405bbb074397fa691a0be7ad3727ec6511e7e99185410870ab6816976af8 parent
+46 symbols
sha256:11c7f3d18541ccf979e5489979813f66b7aaa58f7fd4dccad7b7cfa947b28e44 snapshot
+46
symbols added
0
dead code introduced
Semantic Changes 46 symbols
~ docs/FLOW-STORE-CONTRACT-7A-10.md .md 46 symbols added
+ Flow Store + List/Get Parity — Contract (Phase 7A, Step 7A-10a) section Flow Store + List/Get Parity — Contract (Phase 7A, Step 7A-10a) L1–553
+ mjs (Option A, calendar parity) section 1. Store module shape — lib/flow/flow-store.mjs (Option A, calendar parity) L66–151
+ 1 Constants and on-disk layout variable section 1.1 Constants and on-disk layout L72–100
+ code[jsonc] variable variable code[jsonc] L83–96
+ table section table L74–80
+ mjs exactly) section 1.2 Persistence primitives (mirror event-store.mjs exactly) L100–109
+ table section table L102–108
+ 2 of the spec) section 1.3 Id + version helpers (pin §1.2 of the spec) L109–119
+ table section table L111–118
+ 4 Seeding from flows/starter/ (idempotent) section 1.4 Seeding from flows/starter/ (idempotent) L119–130
+ table section table L121–124
+ 5 Read operations (the v0 surface) section 1.5 Read operations (the v0 surface) L130–142
+ table section table L132–136
+ 6 Client projections (*ForClient — calendar parity) section 1.6 Client projections (*ForClient — calendar parity) L142–151
+ table section table L144–148
+ Acceptance (7A-10a) section 10. Acceptance (7A-10a) L519–531
+ Read operations contract (list + get) section 2. Read operations contract (list + get) L151–176
+ 1 flow list — content-minimized, scope/tag filtered section 2.1 flow list — content-minimized, scope/tag filtered L153–163
+ 2 flow get — full definition + ordered steps section 2.2 flow get — full definition + ordered steps L163–176
+ 1) section 3. CLI commands — knowtation flow … (per FLOW-V0-SPEC §3.1) L176–201
+ code variable variable code L182–187
+ Scope enforcement (server-side, deny-by-default) section 4. Scope enforcement (server-side, deny-by-default) L201–217
+ table section table L203–210
+ Starter Flow seed (from flows/starter/) section 5. Starter Flow seed (from flows/starter/) L217–231
+ yaml with the routes in 7A-10b) section 6. OpenAPI wire shapes (to land in docs/openapi.yaml with the routes in 7A-10b) L231–405
+ 1 GET /api/v1/flows — list (scope/tag filtered, content-minimized) section 6.1 GET /api/v1/flows — list (scope/tag filtered, content-minimized) L236–257
+ code[yaml] variable variable code[yaml] L241–256
+ 2 GET /api/v1/flows/{id} — full definition + ordered steps section 6.2 GET /api/v1/flows/{id} — full definition + ordered steps L257–277
+ code[yaml] variable variable code[yaml] L261–276
+ 3 Component schemas section 6.3 Component schemas L277–405
+ code[yaml] variable variable code[yaml] L279–398
+ Triple-surface parity contract (CLI = MCP = Hub REST) section 7. Triple-surface parity contract (CLI = MCP = Hub REST) L405–425
+ table section table L410–415
+ Fail-closed rules (apply to the store and all three surfaces) section 8. Fail-closed rules (apply to the store and all three surfaces) L425–451
+ Seven-tier test matrix (what each tier proves — representative cases, not code) section 9. Seven-tier test matrix (what each tier proves — representative cases, not code) L451–519
+ mjs section 1. unit — test/flow-store-unit.test.mjs L458–470
+ mjs section 2. integration — test/flow-list-get-parity-integration.test.mjs L470–479
+ mjs section 3. e2e — test/flow-store-e2e.test.mjs L479–486
+ mjs section 4. stress — test/flow-store-stress.test.mjs L486–492
+ mjs section 5. data-integrity — test/flow-store-data-integrity.test.mjs L492–499
+ mjs section 6. performance — test/flow-store-performance.test.mjs L499–504
+ mjs section 7. security — test/flow-store-security.test.mjs L504–519
+ Handoff notes (for the next step, 7A-10b — Auto) section Handoff notes (for the next step, 7A-10b — Auto) L541–553
+ Non-goals (7A-10) section Non-goals (7A-10) L531–541
+ Simple summary section Simple summary L34–48
+ Technical summary section Technical summary L48–66
← Older Oldest on feat/flow-projection-pilot
All commits Newer feat(flow): implement store + list/get read surface (7A-10b) sha256:f0525edc70a9a0d7ecc0e91868aa2d4254330be61b028ac0eeeb98c754cb8c55

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:316f778efe23e6739a042ee9f6a5fe432885aba8ce1f5ea90da73651ce124ead --body "your comment"