@ottochain/sdk 2.3.0 → 2.5.0

package/dist/types/templates/asset-policy.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Asset-policy preset builders (§1.1 of the SDK std-lib/templates handoff).
+ *
+ * Each builder is a PURE function that emits the exact {@link CreateAssetPolicy} wire body the chain
+ * re-derives — no `Date.now()`/`Math.random()`/`crypto.randomUUID()`; fixed inputs → fixed output. The
+ * on-chain policy `schemaHash` and `logicHash` are both `RegistryShape.AssetPolicy.computeDigest` over
+ * `behavior`/`supply`/`morphisms`/`stateShape` (no JSON-Logic body), so these presets are pure data.
+ *
+ * Hard invariants (CLAUDE.md rule #1 — the signed canonical is frozen):
+ *  - `behavior` is ALWAYS summed from {@link TOKEN_BEHAVIOR_BITS} (T=16, S=8, C=4, E=2, G=1), never a
+ *    magic literal int.
+ *  - `morphisms` is REQUIRED on the wire (presence required, emptiness meaningful) — emit `{}` when empty,
+ *    NEVER omit it.
+ *  - `supply` is REQUIRED — emit `{}` when there is no supply authority, never omit it.
+ *  - Absent optionals are OMITTED, never emitted as `null`/`undefined` (the chain signs over
+ *    `JCS(dropNulls(payload))`).
+ *
+ * @see src/ottochain/types.ts — CreateAssetPolicy, SupplyPolicy, MorphismSpec, MorphismKind, TOKEN_BEHAVIOR_BITS
+ */
+import { TOKEN_BEHAVIOR_BITS, type CreateAssetPolicy, type JsonLogicExpression, type MorphismKind, type MorphismSpec, type SupplyPolicy } from '../ottochain/types.js';
+/** A behavior-bit NAME (a key of {@link TOKEN_BEHAVIOR_BITS}) — the only legal way to spell `behavior`. */
+export type BehaviorBitName = keyof typeof TOKEN_BEHAVIOR_BITS;
+/** Sum behavior bits from their NAMES — never a magic literal int (CLAUDE.md #1). */
+export declare function sumBehavior(bits: readonly BehaviorBitName[]): number;
+/**
+ * Derive the default `stateShape.typeName`: strip a trailing `.asset` label, PascalCase the remainder
+ * (splitting on `.`/`-`/`_`/space), then append `State`.
+ *   `rvd.asset` → `RvdState`, `goods.asset` → `GoodsState`, `capped.asset` → `CappedState`.
+ */
+export declare function defaultStateTypeName(name: string): string;
+/**
+ * Fungible currency. Behavior `T|S|C = 28` (transferable + splittable + combinable). Standard morphism
+ * set TRANSFER + FRACTIONALIZE + STAKE (`stakeable`, default true) + BURN (when `burnable`), all PUBLIC.
+ *
+ * Reproduces `riverdale-economy/rvd-policy.json` exactly via
+ * `fungiblePolicy({ name: 'rvd.asset', version: '1.0.0', mintable: true, burnable: true })`.
+ */
+export declare function fungiblePolicy(p: {
+    /** Registry name; conventionally ends `.asset`. */
+    name: string;
+    /** SemVer string. */
+    version: string;
+    /** `supply.decimals` — fractional precision; omit for whole-unit. */
+    decimals?: number;
+    /** `supply.maxSupply` — omit ⇒ uncapped. */
+    maxSupply?: number;
+    /** true ⇒ `supply.mintPolicy = {"==":[1,1]}` (open mint). */
+    mintable?: boolean;
+    /** true ⇒ `supply.burnPolicy = {"==":[1,1]}` AND a BURN morphism. */
+    burnable?: boolean;
+    /** JSON-Logic predicate that OVERRIDES `mintable`'s default mint guard (and enables minting). */
+    mintGuard?: JsonLogicExpression;
+    /** default true ⇒ a STAKE morphism. */
+    stakeable?: boolean;
+    /** `stateShape.typeName`; default `${PascalCase(name-without-.asset)}State`. */
+    stateTypeName?: string;
+    /** Off-chain links grab-bag; omitted when absent. */
+    metadata?: Record<string, string>;
+}): CreateAssetPolicy;
+/**
+ * Non-fungible token. Behavior `T = 16`, or `T|C = 20` with `combinable: true` (the riverdale
+ * `goods.asset`); `transferable: false` drops the T bit (a bound collectible). `morphisms` is `{}` by
+ * default (emitted explicitly, never omitted). Mintable by default ⇒ `supply.mintPolicy = {"==":[1,1]}`.
+ *
+ * Reproduces `riverdale-economy/goods-policy.json` exactly via
+ * `nftPolicy({ name: 'goods.asset', version: '1.0.0', combinable: true })`.
+ */
+export declare function nftPolicy(p: {
+    name: string;
+    version: string;
+    /** `T(16)` → `T|C(20)`. */
+    combinable?: boolean;
+    /** default true; false ⇒ drop the T bit (bound collectible: `0`, or `4` with `combinable`). */
+    transferable?: boolean;
+    /** default true ⇒ `supply.mintPolicy = {"==":[1,1]}`. */
+    mintable?: boolean;
+    /** JSON-Logic predicate that OVERRIDES the default mint guard. */
+    mintGuard?: JsonLogicExpression;
+    /** `supply.maxSupply` — omit ⇒ uncapped edition. */
+    maxSupply?: number;
+    /** `stateShape.typeName`; default `${PascalCase(name-without-.asset)}State`. */
+    stateTypeName?: string;
+    metadata?: Record<string, string>;
+}): CreateAssetPolicy;
+/**
+ * Soulbound token: non-transferable, governable only (`G = 1`; `+E = 3` when `expirable`). No TRANSFER
+ * morphism (`morphisms: {}`); minting is closed after issue (empty `supply`).
+ */
+export declare function soulboundPolicy(p: {
+    name: string;
+    version: string;
+    /** `+E(2)` ⇒ behavior `3`. */
+    expirable?: boolean;
+    /** `stateShape.typeName`; default `${PascalCase(name-without-.asset)}State`. */
+    stateTypeName?: string;
+    metadata?: Record<string, string>;
+}): CreateAssetPolicy;
+/**
+ * Escape hatch: declare `behavior` by NAME (summed from {@link TOKEN_BEHAVIOR_BITS}, never a magic int)
+ * and pass `supply` + `morphisms` through raw. Use when no preset fits.
+ *
+ * Reproduces `riverdale-economy/capped-policy.json` exactly via
+ * `customPolicy({ name: 'capped.asset', version: '1.0.0',
+ *                 behavior: ['transferable', 'splittable', 'combinable'],
+ *                 supply: { maxSupply: 100, mintPolicy: { '==': [1, 1] } }, morphisms: {} })`.
+ */
+export declare function customPolicy(p: {
+    name: string;
+    version: string;
+    /** Behavior-bit NAMES summed to the int (e.g. `['transferable','combinable']` ⇒ 20). Never a literal. */
+    behavior: readonly BehaviorBitName[];
+    /** Raw supply authority, passed through verbatim. */
+    supply: SupplyPolicy;
+    /** Raw morphism map, passed through verbatim (emit `{}` when empty, never omit). */
+    morphisms: Partial<Record<MorphismKind, MorphismSpec>>;
+    /** `stateShape.typeName`; default `${PascalCase(name-without-.asset)}State`. */
+    stateTypeName?: string;
+    metadata?: Record<string, string>;
+}): CreateAssetPolicy;

package/dist/types/templates/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@ottochain/sdk/templates` — the fiber & asset authoring template catalog.
+ *
+ * Typed builders that emit the EXACT canonical wire shapes app authors otherwise hand-roll as raw
+ * JSON-Logic (asset policies, versioned machines, effect directives, migrations, seeded state). Every
+ * builder is additive and pure — it returns the same wire shape the chain re-derives, so a template
+ * output signs to byte-identical `JCS(dropNulls(payload))` (CLAUDE.md rule #1). Hand-rolled JSON keeps
+ * working; these just make the recurring shapes typed, named, and mistake-resistant.
+ *
+ * Origin: the fiber-ergonomics program (ottochain `docs/proposals/fiber-ergonomics/`), Phase A — the
+ * `riverdale-economy` e2e is the migration proof (each preset reproduces its checked-in golden JSON).
+ *
+ * @example
+ * import {
+ *   fungiblePolicy, machine, transition, effect, guard,
+ *   transferAsset, triggers, spawn, seedState, seedFields,
+ * } from '@ottochain/sdk/templates';
+ */
+export * from './asset-policy.js';
+export * from './machine.js';
+export * from './migration.js';
+export * from './state-shape.js';
+export * from '../schema/effects.js';
+export * as guard from '../schema/guards.js';
+export { defineFiberApp, toProtoDefinition, constrained, unconstrained, immutable, projectFiberPolicy, } from '../schema/fiber-app.js';
+export type { FiberAppDefinition, Transition, ProtoStateMachineDefinition, FiberPolicy, FiberPolicyDials, } from '../schema/fiber-app.js';

package/dist/types/templates/machine.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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.
+ */
+import { type Transition, type JsonLogicRule, type DependencySpec, type FiberAppDefinition, type ProtoStateMachineDefinition } from '../schema/fiber-app.js';
+import type { MachineShape, PublishMachineVersion, CreateStateMachine, UpgradeFiber, SemVer, JsonLogicValue, JsonLogicExpression } from '../ottochain/types.js';
+/** Authoring shape for {@link transition} — `on` is the event name (mapped to the wire `eventName`). */
+export interface TransitionSpec<TState extends string = string, TEvent extends string = string> {
+    from: TState;
+    to: TState;
+    /** Event that fires this transition. Mapped to the wire key `eventName`. */
+    on: TEvent;
+    /** JSON-Logic predicate; defaults to the always-true `{ "==": [1, 1] }` when omitted. */
+    guard?: JsonLogicRule;
+    /** The flat effect map (build it with {@link effect}). Passed through verbatim. */
+    effect?: JsonLogicRule;
+    /**
+     * Dependencies for this transition. Defaults to `[]` (ALWAYS present — the chain
+     * `Transition.dependencies: Set[UUID]` has no default; omitting it diverges the canonical).
+     * `toProtoDefinition` later drops any non-string {@link DependencySpec} authoring entries.
+     */
+    dependencies?: readonly (string | DependencySpec)[];
+}
+/**
+ * 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([...]),
+ *   ),
+ * });
+ * ```
+ */
+export declare function transition<TState extends string = string, TEvent extends string = string>(t: TransitionSpec<TState, TEvent>): Transition<TState, TEvent>;
+/**
+ * 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 }
+ * ```
+ */
+export declare function effect(stateUpdate: Record<string, unknown>, ...directives: Record<string, unknown>[]): Record<string, unknown>;
+/** The machine package spec: identity (`name`@`version`) + the one canonical `app` + its schema shape. */
+export interface MachineSpec<TState extends string = string, TEvent extends string = string> {
+    /** Full registry name `labels.tld` (e.g. `"consumer.package"`). */
+    name: string;
+    /** SemVer string (e.g. `"1.0.0"`). */
+    version: SemVer;
+    /** The typed fiber app; projected ONCE to the canonical wire definition via `toProtoDefinition`. */
+    app: FiberAppDefinition<TState, TEvent>;
+    /** The advisory proto projection the chain stores for discovery (carried onto `PublishMachineVersion.machineShape`). */
+    schemaShape: MachineShape;
+}
+/** Options for {@link Machine.publishVersion}. */
+export interface PublishVersionOptions {
+    /** Opt-in runtime conformance gate (#33). Defaults to `false` (REQUIRED on the wire — never omitted). */
+    strict?: boolean;
+    /** Optional off-chain links grab-bag; OMITTED when absent (never `null`). */
+    metadata?: Record<string, string>;
+    /**
+     * Base64 of the proto FileDescriptorSet. REQUIRED on the wire `PublishMachineVersion` (the chain
+     * base64-validates + hashes it, then drops the bytes), so it is ALWAYS present; defaults to the empty
+     * string `''` (valid empty base64) when the skeleton has no descriptor set bound. The verified binding
+     * hangs on `definition.computeDigest`, NOT on this field.
+     */
+    schemaB64?: string;
+}
+/** Options for {@link Machine.create}. */
+export interface CreateOptions {
+    fiberId: string;
+    /** Seeded fiber state (e.g. from `seedState(...)`); pre-seed accumulators so no field reads `null`. */
+    initialData: JsonLogicValue;
+    /** Optional DAG addresses authorized to sign transitions; OMITTED when absent (never `null`). */
+    participants?: string[];
+    /** Optional parent fiber UUID; OMITTED when absent (never `null`). */
+    parentFiberId?: string;
+}
+/** Options for {@link Machine.upgradeFrom}. */
+export interface UpgradeOptions {
+    fiberId: string;
+    targetSequenceNumber: number;
+    /** Optional JSON-Logic migration transform of the prior state; OMITTED when absent (never `null`). */
+    migration?: JsonLogicExpression;
+}
+/** The versioned-machine skeleton returned by {@link machine}. */
+export interface Machine {
+    /** The ONE canonical wire definition (`toProtoDefinition(app)`), shared by publish + create. */
+    wireDefinition(): ProtoStateMachineDefinition;
+    /** The `PublishMachineVersion` body — its `definition` is the SAME object as `wireDefinition()`. */
+    publishVersion(o?: PublishVersionOptions): PublishMachineVersion;
+    /** The `CreateStateMachine` body — references `name@version` via `schemaRef` + the SAME `definition`. */
+    create(o: CreateOptions): CreateStateMachine;
+    /** The `UpgradeFiber` body — re-pins to `name@version` with the SAME `newDefinition`. */
+    upgradeFrom(o: UpgradeOptions): UpgradeFiber;
+}
+/**
+ * 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.
+ */
+export declare function machine<TState extends string = string, TEvent extends string = string>(spec: MachineSpec<TState, TEvent>): Machine;

package/dist/types/templates/migration.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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`).
+ */
+/**
+ * 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 }] }
+ */
+export declare const seedFields: (fields: Record<string, unknown>) => unknown;
+/**
+ * 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 }] }
+ */
+export declare const migration: (build: (priorState: {
+    var: "";
+}) => unknown) => unknown;

package/dist/types/templates/state-shape.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+import type { SchemaFieldType } from '../schema/fiber-app.js';
+export interface StateShape {
+    fields: Record<string, {
+        default: unknown;
+        type?: SchemaFieldType;
+    }>;
+}
+/**
+ * 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' }
+ */
+export declare function seedState(shape: StateShape, overrides?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 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).
+ */
+export declare function declaredFields(shape: StateShape): Set<string>;