Planning Status

This page summarizes the operational state in .planning/. When artifacts disagree with code or root docs, .planning/ wins.

Current State

Field	Value
Milestone	v1.8 Advanced Billing Features
Status	Verified complete (all 3 phases, all plans)
Phase 45 (Streaming Engine)	COMPLETE — 12 plans, 23 requirements
Phase 46 (Plan Upgrades + Multi-Token)	COMPLETE — 16 plans, 24 requirements
Phase 47 (Webhook SDK + Staging Closure)	COMPLETE — 18 plans, 22 requirements
Total plans (v1.8)	46 plans across 3 phases
Last activity	2026-04-17
Next milestone	v1.9 not yet defined

v1.8 was originally scoped as 5 phases (A→B→C→D with E parallel) but was consolidated to 3 phases via aggressive merge:

• Phase 46 merges Plan Upgrades + Multi-Token Activation because both touch SDK builders, dashboard UI, and webhook event tagging; upgrade proration already handles multi-token decimals.
• Phase 47 merges Webhook SDK + Staging Closure because Webhook SDK consumes stabilized events from Phases 45+46, and Playwright E2E naturally validates webhook delivery.

What Lives in .planning/

Core State Files

Path	Role	Format
PROJECT.md	Canonical current-state summary — what the project is, core value, current milestone, validated/active/out-of-scope requirements, key decisions, architecture, constraints	Markdown
STATE.md	Current execution state — milestone, phase, plan progress, performance metrics, accumulated context, decisions, blockers	Markdown + YAML frontmatter
ROADMAP.md	Full milestone and phase history with expandable details per phase	Markdown with <details> blocks
REQUIREMENTS.md	Product requirements organized by milestone with validation state and traceability	Markdown with checkboxes
MILESTONES.md	Milestone completion log — shipped dates, phase/plan counts, key accomplishments	Markdown
RETROSPECTIVE.md	Process retrospective — what worked, what didn't, process evolution	Markdown
config.json	GSD workflow configuration — model profile, workflow toggles	JSON

Subdirectories

Path	Role
milestones/	Per-milestone roadmaps and audit artifacts (v1.0-ROADMAP.md, v1.8-MILESTONE-AUDIT.md, etc.)
phases/	Phase-specific plan files (45-01-PLAN.md), summaries (45-01-SUMMARY.md), and design docs
notes/	Scope decisions (v1.8-scope-decisions.md), design documents (v1.8-streaming-engine-design.md)
research/	Reusable research — STACK.md, ARCHITECTURE.md, questions.md
quick/	Quick-task execution records (260404-da6-PLAN.md + matching summaries)
workstreams/	Legacy workstream structure from v1.2 era
seeds/	Forward-looking ideas with trigger conditions
todos/	Pending work items not yet promoted to phases
debug/	Debug session state for cross-session continuity
tmp/	Temporary working files (ephemeral)

Legacy Milestone Audits

Path	Milestone
v1.1-MILESTONE-AUDIT.md	Arcium Privacy Layer audit
v1.5-MILESTONE-AUDIT.md	Hosted Checkout & Billing audit (tech debt accepted)
v1.8-MILESTONE-AUDIT.md	Advanced Billing Features audit

Milestone History

Milestone	Phases	Plans	Shipped	Timeline	Key Accomplishment
v1.0 Foundation	5	20	2026-03-31	2 days	Protocol core, SDK, dashboard, landing page, docs — the billing primitive works
v1.1 Arcium Privacy Layer	8	26	2026-04-02	2 days	Wrapped USDC, transfer hooks, keeper automation, private analytics pipeline
v1.2 Protocol Admin Dashboard	10	36	2026-04-06	4 days	Admin auth, monitoring, emergency controls, observability, audit trail
v1.3 Merchant Login UX	3	13	2026-04-07	1 day	Email-primary auth, Google SSO, org management, TOTP 2FA
v1.4 Agent Mandates	2	13	2026-04-07	1 day	Scoped agent spending, x402 middleware, 15 SDK methods
v1.5 Hosted Checkout & Billing	7	37	2026-04-09	2 days	Checkout, invoicing, portal, pricing tables, analytics
v1.6 Docs Revamp	4	16	2026-04-10	1 day	60 MDX pages, custom Starlight theme, cookbook, Mermaid diagrams
v1.7 Protocol Modularity	5	29	2026-04-15	3 days	Versioned accounts, TokenConfig registry, upgradeable hook, SDK PDAFactory
v1.8 Advanced Billing Features	3	46	2026-04-17	2 days	Streaming engine, plan upgrades/proration, multi-token, webhook SDK, staging closure

Totals: 47 phases, 236+ plans, ~18 days of active development, 529+ commits.

Notable Observations by Milestone

• v1.0 proved the billing primitive works standalone (no Arcium needed for core value).
• v1.1 validated Arcium MPC integration — encrypted billing logic is viable.
• v1.2 was the largest milestone by phase count (10) and established the admin ops pattern.
• v1.3 made a critical strategic pivot from wallet-first to email-primary auth.
• v1.4 shipped in a single day — agent mandates were a focused, well-scoped feature.
• v1.5 was the largest by plan count (37) and accepted staging tech debt (closed in v1.8 Phase 47).
• v1.6 was a pure documentation milestone — no product code changed.
• v1.7 was infrastructure-only to unblock v1.8 — versioned accounts, dynamic hook, centralized PDAFactory.
• v1.8 consolidated 5 planned phases into 3 via aggressive merge and closed all remaining v1.5 staging debt.

Active Requirements (v1.8)

v1.8 covered 69 requirements across 5 requirement groups:

Group	Count	Phase	Description
STREAM	23	45	Streaming engine — StreamMandate PDA, rate-per-second, settle-then-mutate, fail-closed, SDK accruedNow()
UPGRADE	14	46	Plan upgrades/downgrades with proration — inline pending_upgrade, 3 upgrade instructions, 4-quadrant property tests
MULTI	10	46	Multi-token activation — TokenConfig end-to-end, token picker, formatAmount/parseAmount, admin kill-switch
WEBHOOK	12	47	Webhook SDK — @vela/webhook package, Zod-typed events, HMAC-SHA256, Svix-style retry, endpoint CRUD
STAGING	10	47	v1.5 staging closure — hosted invoices, Resend delivery, magic-link, switch-plan, Playwright+Mailpit E2E

Requirement Highlight: Streaming Engine

The streaming engine (Phase 45) is the most architecturally significant feature shipped in v1.8:

• New on-chain primitive: StreamMandate PDA with authorized_max_rate and settle-then-mutate invariant.
• Transfer hook streaming branch: Discriminator-first dispatch selects periodic vs streaming validation branch.
• Mathematical rigor: Settlement-frequency invariance property test (N settles over T ≡ 1 settle over T within rounding). 128-case proptest suite. u128 intermediates against u64::MAX near-boundary.
• SDK accruedNow(): Real-time accrued value computation client-side with zero RPC calls between settlements.
• Independent keeper: Stream settlement keeper is a separate Cloudflare Worker from periodic keeper.

Requirement Highlight: Webhook SDK

The webhook SDK (Phase 47) provides the developer experience layer for billing events:

• Zod-typed discriminated union over all Vela events (stream.* | mandate.* | pull.* | plan_change.*).
• HMAC-SHA256 verification using Stripe wire format (Vela-Signature: t=<ts>,v1=<hex>).
• Svix-style retry backoff: immediate → 5s → 5min → 30min → 2h → 5h → 10h → 10h.
• DLQ for exhausted deliveries with manual retry action.
• Dual-secret rotation with UI-driven endpoint management.
• CI schema-diff check enforces additive-only event evolution.

Performance Metrics

Aggregate Velocity

Metric	Value
Total plans completed	206+
Average plan duration	~15 minutes
Total execution time	~36 hours of agent time
Development span	18 days (2026-03-29 → 2026-04-17)
Total commits	529+
Average commits/day	~29

Per-Milestone Breakdown

Milestone	Phases	Plans	Days	Plans/Day
v1.0	5	20	2	10.0
v1.1	8	26	2	13.0
v1.2	10	36	4	9.0
v1.3	3	13	1	13.0
v1.4	2	13	1	13.0
v1.5	7	37	2	18.5
v1.6	4	16	1	16.0
v1.7	5	29	3	9.7
v1.8	3	46	2	23.0

Notable Phase Durations

Phase	Duration	Tasks	Files changed
Phase 45 P02	7 min	2	12
Phase 45 P03	3 min	2	5
Phase 45 P04	1 min	2	8
Phase 45 P05	663 min	2	9
Phase 47 P18	205 min	1	11

Key Decisions Accumulated

These decisions are recorded in STATE.md and PROJECT.md. They represent the accumulated architectural and product choices across all milestones.

Protocol Architecture

Decision	Rationale	Milestone
Dual-program split (protocol + transfer hook)	Transfer hook runs during transfer_checked — must be isolated for security. Any bug either lets merchants steal or blocks legitimate payments.	v1.0
Transfer hooks as billing engine (not unlimited approvals)	Solana-native, scoped authorization. EVM can't replicate.	v1.0
Arcium over Confidential Balances	Arcium handles arbitrary computation on encrypted data (usage, analytics, credit scoring). CB only encrypts balances/amounts.	v1.1
Versioned accounts with version: u8 + 64-byte reserved space	Enables additive field migrations without account closure cycles.	v1.7
Plan-independent mandate PDAs	Decouples mandates from plans so plan updates don't invalidate active subscriptions.	v1.7
Per-merchant credentials over per-plan credentials	Credentials track subscriber↔merchant relationship, not plan tier. Plan switching without re-minting.	v1.7
TokenConfig PDA registry over single-mint ProtocolConfig	Required for multi-token billing without breaking changes.	v1.7
Upgradeable transfer hook with dynamic ExtraAccountMetaList (8 slots)	Hook program evolves without redeploying the protocol.	v1.7
Centralized SDK PDAFactory	Single source of truth for PDA derivation prevents drift.	v1.7

Billing Design

Decision	Rationale	Milestone
Streaming is a distinct primitive (not periodic with period=1)	Pull-based with rate-per-second authorization and settle-then-mutate invariant.	v1.8
Upgrade state lives INLINE on Mandate v3 / StreamMandate v2	No separate UpgradeIntent PDA — uses v1.7 reserved space.	v1.8
Stream settlement keeper is SEPARATE from periodic keeper	Different cadence + failure semantics.	v1.8
Oracle lookup for USD display is CLIENT-SIDE via SDK helper	Not on-chain — plans are token-denominated. 60s TTL cache.	v1.8
Fail-closed on non-stream discriminators with WrongAccountType	No silent overdraft. Typed errors for every failure path.	v1.8

Product and Process

Decision	Rationale	Milestone
Email-primary auth over wallet-first	Merchants need traditional login; wallets are treasury tools, not identity.	v1.3
Admin Worker separate from dashboard Worker	Admin has distinct auth model and is never exposed to merchant traffic.	v1.2
EmergencyCancel credential derivation on-chain	D1 cache coupling was brittle for high-stakes cancellations.	v1.2
Hosted billing surfaces in separate repos	vela-checkout and vela-portal have public runtime concerns distinct from dashboard.	v1.5
Gap-closure phase pattern (Phase 43, Phase 44)	When verification reveals drift, spin a dedicated phase rather than retro-amending.	v1.7
Multi-repo (5→11 repos) over monorepo	Each component has different deploy lifecycle, security model, and team ownership.	v1.0+

Blockers/Concerns

Resolved

• v1.5 staging debt — Resolved in Phase 47. Hosted invoices, Resend delivery, portal magic-link, switch-plan, pricing-table returns, Queue/DLQ timing all validated via Playwright+Mailpit E2E.
• Phase 45 CU budget gate — Resolved. LiteSVM CU profile confirmed execute_stream is within budget.
• ExtraAccountMetaList slot enumeration — Resolved. 8 slots confirmed sufficient.
• Browser-safe SDK boundary — Resolved in Phase 46. @vela/sdk/browser barrel with focused deserialization and instruction-byte stability tests.

Currently Open

• v1.9 scope not defined — Next milestone is not yet planned. Seeds and backlog items in .planning/seeds/ and .planning/todos/ await triage.
• Production deployment — All work has been on devnet. Mainnet deployment planning is a separate workstream.
• Arcium production readiness — Arcium MPC is integrated but production MXE availability depends on Arcium's timeline.

Process Rules Implied by the Planning Layer

The .planning/ directory structure implies and enforces several process rules that have emerged across 8 milestones:

1. Workstream-Local Artifacts Matter

Phase outputs should stay inside the active workstream or milestone directory. When artifacts drift (Phase 42's verification revealed integration drift), a dedicated gap-closure phase is the correct response rather than retro-amending the original.

2. Quick Tasks Require Plan + Summary

.planning/quick/ is a real execution lane, not a notes folder. Every quick task gets both a *-PLAN.md and a *-SUMMARY.md. This enables session continuity and prevents duplicate work.

3. Audits Capture Completion + Gap Closure + Drift

Milestone audits (*MILESTONE-AUDIT.md) are expected to capture:

• What actually shipped vs. what was planned.
• Accepted tech debt with explicit justification.
• Cross-phase integration gaps.
• Nyquist validation coverage.

4. Project State is Incomplete Until All Artifacts Agree

PROJECT.md, STATE.md, ROADMAP.md, and REQUIREMENTS.md must all agree on current state. If STATE.md says "Phase 45 complete" but ROADMAP.md doesn't reflect it, the state is considered incomplete. Phase 44 exists specifically to enforce this rule (backfill summaries, reconcile checkboxes, correct scope headers).

5. Decisions Accumulate With Rationale

Every significant decision is logged in STATE.md and PROJECT.md with:

• What was decided.
• Why (rationale).
• Outcome (validated or adopted in which phase).

This prevents circular re-decision and enables new contributors to understand the reasoning behind architectural choices.

6. Machine-Readable State Enables Automation

STATE.md uses YAML frontmatter (gsd_state_version, milestone, status, progress) that can be parsed by tooling. This enables automated state tracking, progress reporting, and session continuity across agent boundaries.

7. Phase Merging is Valid When Dependencies Align

v1.8 consolidated from 5 phases to 3 because adjacent phases shared SDK builders, dashboard UI, and webhook event tagging. The planning layer supported this by making the dependency chain explicit — when Plan B and Plan C both touch the same code paths and Plan C's inputs are Plan B's outputs, merging is valid and reduces integration overhead.