@ottochain/sdk 2.4.0 → 2.5.0

package/dist/types/privacy/sealed-bid.d.ts

@@ -11,8 +11,8 @@
  *     (the Vickrey price). This is the one shared-state step, kept simple for v1; a zk settlement
  *     proof that seals losers' amounts forever is the deferred upgrade (RFC §10).
  */
-import { type FiberAppDefinition } from "../schema/fiber-app.js";
-import { type ShieldOptions } from "./shield-app.js";
+import { type FiberAppDefinition } from '../schema/fiber-app.js';
+import { type ShieldOptions } from './shield-app.js';
 /** The per-bidder PRIVATE state: a bid note `{ amount, bidder, nonce }`. */
 export declare const sealedBidAccountDef: {
     readonly metadata: {
@@ -75,7 +75,7 @@ export declare const sealedBidAccountDef: {
         readonly to: "BID";
         readonly eventName: "place_bid";
         readonly guard: {
-            readonly ">": readonly [{
+            readonly '>': readonly [{
                 readonly var: "event.amount";
             }, 0];
         };
@@ -209,7 +209,7 @@ export declare const vickreyAuctionDef: {
         readonly to: "REVEAL";
         readonly eventName: "reveal";
         readonly guard: {
-            readonly ">=": readonly [{
+            readonly '>=': readonly [{
                 readonly var: "$timestamp";
             }, {
                 readonly var: "state.deadline";
@@ -240,7 +240,7 @@ export declare const vickreyAuctionDef: {
         readonly to: "REVEAL";
         readonly eventName: "reveal";
         readonly guard: {
-            readonly ">=": readonly [{
+            readonly '>=': readonly [{
                 readonly var: "$timestamp";
             }, {
                 readonly var: "state.deadline";
@@ -270,11 +270,11 @@ export declare const vickreyAuctionDef: {
         readonly to: "SETTLED";
         readonly eventName: "settle";
         readonly guard: {
-            readonly ">": readonly [{
+            readonly '>': readonly [{
                 readonly reduce: readonly [{
                     readonly var: "state.revealed";
                 }, {
-                    readonly "+": readonly [{
+                    readonly '+': readonly [{
                         readonly var: "accumulator";
                     }, 1];
                 }, 0];
@@ -299,7 +299,7 @@ export declare const vickreyAuctionDef: {
                         readonly var: "state.revealed";
                     }, {
                         readonly if: readonly [{
-                            readonly ">": readonly [{
+                            readonly '>': readonly [{
                                 readonly var: "current.amount";
                             }, {
                                 readonly var: "accumulator.max";
@@ -316,7 +316,7 @@ export declare const vickreyAuctionDef: {
                             };
                         }, {
                             readonly if: readonly [{
-                                readonly ">": readonly [{
+                                readonly '>': readonly [{
                                     readonly var: "current.amount";
                                 }, {
                                     readonly var: "accumulator.second";

package/dist/types/privacy/shield-app.d.ts

@@ -24,7 +24,7 @@
  * O(state size) (RFC §8). Keep shielded note state small (a few KB); for large keyed state use
  * the auth-DB variant (RFC §3.1.1).
  */
-import { type FiberAppDefinition, type SchemaField } from "../schema/fiber-app.js";
+import { type FiberAppDefinition, type SchemaField } from '../schema/fiber-app.js';
 export interface ShieldOptions {
     /** SP1 program vkey for the zk-jlvm-shielded circuit (0x-prefixed bytes32 hex). Pinned at creation. */
     vkey: string;

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

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

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';