simfile 0.0.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/runtime/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,wEAAwE;AACxE,MAAM,MAAM,qBAAqB,GAC7B,kBAAkB,GAClB,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,WAAW,GACX,YAAY,CAAC;AAEjB,kEAAkE;AAClE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,qBAAqB,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACvC;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAEnH;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,CAAC,wBAAwB,CAAC,CAAC;AAE9E,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B"}

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,64 @@
+import type { MarkerCoverageResult } from "../ledger/markers.js";
+import type { ProbeEvaluationResult } from "../report/probes.js";
+import type { Simfile } from "../schema/model.js";
+import type { RuntimeTrace, RuntimeTraceEvent } from "./types.js";
+export interface ViewerTraceRoom {
+    id: string;
+    label: string;
+    members: string[];
+    scene: [number, number, number];
+    scale?: [number, number];
+    scope: string;
+}
+export interface ViewerTraceCorridor {
+    from_room: string;
+    id: string;
+    path: Array<{
+        x: number;
+        y: number;
+    }>;
+    to_room: string;
+    width?: number;
+}
+export interface ViewerTraceAgent {
+    detail?: string;
+    id: string;
+    label?: string;
+    label_hint?: string;
+    scope: string;
+}
+export interface ViewerTraceFact {
+    actor: string;
+    detail: string;
+    event_id: string;
+    kind: string;
+    payload: RuntimeTraceEvent["payload"];
+    provenance: RuntimeTraceEvent["provenance"];
+    scope?: string;
+    sim_time: number;
+    target: string;
+    tick: number;
+    type: "clock.sync" | "world.message" | "world.dm" | "wake.recommended" | "rule.fired" | "marker.seen" | "probe" | "other";
+}
+export interface ViewerTraceSignal {
+    detail: string;
+    id: string;
+    kind: "variable" | "marker" | "probe";
+    label: string;
+    scene: [number, number, number];
+    scope: string;
+    value: string;
+}
+export interface ViewerContractTrace {
+    agents: ViewerTraceAgent[];
+    corridors: ViewerTraceCorridor[];
+    ledger_facts: ViewerTraceFact[];
+    presence: [];
+    rooms: ViewerTraceRoom[];
+    run_id: string;
+    run_name: string;
+    signals: ViewerTraceSignal[];
+    version: "viewer.trace.v1";
+}
+export declare const buildViewerTrace: (simfile: Simfile, trace: RuntimeTrace, markers: readonly MarkerCoverageResult[], probes: readonly ProbeEvaluationResult[]) => ViewerContractTrace;
+//# sourceMappingURL=viewer-trace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"viewer-trace.d.ts","sourceRoot":"","sources":["../../src/runtime/viewer-trace.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACtC,UAAU,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,UAAU,GAAG,kBAAkB,GAAG,YAAY,GAAG,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC;CAC3H;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,QAAQ,EAAE,EAAE,CAAC;IACb,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AA0KD,eAAO,MAAM,gBAAgB,GAC3B,SAAS,OAAO,EAChB,OAAO,YAAY,EACnB,SAAS,SAAS,oBAAoB,EAAE,EACxC,QAAQ,SAAS,qBAAqB,EAAE,KACvC,mBAaF,CAAC"}

package/dist/runtime/viewer-trace.js

@@ -0,0 +1,164 @@
+const roomScopePattern = /^room:([^:]+):([^:]+)$/u;
+const agentScopePattern = /^agent:([^:]+)$/u;
+const roomIdFromScope = (scope) => scope.match(roomScopePattern)?.[2];
+const agentIdFromScope = (scope) => scope.match(agentScopePattern)?.[1];
+const roomScopesFromEvent = (event) => [event.scope, event.target].filter((scope) => roomScopePattern.test(scope));
+const contentDetail = (event) => {
+    const payload = typeof event.payload === "object" && event.payload !== null
+        ? event.payload
+        : {};
+    const content = payload.content;
+    if (typeof content === "string") {
+        return content;
+    }
+    const reason = payload.reason;
+    if (typeof reason === "string") {
+        return reason;
+    }
+    return event.kind;
+};
+const tickForEvent = (trace, event) => {
+    const matching = trace.samples.find((sample) => sample.sim_time === event.sim_time);
+    return matching?.tick ?? 0;
+};
+const sceneForIndex = (index, count) => {
+    const cols = Math.max(1, Math.ceil(Math.sqrt(count)));
+    const row = Math.floor(index / cols);
+    const col = index % cols;
+    const x = (col - (cols - 1) / 2) * 2.4;
+    const y = (row - Math.max(0, Math.ceil(count / cols) - 1) / 2) * 1.85;
+    return [Number(x.toFixed(2)), Number(y.toFixed(2)), 0];
+};
+const buildRooms = (simfile, trace) => {
+    const scopes = new Set();
+    for (const variable of Object.values(simfile.variables)) {
+        if (roomScopePattern.test(variable.scope))
+            scopes.add(variable.scope);
+    }
+    for (const marker of Object.values(simfile.markers)) {
+        for (const scope of marker.scopes)
+            if (roomScopePattern.test(scope))
+                scopes.add(scope);
+    }
+    for (const event of trace.events) {
+        for (const scope of roomScopesFromEvent(event))
+            scopes.add(scope);
+    }
+    return [...scopes].sort().map((scope, index, all) => {
+        const id = roomIdFromScope(scope) ?? `room-${index}`;
+        return {
+            id,
+            label: id,
+            members: [],
+            scene: sceneForIndex(index, all.length),
+            scale: [1.4, 0.9],
+            scope
+        };
+    });
+};
+const buildCorridors = (rooms) => rooms.slice(1).map((room, index) => {
+    const from = rooms[index];
+    const [ax, ay] = from.scene;
+    const [bx, by] = room.scene;
+    return {
+        from_room: from.id,
+        id: `${from.id}--${room.id}`,
+        path: [
+            { x: ax, y: ay },
+            { x: bx, y: ay },
+            { x: bx, y: by }
+        ],
+        to_room: room.id,
+        width: 0.08
+    };
+});
+const buildAgents = (trace) => {
+    const agents = new Set();
+    for (const event of trace.events) {
+        const target = agentIdFromScope(event.target);
+        if (target)
+            agents.add(target);
+        if (event.provenance === "agentic" && event.actor !== "@world")
+            agents.add(event.actor);
+    }
+    return [...agents].sort().map((id) => ({
+        detail: "Heuristic placement: trace has this agent but no presence stream yet.",
+        id,
+        label: id,
+        label_hint: "heuristic",
+        scope: `agent:${id}`
+    }));
+};
+const factType = (kind) => {
+    if (kind === "clock.sync"
+        || kind === "world.message"
+        || kind === "world.dm"
+        || kind === "wake.recommended"
+        || kind === "rule.fired"
+        || kind === "marker.seen") {
+        return kind;
+    }
+    return "other";
+};
+const buildFacts = (trace) => trace.events.map((event) => ({
+    actor: event.actor,
+    detail: contentDetail(event),
+    event_id: event.event_id,
+    kind: event.kind,
+    payload: event.payload,
+    provenance: event.provenance,
+    scope: event.scope,
+    sim_time: event.sim_time,
+    target: event.target,
+    tick: tickForEvent(trace, event),
+    type: factType(event.kind)
+}));
+const buildSignals = (simfile, trace, markers, probes, rooms) => {
+    const roomByScope = new Map(rooms.map((room) => [room.scope, room.scene]));
+    const signalAt = (scope, offset) => {
+        const [x, y] = roomByScope.get(scope) ?? [0, 0, 0];
+        return [x + offset, y - 0.8, 0.58];
+    };
+    const variables = Object.entries(simfile.variables).map(([id, variable], index) => ({
+        detail: "Final variable value from runtime samples.",
+        id,
+        kind: "variable",
+        label: id,
+        scene: signalAt(variable.scope, index * 0.22),
+        scope: variable.scope,
+        value: String(trace.variables[id] ?? 0)
+    }));
+    const markerSignals = markers.map((marker, index) => ({
+        detail: marker.detail,
+        id: marker.markerId,
+        kind: "marker",
+        label: marker.markerId,
+        scene: signalAt(simfile.markers[marker.markerId]?.scopes[0] ?? "global", index * 0.22),
+        scope: simfile.markers[marker.markerId]?.scopes[0] ?? "global",
+        value: marker.passed ? "pass" : "fail"
+    }));
+    const probeSignals = probes.map((probe, index) => ({
+        detail: `${probe.count} matching event(s)`,
+        id: probe.probeId,
+        kind: "probe",
+        label: probe.probeId,
+        scene: [index * 0.26, -1.8, 0.58],
+        scope: `probe:${probe.probeId}`,
+        value: probe.passed ? "pass" : "fail"
+    }));
+    return [...variables, ...markerSignals, ...probeSignals];
+};
+export const buildViewerTrace = (simfile, trace, markers, probes) => {
+    const rooms = buildRooms(simfile, trace);
+    return {
+        agents: buildAgents(trace),
+        corridors: buildCorridors(rooms),
+        ledger_facts: buildFacts(trace),
+        presence: [],
+        rooms,
+        run_id: trace.runId,
+        run_name: simfile.name,
+        signals: buildSignals(simfile, trace, markers, probes, rooms),
+        version: "viewer.trace.v1"
+    };
+};

package/dist/runtime/world-act.d.ts

@@ -0,0 +1,55 @@
+import type { RangeSpec } from "./numeric.js";
+import type { QueuedWorldAct, RuntimeTraceEvent, WorldActResult, WorldActRejectionCode } from "./types.js";
+/** Simfile's single generic act kind. Its only action at B58 is `variable:set`. */
+export declare const WORLD_ACT_KIND: "world.act";
+export interface WorldActValidationContext {
+    ticks: number;
+    ranges: ReadonlyMap<string, RangeSpec>;
+    variableFedBy: ReadonlyMap<string, string>;
+    seenActIds: Set<string>;
+}
+/**
+ * Ingestion order (exact, per B58 protocol):
+ * 1. dedup (act_id registers on first ingestion regardless of outcome)
+ * 2. run_closed (batch: at_tick >= options.ticks)
+ * 3. unknown_variable
+ * 4. not_authorized (no fed_by, or fed_by !== actor)
+ * 5. not_finite / out_of_range (reject, never clamp)
+ */
+export declare const validateWorldAct: (act: QueuedWorldAct, ctx: WorldActValidationContext) => WorldActRejectionCode | undefined;
+export interface WorldActIngestion {
+    /** Every queued act's result, in original submission (ingress) order. Objects are shared with `resultsByActId` and get their `event_id` filled in as accepted acts are applied. */
+    results: WorldActResult[];
+    resultsByActId: Map<string, WorldActResult>;
+    /** Accepted acts grouped by `at_tick`, preserving ingress order (last write wins on apply). */
+    queueByTick: Map<number, QueuedWorldAct[]>;
+}
+/**
+ * Validates every queued act up front (all inputs the checks depend on —
+ * declared ranges, declared fed_by, total tick count — are static for a run),
+ * without minting any ledger events yet. Accepted acts are grouped by their
+ * `at_tick` for `applyWorldActsAtTick` to apply and mint during the trace loop.
+ */
+export declare const ingestWorldActs: (acts: readonly QueuedWorldAct[], ctx: {
+    ticks: number;
+    ranges: ReadonlyMap<string, RangeSpec>;
+    variableFedBy: ReadonlyMap<string, string>;
+}) => WorldActIngestion;
+export interface ApplyWorldActsContext {
+    runId: string;
+    precision: number;
+    ranges: ReadonlyMap<string, RangeSpec>;
+    variableScopes: ReadonlyMap<string, string>;
+    resultsByActId: ReadonlyMap<string, WorldActResult>;
+    nextSeq: number;
+    emit: (event: RuntimeTraceEvent) => void;
+}
+/**
+ * Applies every accepted act queued for this tick, in ingress order (last
+ * write wins on shared var/tick). Called at the START of tick processing,
+ * after that tick's clock.sync and before generators/derived/rules, so the
+ * write lands in `tickState` and the minted event is visible to same-tick
+ * `event: world.act` conditions and rules.
+ */
+export declare const applyWorldActsAtTick: (tick: number, simTime: number, queuedForTick: readonly QueuedWorldAct[] | undefined, tickState: Record<string, number>, ctx: ApplyWorldActsContext) => number;
+//# sourceMappingURL=world-act.d.ts.map

package/dist/runtime/world-act.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-act.d.ts","sourceRoot":"","sources":["../../src/runtime/world-act.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE3G,mFAAmF;AACnF,eAAO,MAAM,cAAc,EAAG,WAAoB,CAAC;AAyCnD,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACvC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,cAAc,EACnB,KAAK,yBAAyB,KAC7B,qBAAqB,GAAG,SA6B1B,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,mLAAmL;IACnL,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,+FAA+F;IAC/F,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,SAAS,cAAc,EAAE,EAC/B,KAAK;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KACzG,iBA8BF,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACvC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,EACZ,SAAS,MAAM,EACf,eAAe,SAAS,cAAc,EAAE,GAAG,SAAS,EACpD,WAAW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,KAAK,qBAAqB,KACzB,MAoDF,CAAC"}

package/dist/runtime/world-act.js

@@ -0,0 +1,156 @@
+import { createCanonicalEventEnvelope, DEFAULT_EMITTER_STREAM_ID } from "../ledger/stable.js";
+import { clampAndRound } from "./numeric.js";
+/** Simfile's single generic act kind. Its only action at B58 is `variable:set`. */
+export const WORLD_ACT_KIND = "world.act";
+const MAX_ACT_ID_LENGTH = 128;
+const isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+/**
+ * Malformed acts (missing fields, unknown action, non-numeric value) are
+ * transport/schema errors — rejected before ingestion, not surfaced as a
+ * `WorldActResult` rejection code.
+ */
+const assertWellFormedQueuedWorldAct = (act) => {
+    if (!Number.isInteger(act.at_tick) || act.at_tick < 0) {
+        throw new Error(`world.act at_tick must be a non-negative integer: ${String(act.at_tick)}`);
+    }
+    if (!isNonEmptyString(act.act_id) || act.act_id.length > MAX_ACT_ID_LENGTH) {
+        throw new Error("world.act act_id must be a non-empty string of at most 128 characters");
+    }
+    if (act.action !== "variable:set") {
+        throw new Error(`world.act action must be variable:set, got ${String(act.action)}`);
+    }
+    if (!isNonEmptyString(act.variable)) {
+        throw new Error("world.act variable must be a non-empty string");
+    }
+    if (typeof act.value !== "number") {
+        throw new Error(`world.act value must be numeric for act ${act.act_id}`);
+    }
+    if (!isNonEmptyString(act.actor)) {
+        throw new Error("world.act actor must be a non-empty string");
+    }
+    if (!isNonEmptyString(act.principal_id)) {
+        throw new Error("world.act principal_id must be a non-empty string");
+    }
+    if (act.cause_event_ids !== undefined) {
+        if (!Array.isArray(act.cause_event_ids) || act.cause_event_ids.some((id) => !isNonEmptyString(id))) {
+            throw new Error("world.act cause_event_ids must be an array of non-empty strings");
+        }
+    }
+};
+/**
+ * Ingestion order (exact, per B58 protocol):
+ * 1. dedup (act_id registers on first ingestion regardless of outcome)
+ * 2. run_closed (batch: at_tick >= options.ticks)
+ * 3. unknown_variable
+ * 4. not_authorized (no fed_by, or fed_by !== actor)
+ * 5. not_finite / out_of_range (reject, never clamp)
+ */
+export const validateWorldAct = (act, ctx) => {
+    if (ctx.seenActIds.has(act.act_id)) {
+        return "duplicate";
+    }
+    ctx.seenActIds.add(act.act_id);
+    if (act.at_tick >= ctx.ticks) {
+        return "run_closed";
+    }
+    const range = ctx.ranges.get(act.variable);
+    if (!range) {
+        return "unknown_variable";
+    }
+    const fedBy = ctx.variableFedBy.get(act.variable);
+    if (fedBy === undefined || fedBy !== act.actor) {
+        return "not_authorized";
+    }
+    if (!Number.isFinite(act.value)) {
+        return "not_finite";
+    }
+    if (act.value < range.min || act.value > range.max) {
+        return "out_of_range";
+    }
+    return undefined;
+};
+/**
+ * Validates every queued act up front (all inputs the checks depend on —
+ * declared ranges, declared fed_by, total tick count — are static for a run),
+ * without minting any ledger events yet. Accepted acts are grouped by their
+ * `at_tick` for `applyWorldActsAtTick` to apply and mint during the trace loop.
+ */
+export const ingestWorldActs = (acts, ctx) => {
+    const seenActIds = new Set();
+    const results = [];
+    const resultsByActId = new Map();
+    const queueByTick = new Map();
+    for (const act of acts) {
+        assertWellFormedQueuedWorldAct(act);
+        const code = validateWorldAct(act, {
+            ticks: ctx.ticks,
+            ranges: ctx.ranges,
+            variableFedBy: ctx.variableFedBy,
+            seenActIds
+        });
+        const result = code
+            ? { accepted: false, act_id: act.act_id, code }
+            : { accepted: true, act_id: act.act_id, apply_tick: act.at_tick };
+        results.push(result);
+        resultsByActId.set(act.act_id, result);
+        if (!code) {
+            const queued = queueByTick.get(act.at_tick) ?? [];
+            queued.push(act);
+            queueByTick.set(act.at_tick, queued);
+        }
+    }
+    return { results, resultsByActId, queueByTick };
+};
+/**
+ * Applies every accepted act queued for this tick, in ingress order (last
+ * write wins on shared var/tick). Called at the START of tick processing,
+ * after that tick's clock.sync and before generators/derived/rules, so the
+ * write lands in `tickState` and the minted event is visible to same-tick
+ * `event: world.act` conditions and rules.
+ */
+export const applyWorldActsAtTick = (tick, simTime, queuedForTick, tickState, ctx) => {
+    if (!queuedForTick || queuedForTick.length === 0) {
+        return ctx.nextSeq;
+    }
+    let seq = ctx.nextSeq;
+    for (const act of queuedForTick) {
+        const range = ctx.ranges.get(act.variable);
+        if (!range) {
+            throw new Error(`world.act references unknown variable ${act.variable}`);
+        }
+        tickState[act.variable] = clampAndRound(act.value, range, ctx.precision);
+        const scope = ctx.variableScopes.get(act.variable) ?? "global";
+        const payload = {
+            sim_time: simTime,
+            provenance: "agentic",
+            actor: act.actor,
+            target: act.variable,
+            scope,
+            act_id: act.act_id,
+            action: act.action,
+            value: act.value
+        };
+        const event = createCanonicalEventEnvelope({
+            runId: ctx.runId,
+            seq,
+            kind: WORLD_ACT_KIND,
+            simTime,
+            provenance: "agentic",
+            actor: act.actor,
+            target: act.variable,
+            scope,
+            payload,
+            streamId: DEFAULT_EMITTER_STREAM_ID,
+            principalId: act.principal_id,
+            causeEventIds: act.cause_event_ids ?? []
+        });
+        ctx.emit(event);
+        const result = ctx.resultsByActId.get(act.act_id);
+        if (result) {
+            result.event_id = event.event_id;
+            result.apply_tick = tick;
+        }
+        seq += 1;
+    }
+    return seq;
+};

package/dist/schema/binding.d.ts

@@ -0,0 +1,23 @@
+import type { Simfile } from "./model.js";
+export interface BindingDiagnostic {
+    level: "error" | "warn";
+    message: string;
+}
+export interface SpawnfileReportNode {
+    id?: unknown;
+    active_environments?: unknown;
+}
+export interface SpawnfileReport {
+    nodes?: unknown;
+}
+interface ScopeIndex {
+    agents: Set<string>;
+    rooms: Set<string>;
+    teams: Set<string>;
+}
+export declare const createReportScopeIndex: (report: SpawnfileReport) => ScopeIndex;
+export declare const createBindingDiagnostics: (simfile: Simfile, report: SpawnfileReport | null) => BindingDiagnostic[];
+export declare const parseSpawnfileReportJson: (reportJson: string) => SpawnfileReport;
+export declare const loadSpawnfileReport: (pathOrJson: string) => Promise<SpawnfileReport>;
+export {};
+//# sourceMappingURL=binding.d.ts.map

package/dist/schema/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/schema/binding.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,OAAO,EAKR,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACpB;AAwFD,eAAO,MAAM,sBAAsB,GAAI,QAAQ,eAAe,KAAG,UAgBhE,CAAC;AAqLF,eAAO,MAAM,wBAAwB,GAAI,SAAS,OAAO,EAAE,QAAQ,eAAe,GAAG,IAAI,KAAG,iBAAiB,EAqB5G,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,YAAY,MAAM,KAAG,eAa7D,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAU,YAAY,MAAM,KAAG,OAAO,CAAC,eAAe,CAcrF,CAAC"}