simfile 0.0.1

package/dist/runtime/step-tick.d.ts

@@ -0,0 +1,43 @@
+import { type LedgerEventEnvelopeInput } from "../ledger/stable.js";
+import type { ClockRuntime } from "./clock.js";
+import { type CompiledTraceRuntime } from "./trace-compile.js";
+import type { QueuedWorldAct, RuntimeTraceEvent, RuntimeVariableSample, WorldActResult } from "./types.js";
+export type SimfileEventKind = "clock.sync" | "rule.fired" | "world.message" | "world.dm" | "world.act" | "wake.recommended" | "marker.seen";
+export declare const WORLD_ACTOR = "@world";
+/**
+ * Shared canonical-envelope constructor for every event kind minted while
+ * stepping a tick (and reused by `trace-run.ts` for its post-hoc
+ * `marker.seen` events, so there is exactly one place that stamps the
+ * causal envelope for simfile-native trace events).
+ */
+export declare const createTraceEvent: (runId: string, seq: number, kind: SimfileEventKind, simTime: number, actor: string, target: string, scope: string, payload: LedgerEventEnvelopeInput["payload"], causeEventIds?: readonly string[]) => RuntimeTraceEvent;
+export interface StepSimfileTickContext {
+    runId: string;
+    seed: string;
+    precision: number;
+    clock: ClockRuntime;
+    runtime: CompiledTraceRuntime;
+    /** Mutated in place: the run's variable state, before this tick on entry
+     * and after this tick on return. */
+    state: Record<string, number>;
+    /** First seq number to mint for this tick's events. */
+    seq: number;
+    worldActsForTick?: readonly QueuedWorldAct[];
+    worldActResultsByActId: ReadonlyMap<string, WorldActResult>;
+}
+export interface StepSimfileTickResult {
+    events: RuntimeTraceEvent[];
+    sample: RuntimeVariableSample;
+    nextSeq: number;
+}
+/**
+ * Advances the world by exactly one tick: resolve the clock, apply any
+ * queued world.acts, run generators, recompute derived variables, evaluate
+ * rules (minting their world-effect events), then fold the tick's ending
+ * values back into `ctx.state`. This is the pure REFACTOR extraction of
+ * `runSimfileTrace`'s former inline per-tick loop body — same inputs, same
+ * outputs, same mutation order — so a live driver can call it once per
+ * wall-clock tick instead of only ever inside one big batch loop.
+ */
+export declare const stepSimfileTick: (tick: number, ctx: StepSimfileTickContext) => StepSimfileTickResult;
+//# sourceMappingURL=step-tick.d.ts.map

package/dist/runtime/step-tick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-tick.d.ts","sourceRoot":"","sources":["../../src/runtime/step-tick.ts"],"names":[],"mappings":"AACA,OAAO,EAAiF,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACnJ,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK/C,OAAO,EAA6B,KAAK,oBAAoB,EAA2C,MAAM,oBAAoB,CAAC;AACnI,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG3G,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,YAAY,GAAG,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,kBAAkB,GAAG,aAAa,CAAC;AAE7I,eAAO,MAAM,WAAW,WAAW,CAAC;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,OAAO,MAAM,EACb,KAAK,MAAM,EACX,MAAM,gBAAgB,EACtB,SAAS,MAAM,EACf,OAAO,MAAM,EACb,QAAQ,MAAM,EACd,OAAO,MAAM,EACb,SAAS,wBAAwB,CAAC,SAAS,CAAC,EAC5C,gBAAe,SAAS,MAAM,EAAO,KACpC,iBAaoB,CAAC;AAwHxB,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,oBAAoB,CAAC;IAC9B;wCACoC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,sBAAsB,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,EAAE,KAAK,sBAAsB,KAAG,qBA0E3E,CAAC"}

package/dist/runtime/step-tick.js

@@ -0,0 +1,177 @@
+import { drawUniform } from "../kernel/stochastic.js";
+import { createCanonicalEventEnvelope, DEFAULT_EMITTER_STREAM_ID, DEFAULT_PRINCIPAL_ID } from "../ledger/stable.js";
+import { resolveClockState } from "./clock.js";
+import { clampAndRound } from "./numeric.js";
+import { runRuleActions } from "./rule-actions.js";
+import { variableTargetFromActions } from "./trace-compile.js";
+import { applyWorldActsAtTick } from "./world-act.js";
+export const WORLD_ACTOR = "@world";
+/**
+ * Shared canonical-envelope constructor for every event kind minted while
+ * stepping a tick (and reused by `trace-run.ts` for its post-hoc
+ * `marker.seen` events, so there is exactly one place that stamps the
+ * causal envelope for simfile-native trace events).
+ */
+export const createTraceEvent = (runId, seq, kind, simTime, actor, target, scope, payload, causeEventIds = []) => createCanonicalEventEnvelope({
+    runId,
+    seq,
+    kind,
+    simTime,
+    provenance: "mechanical",
+    actor,
+    target,
+    scope,
+    payload,
+    streamId: DEFAULT_EMITTER_STREAM_ID,
+    principalId: DEFAULT_PRINCIPAL_ID,
+    causeEventIds
+});
+const runGenerator = (generator, variables, tick, simTime, phase, candidates, runSeed) => {
+    const active = generator.when ? generator.when.evaluator.evaluate(generator.when.node, {
+        tick,
+        simTime,
+        phase,
+        variables,
+        eventsAtTick: candidates
+    }) : true;
+    if (!active) {
+        return;
+    }
+    if (generator.mode === "set") {
+        if (!generator.setExpr) {
+            throw new Error(`generator ${generator.id} missing set expression`);
+        }
+        variables[generator.target] = generator.setExpr.evaluate({
+            variables,
+            tick,
+            t: simTime
+        });
+        return;
+    }
+    if (generator.mode === "delta") {
+        const delta = generator.deltaExpr
+            ? generator.deltaExpr.evaluate({
+                variables,
+                tick,
+                t: simTime
+            })
+            : generator.delta ?? 0;
+        variables[generator.target] = (variables[generator.target] ?? 0) + delta;
+        return;
+    }
+    const [min, max] = generator.uniform ?? [0, 0];
+    const delta = drawUniform({
+        runSeed,
+        generatorId: generator.id,
+        tick,
+        drawIndex: 0,
+        min,
+        max
+    });
+    variables[generator.target] = (variables[generator.target] ?? 0) + delta;
+};
+const runRule = (rule, tick, simTime, phase, tickState, candidates, precision, ranges, runId, nextSeq, emitTickEvent, nextVariables, clockSyncEventId) => {
+    const matches = rule.when.evaluator.evaluate(rule.when.node, {
+        tick,
+        simTime,
+        phase,
+        variables: tickState,
+        eventsAtTick: candidates
+    });
+    const shouldFire = rule.fireMode === "once"
+        ? matches && !rule.hasFired
+        : matches && !rule.previousMatch;
+    rule.previousMatch = matches;
+    if (!shouldFire) {
+        return nextSeq;
+    }
+    rule.hasFired = true;
+    const target = variableTargetFromActions(rule.spec.do);
+    const fired = createTraceEvent(runId, nextSeq, "rule.fired", simTime, rule.id, target, target, {
+        rule: rule.id,
+        tick,
+        sim_time: simTime,
+        phase,
+        ...(rule.variableIds.length > 0 ? { variables: [...rule.variableIds] } : {})
+    }, [clockSyncEventId]);
+    emitTickEvent(fired);
+    candidates.push({ kind: fired.kind, actor: fired.actor, target: fired.target, scope: fired.scope });
+    return runRuleActions(runId, nextSeq + 1, rule.id, tick, simTime, phase, rule.spec.do, tickState, precision, ranges, nextVariables, [fired.event_id], rule.variableIds, emitTickEvent);
+};
+/**
+ * Advances the world by exactly one tick: resolve the clock, apply any
+ * queued world.acts, run generators, recompute derived variables, evaluate
+ * rules (minting their world-effect events), then fold the tick's ending
+ * values back into `ctx.state`. This is the pure REFACTOR extraction of
+ * `runSimfileTrace`'s former inline per-tick loop body — same inputs, same
+ * outputs, same mutation order — so a live driver can call it once per
+ * wall-clock tick instead of only ever inside one big batch loop.
+ */
+export const stepSimfileTick = (tick, ctx) => {
+    const { simTime, phase } = resolveClockState(ctx.clock, tick);
+    const tickEvents = [];
+    const candidates = [];
+    const emitTickEvent = (event) => {
+        tickEvents.push(event);
+        candidates.push({ kind: event.kind, actor: event.actor, target: event.target, scope: event.scope });
+    };
+    let seq = ctx.seq;
+    const clockSync = createTraceEvent(ctx.runId, seq, "clock.sync", simTime, WORLD_ACTOR, "global", "global", {
+        tick,
+        sim_time: simTime,
+        phase
+    });
+    emitTickEvent(clockSync);
+    seq += 1;
+    const tickState = { ...ctx.state };
+    seq = applyWorldActsAtTick(tick, simTime, ctx.worldActsForTick, tickState, {
+        runId: ctx.runId,
+        precision: ctx.precision,
+        ranges: ctx.runtime.ranges,
+        variableScopes: ctx.runtime.variableScopes,
+        resultsByActId: ctx.worldActResultsByActId,
+        nextSeq: seq,
+        emit: emitTickEvent
+    });
+    for (const generator of ctx.runtime.generators) {
+        runGenerator(generator, tickState, tick, simTime, phase, candidates, ctx.seed);
+        const range = ctx.runtime.ranges.get(generator.target);
+        if (!range) {
+            continue;
+        }
+        tickState[generator.target] = clampAndRound(tickState[generator.target] ?? 0, range, ctx.precision);
+    }
+    for (const variableId of ctx.runtime.derivedOrder) {
+        const spec = ctx.runtime.derivedExpressions.get(variableId);
+        const range = ctx.runtime.ranges.get(variableId);
+        if (!spec || !range) {
+            continue;
+        }
+        tickState[variableId] = clampAndRound(spec.expression.evaluate({
+            variables: tickState,
+            tick,
+            t: simTime
+        }), range, ctx.precision);
+    }
+    const nextVariables = { ...tickState };
+    for (const rule of ctx.runtime.rules) {
+        seq = runRule(rule, tick, simTime, phase, tickState, candidates, ctx.precision, ctx.runtime.ranges, ctx.runId, seq, emitTickEvent, nextVariables, clockSync.event_id);
+    }
+    for (const [id, value] of Object.entries(nextVariables)) {
+        const range = ctx.runtime.ranges.get(id);
+        if (!range) {
+            continue;
+        }
+        ctx.state[id] = clampAndRound(value, range, ctx.precision);
+    }
+    return {
+        events: tickEvents,
+        sample: {
+            phase,
+            sim_time: simTime,
+            tick,
+            variables: { ...ctx.state }
+        },
+        nextSeq: seq
+    };
+};

package/dist/runtime/trace-compile.d.ts

@@ -0,0 +1,66 @@
+import type { Simfile, SimfileRule, SimfileRuleAction, SimfileVariable } from "../schema/model.js";
+import { ConditionEvaluator, type ConditionNode } from "./condition.js";
+import { type CompiledExpression } from "./expression.js";
+interface RangeSpec {
+    min: number;
+    max: number;
+}
+interface VariableSpec {
+    id: string;
+    initial: number;
+    range: RangeSpec;
+    spec: SimfileVariable;
+}
+interface DerivedSpec {
+    expression: CompiledExpression;
+}
+export interface GeneratorRuntime {
+    id: string;
+    target: string;
+    range: RangeSpec;
+    mode: "set" | "delta" | "stochastic";
+    when?: {
+        node: ConditionNode;
+        evaluator: ConditionEvaluator;
+    };
+    delta?: number;
+    deltaExpr?: CompiledExpression;
+    setExpr?: CompiledExpression;
+    uniform?: [number, number];
+}
+export interface RuleRuntime {
+    id: string;
+    spec: SimfileRule;
+    when: {
+        node: ConditionNode;
+        evaluator: ConditionEvaluator;
+    };
+    fireMode: "once" | "per_crossing";
+    previousMatch: boolean;
+    hasFired: boolean;
+    /** Every variable id this rule's own `when:` condition references (`conditionVariableIds`) — `[]` for a rule gated on a phase/event condition instead. Threaded onto this rule's `rule.fired` event and every world-effect event it emits, so the viewer can attribute them to that variable's storyline. */
+    variableIds: string[];
+}
+export interface CompiledTraceRuntime {
+    initialState: Record<string, number>;
+    ranges: Map<string, RangeSpec>;
+    derivedOrder: string[];
+    derivedExpressions: Map<string, DerivedSpec>;
+    generators: GeneratorRuntime[];
+    rules: RuleRuntime[];
+    /** Declared `fed_by` writer per fed variable id (world.act authorization). */
+    variableFedBy: Map<string, string>;
+    /** Declared scope per variable id (world.act envelope scope). */
+    variableScopes: Map<string, string>;
+}
+export declare const parseVariableSpecs: (simfile: Simfile) => Map<string, VariableSpec>;
+export declare const parseDerivedSpecs: (variables: ReadonlyMap<string, VariableSpec>) => {
+    order: string[];
+    specs: Map<string, DerivedSpec>;
+};
+export declare const compileGenerators: (simfile: Simfile, ranges: Map<string, RangeSpec>) => GeneratorRuntime[];
+export declare const compileRules: (simfile: Simfile) => RuleRuntime[];
+export declare const compileRuntime: (simfile: Simfile) => CompiledTraceRuntime;
+export declare const variableTargetFromActions: (actions: readonly SimfileRuleAction[]) => string;
+export {};
+//# sourceMappingURL=trace-compile.d.ts.map

package/dist/runtime/trace-compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-compile.d.ts","sourceRoot":"","sources":["../../src/runtime/trace-compile.ts"],"names":[],"mappings":"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"}

package/dist/runtime/trace-compile.js

@@ -0,0 +1,157 @@
+import { parseRange } from "../kernel/range.js";
+import { conditionVariableIds, ConditionEvaluator } from "./condition.js";
+import { compileExpression } from "./expression.js";
+export const parseVariableSpecs = (simfile) => {
+    const variables = new Map();
+    for (const [id, spec] of Object.entries(simfile.variables)) {
+        const range = parseRange(spec.range);
+        const initial = spec.initial ?? 0;
+        const rawInitial = Number.isFinite(initial) ? initial : 0;
+        variables.set(id, { id, initial: rawInitial, range, spec });
+    }
+    return variables;
+};
+const compileWhen = (node) => ({
+    node: node,
+    evaluator: new ConditionEvaluator()
+});
+const compareIds = (left, right) => {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+};
+const compileGenerator = (generatorId, generator, ranges) => {
+    const range = ranges.get(generator.variable);
+    if (!range) {
+        throw new Error(`generator ${generatorId} references unknown variable ${generator.variable}`);
+    }
+    if (generator.kind === "stochastic") {
+        const [min = 0, max = 0] = generator.uniform;
+        return {
+            id: generatorId,
+            target: generator.variable,
+            range,
+            mode: "stochastic",
+            uniform: [min, max],
+            when: generator.when ? compileWhen(generator.when) : undefined
+        };
+    }
+    if (generator.delta !== undefined) {
+        return {
+            id: generatorId,
+            target: generator.variable,
+            range,
+            mode: "delta",
+            delta: generator.delta,
+            when: generator.when ? compileWhen(generator.when) : undefined
+        };
+    }
+    if (generator.delta_eq !== undefined) {
+        return {
+            id: generatorId,
+            target: generator.variable,
+            range,
+            mode: "delta",
+            deltaExpr: compileExpression(generator.delta_eq),
+            when: generator.when ? compileWhen(generator.when) : undefined
+        };
+    }
+    return {
+        id: generatorId,
+        target: generator.variable,
+        range,
+        mode: "set",
+        setExpr: compileExpression(generator.set_eq ?? "0"),
+        when: generator.when ? compileWhen(generator.when) : undefined
+    };
+};
+export const parseDerivedSpecs = (variables) => {
+    const specs = new Map();
+    for (const [id, variable] of variables.entries()) {
+        if (variable.spec.derive === undefined) {
+            continue;
+        }
+        specs.set(id, { expression: compileExpression(variable.spec.derive.eq) });
+    }
+    const order = [];
+    const seen = new Set();
+    const stack = new Set();
+    const visit = (variableId) => {
+        if (seen.has(variableId)) {
+            return;
+        }
+        if (stack.has(variableId)) {
+            throw new Error(`derived variable cycle at ${variableId}`);
+        }
+        stack.add(variableId);
+        const spec = specs.get(variableId);
+        if (spec) {
+            for (const dependency of spec.expression.dependencies) {
+                if (specs.has(dependency)) {
+                    visit(dependency);
+                }
+            }
+        }
+        stack.delete(variableId);
+        seen.add(variableId);
+        order.push(variableId);
+    };
+    for (const variableId of specs.keys()) {
+        visit(variableId);
+    }
+    return { order, specs };
+};
+export const compileGenerators = (simfile, ranges) => {
+    return Object.entries(simfile.generators)
+        .sort(([left], [right]) => compareIds(left, right))
+        .map(([generatorId, generator]) => compileGenerator(generatorId, generator, ranges));
+};
+export const compileRules = (simfile) => {
+    return Object.entries(simfile.rules)
+        .sort(([left], [right]) => compareIds(left, right))
+        .map(([ruleId, rule]) => ({
+        id: ruleId,
+        spec: rule,
+        when: compileWhen(rule.when),
+        fireMode: rule.fire,
+        previousMatch: false,
+        hasFired: false,
+        variableIds: conditionVariableIds(rule.when)
+    }));
+};
+export const compileRuntime = (simfile) => {
+    const variables = parseVariableSpecs(simfile);
+    const initialState = {};
+    const ranges = new Map();
+    const variableFedBy = new Map();
+    const variableScopes = new Map();
+    for (const [id, spec] of variables.entries()) {
+        initialState[id] = spec.initial;
+        ranges.set(id, spec.range);
+        variableScopes.set(id, spec.spec.scope);
+        if (spec.spec.fed_by !== undefined) {
+            variableFedBy.set(id, spec.spec.fed_by);
+        }
+    }
+    const { order, specs: derivedExpressions } = parseDerivedSpecs(variables);
+    return {
+        initialState,
+        ranges,
+        derivedOrder: order,
+        derivedExpressions,
+        generators: compileGenerators(simfile, ranges),
+        rules: compileRules(simfile),
+        variableFedBy,
+        variableScopes
+    };
+};
+export const variableTargetFromActions = (actions) => {
+    for (const action of actions) {
+        if ("to" in action) {
+            return action.to;
+        }
+    }
+    return "global";
+};

package/dist/runtime/trace-export.d.ts

@@ -0,0 +1,5 @@
+import { scanMarkers, type MarkerDefinition } from "../ledger/markers.js";
+import type { RuntimeTraceEvent } from "./types.js";
+export declare const serializeCanonicalEvents: (events: readonly RuntimeTraceEvent[]) => string[];
+export declare const scanTraceMarkers: (events: readonly RuntimeTraceEvent[], markers: Record<string, MarkerDefinition>) => ReturnType<typeof scanMarkers>;
+//# sourceMappingURL=trace-export.d.ts.map

package/dist/runtime/trace-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-export.d.ts","sourceRoot":"","sources":["../../src/runtime/trace-export.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,eAAO,MAAM,wBAAwB,GAAI,QAAQ,SAAS,iBAAiB,EAAE,KAAG,MAAM,EACzD,CAAC;AAE9B,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,SAAS,iBAAiB,EAAE,EACpC,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KACxC,UAAU,CAAC,OAAO,WAAW,CAAiC,CAAC"}

package/dist/runtime/trace-export.js

@@ -0,0 +1,4 @@
+import { scanMarkers } from "../ledger/markers.js";
+import { stableStringify } from "../ledger/stable.js";
+export const serializeCanonicalEvents = (events) => events.map(stableStringify);
+export const scanTraceMarkers = (events, markers) => scanMarkers(events, markers);

package/dist/runtime/trace-run.d.ts

@@ -0,0 +1,15 @@
+import type { Simfile } from "../schema/model.js";
+import type { RuntimeOptions, RuntimeTrace } from "./types.js";
+/**
+ * Executes a bounded deterministic trace by looping `stepSimfileTick` once
+ * per tick (the REFACTOR extraction, Slice memetics-a): all per-tick
+ * mechanics — clock resolve, world-act application, generators, derived
+ * variables, rules — live in `step-tick.ts` now, so a live driver can call
+ * the exact same function once per wall-clock tick instead of only inside
+ * this one big batch loop. This function's own job shrinks to setup
+ * (compile + initial state + world-act ingestion), the loop itself, and the
+ * post-hoc marker scan over the whole run's events — output is unchanged
+ * from before the extraction (see `trace.test.ts`, which is untouched).
+ */
+export declare const runSimfileTrace: (simfile: Simfile, options: RuntimeOptions) => RuntimeTrace;
+//# sourceMappingURL=trace-run.d.ts.map

package/dist/runtime/trace-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-run.d.ts","sourceRoot":"","sources":["../../src/runtime/trace-run.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAKlD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAA4C,MAAM,YAAY,CAAC;AAYzG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,SAAS,OAAO,EAAE,SAAS,cAAc,KAAG,YAyE3E,CAAC"}

package/dist/runtime/trace-run.js

@@ -0,0 +1,92 @@
+import { scanMarkers } from "../ledger/markers.js";
+import { parseClockSpec } from "./clock.js";
+import { clampAndRound } from "./numeric.js";
+import { createTraceEvent, stepSimfileTick } from "./step-tick.js";
+import { compileRuntime } from "./trace-compile.js";
+import { ingestWorldActs } from "./world-act.js";
+const DEFAULT_PRECISION = 6;
+const EVENT_FUSE_LIMIT = 5_000;
+const validateNonNegativeInteger = (value, name) => {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative integer`);
+    }
+};
+/**
+ * Executes a bounded deterministic trace by looping `stepSimfileTick` once
+ * per tick (the REFACTOR extraction, Slice memetics-a): all per-tick
+ * mechanics — clock resolve, world-act application, generators, derived
+ * variables, rules — live in `step-tick.ts` now, so a live driver can call
+ * the exact same function once per wall-clock tick instead of only inside
+ * this one big batch loop. This function's own job shrinks to setup
+ * (compile + initial state + world-act ingestion), the loop itself, and the
+ * post-hoc marker scan over the whole run's events — output is unchanged
+ * from before the extraction (see `trace.test.ts`, which is untouched).
+ */
+export const runSimfileTrace = (simfile, options) => {
+    const precision = Math.max(0, Math.floor(options.precision ?? DEFAULT_PRECISION));
+    validateNonNegativeInteger(precision, "precision");
+    validateNonNegativeInteger(options.ticks, "ticks");
+    const clock = parseClockSpec(simfile.clock);
+    const runtime = compileRuntime(simfile);
+    const state = {};
+    for (const [id, value] of Object.entries(runtime.initialState)) {
+        const range = runtime.ranges.get(id);
+        if (!range) {
+            throw new Error(`variable ${id} missing range`);
+        }
+        state[id] = clampAndRound(value, range, precision);
+    }
+    const worldActIngestion = ingestWorldActs(options.worldActs ?? [], {
+        ticks: options.ticks,
+        ranges: runtime.ranges,
+        variableFedBy: runtime.variableFedBy
+    });
+    const events = [];
+    const samples = [];
+    let seq = 1;
+    const emitEvent = (event) => {
+        events.push(event);
+        if (events.length > options.ticks * EVENT_FUSE_LIMIT) {
+            throw new Error(`event fuse tripped at ${events.length} events`);
+        }
+    };
+    for (let tick = 0; tick < options.ticks; tick += 1) {
+        const step = stepSimfileTick(tick, {
+            runId: options.runId,
+            seed: options.seed,
+            precision,
+            clock,
+            runtime,
+            state,
+            seq,
+            worldActsForTick: worldActIngestion.queueByTick.get(tick),
+            worldActResultsByActId: worldActIngestion.resultsByActId
+        });
+        seq = step.nextSeq;
+        samples.push(step.sample);
+        for (const event of step.events) {
+            emitEvent(event);
+        }
+    }
+    for (const [markerId, hits] of Object.entries(scanMarkers(events, simfile.markers))) {
+        for (const hit of hits) {
+            emitEvent(createTraceEvent(options.runId, seq, "marker.seen", hit.simTime, markerId, hit.scope, hit.scope, {
+                alias: hit.alias,
+                marker: markerId,
+                source_event_id: hit.eventId,
+                source_event_kind: hit.eventKind
+            }, [hit.eventId]));
+            seq += 1;
+        }
+    }
+    return {
+        runId: options.runId,
+        seed: options.seed,
+        ticks: options.ticks,
+        variables: state,
+        events,
+        samples,
+        diagnostics: [],
+        actResults: worldActIngestion.results
+    };
+};

package/dist/runtime/trace.d.ts

@@ -0,0 +1,10 @@
+export * from "./clock.js";
+export * from "./condition.js";
+export * from "./expression.js";
+export * from "./run-record.js";
+export * from "./step-tick.js";
+export * from "./trace-export.js";
+export * from "./trace-run.js";
+export * from "./viewer-trace.js";
+export * from "./world-act.js";
+//# sourceMappingURL=trace.d.ts.map

package/dist/runtime/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/runtime/trace.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC"}

package/dist/runtime/trace.js

@@ -0,0 +1,9 @@
+export * from "./clock.js";
+export * from "./condition.js";
+export * from "./expression.js";
+export * from "./run-record.js";
+export * from "./step-tick.js";
+export * from "./trace-export.js";
+export * from "./trace-run.js";
+export * from "./viewer-trace.js";
+export * from "./world-act.js";

package/dist/runtime/types.d.ts

@@ -0,0 +1,61 @@
+import type { LedgerEventEnvelope } from "../ledger/stable.js";
+/**
+ * A world.act queued for deterministic ingestion at a given tick. This is the
+ * B58 driver stand-in for a live agent tool call: `run_id`, `actor`,
+ * `principal_id`, and `cause_event_ids` are trusted-injection fields (never
+ * model-supplied); `act_id`, `action`, `variable`, `value` are the only
+ * model-authored fields per the `world_act` tool surface.
+ */
+export interface QueuedWorldAct {
+    at_tick: number;
+    act_id: string;
+    action: "variable:set";
+    variable: string;
+    value: number;
+    actor: string;
+    principal_id: string;
+    cause_event_ids?: string[];
+}
+/** Rejection codes for a queued world.act, in ingestion check order. */
+export type WorldActRejectionCode = "unknown_variable" | "not_authorized" | "out_of_range" | "not_finite" | "duplicate" | "run_closed";
+/** Tool-facing outcome of ingesting a single queued world.act. */
+export interface WorldActResult {
+    accepted: boolean;
+    act_id: string;
+    event_id?: string;
+    apply_tick?: number;
+    code?: WorldActRejectionCode;
+}
+export interface RuntimeOptions {
+    runId: string;
+    seed: string;
+    ticks: number;
+    precision?: number;
+    worldActs?: readonly QueuedWorldAct[];
+}
+export type RuntimeTraceEventPayload = Record<string, unknown> | Array<unknown> | string | number | boolean | null;
+/**
+ * A single runtime-emitted trace event. This is a `LedgerEventEnvelope`: every
+ * event produced by `runSimfileTrace` carries the full causal envelope
+ * (version, run_id, emitter, principal_id, recorded_at, cause_event_ids) —
+ * those fields are typed optional here only so hand-written fixtures in other
+ * modules' tests (which predate the causal envelope) keep type-checking.
+ */
+export type RuntimeTraceEvent = LedgerEventEnvelope<RuntimeTraceEventPayload>;
+export interface RuntimeVariableSample {
+    phase: string | undefined;
+    sim_time: number;
+    tick: number;
+    variables: Record<string, number>;
+}
+export interface RuntimeTrace {
+    runId: string;
+    seed: string;
+    ticks: number;
+    variables: Record<string, number>;
+    events: RuntimeTraceEvent[];
+    samples: RuntimeVariableSample[];
+    diagnostics: string[];
+    actResults: WorldActResult[];
+}
+//# sourceMappingURL=types.d.ts.map