@ottochain/sdk 2.4.0 → 2.5.0

package/dist/cjs/templates/machine.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Versioned-machine skeleton + `transition()` / `effect()` composition (handoff §1.2).
+ *
+ * Two moves:
+ *   1. `transition()` / `effect()` build the wire `Transition` + its flat effect map from typed
+ *      fragments instead of a hand-rolled JSON blob.
+ *   2. `machine()` is a versioned-package SKELETON that OWNS exactly ONE canonical wire definition
+ *      (`toProtoDefinition(app)`, computed once) and hands the SAME object to BOTH `publishVersion()`
+ *      and `create()`. That is the verified-binding invariant (F9): because publish and create cannot
+ *      drift, the chain's `definition.computeDigest` equals the registered `logicHash` and the bind
+ *      admits the fiber. The skeleton REUSES `toProtoDefinition` (the one canonicalization path) — it
+ *      never re-derives the wire shape.
+ *
+ * Guardrail (CLAUDE.md #1): every builder here is a pure function emitting the exact wire shape the
+ * chain re-derives. Absent optionals (`metadata`/`participants`/`parentFiberId`/`migration`) are
+ * OMITTED, never `null`; required-no-default fields (`strict` on publish, `dependencies: []` per
+ * transition) are ALWAYS present.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transition = transition;
+exports.effect = effect;
+exports.machine = machine;
+const fiber_app_js_1 = require("../schema/fiber-app.js");
+/**
+ * Build a wire {@link Transition} from a typed spec.
+ *
+ *   - `on` → `eventName` (the wire key);
+ *   - `guard` defaults to `{ "==": [1, 1] }`;
+ *   - `dependencies` defaults to `[]` and is ALWAYS present;
+ *   - `effect` is passed through (build it with {@link effect}).
+ *
+ * @example
+ * ```ts
+ * transition({
+ *   from: 'debt_current', to: 'debt_current', on: 'buy',
+ *   effect: effect(
+ *     { status: 'debt_current', purchaseCount: { '+': [{ var: 'state.purchaseCount' }, 1] } },
+ *     triggers([...]), transferAsset([...]),
+ *   ),
+ * });
+ * ```
+ */
+function transition(t) {
+    return {
+        from: t.from,
+        to: t.to,
+        eventName: t.on,
+        guard: t.guard ?? { '==': [1, 1] },
+        effect: t.effect,
+        dependencies: t.dependencies ?? [],
+    };
+}
+// =============================================================================
+// effect()
+// =============================================================================
+/**
+ * Compose an effect into ONE FLAT map: the state-update fields PLUS any `_`-directive fragments,
+ * all in a single object (`Object.assign({}, stateUpdate, ...directives)`).
+ *
+ * Riverdale effects are flat maps that mix `_`-reserved directives (`_triggers`, `_transferAsset`,
+ * `_spawn`, …) with plain state-update fields — they are NOT `merge`-wrapped. Each directive fragment
+ * is a `Record` (e.g. the output of `transferAsset(...)` / `triggers(...)`), spread in here. Later
+ * fragments override earlier keys (`Object.assign` semantics).
+ *
+ * @example
+ * ```ts
+ * effect(
+ *   { status: 'debt_current', purchaseCount: { '+': [{ var: 'state.purchaseCount' }, 1] } },
+ *   { _triggers: [...] },
+ *   transferAsset([{ assetId: { var: 'event.payAssetId' }, recipient: toFiber({ var: 'event.retailerId' }) }]),
+ * );
+ * // => { status, purchaseCount, _triggers, _transferAsset }
+ * ```
+ */
+function effect(stateUpdate, ...directives) {
+    return Object.assign({}, stateUpdate, ...directives);
+}
+/** A pinned-Exact `SchemaRef` for `name@version`. Wire: `{ name, version: { Exact: { version } } }`. */
+function exactRef(name, version) {
+    return { name, version: { Exact: { version } } };
+}
+/**
+ * Build a versioned-machine skeleton that binds publish + create to ONE canonical definition.
+ *
+ * The definition is projected ONCE here (`toProtoDefinition(spec.app)`) and the SAME reference is handed
+ * to `wireDefinition()`, `publishVersion().definition`, `create().definition`, and
+ * `upgradeFrom().newDefinition` — so they cannot drift and the chain's verified binding admits the fiber
+ * (F9). REUSES `toProtoDefinition` (the single canonicalization path); never re-derives the wire shape.
+ */
+function machine(spec) {
+    // Project the canonical wire definition ONCE; every consumer reuses this exact reference.
+    const wireDef = (0, fiber_app_js_1.toProtoDefinition)(spec.app);
+    return {
+        wireDefinition() {
+            return wireDef;
+        },
+        publishVersion(o) {
+            return {
+                name: spec.name,
+                version: spec.version,
+                // REQUIRED-no-default on the wire; '' is valid empty base64 when no descriptor set is bound.
+                schemaB64: o?.schemaB64 ?? '',
+                machineShape: spec.schemaShape,
+                definition: wireDef, // SAME reference as wireDefinition()/create()
+                strict: o?.strict ?? false, // REQUIRED — never omitted
+                ...(o?.metadata ? { metadata: o.metadata } : {}), // OMIT when absent
+            };
+        },
+        create(o) {
+            return {
+                fiberId: o.fiberId,
+                definition: wireDef, // SAME reference as wireDefinition()/publishVersion()
+                initialData: o.initialData,
+                schemaRef: exactRef(spec.name, spec.version), // verified binding: name@version
+                ...(o.participants ? { participants: o.participants } : {}), // OMIT when absent
+                ...(o.parentFiberId ? { parentFiberId: o.parentFiberId } : {}), // OMIT when absent
+            };
+        },
+        upgradeFrom(o) {
+            return {
+                fiberId: o.fiberId,
+                targetRef: exactRef(spec.name, spec.version),
+                newDefinition: wireDef, // SAME reference — re-pin hashes to the same logicHash
+                targetSequenceNumber: o.targetSequenceNumber,
+                ...(o.migration !== undefined ? { migration: o.migration } : {}), // OMIT (Option) when absent
+            };
+        },
+    };
+}

package/dist/cjs/templates/migration.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Migration builders — the `UpgradeFiber.migration` JSON-Logic transform applied on a version upgrade.
+ *
+ * THE FOOT-GUN (F9): a migration's evaluation root is the BARE prior state, not `state.x`.
+ * The chain evaluates the migration expression against `sm.stateData` directly
+ * (`MeteredEvaluator.eval(expr, sm.stateData, Migration)`, FiberEngine.scala:300), so:
+ *   - `{ var: '' }`            => the WHOLE prior state object
+ *   - `{ var: 'loyaltyPoints' }` => the top-level `loyaltyPoints` field
+ * This is UNLIKE an effect, where the root is the transition context and you read `{ var: 'state.x' }`.
+ * Writing `state.loyaltyPoints` in a migration silently reads `undefined`. These helpers hide that
+ * asymmetry by pinning the bare-state root for you.
+ *
+ * `migration` is `Option` on `UpgradeFiber` — when there is no transform, OMIT the key (never send `null`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migration = exports.seedFields = void 0;
+/**
+ * Seed / overwrite top-level state fields on a version upgrade.
+ * Emits `{ merge: [{ var: '' }, fields] }` — merges `fields` onto the bare prior state, so existing
+ * fields are preserved and the named fields are added or overwritten.
+ *
+ * The `{ var: '' }` root is the BARE prior state (NOT `state.x` like an effect) — that asymmetry is
+ * exactly the F9 foot-gun this helper hides.
+ *
+ * @example seedFields({ loyaltyPoints: 0 }) // => { merge: [{ var: '' }, { loyaltyPoints: 0 }] }
+ */
+const seedFields = (fields) => ({
+    merge: [{ var: '' }, fields],
+});
+exports.seedFields = seedFields;
+/**
+ * General migration transform with the bare-state root made explicit. `build` receives `{ var: '' }`
+ * (the whole prior state) and returns the migration JSON-Logic.
+ *
+ * @example migration((s) => ({ merge: [s, { x: 1 }] })) // => { merge: [{ var: '' }, { x: 1 }] }
+ */
+const migration = (build) => build({ var: '' });
+exports.migration = migration;

package/dist/cjs/templates/state-shape.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * State-shape-with-defaults — the SDK half of Proposal 01's "declared state shape" (removes F5).
+ *
+ * A declared shape carries a `default` (and optional `type`) per field. It seeds `initialData` so every
+ * accumulator starts at a concrete value — a counter read via `{ '+': [{ var: 'state.x' }, ...] }` never
+ * resolves `null` because `x` was never written. It also yields the set of declared field names for
+ * Proposal 01's var-path checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seedState = seedState;
+exports.declaredFields = declaredFields;
+/**
+ * Build `initialData` by overlaying `overrides` onto each field's declared `default`.
+ * Every declared field gets a concrete value, so no field reads `null` at runtime. An override for a
+ * field replaces that field's default; overrides for undeclared fields are ignored (only declared fields
+ * are emitted). Determinism: pure function of its inputs, stable key order (declared order).
+ *
+ * @example seedState({ fields: { purchaseCount: { default: 0 }, status: { default: 'ACTIVE' } } })
+ *          // => { purchaseCount: 0, status: 'ACTIVE' }
+ */
+function seedState(shape, overrides) {
+    const seeded = {};
+    for (const [name, field] of Object.entries(shape.fields)) {
+        seeded[name] =
+            overrides !== undefined && Object.prototype.hasOwnProperty.call(overrides, name)
+                ? overrides[name]
+                : field.default;
+    }
+    return seeded;
+}
+/**
+ * The set of declared state-field names — the fields the effects may read.
+ * Feeds Proposal 01's var-path checks (a `{ var: 'state.foo' }` whose `foo` is not declared is suspect).
+ */
+function declaredFields(shape) {
+    return new Set(Object.keys(shape.fields));
+}

package/dist/cjs/validation.js

@@ -33,9 +33,7 @@ const hexString = (length) => {
 /**
  * Schema for a DAG address
  */
-exports.DagAddressSchema = zod_1.z
-    .string()
-    .regex(/^DAG[0-9][a-zA-Z0-9]{36}$/, 'Must be a valid DAG address');
+exports.DagAddressSchema = zod_1.z.string().regex(/^DAG[0-9][a-zA-Z0-9]{36}$/, 'Must be a valid DAG address');
 // ============================================================================
 // Core Type Schemas
 // ============================================================================

package/dist/esm/apps/compute/index.js

@@ -0,0 +1,29 @@
+/**
+ * Compute Application — bare computation substrates.
+ *
+ * Turing-complete JLVM substrates with no parties, assets, or governance: pure
+ * in-place state evolution. The flagship is `rule110`, an in-place Rule-110
+ * cellular automaton that proves the account layer is Turing-complete.
+ *
+ * @example
+ * ```typescript
+ * import { getComputeDefinition, COMPUTE_DEFINITIONS } from '@ottochain/sdk/apps/compute';
+ *
+ * const rule110Def = getComputeDefinition('rule110');
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { computeRule110Def } from './state-machines/index.js';
+export { computeRule110Def };
+/** All compute (bare-computation) state machine definitions. */
+export const COMPUTE_DEFINITIONS = {
+    rule110: computeRule110Def,
+};
+/**
+ * Get a compute state machine definition by type.
+ * @param type - 'rule110' (default).
+ */
+export function getComputeDefinition(type = 'rule110') {
+    return COMPUTE_DEFINITIONS[type];
+}

package/dist/esm/apps/compute/state-machines/compute-rule110.js

@@ -0,0 +1,161 @@
+import { defineFiberApp } from '../../../schema/fiber-app.js';
+/**
+ * Rule-110 cellular automaton — an in-place, Turing-complete JLVM substrate.
+ *
+ * Each `step` event advances ONE CA generation in place:
+ *   next[i] = R110(tape[i-1], tape[i], tape[i+1])
+ * with fixed-0 boundaries, computed as a JLVM `map` over a STORED index array
+ * (`idx`) — no bitwise ops, no spawn, no zip. The fiber loops RUNNING → RUNNING;
+ * the chain of transitions IS the Turing-machine tape-head.
+ *
+ * Rule 110: out = 1 iff p ∈ {1,2,3,5,6}, where p = 4·left + 2·center + right.
+ *
+ * THE INLINED-CELL CONSTRAINT (do not "simplify" with `let`)
+ * ---------------------------------------------------------
+ * Inside `map`, a primitive element is overlaid into the eval context, so
+ * `{var:""}` coerces to the element int ONLY in arithmetic position. Opening a
+ * `let` scope over the element makes `{var:""}` resolve to the whole context
+ * object (`{"tag":"map"}`) and any `cat` on it throws `JsonLogicRuntimeError`.
+ * Therefore the per-cell predicate P is fully INLINED at each of the five `==`
+ * comparison sites (P appears 5×; each neighbour read `nb` reads the tape once
+ * per occurrence). This is the only form that works inside `map`. It is built
+ * programmatically below to avoid hand-duplicating P, but it expands to the
+ * inlined AST — NOT a `let`-form.
+ *
+ * Neighbour access uses a computed `var` PATH with a null-default boundary:
+ *   nb(off) = { var: [ { cat: ["state.tape.", off] }, 0 ] }
+ * An out-of-bounds index (-1 or N) resolves to the default `0` (fixed-0
+ * boundary), so `tape`/`idx` stay exactly length N forever.
+ *
+ * Verified end-to-end against `@constellation-network/metagraph-sdk-jlvm@1.8.0-rc.5`:
+ * the effect reproduces the canonical left-growing Rule-110 fractal exactly,
+ * `idx` is byte-identical across every generation, and the unbounded/bounded
+ * guard halts at `gen == maxGen`.
+ */
+// nb(off): read tape at element-relative offset, fixed-0 boundary via null-default.
+const nb = (off) => ({
+    var: [{ cat: ['state.tape.', off] }, 0],
+});
+// P = 4·left + 2·center + right  (element {var:""} is the cell index i).
+const P = {
+    '+': [{ '*': [4, nb({ '-': [{ var: '' }, 1] })] }, { '*': [2, nb({ var: '' })] }, nb({ '+': [{ var: '' }, 1] })],
+};
+// CELL: 1 iff P ∈ {1,2,3,5,6}, else 0. P is INLINED at each `==` site (B1: never
+// `let` over the map element). Built from the rule-110 truth set programmatically.
+const CELL = {
+    if: [{ or: [1, 2, 3, 5, 6].map((k) => ({ '==': [P, k] })) }, 1, 0],
+};
+/**
+ * Rule-110 cellular-automaton fiber definition.
+ *
+ * Trust model: PUBLIC / PERMISSIONLESS / pure compute. No assets, no parties,
+ * no owner — anyone may submit `step`. The DoS surface is bounded by per-event
+ * gas/fee (~987 gas/cell) and the optional `maxGen` halt bound (absent ⇒
+ * unbounded; runs until fees stop).
+ */
+export const computeRule110Def = defineFiberApp({
+    metadata: {
+        name: 'ComputeRule110',
+        app: 'compute',
+        type: 'rule110',
+        version: '1.0.0',
+        description: 'In-place Rule-110 cellular automaton — a Turing-complete substrate. Each ' +
+            '`step` advances one generation: next[i]=R110(tape[i-1],tape[i],tape[i+1]) ' +
+            'with fixed-0 boundaries, as a JLVM map over a stored index array (no ' +
+            'bitwise, no spawn, no zip).',
+    },
+    createSchema: {
+        // maxGen is NOT required: absent ⇒ unbounded (the step guard uses `missing`).
+        required: ['tape', 'idx'],
+        properties: {
+            tape: {
+                type: 'array',
+                items: { type: 'integer' },
+                description: '0/1 CA row (length N).',
+            },
+            idx: {
+                type: 'array',
+                items: { type: 'integer' },
+                immutable: true,
+                description: 'Monotone index array [0..N-1]; REQUIRED (no range/iota opcode). ' +
+                    'Never mutated — the effect preserves it across every generation.',
+            },
+            gen: {
+                type: 'integer',
+                default: 0,
+                description: 'Generation counter (TM step count).',
+            },
+            maxGen: {
+                type: 'integer',
+                description: 'Optional halt bound; absent ⇒ unbounded.',
+            },
+        },
+    },
+    stateSchema: {
+        properties: {
+            tape: { type: 'array', items: { type: 'integer' }, computed: true },
+            idx: { type: 'array', items: { type: 'integer' }, immutable: true },
+            gen: { type: 'integer', computed: true },
+            maxGen: { type: 'integer' },
+            status: { type: 'string', computed: true },
+        },
+    },
+    eventSchemas: {
+        step: { description: 'Advance one CA generation in place.' },
+        halt: { description: 'Terminate once maxGen is reached (gated by gen >= maxGen).' },
+    },
+    states: {
+        RUNNING: {
+            id: 'RUNNING',
+            isFinal: false,
+            metadata: {
+                label: 'Running',
+                description: 'CA evolving; each step = one generation.',
+                category: 'active',
+            },
+        },
+        HALTED: {
+            id: 'HALTED',
+            isFinal: true,
+            metadata: {
+                label: 'Halted',
+                description: 'maxGen reached; terminal.',
+                category: 'terminal',
+            },
+        },
+    },
+    initialState: 'RUNNING',
+    transitions: [
+        {
+            // One `step` = one generation. Loops in place (the TM tape-head).
+            from: 'RUNNING',
+            to: 'RUNNING',
+            eventName: 'step',
+            // Unbounded when maxGen is absent (`missing` → true); else gate on gen < maxGen.
+            guard: {
+                or: [{ missing: ['state.maxGen'] }, { '<': [{ var: 'state.gen' }, { var: 'state.maxGen' }] }],
+            },
+            // Effect result IS the new stateData: merge[state, overrides] preserves
+            // idx/maxGen and overwrites tape/gen.
+            effect: {
+                merge: [
+                    { var: 'state' },
+                    {
+                        tape: { map: [{ var: 'state.idx' }, CELL] },
+                        gen: { '+': [{ var: 'state.gen' }, 1] },
+                    },
+                ],
+            },
+            dependencies: [],
+        },
+        {
+            // halt is rejected until exhaustion: gen >= maxGen.
+            from: 'RUNNING',
+            to: 'HALTED',
+            eventName: 'halt',
+            guard: { '>=': [{ var: 'state.gen' }, { var: 'state.maxGen' }] },
+            effect: { merge: [{ var: 'state' }, { status: 'halted' }] },
+            dependencies: [],
+        },
+    ],
+});

package/dist/esm/apps/compute/state-machines/index.js

@@ -0,0 +1,5 @@
+/**
+ * Compute (bare-computation) state machine definitions.
+ * Re-exports from TypeScript definition files.
+ */
+export { computeRule110Def } from './compute-rule110.js';

package/dist/esm/apps/contracts/index.js

@@ -21,13 +21,13 @@
 // Re-export generated protobuf types (source of truth).
 // The nested lifecycle enum dropped its app prefix in the proto; under this
 // app-scoped entrypoint it is unambiguously State.
-export { State, Contract, ProposeContractRequest, AcceptContractRequest, CompleteContractRequest, RejectContractRequest, DisputeContractRequest, ContractDefinition, stateFromJSON, stateToJSON, } from "../../generated/ottochain/apps/contracts/v1/contract.js";
+export { State, Contract, ProposeContractRequest, AcceptContractRequest, CompleteContractRequest, RejectContractRequest, DisputeContractRequest, ContractDefinition, stateFromJSON, stateToJSON, } from '../../generated/ottochain/apps/contracts/v1/contract.js';
 // Deprecated app-prefixed alias (renamed to State); kept for compat.
-export { State as ContractState, stateFromJSON as contractStateFromJSON, stateToJSON as contractStateToJSON, } from "../../generated/ottochain/apps/contracts/v1/contract.js";
+export { State as ContractState, stateFromJSON as contractStateFromJSON, stateToJSON as contractStateToJSON, } from '../../generated/ottochain/apps/contracts/v1/contract.js';
 // ---------------------------------------------------------------------------
 // State Machine Definitions (generated from JSON at build time)
 // ---------------------------------------------------------------------------
-import { contractUniversalDef, contractAgreementDef, contractEscrowDef, } from "./state-machines/index.js";
+import { contractUniversalDef, contractAgreementDef, contractEscrowDef } from './state-machines/index.js';
 export { contractUniversalDef, contractAgreementDef, contractEscrowDef };
 /** All contract state machine definitions */
 export const CONTRACTS_DEFINITIONS = {
@@ -39,7 +39,7 @@ export const CONTRACTS_DEFINITIONS = {
  * Get a contract state machine definition by type.
  * @param type - 'universal' | 'agreement' | 'escrow' (default: 'agreement')
  */
-export function getContractDefinition(type = "agreement") {
+export function getContractDefinition(type = 'agreement') {
     return CONTRACTS_DEFINITIONS[type];
 }
 /** @deprecated Use getContractDefinition('escrow') */