Concepts

Meta Entities

A .meta/ directory co-located with source content. Contains:

• meta.json — current synthesis state (content, prompts, tokens, errors)
• archive/ — timestamped snapshots of previous syntheses
• .lock — transient lock file during active synthesis

Ownership Tree

Meta entities form a hierarchy based on filesystem nesting. A .meta/ directory owns its parent directory and all descendants, except subtrees that contain their own .meta/. Child meta syntheses are consumed as rollup inputs by parent metas.

Synthesis Phases

A three-phase LLM pipeline managed by a per-meta phase-state machine:

1. Architect — analyzes scope structure, crafts a task brief (conditional: runs on structure change, steer change, or periodic refresh)
2. Builder — executes the brief, produces _content + structured fields
3. Critic — evaluates the synthesis, provides _feedback for the next cycle

Phase-State Machine (_phaseState)

Each meta tracks its three phases independently via _phaseState: { architect, builder, critic }. Each phase can be in one of five states: fresh, stale, pending, running, or failed.

The scheduler selects one phase per tick across the entire corpus, prioritizing by band (critic > builder > architect) and weighted staleness within each band. This enables:

• Surgical retries — only the failed phase reruns; upstream/downstream untouched
• Auto-retry — failed phases are promoted failed → pending on each tick
• Full-cycle completion — archive snapshot + _synthesisCount increment only when all three phases are fresh
• Backward compatibility — derivePhaseState() reconstructs the state from legacy fields on first load

Cross-Meta References (_crossRefs)

A meta can declare explicit relationships to other metas via the _crossRefs property — an array of owner paths. Referenced metas' _content is included as context for the architect and builder steps (not the critic), enabling organizational views that aggregate across source domains without requiring data co-location.

Cross-refs form a heterarchical mesh orthogonal to the ownership tree. Cycles are permitted (A refs B, B refs A — each reads the other's last-synthesized content). No transitive closure: if A needs C's content, declare the ref explicitly.

Cross-ref freshness does NOT affect the referencing meta's staleness. Each meta synthesizes on its own schedule, avoiding dependency cascades.

Staleness

A meta is stale when any file in its scope was modified after _generatedAt. The scheduler uses a weighted formula incorporating tree depth and per-meta emphasis to prioritize which meta to synthesize next.

Set _disabled: true on a meta to exclude it from automatic staleness scheduling. Disabled metas are never selected by the scheduler or by the auto-select path of POST /synthesize, but manual triggers (meta_trigger with an explicit path, or POST /synthesize with an explicit path) still run them.

Progressive Synthesis (_state)

The builder can populate an opaque _state field in meta.json to carry forward intermediate progress across cycles. On timeout (SpawnTimeoutError), the service attempts to salvage any advanced _state from partial output — preserving progress even when the full synthesis fails.

Lock Staging

Synthesis results are staged in a .lock file before being committed to meta.json. If the process crashes between staging and commit, meta.json is untouched — "never write worse."