@weftjs/plan
Placement, declared and then checked against what the compiler inferred. A plan that contradicts a derivation loses, at build time, with the read that caused it named.
Read out of packages/plan/src/index.ts, the package’s public entry, so this page is the surface itself rather than a description of it.
and
function
export function and(a: Condition, b: Condition): Condition { … }Two conditions as one. Sorted, so and(visible, focused) and its reverse are the same value.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
assertPlan
function
export function assertPlan(plan: Plan, context: ValidateContext): Plan { … }The same rules, as a gate. Throws E_PLAN_INVALID with a line per error.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
Specified inspec/plan/plan.md
bytes
function
export function bytes(spec: string | number): number { … }'8kb' and 8192 are the same ceiling. A bad spelling is refused rather than coerced to zero.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
cspOf
function
export function cspOf(plan: Plan, errors: Issue[] = []): Record<string, string[]> { … }The regions' CSP directives, merged; 'none' beside anything else is the one shape that's a conflict, not a union. See spec/kernel/composition.md.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
every
function
export function every(spec: string | number): number { … }every('30s') in milliseconds. A bare number is already milliseconds.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
Specified inspec/plan/plan.md
factsFrom
function
export function factsFrom(
modules: readonly { fragments: readonly { entry: TemplateIR }[] }[],
): Record<string, SlotFacts> { … }Keyed by the compiler's own id — module#export — because that is what a plan names.
Specified inspec/kernel/routing.md
factsOf
function
export function factsOf(entry: TemplateIR): SlotFacts { … }One fragment's facts.
fillableHoles
function
export function fillableHoles(holes: readonly Hole[]): string[] { … }A boundary this render does not own: a streaming hole, or an instance the compiler isolated.
Specified inspec/kernel/routing.md
guard
function
export function guard(name: string, options: { redirect?: string; status?: number } = {}): GuardSpec { … }A plan-level declaration that runs in phase A by construction. See spec/plan/plan.md.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
Specified inspec/kernel/cache.md·spec/plan/plan.md
hopsOf
function
export function hopsOf(plan: Plan): HopCount { … }How many tier boundaries this page crosses. The answer to "how much latency", not "made of what".
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
Specified inspec/kernel/composition.md·spec/plan/plan.md
locusOf
function
export function locusOf(target: string): RenderLocus { … }Where an executor target runs: this thread, a deferred slice, a pool, or another deployment.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
Specified inspec/plan/plan.md
lowerPlan
function
export function lowerPlan(plan: Plan, context: ValidateContext, bindings: RouteBindings): RouteResolver { … }A validated plan plus its bindings into a resolver the kernel can call per request. See spec/kernel/routing.md.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
Specified inspec/kernel/routing.md
nestedHoles
function
export function nestedHoles(holes: readonly Hole[]): number { … }Holes a content-addressed segment memo could serve: a nested list row, or a component instance.
plan
function
export function plan(route: string, entries: readonly PlanEntry[] = [], options: PlanOptions = {}): Plan { … }A plan from its entries. Refuses two shells and a duplicated slot name here, since neither needs the compiler's facts to answer.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
Specified inspec/VERSIONING.md·spec/plan/plan.md
region
function
export function region(name: string): RegionBuilder { … }A slot whose renderer may live on another deployment. Which one is the registry's answer.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
Specified inspec/kernel/composition.md·spec/kernel/ports.md·spec/plan/plan.md
regionSpecOf
function
export function regionSpecOf(
spec: SlotSpec,
decl: RegionDecl,
degraded?: { fallback?: Uint8Array; placeholder?: Uint8Array },
): RegionSpec { … }What the composer is told about a region, derived from the plan rather than declared twice. See spec/kernel/composition.md.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
Specified inspec/plan/plan.md
routeEntry
function
export function routeEntry(plan: Plan, context: ValidateContext, bindings: RouteBindings): LoweredRoute { … }The same, as a row for the router: the pattern and the resolver together.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
shell
function
export function shell(fragment: string, nested: readonly ShellNesting[] = []): ShellSpec { … }The document a route renders into, optionally a chain of layouts nested inside it.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
Specified inspec/kernel/routing.md
slot
function
export function slot(name: string): SlotBuilder { … }A slot by the name of the hole it fills. Every other property is chained onto it.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
Specified inspec/compiler/supported-subset.md·spec/ir/template-ir-2.md·spec/kernel/routing.md·spec/kernel/surgical.md·spec/plan/plan.md
validatePlan
function
export function validatePlan(plan: Plan, context: ValidateContext): Diagnostics { … }Every rule, against one plan. Returns what it found rather than throwing, so a report can print it.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
Specified inspec/compiler/effects.md
verifyRegions
function
export async function verifyRegions(
plans: readonly Plan[],
context: VerifyContext,
probe?: (binding: RegionBinding) => Promise<Uint8Array>,
): Promise<VerifyReport> { … }Ask each region what it is serving. A disagreement is what weft verify --probe exits non-zero on.
Raised in this fileE_NO_REGION_REGISTRY·E_NO_SUCH_REGION·E_REGION_CONTRACT·E_REGION_LOCUS_MISMATCH·E_REGION_UNREACHABLE·E_UNKNOWN_EXECUTOR·W_REGION_TREE_DEEPER
Specified inspec/kernel/composition.md·spec/plan/plan.md
why
function
export function why(input: WhyInput): WhyReport { … }The plan with its provenance attached, which is what makes a generated plan reviewable.
PlanError
class
export class PlanError extends Error {
code: string
constructor(code: string, message: string) {
super(`${code} — ${message}`)
this.name = 'PlanError'
this.code = code
}
}A plan refusal, carrying the code so a caller can branch on it rather than on the text.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
CacheSpec
interface
export interface CacheSpec {
class: PolicyClass
ttlMs?: number
staleWhileRevalidateMs?: number
tags?: string[]
/** Checked against the store's declared consistency at build time. */
consistency?: 'eventual' | 'strong'
}What a slot's cache entry is: its class, how long it lives, and what invalidates it.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
CompiledEntry
interface
export interface CompiledEntry {
entry: TemplateIR
}What the plan layer is allowed to know about a fragment. Every field is derived from what the compiler emitted. See spec/plan/plan.md.
Diagnostics
interface
export interface Diagnostics {
errors: Issue[]
warnings: Issue[]
}Everything wrong with a plan, split by whether it stops the build.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
FormSpec
interface
export interface FormSpec {
prefer?: WireForm
fallback?: WireForm
}Which wire form a slot would rather send, and what it falls back to.
A preference, never a guarantee: the form actually used is the smallest one the client can prove it can apply, and every form of a fragment produces identical bytes anyway.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
FragmentSource
interface
export interface FragmentSource {
entry: TemplateIR
/** Nested row and component templates, by version. */
resolve?(version: string): TemplateIR | undefined
}The seam: a plan and some compiled fragments become a route. See spec/kernel/routing.md.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
GuardSpec
interface
export interface GuardSpec {
name: string
redirect?: string
status?: number
}A guard by name, and what a refusal does: a real redirect or a real status, both in phase A.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
HopCount
interface
export interface HopCount {
regions: number
remote: number
/** Boundaries this plan crosses on one request. A floor: a region that fans out further adds its own. */
hops: number
}The fan-out, as a number the build states rather than a number a deployment discovers — a floor, not an estimate. See spec/kernel/composition.md.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
Issue
interface
export interface Issue {
code: string
slot?: string
message: string
}One problem with a plan: its code, the slot it is about, and a sentence.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
LoweredRoute
interface
export interface LoweredRoute {
pattern: string
value: RouteResolver
}One entry per route in a table the kernel can match against.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
Plan
interface
export interface Plan {
route: string
/** The outermost fragment of the document. Absent only for a plan with no slots. */
shell?: string
/** Layouts nested inside `shell`, outermost first. Absent for the single-document case. See `spec/kernel/routing.md`. */
shellChain?: readonly ShellNesting[]
guards: GuardSpec[]
slots: SlotSpec[]
/** Signals the shell offers its regions, by name — deliberately the only channel between them. See `spec/kernel/composition.md`. */
exposes: string[]
/** The document's own policy: what the response advertises, checked against the strictest class among the shell and its slots. */
cache?: CacheSpec
/** Per-request ceiling. Forty concurrent queries from one page request will melt a database. */
maxConcurrency: number
}A route's placement, delivery and policy, resolved. Generated from the file convention, not a build configuration.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
PlanOptions
interface
export interface PlanOptions {
maxConcurrency?: number
/** Signals the shell exposes to its regions. The only channel between them. */
exposes?: readonly string[]
/** The document's `Cache-Control`, validated against what the shell and its slots read. */
cache?: {
class: PolicyClass
ttl?: string | number
swr?: string | number
tags?: string[]
consistency?: 'eventual' | 'strong'
}
}What belongs to the plan rather than to any one slot: concurrency, the exposed set, the document's policy.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
RefreshSpec
interface
export interface RefreshSpec {
everyMs: number
when?: Condition
}How often a live region re-renders, and the conditions under which the interval applies.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
RegionBindings
interface
export interface RegionBindings {
ports: Ports
/** What a region is told beyond the route and its params. A function of the params: a closure cannot survive the serialisation. */
request?(params: Record<string, string>): RegionRequest
/** The bytes behind a region's declared degradation, by region name — not the slot binding, since a remote region has none. */
degraded?: Record<string, { fallback?: Uint8Array; placeholder?: Uint8Array }>
}What a region needs beyond a slot: the ports, the request, and the bytes behind its degradation.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
RegionBuilder
interface
export interface RegionBuilder {
readonly spec: SlotSpec
/** This process renders it, from the named fragment. The monolith, and the default. */
local(fragment?: string): RegionBuilder
/** It crosses a deployment boundary. Which one is the registry's answer, not the shell's. */
remote(contract?: RegionContract): RegionBuilder
contract(id: string, version: string, reads?: readonly string[]): RegionBuilder
/** Rendered in its place when it fails. */
fallback(fragment: string): RegionBuilder
/** Failure is invisible. An empty hole, and nobody is paged. */
optional(): RegionBuilder
/** Directives this region needs. Merged into the document's, and refused when they contradict. */
csp(directives: Record<string, readonly string[]>): RegionBuilder
/** Exposed signals this region reads. Checked against what the shell exposes. */
consumes(...signals: string
…The region builder. A region is a slot — the whole implementation strategy, not a shortcut. See spec/kernel/composition.md.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
RegionDecl
interface
export interface RegionDecl {
locus: 'local' | 'remote'
/** What this shell was built expecting the region to serve. */
contract?: RegionContract
/** Directives this region needs, merged into the document's policy and refused when they conflict. */
csp?: Record<string, readonly string[]>
/** Exposed signals this region consumes. Checked against what the shell exposes. */
consumes?: readonly string[]
/** A fragment rendered in this region's place when it fails. The design's `fallback('static:…')`. */
fallback?: string
/** Failure is invisible: an empty hole and nobody paged. `placeholder` with no placeholder. */
optional?: boolean
/** Ours, and in the first flush. A region that is `critical` may not be remote. */
critical?: boolean
}What a shell declares about a region — everything except where it runs, which is the registry's. See spec/kernel/composition.md.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
RegionStatus
interface
export interface RegionStatus {
region: string
route: string
declared: 'local' | 'remote'
/** What the registry says, when it has an entry. */
bound?: RegionBinding
/** What the region answered when it was asked, for a verification that probes. */
serving?: { contract?: string; revision?: string; reads?: readonly string[] }
/** What it said it composes in turn. Empty for a leaf; absent for a region nobody asked. */
tree?: readonly RegionNode[]
issues: Issue[]
}What one region says it is serving right now, against what this build expected.
Raised in this fileE_NO_REGION_REGISTRY·E_NO_SUCH_REGION·E_REGION_CONTRACT·E_REGION_LOCUS_MISMATCH·E_REGION_UNREACHABLE·E_UNKNOWN_EXECUTOR·W_REGION_TREE_DEEPER
RouteBindings
interface
export interface RouteBindings {
shell: FragmentSource
/** Layouts nested inside `shell`, outermost first, matching `plan.shellChain`. Disagreement is `E_SHELL_CHAIN_MISMATCH`. */
nested?: readonly (FragmentSource & { at: string })[]
/** The shell's non-slot values, a function of matched params only. See `spec/kernel/routing.md`. */
shellValues?(params: Record<string, string>): Values | Promise<Values>
slots: Record<string, SlotBinding>
guards?: Record<string, GuardHandler>
/** Phase A work beyond the guards. */
envelope?(ctx: EnvelopeContext): void | Promise<void>
critical?: PreloadLink[]
/** Overrides the order derived from the plan's slot deliveries. */
order?: Order
/** Who turns this route's fragments into bytes. Without one, the IR renderer is called directly. An `.incremental()` slot renders through its own memo either way. See `spec/kernel/p
…The bytes-producers behind a plan. The plan says what; this says with what.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
RouteGraph
interface
export interface RouteGraph {
route: string
regions: readonly RegionNode[]
/** Every boundary this route crosses, through the whole tree rather than the first level of it. */
hops: number
/** What the plan counted, which sees only the regions the route itself declares. */
declared: number
}One route's regions as a graph, which is the thing a hop count was standing in for. See spec/kernel/composition.md.
Raised in this fileE_NO_REGION_REGISTRY·E_NO_SUCH_REGION·E_REGION_CONTRACT·E_REGION_LOCUS_MISMATCH·E_REGION_UNREACHABLE·E_UNKNOWN_EXECUTOR·W_REGION_TREE_DEEPER
ShellNesting
interface
export interface ShellNesting {
/** The slot hole of the enclosing layout this one fills. */
at: string
/** The fragment that fills it, which is itself a layout with holes of its own. */
fragment: string
}One link in a chain: the layout, and the hole of the enclosing one it fills.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
ShellSpec
interface
export interface ShellSpec {
shell: string
/** Layouts nested inside it, outermost first: `[{ at: 'body', fragment: 'layout:dashboard' }]`. See `spec/kernel/routing.md`. */
nested?: readonly ShellNesting[]
}Which fragment is the document. Its slot holes are the boundaries the plan's slots fill, and the two sets have to agree exactly — a declaration naming a hole the shell does not have, or a hole nothing fills, is a build error rather than an empty region in production.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
SlotBinding
interface
export interface SlotBinding {
fragment: FragmentSource
values: SlotValues
/** Rendered when the slot degrades. Without one a degraded slot is empty, which is honest. */
placeholder?: Uint8Array
/** Where this slot's render can be reached by name, for an executor a closure cannot go to. `E_SLOT_NOT_ADDRESSABLE` if missing. */
address?: JobAddress
}What actually renders a slot: the fragment, its values, and where it can be reached by name.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
SlotBudgetSpec
interface
export interface SlotBudgetSpec {
cpuMs?: number
jsBytes?: number
/** A cap on regression against the base branch. A ceiling alone produces permanent silence at 39.8 KB. */
growBytes?: number
onExceed?: ExceedPolicy
}A slot's ceilings, already parsed. SlotBuilder.budget takes the human spellings.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
SlotBuilder
interface
export interface SlotBuilder {
readonly spec: SlotSpec
fragment(id: string): SlotBuilder
stream(options?: { prio?: number }): SlotBuilder
buffered(): SlotBuilder
executor(target: ExecutorTarget): SlotBuilder
budget(spec: {
cpu?: string | number
js?: string | number
grow?: string | number
onExceed?: ExceedPolicy
}): SlotBuilder
cache(
cls: PolicyClass,
options?: {
ttl?: string | number
swr?: string | number
tags?: string[]
consistency?: 'eventual' | 'strong'
},
): SlotBuilder
refresh(everyMs: number, options?: { when?: Condition }): SlotBuilder
form(spec: FormSpec): SlotBuilder
/** Data dependency only. A slot that merely sits inside another does not declare this. */
needs(...slots: string[]): SlotBuilder
incremental(): SlotBuilder
speculate(mode?: boolean | 'profile'): SlotBuilder
}The chained form of a SlotSpec. A builder, not a literal, because every call has a rule checked elsewhere attached to it.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
SlotFacts
interface
export interface SlotFacts {
/** Module and export, as the compiler names it. */
id: string
version: string
effects: EffectSet
/** Forms the template can serve, derived by the compiler. */
forms: readonly WireForm[]
/** Boundary names this fragment leaves for somebody else to fill: `slot` holes and isolated instances. */
fillable?: readonly string[]
/** Derived values a memoized recompute could skip. The design's second memoisation level. */
derivedCount?: number
/** Nested templates a content-addressed memo could reuse. The design's third level. */
nestedCount?: number
}The plan is checked against what the compiler inferred, never the other way around. See spec/plan/plan.md.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
Specified inspec/plan/plan.md
SlotSpec
interface
export interface SlotSpec {
name: string
/** The compiled fragment this slot renders: module and export, as the compiler names it. */
fragment?: string
delivery: 'stream' | 'buffered'
prio: number
executor: ExecutorTarget
needs: string[]
budget?: SlotBudgetSpec
cache?: CacheSpec
refresh?: RefreshSpec
form?: FormSpec
incremental: boolean
speculate: boolean | 'profile'
/** Set when this slot is a region: a fragment that may live on another deployment. */
region?: RegionDecl
}One slot, fully resolved: what renders it, when its bytes arrive, where it runs, what it may spend, and what may be done to it later. This is what lowerPlan reads and weft why prints.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
ValidateContext
interface
export interface ValidateContext {
facts: Record<string, SlotFacts>
/** Executor names the deployment actually binds. `inline` and `client` always exist. */
executors?: readonly string[]
store?: { consistency: Consistency; name: string; scope?: Scope }
/** How many instances of this deployment run at once. Defaults to 1. See `spec/plan/plan.md`. */
instances?: number
/** Subrequests one request may make before a platform ceiling. Defaults to Workers' documented 50. */
subrequestCeiling?: number
}What a plan is checked against: the compiler's facts, and what the deployment bound.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
VerifyContext
interface
export interface VerifyContext {
registry?: Registry
/** Executor names this deployment binds. */
executors?: readonly string[]
}The checks a build cannot do, run where the answers exist. See spec/kernel/composition.md.
Raised in this fileE_NO_REGION_REGISTRY·E_NO_SUCH_REGION·E_REGION_CONTRACT·E_REGION_LOCUS_MISMATCH·E_REGION_UNREACHABLE·E_UNKNOWN_EXECUTOR·W_REGION_TREE_DEEPER
VerifyReport
interface
export interface VerifyReport {
regions: RegionStatus[]
errors: Issue[]
warnings: Issue[]
text: string
/** Empty without `--probe`: a topology is what deployments answer, not what a plan says. */
graph: readonly RouteGraph[]
}Every region probed, and whether any of them disagreed with the manifest.
Raised in this fileE_NO_REGION_REGISTRY·E_NO_SUCH_REGION·E_REGION_CONTRACT·E_REGION_LOCUS_MISMATCH·E_REGION_UNREACHABLE·E_UNKNOWN_EXECUTOR·W_REGION_TREE_DEEPER
WhyInput
interface
export interface WhyInput {
plan: Plan
facts: Record<string, SlotFacts>
/** Measured milliseconds per slot. Absent slots are reported as unmeasured. */
timings?: Record<string, number>
/** Keys resolved for one concrete request, when this is being asked at runtime. */
resolved?: Record<string, ResolvedKey>
}weft why — the critical path as a first-class concept. See spec/plan/plan.md.
WhyReport
interface
export interface WhyReport {
text: string
waves: string[][]
criticalPath: string[]
criticalMs: number
sequentialMs: number
measured: boolean
}One route explained: every slot, and where each fact about it came from.
Condition
type
export type Condition = { all: string[] }Conditions a refresh waits for, all of which must hold. Order-free, so and can sort.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
ExecutorTarget
type
export type ExecutorTarget = stringThe plan: a declaration about placement, never a cache key. See spec/plan/plan.md.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
GuardHandler
type
export type GuardHandler = (ctx: EnvelopeContext) => boolean | Promise<boolean>A guard runs in phase A by construction, which is the whole reason guards are a plan-level declaration. Returning false applies the declared redirect or status — a real one, on a response whose envelope is still open.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
PlanEntry
type
export type PlanEntry = SlotBuilder | RegionBuilder | GuardSpec | ShellSpecAnything that can go in a plan: a slot, a region, a guard, or the document itself.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
RenderLocus
type
export type RenderLocus = 'process' | 'client' | 'remote'Where a slot's render happens: this process, the browser, or another deployment. Not the same question as a crash domain. See spec/plan/plan.md.
Raised in this fileE_CACHE_POLICY_CONFLICT·E_CONSISTENCY_MISMATCH·E_CSP_CONFLICT·E_DOCUMENT_POLICY_CONFLICT·E_FORM_UNAVAILABLE·E_NO_SHELL·E_NO_SUCH_FRAGMENT·E_NOT_EXPOSED·E_PLAN_INVALID·E_REGION_CONTRACT_LOCAL·E_REGION_CRITICAL_REMOTE·E_REGION_EXECUTOR·E_RENDER_LOCATION·E_SHELL_HOLE_UNFILLED·E_SHELL_LINK_UNPLACED·E_SLOT_NOT_IN_SHELL·E_TAGS_PROCESS_SCOPED·E_TTL_REQUIRED·E_UNKNOWN_EXECUTOR·E_UNKNOWN_SLOT·W_CPU_BUDGET_ADVISORY·W_DOCUMENT_OUTLIVES_INVALIDATION·W_HOP_COUNT·W_INCREMENTAL_NO_GRAPH·W_REGION_TAGS_UNREACHABLE·W_TTL_ON_STATIC·W_TTL_UNDECLARED·W_WAVE_WIDTH
SlotValues
type
export type SlotValues = (ctx: RenderContext, params: Record<string, string>) => Values | Promise<Values>What a slot renders with. It runs in phase B, so its context has the read surface and no envelope methods — which is why this signature can hand it ctx at all.
Raised in this fileE_NO_REGION_BINDINGS·E_REGION_BOUND_LOCALLY·E_REGION_FALLBACK_UNBOUND·E_SHELL_CHAIN_MISMATCH·E_SLOT_NOT_ADDRESSABLE·E_SLOT_UNBOUND·E_UNKNOWN_GUARD
REGION_EXECUTOR
const
export const REGION_EXECUTOR = 'region'The reserved executor name meaning "the registry decides".
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT
when
const
export const when = {
get visible(): Condition {
return condition('visible')
},
get focused(): Condition {
return condition('focused')
},
get idle(): Condition {
return condition('idle')
},
get always(): Condition {
return condition('always')
},
hover(selector: string): Condition {
return condition(`hover(${selector})`)
},
}The condition vocabulary a refresh may wait for — names rather than predicates, since only the client can evaluate them.
Raised in this fileE_BAD_DURATION·E_BAD_SIZE·E_DUPLICATE_SHELL·E_DUPLICATE_SLOT