@ottochain/sdk 2.4.0 → 2.6.0

package/dist/esm/privacy/sealed-bid.js

@@ -11,45 +11,45 @@
  *     (the Vickrey price). This is the one shared-state step, kept simple for v1; a zk settlement
  *     proof that seals losers' amounts forever is the deferred upgrade (RFC §10).
  */
-import { defineFiberApp } from "../schema/fiber-app.js";
-import { shieldApp } from "./shield-app.js";
+import { defineFiberApp } from '../schema/fiber-app.js';
+import { shieldApp } from './shield-app.js';
 // ── 1. The private bid (base app, shielded by shieldApp) ──────────────────────
 /** The per-bidder PRIVATE state: a bid note `{ amount, bidder, nonce }`. */
 export const sealedBidAccountDef = defineFiberApp({
     metadata: {
-        name: "SealedBidAccount",
-        app: "markets",
-        type: "sealed-bid-account",
-        version: "1.0.0",
+        name: 'SealedBidAccount',
+        app: 'markets',
+        type: 'sealed-bid-account',
+        version: '1.0.0',
         description: "A single bidder's sealed bid (private amount). Shielded via shieldApp.",
     },
     stateSchema: {
         properties: {
-            amount: { type: "number", description: "the (private) bid amount" },
-            bidder: { type: "address" },
-            nonce: { type: "number", description: "per-note randomness; keeps the commitment hiding" },
+            amount: { type: 'number', description: 'the (private) bid amount' },
+            bidder: { type: 'address' },
+            nonce: { type: 'number', description: 'per-note randomness; keeps the commitment hiding' },
         },
     },
     eventSchemas: {
         place_bid: {
-            description: "Set the sealed bid amount",
-            required: ["amount"],
-            properties: { amount: { type: "number", minimum: 1 } },
+            description: 'Set the sealed bid amount',
+            required: ['amount'],
+            properties: { amount: { type: 'number', minimum: 1 } },
         },
     },
     states: {
-        OPEN: { id: "OPEN", isFinal: false, metadata: { label: "Open", description: "No bid yet", category: "initial" } },
-        BID: { id: "BID", isFinal: false, metadata: { label: "Bid", description: "Bid committed", category: "active" } },
+        OPEN: { id: 'OPEN', isFinal: false, metadata: { label: 'Open', description: 'No bid yet', category: 'initial' } },
+        BID: { id: 'BID', isFinal: false, metadata: { label: 'Bid', description: 'Bid committed', category: 'active' } },
     },
-    initialState: "OPEN",
+    initialState: 'OPEN',
     transitions: [
         {
             // This effect is what the zk-jlvm-shielded circuit runs in-zkVM; `exprHash` pins it.
-            from: "OPEN",
-            to: "BID",
-            eventName: "place_bid",
-            guard: { ">": [{ var: "event.amount" }, 0] },
-            effect: { merge: [{ var: "state" }, { amount: { var: "event.amount" } }] },
+            from: 'OPEN',
+            to: 'BID',
+            eventName: 'place_bid',
+            guard: { '>': [{ var: 'event.amount' }, 0] },
+            effect: { merge: [{ var: 'state' }, { amount: { var: 'event.amount' } }] },
             dependencies: [],
         },
     ],
@@ -70,60 +70,69 @@ export function shieldedSealedBidDef(opts) {
  */
 export const vickreyAuctionDef = defineFiberApp({
     metadata: {
-        name: "VickreyAuction",
-        app: "markets",
-        type: "vickrey-auction",
-        version: "1.0.0",
-        description: "Sealed-bid second-price auction: public reveal-then-tally over shielded bids.",
-        crossReferences: { bidPool: "the ShieldedSealedBidAccount pool holding the sealed bids" },
+        name: 'VickreyAuction',
+        app: 'markets',
+        type: 'vickrey-auction',
+        version: '1.0.0',
+        description: 'Sealed-bid second-price auction: public reveal-then-tally over shielded bids.',
+        crossReferences: { bidPool: 'the ShieldedSealedBidAccount pool holding the sealed bids' },
     },
     createSchema: {
-        required: ["seller", "deadline"],
+        required: ['seller', 'deadline'],
         properties: {
-            seller: { type: "address", immutable: true },
-            deadline: { type: "timestamp", immutable: true },
+            seller: { type: 'address', immutable: true },
+            deadline: { type: 'timestamp', immutable: true },
         },
     },
     stateSchema: {
         properties: {
-            seller: { type: "address", immutable: true },
-            deadline: { type: "timestamp", immutable: true },
-            status: { type: "string", computed: true },
-            revealed: { type: "array", computed: true, description: "opened bids [{bidder, amount}]" },
-            winner: { type: "address", computed: true },
-            clearingPrice: { type: "number", computed: true, description: "second-highest bid (Vickrey)" },
+            seller: { type: 'address', immutable: true },
+            deadline: { type: 'timestamp', immutable: true },
+            status: { type: 'string', computed: true },
+            revealed: { type: 'array', computed: true, description: 'opened bids [{bidder, amount}]' },
+            winner: { type: 'address', computed: true },
+            clearingPrice: { type: 'number', computed: true, description: 'second-highest bid (Vickrey)' },
         },
     },
     eventSchemas: {
         reveal: {
-            description: "Open a sealed bid after the deadline",
-            required: ["bidder", "amount"],
-            properties: { bidder: { type: "address" }, amount: { type: "number", minimum: 1 } },
+            description: 'Open a sealed bid after the deadline',
+            required: ['bidder', 'amount'],
+            properties: { bidder: { type: 'address' }, amount: { type: 'number', minimum: 1 } },
         },
-        settle: { description: "Tally the revealed bids (winner + second price)" },
+        settle: { description: 'Tally the revealed bids (winner + second price)' },
     },
     states: {
-        OPEN: { id: "OPEN", isFinal: false, metadata: { label: "Open", description: "Bidding (sealed)", category: "initial" } },
-        REVEAL: { id: "REVEAL", isFinal: false, metadata: { label: "Reveal", description: "Opening bids", category: "active" } },
-        SETTLED: { id: "SETTLED", isFinal: true, metadata: { label: "Settled", description: "Winner + price set", category: "terminal" } },
+        OPEN: {
+            id: 'OPEN',
+            isFinal: false,
+            metadata: { label: 'Open', description: 'Bidding (sealed)', category: 'initial' },
+        },
+        REVEAL: {
+            id: 'REVEAL',
+            isFinal: false,
+            metadata: { label: 'Reveal', description: 'Opening bids', category: 'active' },
+        },
+        SETTLED: {
+            id: 'SETTLED',
+            isFinal: true,
+            metadata: { label: 'Settled', description: 'Winner + price set', category: 'terminal' },
+        },
     },
-    initialState: "OPEN",
+    initialState: 'OPEN',
     transitions: [
         {
-            from: "OPEN",
-            to: "REVEAL",
-            eventName: "reveal",
-            guard: { ">=": [{ var: "$timestamp" }, { var: "state.deadline" }] },
+            from: 'OPEN',
+            to: 'REVEAL',
+            eventName: 'reveal',
+            guard: { '>=': [{ var: '$timestamp' }, { var: 'state.deadline' }] },
             effect: {
                 merge: [
-                    { var: "state" },
+                    { var: 'state' },
                     {
-                        status: "REVEAL",
+                        status: 'REVEAL',
                         revealed: {
-                            cat: [
-                                { var: "state.revealed" },
-                                [{ bidder: { var: "event.bidder" }, amount: { var: "event.amount" } }],
-                            ],
+                            cat: [{ var: 'state.revealed' }, [{ bidder: { var: 'event.bidder' }, amount: { var: 'event.amount' } }]],
                         },
                     },
                 ],
@@ -131,19 +140,16 @@ export const vickreyAuctionDef = defineFiberApp({
             dependencies: [],
         },
         {
-            from: "REVEAL",
-            to: "REVEAL",
-            eventName: "reveal",
-            guard: { ">=": [{ var: "$timestamp" }, { var: "state.deadline" }] },
+            from: 'REVEAL',
+            to: 'REVEAL',
+            eventName: 'reveal',
+            guard: { '>=': [{ var: '$timestamp' }, { var: 'state.deadline' }] },
             effect: {
                 merge: [
-                    { var: "state" },
+                    { var: 'state' },
                     {
                         revealed: {
-                            cat: [
-                                { var: "state.revealed" },
-                                [{ bidder: { var: "event.bidder" }, amount: { var: "event.amount" } }],
-                            ],
+                            cat: [{ var: 'state.revealed' }, [{ bidder: { var: 'event.bidder' }, amount: { var: 'event.amount' } }]],
                         },
                     },
                 ],
@@ -152,44 +158,41 @@ export const vickreyAuctionDef = defineFiberApp({
         },
         {
             // Vickrey tally: fold the revealed bids tracking (max, second, winner).
-            from: "REVEAL",
-            to: "SETTLED",
-            eventName: "settle",
-            guard: { ">": [{ reduce: [{ var: "state.revealed" }, { "+": [{ var: "accumulator" }, 1] }, 0] }, 0] },
+            from: 'REVEAL',
+            to: 'SETTLED',
+            eventName: 'settle',
+            guard: { '>': [{ reduce: [{ var: 'state.revealed' }, { '+': [{ var: 'accumulator' }, 1] }, 0] }, 0] },
             effect: {
                 merge: [
-                    { var: "state" },
+                    { var: 'state' },
                     {
-                        status: "SETTLED",
-                        settledAt: { var: "$timestamp" },
+                        status: 'SETTLED',
+                        settledAt: { var: '$timestamp' },
                         winner: {
-                            var: [
-                                "tally.winner",
-                                null,
-                            ],
+                            var: ['tally.winner', null],
                         },
-                        clearingPrice: { var: ["tally.second", 0] },
+                        clearingPrice: { var: ['tally.second', 0] },
                         // compute the tally once and expose it for the two fields above
                         tally: {
                             reduce: [
-                                { var: "state.revealed" },
+                                { var: 'state.revealed' },
                                 {
                                     if: [
-                                        { ">": [{ var: "current.amount" }, { var: "accumulator.max" }] },
+                                        { '>': [{ var: 'current.amount' }, { var: 'accumulator.max' }] },
                                         {
-                                            max: { var: "current.amount" },
-                                            second: { var: "accumulator.max" },
-                                            winner: { var: "current.bidder" },
+                                            max: { var: 'current.amount' },
+                                            second: { var: 'accumulator.max' },
+                                            winner: { var: 'current.bidder' },
                                         },
                                         {
                                             if: [
-                                                { ">": [{ var: "current.amount" }, { var: "accumulator.second" }] },
+                                                { '>': [{ var: 'current.amount' }, { var: 'accumulator.second' }] },
                                                 {
-                                                    max: { var: "accumulator.max" },
-                                                    second: { var: "current.amount" },
-                                                    winner: { var: "accumulator.winner" },
+                                                    max: { var: 'accumulator.max' },
+                                                    second: { var: 'current.amount' },
+                                                    winner: { var: 'accumulator.winner' },
                                                 },
-                                                { var: "accumulator" },
+                                                { var: 'accumulator' },
                                             ],
                                         },
                                     ],

package/dist/esm/privacy/shield-app.js

@@ -24,7 +24,7 @@
  * O(state size) (RFC §8). Keep shielded note state small (a few KB); for large keyed state use
  * the auth-DB variant (RFC §3.1.1).
  */
-import { defineFiberApp, } from "../schema/fiber-app.js";
+import { defineFiberApp } from '../schema/fiber-app.js';
 /**
  * Field extractors over the abi-encoded `JlvmTransitionPublicValues` — four static `bytes32`
  * `[anchor | nullifier | newCommitment | exprHash]`, a fixed 128-byte (256 hex char) layout with
@@ -36,15 +36,15 @@ const pvField = (publicValues, hexOffset) => ({
 });
 /** Standard public state every shielded pool carries (the rest of the app state is private/off-chain). */
 export const SHIELDED_POOL_STATE = {
-    vkey: { type: "hash", immutable: true },
-    exprHash: { type: "hash", immutable: true },
-    rootWindow: { type: "integer", immutable: true },
-    currentRoot: { type: "hash", computed: true },
-    knownRoots: { type: "array", computed: true, description: "rolling window of valid anchors (hex)" },
-    nullifiers: { type: "array", computed: true, description: "spent set (hex); monotonic — see RFC §5.3" },
-    commitments: { type: "array", computed: true, description: "append-only log of output commitments (hex)" },
-    leafCount: { type: "integer", computed: true, default: 0 },
-    transitions: { type: "integer", computed: true, default: 0 },
+    vkey: { type: 'hash', immutable: true },
+    exprHash: { type: 'hash', immutable: true },
+    rootWindow: { type: 'integer', immutable: true },
+    currentRoot: { type: 'hash', computed: true },
+    knownRoots: { type: 'array', computed: true, description: 'rolling window of valid anchors (hex)' },
+    nullifiers: { type: 'array', computed: true, description: 'spent set (hex); monotonic — see RFC §5.3' },
+    commitments: { type: 'array', computed: true, description: 'append-only log of output commitments (hex)' },
+    leafCount: { type: 'integer', computed: true, default: 0 },
+    transitions: { type: 'integer', computed: true, default: 0 },
 };
 /**
  * Build the shielded-pool variant of `base`.
@@ -53,7 +53,7 @@ export const SHIELDED_POOL_STATE = {
  * @param opts  the circuit vkey + the pinned `exprHash` + the anchor window.
  */
 export function shieldApp(base, opts) {
-    const publicValues = { var: "event.publicValues" };
+    const publicValues = { var: 'event.publicValues' };
     const anchor = pvField(publicValues, 2);
     const nullifier = pvField(publicValues, 66);
     const newCommitment = pvField(publicValues, 130);
@@ -62,13 +62,13 @@ export function shieldApp(base, opts) {
     const guard = {
         and: [
             // 1. the proof verifies against the pool's pinned vkey over EXACTLY these public bytes
-            { groth16_verify: [{ var: "state.vkey" }, publicValues, { var: "event.proof" }] },
+            { groth16_verify: [{ var: 'state.vkey' }, publicValues, { var: 'event.proof' }] },
             // 2. it ran the app logic this pool pins (binds which effect produced the transition)
-            { "===": [exprHash, { var: "state.exprHash" }] },
+            { '===': [exprHash, { var: 'state.exprHash' }] },
             // 3. the spent note was proven under an anchor we still honor
-            { in: [anchor, { var: "state.knownRoots" }] },
+            { in: [anchor, { var: 'state.knownRoots' }] },
             // 4. inter-transfer double-spend guard: the nullifier is not already spent
-            { none: [{ var: "state.nullifiers" }, { "===": [{ var: "" }, nullifier] }] },
+            { none: [{ var: 'state.nullifiers' }, { '===': [{ var: '' }, nullifier] }] },
         ],
     };
     // EFFECT (combine): spend the nullifier, record the new commitment, advance counters.
@@ -76,52 +76,52 @@ export function shieldApp(base, opts) {
     // per RFC §6.2 / §10; the chain records the commitment + nullifier here.
     const effect = {
         merge: [
-            { var: "state" },
+            { var: 'state' },
             {
-                nullifiers: { cat: [{ var: "state.nullifiers" }, [nullifier]] },
-                commitments: { cat: [{ var: "state.commitments" }, [newCommitment]] },
-                leafCount: { "+": [{ var: "state.leafCount" }, 1] },
-                transitions: { "+": [{ var: "state.transitions" }, 1] },
-                lastTransitionAt: { var: "$ordinal" },
+                nullifiers: { cat: [{ var: 'state.nullifiers' }, [nullifier]] },
+                commitments: { cat: [{ var: 'state.commitments' }, [newCommitment]] },
+                leafCount: { '+': [{ var: 'state.leafCount' }, 1] },
+                transitions: { '+': [{ var: 'state.transitions' }, 1] },
+                lastTransitionAt: { var: '$ordinal' },
             },
         ],
     };
     return defineFiberApp({
         metadata: {
             name: `Shielded${base.metadata.name}`,
-            app: "privacy",
+            app: 'privacy',
             type: `shielded-${base.metadata.type}`,
             version: base.metadata.version,
             description: `Shielded (zk-jlvm-shielded) variant of ${base.metadata.name}: private state transitions ` +
                 `verified by a Groth16 proof; the nullifier set + anchors are public pool state.`,
         },
         createSchema: {
-            required: ["vkey", "exprHash"],
+            required: ['vkey', 'exprHash'],
             properties: {
-                vkey: { type: "hash", immutable: true, default: opts.vkey },
-                exprHash: { type: "hash", immutable: true, default: opts.exprHash },
-                rootWindow: { type: "integer", immutable: true, default: opts.rootWindow ?? 64 },
+                vkey: { type: 'hash', immutable: true, default: opts.vkey },
+                exprHash: { type: 'hash', immutable: true, default: opts.exprHash },
+                rootWindow: { type: 'integer', immutable: true, default: opts.rootWindow ?? 64 },
             },
         },
         stateSchema: { properties: { ...SHIELDED_POOL_STATE } },
         eventSchemas: {
             transition: {
                 description: `A private state transition of ${base.metadata.name}, attested by a zk-jlvm-shielded Groth16 proof.`,
-                required: ["proof", "publicValues"],
+                required: ['proof', 'publicValues'],
                 properties: {
-                    proof: { type: "string", description: "Groth16 proof bytes (0x hex)" },
-                    publicValues: { type: "string", description: "abi-encoded JlvmTransitionPublicValues (4×bytes32, 0x hex)" },
+                    proof: { type: 'string', description: 'Groth16 proof bytes (0x hex)' },
+                    publicValues: { type: 'string', description: 'abi-encoded JlvmTransitionPublicValues (4×bytes32, 0x hex)' },
                 },
             },
         },
         states: {
             ACTIVE: {
-                id: "ACTIVE",
+                id: 'ACTIVE',
                 isFinal: false,
-                metadata: { label: "Active", description: "Pool accepts shielded transitions", category: "active" },
+                metadata: { label: 'Active', description: 'Pool accepts shielded transitions', category: 'active' },
             },
         },
-        initialState: "ACTIVE",
-        transitions: [{ from: "ACTIVE", to: "ACTIVE", eventName: "transition", guard, effect, dependencies: [] }],
+        initialState: 'ACTIVE',
+        transitions: [{ from: 'ACTIVE', to: 'ACTIVE', eventName: 'transition', guard, effect, dependencies: [] }],
     });
 }

package/dist/esm/schema/effects.js

@@ -33,3 +33,140 @@ export const addDependency = (fiberId) => ({
 export const setDependencyActive = (fiberId, active) => ({
     _setDependencyActive: [{ fiberId, active }],
 });
+/**
+ * `_transferAsset`: move one or more WHOLE asset instances the emitting fiber holds, each to a single
+ * recipient. The directive rides INSIDE a `merge` effect map (the engine extracts `_`-prefixed keys
+ * before merging into state); a transition-level `emits` block is silently stripped by
+ * `toProtoDefinition`, which would strand the asset.
+ *
+ * Each directive is `{ assetId, recipient }` ONLY — there is NO `amount` field. The combiner reassigns
+ * `holder := recipient` on the WHOLE asset record (`AssetCombiner.applyFiberTransfer`); value is moved
+ * one whole instance at a time, never split. `recipient` must resolve to the canonical `AssetHolder`
+ * OBJECT form — `{"Fiber":{"fiberId":..}}` / `{"Wallet":{"address":..}}` — built with {@link toFiber} /
+ * {@link toWallet}; the chain raises a graceful `CombineRejected` on a bare string or malformed object
+ * (`EffectExtractor.parseAssetTransfer`). `assetId` is a UUID; the holder id may be a literal or an
+ * expression (e.g. `{ var: "event.agent" }`).
+ *
+ * Combiner-side holder defense (R1) independently re-validates every directive: the asset must resolve,
+ * be held by `Fiber(self)`, be `behavior.transferable`, and (Fiber recipient) the recipient fiber must be
+ * live — else the whole transition is `CombineRejected`. There is a hard cap of 32 asset mutations per
+ * transition (all-or-nothing); keep emitting fibers at ≤1 transfer per transition for claim/withdraw/slash.
+ *
+ * @example
+ * effect: { merge: [ { var: "state" }, {
+ *   status: "SETTLED",
+ *   ...transferAsset([{ assetId: { var: "event.rewardAssetId" }, recipient: toWallet({ var: "event.agent" }) }]),
+ * } ] }
+ */
+export const transferAsset = (transfers) => ({ _transferAsset: transfers });
+/**
+ * Build a `_transferAsset` `recipient` as the canonical `AssetHolder` OBJECT form. The chain requires the
+ * object form ONLY — `{"Fiber":{"fiberId":..}}` / `{"Wallet":{"address":..}}` — and raises a graceful
+ * `CombineRejected` on a bare string or a malformed object (`EffectExtractor.parseAssetTransfer`); the
+ * legacy bare-string UUID/DAG-address disambiguation has been removed. These mirror the typed
+ * {@link fiberHolder} / {@link walletHolder} `AssetHolder` builders (used for `MintAsset.holder` /
+ * `ApplyMorphism.recipient`) but accept a `JsonLogicValue`, so the id can be a runtime expression:
+ *
+ * ```ts
+ * transferAsset([{ assetId, recipient: toFiber({ var: "event.retailerId" }) }]);  // → {"Fiber":{"fiberId":..}}
+ * transferAsset([{ assetId, recipient: toWallet({ var: "event.agent" }) }]);       // → {"Wallet":{"address":..}}
+ * ```
+ */
+export const toFiber = (fiberId) => ({
+    Fiber: { fiberId },
+});
+/** See {@link toFiber}: a `transferAsset` recipient held by a wallet — `{"Wallet":{"address":..}}`. */
+export const toWallet = (address) => ({
+    Wallet: { address },
+});
+/**
+ * `_triggers` (F4): fire one or more CROSS-FIBER events. Each entry is projected to
+ * `{ targetMachineId, eventName, payload }` — the exact shape the chain's `EffectExtractor` reads
+ * (`ReservedKeys.scala`, `EffectExtractor.scala`). `target` is the recipient fiber id (a literal UUID
+ * or an expression, e.g. `{ var: "event.retailerId" }`); `event` is the event NAME to enqueue on it;
+ * `payload` is the event body — omit it and the builder emits `{}` (never `null`).
+ *
+ * Authoring this as a builder makes a typo'd `_trigger` / `triggres` a TypeScript error rather than a
+ * silently-merged state field (the F4 foot-gun). Place the fragment INSIDE the effect's state-update
+ * map so it rides in the evaluated result the extractor reads.
+ *
+ * @example
+ * effect: { merge: [ { var: "state" }, {
+ *   status: "debt_current",
+ *   ...triggers([{ target: { var: "event.retailerId" }, event: "process_sale",
+ *     payload: { buyerId: { var: "machineId" }, quantity: { var: "event.quantity" } } }]),
+ * } ] }
+ */
+export const triggers = (ts) => ({
+    _triggers: ts.map((t) => ({
+        targetMachineId: t.target,
+        eventName: t.event,
+        payload: t.payload ?? {},
+    })),
+});
+/**
+ * `_spawn`: create one or more CHILD fibers, each from a literal machine `definition`. Each entry is
+ * `{ childId, definition, initialData, owners }` (`ReservedKeys.scala`, `EffectExtractor.scala`).
+ *
+ * The chain extracts `_spawn` from the effect EXPRESSION, not the evaluated result, so `definition`
+ * MUST be a literal {@link ProtoStateMachineDefinition} (e.g. a nested `machine().wireDefinition()` /
+ * `toProtoDefinition(child)` output) — NOT an expression the engine would evaluate at runtime.
+ *
+ * F8 gotcha — `owners` is load-bearing. A spawned child's transitions are gated by
+ * `owners ∪ authorizedSigners` (`riverdale-economy/README.md`), so EVERY party that will later drive
+ * the child (e.g. every bidder on a spawned auction) MUST be listed in `owners`, or their events are
+ * rejected. `owners` may be a literal id array or an expression (e.g. `{ var: "event.auctionOwners" }`);
+ * `childId` / `initialData` likewise accept literals or expressions.
+ */
+export const spawn = (ds) => ({ _spawn: ds });
+/**
+ * `_emit`: emit one or more domain events to the fiber's outbox. Each entry is
+ * `{ name, data, destination? }` (`ReservedKeys.scala`, `EffectExtractor.scala`). `name` is the event
+ * name, `data` the body (a literal or an expression), and `destination` an OPTIONAL routing target —
+ * omit it when absent (callers never pass `null`, so it is simply absent on the wire).
+ */
+export const emit = (es) => ({
+    _emit: es,
+});
+/**
+ * `_scriptCall`: invoke a SCRIPT fiber's `method` from an effect. Unlike the array-valued directives,
+ * `_scriptCall` is a SINGLE object `{ fiberId, method, args }` (chain `ReservedKeys.scala` `SCRIPT_CALL` /
+ * `EffectExtractor.extractScriptCall`). `fiberId` is the target script's UUID (a literal or an expression,
+ * e.g. `{ var: "state.resolverId" }`); `method` is the script method NAME; `args` is the argument body —
+ * a JSON-Logic value the chain EVALUATES against the transition context before dispatch.
+ *
+ * The chain's extractor requires ALL THREE fields — if `args` is absent the whole call is silently DROPPED
+ * (fail-silent, like the other extractors). So the builder ALWAYS emits `args`, defaulting an omitted one
+ * to `{}` (no-args), mirroring how {@link triggers} defaults an absent `payload`. Authoring this as a
+ * builder makes a typo'd `_scriptcall` / wrong field a TypeScript error rather than a silently-merged
+ * state field. Place the fragment INSIDE the effect's state-update map so it rides in the evaluated result.
+ *
+ * @example
+ * effect: { merge: [ { var: "state" }, {
+ *   status: "resolving",
+ *   ...scriptCall({ fiberId: { var: "state.resolverId" }, method: "resolve",
+ *     args: { marketId: { var: "machineId" } } }),
+ * } ] }
+ */
+export const scriptCall = (call) => ({
+    _scriptCall: {
+        fiberId: call.fiberId,
+        method: call.method,
+        args: call.args ?? {},
+    },
+});
+/**
+ * The complete set of `_`-prefixed RESERVED effect keys the chain's `EffectExtractor` consumes and
+ * `StateMerger` strips from state (`ReservedKeys.scala:12-49`). Exported so a validator (Proposal 01)
+ * can reject an unknown `_`-prefixed key (a typo'd directive) instead of letting it silently leak into
+ * persisted state.
+ */
+export const RESERVED_EFFECT_KEYS = [
+    '_triggers',
+    '_spawn',
+    '_emit',
+    '_transferAsset',
+    '_scriptCall',
+    '_addDependency',
+    '_setDependencyActive',
+];