README
¶
Wave2 Architecture (Phased, Task-Native)
Wave2 is a clean-slate rewrite focused on the smallest architecture that still covers all required observable behavior.
Public Surfaces
wave2/wave.go: app-facing runtime APIwave2/wavebuild/wavebuild.go: build/dev phase pipeline plus framework-signal contractwave2/wavefw/wavefw.go: framework-facing signal translation
Runtime/Buildtime Boundary
This split is strict:
wave2is runtime-facing and must stay free of build/dev-heavy dependencies.wave2/wavebuildis build/dev orchestration.wave2must never importwave2/wavebuild.
This keeps production binaries lean and prevents file-watching/build toolchain weight from leaking into runtime application servers.
Canonical Pipeline
Wave2 orchestration is phase-based:
eventsbuildbackend_settlingfrontend_settling
Mode policy:
devexecutes phases 1-4.prodbypasses phases 1/3/4 and executes phase 2 only.
Each phase:
- plans terminal goals for that phase
- runs terminal roots in
kit/tasks - lets
kit/tasksown prerequisite ordering, dedupe, and parallelism - frontend settling uses one terminal browser action with explicit precedence
- notify-Vite failure heals through backend restart/readiness; current policy then applies hard reload when Vite restart occurs
Task Context Contract
One batch-scoped tasks.Ctx is shared across all executed phases in a batch.
That gives:
- one identity domain for all task keys in the batch
- one cache domain for task outputs reused by downstream callers
- no second DAG scheduler outside
kit/tasks
Execution Port Contract
Terminal side effects are emitted through one explicit execution port:
- one phase-effect task
- keyed by an explicit phase-effect request
- invoked directly by terminal phase tasks
- phase-effect result carries effect outcomes needed by later planners
This keeps phase planning pure while allowing side-effect implementation to be swapped without changing the task graph.
Framework Boundary
Wave2 emits framework-agnostic signals.
wavefw translates those signals into framework-owned actions. Wave2 does not
encode framework endpoint names, conventions, or transport details.
Documentation
¶
Overview ¶
Package wave2 is the app-facing runtime API for Wave2 applications.
This package intentionally excludes build/dev orchestration concerns so production applications keep a lean runtime dependency surface.
Index ¶
Constants ¶
const RuntimeConfigPath = "wave_owned/runtime_cfg.json"
RuntimeConfigPath is the fixed runtime-config artifact path relative to dist-static root.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// DistStaticFS is the dist static filesystem root containing generated
// Wave2 runtime artifacts.
//
// In production, you probably want to use `embed.FS`.
// In development, leave this field null (the dev server doesn't even use it,
// and you can improve speed by avoid the `embed.FS` compilation overhead).
DistStaticFS fs.FS
// Logger is the optional runtime logger used by Wave2.
Logger *slog.Logger
}
Options configures Wave2 runtime construction from generated dist artifacts.
type RuntimeConfig ¶
type RuntimeConfig struct {
PublicPathPrefix string `json:"public_path_prefix"`
}
RuntimeConfig is the generated runtime-config artifact loaded by Wave2.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package wavebuild defines the build/dev orchestration contracts for Wave2.
|
Package wavebuild defines the build/dev orchestration contracts for Wave2. |
|
Package wavefw provides the framework-facing adapter API for Wave2.
|
Package wavefw provides the framework-facing adapter API for Wave2. |