@ottochain/sdk 2.2.5 → 2.4.0

package/dist/esm/apps/governance/state-machines/governance-simple.js

@@ -1,4 +1,5 @@
 import { defineFiberApp } from "../../../schema/fiber-app.js";
+import { actorHasEntry, signerHasEntry, signerInSet, signerIsAnyParty, signerIsNotParty, } from "../../../schema/guards.js";
 /**
  * Simple org governance: manage members, update rules, resolve disputes.
  */
@@ -89,11 +90,8 @@ export const govSimpleDef = defineFiberApp({
             },
         },
         finalize: {
-            description: "Finalize the voting period",
-            required: ["forCount"],
-            properties: {
-                forCount: { type: "number" },
-            },
+            description: "Finalize the voting period (for-count derived from recorded ballots)",
+            properties: {},
         },
         file_dispute: {
             description: "File a dispute against a member",
@@ -122,18 +120,47 @@ export const govSimpleDef = defineFiberApp({
             },
         },
         dissolve: {
-            description: "Dissolve the organization (requires 90% approval)",
-            required: ["approvalCount"],
-            properties: {
-                approvalCount: { type: "number" },
-            },
+            description: "Dissolve the organization (requires every member to sign this op — verified unanimity)",
+            properties: {},
         },
     },
     states: {
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        VOTING: { id: "VOTING", isFinal: false, metadata: null },
-        DISPUTE: { id: "DISPUTE", isFinal: false, metadata: null },
-        DISSOLVED: { id: "DISSOLVED", isFinal: true, metadata: null },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Governance is idle and ready to accept a proposal",
+                category: "initial",
+            },
+        },
+        VOTING: {
+            id: "VOTING",
+            isFinal: false,
+            metadata: {
+                label: "Voting",
+                description: "A proposal is open for voting",
+                category: "pending",
+            },
+        },
+        DISPUTE: {
+            id: "DISPUTE",
+            isFinal: false,
+            metadata: {
+                label: "Dispute",
+                description: "A proposal outcome is being disputed",
+                category: "pending",
+            },
+        },
+        DISSOLVED: {
+            id: "DISSOLVED",
+            isFinal: true,
+            metadata: {
+                label: "Dissolved",
+                description: "Governance entity dissolved (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "ACTIVE",
     transitions: [
@@ -142,16 +169,16 @@ export const govSimpleDef = defineFiberApp({
             from: "ACTIVE",
             to: "ACTIVE",
             eventName: "add_member",
-            guard: { in: [{ var: "event.agent" }, { var: "state.admins" }] },
+            guard: signerInSet("state.admins"),
             effect: {
                 merge: [
                     { var: "state" },
                     {
                         members: {
-                            setKey: [
+                            set: [
                                 { var: "state.members" },
                                 { var: "event.member" },
-                                { role: { var: "event.role" }, addedAt: { var: "$timestamp" } },
+                                { role: { var: "event.role" }, addedAt: { var: "$ordinal" } },
                             ],
                         },
                     },
@@ -164,13 +191,13 @@ export const govSimpleDef = defineFiberApp({
             from: "ACTIVE",
             to: "ACTIVE",
             eventName: "remove_member",
-            guard: { in: [{ var: "event.agent" }, { var: "state.admins" }] },
+            guard: signerInSet("state.admins"),
             effect: {
                 merge: [
                     { var: "state" },
                     {
                         members: {
-                            deleteKey: [{ var: "state.members" }, { var: "event.member" }],
+                            unset: [{ var: "state.members" }, { var: "event.member" }],
                         },
                     },
                 ],
@@ -182,7 +209,9 @@ export const govSimpleDef = defineFiberApp({
             from: "ACTIVE",
             to: "VOTING",
             eventName: "propose",
-            guard: { getKey: [{ var: "state.members" }, { var: "event.agent" }] },
+            // S1/A2 coupled fix: a CHAIN-VERIFIED signer must be a member (getKey is not a
+            // JLVM opcode; signerHasEntry checks signer ∈ keys(state.members) via `has`).
+            guard: signerHasEntry("state.members"),
             effect: {
                 merge: [
                     { var: "state" },
@@ -192,9 +221,9 @@ export const govSimpleDef = defineFiberApp({
                             type: { var: "event.type" },
                             changes: { var: "event.changes" },
                             proposer: { var: "event.agent" },
-                            proposedAt: { var: "$timestamp" },
+                            proposedAt: { var: "$ordinal" },
                             deadline: {
-                                "+": [{ var: "$timestamp" }, { var: "state.votingPeriodMs" }],
+                                "+": [{ var: "$ordinal" }, { var: "state.votingPeriodMs" }],
                             },
                         },
                         votes: {},
@@ -208,12 +237,14 @@ export const govSimpleDef = defineFiberApp({
             from: "VOTING",
             to: "VOTING",
             eventName: "vote",
+            // S1/A2 coupled fix: bind event.agent to a verified signer who is a member (actorHasEntry),
+            // and block a re-vote by that SAME bound actor — so the ballot is recorded under, and deduped
+            // on, the chain-verified voter. Without the binding, signerHasEntry only proves SOME signer is a
+            // member, letting one member stuff votes under arbitrary keys (set is the rc.5 map-write opcode).
             guard: {
                 and: [
-                    { getKey: [{ var: "state.members" }, { var: "event.agent" }] },
-                    {
-                        "!": [{ getKey: [{ var: "state.votes" }, { var: "event.agent" }] }],
-                    },
+                    actorHasEntry("state.members"),
+                    { "!": [{ has: [{ var: "state.votes" }, { var: "event.agent" }] }] },
                 ],
             },
             effect: {
@@ -221,10 +252,10 @@ export const govSimpleDef = defineFiberApp({
                     { var: "state" },
                     {
                         votes: {
-                            setKey: [
+                            set: [
                                 { var: "state.votes" },
                                 { var: "event.agent" },
-                                { vote: { var: "event.vote" }, votedAt: { var: "$timestamp" } },
+                                { vote: { var: "event.vote" }, votedAt: { var: "$ordinal" } },
                             ],
                         },
                     },
@@ -237,12 +268,24 @@ export const govSimpleDef = defineFiberApp({
             from: "VOTING",
             to: "ACTIVE",
             eventName: "finalize",
+            // S2/A2 coupled fix: the for-count is DERIVED from recorded ballots in
+            // state.votes (length of the "for" entries), never read from the attacker's
+            // event.forCount. members is a Map so its count is length(keys(members)).
             guard: {
                 ">=": [
-                    { var: "event.forCount" },
+                    {
+                        length: [
+                            {
+                                filter: [
+                                    { values: [{ var: "state.votes" }] },
+                                    { "===": [{ var: "vote" }, "for"] },
+                                ],
+                            },
+                        ],
+                    },
                     {
                         "*": [
-                            { size: { var: "state.members" } },
+                            { length: [{ keys: [{ var: "state.members" }] }] },
                             { var: "state.passingThreshold" },
                         ],
                     },
@@ -266,7 +309,7 @@ export const govSimpleDef = defineFiberApp({
                                         type: "rule_change",
                                         proposal: { var: "state.proposal" },
                                         outcome: "passed",
-                                        finalizedAt: { var: "$timestamp" },
+                                        finalizedAt: { var: "$ordinal" },
                                     },
                                 ],
                             ],
@@ -283,12 +326,23 @@ export const govSimpleDef = defineFiberApp({
             from: "VOTING",
             to: "ACTIVE",
             eventName: "finalize",
+            // S2/A2 coupled fix (failed arm): derive the for-count from recorded ballots in
+            // state.votes; never from event.forCount. members count = length(keys(members)).
             guard: {
                 "<": [
-                    { var: "event.forCount" },
+                    {
+                        length: [
+                            {
+                                filter: [
+                                    { values: [{ var: "state.votes" }] },
+                                    { "===": [{ var: "vote" }, "for"] },
+                                ],
+                            },
+                        ],
+                    },
                     {
                         "*": [
-                            { size: { var: "state.members" } },
+                            { length: [{ keys: [{ var: "state.members" }] }] },
                             { var: "state.passingThreshold" },
                         ],
                     },
@@ -306,7 +360,7 @@ export const govSimpleDef = defineFiberApp({
                                         type: "rule_change",
                                         proposal: { var: "state.proposal" },
                                         outcome: "failed",
-                                        finalizedAt: { var: "$timestamp" },
+                                        finalizedAt: { var: "$ordinal" },
                                     },
                                 ],
                             ],
@@ -323,7 +377,9 @@ export const govSimpleDef = defineFiberApp({
             from: "ACTIVE",
             to: "DISPUTE",
             eventName: "file_dispute",
-            guard: { getKey: [{ var: "state.members" }, { var: "event.agent" }] },
+            // S1/A2 coupled fix: only a CHAIN-VERIFIED member may file (getKey is not a JLVM
+            // opcode; signerHasEntry checks signer ∈ keys(state.members) via `has`).
+            guard: signerHasEntry("state.members"),
             effect: {
                 merge: [
                     { var: "state" },
@@ -333,7 +389,7 @@ export const govSimpleDef = defineFiberApp({
                             plaintiff: { var: "event.agent" },
                             defendant: { var: "event.defendant" },
                             claim: { var: "event.claim" },
-                            filedAt: { var: "$timestamp" },
+                            filedAt: { var: "$ordinal" },
                             evidence: [],
                         },
                         votes: {},
@@ -347,16 +403,10 @@ export const govSimpleDef = defineFiberApp({
             from: "DISPUTE",
             to: "DISPUTE",
             eventName: "submit_evidence",
-            guard: {
-                or: [
-                    {
-                        "===": [{ var: "event.agent" }, { var: "state.dispute.plaintiff" }],
-                    },
-                    {
-                        "===": [{ var: "event.agent" }, { var: "state.dispute.defendant" }],
-                    },
-                ],
-            },
+            guard: signerIsAnyParty([
+                "state.dispute.plaintiff",
+                "state.dispute.defendant",
+            ]),
             effect: {
                 merge: [
                     { var: "state" },
@@ -372,7 +422,7 @@ export const govSimpleDef = defineFiberApp({
                                                 {
                                                     from: { var: "event.agent" },
                                                     content: { var: "event.content" },
-                                                    at: { var: "$timestamp" },
+                                                    at: { var: "$ordinal" },
                                                 },
                                             ],
                                         ],
@@ -390,18 +440,16 @@ export const govSimpleDef = defineFiberApp({
             from: "DISPUTE",
             to: "DISPUTE",
             eventName: "vote",
+            // S1/A2 coupled fix: bind event.agent to a verified member (actorHasEntry), exclude the parties,
+            // and block a re-vote by that SAME bound actor — so the dispute ballot is recorded under, and
+            // deduped on, the chain-verified voter (set is the rc.5 map-write opcode; signerIsNotParty still
+            // excludes any signer who is a party, which covers the bound actor).
             guard: {
                 and: [
-                    { getKey: [{ var: "state.members" }, { var: "event.agent" }] },
-                    {
-                        "!==": [{ var: "event.agent" }, { var: "state.dispute.plaintiff" }],
-                    },
-                    {
-                        "!==": [{ var: "event.agent" }, { var: "state.dispute.defendant" }],
-                    },
-                    {
-                        "!": [{ getKey: [{ var: "state.votes" }, { var: "event.agent" }] }],
-                    },
+                    actorHasEntry("state.members"),
+                    signerIsNotParty("state.dispute.plaintiff"),
+                    signerIsNotParty("state.dispute.defendant"),
+                    { "!": [{ has: [{ var: "state.votes" }, { var: "event.agent" }] }] },
                 ],
             },
             effect: {
@@ -409,12 +457,12 @@ export const govSimpleDef = defineFiberApp({
                     { var: "state" },
                     {
                         votes: {
-                            setKey: [
+                            set: [
                                 { var: "state.votes" },
                                 { var: "event.agent" },
                                 {
                                     ruling: { var: "event.ruling" },
-                                    votedAt: { var: "$timestamp" },
+                                    votedAt: { var: "$ordinal" },
                                 },
                             ],
                         },
@@ -428,9 +476,11 @@ export const govSimpleDef = defineFiberApp({
             from: "DISPUTE",
             to: "ACTIVE",
             eventName: "resolve",
+            // A2 fix: count recorded ballots. votes is a Map, and `length` rejects Maps, so
+            // count its keys: length(keys(state.votes)). (size is not a JLVM opcode.)
             guard: {
                 ">=": [
-                    { size: { var: "state.votes" } },
+                    { length: [{ keys: [{ var: "state.votes" }] }] },
                     { var: "state.disputeQuorum" },
                 ],
             },
@@ -447,7 +497,7 @@ export const govSimpleDef = defineFiberApp({
                                         dispute: { var: "state.dispute" },
                                         ruling: { var: "event.ruling" },
                                         remedy: { var: "event.remedy" },
-                                        resolvedAt: { var: "$timestamp" },
+                                        resolvedAt: { var: "$ordinal" },
                                     },
                                 ],
                             ],
@@ -464,14 +514,28 @@ export const govSimpleDef = defineFiberApp({
             from: "ACTIVE",
             to: "DISSOLVED",
             eventName: "dissolve",
+            // S2/A2 coupled fix: dissolution must not trust an attacker-supplied
+            // approvalCount. Derive consent from the CHAIN-VERIFIED signers — every member
+            // (a key in state.members) must be among proofs[].address, with a non-empty
+            // belt. members is a Map, so iterate keys(members); size is not a JLVM opcode.
             guard: {
-                ">=": [
-                    { var: "event.approvalCount" },
-                    { "*": [{ size: { var: "state.members" } }, 0.9] },
+                and: [
+                    { ">": [{ length: [{ keys: [{ var: "state.members" }] }] }, 0] },
+                    {
+                        all: [
+                            { keys: [{ var: "state.members" }] },
+                            {
+                                in: [
+                                    { var: "" },
+                                    { map: [{ var: "proofs" }, { var: "address" }] },
+                                ],
+                            },
+                        ],
+                    },
                 ],
             },
             effect: {
-                merge: [{ var: "state" }, { dissolvedAt: { var: "$timestamp" } }],
+                merge: [{ var: "state" }, { dissolvedAt: { var: "$ordinal" } }],
             },
             dependencies: [],
         },

package/dist/esm/apps/governance/state-machines/governance-universal.js

@@ -49,9 +49,33 @@ export const govUniversalDef = defineFiberApp({
         },
     },
     states: {
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        VOTING: { id: "VOTING", isFinal: false, metadata: null },
-        DISSOLVED: { id: "DISSOLVED", isFinal: true, metadata: null },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Governance is idle and ready to accept a proposal",
+                category: "initial",
+            },
+        },
+        VOTING: {
+            id: "VOTING",
+            isFinal: false,
+            metadata: {
+                label: "Voting",
+                description: "A proposal is open for voting",
+                category: "pending",
+            },
+        },
+        DISSOLVED: {
+            id: "DISSOLVED",
+            isFinal: true,
+            metadata: {
+                label: "Dissolved",
+                description: "Governance entity dissolved (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "ACTIVE",
     transitions: [
@@ -66,7 +90,7 @@ export const govUniversalDef = defineFiberApp({
                     {
                         status: "VOTING",
                         proposal: { var: "event.proposal" },
-                        proposedAt: { var: "$timestamp" },
+                        proposedAt: { var: "$ordinal" },
                         votes: {},
                     },
                 ],
@@ -125,7 +149,7 @@ export const govUniversalDef = defineFiberApp({
                     { var: "state" },
                     {
                         status: "DISSOLVED",
-                        dissolvedAt: { var: "$timestamp" },
+                        dissolvedAt: { var: "$ordinal" },
                     },
                 ],
             },

package/dist/esm/apps/identity/constants.js

@@ -5,7 +5,7 @@
  *
  * @packageDocumentation
  */
-import { IdentityState } from "../../generated/ottochain/apps/identity/v1/identity.js";
+import { State } from "../../generated/ottochain/apps/identity/v1/identity.js";
 import { AttestationType } from "../../generated/ottochain/apps/identity/v1/attestation.js";
 // ---------------------------------------------------------------------------
 // State Machine Transitions
@@ -16,25 +16,25 @@ import { AttestationType } from "../../generated/ottochain/apps/identity/v1/atte
  * Note: Some transitions are type-specific (agent vs oracle)
  */
 export const IDENTITY_TRANSITIONS = {
-    [IdentityState.IDENTITY_STATE_UNSPECIFIED]: [],
-    [IdentityState.IDENTITY_STATE_UNREGISTERED]: ["register"],
-    [IdentityState.IDENTITY_STATE_REGISTERED]: ["activate", "withdraw"],
-    [IdentityState.IDENTITY_STATE_ACTIVE]: [
+    [State.IDENTITY_STATE_UNSPECIFIED]: [],
+    [State.IDENTITY_STATE_UNREGISTERED]: ["register"],
+    [State.IDENTITY_STATE_REGISTERED]: ["activate", "withdraw"],
+    [State.IDENTITY_STATE_ACTIVE]: [
         "challenge",
         "slash",
         "deactivate",
         "withdraw",
     ],
-    [IdentityState.IDENTITY_STATE_CHALLENGED]: [
+    [State.IDENTITY_STATE_CHALLENGED]: [
         "uphold_challenge",
         "dismiss_challenge",
     ],
-    [IdentityState.IDENTITY_STATE_SUSPENDED]: ["begin_probation"],
-    [IdentityState.IDENTITY_STATE_PROBATION]: ["complete_probation"],
-    [IdentityState.IDENTITY_STATE_SLASHED]: ["reactivate", "withdraw"],
-    [IdentityState.IDENTITY_STATE_INACTIVE]: ["activate", "withdraw"],
-    [IdentityState.IDENTITY_STATE_WITHDRAWN]: [], // Terminal state
-    [IdentityState.UNRECOGNIZED]: [],
+    [State.IDENTITY_STATE_SUSPENDED]: ["begin_probation"],
+    [State.IDENTITY_STATE_PROBATION]: ["complete_probation"],
+    [State.IDENTITY_STATE_SLASHED]: ["reactivate", "withdraw"],
+    [State.IDENTITY_STATE_INACTIVE]: ["activate", "withdraw"],
+    [State.IDENTITY_STATE_WITHDRAWN]: [], // Terminal state
+    [State.UNRECOGNIZED]: [],
 };
 // Legacy alias
 export const AGENT_TRANSITIONS = IDENTITY_TRANSITIONS;
@@ -53,6 +53,45 @@ export const ATTESTATION_DELTAS = {
     [AttestationType.ATTESTATION_TYPE_BEHAVIORAL]: 3,
     [AttestationType.UNRECOGNIZED]: 0,
 };
+// ---------------------------------------------------------------------------
+// Identity Registry — role attestations
+// ---------------------------------------------------------------------------
+/**
+ * Role-attestation types issued by the identity registry (identity-registry fiber).
+ * These are the ecosystem-wide authority roles consumer apps gate on via the registry
+ * dependency + `signerHasRole` (see docs/design/app-hardening-identity-integration.md §4.2).
+ */
+export const REGISTRY_ROLES = {
+    ARBITER: "ARBITER",
+    SLASHER: "SLASHER",
+    ISSUER: "ISSUER",
+    BOARD_MEMBER: "BOARD_MEMBER",
+};
+/**
+ * Maps each role to the registry's flat per-role state-map field. A consumer app reads
+ * `machines.<registryDep>.state.<field>` (a `{ <address>: true }` map) and binds membership to a
+ * verified signer with `signerHasRole`. Kept in lock-step with the identity-registry stateSchema.
+ */
+export const REGISTRY_ROLE_MAP = {
+    ARBITER: "arbiters",
+    SLASHER: "slashers",
+    ISSUER: "issuers",
+    BOARD_MEMBER: "boardMembers",
+};
+/**
+ * Build the `machines.<registryDep>.state.<roleMap>` var path a consumer guard reads to check a role,
+ * e.g. `registryRolePath("reg-uuid", "ARBITER")` → `"machines.reg-uuid.state.arbiters"`.
+ */
+export function registryRolePath(registryDep, role) {
+    return `machines.${registryDep}.state.${REGISTRY_ROLE_MAP[role]}`;
+}
+/**
+ * Build the `machines.<registryDep>.state.reputations` var path a consumer guard reads for a
+ * reputation gate (`signerHasReputation`).
+ */
+export function registryReputationPath(registryDep) {
+    return `machines.${registryDep}.state.reputations`;
+}
 /**
  * Check if a transition is valid for the given state.
  */

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

@@ -16,13 +16,17 @@
  *
  * @packageDocumentation
  */
-// Re-export generated protobuf types (source of truth)
-export { IdentityType, IdentityState, Platform, PlatformLink, Reputation, PenaltyEvent, Identity, RegisterIdentityRequest, ActivateIdentityRequest, LinkPlatformRequest, ChallengeIdentityRequest, AddStakeRequest, WithdrawIdentityRequest, IdentityDefinition, identityTypeFromJSON, identityTypeToJSON, identityStateFromJSON, identityStateToJSON, platformFromJSON, platformToJSON, } from "../../generated/ottochain/apps/identity/v1/identity.js";
+// Re-export generated protobuf types (source of truth).
+// The nested lifecycle/kind enums dropped their app prefix in the proto; under
+// this app-scoped entrypoint they are unambiguously Type / State.
+export { Type, State, Platform, PlatformLink, Reputation, PenaltyEvent, Identity, RegisterIdentityRequest, ActivateIdentityRequest, LinkPlatformRequest, ChallengeIdentityRequest, AddStakeRequest, WithdrawIdentityRequest, IdentityDefinition, typeFromJSON, typeToJSON, stateFromJSON, stateToJSON, platformFromJSON, platformToJSON, } from "../../generated/ottochain/apps/identity/v1/identity.js";
 // Legacy aliases for backward compatibility
-export { IdentityState as AgentState } from "../../generated/ottochain/apps/identity/v1/identity.js";
+export { State as AgentState } from "../../generated/ottochain/apps/identity/v1/identity.js";
+// Deprecated app-prefixed aliases (renamed to Type / State); kept for compat.
+export { Type as IdentityType, State as IdentityState, typeFromJSON as identityTypeFromJSON, typeToJSON as identityTypeToJSON, stateFromJSON as identityStateFromJSON, stateToJSON as identityStateToJSON, } from "../../generated/ottochain/apps/identity/v1/identity.js";
 export { AttestationType, ReputationDelta, Attestation, VouchRequest, ChallengeRequest, ReputationConfig, attestationTypeFromJSON, attestationTypeToJSON, } from "../../generated/ottochain/apps/identity/v1/attestation.js";
 // Re-export constants and utilities
-export { IDENTITY_TRANSITIONS, AGENT_TRANSITIONS, ATTESTATION_DELTAS, canTransition, getReputationDelta, } from "./constants.js";
+export { IDENTITY_TRANSITIONS, AGENT_TRANSITIONS, ATTESTATION_DELTAS, REGISTRY_ROLES, REGISTRY_ROLE_MAP, registryRolePath, registryReputationPath, canTransition, getReputationDelta, } from "./constants.js";
 // ---------------------------------------------------------------------------
 // Configuration Defaults
 // ---------------------------------------------------------------------------
@@ -41,17 +45,18 @@ export const DEFAULT_REPUTATION_CONFIG = {
 // ---------------------------------------------------------------------------
 // State Machine Definitions (generated from JSON at build time)
 // ---------------------------------------------------------------------------
-import { identityUniversalDef, identityAgentDef, identityOracleDef, } from "./state-machines/index.js";
-export { identityUniversalDef, identityAgentDef, identityOracleDef };
+import { identityUniversalDef, identityAgentDef, identityOracleDef, identityRegistryDef, } from "./state-machines/index.js";
+export { identityUniversalDef, identityAgentDef, identityOracleDef, identityRegistryDef, };
 /** All identity state machine definitions */
 export const IDENTITY_DEFINITIONS = {
     universal: identityUniversalDef,
     agent: identityAgentDef,
     oracle: identityOracleDef,
+    registry: identityRegistryDef,
 };
 /**
  * Get an identity state machine definition by type.
- * @param type - 'universal' | 'agent' | 'oracle' (default: 'agent')
+ * @param type - 'universal' | 'agent' | 'oracle' | 'registry' (default: 'agent')
  */
 export function getIdentityDefinition(type = "agent") {
     return IDENTITY_DEFINITIONS[type];

package/dist/esm/apps/identity/state-machines/identity-agent.js

@@ -129,12 +129,60 @@ export const identityAgentDef = defineFiberApp({
         },
     },
     states: {
-        REGISTERED: { id: "REGISTERED", isFinal: false },
-        ACTIVE: { id: "ACTIVE", isFinal: false },
-        CHALLENGED: { id: "CHALLENGED", isFinal: false },
-        SUSPENDED: { id: "SUSPENDED", isFinal: false },
-        PROBATION: { id: "PROBATION", isFinal: false },
-        WITHDRAWN: { id: "WITHDRAWN", isFinal: true },
+        REGISTERED: {
+            id: "REGISTERED",
+            isFinal: false,
+            metadata: {
+                label: "Registered",
+                description: "Agent registered but not yet activated",
+                category: "initial",
+            },
+        },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Agent is active and accruing reputation",
+                category: "active",
+            },
+        },
+        CHALLENGED: {
+            id: "CHALLENGED",
+            isFinal: false,
+            metadata: {
+                label: "Challenged",
+                description: "A challenge has been raised; awaiting resolution",
+                category: "pending",
+            },
+        },
+        SUSPENDED: {
+            id: "SUSPENDED",
+            isFinal: false,
+            metadata: {
+                label: "Suspended",
+                description: "Agent suspended after an upheld challenge",
+                category: "pending",
+            },
+        },
+        PROBATION: {
+            id: "PROBATION",
+            isFinal: false,
+            metadata: {
+                label: "Probation",
+                description: "Conditional reinstatement under monitoring",
+                category: "active",
+            },
+        },
+        WITHDRAWN: {
+            id: "WITHDRAWN",
+            isFinal: true,
+            metadata: {
+                label: "Withdrawn",
+                description: "Agent withdrawn from the registry (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "REGISTERED",
     transitions: [
@@ -146,7 +194,7 @@ export const identityAgentDef = defineFiberApp({
             effect: {
                 merge: [
                     { var: "state" },
-                    { status: "ACTIVE", activatedAt: { var: "$timestamp" } },
+                    { status: "ACTIVE", activatedAt: { var: "$ordinal" } },
                 ],
             },
         },
@@ -203,7 +251,7 @@ export const identityAgentDef = defineFiberApp({
             effect: {
                 merge: [
                     { var: "state" },
-                    { status: "SUSPENDED", suspendedAt: { var: "$timestamp" } },
+                    { status: "SUSPENDED", suspendedAt: { var: "$ordinal" } },
                 ],
             },
         },
@@ -215,7 +263,7 @@ export const identityAgentDef = defineFiberApp({
             effect: {
                 merge: [
                     { var: "state" },
-                    { status: "PROBATION", probationStartedAt: { var: "$timestamp" } },
+                    { status: "PROBATION", probationStartedAt: { var: "$ordinal" } },
                 ],
             },
         },