weft
ir 2.6.0 · warp 1.8.0
generatedwalked out of the package's public entry

@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.

61exports
61with a doc comment on the declaration

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

packages/plan/src/dsl.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/facts.ts

factsOf function

export function factsOf(entry: TemplateIR): SlotFacts { … }

One fragment's facts.

packages/plan/src/facts.ts

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

packages/plan/src/facts.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/lower.ts

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.

packages/plan/src/facts.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/lower.ts

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

packages/plan/src/lower.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/verify.ts

why function

export function why(input: WhyInput): WhyReport { … }

The plan with its provenance attached, which is what makes a generated plan reviewable.

packages/plan/src/why.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/dsl.ts

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.

packages/plan/src/facts.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/lower.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/lower.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/lower.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/verify.ts

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

packages/plan/src/lower.ts

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

packages/plan/src/verify.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/lower.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/verify.ts

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

packages/plan/src/verify.ts

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.

packages/plan/src/why.ts

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.

packages/plan/src/why.ts

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

packages/plan/src/dsl.ts

ExecutorTarget type

export type ExecutorTarget = string

The 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

packages/plan/src/dsl.ts

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

packages/plan/src/lower.ts

PlanEntry type

export type PlanEntry = SlotBuilder | RegionBuilder | GuardSpec | ShellSpec

Anything 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

packages/plan/src/dsl.ts

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

packages/plan/src/validate.ts

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

packages/plan/src/lower.ts

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

packages/plan/src/dsl.ts

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

packages/plan/src/dsl.ts