@ixo/oracle-runtime-workers 0.32.0 → 0.33.0

package/src/plugins/hub-actions/chain-tx-catalog.ts

@@ -3,7 +3,10 @@ import {
   CHAIN_TX_COLLECTION_STATES,
   CHAIN_TX_DISPUTE_REASONS,
   CHAIN_TX_ENTITY_PERMISSIONS,
+  CHAIN_TX_GROUP_ACTION_TYPES,
+  CHAIN_TX_GROUP_VOTE_OPTIONS,
   CHAIN_TX_MAX_CLAIM_PERMISSION,
+  CHAIN_TX_MAX_GROUP_ACTIONS,
   CHAIN_TX_MAX_MESSAGES,
   CHAIN_TX_MAX_PAYMENT_COINS,
   CHAIN_TX_MAX_SECONDS,
@@ -12,6 +15,8 @@ import {
   CHAIN_TX_VOTE_OPTIONS,
   DENOM,
   sanitizePublishedText,
+  type ChainTxGroupActionType,
+  type ChainTxGroupMessageType,
   type ChainTxMessageType,
 } from '@ixo/action-protocol';
 import { z } from 'zod';
@@ -98,6 +103,13 @@ const SERVICE_REF =
  */
 const LINKED_ENTITY_ADDRESS =
   /^(?:\{id\}#)?ixo1(?:[023456789acdefghjklmnpqrstuvwxyz]{38}|[023456789acdefghjklmnpqrstuvwxyz]{58})$/;
+/** A 32-byte contract address (a group and its proposal list): `ixo1` and 58 characters. */
+const CONTRACT_ADDRESS = /^ixo1[023456789acdefghjklmnpqrstuvwxyz]{58}$/;
+/**
+ * A group proposal's number: digits without leading zeros, at most
+ * 2^53 − 1 (Auth Hub writes it as a JSON number).
+ */
+const GROUP_PROPOSAL_ID = /^[1-9][0-9]{0,15}$/;
 
 /**
  * Characters that would let text render as something else: C0 and C1
@@ -494,11 +506,12 @@ const IID_REMOVE_RULE =
   'Copy the id exactly as the lookup shows it, whatever its form (`#api`, `{id}#ixo1…`): Auth Hub checks it is there before it makes the card.';
 
 /**
- * The catalogue. Every `rules` text ends with how to say the step to the
- * owner: plain everyday words, never the message type or chain terms (the
- * review card in Auth Hub shows the exact values).
+ * The types the owner's own account does (every type but the four group
+ * steps). Every `rules` text ends with how to say the step to the owner:
+ * plain everyday words, never the message type or chain terms (the review
+ * card in Auth Hub shows the exact values).
  */
-export const CHAIN_TX_CATALOG = {
+const OWNER_CATALOG = {
   'cosmos.bank.send': {
     summary:
       "send coins (IXO or another token the owner holds) from the owner's wallet.",
@@ -1158,14 +1171,213 @@ export const CHAIN_TX_CATALOG = {
       ),
     }),
   },
+} as const satisfies Record<
+  Exclude<ChainTxMessageType, ChainTxGroupMessageType>,
+  ChainTxCatalogEntry
+>;
+
+// ---- Groups (DAO DAO groups with single-choice proposals) ----
+
+const contractAddress = (what: string) =>
+  z
+    .string()
+    .regex(
+      CONTRACT_ADDRESS,
+      'A 32-byte ixo1… contract address (62 characters), copied exactly from chain_lookup daos or dao_proposals.',
+    )
+    .describe(what);
+const groupDao = contractAddress(
+  'The group: its own address (`dao` in chain_lookup daos or dao_proposals).',
+);
+const proposalModule = contractAddress(
+  'The group’s proposal list the step acts on (`proposalModule` in chain_lookup dao_proposals, or a `proposalLists` entry in daos); never the group’s own address.',
+);
+const groupProposalId = z
+  .string()
+  .regex(
+    GROUP_PROPOSAL_ID,
+    'The proposal number: digits from 1, no leading zeros (the `id`, not the label such as A3).',
+  )
+  // zod runs every check: a value the pattern refused is not parsed here.
+  .refine(
+    (value) =>
+      !GROUP_PROPOSAL_ID.test(value) ||
+      BigInt(value) <= BigInt(Number.MAX_SAFE_INTEGER),
+    { message: `At most ${Number.MAX_SAFE_INTEGER}.` },
+  )
+  .describe(
+    'The proposal’s number in its proposal list (`id` in chain_lookup dao_proposals, not the label).',
+  );
+/** Text published on chain with a group step: plain and shown exactly as written. */
+const groupText = (max: number, what: string) =>
+  plainText(max, what).refine(shownAsIs, { message: SHOWN_AS_IS });
+/** `dao` and `proposalModule` are two different contracts (the protocol names `proposalModule`). */
+function twoContracts(
+  message: { dao: string; proposalModule: string },
+  ctx: z.RefinementCtx,
+): void {
+  if (message.proposalModule === message.dao)
+    ctx.addIssue({
+      code: 'custom',
+      path: ['proposalModule'],
+      message:
+        'The proposal list, a different address than the group’s own (`dao`).',
+    });
+}
+
+/**
+ * What a group proposal's action may be, by type: exactly the top-level
+ * message of that type (same fields, same rules), with the group's own
+ * account as the actor. A dates change names both dates: a date left out
+ * would be read now and be out of date when the group carries it out.
+ */
+const GROUP_ACTION_SCHEMAS = {
+  'cosmos.bank.send': OWNER_CATALOG['cosmos.bank.send'].schema,
+  'ixo.token.transfer': OWNER_CATALOG['ixo.token.transfer'].schema,
+  'ixo.token.retire': OWNER_CATALOG['ixo.token.retire'].schema,
+  'cosmos.staking.delegate': OWNER_CATALOG['cosmos.staking.delegate'].schema,
+  'cosmos.staking.undelegate':
+    OWNER_CATALOG['cosmos.staking.undelegate'].schema,
+  'cosmos.staking.redelegate':
+    OWNER_CATALOG['cosmos.staking.redelegate'].schema,
+  'cosmos.distribution.withdraw-rewards':
+    OWNER_CATALOG['cosmos.distribution.withdraw-rewards'].schema,
+  'cosmos.gov.vote': OWNER_CATALOG['cosmos.gov.vote'].schema,
+  'ixo.claims.update-collection-state':
+    OWNER_CATALOG['ixo.claims.update-collection-state'].schema,
+  'ixo.claims.update-collection-dates': z
+    .strictObject({
+      type: z.literal('ixo.claims.update-collection-dates'),
+      collectionId,
+      adminAddress,
+      startDate: instant('When it opens (always given in a group proposal).'),
+      endDate: instant(
+        'When it closes; null: no end date (always given in a group proposal).',
+      ).nullable(),
+    })
+    .superRefine(endAfterStart),
+  'ixo.claims.update-collection-quota':
+    OWNER_CATALOG['ixo.claims.update-collection-quota'].schema,
+  'ixo.claims.create-collection':
+    OWNER_CATALOG['ixo.claims.create-collection'].schema,
+  'ixo.entity.create-account':
+    OWNER_CATALOG['ixo.entity.create-account'].schema,
+  'ixo.entity.revoke-account-authz':
+    OWNER_CATALOG['ixo.entity.revoke-account-authz'].schema,
+} as const satisfies Record<ChainTxGroupActionType, z.ZodObject>;
+
+/** The action types a group proposal may hold, in the protocol's order. */
+export const GROUP_ACTION_TYPES: readonly ChainTxGroupActionType[] =
+  CHAIN_TX_GROUP_ACTION_TYPES;
+
+const [firstGroupAction, ...otherGroupActions] = GROUP_ACTION_TYPES.map(
+  (type) => GROUP_ACTION_SCHEMAS[type],
+);
+if (!firstGroupAction)
+  throw new Error('The protocol lists no group action types');
+/**
+ * One action of a new group proposal: its `type` picks the schema. A type a
+ * group cannot do is refused on `actions[j].type`, as the protocol does.
+ */
+export const GROUP_ACTION_SCHEMA = z.discriminatedUnion(
+  'type',
+  [firstGroupAction, ...otherGroupActions],
+  {
+    error: `A group proposal can only hold these actions: ${GROUP_ACTION_TYPES.join(', ')}.`,
+  },
+);
+
+/** Said once for the four group steps. */
+const GROUP_RULES =
+  'A group here is a DAO DAO group on the IXO network (people say group, club, cooperative or DAO). Find it and its proposals with chain_lookup dao_proposals (`dao`, `proposalModule`, `id`, `label`, title, status, when voting closes) or chain_lookup daos (the person’s groups and, per group, `proposalLists` for new proposals). Copy `dao`, `proposalModule` and `proposalId` exactly from there: `dao` is the group’s own address, `proposalModule` its proposal list (a different address), `proposalId` the number without the list’s letter. Auth Hub checks the group and its proposal on chain and refuses what the group does not allow. One group step per card: nothing else goes on the same card. Only single-choice proposals are supported (not multiple choice). The review card may ask the owner to confirm twice: in the groups in use today one admin account can change how the group works without a vote, and the card says so. If the owner asks why, explain that calmly in one sentence; it is how these groups are set up, not a problem with this card.';
+
+const GROUP_CATALOG = {
+  'daodao.proposal.vote': {
+    summary:
+      'vote yes, no or abstain on a proposal in a group (DAO) the owner belongs to.',
+    rules: `${GROUP_RULES} Records the owner’s vote on one group proposal while its voting is open (\`votingEnded\` absent in dao_proposals). Before asking how they vote, tell the owner the proposal’s title and label and when voting closes, and whether they can change the vote later (\`allowRevoting\`); never vote without the owner saying how, in this conversation. \`vote\`: \`yes\`, \`no\` or \`abstain\`. \`rationale\` is optional: the owner’s reason, published with the vote, up to 300 characters, exactly as they said it (no links, no hidden characters, one line). The weight of the vote is what the owner had in the group when the proposal started: Auth Hub refuses the card when they had none, and when they already voted on a proposal that doesn’t allow changing a vote. A vote on a proposal whose result is already decided is still recorded until voting closes, but can’t change the result. Say it like: “Vote Yes on proposal A3, ‘Fix the borehole’, in Clean Water Group. This group doesn’t let you change your vote later.”`,
+    schema: z
+      .strictObject({
+        type: z.literal('daodao.proposal.vote'),
+        dao: groupDao,
+        proposalModule,
+        proposalId: groupProposalId,
+        vote: z
+          .literal([...CHAIN_TX_GROUP_VOTE_OPTIONS])
+          .describe('yes, no or abstain.'),
+        rationale: groupText(
+          300,
+          'Optional: the owner’s reason, published with the vote.',
+        ).optional(),
+      })
+      .superRefine(twoContracts),
+  },
+  'daodao.proposal.execute': {
+    summary:
+      'carry out a group proposal that passed, so the group’s own account does what it says.',
+    rules: `${GROUP_RULES} Carries out a proposal that passed (\`canRun\` in dao_proposals): the group’s own account then does the proposal’s actions, which the review card lists. On a proposal list the group switched off (\`listDisabled\`), a proposal with actions can’t be carried out. Only when the owner asks for it. Tell them what the proposal does (its title) before preparing. Some groups let only members carry proposals out. Auth Hub tries it first and refuses the card when the actions would fail now (in most groups a failed run marks the proposal failed for good), for example when the group doesn’t hold enough; tell the owner it can be tried again once that is fixed. It costs the owner only the network fee; a deposit paid with the proposal goes back to whoever proposed it unless the group keeps deposits (the review card says). After it goes through (hub_action_status), read the receipt’s \`groupActions\`: \`"failed"\` means the proposal’s actions did not happen and it can’t be tried again; never say it is done. \`"unknown"\`: check its status with chain_lookup dao_proposals before saying anything. Say it like: “Carry out proposal A3, ‘Pay Thandi’, in Clean Water Group: the group sends Thandi 500 IXO. This can’t be undone.”`,
+    schema: z
+      .strictObject({
+        type: z.literal('daodao.proposal.execute'),
+        dao: groupDao,
+        proposalModule,
+        proposalId: groupProposalId,
+      })
+      .superRefine(twoContracts),
+  },
+  'daodao.proposal.close': {
+    summary:
+      'close a group proposal that did not pass (its actions will never happen).',
+    rules: `${GROUP_RULES} Closes a proposal that did not pass (\`canClose\` in dao_proposals): none of its actions will happen. Only when the owner asks for it. Closing does not give its deposit back to whoever proposed it: in most groups the deposit goes to the group (the review card says where it goes); say so. Say it like: “Close proposal A3 in Clean Water Group. It didn’t pass, so nothing in it will happen; its 1 IXO deposit goes to the group, not back to whoever proposed it.”`,
+    schema: z
+      .strictObject({
+        type: z.literal('daodao.proposal.close'),
+        dao: groupDao,
+        proposalModule,
+        proposalId: groupProposalId,
+      })
+      .superRefine(twoContracts),
+  },
+  'daodao.proposal.create': {
+    summary:
+      'ask a group (DAO) to vote on a new proposal: agreement only, or up to 4 things the group’s own account then does.',
+    rules: `${GROUP_RULES} Asks the group to vote on a new proposal from the owner. Never propose without the owner asking for it and agreeing to the exact title, description and actions. \`proposalModule\` is one of the group’s \`proposalLists\` in chain_lookup daos (use one that is not \`disabled\` and whose \`deposit\` a card can pay; \`membersOnly: true\`: only members may propose). \`title\` (up to 100 characters) and \`description\` (up to 300) are published as written: plain text on one line, no links, no hidden characters. \`actions\` is what the group’s own account does if the proposal passes: \`[]\` asks for agreement only; otherwise up to ${CHAIN_TX_MAX_GROUP_ACTIONS} actions, each written exactly like a top-level message of its type (describe that type too), of these types only: ${GROUP_ACTION_TYPES.join(', ')}. In an action the group is the actor, not the owner: a coin send goes from the group’s own account (\`dao\`; check what it holds with chain_lookup balances for that address), a stake stakes the group’s IXO, a collection change needs a permission given to the group’s address, a new collection or an entity account needs an entity the group owns, and a collection dates change gives both \`startDate\` and \`endDate\` (null = no end). Amounts are display units as at top level (IXO by default; another token only one listed in hub_action_options \`transfer.tokens\`, for its decimals); the owner’s own balance is not used. The network checks each action only when the group carries the proposal out, possibly days later; if one fails then, none happen. When the group takes a deposit, it comes from the owner’s wallet: say how much, and that it may be lost if the proposal doesn’t pass or is never carried out (it comes back only as the group’s refund rule says, \`refundPolicy\` in daos). A proposal can’t be withdrawn once made. Once it went through (hub_action_status), the receipt names the new proposal’s number (\`proposalId\`); when it is null, find the new proposal with chain_lookup dao_proposals and never guess its number. Say it like: “Propose to Clean Water Group: ‘Pay Thandi for the borehole repair’. If it passes, the group sends her 500 IXO; proposing costs you a 1 IXO deposit, which you get back only if it passes and is carried out.”`,
+    schema: z
+      .strictObject({
+        type: z.literal('daodao.proposal.create'),
+        dao: groupDao,
+        proposalModule,
+        title: groupText(100, 'The proposal’s title, as published.'),
+        description: groupText(
+          300,
+          'What the proposal asks, as published (one line).',
+        ),
+        actions: z
+          .array(GROUP_ACTION_SCHEMA)
+          .max(CHAIN_TX_MAX_GROUP_ACTIONS)
+          .describe(
+            `What the group’s own account does if it passes: [] for agreement only, or up to ${CHAIN_TX_MAX_GROUP_ACTIONS} actions, each a message of one of: ${GROUP_ACTION_TYPES.join(', ')}.`,
+          ),
+      })
+      .superRefine(twoContracts),
+  },
+} as const satisfies Record<ChainTxGroupMessageType, ChainTxCatalogEntry>;
+
+/**
+ * The catalogue: every message type the protocol knows, the owner's own
+ * types first, then the four group steps (the protocol's order).
+ */
+export const CHAIN_TX_CATALOG = {
+  ...OWNER_CATALOG,
+  ...GROUP_CATALOG,
 } as const satisfies Record<ChainTxMessageType, ChainTxCatalogEntry>;
 
 /** What every message type shares, returned once by describe_chain_messages. */
 export const CHAIN_TX_GENERAL_RULES = [
-  'Addresses are 20-byte `ixo1…` account addresses (contract addresses are refused), validators `ixovaloper1…`, entities `did:ixo:entity:…`. Copy every id, address and number exactly from a lookup (chain_lookup, hub_action_options) or from the owner; never invent or guess one. Ids (`claimId`, `collectionId`, token `id`, proofs) use only letters, digits and `: . _ / -`.',
+  'Addresses are 20-byte `ixo1…` account addresses (contract addresses are refused), except a group’s own address and its proposal list in the group steps (32-byte `ixo1…` contract addresses); validators `ixovaloper1…`, entities `did:ixo:entity:…`. Copy every id, address and number exactly from a lookup (chain_lookup, hub_action_options) or from the owner; never invent or guess one. Ids (`claimId`, `collectionId`, token `id`, proofs) use only letters, digits and `: . _ / -`.',
   'Give only the fields listed for a type: the runtime adds the chain, the network, the signer and the owner’s own DID and address where a message needs them, and Auth Hub sets the fee. Amounts: coin sends and stakes are what the owner says in the token’s units ("100" IXO); impact tokens are whole tokens; collection payments are base units (1 IXO = 1000000 uixo). Dates are RFC 3339 with Z or an offset, from the owner’s time zone.',
-  `Up to ${CHAIN_TX_MAX_MESSAGES} messages per transaction, run in the order given (put them in the order the owner said them, and keep one decision in one card); all succeed or none do. A step that needs something stored first (a dispute statement, a profile, a document) can only be prepared once it is stored.`,
-  'How to talk about it: before preparing, say in one or two plain, everyday sentences what will happen and what it means for the owner (what leaves their wallet, what someone else will be able to do, how long it takes, whether it can be undone), the way each type’s “Say it like” does. Use names (of the validator, collection, entity or person) when a lookup gives them. Never say message type names or chain words such as authz, grant, MsgExec, bech32, valoper, uixo, base units, DID, IID, delegate or redelegate: say stake, unstake, move stake, permission, account, identity and IXO. Show an address only when the owner needs it to check who receives something. The review card in Auth Hub shows every exact value.',
+  `Up to ${CHAIN_TX_MAX_MESSAGES} messages per transaction, run in the order given (put them in the order the owner said them, and keep one decision in one card); all succeed or none do. A group step (a vote, carrying out or closing a group proposal, a new group proposal) goes alone on its card. A step that needs something stored first (a dispute statement, a profile, a document) can only be prepared once it is stored.`,
+  'How to talk about it: before preparing, say in one or two plain, everyday sentences what will happen and what it means for the owner (what leaves their wallet, what someone else will be able to do, how long it takes, whether it can be undone), the way each type’s “Say it like” does. Use names (of the validator, collection, entity or person) when a lookup gives them. Never say message type names or chain words such as authz, grant, MsgExec, bech32, valoper, uixo, base units, DID, IID, delegate, redelegate, DAO, proposal module, contract or execute: say stake, unstake, move stake, permission, account, identity, IXO, group, proposal, vote, deposit and carry out. Show an address only when the owner needs it to check who receives something. The review card in Auth Hub shows every exact value.',
 ].join(' ');
 
 /** A catalogue message as its schema parses it. */

package/src/plugins/hub-actions/hub-actions.plugin.ts

@@ -1,4 +1,5 @@
 import {
+  CHAIN_TX_GROUP_MESSAGE_TYPES,
   CHAIN_TX_MAX_MESSAGES,
   CHAIN_TX_MESSAGE_TYPES,
   operationJsonSchema,
@@ -30,6 +31,8 @@ import { toolNotRunMessage } from '../../core/tool-not-run';
 import {
   CHAIN_TX_CATALOG,
   CHAIN_TX_GENERAL_RULES,
+  GROUP_ACTION_SCHEMA,
+  GROUP_ACTION_TYPES,
   chainTxMessageInput,
   hasUnsafeText,
 } from './chain-tx-catalog';
@@ -100,22 +103,38 @@ const memoSchema = z
 /**
  * A catalogue field reduced to its basic type: no descriptions, patterns or
  * limits (those stay in describe_chain_messages and the handler's check).
+ * A union of message types (a new group proposal's `actions`) is given as
+ * `typeUnion` gives the messages themselves: fields only for the types in
+ * `described`.
  */
-export function fieldsOnly(schema: z.core.$ZodType): z.ZodType {
+export function fieldsOnly(
+  schema: z.core.$ZodType,
+  described?: ReadonlySet<string>,
+): z.ZodType {
   if (schema instanceof z.ZodObject)
     return z.strictObject(
       Object.fromEntries(
         Object.entries(schema.shape).map(([key, field]) => [
           key,
-          fieldsOnly(field),
+          fieldsOnly(field, described),
         ]),
       ),
     );
   if (schema instanceof z.ZodOptional)
-    return fieldsOnly(schema.unwrap()).optional();
+    return fieldsOnly(schema.unwrap(), described).optional();
   if (schema instanceof z.ZodNullable)
-    return fieldsOnly(schema.unwrap()).nullable();
-  if (schema instanceof z.ZodArray) return z.array(fieldsOnly(schema.element));
+    return fieldsOnly(schema.unwrap(), described).nullable();
+  if (schema instanceof z.ZodArray)
+    return z.array(fieldsOnly(schema.element, described));
+  if (schema instanceof z.ZodDiscriminatedUnion)
+    return typeUnion(
+      schema.options.map((option) => {
+        if (!(option instanceof z.ZodObject))
+          throw new Error('A message union holds a non-object branch');
+        return [messageTypeOf(option), option] as const;
+      }),
+      described,
+    );
   if (schema instanceof z.ZodString) return z.string();
   if (schema instanceof z.ZodNumber) return z.number();
   if (schema instanceof z.ZodBoolean) return z.boolean();
@@ -125,42 +144,51 @@ export function fieldsOnly(schema: z.core.$ZodType): z.ZodType {
   );
 }
 
+/** The `type` a catalogue message schema is for (its `type` literal). */
+function messageTypeOf(schema: z.ZodObject): string {
+  const type = schema.shape.type;
+  const [value] = type instanceof z.ZodLiteral ? [...type.values] : [];
+  if (typeof value !== 'string')
+    throw new Error('A catalogue message schema has no `type` literal');
+  return value;
+}
+
 /**
  * One message type as the model is given it: its field names and basic
  * types, so a provider that holds a tool call to its schema sends every
  * field. Loose, so a field the type does not have reaches the handler,
  * which names it.
  */
-function messageFieldsOnly(schema: z.ZodObject) {
+function messageFieldsOnly(
+  schema: z.ZodObject,
+  described?: ReadonlySet<string>,
+) {
   return z.looseObject(
     Object.fromEntries(
       Object.entries(schema.shape).map(([key, field]) => [
         key,
-        fieldsOnly(field),
+        fieldsOnly(field, described),
       ]),
     ),
   );
 }
 
 /**
- * The schema the model is given: per type its fields (messageFieldsOnly)
- * when the type was described in this session (`described`; absent: every
- * type), and one open branch naming every other type (`type` one of them,
- * any other field allowed). A type the model has not read about costs its
- * name only; the request handler refuses it until it is described, and
- * the next model call is given its fields (`chainTxFieldsMiddleware`).
- * Each message is checked by the handler against its full catalogue
- * schema.
+ * Messages as the model is given them: per type its fields
+ * (messageFieldsOnly) when the type was described in this session
+ * (`described`; absent: every type), and one open branch naming every
+ * other type (`type` one of them, any other field allowed). A union inside
+ * a message (a new group proposal's `actions`) takes `nested` instead.
  */
-export function chainTransactionSchemaFor(
-  catalog: Readonly<Record<string, { schema: z.ZodObject }>>,
+function typeUnion(
+  schemas: readonly (readonly [string, z.ZodObject])[],
   described?: ReadonlySet<string>,
+  nested: ReadonlySet<string> | undefined = described,
 ) {
-  const entries = Object.entries(catalog);
-  const withFields = entries
+  const withFields = schemas
     .filter(([type]) => !described || described.has(type))
-    .map(([, entry]) => messageFieldsOnly(entry.schema));
-  const [firstUnread, ...unread] = entries
+    .map(([, schema]) => messageFieldsOnly(schema, nested));
+  const [firstUnread, ...unread] = schemas
     .filter(([type]) => described && !described.has(type))
     .map(([type]) => type);
   const branches =
@@ -172,9 +200,36 @@ export function chainTransactionSchemaFor(
         ];
   const [first, ...rest] = branches;
   if (!first) throw new Error('The chain transaction catalogue is empty');
+  return z.discriminatedUnion('type', [first, ...rest]);
+}
+
+/**
+ * The schema the model is given: the messages as `typeUnion` gives them,
+ * a new group proposal's actions the same way. A type the model has not
+ * read about costs its name only; the request handler refuses it until it
+ * is described, and the next model call is given its fields
+ * (`chainTxFieldsMiddleware`). Without a session store (`described`
+ * absent) every message type carries its fields, but a new proposal's
+ * actions are named only: the 14 action types' fields would repeat their
+ * top-level branches (26 228 characters instead of 20 950); the
+ * handler names any field it misses. Each message is checked by the
+ * handler against its full catalogue schema.
+ */
+export function chainTransactionSchemaFor(
+  catalog: Readonly<Record<string, { schema: z.ZodObject }>>,
+  described?: ReadonlySet<string>,
+) {
   return z.strictObject({
     messages: z
-      .array(z.discriminatedUnion('type', [first, ...rest]))
+      .array(
+        typeUnion(
+          Object.entries(catalog).map(
+            ([type, entry]) => [type, entry.schema] as const,
+          ),
+          described,
+          described ?? new Set<string>(),
+        ),
+      )
       .min(1)
       .max(CHAIN_TX_MAX_MESSAGES),
     memo: memoSchema,
@@ -649,7 +704,10 @@ async function requestChainTransaction(
     const unread = [
       ...new Set(
         parsed.data.messages
-          .map(chainTxTypeOf)
+          .flatMap((message) => [
+            chainTxTypeOf(message),
+            ...groupActionTypesOf(message),
+          ])
           .filter(
             (type): type is ChainTxMessageType =>
               type !== null && !described.includes(type),
@@ -719,6 +777,19 @@ function strictChainTxMessages(
 ): { messages: ChainTxMessageInput[] } | { issues: string[] } {
   const checked: ChainTxMessageInput[] = [];
   const issues: string[] = [];
+  // A group step is a chain of reads in Auth Hub and names a new
+  // proposal's number on its receipt: it goes alone on its card (the
+  // protocol refuses `messages` otherwise).
+  if (
+    messages.length > 1 &&
+    messages.some((message) => {
+      const type = chainTxTypeOf(message);
+      return type !== null && GROUP_STEP_TYPES.includes(type);
+    })
+  )
+    issues.push(
+      'messages: a group step (a group vote, carrying out or closing a group proposal, a new group proposal) goes alone on its card; prepare the other messages on another card',
+    );
   messages.forEach((message, index) => {
     const type = chainTxTypeOf(message);
     if (!type) {
@@ -739,6 +810,31 @@ function chainTxTypeOf(message: unknown): ChainTxMessageType | null {
   return CHAIN_TX_MESSAGE_TYPES.find((known) => known === type) ?? null;
 }
 
+const GROUP_STEP_TYPES: readonly ChainTxMessageType[] =
+  CHAIN_TX_GROUP_MESSAGE_TYPES;
+
+/**
+ * The action types a new group proposal holds (each a type a group may
+ * do): their rules are read like a top-level message's before the card.
+ * Anything else is left to the message's own check.
+ */
+function groupActionTypesOf(message: unknown): ChainTxMessageType[] {
+  if (
+    chainTxTypeOf(message) !== 'daodao.proposal.create' ||
+    typeof message !== 'object' ||
+    message === null ||
+    !('actions' in message) ||
+    !Array.isArray(message.actions)
+  )
+    return [];
+  return message.actions
+    .map(chainTxTypeOf)
+    .filter(
+      (type): type is ChainTxMessageType =>
+        type !== null && GROUP_ACTION_TYPES.some((allowed) => allowed === type),
+    );
+}
+
 function chainTxShapeRefusal(
   issues: readonly string[],
 ): HubActionRequestResult {
@@ -784,10 +880,11 @@ function issuesOf(
 
 /**
  * The catalogue types this account may use: the Hub capabilities'
- * `chainTx.messageTypes`. None when chain transactions cannot be used
+ * `chainTx.messageTypes`, which follow the protocol level the Hub speaks
+ * with this runtime (level 5: the four 0.6.0 types; 6: 33; 7: all 37, the
+ * four group steps included). None when chain transactions cannot be used
  * here: not a channel turn, Hub actions off, chain transactions off for the
- * account, a Hub at protocol level 5 (the 0.6.0 types only, as it lists
- * them), or capabilities that cannot be read (the owner object answers its
+ * account, or capabilities that cannot be read (the owner object answers its
  * last good capabilities while a read fails, and does not retry a failed
  * read for 30 s, so this never holds a turn for long).
  */
@@ -815,6 +912,19 @@ async function availableChainTxTypes(
   );
 }
 
+/**
+ * A new group proposal's action as describe_chain_messages lists it: the
+ * types it may be, each with its own fields (described on its own), so one
+ * description does not repeat fourteen others.
+ */
+const GROUP_ACTION_FIELDS = {
+  type: 'object',
+  description:
+    'One message of the types listed in `type`, with exactly that type’s fields (describe_chain_messages that type); the group’s own account is its actor.',
+  properties: { type: { type: 'string', enum: [...GROUP_ACTION_TYPES] } },
+  required: ['type'],
+};
+
 /** Each type's fields as JSON Schema, built once. */
 const catalogueFields = new Map<ChainTxMessageType, unknown>();
 function fieldsOf(type: ChainTxMessageType): unknown {
@@ -822,6 +932,14 @@ function fieldsOf(type: ChainTxMessageType): unknown {
   if (fields === undefined) {
     const { properties, required } = z.toJSONSchema(
       CHAIN_TX_CATALOG[type].schema,
+      {
+        override: ({ zodSchema, jsonSchema }) => {
+          if (zodSchema !== GROUP_ACTION_SCHEMA) return;
+          for (const key of Object.keys(jsonSchema))
+            Reflect.deleteProperty(jsonSchema, key);
+          Object.assign(jsonSchema, GROUP_ACTION_FIELDS);
+        },
+      },
     );
     fields = { properties, required };
     catalogueFields.set(type, fields);
@@ -914,6 +1032,45 @@ export function modelOutcome(
 export const CANCELLED_MEANING =
   'Withdrawn before anything was sent: nothing happened on chain. The person may have cancelled it, or Auth Hub withdrew it because something it depended on changed after the review; do not say the person cancelled it. If they still want it, offer to prepare a fresh one.';
 
+/**
+ * A carried-out group proposal whose actions failed: the transaction
+ * succeeds (code 0) even then, and the network marks the proposal failed
+ * for good, so the receipt's `groupActions` is the only sign.
+ */
+export const GROUP_ACTIONS_FAILED_MEANING =
+  'The transaction went through, but the proposal’s actions failed: nothing in the proposal happened, the network has marked it failed for good and it can’t be carried out again. The network fee was used unless a fee grant covered it. Never say it is done; tell the person plainly.';
+
+/** A carried-out group proposal whose transaction did not show whether its actions ran. */
+export const GROUP_ACTIONS_UNKNOWN_MEANING =
+  'The transaction went through, but Auth Hub could not tell from it whether the proposal’s actions happened. Check the proposal’s status with chain_lookup dao_proposals (executed: they happened; execution_failed: they did not) before saying anything about it; never say it is done until then.';
+
+/** A new group proposal whose number Auth Hub could not read from the transaction. */
+export const PROPOSAL_NUMBER_UNKNOWN_MEANING =
+  'The new proposal was made, but Auth Hub could not read its number from the transaction. Find the new proposal with chain_lookup dao_proposals (the group’s newest) before naming it; never guess its number.';
+
+/**
+ * What an outcome means beyond its fields, for the model: a withdrawn card,
+ * a carried-out proposal whose actions failed or may have, a new proposal
+ * without its number. Undefined for anything else.
+ */
+export function outcomeMeaning(
+  outcome: ActionOutcomeV1 | null,
+): string | undefined {
+  if (!outcome) return undefined;
+  if (outcome.status === 'cancelled') return CANCELLED_MEANING;
+  const receipt = outcome.receipt;
+  if (receipt?.kind !== 'ixo.chain.tx.v1') return undefined;
+  for (const step of receipt.steps) {
+    if (step.type === 'daodao.proposal.execute') {
+      if (step.groupActions === 'failed') return GROUP_ACTIONS_FAILED_MEANING;
+      if (step.groupActions === 'unknown') return GROUP_ACTIONS_UNKNOWN_MEANING;
+    }
+    if (step.type === 'daodao.proposal.create' && step.proposalId === null)
+      return PROPOSAL_NUMBER_UNKNOWN_MEANING;
+  }
+  return undefined;
+}
+
 async function hubActionStatus(
   input: unknown,
   ctx: RuntimeContext,
@@ -935,15 +1092,14 @@ async function hubActionStatus(
         status: 'unavailable',
         reason: 'No Hub action with this id was prepared for this owner.',
       };
+    const meaning = outcomeMeaning(read.outcome);
     return {
       status: 'known',
       reviewStatus: read.reviewStatus,
       operationStatus: read.operationStatus,
       outcome: modelOutcome(read.outcome),
       ...(read.summary ? { summary: read.summary } : {}),
-      ...(read.outcome?.status === 'cancelled'
-        ? { meaning: CANCELLED_MEANING }
-        : {}),
+      ...(meaning ? { meaning } : {}),
     };
   } catch (error) {
     // An Auth Hub that must be updated first: plain words, not a tool error.
@@ -1012,6 +1168,7 @@ const manifest: PluginManifest = {
     'The user asks to file or evaluate a claim, or to send coins or impact tokens on chain.',
     'The user asks to stake, unstake or move IXO, claim staking rewards, vote on a network proposal or retire impact tokens.',
     'The user asks to reserve or dispute a claim, create or change a claim collection, give or remove a permission, create or update an entity, or change the links of an identity.',
+    'The user asks to vote on a proposal of a group (DAO) they belong to, carry out or close a group proposal, or put a new proposal to a group.',
     'The user asks to review an exact private resource or to sign a statement.',
     'The user asks to connect Gmail or Calendar, send a reviewed email or add an event.',
     'The user asks for document access or to save a private note.',
@@ -1043,7 +1200,7 @@ export class HubActionsPlugin extends OraclePlugin {
   /**
    * request_chain_transaction is built per turn: its schema names only the
    * message types this account may use (Auth Hub capabilities, cached by
-   * the owner object), so 33 types do not reach a model that may use 4.
+   * the owner object), so 37 types do not reach a model that may use 4.
    */
   override async getRequestTools(ctx: RuntimeContext): Promise<PluginTool[]> {
     const [available, described] = await Promise.all([
@@ -1093,7 +1250,7 @@ export class HubActionsPlugin extends OraclePlugin {
       {
         name: 'hub_action_status',
         description:
-          'Read the verified status of a Hub action already prepared for this owner. Never executes. A `cancelled` outcome was withdrawn before anything was sent, by the person or by Auth Hub (`meaning` says so): never say the person cancelled it.',
+          'Read the verified status of a Hub action already prepared for this owner. Never executes. A `cancelled` outcome was withdrawn before anything was sent, by the person or by Auth Hub (`meaning` says so): never say the person cancelled it. When `meaning` is present, it says what the outcome means for the person (for example a carried-out group proposal whose actions failed): follow it.',
         schema: statusSchema,
         effect: 'read',
         handler: hubActionStatus,