Is there a Digital Twin Runtime inside Plant and Factory?

Architecture research report. 2026-09-18. No code was changed; every claim below points at the existing files.

Repositories studied:

• Plant — plant/ (4D Plant Digital Twin, 4,924 lines; simulation core src/sim/ 1,343 lines)
• Factory — factory/ (Digital Energy Factory, 8,016 lines; simulation core src/sim/ 626 lines, agent world src/world/ 909 lines)

0. The answer first

Yes, but for a much smaller runtime than the question implies. The two applications share a real, non-cosmetic core: a pure step function over a plain state object, driven by a piecewise-constant input schedule, cached as a trajectory that is immutable in the past and recomputable in the future, with branching by structural sharing and causality derived purely from trajectory differences. Plant already implements all of that in ~400 lines (twin.ts 111, causal.ts 283) and none of it mentions tomatoes in its control flow. Factory implements the first quarter (the step function) and lacks the trajectory, which is exactly the part it would need to gain counterfactuals, "why" questions and observation correction.

What the evidence does not support is a large framework of TwinDefinition/Entity/Environment/CausalGraph classes. The two domains agree on control flow and disagree on almost every data shape: organs versus power flows, integer days versus fractional hours, immutable functional updates versus in-place mutation, derived events versus pushed events. Everything that touches those shapes should stay in the domain.

The smallest useful common runtime is five things:

Together these are roughly 500 lines of TypeScript with no dependency on three.js, React or zustand. That is the runtime. Everything else in the wish list (Entity, Environment, Prediction, Uncertainty, CausalGraph, TelemetryAdapter) either has one real implementation, zero real implementations, or two implementations that share a word and nothing else. Those are recorded below as deferred or domain, with the reason.

1. Existing-system comparison

Concept by concept. "Common" means a mechanism both codebases already exhibit or could adopt with a signature change; "Remainder" is what must stay in the domain package.

STATE

Common: state is a plain serialisable object; JSON.stringify equality is already the determinism test in Plant (sim-check.ts). The runtime should treat S as an opaque generic and require only clone(S) and equals-by-serialisation.

Remainder: all field names. Organ arrays with ids and the nextId counter are Plant's; the flow ledger and daily accumulators are Factory's.

TIME

Common: a Clock { t, dt, speed } and the rule "the stepper never reads wall-clock time". Both apps already keep animation time apart from simulation time (wind.uTime in Plant, runtime.clock / visualDt in Factory).

Remainder: epoch vs continuous is a genuine difference, not a naming difference. The runtime must support both an episodic trajectory (fixed grid, N states) and a rolling trajectory (fixed step, sliding window). Do not unify them into one timeline class with flags; provide one Trajectory<S> over a fixed step dt and let Plant use dt = 1 day and Factory dt = 1 minute with a window.

ENTITY

Common: the only thing both need is addressable values: a string path that resolves to a number in any state of any branch. Plant already reduces entities to (addr → value) maps before diffing (causal.ts:233–249). The runtime should standardise the accessor, not the entity.

Remainder: entity lifecycle. Forcing Factory's scalars into an Entity[] collection would add indirection to a model whose whole value is being 30 lines of arithmetic per device. Do not do it.

OBSERVATION

Common: nothing executable yet. Both have the intent and the same shape of intent: measurements arrive as flat channels keyed by name with a timestamp and a source tag. Section 7 designs this.

ENVIRONMENT

Common: an Inputs(t) provider that the stepper receives as an argument. Plant's envAt(day) is one; Factory's would be { sun: sunAt(hour), weather: WEATHER[id] }.

Remainder: what an environment contains. Plant's environment is a controlled variable (the grower sets water); Factory's is largely uncontrolled (the sun). The runtime must not pretend to know which is which; that is a per-channel provenance/controllability flag (section 10), not a class hierarchy.

DYNAMICS

Common: the DynamicsModel<S, I, P> signature (state, inputs, params, dt, rng) → state plus a version string. Both fit after Factory moves weather, scenario and refuelQueueKg from state to inputs (they can also stay mirrored in state for display).

Remainder: the equations. Nothing inside either step function generalises, and nothing should.

SIMULATION (the driver loop)

Common: a driver that advances a trajectory by whole steps independent of frames. Plant has it. Factory's loop is frame-coupled: the substep size h = simHours / sub depends on the frame's dt, so two runs of the same scenario produce slightly different trajectories. The runtime's fixed-step accumulator fixes this for free.

INTERVENTION

Common: an intervention is an edit to the input schedule from time t. Both apps' interventions reduce to that: Plant literally, Factory once gridAvailable, loadMult, pvBoost, weather are schedule channels. The window form (applyWindow) is generic and useful for maintenance/outage interventions in Factory ("grid outage 14:00–15:30").

Remainder: clock jumps (setHour: 22.5 in Factory's night scenario) are a view action, not an intervention, and should be treated as such.

TRAJECTORY

Common: Trajectory<S> is the single most valuable transferable piece. It is already domain-free in Plant: it calls stepDay and envAt and nothing else.

Remainder: Plant's interpolation between grid points (interpolateState) knows organs; it is a domain lerp(S, S, f) hook.

COUNTERFACTUAL

Common: branch(trajectory, t, edit). The reference trick (keep the pre-edit branch automatically) is domain-independent and worth keeping in the kernel.

CAUSALITY

Section 9 draws the boundary. Short version: divergence, persistence, tiers-by-order and time-to-effect are generic; chains, graph, organ matching, limiting factors and vocabulary are domain.

PREDICTION

Common: prediction = the future part of the trajectory. There is no separate predictor in either app and no reason to introduce one in the runtime.

UNCERTAINTY

Common: nothing. Do not build an uncertainty subsystem from one cosmetic band. Reserve a slot: a trajectory may carry an optional bounds(t, path) → [lo, hi], and an ensemble (N seeds) is the natural first real implementation because the kernel already makes seeded branches cheap.

RENDERING

Common: renderer reads (state, layout) snapshots and emits selection ids; never mutates state. Section 11 formalises this.

Remainder: all geometry. Plant's layout.ts is the right pattern (domain computes a three-free presentation model); Factory's world/ is the same pattern for statics.

EVENTS

Common: both are Event { t, key, level, text }. The kernel should prefer derived events (predicates over trajectory) because they survive branching and recompute, and allow emitted events as a stepper output channel rather than a mutation of state.

SCENARIOS

Common: Scenario = { name, inputsPatch, interventions[], view? }. Fits both once Factory's flags become schedule channels.

VALIDATION

Common: Invariant<S> = (s) => number (residual) and determinism as a standard check. Domain: the assertions themselves.

2. Common conceptual model

Derived from the tables, not from the wish list:

                ┌──────────────────────────────────────────────┐
                │  Trajectory<S>                                │
   Schedule<I>  │  states[k] at t0 + k·dt                      │
   (inputs by t)│  history (k ≤ now) immutable                  │
        │       │  future (k > now) = fold(step, states[now])   │
        ▼       │  branch(t, edit) shares history by reference  │
   step(S, I, P, dt, rng) → S  (+ emitted events)               │
                └──────────────────────────────────────────────┘
                         │                    │
        VariableRegistry │                    │ Layout<S> (domain, three-free)
        path → number    ▼                    ▼
        divergence / time-to-effect      RendererAdapter (three, 2D, headless…)
        (generic)                         reads snapshots, emits selection

Names that survived contact with the code:

• Stepper (not "DynamicsModel"): a function, with a version string and a parameter record.
• Schedule (not "Environment" and not "Intervention"): both apps reduce environment and intervention to "inputs as a function of time, edited from t onward". Environment vs intervention is a per-channel label, not a type.
• Trajectory: the cached fold. This is the twin's memory.
• Branch: a trajectory that shares history with its parent.
• VariableRegistry: { key, get(S) → number, tier, threshold, mode } — Plant's CAUSAL_VARS, generalised.
• Analysis: divergences + time-to-effect over two trajectories.
• Layout: domain-owned, dependency-free presentation model (Plant's PlantLayout, Factory's world layout + flow list).
• Provenance: tags on parameter records and schedule channels, inherited by variables by rule.

Names that did not survive:

• TwinDefinition / TwinInstance — there is exactly one definition per app and it is the module itself. A TwinDefinition object would be a bag of the five functions above; call it that (TwinModule<S, I, P>), and do not add registry, discovery or plugin loading until a third domain exists.
• Entity / Environment classes — see the ENTITY and ENVIRONMENT rows; accessors and channels cover both apps without new object models.
• CausalGraph — Plant's graph is a hand-drawn diagram with coordinates (causal.ts:133). It is domain content, not a runtime facility.
• Prediction / Uncertainty as types — the future half of a trajectory and an optional bounds function.
• TelemetryAdapter — premature; section 7 defines the ingest contract only.

3. Proposed runtime boundary

packages/twin-core           (future; NOT to be created yet)
  clock.ts        Clock, fixed-step accumulator
  schedule.ts     Schedule<I>: segments, at(t), setFrom(t, patch), window(t0, t1, patch)
  trajectory.ts   Trajectory<S,I,P>: states, computeFrom, branch, stateAt(lerp hook)
  rng.ts          hash32 / rand01 (verbatim from plant/src/sim/rng.ts)
  variables.ts    VariableSpec, registry, divergence(), timeToEffect(), values()
  events.ts       DerivedEvent predicates, EmittedEvent channel
  provenance.ts   ProvenanceTag, ledger, inherit rules
  observe.ts      Observation, Estimator interface, assimilate()
  invariants.ts   Invariant<S>, determinismCheck()
  adapter.ts      Snapshot<S,L>, RendererAdapter interface (types only)

Rules the boundary must enforce, all of which Plant already satisfies and Factory nearly does:

1. No imports of three, react, zustand, DOM, or window inside twin-core. (Factory's store.ts line 2 is the one current violation; it lives in the app layer anyway.)
2. The stepper receives inputs and parameters as arguments; it never reads module state that changes (Factory's eventId, _sunset must become part of P or the emitted-events channel).
3. Randomness comes only from rng(seed, id, salt). Math.random is permitted only outside the core (Factory's agents, which are renderer-side life).
4. Time is t0 + k·dt. Frame time never reaches the stepper.

4. Domain / plugin boundary

A domain package supplies exactly:

plant-twin (existing plant/src/sim, repackaged)      factory-twin (existing factory/src/sim, repackaged)
  types.ts        PlantState, Environment              engine.ts   SimState, FactoryInputs
  model.ts        stepDay  → Stepper                   engine.ts   step      → Stepper (inputs as args)
  species.ts      SpeciesParams + DSSAT provenance     config.ts   PLANT + WEATHER + provenance tags
  layout.ts       PlantLayout (three-free)             world/layout.ts + flows (three-free)
  causal.ts       CAUSAL_VARS entries, tiers,          (new) VARS: batterySoc, gridImport, loadShed… ,
                  RESPONSE_OF/CORE/TAIL chains,               tiers: environment→dispatch→storage→kpi
                  GRAPH_NODES/EDGES, organDeltas,
                  limitingFactors
  scenarios.ts    presets                              engine.ts   SCENARIOS as schedule patches
  ask.ts          vocabulary tables                    —

The plugin contract is the TwinModule<S, I, P> record in section 5. It is deliberately a record of functions and tables, not a class to extend. Both apps can satisfy it with re-exports and one signature change each (section 13, 14).

5. TypeScript interface sketches

Only what the evidence justifies. Names are proposals.

// ---------- time
export interface Clock { t0: number; dt: number; unit: 'day' | 'hour' | 'minute' | 's' }
export const index = (c: Clock, t: number) => Math.floor((t - c.t0) / c.dt + 1e-9)

// ---------- inputs (environment + interventions, per channel)
export type Channels = Record<string, number | string | boolean>
export interface Segment<I extends Channels> { from: number; inputs: I; label?: string }
export interface Schedule<I extends Channels> {
  segments: Segment<I>[]
  at(t: number): I                                     // plant twin.envAt
  setFrom(t: number, patch: Partial<I>, label?: string): void   // plant setEnvFrom
  window(t0: number, t1: number, patch: Partial<I>, label?: string): void // plant applyWindow
  edits(): { t: number; key: keyof I; from: unknown; to: unknown }[]     // plant interventionsOf
}

// ---------- dynamics
export type Rng = (id: number, salt?: number) => number    // plant rand01 bound to a seed
export interface StepResult<S> { state: S; events?: EmittedEvent[] }
export interface Stepper<S, I extends Channels, P> {
  version: string                                          // model version for reproducibility
  init(params: P, seed: number): S
  step(prev: S, inputs: I, params: P, dt: number, rng: Rng): StepResult<S>
  clone(s: S): S                                           // plant cloneState; factory structuredClone-able
  lerp?(a: S, b: S, f: number): S                          // plant interpolateState (optional)
}

// ---------- trajectory + branching
export interface Trajectory<S, I extends Channels, P> {
  readonly id: string
  readonly parent?: string
  readonly clock: Clock
  readonly seed: number
  readonly params: P
  readonly stepper: Stepper<S, I, P>
  schedule: Schedule<I>
  states: S[]                                              // states[k] = state at t0 + k·dt
  now: number                                              // index of the last non-predicted state
  horizon: number                                          // last index computed (plant: 120)
  computeFrom(k: number): void                             // plant computeFrom
  branch(k: number, label: string): Trajectory<S, I, P>    // plant clone(): shares states[0..k]
  stateAt(t: number): S                                    // plant stateAt with lerp hook
}

// ---------- variables and analysis (plant CAUSAL_VARS, generalised)
export type Tier = string                                   // ordered per domain
export interface VariableSpec<S> {
  key: string; label: string; tier: Tier
  get(s: S): number
  mode: 'rel' | 'abs'; threshold: number; scale: number; min?: number
  fmt?(v: number): string
  provenance?: ProvenanceTag                               // default class for this variable
}
export interface Divergence { key: string; tier: Tier; k: number; base: number; alt: number; delta: number; rel: number; direction: 'up' | 'down' }
export interface Analysis<S> {
  base: Trajectory<S, any, any>; alt: Trajectory<S, any, any>; fromK: number
  divergences: Divergence[]                                // plant analyze(): first persistent exceedance
  byKey: Record<string, Divergence | undefined>
  timeToEffect: Record<Tier, number | null>                // first divergence per tier
  values(key: string, k: number): { base: number; alt: number; delta: number; rel: number }
  act(key: string, k: number): number                      // normalised −1…1 for graph intensity
}
export function analyze<S>(vars: VariableSpec<S>[], tiers: Tier[], base: Trajectory<S, any, any>, alt: Trajectory<S, any, any>, fromK: number): Analysis<S>

// ---------- events
export interface EmittedEvent { t: number; level: 'info' | 'warn' | 'alarm'; key: string; text: string }
export interface DerivedEvent<S> { key: string; label: string; first(s: S): boolean }   // plant twin.events()

// ---------- observation / estimation (section 7)
export interface Observation { t: number; source: string; channels: Record<string, { value: number; quality?: number }> }
export interface Estimator<S> { assimilate(prior: S, obs: Observation, t: number): { state: S; provenance: ProvenanceDelta } }

// ---------- provenance (section 10)
export type ProvenanceClass = 'MEASURED' | 'ESTIMATED' | 'SCIENTIFIC_MODEL' | 'DERIVED' | 'ASSUMED' | 'PROCEDURAL'
export interface ProvenanceTag { class: ProvenanceClass; source?: string; ref?: string; retrieved?: string; note?: string }
export type ProvenanceLedger = Record<string /* path */, ProvenanceTag>
export type ProvenanceDelta = Record<string, ProvenanceTag>

// ---------- renderer boundary (section 11)
export interface Snapshot<S, L> { trajectoryId: string; t: number; state: S; layout: L; branches?: Snapshot<S, L>[] }
export interface RendererAdapter<S, L> {
  mount(host: unknown): void
  render(snap: Snapshot<S, L>, view: ViewState): void
  onSelect(cb: (addr: string | null) => void): void
  unmount(): void
}

// ---------- the plugin record
export interface TwinModule<S, I extends Channels, P, L> {
  name: string
  clock: Clock
  stepper: Stepper<S, I, P>
  defaultInputs: I
  defaultParams: P
  layout(s: S, p: P): L                                    // three-free presentation model
  variables: VariableSpec<S>[]
  tiers: Tier[]
  derivedEvents: DerivedEvent<S>[]
  invariants: { name: string; residual(s: S): number; tolerance: number }[]
  provenance: ProvenanceLedger                             // for params and input channels
  scenarios: { name: string; inputs?: Partial<I>; interventions?: { t: number; patch: Partial<I> }[] }[]
}

That is the whole surface. Note what is absent: no Entity, no Environment class, no CausalGraph, no Prediction, no Uncertainty beyond the optional bounds slot mentioned earlier.

6. State transition model

The invariant

STATE(k+1) = step( STATE(k), SCHEDULE.at(t_k), PARAMS, dt, rng(seed) )

Plant holds it exactly today. computeFrom is literally this fold (twin.ts:36–38): stepDay(states[d], envAt(d), { seed, species }). Inputs are the environment schedule; interventions are edits to it; params are SpeciesParams; randomness is rand01(seed, organId, salt).

Factory holds it after one signature change. Today step(s, dt) reads its inputs from inside s: s.weather (set by the store), s.scenario (set by applyScenario), s.gridAvailable, s.cloudTimer, s.refuelQueueKg (written by the traffic layer). The equations themselves are already a function of (s, sun(hour), WEATHER[weather], scenario flags, PLANT, dt). Moving those to an inputs argument:

interface FactoryInputs { weather: WeatherId; gridAvailable: boolean; pvBoost: number; loadMult: number; cloudFactorTarget: number; refuelRequestKg: number }
step(prev, inputs, PLANT, dt, rng) → next

changes ~15 lines of step and applyScenario and nothing in the arithmetic. The cloud transient becomes a scheduled cloudFactorTarget window (which is what it already is: cloudTimer counts down minutes). The EMS forecast (sunsetHour) is a function of PLANT.site and belongs in params.

Two things must move out of the state to make the fold pure:

• pushEvent → return events from step (the StepResult.events channel); the rolling 40-cap becomes a UI concern.
• eventId global → derive ids from (k, index).

History vs prediction

Both apps need the same split, and only Plant has it: states[0..now] are history (in a real twin: estimated from observations), states[now+1..horizon] are prediction (the fold). Editing the schedule at t ≥ now recomputes only the prediction; the history is never rewritten. This is the rule Plant's README states and its setEnvFrom enforces; it is the rule that makes observation correction (section 7) and counterfactuals (section 8) fall out of the same mechanism.

For Factory the window matters: at dt = 1 min a 48-hour rolling trajectory is 2,880 states of ~100 numbers, trivially cheap (Factory already runs 600 substeps at startup in createSim).

7. Observation / state-estimation model

Neither app assimilates anything today; Plant has the record shape and an unused interface; Factory has a README sentence. The design below is the smallest one that turns "SIMULATED OBSERVATION" into "MEASURED" without rewriting either model.

Contract

Observation(t) ──► Estimator.assimilate(prior = states[k(t)], obs) ──► states[k] := posterior
                                                                       provenance[path] := MEASURED / ESTIMATED
                                                                       trajectory.now = k
                                                                       computeFrom(k)          (re-predict)

One Observation is a flat map of channels. Channels resolve to either state paths (they correct the state) or input channels (they replace a scheduled or modelled input). The TwinModule declares which is which in a binding table; the kernel does not guess.

Plant binding (from PlantObservation)

The important structural fact: Plant's aggregates are derived, so a generic "set height = 1.42" is meaningless. The kernel provides the pipeline; the domain provides the estimator that knows how to push an aggregate back into organs. The kernel's generic estimators are only overwrite (for paths that are primary state) and replaceInput (for input channels).

Factory binding (SCADA / IoT / meters / BMS / EMS)

Factory is the easier assimilation case because its state is mostly primary scalars; the hard part is that its dispatch logic is inside the step. When a real EMS exists, the dispatch decision arrives as an input and the model degrades gracefully to "physics only" (SOC integration, H₂ balance, KPIs). The runtime should support a stepper that accepts optional externally-supplied decision channels — which is just more input channels, no new mechanism.

Where "now" comes from

Plant's now is the UI day; Factory's is wall-clock. With assimilation, now is the timestamp of the latest accepted observation. Everything at k ≤ now carries MEASURED/ESTIMATED provenance; everything after is SCIENTIFIC_MODEL/ASSUMED. That is precisely the "OBSERVED · ESTIMATED · PREDICTED" panel Plant already draws with simulated data (TwinStatePanel.tsx).

8. Counterfactual branching model

Plant's implementation is already the generic one; the analysis is whether the same mechanism serves the other domains.

                         trajectory T (schedule S, states[0..now])
                                      │
                    branch(now)       │       branch(now)
          ┌───────────────────────────┼─────────────────────────┐
          ▼                           ▼                         ▼
   BASELINE = T                 A = T.branch(now)          B = T.branch(now)
   (unchanged schedule)         A.schedule.setFrom(now,    B.schedule.window(now, now+90 min,
                                  { water: 25 })              { gridAvailable: false })
          │                           │                         │
   computeFrom(now)             computeFrom(now)          computeFrom(now)

Each branch is segments copy + states.slice() (history shared by reference because states are immutable values; Plant relies on cloneState producing fresh objects each step). Mapped onto the four requested cases:

So the generic branching needs exactly two edit kinds — schedule edits and parameter patches — and Plant already has the first; the second is trivial. The "recovery" branch (branch of a branch) and the automatic "reference" (pre-edit branch) need no additions.

What does not generalise: the Day-120 previewIntervention row list (causal.ts:279) is domain (which variables to report); the kernel offers preview(T, k, edit) → Analysis and the domain picks the rows.

9. Causal-analysis boundary

Reading causal.ts line by line, the split is clean:

Generic (no domain semantics, keep in kernel):

• values(key, k) — accessor arithmetic (causal.ts:91).
• Divergence detection: first index where |alt − base| exceeds a threshold (relative or absolute, with a floor) and persists one more step (causal.ts:101–118). The persistence rule is the part that makes it robust to integer-valued variables (fruit count) and should be kept.
• Ordering by (k, tierRank) and timeToEffect = first divergence per tier (causal.ts:119–124). Needs only an ordered list of tier names from the domain.
• act() normalisation for graph intensity (causal.ts:96).
• Intervention reconstruction from schedule edits (causal.ts:80–88).
• preview(T, k, edit) — branch + analyze without commit.
• Difference listing at a time (Ask's "differences at this day", ask.ts:88).

Domain (stays in the plant package; Factory writes its own):

• The CAUSAL_VARS entries: keys, getters, thresholds, tiers, phrasing (up/down verbs) (causal.ts:29–58).
• RESPONSE_OF, CORE, TAIL chain tables — an ordering of mechanism that encodes plant physiology (causal.ts:186–197). Factory's equivalent would be irradiance → pvPotential → flows.pvToBattery → batterySoc → fuelCellPower → gridImport.
• GRAPH_NODES with pixel coordinates and GRAPH_EDGES with via variables — diagram content.
• organDeltas — address matching is domain (it knows axes and ranks), though the kernel can offer diffByAddress(mapA, mapB) once both sides are Map<addr, number>.
• limitingFactors — re-runs the model's response functions; there is no domain-free notion of "limiting factor". Factory's analogue is the flow ledger (which source served the load), a different computation.
• Ask vocabulary (ENV_WORDS, TARGET_WORDS) — domain; the four intent classes (what-if, when-diverged, differences, why) are generic dispatch, and can live in the kernel as an intent enum with domain-supplied matchers.

Boundary statement: the kernel answers whether, when, and by how much two trajectories differ per registered variable and per tier; the domain answers through which mechanism and in which words.

10. Provenance model

What exists:

• Plant records provenance at the parameter source level, thoroughly: each species JSON carries source { model, repository, license, files, cultivar, ecotype, retrieved } (data/species/*.json); ARCH_SOURCES and DM[].source cite literature for botanical facts (species.ts:70–103); the header comments in types.ts, model.ts, response.ts declare the equations "illustrative"; the UI stamps SIMULATED, SIMULATED OBSERVATION, PREDICTED, DSSAT CSM v4.8 CROPGRO badges (TwinStatePanel.tsx).
• Factory records it at the file level: config.ts opens with "Every number here is a demonstration assumption"; engine.ts with "carry no engineering, safety, sizing, financial or operational meaning"; the UI shows a SIMULATED chip; renderer assets have ASSET-LICENSES.md.
• Neither attaches provenance to a runtime value.

Design principle: provenance is attached to producers, not to numbers. Three producer kinds exist in both apps, and each gets tagged once:

1. Parameters — a ledger entry per parameter path at module definition time. Plant: species.TM.lfmax → { class: SCIENTIFIC_MODEL, source: 'DSSAT CSM v4.8 CROPGRO', ref: 'TMGRO048.CUL', retrieved: '2026-09-18' }; species.TM.dm.fruit → { class: DERIVED, source: 'USDA FDC tomato 94.5 % water' }; ASSIM_K → { class: ASSUMED, note: 'tomato calibration constant' }. Factory: PLANT.bess.energyMWh → { class: ASSUMED } until a nameplate arrives; PLANT.grid.carbonKgPerMWh → { class: ASSUMED, note: 'marginal, coal-heavy region' }.
2. Input channels — per channel, per time range: SCHEDULED (user plan; class ASSUMED) before assimilation, MEASURED after (replaceInput writes the tag with the observation's source).
3. State variables — inherited by rule, not stored per number: a state path produced by the stepper is SCIENTIFIC_MODEL if the stepper's declared class is scientific, else ASSUMED; after overwrite by an estimator it is MEASURED at that k; after a domain nudge it is ESTIMATED; a variable registered as DERIVED (Plant's height, lai; Factory's renewableShare) is DERIVED regardless. The kernel stores only the deltas per k (ProvenanceDelta, usually empty) and resolves provenanceOf(path, k) by looking up delta → variable default → stepper default.
4. Presentation values — anything computed in layout() (Plant's leaf yaw from rand01(7, id), branch droop, Factory's road jitter) is PROCEDURAL by definition of the layout function; no per-value work.

Cost: one Record<path, ProvenanceTag> per module (Plant's is already 80 % written as JSON and comments), one optional delta map per trajectory index, and a three-line resolver. No arithmetic changes. The UI badges Plant already draws become provenanceOf(...) lookups instead of hard-coded strings.

Worked examples from the brief:

• fruit mass: species.TM.fruitFreshMass = fruitDryMass / dm.fruit; fruitDryMass = WTPSD × SDPDV / THRSH (DSSAT cultivar, SCIENTIFIC_MODEL) ÷ dm.fruit (USDA, DERIVED) → the parameter resolves to DERIVED with two cited sources; a fruit's runtime biomass inherits SCIENTIFIC_MODEL from the stepper until phenotyping overwrites it (MEASURED).
• battery SOC: ASSUMED initial (initialSoc: 0.62), SCIENTIFIC_MODEL while integrated, MEASURED once BMS telemetry is assimilated.
• branch orientation: PROCEDURAL (produced by computeLayout).

11. Renderer adapter

Current dependency direction, verified:

plant/src/sim  ──(types + layout)──►  plant/src/render (three)      ✔ no reverse edge
factory/src/sim, world ──────────►  factory/src/scene (three)       ✔ no reverse edge
factory/src/state/store.ts ──► three   (dev handle only)            ✘ app-layer leak, harmless today
factory/src/scene/Scene.tsx  ──► runtime.sim.refuelQueueKg += …     ✘ renderer writes into sim state

The contract that both already follow in practice:

Runtime ──► Snapshot { t, state, layout, branches[] } ──► RendererAdapter.render(snapshot, view)
Runtime ◄── adapter.onSelect(addr)                                    (the only upstream message)

Details that the evidence fixes:

• Layout is computed on the runtime side and is three-free. Plant's computeLayout is the model for this; it even feeds back one number (canopyWidth) into the state, which is fine because it is pure. Factory's static world/layout.ts is the same idea for geometry that never changes; its dynamic part is flows (already in state).
• Multiple instances per frame. Plant renders up to three trajectories in split panes with one camera. Snapshot.branches[] carries them; the adapter decides pane layout (a view concern).
• Interpolation belongs to the runtime. stateAt(t) with the domain lerp hook produces the sub-step state; the adapter never interpolates domain state itself.
• Ambient life is adapter-side. Factory's Traffic (workers, vehicles, forklift fork state) is visual, non-deterministic and frame-stepped; it must stay in the adapter. Its single feedback (refuelQueueKg) becomes an input channel (refuelRequestKg per step) so the renderer emits an input event instead of writing sim state. That closes the one upstream write.
• Picking returns addresses. Plant: L:m:12; Factory: bess. The runtime resolves an address to variables for the info panel.
• Headless adapter is the null adapter: render() ignored, snapshots consumed by scripts. Plant's sim-check.ts already is this; Factory's verify.mjs needs the browser only because the driver is inside R3F, which the kernel driver removes.

What must not enter the adapter interface: camera presets, DoF, post-processing, textures, instancing strategy, LOD, split-pane geometry. These differ completely between the two apps and are the bulk of their code (Plant render/ 1,861 lines; Factory scene/ 5,079 lines).

12. Determinism and versioning

Plant's property, verbatim: "same initial state, model version, parameters, interventions, random seed → same trajectory." Evidence: rand01(seed, organId, salt) is order-independent hashing (rng.ts); sim-check.ts asserts JSON.stringify(t2.states[120]) === JSON.stringify(t.states[120]) and that a branch's states[45] is identical to the parent's; layout.ts uses a fixed seed = 7.

Factory's gaps, verbatim:

1. Substep size depends on frame time: sub = ceil(simHours / (1/60)); h = simHours / sub (Scene.tsx:36–39). A 16 ms frame at 10× produces h ≈ 0.044 min, a 33 ms frame h ≈ 0.09 min; ramp limiters (towards(..., rampMWPerMin · dt · 60)) and clamp make the result step-size-dependent. Two runs differ at the third decimal.
2. Global eventId and _sunset cache (benign but impure).
3. Agents use Math.random (acceptable: they are adapter-side).
4. No model version string anywhere; Plant has none either, only the DSSAT retrieved date.

Runtime design:

• Fixed-step accumulator in the driver: acc += dtVisual · speed; while (acc ≥ dt) { step(dt); acc −= dt }. Trajectory index, not frame, is the time base.
• ReproKey = hash(stepper.version, JSON(params), JSON(schedule.segments), seed, clock) stored on every trajectory and printed by the headless check. Two trajectories with equal keys must have byte-equal states.
• stepper.version is mandatory and bumped by hand; params provenance (section 10) carries data versions (retrieved).
• The determinism check is a kernel invariant, run by both sim-check and verify.

13. Migration strategy for Plant

Plant is already 90 % on the target shape. The migration is a repackaging, and it can be done without changing a single equation:

1. Split twin.ts into kernel Trajectory/Schedule (the class body minus events(), observation(), species) and a domain plantTwin: TwinModule. DigitalTwin remains as a thin façade so store.ts, render/, ui/ and the scripts keep compiling.
2. Move rng.ts to the kernel verbatim.
3. Split causal.ts: analyze, values, act, divergence loop, tierRank, interventionsOf, previewIntervention's branch part → kernel; CAUSAL_VARS, chains, graph, organDeltas, limitingFactors, row lists → plant-twin.
4. events() becomes derivedEvents: DerivedEvent<PlantState>[] (eight predicates already written).
5. PlantObservation becomes an Observation binding table plus one domain Estimator (the nudge rules in section 7) — the only new code.
6. Provenance ledger: generated from the species JSON source blocks plus ~20 hand entries for ASSIM_K, MAINT_*, HYPOCOTYL, GROUND_AREA, response-function constants.
7. Acceptance: sim-check.ts output byte-identical before and after; causal-check.ts output identical; ReproKey printed.

Risk: low. The refactor is mechanical and the tests already exist.

14. Migration strategy for Factory

Factory needs behavioural additions, not just repackaging, so it should go second and only after the kernel has proven itself on Plant.

1. Inputs out of state. Define FactoryInputs (weather, gridAvailable, pvBoost, loadMult, cloudFactorTarget, refuelRequestKg). step(s, inputs, PLANT, dt, rng). applyScenario becomes a schedule edit; setWeather a schedule edit; the cloud event a window. Keep mirrored copies in state for the HUD during the transition.
2. Events as output. pushEvent returns through StepResult.events; the store keeps the rolling 40. eventId removed.
3. Fixed-step driver. Replace the Ticker substep arithmetic with the kernel accumulator at dt = 1 min. This alone makes runs reproducible.
4. Rolling trajectory. Keep 48 h of states (2,880 × ~100 numbers). setHour becomes "scrub within the trajectory" backwards and "fast-forward the fold" forwards, which is more honest than today's clock jump (today, jumping the hour leaves SOC and H₂ at their pre-jump values).
5. Variables + tiers. ~15 VariableSpec entries (irradiance, pvPotential, load, batteryPower, batterySoc, electrolyserPower, h2Stored, fuelCellPower, gridImport, gridExport, loadShed, renewableShare, carbonIntensity) over tiers environment → dispatch → storage → kpi. With that, analyze() gives Factory "when did the outage branch diverge, and what reached the KPI first" for free.
6. Branching UI. Scenario switch becomes branch(now) + edit; the control room gains a Sankey per branch. Optional; the kernel does not require UI changes.
7. Agents stay put in world/ + scene/, but refuelQueueKg flows through the input channel.
8. Provenance ledger from config.ts (every entry ASSUMED with the existing comments as notes) and sun.ts (SCIENTIFIC_MODEL: declination/hour-angle geometry, ASSUMED: 0.7^AM^0.678 clear-sky constant).
9. Acceptance: verify.mjs still 31/31; balanceResidual < 0.01; new headless factory-check.ts prints the ReproKey and asserts two runs equal.

Risk: moderate. Step 4 changes user-visible time semantics; step 1 touches the dispatch block. Both are contained in engine.ts/store.ts/Scene.tsx.

15. What should NOT be abstracted

Each item below appears in one app only, or in both with incompatible meaning, or is cheap to duplicate:

• Organ topology and lifecycle (Axis/Node/Leaf/Truss/Flower/Fruit, nextId, senescence) — Plant only.
• Plant layout physics (computeLayout: phyllotaxis, gravity sag, truss bending) — Plant only, 319 lines that would not lose a line by being "generic".
• EMS dispatch (the if (net ≥ 0) … else … block) — Factory only; it is the model.
• Road and walkway graphs, agents, forklift fork state machine — Factory renderer-side life.
• Scenario contents, camera presets, tour scripts, HUD/panels — per app.
• Causal chain tables, graph coordinates, Ask vocabulary — domain content (section 9).
• Uncertainty — one cosmetic band is not a subsystem.
• Entity/Environment object models — accessors and channels suffice (sections 1, 2).
• A plugin registry / dynamic loading — there are two modules and they are both statically imported.
• A shared UI kit — the two UIs share zustand and CSS conventions only.
• Interpolation — interpolateState knows organs; keep it a domain hook.

16. Risks of premature abstraction

1. n = 2. Every "common" pattern here is common to two samples written by the same hands within the same day, in the same stack. The trajectory/branch/divergence core is defensible because it is already domain-free in the code; anything beyond it is extrapolation.
2. The kernel is the size of Plant's sim. Plant's whole engine is 1,343 lines; a 500-line kernel is a large fraction of the thing it abstracts. If the kernel grows past ~800 lines it has stopped being "smallest useful".
3. Time-regime mismatch. Episodic (Plant) vs rolling (Factory) trajectories are different products. A unified Trajectory with now/horizon/window handles both, but the UI semantics (scrub vs live) will still differ and must not be forced into one timeline widget.
4. Factory's live feel. Today scenario switches are instantaneous mutations of a live sim; a branch-and-recompute model may feel slower or more "analytical". Keep a "commit branch to live" action so the live experience survives.
5. Estimator complexity. Plant's aggregates are derived from organs, so assimilation needs bespoke inverse rules. If the kernel tries to be clever here (generic nudging of aggregates) it will be wrong for plants and unnecessary for factories. Keep overwrite and replaceInput generic; everything else domain.
6. Provenance creep. Tagging every arithmetic result is the failure mode the brief warns about; the producer-level ledger with inheritance (section 10) is the guard. Resist per-number tags.
7. Renderer temptation. Both apps' realism pipelines (materials, LOD, impostors, DoF) are where most of the code lives and where reuse feels biggest. It is not runtime code and should not be pulled in by the same package boundary; a separate, optional "r3f-kit" could exist later and must not be a dependency of the kernel.
8. Losing determinism during migration. Factory's frame-coupled stepping must be fixed before it is wrapped in a trajectory, or branch comparisons will show spurious divergences.

17. Minimal proof-of-concept plan

Goal: prove the five kernel pieces on both apps with zero behavioural change to Plant and one behavioural fix to Factory, in a scratch package that is not yet shared code.

Step 1 — Extract, don't design (Plant, ~1 day). Copy twin.ts + rng.ts + the generic half of causal.ts into poc/twin-core/, parameterise by <S, I, P>, re-export DigitalTwin from the plant package as a façade. Acceptance: npm run sim and causal-check.ts print byte-identical output; grep shows zero three/react imports in twin-core.

Step 2 — Signature change (Factory, ~1 day). step(prev, inputs, PLANT, dt) with FactoryInputs; pushEvent → returned events; fixed-step accumulator in Ticker. Acceptance: verify.mjs 31/31; a new factory-check.ts runs 24 h headless twice and asserts equal JSON; balanceResidual < 0.01 throughout.

Step 3 — Trajectory + branch (Factory, ~1 day). Wrap the stepper in Trajectory with dt = 1 min, 48 h window. Script: baseline vs window(14:00, 15:30, { gridAvailable: false }); register 13 variables in four tiers; run analyze. Acceptance: it reports the outage at 14:00, batteryPower divergence within 1 min, fuelCellPower within a few minutes, gridImport immediately, carbonIntensity at the KPI tier — i.e. the same "time-to-effect" narrative Plant produces for drought, from the same code path.

Step 4 — Observation smoke test (both, ~1 day). Feed a synthetic Observation (Factory: BMS SOC 0.40 at 12:00; Plant: plantHeight +10 % at day 40) through assimilate with overwrite / a domain nudge; assert now moves, history before now is untouched, prediction after is recomputed, and provenanceOf('batterySoc', k12:00) === MEASURED.

Step 5 — Decide. If steps 1–4 land under ~600 kernel lines and both apps' existing checks pass unchanged, create the shared package. If the kernel needs domain conditionals to pass, stop and keep two copies.

Deliberately out of scope for the PoC: UI changes, renderer adapter implementation (only the type), uncertainty, Ask, plugin registry.

Appendix A — Line-level evidence index