@ottochain/sdk 2.4.0 → 2.6.0

package/dist/types/schema/fiber-app.d.ts

@@ -105,6 +105,269 @@ export interface Transition<TState extends string = string, TEvent extends strin
     dependencies?: readonly (string | DependencySpec)[];
     emits?: readonly (string | EmitSpec)[];
 }
+/**
+ * `allowedEffects` element — the 5 `EffectKind` families, UPPERCASE on the wire
+ * (`enumeratum` `Uppercase` mixin). Chain: `EffectKind` in `FiberPolicy.scala`.
+ */
+export type EffectKind = 'TRIGGER' | 'SPAWN' | 'EMIT' | 'TRANSFER' | 'DEPENDENCY';
+/**
+ * `spawnOwnerPolicy` — UPPERCASE (`enumeratum` `Uppercase`). Chain: `SpawnOwnerPolicy`
+ * (`Explicit` / `SubsetOfParent` / `InheritParent` ⇒ `"EXPLICIT"` / `"SUBSETOFPARENT"`
+ * / `"INHERITPARENT"`).
+ */
+export type SpawnOwnerPolicy = 'EXPLICIT' | 'SUBSETOFPARENT' | 'INHERITPARENT';
+/**
+ * `dependencyPolicy.mode` — UPPERCASE (`enumeratum` `Uppercase`). Chain: `DependencyMode`
+ * (`Open` / `Allowlist` / `Frozen`). REQUIRED on the wire (Scala defaults it to `Open`,
+ * but the `customizableEncoder` always encodes the value).
+ */
+export type DependencyMode = 'OPEN' | 'ALLOWLIST' | 'FROZEN';
+/**
+ * `transferPolicy` — recipient allowlist for `_transferAsset`. Chain: `TransferPolicy`
+ * (`Option[Set[UUID]]` fibers, `Option[Set[Address]]` wallets). Each field is OPTIONAL;
+ * an absent field ⇒ that recipient class is unconstrained (and is `dropNulls`-stripped).
+ */
+export interface TransferPolicy {
+    /** Fiber UUIDs permitted to receive a transfer. */
+    allowedRecipientFibers?: readonly string[];
+    /** DAG wallet addresses permitted to receive a transfer. */
+    allowedRecipientWallets?: readonly string[];
+}
+/**
+ * `dependencyPolicy` — dynamic-dependency posture. Chain: `DependencyPolicy`
+ * (`mode: DependencyMode`, `allowed: Option[Set[UUID]]`). `mode` is REQUIRED; `allowed`
+ * is meaningful only when `mode === 'ALLOWLIST'` and is `dropNulls`-stripped otherwise.
+ */
+export interface DependencyPolicy {
+    /** Posture: `OPEN` (any target) / `ALLOWLIST` (only `allowed`) / `FROZEN` (no new). */
+    mode: DependencyMode;
+    /** Fiber UUIDs permitted as dependency targets (meaningful only under `ALLOWLIST`). */
+    allowed?: readonly string[];
+}
+/**
+ * `migrationAuthority` — who may authorize a `Governed` migration. Chain:
+ * `MigrationAuthority`, a DISJOINT-FIELD discriminated union (no tag key): the `Signers`
+ * arm carries `addresses`, the `Role` arm carries `registryFiberId` + `roleField`. The
+ * presence of disjoint fields is the discriminator (same as the chain decoder's `.or`).
+ */
+export type MigrationAuthority = {
+    /** VERIFIED signer DAG addresses permitted to authorize the migration (`Signers`). */
+    addresses: readonly string[];
+} | {
+    /** Registry fiber UUID whose role-map is consulted (`Role`). */
+    registryFiberId: string;
+    /** Field/key in that fiber's state holding the `{<address>: true}` role map (`Role`). */
+    roleField: string;
+};
+/**
+ * `upgradePolicy` — the upgrade-path constitution. Chain: `UpgradePolicy`. The three
+ * bare variants encode as LOWERCASE tag STRINGS (`"immutable"` / `"appendOnly"` /
+ * `"arbitrary"`); the `Governed` arm encodes as the object `{ authority: <MigrationAuthority> }`.
+ *
+ * NOTE: this lowercase `"immutable"` is the upgradePolicy DIAL VALUE — distinct from the
+ * policy-level variant tag `"Immutable"` (capital-I), a different construct added in a
+ * later change.
+ */
+export type UpgradePolicy = 'immutable' | 'appendOnly' | 'arbitrary' | {
+    /** Authority that may consent to a `Governed` migration. */
+    authority: MigrationAuthority;
+};
+/**
+ * `transitionPolicy` — WHO may drive a transition on this fiber. Chain: `TransitionPolicy`
+ * (chain PR #194), a bare tag STRING with three ranked levels:
+ *
+ *   - `"Open"` — anyone may drive a transition; the transition's `guard` is the only gate.
+ *     This is the chain DEFAULT when the dial is ABSENT, so omitting it is byte-identical
+ *     to the legacy (pre-#194) behaviour.
+ *   - `"OwnersOrParticipants"` — only the fiber's owners or its declared participants.
+ *   - `"Owners"` — only the fiber's owners.
+ *
+ * Absent ⇒ `"Open"` (chain `transitionPolicy: Option[TransitionPolicy] = None`,
+ * `dropNulls`-stripped). The chain joins this to the tighten-only upgrade lattice, so an
+ * upgrade may only RAISE the level (`Open < OwnersOrParticipants < Owners`); LOOSENING it
+ * (including dropping the dial on a fiber that had it set) is rejected as `CombineRejected`.
+ */
+export type TransitionPolicy = 'Open' | 'OwnersOrParticipants' | 'Owners';
+/**
+ * `compatibleWith` — the inclusive-min / exclusive-max SemVer bridge window a migration
+ * may target. Chain: `VersionRange` (`min: Option[SemVer]`, `max: Option[SemVer]`). Each
+ * bound is a SemVer STRING (`"1.2.3"`); an absent bound is unconstrained on that side and
+ * is `dropNulls`-stripped.
+ */
+export interface VersionRange {
+    /** Inclusive lower bound, e.g. `"1.0.0"` (absent ⇒ unconstrained below). */
+    min?: string;
+    /** Exclusive upper bound, e.g. `"2.0.0"` (absent ⇒ unconstrained above). */
+    max?: string;
+}
+/**
+ * `FiberPolicy` — the constitution a definition declares for the fibers it spawns.
+ *
+ * This MIRRORS the chain ADT `FiberPolicy = Unconstrained | Immutable | Constrained(<dials>)`
+ * (chain branch `feat/fiber-policy-adt`). The representation here is chosen for
+ * BYTE-FOR-BYTE wire parity with the chain, because a `StateMachineDefinition` is
+ * signed verbatim by the SDK (`batchSign(dropNulls(...))`) and re-encoded + verified
+ * by the chain. The rule is:
+ *
+ *   - **`Unconstrained`** ⇒ there is **NO `policy` key** on the wire definition at all.
+ *     In the SDK this is the DEFAULT and is represented by simply OMITTING `policy`
+ *     (i.e. `policy === undefined`).
+ *   - **`Immutable`** ⇒ the definition is permanently locked; `policy` is the bare JSON
+ *     STRING `"Immutable"` (EXACT casing, capital-I) — NOT an object. Semantically this is
+ *     the upgradePolicy DIAL set to its LOWERCASE `"immutable"` value with no other dial
+ *     set, and the chain collapses that exact `Constrained` into the `Immutable` variant.
+ *     See {@link immutable} and the canonical collapse in {@link projectFiberPolicy}.
+ *   - **`Constrained(dials)`** ⇒ `policy` is a bare object of ONLY the dials that are
+ *     SET. Unset dials are absent (the chain `dropNulls`-strips them; so does the SDK
+ *     at sign time). A `Constrained` with no dials set is wire-indistinguishable from
+ *     `Unconstrained`, so `toProtoDefinition` collapses it back to "no policy key".
+ *
+ * All 15 dials are optional. Provide any subset.
+ */
+export interface FiberPolicyDials {
+    /** Whether the fiber may reproduce itself (spawn instances of its own definition). Wire: boolean. */
+    selfReproducing?: boolean;
+    /**
+     * Allow-list of effect families this fiber's transitions may produce, as a SET of the 5
+     * UPPERCASE {@link EffectKind} tokens (`"TRIGGER" | "SPAWN" | "EMIT" | "TRANSFER" |
+     * "DEPENDENCY"`). Order is not significant; duplicates are collapsed by the chain's `Set`.
+     * Chain: `allowedEffects: Option[Set[EffectKind]]`.
+     */
+    allowedEffects?: readonly EffectKind[];
+    /**
+     * Who/what may own fibers this one spawns — an UPPERCASE {@link SpawnOwnerPolicy} token
+     * (`"EXPLICIT" | "SUBSETOFPARENT" | "INHERITPARENT"`). Chain: `spawnOwnerPolicy: Option[SpawnOwnerPolicy]`.
+     */
+    spawnOwnerPolicy?: SpawnOwnerPolicy;
+    /** Maximum spawn-generation depth (descendant chain length). Wire: number. */
+    maxGenerations?: number;
+    /** Maximum number of children a single transition may spawn. Wire: number. */
+    maxSpawnFanout?: number;
+    /** SET of caller fiber UUIDs permitted to drive transitions on this fiber. Wire: string[]. */
+    acceptedCallers?: readonly string[];
+    /** SET of state ids that are sealed (no transition may fire from them). Wire: string[]. */
+    sealedStates?: readonly string[];
+    /**
+     * WHO may drive a transition on this fiber — a {@link TransitionPolicy} bare tag
+     * (`"Open" | "OwnersOrParticipants" | "Owners"`). Absent ⇒ `"Open"` (guard-only, the
+     * chain default); set `"Owners"`/`"OwnersOrParticipants"` to gate transitions by identity
+     * in ADDITION to the guard. Chain: `transitionPolicy: Option[TransitionPolicy]` (chain PR #194).
+     */
+    transitionPolicy?: TransitionPolicy;
+    /**
+     * Recipient allowlist for `_transferAsset` — the {@link TransferPolicy} object
+     * `{ allowedRecipientFibers?: uuid[], allowedRecipientWallets?: DAG-address[] }`.
+     * Chain: `transferPolicy: Option[TransferPolicy]`.
+     */
+    transferPolicy?: TransferPolicy;
+    /**
+     * Dynamic-dependency policy — the {@link DependencyPolicy} object `{ mode, allowed? }`
+     * where `mode` is the REQUIRED UPPERCASE {@link DependencyMode}. Chain:
+     * `dependencyPolicy: Option[DependencyPolicy]`.
+     */
+    dependencyPolicy?: DependencyPolicy;
+    /**
+     * In-place upgrade/migration posture — an {@link UpgradePolicy}: a LOWERCASE bare tag
+     * (`"immutable" | "appendOnly" | "arbitrary"`) OR the `Governed` object
+     * `{ authority: <MigrationAuthority> }`. Chain: `upgradePolicy: Option[UpgradePolicy]`.
+     */
+    upgradePolicy?: UpgradePolicy;
+    /** Self-declared SemVer of this definition as a STRING `"major.minor.patch"` (e.g. `"1.2.3"`). Chain: `version: Option[SemVer]`. */
+    version?: string;
+    /**
+     * Migration bridge window — the {@link VersionRange} object `{ min?: semver, max?: semver }`
+     * naming the successor versions this definition declares it will migrate TO. Chain:
+     * `compatibleWith: Option[VersionRange]`.
+     */
+    compatibleWith?: VersionRange;
+    /** SET of (ERC-165-style) interface identifiers this definition advertises. Wire: string[]. */
+    interfaces?: readonly string[];
+    /**
+     * Authority permitted to authorize a `Governed` migration — a {@link MigrationAuthority}:
+     * `{ addresses: DAG-address[] }` (Signers) OR `{ registryFiberId: uuid, roleField: string }`
+     * (Role), discriminated by disjoint fields. Chain: `migrationAuthority: Option[MigrationAuthority]`.
+     */
+    migrationAuthority?: MigrationAuthority;
+}
+/**
+ * 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.
+ */
+export declare const IMMUTABLE_POLICY: "Immutable";
+export type ImmutablePolicy = typeof IMMUTABLE_POLICY;
+/**
+ * Wire form of a `FiberPolicy`. Mirrors the chain ADT's non-`Unconstrained` arms:
+ *
+ *   - a bare object of the SET dials — the `Constrained` arm. Unset dials are stripped at
+ *     projection time (and again by `dropNulls` at sign time), so this object matches the
+ *     chain's `dropNulls`-stripped `Constrained` encoding exactly; OR
+ *   - the bare JSON string `"Immutable"` — the {@link ImmutablePolicy} arm.
+ *
+ * (`Unconstrained` has no wire representation: it is the absence of the `policy` key.)
+ */
+export type FiberPolicy = FiberPolicyDials | ImmutablePolicy;
+/**
+ * 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).
+ */
+export declare function unconstrained(): 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() });
+ * ```
+ */
+export declare function immutable(): ImmutablePolicy;
+/**
+ * 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'],
+ * });
+ * ```
+ */
+export declare function constrained(dials: FiberPolicyDials): FiberPolicy | undefined;
+/**
+ * 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.
+ */
+export declare function projectFiberPolicy(policy: FiberPolicy | undefined): FiberPolicy | undefined;
 export interface FiberAppMetadata {
     name: string;
     app: string;
@@ -125,6 +388,16 @@ export interface CrossReferences {
 }
 export interface FiberAppDefinition<TState extends string = string, TEvent extends string = string> {
     metadata: FiberAppMetadata;
+    /**
+     * Fiber constitution. Mirrors the chain ADT `FiberPolicy = Unconstrained | Immutable |
+     * Constrained(<dials>)`. OMIT this field (the default) for `Unconstrained` — the projected
+     * wire definition then has NO `policy` key. Set it to `immutable()` to permanently lock the
+     * definition (projects to the bare string `"Immutable"`). Set it to a `constrained({...})`
+     * object to declare a subset of the 15 dials; unset dials are stripped so the wire form
+     * matches the chain's `dropNulls`-stripped `Constrained` byte-for-byte (and a lone
+     * `upgradePolicy: 'immutable'` collapses to `"Immutable"`).
+     */
+    policy?: FiberPolicy;
     /** Schema for fiber creation inputs (user-provided) */
     createSchema?: {
         required?: readonly string[];
@@ -195,6 +468,14 @@ export interface ProtoStateMachineDefinition {
         dependencies: string[];
     }>;
     metadata?: Record<string, unknown>;
+    /**
+     * Fiber constitution. PRESENT for `Constrained` (a bare object of the SET dials) and for
+     * `Immutable` (the bare string `"Immutable"`); ABSENT for `Unconstrained`. This
+     * omit-on-unconstrained rule is the wire parity contract: the chain emits no `policy` key
+     * for `Unconstrained`, so neither may the SDK, or the signature breaks (HTTP 400). See
+     * {@link projectFiberPolicy}.
+     */
+    policy?: FiberPolicy;
 }
 /**
  * Extract proto-compatible StateMachineDefinition from a FiberAppDefinition.

package/dist/types/schema/guards.d.ts

@@ -131,4 +131,16 @@ export declare const signerHasRoleVia: (registryIdVar: string, roleField: string
  * so a single gated transition is split into a bind step then this assert step. See
  * docs/design/app-hardening-identity-integration.md §5–§6.
  */
+/**
+ * EFFECT-KEY-BINDING dedup over an ARRAY of records: no existing element of the array at `arrayVar`
+ * (e.g. `"state.submissions"`, shaped `[ { addr, value }, … ]`) has its `field` (default `"addr"`)
+ * equal to the actor at `actorVar` (default `"event.agent"`). The array analog of the map-keyed
+ * `{"!":[has(...)]}` dedup — used where the collection is an append-only array of `{addr,…}` records
+ * (there is no `(array,string)` key check, but `none` over the array with a per-element `===` is total).
+ *
+ * The bare-element callback context inside `none` sees each record map directly, so `{get:[{var:""},field]}`
+ * is a valid `(map,string)` read. Pair with an `actorIsSigner`/`actorHasEntry` clause on the same
+ * `actorVar` (the dedup proves "not yet present", not "is the verified signer").
+ */
+export declare const actorNotInArray: (arrayVar: string, field?: string, actorVar?: string) => GuardRule;
 export declare const depInState: (refVar: string, requiredState: string) => GuardRule;

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;