@ottochain/sdk 2.2.4 → 2.3.0

package/dist/types/ottochain/genesis-manifest.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Genesis Manifest Exporter
+ *
+ * The ottochain metagraph can boot from a NON-EMPTY genesis: a set of standard
+ * packages pre-registered in the registry before any user transaction. This SDK
+ * is the source of truth for those std apps (their proto schemas + JSON-Logic
+ * state-machine definitions), so it is also the source of truth for the
+ * *genesis manifest* — the per-app CONTENT the chain needs to pre-register each
+ * package at genesis.
+ *
+ * DESIGN — content, not consensus hashes:
+ * The manifest ships CONTENT only: the `schemaShape` (the typed, proto-faithful
+ * projection of the app's state message) and the `definition` (the JSON-Logic
+ * `StateMachineDefinition`, verbatim — the same object the chain decodes for any
+ * fiber). The CHAIN computes the consensus values itself from this content:
+ *   - `logicHash` = `StateMachineDefinition.computeDigest(definition)`
+ *   - `schemaHash` = commitment over the FileDescriptorSet (off-chain/Bridge)
+ * We deliberately do NOT replicate the chain's canonical hashing here, so there
+ * is ZERO hash-parity risk. No advisory hashes are emitted (see HONESTY notes in
+ * the PR description); add them later only if an off-chain consumer needs them,
+ * clearly marked advisory.
+ *
+ * NAMING — the reserved `std` label:
+ * Each package is named `std.<app>.package`. `RegistryName` reserves the `std`
+ * label in-protocol (`RegistryName.isReserved`), so ordinary user registrations
+ * of `std.*` are rejected — only the privileged genesis path may claim them.
+ * That is exactly the point: users cannot squat the standard names.
+ *
+ * SCHEMA SHAPES — chain-verified ground truth:
+ * The three `stateMessage` shapes are reproduced verbatim from the chain's own
+ * conformance suite (`StandardAppsConformanceSuite`, the `identity` / `proposal`
+ * / `market` `MessageShape` vals), which proves the on-chain shape validator and
+ * the conformance gate accept them. `commands` is left EMPTY for this first cut —
+ * the conformance suite itself models all three apps with `SortedMap.empty`
+ * commands, and the proto `*Request` messages are transaction-layer DTOs that do
+ * not map cleanly onto the universal state machines' free-form JSON-Logic event
+ * payloads. Deriving per-event command shapes is a flagged follow-up.
+ *
+ * The JSON shape emitted here is built to deserialize against the chain's circe
+ * codecs (`SchemaShape` / `FieldShape` / `MessageShape` and
+ * `StateMachineDefinition`), whose magnolia config is camelCase with defaults.
+ *
+ * @packageDocumentation
+ */
+/**
+ * One field of a protobuf message, mirroring a `FieldDescriptorProto` at the
+ * field level. Matches the chain's `FieldShape` (camelCase, defaults for
+ * `repeated`/`optional`).
+ */
+export interface FieldShape {
+    name: string;
+    number: number;
+    typeName: string;
+    repeated: boolean;
+    optional: boolean;
+}
+/** A protobuf message projection. Matches the chain's `MessageShape`. */
+export interface MessageShape {
+    typeName: string;
+    fields: FieldShape[];
+}
+/**
+ * The typed, proto-faithful projection of a registered schema. Matches the
+ * chain's `SchemaShape`: the state message plus one message per command/event,
+ * keyed by event name.
+ */
+export interface SchemaShape {
+    stateMessage: MessageShape;
+    commands: Record<string, MessageShape>;
+}
+/**
+ * A JSON-Logic `StateMachineDefinition` as the chain decodes it. Kept as an
+ * opaque JSON object: the chain owns its meaning and its hashing. `from`/`to`
+ * and the `states` keys are bare strings (the chain's `StateId` encodes as a
+ * string); `dependencies` defaults to `[]` and state `metadata` to `null`.
+ */
+export interface StateMachineDefinition {
+    states: Record<string, {
+        id: string;
+        isFinal: boolean;
+        metadata: unknown | null;
+    }>;
+    initialState: string;
+    transitions: Array<{
+        from: string;
+        to: string;
+        eventName: string;
+        guard: unknown;
+        effect: unknown;
+        dependencies: unknown[];
+    }>;
+    metadata: unknown | null;
+}
+/**
+ * One package to pre-register at genesis. This is the genesis INPUT, not the
+ * chain's stored `RegisteredVersion`: it carries CONTENT only and the chain
+ * derives `schemaHash` / `logicHash` from it.
+ */
+export interface GenesisPackage {
+    /** RegistryName `"<labels>.package"`, e.g. `std.identity.package`. */
+    name: string;
+    /** SemVer of this initial version. */
+    semver: string;
+    /** Opt-in runtime conformance gate (`RegisteredVersion.strict`). */
+    strict: boolean;
+    /** Free-form notes map (<=8 entries, key <=32 chars, value <=128 chars). */
+    metadata: Record<string, string>;
+    /** Typed, proto-faithful projection of the app's schema. */
+    schemaShape: SchemaShape;
+    /** The JSON-Logic state-machine definition, verbatim. */
+    definition: StateMachineDefinition;
+}
+/** The full genesis manifest the chain consumes to bootstrap its registry. */
+export interface GenesisManifest {
+    version: number;
+    packages: GenesisPackage[];
+}
+/** Manifest schema version. Bump on any breaking change to the shape. */
+export declare const GENESIS_MANIFEST_VERSION = 1;
+/**
+ * Assemble the genesis manifest for the standard apps.
+ *
+ * Covers THREE apps in this first cut — identity, governance, markets (all the
+ * `universal` variant). The other std apps (contracts, oracles, corporate) and
+ * non-universal variants are a flagged follow-up.
+ *
+ * @returns a `GenesisManifest` whose JSON deserializes against the chain's circe
+ *   codecs. Hashes are intentionally absent — the chain derives them.
+ */
+export declare function buildGenesisManifest(): GenesisManifest;

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

@@ -6,7 +6,7 @@
  * @packageDocumentation
  */
 export * as proto from '../generated/index.js';
-export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, JsonLogicValue, JsonLogicExpression, FiberStatus, AccessControlPolicy, StateMachineDefinition, EmittedEvent, EventReceipt, OracleInvocation, FiberLogEntry, StateMachineFiberRecord, ScriptFiberRecord, FiberRecord, FiberCommit, OnChain, CalculatedState, CreateStateMachine, TransitionStateMachine, ArchiveStateMachine, CreateScript, InvokeScript, OttochainMessage, OttochainMessageType, } from './types.js';
+export type { Address, FiberId, StateId, HashValue, FiberOrdinal, SnapshotOrdinal, JsonLogicValue, JsonLogicExpression, FiberStatus, AccessControlPolicy, StateMachineDefinition, SemVer, RegistryStatus, VersionReq, SchemaRef, FieldShape, MessageShape, SchemaShape, SchemaBinding, RegisteredVersion, VersionLineage, RegistryTarget, RegistryEntry, EmittedEvent, EventReceipt, OracleInvocation, CreationReceipt, UpgradeReceipt, FiberLogEntry, StateMachineFiberRecord, ScriptFiberRecord, FiberRecord, FiberCommit, OnChain, CalculatedState, CreateStateMachine, TransitionStateMachine, ArchiveStateMachine, UpgradeFiber, CreateScript, InvokeScript, PublishVersion, SetVersionStatus, RegisterAlias, OttochainMessage, OttochainMessageType, } from './types.js';
 export { OTTOCHAIN_MESSAGE_TYPES } from './types.js';
 export type { CurrencySnapshotResponse } from './snapshot.js';
 export { decodeOnChainState, getSnapshotOnChainState, getLatestOnChainState, getLogsForFiber, getEventReceipts, getScriptInvocations, extractOnChainState, } from './snapshot.js';
@@ -16,3 +16,5 @@ export { createTransitionPayload, createArchivePayload, createInvokeScriptPayloa
 export type { CreateStateMachineParams, CreateStateMachineMessage, CreateScriptParams, CreateScriptMessage, DataTransactionRequest, TransitionParams, TransitionStateMachineMessage, ArchiveParams, ArchiveStateMachineMessage, InvokeScriptParams, InvokeScriptMessage, } from './transaction.js';
 export { normalizeCreateStateMachine, normalizeTransitionStateMachine, normalizeArchiveStateMachine, normalizeMessage, } from './normalize.js';
 export { dropNulls } from './drop-nulls.js';
+export { buildGenesisManifest, GENESIS_MANIFEST_VERSION } from './genesis-manifest.js';
+export type { GenesisManifest, GenesisPackage, SchemaShape as GenesisSchemaShape, MessageShape as GenesisMessageShape, FieldShape as GenesisFieldShape, StateMachineDefinition as GenesisStateMachineDefinition, } from './genesis-manifest.js';

package/dist/types/ottochain/normalize.d.ts

@@ -2,46 +2,38 @@
  * Normalize OttoChain Messages for Signing
  *
  * Converts OttoChain message objects to the wire format expected by the
- * Scala metagraph. Metakit's JsonBinaryCodec (used by OttoChain for data
- * transaction signing) canonicalizes JSON with dropNullValues = true.
+ * Scala metagraph. Specifically, ensures all `Option[A]=None` fields are
+ * present as explicit `null` values, matching what circe's magnolia encoder
+ * produces on the Scala side.
  *
- * NOTE: This is Metakit's codec, NOT tessellation's JsonSerializer (which
- * uses Brotli compression for snapshots/consensus — a different layer).
- * Different layers use different byte-sequence encoders.
+ * This is necessary because metakit's `JsonBinaryCodec.deriveDataUpdate`
+ * (rc.8) canonicalizes the circe-encoded JSON **including null fields**.
+ * If the TypeScript client omits optional fields (undefined), the canonical
+ * JSON won't match and signature verification will fail.
  *
- * Because Metakit drops null fields during canonicalization, the canonical
- * JSON used for signature verification **omits** null fields entirely.
- * If the TypeScript client includes explicit nulls (e.g., `"metadata": null`),
- * the canonical form won't match and signature verification will fail.
- *
- * Schema mapping (Scala → TypeScript wire format):
- * - `Option[A] = None` → field OMITTED (not null, not undefined)
+ * Schema mapping (Scala → TypeScript):
+ * - `Option[A] = None` → `null` (must be explicit, not undefined/absent)
  * - `Option[A] = Some(v)` → `v`
- * - `List.empty` / `Set.empty` → `[]`
+ * - `List.empty` → `[]`
  * - `Map.empty` → `{}`
- * - `Boolean = false` → `false` (always include, not a null/Option)
  */
 /**
  * Normalize a CreateStateMachine message for wire format
  *
- * Metakit's JsonBinaryCodec uses dropNullValues = true for canonicalization.
- * Optional fields at their defaults must be OMITTED (not set to null)
- * to match the canonical JSON used for signature verification.
- *
- * - definition.metadata → OMITTED when absent/FiberAppMetadata
- * - definition.states[*].metadata → OMITTED when absent
- * - definition.transitions[*].dependencies → [] (Set.empty default, always included)
- * - parentFiberId → OMITTED when absent (Option[UUID] = None)
- * - participants → OMITTED when absent (Option[Set[Address]] = None)
+ * Ensures all Option/default fields are explicit in wire format:
+ * - definition.metadata → null when absent
+ * - definition.states[*].metadata → null when absent
+ * - definition.transitions[*].dependencies → [] when absent
+ * - parentFiberId → null when absent
  *
  * @example
  * ```typescript
  * const message = normalizeCreateStateMachine({
  *   fiberId: '...',
- *   definition: { states: { INIT: { id: 'INIT', isFinal: false } }, ... },
+ *   definition: { states: { INIT: { id: { value: 'INIT' }, isFinal: false } }, ... },
  *   initialData: {}
  * });
- * // Optional fields are absent (not null): no parentFiberId, no metadata, etc.
+ * // message now has parentFiberId: null, definition.metadata: null, etc.
  * ```
  */
 export declare function normalizeCreateStateMachine(msg: Record<string, unknown>): Record<string, unknown>;

package/dist/types/ottochain/types.d.ts

@@ -46,6 +46,183 @@ export interface StateMachineDefinition {
     transitions: unknown[];
     metadata?: JsonLogicValue;
 }
+/**
+ * Semantic version `MAJOR.MINOR.PATCH`.
+ * Wire format: plain string (e.g. "1.0.0"). Also used as a JSON map key.
+ *
+ * @see modules/models/.../schema/registry/SemVer.scala
+ */
+export type SemVer = string;
+/**
+ * Lifecycle status of a registered version (npm/Cargo-style).
+ * Wire format: uppercase string (enumeratum `Uppercase`).
+ *
+ *  - `ACTIVE`     — selectable + recommended.
+ *  - `DEPRECATED` — still resolvable/runnable, flagged, discouraged for new instances.
+ *  - `YANKED`     — excluded from NEW resolutions; existing pinned fibers keep running.
+ *
+ * @see modules/models/.../schema/registry/RegistryStatus.scala
+ */
+export type RegistryStatus = 'ACTIVE' | 'DEPRECATED' | 'YANKED';
+/**
+ * A caller's version requirement, resolved against a {@link VersionLineage} (Cargo/npm-style).
+ * Wire format: single-key wrapper object (sealed-trait encoding).
+ *
+ *  - `Exact`      — exactly this version: `{"Exact":{"version":"1.0.0"}}`.
+ *  - `Caret`      — same MAJOR and `>= v` (`^1.2.0`).
+ *  - `Tilde`      — same MAJOR.MINOR and `>= v` (`~1.2.0`).
+ *  - `Latest`     — highest selectable version: `{"Latest":{}}`.
+ *  - `PinnedHash` — the exact artifact by schema hash, version-agnostic.
+ *
+ * @see modules/models/.../schema/registry/VersionReq.scala
+ */
+export type VersionReq = {
+    Exact: {
+        version: SemVer;
+    };
+} | {
+    Caret: {
+        version: SemVer;
+    };
+} | {
+    Tilde: {
+        version: SemVer;
+    };
+} | {
+    Latest: Record<string, never>;
+} | {
+    PinnedHash: {
+        schemaHash: string;
+    };
+};
+/**
+ * A caller's reference to a registered schema/program version, supplied at fiber creation
+ * (`CreateStateMachine.schemaRef`). The chain resolves `version` against the registry at create time.
+ * Wire format: `{"name":"counter.package","version":{"Exact":{"version":"1.0.0"}}}`.
+ *
+ * @see modules/models/.../schema/registry/SchemaRef.scala
+ */
+export interface SchemaRef {
+    /** Full registry name `labels.tld` (e.g. "counter.package"). */
+    name: string;
+    version: VersionReq;
+}
+/**
+ * One field of a {@link MessageShape} — mirrors a protobuf `FieldDescriptorProto`
+ * at the field level (name + field number + type).
+ * Wire format: `repeated`/`optional` default to `false` and are omittable.
+ *
+ * @see modules/models/.../schema/registry/SchemaShape.scala
+ */
+export interface FieldShape {
+    name: string;
+    number: number;
+    typeName: string;
+    repeated?: boolean;
+    optional?: boolean;
+}
+/**
+ * A single protobuf message shape: its type name plus its fields.
+ *
+ * @see modules/models/.../schema/registry/SchemaShape.scala
+ */
+export interface MessageShape {
+    typeName: string;
+    fields: FieldShape[];
+}
+/**
+ * The on-chain projection of a version's proto schema: the State message plus one
+ * message per command/event (keyed by event name). Publisher-claimed and advisory.
+ *
+ * @see modules/models/.../schema/registry/SchemaShape.scala
+ */
+export interface SchemaShape {
+    stateMessage: MessageShape;
+    /** One message per command/event, keyed by event name. */
+    commands: Record<string, MessageShape>;
+}
+/**
+ * The resolved, pinned binding recorded on a fiber: which registry (name, version) it
+ * instantiates, with the committed hashes. Resolved once at create, then immutable.
+ *
+ * @see modules/models/.../schema/registry/SchemaBinding.scala
+ */
+export interface SchemaBinding {
+    /** Full registry name `labels.tld`. */
+    name: string;
+    version: SemVer;
+    /** Commitment to the protobuf FileDescriptorSet (descriptor bytes; off-chain). */
+    schemaHash: string;
+    /** The verified-binding anchor: `StateMachineDefinition.computeDigest` of the logic. */
+    logicHash: string;
+}
+/**
+ * One immutable version of a registry entry. The chain commits only the hashes + the
+ * typed {@link SchemaShape} projection (never the descriptor or definition bytes).
+ * Wire format: `strict` defaults to `false` and is omittable.
+ *
+ * @see modules/models/.../schema/registry/RegisteredVersion.scala
+ */
+export interface RegisteredVersion {
+    version: SemVer;
+    /** Commitment to the protobuf FileDescriptorSet (descriptor bytes; off-chain). */
+    schemaHash: string;
+    /** The verified-binding anchor: `StateMachineDefinition.computeDigest` of the logic. */
+    logicHash: string;
+    schemaShape: SchemaShape;
+    status: RegistryStatus;
+    /** Snapshot ordinal at which this version was registered. */
+    registeredAt: number;
+    /** Opt-in runtime conformance gate (#33); defaults to `false`. */
+    strict?: boolean;
+}
+/**
+ * The append-only, monotonic version lineage of a single registry entry.
+ * Wire format: `versions` is a SemVer-string-keyed map of {@link RegisteredVersion}.
+ *
+ * @see modules/models/.../schema/registry/VersionLineage.scala
+ */
+export interface VersionLineage {
+    /** SemVer-string keyed map of registered versions. */
+    versions: Record<string, RegisteredVersion>;
+}
+/**
+ * What a registry entry resolves to, discriminated by the name's TLD.
+ * Wire format: single-key wrapper object (sealed-trait encoding).
+ *
+ *  - `SchemaPackage` (`.package`) — a versioned schema/program type (its {@link VersionLineage}).
+ *    Note the double-nesting: `SchemaPackage.versions` is a {@link VersionLineage} whose
+ *    own `.versions` is the SemVer-keyed map, e.g.
+ *    `{"SchemaPackage":{"versions":{"versions":{"1.0.0":{...}}}}}`.
+ *  - `InstanceAlias` (`.machine` / `.script`) — a nickname for an existing fiber (#29).
+ *
+ * @see modules/models/.../schema/registry/RegistryTarget.scala
+ */
+export type RegistryTarget = {
+    SchemaPackage: {
+        versions: VersionLineage;
+    };
+} | {
+    InstanceAlias: {
+        fiberId: string;
+    };
+};
+/**
+ * A single owned entry in the registry namespace: a name -> a discriminated
+ * {@link RegistryTarget}, with the owning addresses and an optional off-chain metadata grab-bag.
+ * Wire format: `metadata` defaults to `{}` and is omittable.
+ *
+ * @see modules/models/.../schema/registry/RegistryEntry.scala
+ */
+export interface RegistryEntry {
+    /** Full registry name `labels.tld`. */
+    name: string;
+    /** Owning DAG addresses (who may publish versions / change status / transfer). */
+    owner: string[];
+    target: RegistryTarget;
+    /** Optional off-chain links grab-bag (e.g. "repo"/"homepage" -> URL). */
+    metadata?: Record<string, string>;
+}
 /**
  * Event emitted by a state machine transition trigger.
  */
@@ -84,10 +261,40 @@ export interface OracleInvocation {
     invokedAt: number;
     invokedBy: string;
 }
+/**
+ * Birth record for a fiber, emitted once at creation. Records the resolved registry
+ * binding (name@version + committed hashes) when instantiated from a registered version
+ * (#26), or omits it for an ad-hoc fiber. Seeds the audit-trail rendering (#30).
+ *
+ * @see modules/models/.../schema/fiber/FiberLogEntry.scala
+ */
+export interface CreationReceipt {
+    fiberId: string;
+    ordinal: number;
+    initialState: string;
+    owners: string[];
+    schemaBinding?: SchemaBinding;
+    parentFiberId?: string;
+}
+/**
+ * Emitted when a fiber is upgraded to a different registered version (#27). Records the
+ * binding change (from -> to) and whether a state migration ran.
+ *
+ * @see modules/models/.../schema/fiber/FiberLogEntry.scala
+ */
+export interface UpgradeReceipt {
+    fiberId: string;
+    ordinal: number;
+    /** Prior binding; absent for a fiber that had no registry binding before the upgrade. */
+    fromBinding?: SchemaBinding;
+    toBinding: SchemaBinding;
+    gasUsed: number;
+    migrated: boolean;
+}
 /**
  * Union type for all fiber log entries.
  */
-export type FiberLogEntry = EventReceipt | OracleInvocation;
+export type FiberLogEntry = EventReceipt | OracleInvocation | CreationReceipt | UpgradeReceipt;
 /**
  * On-chain record for a state machine fiber.
  * Wire format: all ordinals/states/hashes are plain primitives.
@@ -107,6 +314,8 @@ export interface StateMachineFiberRecord {
     lastReceipt?: EventReceipt;
     parentFiberId?: string;
     childFiberIds: string[];
+    /** The resolved, pinned registry binding (#26), present when created from a registered version. */
+    schemaBinding?: SchemaBinding;
 }
 /**
  * On-chain record for a script oracle fiber.
@@ -142,6 +351,8 @@ export interface FiberCommit {
 export interface OnChain {
     fiberCommits: Record<string, FiberCommit>;
     latestLogs: Record<string, FiberLogEntry[]>;
+    /** Per-registry-entry commitment hash, keyed by full registry name `labels.tld`. */
+    registryCommits: Record<string, string>;
 }
 /**
  * Full calculated state (served by ML0 /v1/ endpoints).
@@ -149,6 +360,10 @@ export interface OnChain {
 export interface CalculatedState {
     stateMachines: Record<string, StateMachineFiberRecord>;
     scripts: Record<string, ScriptFiberRecord>;
+    /** Registry namespace, keyed by full registry name `labels.tld`. */
+    registry: Record<string, RegistryEntry>;
+    /** Reverse records (#29): fiber UUID -> its canonical registered name. */
+    reverseNames: Record<string, string>;
 }
 /**
  * Create a new state machine fiber.
@@ -160,6 +375,11 @@ export interface CreateStateMachine {
     parentFiberId?: string | null;
     /** Optional set of DAG addresses authorized to sign transitions (multi-party signing). */
     participants?: string[] | null;
+    /**
+     * Optional reference to a registered schema/program version (#26). When present, the chain
+     * resolves it against the registry at create time and records the verified {@link SchemaBinding}.
+     */
+    schemaRef?: SchemaRef | null;
 }
 /**
  * Trigger a state machine transition.
@@ -195,6 +415,64 @@ export interface InvokeScript {
     args: JsonLogicValue;
     targetSequenceNumber: number;
 }
+/**
+ * Upgrade an existing fiber to a different registered version of the SAME package (#27).
+ * The chain verifies `newDefinition` hashes to the target version's `logicHash`, applies the
+ * optional `migration` (a JSON-Logic transform of the prior state data), preserves the current
+ * state id, and re-pins the binding.
+ */
+export interface UpgradeFiber {
+    fiberId: string;
+    targetRef: SchemaRef;
+    newDefinition: StateMachineDefinition;
+    /** Optional JSON-Logic transform applied to the prior state data during upgrade. */
+    migration?: JsonLogicExpression;
+    targetSequenceNumber: number;
+}
+/**
+ * Create-or-append a registry schema-package version (npm-publish semantics): the first publish
+ * for a name claims it and makes the signer the owner; later publishes require an existing owner.
+ *
+ * Note: `fiberId` is NOT on the wire — the chain derives the routing id from `name`.
+ */
+export interface PublishVersion {
+    /** Full registry name `labels.tld` (e.g. "order.package"). */
+    name: string;
+    version: SemVer;
+    /** Base64 of the proto FileDescriptorSet; the chain base64-validates + hashes it, then drops the bytes. */
+    schemaB64: string;
+    /** The typed proto projection the chain stores for discovery (advisory). */
+    schemaShape: SchemaShape;
+    /** The typed JSON-Logic state machine; hashed into `logicHash` for verified binding (#37). */
+    definition: StateMachineDefinition;
+    /** Opt-in runtime conformance gate (#33); defaults to `false`, omittable. */
+    strict?: boolean;
+    /** Optional off-chain links grab-bag set on the entry at first publish; defaults to `{}`, omittable. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Change a registered version's lifecycle status (Active <-> Deprecated -> Yanked). Owner-gated.
+ */
+export interface SetVersionStatus {
+    /** Full registry name `labels.tld`. */
+    name: string;
+    version: SemVer;
+    status: RegistryStatus;
+}
+/**
+ * Register a human-readable nickname for an existing fiber (#29). The name's TLD must be
+ * `.machine` or `.script` and match the target fiber's kind; the signer must own the target.
+ *
+ * Note: `fiberId` is NOT on the wire — the chain derives the routing id from `name`.
+ */
+export interface RegisterAlias {
+    /** Full registry name `labels.tld` (e.g. "my-escrow.machine"). */
+    name: string;
+    /** The existing fiber UUID this alias points at. */
+    targetFiberId: string;
+    /** Optional off-chain links grab-bag; defaults to `{}`, omittable. */
+    metadata?: Record<string, string>;
+}
 /**
  * Union type for all ottochain messages.
  * JSON is wrapped as `{ MessageName: { ...fields } }`.
@@ -205,16 +483,24 @@ export type OttochainMessage = {
     TransitionStateMachine: TransitionStateMachine;
 } | {
     ArchiveStateMachine: ArchiveStateMachine;
+} | {
+    UpgradeFiber: UpgradeFiber;
 } | {
     CreateScript: CreateScript;
 } | {
     InvokeScript: InvokeScript;
+} | {
+    PublishVersion: PublishVersion;
+} | {
+    SetVersionStatus: SetVersionStatus;
+} | {
+    RegisterAlias: RegisterAlias;
 };
 /**
  * Names of all valid OttochainMessage types.
  * Use this for runtime validation (e.g., in API routes).
  */
-export declare const OTTOCHAIN_MESSAGE_TYPES: readonly ["CreateStateMachine", "TransitionStateMachine", "ArchiveStateMachine", "CreateScript", "InvokeScript"];
+export declare const OTTOCHAIN_MESSAGE_TYPES: readonly ["CreateStateMachine", "TransitionStateMachine", "ArchiveStateMachine", "UpgradeFiber", "CreateScript", "InvokeScript", "PublishVersion", "SetVersionStatus", "RegisterAlias"];
 /**
  * Type representing valid message type names.
  */

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

@@ -40,11 +40,50 @@ export interface EventSchema {
     required?: readonly string[];
     properties?: Record<string, SchemaField>;
 }
+/**
+ * Lifecycle category for a state — a small fixed vocabulary that lets UIs group
+ * and color states and lets analytics bucket fibers without app-specific logic.
+ *
+ * - `initial`  — the machine's `initialState` (entry point)
+ * - `active`   — a normal, operational, non-terminal state
+ * - `pending`  — a transient state awaiting an action/condition/timeout
+ * - `terminal` — a final state (`isFinal: true`); the machine ends here
+ */
+export type StateCategory = 'initial' | 'active' | 'pending' | 'terminal';
+/**
+ * Standard per-state metadata convention for OttoChain std apps.
+ *
+ * This is the minimal, high-value block we attach to every standard state
+ * definition (instead of `metadata: null`). It is plain JSON, so it survives
+ * the client/server null-dropping canonicalization (only NULL fields are
+ * dropped; a populated object is kept and signed/verified identically on both
+ * sides). Custom apps may extend `StateDefinition.metadata` with extra keys.
+ *
+ * Fields:
+ * - `label`       — short human-readable title for the state (e.g. "Active")
+ * - `description` — one-line explanation of what the state means
+ * - `category`    — optional lifecycle hint (see {@link StateCategory})
+ */
+export interface StdStateMetadata {
+    /** Short human-readable title, e.g. "Voting". */
+    label: string;
+    /** One-line description of what this state represents. */
+    description: string;
+    /** Optional lifecycle category hint for UIs / analytics. */
+    category?: StateCategory;
+}
 export interface StateDefinition {
     id: string;
     isFinal: boolean;
     description?: string;
-    metadata?: Record<string, unknown> | null;
+    /**
+     * Optional per-state metadata. Std apps populate the {@link StdStateMetadata}
+     * convention (`label` / `description` / `category`); custom apps may use any
+     * JSON object or `null`. NOTE: a `null` here is stripped from the signed wire
+     * form (the chain drops null object-fields), so prefer populated metadata or
+     * omit the field entirely.
+     */
+    metadata?: StdStateMetadata | Record<string, unknown> | null;
 }
 export type JsonLogicRule = Record<string, unknown>;
 export interface EmitSpec {