plan

type Backend ¶

type Backend interface {
	// Compile executes one node against its materialised input tables
	// and returns the resulting output table. ctx propagation is
	// best-effort — impls may honour cancellation between rows or only
	// at op boundaries.
	Compile(ctx context.Context, node Node, ins []*table.Table) (*table.Table, error)
}

Backend is the contract the compiler uses to execute one DAG node against its materialised input tables. plan/nodes never call into Pulse (or any specific compute engine) directly: they route Execute through whichever Backend the builder injected. Concrete impls live in compile/ (the in-memory backend ships in P04; future Pulse / DuckDB / Arrow backends drop in behind the same interface).

The interface lives in plan/ — not compile/ — because every plan node consumes it. Inverting the layering would force plan/nodes to import compile/ and risk an import cycle (compile/ already imports plan/ for the Node interface). See D032.

Nodes with no injected backend fall back to PRISM_COMPILE_001 to preserve P03's stub semantics (see D033 for the injection mechanism).

type Builder ¶

type Builder struct {
	// contains filtered or unexported fields
}

Builder constructs a DAG. AddNode + MarkRoot + MarkSink populate state; Build validates the result and produces an immutable *DAG.

The Builder is intentionally narrow — no Edge() method, because edges are already implicit in each Node's Inputs(). Build verifies every input target exists in the node set and at least one sink exists.

func NewBuilder() *Builder

func (b *Builder) AddNode(n Node) error

func (b *Builder) AddNodeUnchecked(n Node)

func (b *Builder) Build() (*DAG, error)

func (b *Builder) BuildUnchecked() *DAG

func (b *Builder) MarkRoot(id NodeID) error

func (b *Builder) MarkSink(id NodeID) error

func (b *Builder) NodeIDs() map[NodeID]struct{}

type ChildDAG ¶

type ChildDAG struct {
	// DAG is the sub-plan for this child (one layer or one panel).
	DAG *DAG
	// Tip is the sub-plan's sole sink — the table the encoder reads.
	Tip NodeID
	// Spec is the merged child spec (parent datasets / data already
	// folded in by BuildComposite).
	Spec *spec.Spec
}

ChildDAG carries one child's plan + the encoder-facing spec. The spec is forwarded so the encoder can read the child's mark, encoding, title etc. without re-walking the parent.

type CompositeDAG ¶

type CompositeDAG struct {
	Kind     CompositeKind
	Rows     int
	Cols     int
	Children []ChildDAG
	Resolve  *spec.Resolve
}

CompositeDAG is the plan-stage representation of a composite spec (layer / concat / hconcat / vconcat). Per D049 + D050 each child owns its own sub-DAG; the executor handles each child independently via the existing plan.Execute entry point.

Layout metadata (Rows, Cols) is normalised by BuildComposite based on the composition kind:

• Layer: Rows=1, Cols=1 (cells flatten into one Scene's layers).
• HConcat: Rows=1, Cols=len(Children).
• VConcat: Rows=len(Children), Cols=1.
• Concat: treated as HConcat in v1 (D053).
• Facet: Rows=0, Cols=0 placeholders (D054); the encoder fills in concrete dimensions after partitioning the upstream table.
• Repeat: Rows=len(repeat.Row) or 1, Cols=len(repeat.Column) or 1 (D056); per-cell sub-DAGs land in Children in row-major order.

Resolve carries cross-layer scale / axis resolution and is only meaningful when Kind == CompositeLayer; concat ignores it (cross- panel shared scales arrive with facet in P09).

type CompositeKind ¶

type CompositeKind string

CompositeKind discriminates the six composition primitives Prism supports as of P09. Selection-rooted composition stays deferred to P13.

const (
	// CompositeLayer is `spec.Layer[]` — N layers in one chart with
	// (optional) cross-layer scale resolution.
	CompositeLayer CompositeKind = "layer"
	// CompositeConcat is `spec.Concat[]` — flat array of side-by-side
	// panels. In v1 this is functionally identical to CompositeHConcat
	// (D053); the `columns` wrap parameter lands in a future phase.
	CompositeConcat CompositeKind = "concat"
	// CompositeHConcat is `spec.HConcat[]` — 1 row × N cols.
	CompositeHConcat CompositeKind = "hconcat"
	// CompositeVConcat is `spec.VConcat[]` — N rows × 1 col.
	CompositeVConcat CompositeKind = "vconcat"
	// CompositeFacet is `spec.Facet{row, column}` — small multiples
	// driven by distinct values of the row / column field(s) (D054).
	// The builder returns a single shared sub-DAG (the parent's
	// pipeline); the encoder partitions the resulting Table by
	// `(row_value, col_value)` tuples and emits one SceneCell per
	// partition. `len(Children) == 1` is the convention "single
	// pipeline, encoder fans out" for facet.
	CompositeFacet CompositeKind = "facet"
	// CompositeRepeat is `spec.Repeat{row, column}` — small multiples
	// driven by a field-list. Each cell substitutes its field name
	// into the child spec and builds an independent sub-DAG (D056),
	// so `len(Children) == rows * cols` for repeat.
	CompositeRepeat CompositeKind = "repeat"
)

type DAG ¶

type DAG struct {
	// contains filtered or unexported fields
}

DAG is the immutable plan graph. Constructed via Builder; mutated only by optimizer passes that return new DAG instances with structural sharing (D017). All public accessors return sorted / stable views so downstream code (renderers, executor, tests) sees deterministic ordering across runs.

func Optimize(d *DAG, passes []Pass) (*DAG, error)

func (d *DAG) Dependents(id NodeID) []NodeID

func (d *DAG) Node(id NodeID) (Node, bool)

func (d *DAG) Nodes() []NodeID

func (d *DAG) Roots() []NodeID

func (d *DAG) Sinks() []NodeID

func (d *DAG) Size() int

func (d *DAG) TopoLevels() ([][]NodeID, error)

func (d *DAG) WithNode(n Node) *DAG

func (d *DAG) WithRootAdded(id NodeID) *DAG

func (d *DAG) WithSinkAdded(id NodeID) *DAG

func (d *DAG) WithoutNode(id NodeID) *DAG

type ExecOpts ¶

type ExecOpts struct {
	// Workers is the upper bound on goroutines per level. 0 = consult
	// PRISM_QUERY_WORKERS (set positive) else runtime.NumCPU(); 1 =
	// strictly sequential.
	Workers        int
	Cache          TableCache
	JoinMaxRows    int
	PerNodeTimeout time.Duration
	AbortOnError   bool
	OnNodeStart    func(NodeID)
	OnNodeDone     func(NodeID, time.Duration, error)
}

ExecOpts controls one Execute call. Zero values are sensible: Workers=0 consults PRISM_QUERY_WORKERS env, then falls back to runtime.NumCPU(); Cache=nil disables memoization; PerNodeTimeout=0 disables per-node timeouts; AbortOnError=false is partial-failure mode.

type ExecResult ¶

type ExecResult struct {
	Tables  map[NodeID]*table.Table
	Errors  []NodeError
	Elapsed time.Duration
}

ExecResult carries the per-node tables that successfully materialised plus per-failed-node errors.

func Execute(ctx context.Context, d *DAG, opts ExecOpts) (*ExecResult, error)

type LRU ¶

type LRU struct {
	// contains filtered or unexported fields
}

LRU is a thread-safe bounded TableCache backed by a doubly-linked list + map. Eviction is least-recently-used: each Get/Put moves the touched entry to the front; capacity overflow drops the tail.

Capacity defaults to limits.DefaultTableCacheSize when caller passes a non-positive value to NewLRU. Hits/Misses counters power the executor-level cache-hit test (see TestPrismTableCacheHit in plan/cache_test.go).

func NewLRU(capacity int) *LRU

func (c *LRU) Capacity() int

func (c *LRU) Get(key string) (*table.Table, bool)

func (c *LRU) Hits() int64

func (c *LRU) Len() int

func (c *LRU) Misses() int64

func (c *LRU) Put(key string, t *table.Table)

type Labeled ¶

type Labeled interface {
	// Kind returns a short type name like "FilterNode" or "JoinNode".
	Kind() string
	// Summary returns a one-line parameter summary used in DOT labels
	// (e.g. "expr: score > 50"). Empty is acceptable.
	Summary() string
}

Labeled is the optional capability a Node implements when it wants the renderers to print something richer than its Go type name. The renderers fall back to reflect-based detection when a node does not satisfy this interface.

type Node ¶

type Node interface {
	// ID returns the stable identifier for this node.
	ID() NodeID
	// Inputs returns the upstream NodeIDs this node depends on. A
	// SourceNode returns nil (it has no upstream).
	Inputs() []NodeID
	// Schema returns the node's output schema given its inputs'
	// schemas. Nodes that cannot compute their schema without
	// execution data (rare; Pivot is the only P03 example) return
	// the first input schema and document the gap.
	Schema(in []*encoding.Schema) (*encoding.Schema, error)
	// Execute runs the node and returns the materialised Table. The
	// `in` slice carries upstream Tables in declaration order; for a
	// SourceNode it is always nil. Stubbed P03 nodes return
	// PRISM_COMPILE_001 here.
	Execute(ctx context.Context, in []*table.Table) (*table.Table, error)
	// Fingerprint returns a deterministic string capturing this node's
	// identity (op + parameters) used as a cache key component.
	Fingerprint() string
}

Node is the contract every DAG node satisfies. It is the only interface the executor knows about: schedulers, optimizer passes, renderers, and the cache key builder all consume Nodes through this surface.

Schema(in) lets callers reason about a node's output shape without executing — required for DAG visualisation, optimizer-pass eligibility, and the stubbed P03 nodes whose Execute bodies return PRISM_COMPILE_001 until P04. The `in` slice carries upstream schemas in declaration order; nodes that ignore inputs (Source) pass nil.

Fingerprint is a deterministic string capturing this node's identity (op + parameters). The cache key builder combines it with each input Table's Hash() to form a content-addressable cache key.

type NodeError ¶

type NodeError struct {
	Node NodeID
	Code string
	Err  error
}

NodeError is the per-failed-node detail entry.

func (e *NodeError) Error() string

func (e *NodeError) Unwrap() error

type NodeID ¶

type NodeID string

NodeID is the stable identifier for one DAG node. Implementations choose the format (path basename, sha hash, monotonic counter); the executor only needs equality semantics. IDs are case-sensitive and must be unique within a single DAG.

type Pass ¶

type Pass interface {
	Name() string
	Apply(*DAG) (*DAG, bool, error)
}

Pass is one optimizer transformation. Apply returns the (possibly new) DAG, a flag indicating whether anything changed, and an error. Passes MUST NOT mutate the input DAG — they return a fresh *DAG with structural sharing (WithNode / WithoutNode) for the changes they introduce.

type TableCache ¶

type TableCache interface {
	Get(key string) (*table.Table, bool)
	Put(key string, t *table.Table)
}

TableCache is the interface every Prism table cache satisfies. P03 ships the interface only; the LRU implementation lands in P07. ExecOpts.Cache stays nil in P03.