@zhin.js/workroom 0.0.0 → 0.0.2

package/lib/room/room-send-limiter.d.ts

@@ -0,0 +1,91 @@
+import type { OutboundMessageService } from '@zhin.js/core/runtime';
+/**
+ * Per-account send rate limiter for Room output (personal QQ accounts can be risk-controlled by the platform).
+ *
+ * Two forms over ONE shared instance (`createRoomSendLimiter`), both booking into the same per-account map:
+ * - `send(request)`: a decorator over `Pick<OutboundMessageService, 'send'>`; once a slot is granted it still
+ *   calls the wrapped `send`.
+ * - `outboundMiddleware()`: an outbound middleware definition (`{ target: 'outbound', handle(ctx, next) }`);
+ *   books a slot, sleeps, then `await next()`. Wrap it as `defineMiddleware(limiter.outboundMiddleware())`
+ *   to get the feature brand. `middleware(envelope, next)` is the low-level form underneath it.
+ * Either way the normal outbound chain (OutboundRenderer -> outbound middleware -> Endpoint) is never bypassed:
+ * the limiter only delays or refuses before `inner.send` / `next()`.
+ *
+ * C1 MUST make EVERY outbound of a member Endpoint use this same instance (as an outbound middleware, or by
+ * wrapping the shared OutboundMessageService), keyed by account. Wrapping only RoomBus's `outbound` under-counts
+ * `$reply` and generation output of the same account, so the account-level risk-control protection would only
+ * be partial. It is not installed globally by B4.
+ *
+ * One outbound path must use exactly ONE form (middleware, OR `send` wrapping the OutboundMessageService).
+ * Using both on the same path books the same send twice and double-counts it. Share the instance across
+ * DIFFERENT paths of the same account, not across two forms of one path.
+ */
+type DeliveryReceipt = Awaited<ReturnType<OutboundMessageService['send']>>;
+export interface RoomSendLimit {
+    readonly maxPerMinute?: number;
+    readonly minIntervalMs?: number;
+}
+export interface RoomSendLimiterOptions {
+    /** Wrapped service for the `send` form; without it `send` refuses. Not needed for the `middleware` form. */
+    readonly inner?: Pick<OutboundMessageService, 'send'>;
+    /** Bot account of an endpoint (e.g. PeerRegistry.selfOf). Falls back to the endpoint id when unknown. */
+    readonly accountOf?: (endpointId: string) => string | undefined;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Default 20. */
+    readonly maxPerMinute?: number;
+    /** Minimum gap between two sends of one account. Default 1000. */
+    readonly minIntervalMs?: number;
+    /** A send that would have to wait longer is rejected instead. Default 5000. */
+    readonly maxWaitMs?: number;
+    /** Overrides keyed by account (or `endpoint:<id>` for unresolved accounts). */
+    readonly perAccount?: Readonly<Record<string, RoomSendLimit>>;
+    readonly logger?: {
+        warn(message: string): void;
+    };
+}
+export interface RateLimitedOutboundOptions extends RoomSendLimiterOptions {
+    readonly inner: Pick<OutboundMessageService, 'send'>;
+}
+/** Structural outbound envelope: only what the limiter reads, so no core middleware type is imported. */
+export interface RoomSendEnvelope {
+    readonly conversation: {
+        readonly endpoint: {
+            readonly id: string;
+        };
+    };
+}
+export declare class RoomSendRateLimitedError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    constructor(code: string, message: string, retryable: boolean);
+}
+/** Structural subset of the core outbound middleware context: the envelope lives in `input`. */
+export interface RoomOutboundMiddlewareContext {
+    readonly input: RoomSendEnvelope;
+}
+/** Structural outbound middleware definition; `phase` / `order` default in `defineMiddleware`. */
+export interface RoomOutboundMiddlewareDefinition {
+    readonly target: 'outbound';
+    handle(context: RoomOutboundMiddlewareContext, next: () => Promise<void>): Promise<void>;
+}
+export interface RoomSendLimiter {
+    send(request: Parameters<OutboundMessageService['send']>[0]): Promise<DeliveryReceipt>;
+    /**
+     * Low-level: takes the ENVELOPE, not the core middleware context. Passing the context makes `reserve` fail
+     * closed on every send. Use `outboundMiddleware()` in plugins. Adaptation by hand:
+     * `handle: (ctx, next) => limiter.middleware(ctx.input, next)`.
+     * Throws RoomSendRateLimitedError when refused.
+     */
+    middleware(envelope: RoomSendEnvelope, next: () => Promise<void>): Promise<void>;
+    /**
+     * Outbound middleware definition for plugins: `defineMiddleware(limiter.outboundMiddleware())`.
+     * Do not combine with `send` on the same outbound path (double counting).
+     */
+    outboundMiddleware(): RoomOutboundMiddlewareDefinition;
+}
+export declare function createRoomSendLimiter(options: RoomSendLimiterOptions): RoomSendLimiter;
+/** Tests / standalone use only. Production (C1) uses the shared `createRoomSendLimiter` instance. */
+export declare function createRateLimitedOutbound(options: RateLimitedOutboundOptions): Pick<OutboundMessageService, 'send'>;
+export {};
+//# sourceMappingURL=room-send-limiter.d.ts.map

package/lib/room/room-send-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-send-limiter.d.ts","sourceRoot":"","sources":["../../src/room/room-send-limiter.ts"],"names":[],"mappings":"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"}

package/lib/room/room-send-limiter.js

@@ -0,0 +1,124 @@
+const WINDOW_MS = 60_000;
+const MAX_KEYS = 1024;
+export class RoomSendRateLimitedError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'RoomSendRateLimitedError';
+    }
+}
+function positive(name, value, fallback, allowZero = false) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < (allowZero ? 0 : 1)) {
+        throw new RangeError(`Room send limiter option ${name} must be a ${allowZero ? 'non-negative' : 'positive'} integer, got ${String(resolved)}`);
+    }
+    return resolved;
+}
+const rejected = (code, message, retryable) => Object.freeze({ status: 'rejected', failure: Object.freeze({ code, message, retryable }) });
+export function createRoomSendLimiter(options) {
+    const { inner, logger } = options;
+    const now = options.now ?? (() => Date.now());
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => { setTimeout(resolve, ms); }));
+    const maxPerMinute = positive('maxPerMinute', options.maxPerMinute, 20);
+    const minIntervalMs = positive('minIntervalMs', options.minIntervalMs, 1000, true);
+    const maxWaitMs = positive('maxWaitMs', options.maxWaitMs, 5000, true);
+    const overrides = new Map();
+    for (const [key, limit] of Object.entries(options.perAccount ?? {})) {
+        overrides.set(key, {
+            maxPerMinute: positive(`perAccount.${key}.maxPerMinute`, limit.maxPerMinute, maxPerMinute),
+            minIntervalMs: positive(`perAccount.${key}.minIntervalMs`, limit.minIntervalMs, minIntervalMs, true),
+        });
+    }
+    const bookings = new Map();
+    const sweep = (at) => {
+        for (const [key, booking] of bookings) {
+            if (booking.last + WINDOW_MS <= at)
+                bookings.delete(key);
+        }
+    };
+    /** Synchronous so that arrival order equals booking order. Returns the wait, or a rejection receipt. */
+    const reserve = (request) => {
+        try {
+            const endpointId = request.conversation.endpoint.id;
+            if (typeof endpointId !== 'string' || endpointId === '')
+                throw new TypeError('request has no endpoint id');
+            const key = options.accountOf?.(endpointId) || `endpoint:${endpointId}`;
+            const limit = overrides.get(key) ?? { maxPerMinute, minIntervalMs };
+            const at = now();
+            if (!Number.isFinite(at))
+                throw new TypeError('clock returned a non-finite value');
+            let booking = bookings.get(key);
+            if (booking && booking.last + WINDOW_MS <= at) {
+                bookings.delete(key);
+                booking = undefined;
+            }
+            if (!booking) {
+                if (bookings.size >= MAX_KEYS)
+                    sweep(at);
+                if (bookings.size >= MAX_KEYS) {
+                    return rejected('room_send_guard_error', `too many tracked send accounts (${MAX_KEYS})`, true);
+                }
+            }
+            const slots = booking?.slots ?? [];
+            let slot = Math.max(at, booking ? booking.last + limit.minIntervalMs : at);
+            if (slots.length >= limit.maxPerMinute) {
+                slot = Math.max(slot, slots[slots.length - limit.maxPerMinute] + WINDOW_MS);
+            }
+            const wait = slot - at;
+            if (wait > maxWaitMs) {
+                return rejected('room_send_rate_limited', `account ${key} send rate limit reached; retry in ${wait} ms`, true);
+            }
+            // Booked before sending: platform risk control counts attempts, so failures count too.
+            slots.push(slot);
+            while (slots.length > limit.maxPerMinute)
+                slots.shift();
+            bookings.set(key, { slots, last: slot });
+            return wait;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger?.warn(`room send limiter failed closed: ${message}`);
+            return rejected('room_send_guard_error', message, false);
+        }
+    };
+    const middleware = async (envelope, next) => {
+        const wait = reserve(envelope);
+        if (typeof wait !== 'number') {
+            logger?.warn(`room send refused: ${wait.failure?.code ?? wait.status}`);
+            throw new RoomSendRateLimitedError(wait.failure?.code ?? 'room_send_guard_error', wait.failure?.message ?? 'send refused', wait.failure?.retryable ?? false);
+        }
+        if (wait > 0)
+            await sleep(wait);
+        await next();
+    };
+    return Object.freeze({
+        async send(request) {
+            if (!inner)
+                return rejected('room_send_guard_error', 'send limiter has no inner service', false);
+            const wait = reserve(request);
+            if (typeof wait !== 'number') {
+                logger?.warn(`room send refused: ${wait.failure?.code ?? wait.status}`);
+                return wait;
+            }
+            if (wait > 0)
+                await sleep(wait);
+            return inner.send(request);
+        },
+        middleware,
+        outboundMiddleware() {
+            return Object.freeze({
+                target: 'outbound',
+                handle: (context, next) => middleware(context.input, next),
+            });
+        },
+    });
+}
+/** Tests / standalone use only. Production (C1) uses the shared `createRoomSendLimiter` instance. */
+export function createRateLimitedOutbound(options) {
+    const limiter = createRoomSendLimiter(options);
+    return Object.freeze({ send: (request) => limiter.send(request) });
+}
+//# sourceMappingURL=room-send-limiter.js.map

package/lib/room/room-send-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-send-limiter.js","sourceRoot":"","sources":["../../src/room/room-send-limiter.ts"],"names":[],"mappings":"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"}

package/lib/room/room-task-authorizer.d.ts

@@ -0,0 +1,54 @@
+import type { RoomTaskCommand } from './room-task.js';
+import type { GuardActor, RoomGuards } from './room-guards.js';
+import type { RoomDefinition } from './room-definition.js';
+import type { RoomEntry } from './room-registry.js';
+export type RoomTaskAuthorizer = (roomId: string, command: RoomTaskCommand) => string | undefined;
+export type RoomAssignCommand = Extract<RoomTaskCommand, {
+    type: 'assign';
+}>;
+export interface RoomTaskAuthorizerOptions {
+    readonly guards: Pick<RoomGuards, 'authorizeSensitive'>;
+    /** Resolves the `by` of a command to the actor behind it; undefined means unknown, which is refused. */
+    readonly actorOf: (by: string) => GuardActor | undefined;
+    /**
+     * Role check for `assign` (lead / coordinator only); return a refusal reason or undefined to allow.
+     * Optional, but when absent every `assign` is refused (fail-closed).
+     */
+    readonly authorizeAssign?: (roomId: string, command: RoomAssignCommand) => string | undefined;
+    /**
+     * Composed after the built-in checks pass. Use `createRoomRoleAuthorizer(...)` to enforce the role /
+     * membership checks for create / start / block / complete / handoff (and `handoffTo`); when absent those
+     * commands are not checked here (not a safe default).
+     */
+    readonly next?: RoomTaskAuthorizer;
+}
+export declare function createRoomTaskAuthorizer(options: RoomTaskAuthorizerOptions): RoomTaskAuthorizer;
+export interface RoomRoleAuthorizerOptions {
+    /** The Room definition (preferred) or a registry entry; membership is indexed from it. */
+    readonly room: RoomDefinition | RoomEntry;
+    /** When given, commands for any other room id are refused (`unknown room`). */
+    readonly roomId?: string;
+    /**
+     * Resolves `by` to an actor; used only for `create`, where a human may start a Task. Without it, a `by` with
+     * the `human:` prefix counts as a human and every other `by` must be a member.
+     */
+    readonly actorOf?: (by: string) => GuardActor | undefined;
+}
+/**
+ * Role / membership check to pass as `next` of `createRoomTaskAuthorizer`. Returns a refusal reason or undefined.
+ * - create: `assignee` (if any) must be a member; `by` must be a known actor (a member or a human).
+ * - start / block / complete: `by` must be a member.
+ * - handoff: `by` and `to` are members and the role of `by` lists the role of `to` in `handoffTo`
+ *   (no `handoffTo` means no handoff allowed).
+ * - assign / cancel: not checked here (see `createRoomRoleAssignAuthorizer` and the built-in cancel check).
+ * - any other (unknown) command type is refused.
+ * Fail-closed: any throw (or a member whose role is missing) is a refusal.
+ */
+export declare function createRoomRoleAuthorizer(options: RoomRoleAuthorizerOptions): RoomTaskAuthorizer;
+/**
+ * Role check for `assign`, to pass as `authorizeAssign`: only the coordinator (a Room without one refuses every
+ * assign) may assign, and only to a member. The hook is synchronous and cannot see the Task, so status-dependent
+ * rules stay with the state machine. Fail-closed: a throw is a refusal.
+ */
+export declare function createRoomRoleAssignAuthorizer(options: Pick<RoomRoleAuthorizerOptions, 'room' | 'roomId'>): (roomId: string, command: RoomAssignCommand) => string | undefined;
+//# sourceMappingURL=room-task-authorizer.d.ts.map

package/lib/room/room-task-authorizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-task-authorizer.d.ts","sourceRoot":"","sources":["../../src/room/room-task-authorizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AA4BpD,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,MAAM,GAAG,SAAS,CAAC;AAElG,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,eAAe,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAC;AAE7E,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC;IACxD,wGAAwG;IACxG,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;IACzD;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,KAAK,MAAM,GAAG,SAAS,CAAC;IAC9F;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CA2B/F;AAID,MAAM,WAAW,yBAAyB;IACxC,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,CAAC;CAC3D;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAuC/F;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,IAAI,CAAC,yBAAyB,EAAE,MAAM,GAAG,QAAQ,CAAC,GAC1D,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,KAAK,MAAM,GAAG,SAAS,CAepE"}

package/lib/room/room-task-authorizer.js

@@ -0,0 +1,139 @@
+export function createRoomTaskAuthorizer(options) {
+    const { guards, actorOf, authorizeAssign, next } = options;
+    return (roomId, command) => {
+        if (command.type === 'cancel') {
+            try {
+                const actor = actorOf(command.by);
+                if (!actor)
+                    return 'task.cancel requires a known human actor';
+                const refusal = guards.authorizeSensitive('task.cancel', actor);
+                if (refusal !== undefined)
+                    return refusal;
+            }
+            catch (error) {
+                return `task.cancel authorization failed: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        else if (command.type === 'assign') {
+            if (!authorizeAssign)
+                return 'task.assign requires a role check (authorizeAssign); refused by default';
+            try {
+                const refusal = authorizeAssign(roomId, command);
+                if (refusal !== undefined)
+                    return refusal;
+            }
+            catch (error) {
+                return `task.assign authorization failed: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        try {
+            return next?.(roomId, command);
+        }
+        catch (error) {
+            return `task authorization failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    };
+}
+function indexRoom(room) {
+    const entry = 'definition' in room ? room : undefined;
+    const definition = entry ? entry.definition : room;
+    const byAgent = new Map();
+    for (const member of definition.members)
+        byAgent.set(member.agent, member.role);
+    return {
+        id: entry?.id,
+        coordinator: definition.coordinator,
+        roleOf: (agent) => (Object.hasOwn(definition.roles, byAgent.get(agent) ?? '') ? byAgent.get(agent) : undefined),
+        handoffTo: (agent) => {
+            const role = byAgent.get(agent);
+            return role !== undefined && Object.hasOwn(definition.roles, role) ? definition.roles[role]?.handoffTo : undefined;
+        },
+    };
+}
+const isHumanBy = (by) => by.startsWith('human:') && by.length > 'human:'.length;
+/**
+ * Role / membership check to pass as `next` of `createRoomTaskAuthorizer`. Returns a refusal reason or undefined.
+ * - create: `assignee` (if any) must be a member; `by` must be a known actor (a member or a human).
+ * - start / block / complete: `by` must be a member.
+ * - handoff: `by` and `to` are members and the role of `by` lists the role of `to` in `handoffTo`
+ *   (no `handoffTo` means no handoff allowed).
+ * - assign / cancel: not checked here (see `createRoomRoleAssignAuthorizer` and the built-in cancel check).
+ * - any other (unknown) command type is refused.
+ * Fail-closed: any throw (or a member whose role is missing) is a refusal.
+ */
+export function createRoomRoleAuthorizer(options) {
+    const { room, roomId, actorOf } = options;
+    return (target, command) => {
+        try {
+            const index = indexRoom(room);
+            if (roomId !== undefined && target !== roomId)
+                return `unknown room ${target}`;
+            if (roomId === undefined && index.id !== undefined && target !== index.id)
+                return `unknown room ${target}`;
+            const member = (agent) => index.roleOf(agent) !== undefined;
+            switch (command.type) {
+                case 'create': {
+                    const known = actorOf ? actorOf(command.by) !== undefined : isHumanBy(command.by) || member(command.by);
+                    if (!known)
+                        return `create: unknown actor ${command.by}`;
+                    if (command.assignee !== undefined && !member(command.assignee))
+                        return `create: ${command.assignee} is not a member`;
+                    return undefined;
+                }
+                case 'start':
+                case 'block':
+                case 'complete':
+                    return member(command.by) ? undefined : `${command.type}: ${command.by} is not a member of room ${target}`;
+                case 'handoff': {
+                    const from = index.roleOf(command.by);
+                    if (from === undefined)
+                        return `handoff: ${command.by} is not a member of room ${target}`;
+                    const to = index.roleOf(command.to);
+                    if (to === undefined)
+                        return `handoff: ${command.to} is not a member of room ${target}`;
+                    if (!index.handoffTo(command.by)?.includes(to))
+                        return `handoff: role ${from} may not hand off to role ${to}`;
+                    return undefined;
+                }
+                case 'assign':
+                case 'cancel':
+                    return undefined; // checked by `authorizeAssign` / the built-in cancel check
+                default: {
+                    const unknown = command;
+                    return `unsupported command type ${String(unknown.type)}`;
+                }
+            }
+        }
+        catch (error) {
+            return `task authorization failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    };
+}
+/**
+ * Role check for `assign`, to pass as `authorizeAssign`: only the coordinator (a Room without one refuses every
+ * assign) may assign, and only to a member. The hook is synchronous and cannot see the Task, so status-dependent
+ * rules stay with the state machine. Fail-closed: a throw is a refusal.
+ */
+export function createRoomRoleAssignAuthorizer(options) {
+    const { room, roomId } = options;
+    return (target, command) => {
+        try {
+            const index = indexRoom(room);
+            if (roomId !== undefined && target !== roomId)
+                return `unknown room ${target}`;
+            if (roomId === undefined && index.id !== undefined && target !== index.id)
+                return `unknown room ${target}`;
+            if (index.roleOf(command.by) === undefined)
+                return `assign: ${command.by} is not a member of room ${target}`;
+            if (index.coordinator === undefined || command.by !== index.coordinator)
+                return 'assign: only the coordinator may assign';
+            if (index.roleOf(command.assignee) === undefined)
+                return `assign: ${command.assignee} is not a member`;
+            return undefined;
+        }
+        catch (error) {
+            return `task authorization failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    };
+}
+//# sourceMappingURL=room-task-authorizer.js.map

package/lib/room/room-task-authorizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-task-authorizer.js","sourceRoot":"","sources":["../../src/room/room-task-authorizer.ts"],"names":[],"mappings":"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"}

package/lib/room/room-task-journal.d.ts

@@ -0,0 +1,27 @@
+import { type RoomTaskEvent } from './room-task.js';
+/** One append-only event stream per Room. */
+export interface RoomTaskJournal {
+    read(roomId: string): Promise<readonly RoomTaskEvent[]>;
+    /**
+     * Compare-and-set append. `expectedSequence` is the sequence of the last stored event (-1 when empty).
+     * The batch is written atomically: all events or none.
+     */
+    append(roomId: string, expectedSequence: number, events: readonly RoomTaskEvent[]): Promise<readonly RoomTaskEvent[]>;
+}
+export declare class RoomTaskSequenceConflictError extends Error {
+    readonly roomId: string;
+    readonly expected: number;
+    readonly actual: number;
+    constructor(roomId: string, expected: number, actual: number);
+}
+export declare class RoomTaskJournalCorruptionError extends Error {
+    constructor(message: string);
+}
+/** Shared batch checks: scope, contiguity from expectedSequence + 1 and a full replay of the result. */
+export declare function assertRoomTaskAppend(roomId: string, current: readonly RoomTaskEvent[], expectedSequence: number, events: readonly RoomTaskEvent[]): void;
+export declare class MemoryRoomTaskJournal implements RoomTaskJournal {
+    #private;
+    read(roomId: string): Promise<readonly RoomTaskEvent[]>;
+    append(roomId: string, expectedSequence: number, events: readonly RoomTaskEvent[]): Promise<readonly RoomTaskEvent[]>;
+}
+//# sourceMappingURL=room-task-journal.d.ts.map

package/lib/room/room-task-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-task-journal.d.ts","sourceRoot":"","sources":["../../src/room/room-task-journal.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAErE,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;IACxD;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;CACvH;AAED,qBAAa,6BAA8B,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAlE,MAAM,EAAE,MAAM,EAAW,QAAQ,EAAE,MAAM,EAAW,MAAM,EAAE,MAAM;CAIxF;AAED,qBAAa,8BAA+B,SAAQ,KAAK;gBAC3C,OAAO,EAAE,MAAM;CAI5B;AAED,wGAAwG;AACxG,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,SAAS,aAAa,EAAE,GAC/B,IAAI,CAQN;AAED,qBAAa,qBAAsB,YAAW,eAAe;;IAGrD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;IAIvD,MAAM,CACV,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,SAAS,aAAa,EAAE,GAC/B,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC;CASrC"}

package/lib/room/room-task-journal.js

@@ -0,0 +1,49 @@
+import { deepFreezeWorkroomValue } from '../workroom/canonical-value.js';
+import { replayRoomTasks } from './room-task.js';
+export class RoomTaskSequenceConflictError extends Error {
+    roomId;
+    expected;
+    actual;
+    constructor(roomId, expected, actual) {
+        super(`Room Task journal for ${roomId} expected sequence ${expected} but found ${actual}`);
+        this.roomId = roomId;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'RoomTaskSequenceConflictError';
+    }
+}
+export class RoomTaskJournalCorruptionError extends Error {
+    constructor(message) {
+        super(`Room Task journal is corrupt: ${message}`);
+        this.name = 'RoomTaskJournalCorruptionError';
+    }
+}
+/** Shared batch checks: scope, contiguity from expectedSequence + 1 and a full replay of the result. */
+export function assertRoomTaskAppend(roomId, current, expectedSequence, events) {
+    const actual = current.length - 1;
+    if (actual !== expectedSequence)
+        throw new RoomTaskSequenceConflictError(roomId, expectedSequence, actual);
+    events.forEach((event, index) => {
+        if (event.roomId !== roomId)
+            throw new Error(`Room Task append scope drift: event belongs to room ${String(event.roomId)}`);
+        if (event.sequence !== expectedSequence + 1 + index)
+            throw new Error('Room Task append sequence is not contiguous');
+    });
+    replayRoomTasks(roomId, [...current, ...events]);
+}
+export class MemoryRoomTaskJournal {
+    #rooms = new Map();
+    async read(roomId) {
+        return this.#rooms.get(roomId) ?? Object.freeze([]);
+    }
+    async append(roomId, expectedSequence, events) {
+        const current = this.#rooms.get(roomId) ?? [];
+        // Copy first so later mutation of the caller's objects cannot reach the store.
+        const copy = events.map(event => JSON.parse(JSON.stringify(event)));
+        assertRoomTaskAppend(roomId, current, expectedSequence, copy);
+        const frozen = copy.map(event => deepFreezeWorkroomValue(event));
+        this.#rooms.set(roomId, Object.freeze([...current, ...frozen]));
+        return Object.freeze(frozen);
+    }
+}
+//# sourceMappingURL=room-task-journal.js.map

package/lib/room/room-task-journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-task-journal.js","sourceRoot":"","sources":["../../src/room/room-task-journal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,eAAe,EAAsB,MAAM,gBAAgB,CAAC;AAYrE,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACjC;IAAyB;IAA2B;IAAzE,YAAqB,MAAc,EAAW,QAAgB,EAAW,MAAc;QACrF,KAAK,CAAC,yBAAyB,MAAM,sBAAsB,QAAQ,cAAc,MAAM,EAAE,CAAC,CAAC;QADxE,WAAM,GAAN,MAAM,CAAQ;QAAW,aAAQ,GAAR,QAAQ,CAAQ;QAAW,WAAM,GAAN,MAAM,CAAQ;QAErF,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IACvD,YAAY,OAAe;QACzB,KAAK,CAAC,iCAAiC,OAAO,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;IAC/C,CAAC;CACF;AAED,wGAAwG;AACxG,MAAM,UAAU,oBAAoB,CAClC,MAAc,EACd,OAAiC,EACjC,gBAAwB,EACxB,MAAgC;IAEhC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAClC,IAAI,MAAM,KAAK,gBAAgB;QAAE,MAAM,IAAI,6BAA6B,CAAC,MAAM,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC3G,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5H,IAAI,KAAK,CAAC,QAAQ,KAAK,gBAAgB,GAAG,CAAC,GAAG,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACtH,CAAC,CAAC,CAAC;IACH,eAAe,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,OAAO,qBAAqB;IACvB,MAAM,GAAG,IAAI,GAAG,EAAoC,CAAC;IAE9D,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,MAAM,CACV,MAAc,EACd,gBAAwB,EACxB,MAAgC;QAEhC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC9C,+EAA+E;QAC/E,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAkB,CAAC,CAAC;QACrF,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAAC,KAAK,CAAC,CAAC,CAAC;QACjE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QAChE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;CACF"}

package/lib/room/room-task-service.d.ts

@@ -0,0 +1,54 @@
+import { type RoomTaskCommand, type RoomTaskEvent, type RoomTaskStatus, type RoomTaskView } from './room-task.js';
+import { type RoomTaskJournal } from './room-task-journal.js';
+export declare class RoomTaskAuthorizationError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export interface RoomTaskExecuteResult {
+    readonly events: readonly RoomTaskEvent[];
+    readonly state: RoomTaskView;
+    /** True when the commandId was already applied (idempotent hit); no new events were written. */
+    readonly replayed: boolean;
+}
+export interface RoomTaskListFilter {
+    readonly status?: RoomTaskStatus;
+    readonly assignee?: string;
+}
+export interface RoomTaskServiceOptions {
+    readonly journal: RoomTaskJournal;
+    readonly newId?: () => string;
+    /** Source of command timestamps' default and nothing else; the pure layer never reads a clock. */
+    readonly now?: () => number;
+    /**
+     * Hook for membership / role checks (done by the caller layer, not the state machine).
+     * Return a refusal reason to reject the command; return undefined to allow it.
+     *
+     * authorize MUST restrict who may issue `assign` against an already-assigned or blocked Task: allow only
+     * the lead/coordinator role, because `assign` checks neither `from` nor counts handoffCount. A member who
+     * wants to give up a Task must use `handoff`. The C1 authorize hook has to enforce this: createRoomTaskAuthorizer
+     * is the fail-closed path (it refuses every `assign` unless its `authorizeAssign` role check allows it).
+     */
+    readonly authorize?: (roomId: string, command: RoomTaskCommand) => string | undefined;
+    readonly logger?: {
+        warn(message: string): void;
+    };
+}
+/** `Omit` must distribute over the command union, or the per-command fields (`result`, `to`, ...) are lost. */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+export type RoomTaskExecuteInput = DistributiveOmit<RoomTaskCommand, 'at'> & {
+    readonly at?: number;
+};
+export interface RoomTaskService {
+    execute(roomId: string, command: RoomTaskExecuteInput): Promise<RoomTaskExecuteResult>;
+    get(roomId: string, taskId: string): Promise<RoomTaskView | undefined>;
+    list(roomId: string, filter?: RoomTaskListFilter): Promise<readonly RoomTaskView[]>;
+    /**
+     * Listeners run after the command is persisted and after the Room serial section has finished, in the
+     * order of the caller's own events. Concurrent executes may interleave their dispatches, so subscribers
+     * must order by `event.sequence`. Errors are logged, never propagated.
+     */
+    subscribe(listener: (event: RoomTaskEvent) => void | Promise<void>): () => void;
+}
+export declare function createRoomTaskService(options: RoomTaskServiceOptions): RoomTaskService;
+export {};
+//# sourceMappingURL=room-task-service.d.ts.map

package/lib/room/room-task-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-task-service.d.ts","sourceRoot":"","sources":["../../src/room/room-task-service.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,aAAa,EAElB,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAiC,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE7F,qBAAa,0BAA2B,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAIpC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,kGAAkG;IAClG,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,KAAK,MAAM,GAAG,SAAS,CAAC;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACnD;AAED,+GAA+G;AAC/G,KAAK,gBAAgB,CAAC,CAAC,EAAE,CAAC,SAAS,WAAW,IAAI,CAAC,SAAS,OAAO,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;AACzF,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,CAAC,eAAe,EAAE,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtG,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACvF,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IACvE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IACpF;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC;CACjF;AAUD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAkFtF"}