@kubun/plugin-p2p 0.15.0 → 0.16.0

package/lib/groups/did-cache-seed.d.ts

@@ -0,0 +1,26 @@
+import { type DIDCache } from '@kokuin/token';
+import type { StoreProvider } from '@kubun/db';
+import type { Logger } from '@kubun/logger';
+import type { GroupHandleRegistry } from './group-handle-registry.js';
+export type SeedDIDCacheParams = {
+    cache: DIDCache;
+    registry: GroupHandleRegistry;
+    groupID: string;
+    stores?: StoreProvider;
+    logger?: Logger;
+};
+/**
+ * Seed the shared DID cache with every `did:peer:4` co-member's document, read
+ * off the MLS roster's authenticated leaf long forms.
+ *
+ * A co-member's short-form `iss` on a peer-lane token carries no document, so a
+ * freshly-spawned tunnel/sync Server cannot resolve it without this. The roster
+ * leaf is the one authenticated source of the long form — the membership row
+ * holds only the normalized short form, which carries none.
+ *
+ * Monotonic and idempotent: a peer:4 doc is content-addressed, so re-seeding an
+ * existing entry is a no-op and a departed member's lingering doc is harmless
+ * (per-scope authorization gates access downstream, not cache presence). So the
+ * membership-change seam only ever adds, never evicts.
+ */
+export declare function seedDIDCacheFromRoster(params: SeedDIDCacheParams): Promise<void>;

package/lib/groups/did-cache-seed.js

@@ -0,0 +1,38 @@
+import { decodePeer4, isPeer4 } from '@kokuin/token';
+/**
+ * Seed the shared DID cache with every `did:peer:4` co-member's document, read
+ * off the MLS roster's authenticated leaf long forms.
+ *
+ * A co-member's short-form `iss` on a peer-lane token carries no document, so a
+ * freshly-spawned tunnel/sync Server cannot resolve it without this. The roster
+ * leaf is the one authenticated source of the long form — the membership row
+ * holds only the normalized short form, which carries none.
+ *
+ * Monotonic and idempotent: a peer:4 doc is content-addressed, so re-seeding an
+ * existing entry is a no-op and a departed member's lingering doc is harmless
+ * (per-scope authorization gates access downstream, not cache presence). So the
+ * membership-change seam only ever adds, never evicts.
+ */ export async function seedDIDCacheFromRoster(params) {
+    const { cache, registry, groupID, stores, logger } = params;
+    const members = await registry.readHandle(groupID, (handle)=>handle.listMembers(), stores == null ? undefined : {
+        stores
+    });
+    for (const member of members){
+        // did:key members resolve natively; only a genuine peer:4 long form (≠ the
+        // short-form `id`) carries a document worth caching.
+        if (!isPeer4(member.longForm) || member.longForm === member.id) {
+            continue;
+        }
+        try {
+            const { shortForm, doc } = decodePeer4(member.longForm);
+            await cache.set(shortForm, doc);
+        } catch (error) {
+            // A single unparseable leaf must not abort seeding the rest of the roster.
+            logger?.warn('did-cache roster seed skipped a member', {
+                groupID,
+                id: member.id,
+                error
+            });
+        }
+    }
+}

package/lib/groups/group-crypto.d.ts

@@ -6,26 +6,25 @@ import type { GroupHandleRegistry } from './group-handle-registry.js';
  * port: epoch, an epoch-bound topic-derivation secret, and byte-level
  * encrypt/decrypt over the live MLS handle.
  *
- * `wrap`/`unwrap`/`exportSecret` route through `registry.readHandle`, taking the
- * per-group mutex and observing the canonical handle, framed as in
- * `mls-codec.ts`. `exportSecret` passes the caller's label through untouched:
- * the labels belong to the package deriving topics from the result, so
- * substituting one moves every topic ID away from what the caller addressed.
+ * `wrap`/`unwrap`/`exportSecret` route through `registry.readHandle`, under the
+ * per-group mutex, framed as in `mls-codec.ts`. `exportSecret` passes the
+ * caller's label through untouched: the labels belong to the package deriving
+ * topics from the result, so substituting one moves every topic ID away from
+ * what the caller addressed.
  *
  * `sealEntries`/`openEntries` are a SECOND seal, NOT interchangeable with
  * `wrap`/`unwrap`: those consume a ratchet generation and mutate the handle, so
  * they cannot serve an open running inside the apply of the commit carrying the
  * blob. The bytes must match `@kumiai/mls-rpc` exactly — the seal is agreed
- * without exchange, so a divergence is not a decode error but a group whose
- * members silently stop reading each other's commits.
+ * without exchange, so a divergence silently stops members reading each other's
+ * commits rather than surfacing as a decode error.
  *
  * The epoch is READ FROM THE REGISTRY, never cached: applying someone else's
  * commit advances the handle without touching this file, and a stale number
  * classifies every later frame as `ahead`, so the cursor skips it forever.
  * `initialEpoch` covers only construction before the registry has observed a
  * handle — the caller MUST read the handle's epoch first, or a returning peer
- * answering `0` steps over every commit it missed. Construction is synchronous
- * and eager, leaving no window to prime it afterwards.
+ * answering `0` steps over every commit it missed.
  */
 export type GroupCryptoParams = {
     registry: GroupHandleRegistry;

package/lib/groups/group-crypto.js

@@ -10,20 +10,19 @@ import { mlsDecryptFramed, mlsEncryptFramed } from './mls-codec.js';
 // `@kumiai/mls-rpc` uses for the ledger-entry seal (`new Uint8Array()`), which is
 // what lets a blob sealed here open there.
 const TOPIC_SECRET_CONTEXT = new Uint8Array(0);
-// Default when a caller names no length. 32 bytes feeds an HKDF-based topic
-// derivation; the length is otherwise unconstrained. It is also XChaCha20-
-// Poly1305's key size, and the same 32 the ledger-entry seal exports at — RFC
-// 9420 §8.5 binds the length into the exporter's KDFLabel, so deriving this from
-// the ciphersuite instead would return 48 on SHA-384 and break every seal.
+// Default when a caller names no length. 32 feeds the HKDF topic derivation, is
+// XChaCha20-Poly1305's key size, and is what the ledger-entry seal exports at.
+// Fixed, not ciphersuite-derived: RFC 9420 §8.5 binds the length into the
+// exporter's KDFLabel, so 48 on SHA-384 would break every seal.
 const DEFAULT_SECRET_LENGTH = 32;
 // XChaCha20-Poly1305's nonce, carried in the clear ahead of the ciphertext.
 const ENTRY_NONCE_BYTES = 24;
 // Sealed blob format version, first byte, in the clear:
 //   [ VERSION(1) | NONCE(24) | CIPHERTEXT ]
-// Unauthenticated by necessity — it is read to decide how to open, so it cannot
-// sit under the seal. It buys diagnosis, not compatibility: no v1 reader can open
-// a v2 blob either way, but the failure reads as "unsupported version" rather
-// than an AEAD refusal indistinguishable from a wrong epoch or a tampered frame.
+// Unauthenticated by necessity — read to decide how to open, so it cannot sit
+// under the seal. Buys diagnosis, not compatibility: a v2 blob fails a v1 reader
+// either way, but reads as "unsupported version" rather than an AEAD refusal
+// indistinguishable from a wrong epoch or a tampered frame.
 const ENTRY_VERSION = 1;
 export function createGroupCrypto(params) {
     const { registry, groupID, initialEpoch, runtime = createRuntime() } = params;
@@ -34,11 +33,10 @@ export function createGroupCrypto(params) {
             return await mlsExporter(handle.state.keySchedule.exporterSecret, ENTRY_SEAL_LABEL, TOPIC_SECRET_CONTEXT, DEFAULT_SECRET_LENGTH, handle.context.cipherSuite);
         });
     const exportSecret = (label, length)=>{
-        // Reusing the ledger-entry label would not be an independent export: it is
-        // the exact exporter call `sealEntries`/`openEntries` make (same context,
-        // same length), so it would hand back the ledger-entry seal key under
-        // another name and make every holder of a topic secret a reader of the
-        // group's control ledger. Refused here rather than left to the doc.
+        // Reusing the ledger-entry label is not an independent export: it is the
+        // exact exporter call `sealEntries`/`openEntries` make (same context, same
+        // length), so it would hand back the seal key under another name and make
+        // every holder of a topic secret a reader of the control ledger.
         if (label === ENTRY_SEAL_LABEL) {
             throw new Error(`exportSecret: label '${label}' is reserved for the ledger-entry seal`);
         }
@@ -51,52 +49,50 @@ export function createGroupCrypto(params) {
     // MLS state outside the per-group mutex. `initialEpoch` only covers the window
     // before the registry has observed a handle for this group.
     const epoch = ()=>registry.groupEpoch(groupID) ?? initialEpoch;
-    const wrap = (bytes)=>registry.readHandle(groupID, (handle)=>mlsEncryptFramed(handle, bytes));
+    const wrap = (bytes, opts)=>registry.readHandle(groupID, (handle)=>mlsEncryptFramed(handle, bytes, opts?.aad));
     // In-flight decrypt cache, keyed by the ciphertext bytes.
     //
-    // group-rpc subscribes TWO broadcast transports per app-protocol topic (the
-    // anycast `BroadcastClient` and the `busServer`) and the hub mux fans every
-    // frame to both, so `unwrap` runs twice in one synchronous burst. MLS
-    // decryption is single-use: `handle.decrypt` consumes a forward-secret ratchet
-    // generation, so the second call fails with "Desired gen in the past" and the
-    // frame never reaches its handler. Caching the in-flight promise per ciphertext
-    // makes `unwrap` idempotent — the first call advances the ratchet, the sibling
-    // (calling before it resolves) replays the plaintext. Entries drop once
-    // settled, so the map holds only concurrent in-flight decrypts and never an
-    // evicted pending one; distinct ciphertexts miss and decrypt normally, so
-    // forward secrecy across messages is preserved.
+    // group-rpc subscribes TWO broadcast transports per app-protocol topic and the
+    // hub mux fans every frame to both, so `unwrap` runs twice in one synchronous
+    // burst. MLS decryption is single-use: `handle.decrypt` consumes a
+    // forward-secret ratchet generation, so the second call fails and the frame
+    // never reaches its handler. Caching the in-flight promise per ciphertext makes
+    // `unwrap` idempotent — the sibling replays the plaintext instead. Entries drop
+    // once settled, so only concurrent in-flight decrypts are held; distinct
+    // ciphertexts miss and decrypt normally, preserving forward secrecy.
     //
-    // The replayed value carries an IDENTITY, not just bytes. That is sound only
-    // because the key is the ciphertext: one ciphertext at one epoch has exactly
-    // one MLS-authenticated sender, so a replay cannot attribute a frame to
-    // anyone but the leaf that sealed it.
+    // The replayed value carries an IDENTITY, not just bytes. Sound only because
+    // the key is the ciphertext: one ciphertext at one epoch has exactly one
+    // MLS-authenticated sender, so a replay cannot misattribute the frame.
     const unwrapCache = new Map();
-    const unwrap = (bytes)=>{
-        const key = toB64(bytes);
+    const unwrap = (bytes, opts)=>{
+        const expectedAAD = opts?.expectedAAD;
+        // Key on ciphertext AND expectedAAD: both siblings of the dedup'd frame carry
+        // the same expectedAAD, so they still collapse to one decrypt. Keying on the
+        // bytes alone would let the same ciphertext on a DIFFERENT topic reuse the
+        // first success, defeating the wrong-topic check the binding exists for.
+        const key = `${toB64(bytes)}:${expectedAAD == null ? '' : toB64(expectedAAD)}`;
         const cached = unwrapCache.get(key);
         if (cached != null) {
             return cached;
         }
         const promise = registry.readHandle(groupID, async (handle)=>{
-            const { payload, senderDID } = await mlsDecryptFramed(handle, bytes);
+            const { payload, senderDID } = await mlsDecryptFramed(handle, bytes, expectedAAD);
             return {
                 payload,
                 senderDID
             };
         });
-        // Drop the entry once it settles (success or failure): the sibling transport
-        // has already taken the in-flight promise, and a genuine failure must not be
-        // cached so a later valid frame with the same bytes (e.g. after a resync) can
-        // decrypt afresh.
+        // Drop the entry once it settles: the sibling has already taken the in-flight
+        // promise, and a genuine failure must not be cached so a later valid frame
+        // with the same bytes (e.g. after a resync) can decrypt afresh.
         //
         // `.finally()` returns a NEW promise that rejects with the same reason, so
-        // this cleanup branch needs a handler of its own. The caller handles the
-        // promise it was handed; without the catch here the derived one escapes as an
-        // unhandled rejection. Not an edge case: a frame this handle cannot open —
-        // another epoch's, another group's — is ordinary on a shared log, so the
-        // rejecting path is the common one. Only this branch is absorbed; the promise
-        // returned below still rejects to the caller, which is what decides the frame
-        // is dead.
+        // this cleanup branch needs its own handler or it escapes as an unhandled
+        // rejection — and a frame this handle cannot open (another epoch's, another
+        // group's) is ordinary on a shared log, so rejection is the common path. Only
+        // this branch is absorbed; the promise returned below still rejects to the
+        // caller, which is what decides the frame is dead.
         unwrapCache.set(key, promise);
         void promise.finally(()=>{
             unwrapCache.delete(key);
@@ -104,23 +100,23 @@ export function createGroupCrypto(params) {
         return promise;
     };
     // Reads the epoch every MLSMessage carries in its own cleartext. Needs no
-    // handle and no key, and must never throw: it is asked about every frame a log
-    // holds, most of which are not this member's to open. `null` for anything
-    // ts-mls will not decode, which is how a caller tells a frame sealed AHEAD
-    // (openable once it catches up) from one sealed BELOW (gone forever, since MLS
-    // ratchets forward) — the distinction the app lane's durable cursor rests on.
-    // Untrusted: it is the publisher's word relayed by an untrusted hub, so it may
-    // only decide what to TRY, never that bytes are authentic.
+    // handle or key and must never throw: it is asked about every frame a log
+    // holds, most not this member's to open. `null` for anything ts-mls will not
+    // decode, which lets a caller tell a frame sealed AHEAD (openable once it
+    // catches up) from one sealed BELOW (gone forever, since MLS ratchets forward)
+    // — the distinction the app lane's durable cursor rests on. Untrusted: the
+    // publisher's word via an untrusted hub, so it decides what to TRY, never that
+    // bytes are authentic.
     const frameEpoch = (bytes)=>{
         const epochValue = readMessageEpoch(bytes);
         return epochValue == null ? null : Number(epochValue);
     };
     // Seals the ledger-entry blob a Commit carries, under a key derived from this
     // epoch's exporter secret rather than the message ratchet `wrap` consumes.
-    // Derived-key sealing is what makes the open PURE, so it can run from inside
-    // the apply of the very commit whose blob it opens — the only place it runs,
-    // and one the ratchet-backed pair cannot serve. Byte format is fixed by
-    // `@kumiai/mls-rpc`; a one-byte drift is a group that silently partitions.
+    // Derived-key sealing makes the open PURE, so it can run inside the apply of
+    // the very commit whose blob it opens — the only place it runs, which the
+    // ratchet-backed pair cannot serve. Byte format is fixed by `@kumiai/mls-rpc`;
+    // a one-byte drift silently partitions the group.
     const sealEntries = async (bytes)=>{
         const key = await exportEntryKey();
         // Random per seal: two members can frame a commit at the same epoch, and a

package/lib/groups/group-handlers.d.ts

@@ -1,9 +1,10 @@
 import type { ProcedureHandlers } from '@enkaku/server';
+import type { WorkflowAPI } from '@kubun/plugin-workflow-api';
 import type { ProcessBroadcastParams } from './broadcast.js';
-import type { ControlProtocol, PeerProtocol, SyncProtocol } from './group-protocols.js';
+import type { ControlProtocol, PeerProtocol, SyncProtocol, WorkflowProtocol } from './group-protocols.js';
 /**
- * The app-lane handler maps a per-group peer wires into `createGroupPeer`. Keyed
- * to {@link groupProtocols} so the peer dispatches each decoded procedure payload
+ * Per-group handler maps wired into `createGroupPeer`, keyed to
+ * {@link groupProtocols} so the peer dispatches each decoded procedure payload
  * to the matching handler.
  */
 export type GroupHandlers = {
@@ -11,20 +12,55 @@ export type GroupHandlers = {
     sync: ProcedureHandlers<SyncProtocol>;
     peer: ProcedureHandlers<PeerProtocol>;
 };
+/**
+ * The subset of the workflow API the observe handlers read: enumerate this
+ * device's instances (`list`), resolve one by id (`get`), and test each name for
+ * remote-observe opt-in. Threaded live via `engine.getAPI('workflow')`, so the
+ * protocol layer keeps its type-only dependency on `@kubun/plugin-workflow-api`.
+ * `get` resolves `workflow/status` in one lookup rather than scanning `list()`.
+ */
+export type WorkflowDiscoverAPI = Pick<WorkflowAPI, 'list' | 'get' | 'isRemotelyObservable'>;
+/**
+ * The observe subset plus the three directed COMMAND methods and the command
+ * opt-in predicate. `buildWorkflowHandlers` serves all six `workflow` procedures
+ * off one map, so it takes this superset; threaded live the same way, so the
+ * protocol layer keeps its type-only dependency on `@kubun/plugin-workflow-api`.
+ */
+export type WorkflowCommandAPI = WorkflowDiscoverAPI & Pick<WorkflowAPI, 'enqueue' | 'cancel' | 'retry' | 'isRemotelyCommandable'>;
+/**
+ * The `workflow/discover` handler for one group. Enumerates this device's own
+ * instances and returns ONLY those whose workflow opted into remote observation.
+ * The reply is a bare `InstanceStatus[]`: the gather envelope carries the
+ * authenticated `senderDID`, so the body attributes nothing — exactly as
+ * `peer/query` returns its bare announcement.
+ */
+export declare function buildWorkflowHandlers(api: WorkflowCommandAPI): {
+    workflow: ProcedureHandlers<WorkflowProtocol>;
+};
 /**
  * Build the control + sync procedure handlers for a single group.
  *
- * Each handler is a thin adapter: it maps the typed group-rpc procedure payload
- * back to the {@link GroupBroadcastMessage} the pure {@link processBroadcast}
- * apply logic already understands, re-adding the `groupID` the peer is bound to
- * (group-rpc strips it from the wire because each topic already encodes the
- * group). The apply logic owns verification, conflict resolution, and storage;
- * the handler owns only the shape translation.
+ * Each handler is a thin adapter: it maps the typed group-rpc payload back to the
+ * {@link GroupBroadcastMessage} the pure {@link processBroadcast} apply logic
+ * understands, re-adding the `groupID` group-rpc strips from the wire (each topic
+ * already encodes the group). The apply logic owns verification, conflict
+ * resolution, and storage; the handler owns only shape translation.
  *
- * Event handlers are fire-and-forget. `processBroadcast` already drops an
- * unverifiable or malformed payload and returns `{ applied: false }` rather than
- * throwing, so the result is intentionally ignored. A programmer-error rethrow
- * (or an unexpected store fault) is caught and logged here so a single bad frame
- * never escapes as an unhandled rejection out of the receive loop.
+ * Event handlers are fire-and-forget. `processBroadcast` drops an unverifiable or
+ * malformed payload and returns `{ applied: false }` rather than throwing, so the
+ * result is ignored. A rethrow (or unexpected store fault) is caught and logged
+ * here so a single bad frame never escapes the receive loop as an unhandled
+ * rejection.
  */
 export declare function buildGroupHandlers(params: ProcessBroadcastParams, groupID: string): GroupHandlers;
+/**
+ * The group handlers with the `workflow` observe + command handlers
+ * conditionally added, paired with {@link composeGroupProtocols}. A FRESH object
+ * — the base handlers are never mutated. Absent api the base is returned
+ * unchanged, so the workflow lane has no handler (and no protocol was mounted
+ * either).
+ *
+ * Returns the base type: the extra handlers are served by name at runtime, but
+ * the peer stays typed at the base shape the manager routes.
+ */
+export declare function composeGroupHandlers(base: GroupHandlers, api: WorkflowCommandAPI | undefined): GroupHandlers;

package/lib/groups/group-handlers.js

@@ -1,30 +1,182 @@
+import { RETRY_REFUSAL_REASONS } from '@kubun/plugin-workflow-api';
 import { signAccessDefaultSet } from './access-default-token.js';
 import { processBroadcast } from './broadcast.js';
 /**
  * Why this device is not answering a `peer/query`.
  *
  * Declining is a THROW because that is the only silence the lane offers: the
- * broadcast responder writes a reply for whatever a handler returns, and the
- * requester's gather drops replies that carried an error and keeps the rest. So a
- * decline bounds the RESULT, not the traffic — every member still publishes one
- * reply frame — and "only matching devices reply" is true of what a gather
- * reports, not of what crosses the hub.
+ * responder writes a reply for whatever a handler returns, and the gather drops
+ * errored replies and keeps the rest. So a decline bounds the RESULT, not the
+ * traffic — every member still publishes one reply frame, and "only matching
+ * devices reply" is true of what a gather reports, not of what crosses the hub.
  */ class PeerQueryDeclined extends Error {
     constructor(reason){
         super(`peer/query declined: ${reason}`);
         this.name = 'PeerQueryDeclined';
     }
 }
+// The engine's own retry refusals, recovered structurally from the thrown
+// WorkflowRetryError: catching a runtime instance would need a value import the
+// type-only boundary forbids. Sourced from the api package's
+// RETRY_REFUSAL_REASONS so it cannot drift; a recognized reason maps through
+// verbatim, anything else is a genuine fault and is rethrown (→ generic
+// HANDLER_ERROR).
+const KNOWN_RETRY_REFUSAL_REASONS = new Set(RETRY_REFUSAL_REASONS);
+function retryRefusalReason(error) {
+    const reason = error?.reason;
+    return typeof reason === 'string' && KNOWN_RETRY_REFUSAL_REASONS.has(reason) ? reason : undefined;
+}
+/**
+ * A `workflow/status` refusal. One error for BOTH an unknown id and a
+ * non-observable instance, so the caller cannot tell them apart — the throw
+ * surfaces to `.to()` as the enkaku-generic handler-error pair regardless of
+ * what was thrown, so the two cases are already wire-indistinguishable.
+ */ class WorkflowInstanceNotObservable extends Error {
+    constructor(){
+        super('workflow instance not found');
+        this.name = 'WorkflowInstanceNotObservable';
+    }
+}
+/**
+ * The `workflow/discover` handler for one group. Enumerates this device's own
+ * instances and returns ONLY those whose workflow opted into remote observation.
+ * The reply is a bare `InstanceStatus[]`: the gather envelope carries the
+ * authenticated `senderDID`, so the body attributes nothing — exactly as
+ * `peer/query` returns its bare announcement.
+ */ export function buildWorkflowHandlers(api) {
+    // cancel/retry resolve get(instanceID)→name and refuse identically when the
+    // instance is missing OR not commandable: a non-commandable instance must be
+    // indistinguishable from a nonexistent one, or a probe could confirm a hidden
+    // instance exists by the difference in the reply. Returns the resolved status
+    // when the gate passes, else the shared `not_found` refusal.
+    const resolveCommandable = async (instanceID)=>{
+        const instance = await api.get(instanceID);
+        if (instance == null || !api.isRemotelyCommandable(instance.name)) {
+            return {
+                ok: false,
+                result: {
+                    ok: false,
+                    reason: 'not_found'
+                }
+            };
+        }
+        return {
+            ok: true,
+            status: instance
+        };
+    };
+    return {
+        workflow: {
+            'workflow/discover': async ()=>{
+                const instances = await api.list();
+                return instances.filter((instance)=>api.isRemotelyObservable(instance.name));
+            },
+            // Same policy as discover, reached directed via `.to(peer)` rather than by
+            // gather. The serving side is identical; only the transport differs.
+            'workflow/list': async ()=>{
+                const instances = await api.list();
+                return instances.filter((instance)=>api.isRemotelyObservable(instance.name));
+            },
+            'workflow/status': async ({ param })=>{
+                const instance = await api.get(param.instanceID);
+                // A non-observable instance must be indistinguishable from a missing one:
+                // the same refusal for both, or a probe could confirm a hidden instance
+                // exists by the difference in the reply.
+                if (instance == null || !api.isRemotelyObservable(instance.name)) {
+                    throw new WorkflowInstanceNotObservable();
+                }
+                return instance;
+            },
+            // Directed: exactly one device runs this. A business refusal is RETURNED as
+            // data (enkaku collapses a throw to a generic error), so a non-commandable
+            // name refuses with `not_commandable` rather than throwing.
+            'workflow/enqueue': async ({ param })=>{
+                if (!api.isRemotelyCommandable(param.name)) {
+                    return {
+                        ok: false,
+                        reason: 'not_commandable'
+                    };
+                }
+                const handle = await api.enqueue(param.name, param.params, param.opts);
+                // Normalize the enqueue handle to the InstanceStatus the wire carries, as
+                // cancelWorkflow does. A miss right after enqueue is an infra fault, not a
+                // business refusal, so it throws (→ generic error).
+                const status = await api.get(handle.instanceID);
+                if (status == null) {
+                    throw new Error(`Workflow instance "${handle.instanceID}" not found after enqueue`);
+                }
+                return {
+                    ok: true,
+                    status
+                };
+            },
+            'workflow/cancel': async ({ param })=>{
+                const resolved = await resolveCommandable(param.instanceID);
+                if (!resolved.ok) {
+                    return resolved.result;
+                }
+                await api.cancel(param.instanceID);
+                const status = await api.get(param.instanceID);
+                if (status == null) {
+                    throw new Error(`Workflow instance "${param.instanceID}" not found after cancel`);
+                }
+                return {
+                    ok: true,
+                    status
+                };
+            },
+            'workflow/retry': async ({ param })=>{
+                const resolved = await resolveCommandable(param.instanceID);
+                if (!resolved.ok) {
+                    return resolved.result;
+                }
+                try {
+                    const status = await api.retry(param.instanceID);
+                    return {
+                        ok: true,
+                        status
+                    };
+                } catch (error) {
+                    // The engine's own retry refusals map through as data; a genuine fault
+                    // is rethrown to surface as the generic handler error.
+                    const reason = retryRefusalReason(error);
+                    if (reason == null) {
+                        throw error;
+                    }
+                    // Reconcile an ambiguous at-least-once retry: the directed lane resends
+                    // to the same mailbox when a request throws, so a SUCCESSFUL first retry
+                    // whose response leg was lost is resent and then refused `not_failed`
+                    // (the first attempt already re-armed the instance). If it is now
+                    // runnable, the transition already happened — report idempotent success
+                    // rather than a false refusal. A terminal instance never satisfied the
+                    // request, so its `not_failed` stands.
+                    if (reason === 'not_failed') {
+                        const current = await api.get(param.instanceID);
+                        if (current != null && (current.status === 'pending' || current.status === 'running')) {
+                            return {
+                                ok: true,
+                                status: current
+                            };
+                        }
+                    }
+                    return {
+                        ok: false,
+                        reason
+                    };
+                }
+            }
+        }
+    };
+}
 /**
- * The MLS-authenticated sender of a frame, which group-rpc surfaces at
- * `message.payload.iss`. It builds that context message itself from the sender
- * `unwrap` recovered, so `iss` is an authenticated DID and not a transport-claimed
- * one.
+ * The MLS-authenticated sender of a frame, surfaced by group-rpc at
+ * `message.payload.iss`. group-rpc builds that context message from the sender
+ * `unwrap` recovered, so `iss` is authenticated, not transport-claimed.
  *
- * Absent when the frame opened at a leaf that could not be named. That is
- * `undefined`, never a sentinel: a placeholder DID would be an identity claim
- * nothing vouched for, and a guard comparing against it would be comparing
- * against a value chosen for never matching rather than one meaning "unknown".
+ * Absent when the frame opened at a leaf that could not be named — `undefined`,
+ * never a sentinel: a placeholder DID would be an identity claim nothing vouched
+ * for, and a guard against it would compare against a never-matching value rather
+ * than one meaning "unknown".
  */ function authenticatedSender(message) {
     const payload = message.payload;
     const iss = payload.iss;
@@ -33,18 +185,17 @@ import { processBroadcast } from './broadcast.js';
 /**
  * Build the control + sync procedure handlers for a single group.
  *
- * Each handler is a thin adapter: it maps the typed group-rpc procedure payload
- * back to the {@link GroupBroadcastMessage} the pure {@link processBroadcast}
- * apply logic already understands, re-adding the `groupID` the peer is bound to
- * (group-rpc strips it from the wire because each topic already encodes the
- * group). The apply logic owns verification, conflict resolution, and storage;
- * the handler owns only the shape translation.
+ * Each handler is a thin adapter: it maps the typed group-rpc payload back to the
+ * {@link GroupBroadcastMessage} the pure {@link processBroadcast} apply logic
+ * understands, re-adding the `groupID` group-rpc strips from the wire (each topic
+ * already encodes the group). The apply logic owns verification, conflict
+ * resolution, and storage; the handler owns only shape translation.
  *
- * Event handlers are fire-and-forget. `processBroadcast` already drops an
- * unverifiable or malformed payload and returns `{ applied: false }` rather than
- * throwing, so the result is intentionally ignored. A programmer-error rethrow
- * (or an unexpected store fault) is caught and logged here so a single bad frame
- * never escapes as an unhandled rejection out of the receive loop.
+ * Event handlers are fire-and-forget. `processBroadcast` drops an unverifiable or
+ * malformed payload and returns `{ applied: false }` rather than throwing, so the
+ * result is ignored. A rethrow (or unexpected store fault) is caught and logged
+ * here so a single bad frame never escapes the receive loop as an unhandled
+ * rejection.
  */ export function buildGroupHandlers(params, groupID) {
     const safeApply = async (apply)=>{
         try {
@@ -246,3 +397,18 @@ import { processBroadcast } from './broadcast.js';
         }
     };
 }
+/**
+ * The group handlers with the `workflow` observe + command handlers
+ * conditionally added, paired with {@link composeGroupProtocols}. A FRESH object
+ * — the base handlers are never mutated. Absent api the base is returned
+ * unchanged, so the workflow lane has no handler (and no protocol was mounted
+ * either).
+ *
+ * Returns the base type: the extra handlers are served by name at runtime, but
+ * the peer stays typed at the base shape the manager routes.
+ */ export function composeGroupHandlers(base, api) {
+    return api != null ? {
+        ...base,
+        ...buildWorkflowHandlers(api)
+    } : base;
+}