@ottochain/sdk 2.3.0 → 2.5.0

package/dist/cjs/schema/effects.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Builders for the fiber-engine reserved EFFECT directives — the `_`-prefixed keys the chain extracts
+ * from an evaluated effect result and applies as side effects (then strips from the merged state).
+ *
+ * Place the returned fragment INSIDE the state-update map of a `merge` effect, so the directive rides in
+ * the evaluated result map (EffectExtractor reads it; StateMerger drops `_`-prefixed keys from state):
+ *
+ * ```ts
+ * effect: {
+ *   merge: [
+ *     { var: "state" },
+ *     { boundAt: { var: "$ordinal" }, ...addDependency({ var: "event.registryId" }) },
+ *   ],
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESERVED_EFFECT_KEYS = exports.emit = exports.spawn = exports.triggers = exports.toWallet = exports.toFiber = exports.transferAsset = exports.setDependencyActive = exports.addDependency = void 0;
+/**
+ * `_addDependency` (#24): add — or re-activate — a runtime DYNAMIC dependency on `fiberId`, so that
+ * fiber's state appears in `machines.<fiberId>` for SUBSEQUENT transitions of this fiber. `fiberId` may
+ * be a literal UUID string or an expression (e.g. `{ var: "event.registryId" }`, `{ var: "state.registryId" }`).
+ * The ledger is append-only, idempotent (one entry per fiber), and engine-bounded (active + ledger caps).
+ * Because the `machines` context is built BEFORE the effect runs, the bound dependency is readable only
+ * from the NEXT transition onward (two-phase: bind, then read).
+ */
+const addDependency = (fiberId) => ({
+    _addDependency: [{ fiberId }],
+});
+exports.addDependency = addDependency;
+/**
+ * `_setDependencyActive` (#24): toggle a dynamic dependency's `active` flag. The entry is NEVER removed —
+ * deactivation simply drops it from the `machines` context (and it can be cheaply re-activated). `fiberId`
+ * may be a literal or an expression.
+ */
+const setDependencyActive = (fiberId, active) => ({
+    _setDependencyActive: [{ fiberId, active }],
+});
+exports.setDependencyActive = setDependencyActive;
+/**
+ * `_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" }) }]),
+ * } ] }
+ */
+const transferAsset = (transfers) => ({ _transferAsset: transfers });
+exports.transferAsset = transferAsset;
+/**
+ * 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":..}}
+ * ```
+ */
+const toFiber = (fiberId) => ({
+    Fiber: { fiberId },
+});
+exports.toFiber = toFiber;
+/** See {@link toFiber}: a `transferAsset` recipient held by a wallet — `{"Wallet":{"address":..}}`. */
+const toWallet = (address) => ({
+    Wallet: { address },
+});
+exports.toWallet = toWallet;
+/**
+ * `_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" } } }]),
+ * } ] }
+ */
+const triggers = (ts) => ({
+    _triggers: ts.map((t) => ({
+        targetMachineId: t.target,
+        eventName: t.event,
+        payload: t.payload ?? {},
+    })),
+});
+exports.triggers = triggers;
+/**
+ * `_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.
+ */
+const spawn = (ds) => ({ _spawn: ds });
+exports.spawn = spawn;
+/**
+ * `_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).
+ */
+const emit = (es) => ({
+    _emit: es,
+});
+exports.emit = emit;
+/**
+ * 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.
+ */
+exports.RESERVED_EFFECT_KEYS = [
+    '_triggers',
+    '_spawn',
+    '_emit',
+    '_transferAsset',
+    '_scriptCall',
+    '_addDependency',
+    '_setDependencyActive',
+];

package/dist/cjs/schema/fiber-app.js

@@ -6,7 +6,132 @@
  * no JSON, no code generation. Import types directly.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toProtoDefinition = exports.toJSON = exports.isFinalState = exports.getEventsFrom = exports.getTransitionsFrom = exports.defineFiberApp = void 0;
+exports.IMMUTABLE_POLICY = void 0;
+exports.unconstrained = unconstrained;
+exports.immutable = immutable;
+exports.constrained = constrained;
+exports.projectFiberPolicy = projectFiberPolicy;
+exports.defineFiberApp = defineFiberApp;
+exports.getTransitionsFrom = getTransitionsFrom;
+exports.getEventsFrom = getEventsFrom;
+exports.isFinalState = isFinalState;
+exports.toJSON = toJSON;
+exports.toProtoDefinition = toProtoDefinition;
+/**
+ * The wire (and authoring) tag for the `Immutable` policy VARIANT: the bare JSON string
+ * `"Immutable"`. EXACT casing, capital-I — this is the POLICY-LEVEL variant name and is
+ * DISTINCT from the `upgradePolicy` dial VALUE `"immutable"` (lowercase). The chain emits
+ * exactly this capital-I string for `Immutable`, so the SDK must too, byte-for-byte.
+ */
+exports.IMMUTABLE_POLICY = 'Immutable';
+/** The names of the 15 policy dials, in declaration order. Used by the projector. */
+const FIBER_POLICY_DIALS = [
+    'selfReproducing',
+    'allowedEffects',
+    'spawnOwnerPolicy',
+    'maxGenerations',
+    'maxSpawnFanout',
+    'acceptedCallers',
+    'sealedStates',
+    'transitionPolicy',
+    'transferPolicy',
+    'dependencyPolicy',
+    'upgradePolicy',
+    'version',
+    'compatibleWith',
+    'interfaces',
+    'migrationAuthority',
+];
+/**
+ * The canonical UNCONSTRAINED policy: omission. Provided as a named export for
+ * readability at call sites — `policy: unconstrained()` documents intent, and projects
+ * to NO `policy` key (identical to leaving `policy` off entirely).
+ */
+function unconstrained() {
+    return undefined;
+}
+/**
+ * The canonical IMMUTABLE policy: the definition is permanently locked. Projects to the
+ * bare JSON string `"Immutable"` ({@link IMMUTABLE_POLICY}), the chain's `Immutable`
+ * variant tag. Semantically equivalent to `constrained({ upgradePolicy: 'immutable' })`
+ * with no other dial set — which `constrained()`/`projectFiberPolicy()` collapse to the
+ * same string for wire parity (see {@link constrained}).
+ *
+ * @example
+ * ```ts
+ * const def = defineFiberApp({ ...spec, policy: immutable() });
+ * ```
+ */
+function immutable() {
+    return exports.IMMUTABLE_POLICY;
+}
+/**
+ * Build a CONSTRAINED `FiberPolicy` from any subset of the 15 dials.
+ *
+ * Pass only the dials you want to set. Dials left `undefined`/`null` are dropped so the
+ * result is a clean, minimal object that serializes identically to the chain's
+ * `dropNulls`-stripped `Constrained`. If NO dial is effectively set, this returns
+ * `undefined` (an empty constraint == `Unconstrained`), which projects to no `policy`
+ * key — preserving wire parity.
+ *
+ * CANONICAL COLLAPSE: `constrained({ upgradePolicy: 'immutable' })` with NO other dial set
+ * collapses to the bare string `"Immutable"` ({@link IMMUTABLE_POLICY}), because the chain
+ * collapses that exact `Constrained` into the `Immutable` variant. NOTE the casing: the
+ * collapse triggers on the chain's LOWERCASE upgradePolicy dial value `"immutable"`, and
+ * the result is the capital-I policy-variant tag `"Immutable"`. Signing the dials object
+ * `{ "upgradePolicy": "immutable" }` instead would diverge the canonical (the chain
+ * re-encodes it as `"Immutable"`) and break the create signature. Adding ANY other dial
+ * keeps it a dials object.
+ *
+ * @example
+ * ```ts
+ * const policy = constrained({
+ *   selfReproducing: false,
+ *   maxGenerations: 3,
+ *   allowedEffects: ['EMIT', 'TRANSFER'],
+ *   sealedStates: ['ARCHIVED'],
+ * });
+ * ```
+ */
+function constrained(dials) {
+    const out = {};
+    for (const k of FIBER_POLICY_DIALS) {
+        const v = dials[k];
+        if (v === undefined || v === null)
+            continue;
+        out[k] = v;
+    }
+    const keys = Object.keys(out);
+    if (keys.length === 0)
+        return undefined;
+    // Canonical collapse: a lone LOWERCASE `upgradePolicy: 'immutable'` (the chain's dial
+    // value) IS the `Immutable` variant — emit the capital-I `"Immutable"` tag, not the dials.
+    if (keys.length === 1 && out.upgradePolicy === 'immutable')
+        return exports.IMMUTABLE_POLICY;
+    return out;
+}
+/**
+ * Project an authoring `policy` value onto the wire form. Returns one of:
+ *   - `undefined` when the policy is (effectively) `Unconstrained` — i.e. omit the `policy`
+ *     key entirely;
+ *   - the bare string `"Immutable"` ({@link IMMUTABLE_POLICY}) for the `Immutable` variant
+ *     (also the collapse of a lone LOWERCASE `upgradePolicy: 'immutable'`); or
+ *   - the minimal `Constrained` dials object otherwise.
+ *
+ * Centralizes the omit-on-unconstrained AND the Immutable-collapse parity rules so every
+ * projection path (`toProtoDefinition`, the genesis manifest) stays consistent.
+ */
+function projectFiberPolicy(policy) {
+    if (policy === undefined || policy === null)
+        return undefined;
+    // The Immutable variant is already its canonical bare-string wire form.
+    if (policy === exports.IMMUTABLE_POLICY)
+        return exports.IMMUTABLE_POLICY;
+    // Re-run the dial filter so a hand-built object with explicit-undefined/empty dials
+    // collapses to Unconstrained, and a lone `upgradePolicy: 'immutable'` collapses to
+    // `"Immutable"`, exactly like `constrained()` does.
+    return constrained(policy);
+}
 // =============================================================================
 // Helper: defineFiberApp
 // =============================================================================
@@ -32,27 +157,22 @@ function defineFiberApp(definition) {
     // Runtime validation could go here
     return definition;
 }
-exports.defineFiberApp = defineFiberApp;
 /** Get valid transitions from a given state */
 function getTransitionsFrom(def, state) {
-    return def.transitions.filter(t => t.from === state);
+    return def.transitions.filter((t) => t.from === state);
 }
-exports.getTransitionsFrom = getTransitionsFrom;
 /** Get valid event names from a given state */
 function getEventsFrom(def, state) {
-    return getTransitionsFrom(def, state).map(t => t.eventName);
+    return getTransitionsFrom(def, state).map((t) => t.eventName);
 }
-exports.getEventsFrom = getEventsFrom;
 /** Check if a state is final */
 function isFinalState(def, state) {
     return def.states[state]?.isFinal ?? false;
 }
-exports.isFinalState = isFinalState;
 /** Convert definition to plain JSON (for serialization) */
 function toJSON(def) {
     return JSON.parse(JSON.stringify(def));
 }
-exports.toJSON = toJSON;
 /**
  * Extract proto-compatible StateMachineDefinition from a FiberAppDefinition.
  * Use this when submitting to the metagraph.
@@ -70,14 +190,19 @@ function toProtoDefinition(def) {
     const protoDef = {
         states: {},
         initialState: def.initialState,
-        transitions: def.transitions.map(t => ({
+        transitions: def.transitions.map((t) => ({
             from: t.from,
             to: t.to,
             eventName: t.eventName,
             guard: t.guard, // Required - Scala has no default
             effect: t.effect, // Required - Scala has no default
-            // dependencies has default Set.empty in Scala, so omit if empty
-            ...(t.dependencies?.length && { dependencies: [...t.dependencies] }),
+            // Chain `Transition.dependencies: Set[UUID]` is REQUIRED (no Scala default), and each
+            // element must be a fiber UUID string. A `DependencySpec` object is a build-time-only
+            // authoring affordance with no wire representation (concrete dependency UUIDs are per
+            // instance, not part of the definition template), so drop non-string entries. Always
+            // emit the array — omitting a no-default field diverges the canonical and the chain
+            // rejects the whole update (InvalidSignature / decode failure).
+            dependencies: (t.dependencies ?? []).filter((d) => typeof d === 'string'),
         })),
     };
     // Copy states (only id and isFinal)
@@ -87,10 +212,20 @@ function toProtoDefinition(def) {
             isFinal: state.isFinal,
         };
     }
-    // Pass metadata through unchanged - it's an optional unstructured object
-    if (def.metadata) {
-        protoDef.metadata = def.metadata;
+    // NOTE: `def.metadata` is the SDK's FiberAppMetadata (name/app/type/version — app-routing
+    // packaging info), NOT chain metadata. Projecting it onto the wire would make the on-chain
+    // canonical + the registry `logicHash` depend on packaging fields (changing `description` would
+    // change the signed digest of an otherwise-identical machine), so it is deliberately NOT emitted
+    // (the chain's `StateMachineDefinition.metadata` stays absent → `None`). A caller that genuinely
+    // needs on-chain metadata sets `ProtoStateMachineDefinition.metadata` explicitly after conversion.
+    // Fiber constitution. OMIT the `policy` key entirely for `Unconstrained` (the chain
+    // emits nothing for it); emit the bare string `"Immutable"` for `Immutable`; emit a bare
+    // object of only the SET dials for `Constrained`. `projectFiberPolicy` returns `undefined`
+    // for an (effectively) unconstrained policy, so we assign only when it is a real policy —
+    // keeping the wire byte-for-byte identical to the chain's encoding.
+    const policy = projectFiberPolicy(def.policy);
+    if (policy !== undefined) {
+        protoDef.policy = policy;
     }
     return protoDef;
 }
-exports.toProtoDefinition = toProtoDefinition;