Skip to content

Commit 43e30f1

Browse files
juanmardefagojuanmardefago
committed
docs: record MVP-033 network contract
Document the resolved chain/network discovery contract for MVP and add a sequencing guide derived from the MVP backlog. - mark MVP-033 as done and record the chosen package-derived network behavior in plans/mvp-implementation-backlog.md - narrow the corresponding open question in docs/mvp-scope.md - add docs/mvp-implementation-sequencing.md to describe dependency-driven implementation order and parallel work lanes
1 parent ac12713 commit 43e30f1

3 files changed

Lines changed: 349 additions & 10 deletions

File tree

‎docs/mvp-implementation-sequencing.md‎

Lines changed: 324 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,324 @@
1+
# MVP Implementation Sequencing
2+
3+
This document derives a recommended implementation sequence from `plans/mvp-implementation-backlog.md`.
4+
5+
It is not a replacement for the backlog.
6+
7+
Use it to:
8+
9+
- understand which tasks are true prerequisites for others
10+
- identify which work can proceed in parallel
11+
- avoid prompting agents to implement downstream tasks before the required contracts are stable enough
12+
13+
Use `docs/mvp-scope.md` as the target-state definition and `plans/mvp-implementation-backlog.md` as the source of truth for task definitions, dependencies, and status.
14+
15+
## How To Read This Document
16+
17+
This is a dependency-driven sequencing guide, not a strict linear priority list.
18+
19+
The MVP backlog is a DAG with multiple work lanes. Some tasks are:
20+
21+
- **hard blockers**: downstream implementation should not proceed until they are resolved or narrowed enough
22+
- **soft blockers**: they affect a lane, but some limited work can still proceed under the documented assumptions
23+
- **parallelizable**: they can be worked on independently once their local prerequisites are stable enough
24+
25+
This document combines:
26+
27+
- explicit task dependencies from `plans/mvp-implementation-backlog.md`
28+
- execution judgment about which tasks are safest or most useful to do earlier within those dependency constraints
29+
30+
When this document recommends an order that is not strictly enforced by the backlog, treat it as advisory rather than mandatory.
31+
32+
For `open_question` tasks, “done” means producing a concrete output that downstream work can reference:
33+
34+
- a documented decision
35+
- a narrowed contract
36+
- or an explicit recorded deferral
37+
38+
## Sequencing Principles
39+
40+
1. Freeze shared contracts before asking agents to implement multiple dependent tasks.
41+
2. Unlock work by lane once the minimum required contracts for that lane are stable enough.
42+
3. Do not wait for every open question to be fully closed before starting all implementation.
43+
4. Do not start downstream implementation by embedding an implicit answer to an unresolved contract question.
44+
5. Prefer prompting one `MVP-###` task at a time unless the supporting change is strictly required by that task’s `Done when` or `Verify`.
45+
46+
## Phase 0: Shared Contract And Decision Gate
47+
48+
These tasks define semantics or interfaces that multiple lanes depend on.
49+
50+
The grouping is recommended because these tasks have broad downstream impact. It is not a claim that every one of them must be fully closed before any implementation begins.
51+
52+
### Hard Blockers
53+
54+
- `MVP-004` Define and document the byte-billing and payment/header contract used in the real runtime path
55+
- Blocks most runtime payment, provider integration, and client integration work.
56+
- `MVP-027` Freeze canonical payment identity, `collection_id` reuse, and session-vs-payment keying semantics
57+
- Blocks reconnect, provider state, settlement lifecycle, and operator retrieval/collection work.
58+
- `MVP-028` Define the MVP authentication and authorization contract for oracle and provider operator surfaces
59+
- Blocks authenticated admin/operator implementation for oracle and provider APIs.
60+
61+
### Soft Blockers
62+
63+
- `MVP-001` Freeze the pricing exposure contract between oracle metadata and provider handshake
64+
- Primarily blocks discovery/oracle integration where pricing semantics could drift.
65+
- Some oracle work can proceed if pricing remains explicitly non-authoritative or advisory.
66+
- `MVP-023` Define the final MVP observability floor beyond structured logs and status tooling
67+
- Primarily blocks final observability closure, not all operator visibility work.
68+
69+
### Guidance
70+
71+
- Start MVP execution by resolving as many hard blockers as possible.
72+
- Do not require all soft blockers to be fully closed before any implementation begins.
73+
- For `MVP-001` and `MVP-023`, allow limited implementation so long as the current assumptions remain explicit and no irreversible semantics are baked into code.
74+
- `MVP-033` is already resolved enough for downstream discovery and client-integration work to rely on its contract.
75+
76+
## Phase 1: Lane Unlocks
77+
78+
Once enough of the Phase 0 gate is stable, work can proceed in parallel lanes.
79+
80+
The lane ordering below respects explicit backlog dependencies. Ordering within a lane is recommended unless the backlog dependency graph makes it mandatory.
81+
82+
### Lane A: Discovery And Consumer Entry
83+
84+
Minimum prerequisites:
85+
86+
- `MVP-033` resolved enough for implementation
87+
- `MVP-001` stable enough for the chosen oracle/pricing exposure behavior
88+
89+
Recommended sequence:
90+
91+
1. `MVP-005` Implement a standalone oracle service with manual whitelist and recommended-provider response
92+
2. `MVP-007` Integrate consumer sidecar with oracle discovery while preserving direct-provider fallback
93+
3. `MVP-017` Integrate the real consumer/client path with consumer sidecar init, usage reporting, and session end
94+
4. `MVP-030` Add runtime compatibility and preflight checks for real provider/plugin deployments
95+
96+
Notes:
97+
98+
- `MVP-033` is resolved for MVP with the following contract:
99+
- consumer sidecar derives network from the Substreams package by default
100+
- if a package/module resolves a specific `networks` entry, that takes precedence over top-level `network`
101+
- explicit input remains supported only as fallback when package derivation is unavailable
102+
- mismatch between explicit and package-derived values fails fast after normalization
103+
- missing usable network also fails fast
104+
- `MVP-017` also depends on `MVP-011`, so only the entry/lifecycle portion should move first.
105+
- `MVP-030` is late in the lane because it depends on real-path integration existing.
106+
107+
### Lane B: Runtime Payment And Stream Control
108+
109+
Minimum prerequisites:
110+
111+
- `MVP-004`
112+
113+
Recommended sequence:
114+
115+
1. `MVP-010` Implement session-local low-funds detection and provider Continue/Pause/Stop decisions during streaming
116+
2. `MVP-012` Add deterministic RAV issuance thresholds suitable for real runtime behavior
117+
3. `MVP-014` Integrate provider gateway validation into the real provider streaming path
118+
4. `MVP-015` Wire real byte metering from the provider/plugin path into gateway payment state
119+
5. `MVP-011` Propagate provider stop/pause decisions through consumer sidecar into the real client path
120+
6. `MVP-016` Enforce gateway Continue/Pause/Stop decisions in the live provider stream lifecycle
121+
7. `MVP-031` Wire the live PaymentSession and RAV-control loop into the real client/provider runtime path
122+
123+
Notes:
124+
125+
- `MVP-010` and `MVP-014` are the main foundations in this lane.
126+
- `MVP-031` is effectively the capstone runtime-payment task because it depends on real provider and consumer integration plus thresholding.
127+
128+
### Lane C: Provider State, Settlement, And Operator Retrieval
129+
130+
Minimum prerequisites:
131+
132+
- `MVP-027`
133+
134+
Recommended sequence:
135+
136+
1. `MVP-003` Define the durable provider-side payment and settlement data model
137+
2. `MVP-008` Add durable provider storage for accepted RAV, session state, and collection lifecycle state
138+
3. `MVP-029` Implement provider collection lifecycle transitions and update surfaces for `collectible`, `collect_pending`, `collected`, and retryable collection state
139+
4. `MVP-009` Expose provider inspection and settlement-data retrieval APIs for accepted/collectible RAV state
140+
5. `MVP-022` Add authentication and authorization to provider admin/operator APIs
141+
6. `MVP-019` Implement provider inspection CLI flows for collectible/accepted RAV data
142+
7. `MVP-020` Implement manual collection CLI flow that crafts/signs/submits collect transactions locally
143+
8. `MVP-032` Expose operator runtime/session/payment inspection APIs and CLI/status flows
144+
9. `MVP-018` Implement operator funding CLI flows for approve/deposit/top-up beyond local demo assumptions
145+
146+
Notes:
147+
148+
- `MVP-008` and `MVP-029` can begin in parallel once `MVP-003` and `MVP-027` are stable enough.
149+
- `MVP-009` depends on `MVP-029`, so this part of the sequence is required by the backlog rather than just recommended.
150+
- `MVP-018` comes late because the current backlog explicitly ties it to operator runtime/low-funds inspection surfaces.
151+
152+
### Lane D: Reconnect And Resume
153+
154+
Minimum prerequisites:
155+
156+
- `MVP-027`
157+
158+
Recommended sequence:
159+
160+
1. `MVP-002` Freeze reconnect handshake semantics so provider can return fresh or latest-known resumable RAV during normal session init
161+
2. `MVP-008` durable provider state work must be stable enough for reconnect behavior
162+
3. `MVP-013` Implement provider-authoritative reconnect/resume in the normal handshake path
163+
164+
Notes:
165+
166+
- This lane depends on both protocol and persistence work.
167+
- Reconnect should not be treated as complete until it is proven against provider-authoritative durable state, not just consumer-local memory.
168+
169+
### Lane E: Security And Deployment
170+
171+
Minimum prerequisites:
172+
173+
- `MVP-028` for authenticated operator/admin surfaces
174+
175+
Recommended sequence:
176+
177+
1. `MVP-021` Make TLS the default non-dev runtime posture for oracle, sidecar, and provider integration paths
178+
2. `MVP-006` Add authenticated oracle administration for whitelist and provider metadata management
179+
3. `MVP-022` Add authentication and authorization to provider admin/operator APIs
180+
4. `MVP-030` Add runtime compatibility and preflight checks for real provider/plugin deployments
181+
182+
Notes:
183+
184+
- `MVP-021` can proceed relatively early even though it has no hard dependency on `MVP-028`.
185+
- `MVP-030` overlaps discovery and runtime work and should land once the real deployment path is concrete enough to validate.
186+
187+
### Lane F: Observability, Validation, And Docs
188+
189+
Minimum prerequisites:
190+
191+
- `MVP-023` for final observability scope
192+
193+
Recommended sequence:
194+
195+
1. `MVP-024` Implement basic operator-facing inspection/status surfaces and log correlation
196+
2. `MVP-025` Add MVP acceptance coverage for the primary end-to-end scenarios in docs/tests/manual verification
197+
3. `MVP-026` Refresh protocol/runtime docs so they match the MVP architecture and explicit open questions
198+
199+
Notes:
200+
201+
- `MVP-024` can begin in a limited way before `MVP-023` is fully closed if it stays within the current “basic visibility” assumption.
202+
- `MVP-025` should be updated incrementally throughout implementation, but its final closure belongs near the end.
203+
- `MVP-026` should be completed after the key open-question outputs it depends on are stable.
204+
205+
## Suggested Implementation Phases
206+
207+
This is the most practical high-level order to use when prompting agents.
208+
209+
It is a recommended rollout sequence, not a canonical priority order embedded in the backlog itself.
210+
211+
### Phase 0: Resolve Or Narrow Shared Contracts
212+
213+
- `MVP-004`
214+
- `MVP-027`
215+
- `MVP-028`
216+
- `MVP-001`
217+
- `MVP-023`
218+
219+
Already resolved:
220+
221+
- `MVP-033`
222+
223+
### Phase 1: Start The First Implementable Lanes
224+
225+
- Discovery foundation:
226+
- `MVP-005`
227+
- `MVP-007`
228+
- Runtime foundation:
229+
- `MVP-010`
230+
- `MVP-012`
231+
- `MVP-014`
232+
- Provider state foundation:
233+
- `MVP-003`
234+
- `MVP-008`
235+
- `MVP-029`
236+
- Security foundation:
237+
- `MVP-021`
238+
239+
### Phase 2: Integrate Runtime And Retrieval Paths
240+
241+
- `MVP-015`
242+
- `MVP-011`
243+
- `MVP-016`
244+
- `MVP-017`
245+
- `MVP-009`
246+
- `MVP-022`
247+
- `MVP-002`
248+
249+
### Phase 3: Complete Reconnect, Runtime Control, And Operator Flows
250+
251+
- `MVP-013`
252+
- `MVP-031`
253+
- `MVP-006`
254+
- `MVP-019`
255+
- `MVP-020`
256+
- `MVP-032`
257+
- `MVP-018`
258+
- `MVP-030`
259+
260+
### Phase 4: Finalize Visibility, Acceptance, And Documentation
261+
262+
- `MVP-024`
263+
- `MVP-025`
264+
- `MVP-026`
265+
266+
## Tasks That Can Safely Start Before Every Open Question Is Closed
267+
268+
These are useful to know when sequencing agent work.
269+
270+
This section is interpretive guidance based on the assumptions register and dependency graph. It is not a direct restatement of the backlog.
271+
272+
### Safe To Start Early
273+
274+
- `MVP-021`
275+
- TLS default posture is broadly independent of most unresolved protocol questions.
276+
- `MVP-024`
277+
- Basic log correlation and status surfaces can begin before observability scope is finalized.
278+
- `MVP-025`
279+
- Acceptance coverage scaffolding can be built incrementally while implementation proceeds.
280+
281+
### Safe To Start If Assumptions Remain Explicit
282+
283+
- `MVP-005`
284+
- Can begin before `MVP-001` is fully closed if pricing authority remains clearly non-final in the API/implementation.
285+
- `MVP-003`
286+
- Some schema design can begin while `MVP-027` is being narrowed, but it should not be treated as finalized until identity semantics are stable.
287+
- `MVP-024`
288+
- Can proceed in a reduced/basic form before `MVP-023` is fully closed.
289+
290+
### Should Usually Wait
291+
292+
- `MVP-007`
293+
- Should wait until the chain/network and pricing exposure contracts are stable enough.
294+
- `MVP-013`
295+
- Should wait until reconnect semantics and durable provider state are both stable enough.
296+
- `MVP-019` and `MVP-020`
297+
- Should wait until retrieval APIs, auth, and collection lifecycle semantics are in place.
298+
299+
## Prompting Guidance For Sequenced Work
300+
301+
When prompting an agent, reference both the task and its place in the sequencing.
302+
303+
Recommended pattern:
304+
305+
1. State the current phase or lane.
306+
2. State the exact `MVP-###` task.
307+
3. Name the resolved prerequisites the agent is allowed to rely on.
308+
4. Name any unresolved upstream questions the agent must not answer implicitly in code.
309+
310+
Example:
311+
312+
```text
313+
We are currently in Phase 1, Runtime foundation.
314+
Implement MVP-010 only.
315+
You may rely on MVP-004 as the frozen runtime billing/payment contract.
316+
Do not broaden into MVP-011 or MVP-016 except for strictly necessary supporting edits.
317+
If you find that MVP-010 still requires unresolved semantics beyond MVP-004, mark it blocked instead of choosing an implicit contract in code.
318+
```
319+
320+
## Notes
321+
322+
- This document derives sequence from the current dependency structure in `plans/mvp-implementation-backlog.md`.
323+
- If task dependencies change, this document should be updated to match.
324+
- When the backlog and this document disagree, the backlog is the source of truth.

‎docs/mvp-scope.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -316,7 +316,13 @@ The scenarios below are the primary definition of done for the MVP.
316316

317317
## Open Questions
318318

319-
- Should chain/network be derived automatically from the Substreams package, or supplied explicitly to the oracle query path?
319+
- The chain/network discovery input contract is narrowed for MVP:
320+
- consumer sidecar derives network from the Substreams package by default
321+
- if a package/module resolves a specific `networks` entry, that takes precedence over top-level `network`
322+
- explicit user-supplied network input remains supported only as fallback when package derivation is unavailable
323+
- if both explicit input and package-derived network exist and differ after normalization, the request fails fast
324+
- if neither source yields a usable network, the request fails fast
325+
- SDS uses the same canonical network keys as the Graph networks registry for MVP, with repo-owned/pinned mappings rather than live runtime registry lookups
320326
- What is the pricing authority contract between oracle metadata and provider handshake responses?
321327
- What is the exact canonical payment identity and `collection_id` reuse policy for fresh workloads versus reconnects?
322328
- How much of the reconnect/recovery state should be keyed by session versus on-chain payment identity?

‎plans/mvp-implementation-backlog.md‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,13 @@ Unless otherwise scoped, the baseline validation for code changes remains:
4242

4343
These assumptions are referenced by task ID so it is clear where unresolved decisions still matter.
4444

45-
- `A1` Chain/network discovery input is still open.
46-
- MVP work should support an explicit chain/network input path now.
47-
- Automatic derivation from the Substreams package remains optional/open.
45+
- `A1` Chain/network discovery input is narrowed for MVP, but implementation details still matter.
46+
- Consumer sidecar derives network from the Substreams package by default.
47+
- If a package/module resolves a specific `networks` entry, that takes precedence over top-level `network`.
48+
- Explicit input remains supported as fallback when package derivation is unavailable.
49+
- If both explicit input and derived package network exist and differ after normalization, fail fast.
50+
- If neither source yields a usable network, fail fast.
51+
- SDS should use repo-owned/pinned mappings to the Graph networks registry keys for MVP rather than live runtime registry lookups.
4852

4953
- `A2` Pricing authority between oracle metadata and provider handshake is still open.
5054
- MVP work should avoid hard-coding a final authority rule unless/until aligned with StreamingFast.
@@ -110,7 +114,7 @@ These assumptions are referenced by task ID so it is clear where unresolved deci
110114
| MVP-030 | `not_started` | provider-integration | none | `MVP-014`, `MVP-017` | `A`, `G` | Add runtime compatibility and preflight checks for real provider/plugin deployments |
111115
| MVP-031 | `not_started` | runtime-payment | none | `MVP-004`, `MVP-012`, `MVP-014`, `MVP-017` | `A`, `C` | Wire the live PaymentSession and RAV-control loop into the real client/provider runtime path |
112116
| MVP-032 | `not_started` | operations | `A3`, `A4`, `A5` | `MVP-003`, `MVP-008`, `MVP-010`, `MVP-022` | `B`, `C`, `D`, `F`, `G` | Expose operator runtime/session/payment inspection APIs and CLI/status flows |
113-
| MVP-033 | `open_question` | protocol | `A1` | none | `A` | Freeze the chain/network discovery input contract across client, sidecar, and oracle |
117+
| MVP-033 | `done` | protocol | `A1` | none | `A` | Freeze the chain/network discovery input contract across client, sidecar, and oracle |
114118

115119
## Protocol and Contract Tasks
116120

@@ -127,20 +131,25 @@ These assumptions are referenced by task ID so it is clear where unresolved deci
127131
- Update `docs/mvp-scope.md` open question if unresolved, or close it if decided.
128132
- Add or update integration/manual verification notes for whichever pricing source is actually consumed at runtime.
129133

130-
- [ ] MVP-033 Freeze the chain/network discovery input contract across client, sidecar, and oracle.
134+
- [x] MVP-033 Freeze the chain/network discovery input contract across client, sidecar, and oracle.
131135
- Context:
132136
- The MVP requires oracle-backed provider discovery keyed by chain/network context, but the source of that context is still open.
133137
- Leaving this only as an assumption risks incompatible implementations across the real client path, sidecar API, and oracle API.
134138
- Assumptions:
135139
- `A1`
136140
- Done when:
137141
- The repo defines the canonical chain/network identifier shape used by the oracle query path.
138-
- It is explicit whether the real client must supply chain/network directly, whether the sidecar may derive it, and what fallback behavior is allowed when derivation is unavailable.
139-
- Validation and error behavior are documented for missing, invalid, or unsupported chain/network inputs.
142+
- Consumer sidecar derives network from the Substreams package by default.
143+
- If a package/module resolves a specific `networks` entry, that takes precedence over top-level `network`.
144+
- Explicit input remains supported only as fallback when package derivation is unavailable.
145+
- If both explicit input and package-derived network exist and differ after normalization, the request fails fast.
146+
- If neither source yields a usable network, the request fails fast.
147+
- SDS uses the same canonical network keys as the Graph networks registry for MVP, with repo-owned/pinned mappings rather than live runtime registry lookups.
148+
- Consumer sidecar owns derivation, normalization, validation, and conflict detection.
140149
- MVP-005, MVP-007, and MVP-017 all point to the same contract.
141150
- Verify:
142-
- Update `docs/mvp-scope.md` open question if unresolved, or close/narrow it if decided.
143-
- Add contract-level tests or documented manual verification for valid, missing, and unsupported chain/network inputs.
151+
- Update `docs/mvp-scope.md` open question to reflect the narrowed contract.
152+
- Add contract-level tests or documented manual verification for package-derived network success, explicit-input fallback, mismatch rejection, and missing-network rejection.
144153

145154
- [ ] MVP-002 Freeze reconnect handshake semantics so provider can return fresh or latest-known resumable RAV during normal session init.
146155
- Context:

0 commit comments

Comments
 (0)