agent-protocols 0.8.0 → 0.10.0

package/dist/discourse.js

@@ -2,7 +2,7 @@
  * Agent Discourse Protocol 1.0: kernel types, the room type system, and
  * verification helpers.
  *
- * The protocol defines eleven built-in event types. Every other event type is
+ * The protocol defines twelve built-in event types. Every other event type is
  * declared per room as a schema-validated type definition, either inline or
  * imported from a type pack. Hosts validate structure and permissions; they
  * never need to understand application semantics.
@@ -10,14 +10,15 @@
 import { Validator } from "@cfworker/json-schema";
 import canonicalize from "canonicalize";
 import { createHash } from "node:crypto";
-import { protocolError } from "./errors.js";
-import { MAX_SAFE_NONCE, createEvent, validateAgentId, verifyEnvelope, withRoomHead, withRoomId, } from "./identity.js";
+import { AgentProtocolError, protocolError } from "./errors.js";
+import { MAX_SAFE_NONCE, createEvent, validateAgentId, validateEventFields, validateOrigin, verifyEnvelope, withRoomHead, withRoomId, } from "./identity.js";
 export const DISCOURSE_PROTOCOL = "agent-discourse/1.0";
-/** The eleven built-in event types. All other types are room-defined. */
+/** The twelve built-in event types. All other types are room-defined. */
 export const eventType = {
     ROOM_CREATE: "room.create",
     ROOM_UPDATE: "room.update",
     ROOM_JOIN: "room.join",
+    ROOM_JOIN_REQUEST: "room.join.request",
     ROOM_JOIN_REVIEW: "room.join.review",
     ROOM_LEAVE: "room.leave",
     ROOM_MEMBER_ROLE_UPDATE: "room.member.role.update",
@@ -29,9 +30,9 @@ export const eventType = {
 };
 export const BUILTIN_EVENT_TYPES = Object.values(eventType);
 /**
- * Built-in membership events. They carry the `signal` class: they anchor to
- * an accepted record but never contend for or advance the room head, so busy
- * rooms cannot starve joins, reviews, or other membership writes.
+ * Built-in membership events. They are `signal`-class: they anchor to an
+ * accepted record but are never checked against or advance the room head, so
+ * busy rooms cannot starve joins, reviews, or other membership writes.
  */
 export const MEMBERSHIP_EVENT_TYPES = [
     eventType.ROOM_JOIN,
@@ -40,22 +41,36 @@ export const MEMBERSHIP_EVENT_TYPES = [
     eventType.ROOM_MEMBER_ROLE_UPDATE,
     eventType.ROOM_MEMBER_REMOVE,
 ];
-/** Section 13.2 class of a built-in type; `undefined` for room-defined types. */
+/**
+ * Contract writes (Section 5.1): anchored like signals, so discussion traffic
+ * cannot starve them, but head-advancing, so messages and control writes
+ * composed against the old contract are rejected and re-read.
+ */
+export const CONTRACT_EVENT_TYPES = [
+    eventType.ROOM_UPDATE,
+    eventType.ROOM_CLOSE,
+    eventType.ROOM_CANCEL,
+    eventType.TYPE_DEFINE,
+];
+/**
+ * Section 12.2 class of a built-in type; `undefined` for room-defined types and
+ * for `room.join.request`, which never becomes a record.
+ */
 export function builtinEventClass(type) {
     switch (type) {
         case eventType.ROOM_CREATE:
+            return "genesis";
         case eventType.ROOM_UPDATE:
         case eventType.ROOM_CLOSE:
         case eventType.ROOM_CANCEL:
-            return "lifecycle";
+        case eventType.TYPE_DEFINE:
+            return "contract";
         case eventType.ROOM_JOIN:
         case eventType.ROOM_JOIN_REVIEW:
         case eventType.ROOM_LEAVE:
         case eventType.ROOM_MEMBER_ROLE_UPDATE:
         case eventType.ROOM_MEMBER_REMOVE:
             return "signal";
-        case eventType.TYPE_DEFINE:
-            return "control";
         case eventType.MESSAGE_CREATE:
             return "message";
         default:
@@ -63,55 +78,87 @@ export function builtinEventClass(type) {
     }
 }
 /**
- * Whether an accepted record of this type advances the room head and must
- * therefore match the current head when written (Section 5.1). Room lifecycle,
- * `message`-kind, and `control`-kind records advance the head; `signal`-kind
- * records — including the built-in membership events — only anchor to an
- * accepted record. Unknown custom types default to head-advancing.
+ * Record class of an event type; `undefined` for `room.join.request` and for
+ * custom types absent from `registry`.
+ */
+export function recordClass(type, registry) {
+    const builtin = builtinEventClass(type);
+    if (builtin !== undefined)
+        return builtin;
+    if (isBuiltinEventType(type))
+        return undefined;
+    const def = Array.isArray(registry)
+        ? registry.find((d) => d.type === type)
+        : registry?.get(type);
+    return def?.kind;
+}
+/**
+ * Whether an accepted record of this type advances the room head (Section
+ * 5.1): `genesis`, `contract`, and `control` records. Unknown custom types
+ * default to head-advancing.
  */
 export function eventAdvancesRoomHead(type, registry) {
-    const builtinClass = builtinEventClass(type);
-    if (builtinClass !== undefined)
-        return builtinClass !== "signal";
-    const def = registry?.get(type);
-    return def === undefined || def.kind !== "signal";
+    const cls = recordClass(type, registry);
+    return cls !== "message" && cls !== "signal";
+}
+/**
+ * Whether a write of this type is checked against the room head (Section
+ * 5.1): `message.create` and custom `message`/`control` kinds must be based at
+ * or after the current head. Contract and signal writes only anchor. Unknown
+ * custom types default to head-checked.
+ */
+export function eventRequiresRoomHead(type, registry) {
+    const cls = recordClass(type, registry);
+    if (cls === undefined)
+        return !isBuiltinEventType(type);
+    return cls === "message" || cls === "control";
+}
+/**
+ * Section 5.1 base check for a room write based on `baseSeq` / `baseHash`.
+ * `anchorHash` is the hash of the accepted record at `baseSeq` in the same
+ * room (`undefined` when there is none) and `headSeq` is the current room
+ * head. Every base must name an accepted record (`base_record_mismatch`);
+ * `message` and `control` writes must also be based at or after the head
+ * (`room_head_mismatch`).
+ */
+export function validateRoomBase(type, registry, baseSeq, baseHash, anchorHash, headSeq) {
+    if (anchorHash !== baseHash) {
+        throw protocolError("base_record_mismatch", `base ${baseSeq} does not name an accepted record of this room`);
+    }
+    if (eventRequiresRoomHead(type, registry) && baseSeq < headSeq) {
+        throw protocolError("room_head_mismatch", `base ${baseSeq} is before the room head ${headSeq}`);
+    }
 }
-/** Standard ADP error codes from the Section 20 table. */
+/** ADP-specific error codes (Section 19); shared codes come from Agent Identity. */
 export const DISCOURSE_ERROR_CODES = [
-    "invalid_event",
-    "invalid_event_hash",
-    "invalid_signature",
-    "invalid_actor",
-    "timestamp_out_of_window",
-    "nonce_not_greater",
     "room_not_found",
     "room_not_active",
-    "room_ended",
-    "permission_denied",
+    "host_mismatch",
     "approval_required",
     "join_request_not_found",
-    "join_request_not_approved",
-    "join_request_role_mismatch",
-    "join_request_expired",
+    "join_request_not_pending",
     "member_banned",
     "role_not_allowed",
     "max_speakers_exceeded",
     "membership_required",
-    "invalid_token",
     "room_head_mismatch",
     "base_record_mismatch",
     "agent_status_not_found",
-    "rate_limited",
-    "payload_too_large",
     "type_not_defined",
     "type_disabled",
+    "type_conflict",
+    "invalid_type_schema",
     "payload_schema_violation",
     "pack_unavailable",
 ];
 /** Hosts MUST reject events with more than this many `mentions` entries. */
 export const MAX_MENTIONS = 32;
+/** Room IDs are host-assigned and URL-safe (Section 6.1). */
+export const ROOM_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** `<algorithm>:<base64url-digest>` content digests (Section 12.5). */
+export const CONTENT_DIGEST_PATTERN = /^(sha256|sha3-256):[A-Za-z0-9_-]{43}$/;
 /** Custom event types must not use these prefixes. */
-export const RESERVED_TYPE_PREFIXES = ["room.", "type."];
+export const RESERVED_TYPE_PREFIXES = ["room.", "type.", "message."];
 /** Registered type packs defined by the specification in `1.0.packs.json`. */
 export const packId = {
     REACTIONS: "adp:reactions/1.0",
@@ -134,6 +181,10 @@ export function packMap(document) {
 export function roomCreateEvent(actor, createdAt, nonce, payload) {
     return createEvent(DISCOURSE_PROTOCOL, eventType.ROOM_CREATE, actor, createdAt, nonce, payload);
 }
+/** A `room.join.request` carries `room_id` but no base: its author may not be able to read the room. */
+export function roomJoinRequestEvent(actor, createdAt, nonce, roomId, payload) {
+    return withRoomId(createEvent(DISCOURSE_PROTOCOL, eventType.ROOM_JOIN_REQUEST, actor, createdAt, nonce, payload), roomId);
+}
 export function typeDefineEvent(actor, createdAt, nonce, roomId, baseSeq, baseHash, declaration) {
     return withRoomHead(withRoomId(createEvent(DISCOURSE_PROTOCOL, eventType.TYPE_DEFINE, actor, createdAt, nonce, declaration), roomId), baseSeq, baseHash);
 }
@@ -146,44 +197,52 @@ export function isBuiltinEventType(type) {
 export function eventRequiresRoomId(type) {
     return type !== eventType.ROOM_CREATE;
 }
+/** Whether events of this type carry `base_seq` / `base_hash`. */
+export function eventRequiresBase(type) {
+    return type !== eventType.ROOM_CREATE && type !== eventType.ROOM_JOIN_REQUEST;
+}
+export function validateRoomId(roomId) {
+    if (typeof roomId !== "string" || !ROOM_ID_PATTERN.test(roomId)) {
+        throw protocolError("invalid_event", "room_id must match [A-Za-z0-9_-]{1,64}");
+    }
+}
 export function validateDiscourseEnvelope(envelope) {
     verifyEnvelope(envelope);
-    const protocol = envelope.event.protocol;
-    if (protocol !== DISCOURSE_PROTOCOL) {
-        throw protocolError("invalid_event_protocol", `expected ${DISCOURSE_PROTOCOL}, got ${protocol}`);
+    validateDiscourseEventFields(envelope.event);
+}
+/** Section 5 event-shape rules: closed fields, room ID, base, and mentions. */
+export function validateDiscourseEventFields(event) {
+    if (event.protocol !== DISCOURSE_PROTOCOL) {
+        throw protocolError("invalid_event_protocol", `expected ${DISCOURSE_PROTOCOL}, got ${event.protocol}`);
     }
-    if (envelope.event.type === eventType.ROOM_CREATE) {
-        validateRoomCreateEventFields(envelope.event);
+    if (event.type === eventType.ROOM_CREATE) {
+        validateEventFields(event);
+        return;
     }
-    else {
-        if (envelope.event.room_id === undefined) {
+    if (event.type === eventType.ROOM_JOIN_REQUEST) {
+        validateEventFields(event, ["room_id"]);
+        if (event.room_id === undefined) {
             throw protocolError("missing_room_id", "event requires a room_id");
         }
-        validateRoomHeadPrecondition(envelope.event);
-        validateMentions(envelope.event.mentions);
+        validateRoomId(event.room_id);
+        return;
     }
+    validateEventFields(event, ["room_id", "base_seq", "base_hash", "mentions"]);
+    if (event.room_id === undefined) {
+        throw protocolError("missing_room_id", "event requires a room_id");
+    }
+    validateRoomId(event.room_id);
+    validateRoomHeadPrecondition(event);
+    validateMentions(event.mentions);
 }
 export function validateRoomPath(envelope, pathRoomId) {
-    const actual = envelope.event.room_id;
-    if (envelope.event.type === eventType.ROOM_CREATE) {
-        validateRoomCreateEventFields(envelope.event);
+    validateDiscourseEventFields(envelope.event);
+    if (envelope.event.type === eventType.ROOM_CREATE)
         return;
-    }
-    validateRoomHeadPrecondition(envelope.event);
-    validateMentions(envelope.event.mentions);
-    if (actual === undefined)
-        throw protocolError("missing_room_id", "event requires a room_id");
+    const actual = envelope.event.room_id;
     if (actual !== pathRoomId)
         throw protocolError("room_id_mismatch", `expected ${pathRoomId}, got ${actual}`);
 }
-function validateRoomCreateEventFields(event) {
-    if (event.room_id !== undefined ||
-        event.base_seq !== undefined ||
-        event.base_hash !== undefined ||
-        Object.prototype.hasOwnProperty.call(event, "mentions")) {
-        throw protocolError("invalid_event", "room.create must not include room_id, base_seq, base_hash, or mentions");
-    }
-}
 export function validateRoomHeadPrecondition(event) {
     const baseSeq = event.base_seq;
     const baseHash = event.base_hash;
@@ -240,7 +299,16 @@ export function isTypeDef(declaration) {
         !isPackImport(declaration) &&
         "type" in declaration);
 }
+const TYPE_DEF_FIELDS = [
+    "type", "kind", "title", "description", "schema", "roles", "instructions",
+    "status", "rate_hint", "max_payload_hint", "extra",
+];
 export function validateTypeDef(def) {
+    for (const key of Object.keys(def)) {
+        if (!TYPE_DEF_FIELDS.includes(key)) {
+            throw protocolError("invalid_event", `unknown type definition field: ${key}`);
+        }
+    }
     validateCustomEventTypeName(def.type);
     if (!includes(TYPE_KINDS, def.kind)) {
         throw protocolError("invalid_event", `invalid type kind: ${def.kind}`);
@@ -251,7 +319,15 @@ export function validateTypeDef(def) {
     if (typeof def.schema !== "object" ||
         def.schema === null ||
         Array.isArray(def.schema)) {
-        throw protocolError("invalid_event", "type definition schema must be a JSON Schema object");
+        throw protocolError("invalid_type_schema", "type definition schema must be a JSON Schema object");
+    }
+    try {
+        validateTypeSchemaProfile(def.schema);
+    }
+    catch (error) {
+        if (error instanceof AgentProtocolError)
+            throw error;
+        throw protocolError("invalid_type_schema", `invalid type schema: ${error}`);
     }
     compileSchema(def.schema);
     if (def.roles !== undefined) {
@@ -285,15 +361,23 @@ export function validatePackImport(declaration) {
         }
     }
     else if (hasExternal) {
-        if (declaration.digest.trim() === "") {
-            throw protocolError("invalid_event", "external pack digest must not be empty");
+        if (!/^https:\/\//.test(declaration.pack)) {
+            throw protocolError("invalid_event", "external pack must be an HTTPS URL");
+        }
+        if (!CONTENT_DIGEST_PATTERN.test(declaration.digest)) {
+            throw protocolError("invalid_event", "external pack digest must be <sha256|sha3-256>:<base64url-digest>");
         }
     }
     else {
         throw protocolError("invalid_event", "pack import requires either use, or pack with digest");
     }
-    if (declaration.types !== undefined && declaration.types.length === 0) {
-        throw protocolError("invalid_event", "pack import types subset must not be empty");
+    if (declaration.types !== undefined) {
+        if (declaration.types.length === 0) {
+            throw protocolError("invalid_event", "pack import types subset must not be empty");
+        }
+        if (new Set(declaration.types).size !== declaration.types.length) {
+            throw protocolError("type_conflict", "pack import types subset has duplicates");
+        }
     }
 }
 export function validateTypeDeclaration(declaration) {
@@ -310,36 +394,346 @@ export function validateTypeDeclaration(declaration) {
 function isRegisteredPackId(id) {
     return /^adp:[a-z0-9-]+\/[0-9]+\.[0-9]+$/.test(id);
 }
+// ── Type schema profile (Section 12.3.1).
+const FORBIDDEN_SCHEMA_KEYWORDS = [
+    "$dynamicRef",
+    "$dynamicAnchor",
+    "$recursiveRef",
+    "$recursiveAnchor",
+    "$vocabulary",
+];
+const SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+const ANNOTATION_KEYWORDS = ["format", "contentEncoding", "contentMediaType", "contentSchema"];
+const SUBSCHEMA_KEYWORDS = [
+    "items",
+    "additionalProperties",
+    "not",
+    "if",
+    "then",
+    "else",
+    "contains",
+    "propertyNames",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+    "additionalItems",
+];
+const SUBSCHEMA_ARRAY_KEYWORDS = ["allOf", "anyOf", "oneOf", "prefixItems"];
+const SUBSCHEMA_MAP_KEYWORDS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"];
+/** Calls `visit` on every subschema object of `schema`, depth first. */
+function walkSchema(schema, visit) {
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema))
+        return;
+    const node = schema;
+    visit(node);
+    for (const key of SUBSCHEMA_KEYWORDS)
+        walkSchema(node[key], visit);
+    for (const key of SUBSCHEMA_ARRAY_KEYWORDS) {
+        if (Array.isArray(node[key]))
+            for (const item of node[key])
+                walkSchema(item, visit);
+    }
+    for (const key of SUBSCHEMA_MAP_KEYWORDS) {
+        const map = node[key];
+        if (typeof map === "object" && map !== null && !Array.isArray(map)) {
+            for (const value of Object.values(map))
+                walkSchema(value, visit);
+        }
+    }
+}
+/**
+ * Enforces the type schema profile (Section 12.3.1): fragment-only `$ref`, no
+ * dynamic or recursive references, the 2020-12 dialect, and portable
+ * regular expressions.
+ */
+export function validateTypeSchemaProfile(schema) {
+    walkSchema(schema, (node) => {
+        for (const keyword of FORBIDDEN_SCHEMA_KEYWORDS) {
+            if (keyword in node)
+                throw protocolError("invalid_type_schema", `${keyword} is not allowed`);
+        }
+        if ("$schema" in node && node.$schema !== SCHEMA_DIALECT) {
+            throw protocolError("invalid_type_schema", "$schema must be the draft 2020-12 dialect");
+        }
+        if ("$ref" in node && (typeof node.$ref !== "string" || !node.$ref.startsWith("#"))) {
+            throw protocolError("invalid_type_schema", "$ref must be a fragment inside the schema");
+        }
+        if ("pattern" in node) {
+            if (typeof node.pattern !== "string")
+                throw protocolError("invalid_type_schema", "pattern must be a string");
+            validatePortablePattern(node.pattern);
+        }
+        const patternProperties = node.patternProperties;
+        if (typeof patternProperties === "object" && patternProperties !== null) {
+            for (const key of Object.keys(patternProperties))
+                validatePortablePattern(key);
+        }
+    });
+}
+/**
+ * Checks that a pattern is an I-Regexp (RFC 9485) without `\p{…}`/`\P{…}`
+ * and without `.` outside a character class, optionally anchored with a
+ * leading `^` and a trailing `$` (Section 12.3.1).
+ */
+export function validatePortablePattern(pattern) {
+    const reject = (reason) => {
+        throw protocolError("invalid_type_schema", `pattern ${JSON.stringify(pattern)} is not portable: ${reason}`);
+    };
+    let body = pattern;
+    if (body.startsWith("^"))
+        body = body.slice(1);
+    if (body.endsWith("$") && !body.endsWith("\\$"))
+        body = body.slice(0, -1);
+    const chars = [...body];
+    let i = 0;
+    let depth = 0;
+    let canQuantify = false;
+    const singleEscapes = "()*+-.?[\\]^{|}nrt";
+    const readEscape = () => {
+        const next = chars[i + 1];
+        if (next === undefined)
+            reject("dangling escape");
+        if (!singleEscapes.includes(next))
+            reject(`escape \\${next}`);
+        i += 2;
+    };
+    while (i < chars.length) {
+        const ch = chars[i];
+        if (ch === "\\") {
+            readEscape();
+            canQuantify = true;
+        }
+        else if (ch === "[") {
+            i += 1;
+            if (chars[i] === "^")
+                i += 1;
+            // A leading `]` is literal in some engines and an empty class in others.
+            if (chars[i] === "]")
+                reject("empty character class");
+            while (i < chars.length && chars[i] !== "]") {
+                if (chars[i] === "\\")
+                    readEscape();
+                else if (chars[i] === "[")
+                    reject("nested character class");
+                else
+                    i += 1;
+            }
+            if (chars[i] !== "]")
+                reject("unterminated character class");
+            i += 1;
+            canQuantify = true;
+        }
+        else if (ch === "(") {
+            if (chars[i + 1] === "?")
+                reject("group modifiers");
+            depth += 1;
+            i += 1;
+            canQuantify = false;
+        }
+        else if (ch === ")") {
+            if (depth === 0)
+                reject("unbalanced parenthesis");
+            depth -= 1;
+            i += 1;
+            canQuantify = true;
+        }
+        else if (ch === "|") {
+            i += 1;
+            canQuantify = false;
+        }
+        else if (ch === "*" || ch === "+" || ch === "?") {
+            if (!canQuantify)
+                reject("quantifier without operand");
+            i += 1;
+            if (chars[i] === "?" || chars[i] === "+")
+                reject("lazy or possessive quantifier");
+            canQuantify = false;
+        }
+        else if (ch === "{") {
+            if (!canQuantify)
+                reject("quantifier without operand");
+            const rest = chars.slice(i).join("");
+            const match = /^\{[0-9]+(,[0-9]*)?\}/.exec(rest);
+            if (!match)
+                reject("malformed quantifier");
+            i += [...match[0]].length;
+            if (chars[i] === "?" || chars[i] === "+")
+                reject("lazy or possessive quantifier");
+            canQuantify = false;
+        }
+        else if (ch === ".") {
+            reject("'.' outside a character class");
+        }
+        else if (ch === "^" || ch === "$") {
+            reject("anchor inside the pattern");
+        }
+        else if (ch === "}" || ch === "]") {
+            reject(`unescaped ${ch}`);
+        }
+        else {
+            i += 1;
+            canQuantify = true;
+        }
+    }
+    if (depth !== 0)
+        reject("unbalanced parenthesis");
+}
+/** A copy of `schema` without annotation-only keywords, which validators must not assert. */
+function stripAnnotations(schema) {
+    const copy = structuredClone(schema);
+    walkSchema(copy, (node) => {
+        for (const keyword of ANNOTATION_KEYWORDS)
+            delete node[keyword];
+    });
+    return copy;
+}
+const ROOM_POLICY_FIELDS = ["invites", "open_roles", "max_speakers", "observer_allowed", "extra"];
+/** Section 8.3 rules for a room policy. */
+export function validateRoomPolicy(policy) {
+    if (policy === undefined)
+        return;
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        throw protocolError("invalid_event", "policy must be an object");
+    }
+    for (const key of Object.keys(policy)) {
+        if (!ROOM_POLICY_FIELDS.includes(key))
+            throw protocolError("invalid_event", `unknown policy field: ${key}`);
+    }
+    const maxSpeakers = policy.max_speakers;
+    if (maxSpeakers !== undefined &&
+        (!Number.isInteger(maxSpeakers) || maxSpeakers < 1)) {
+        throw protocolError("invalid_event", "max_speakers must be a positive integer");
+    }
+    const observerAllowed = policy.observer_allowed ?? true;
+    if (policy.invites !== undefined) {
+        if (typeof policy.invites !== "object" || policy.invites === null || Array.isArray(policy.invites)) {
+            throw protocolError("invalid_event", "invites must be an object");
+        }
+        for (const [agentId, role] of Object.entries(policy.invites)) {
+            validateAgentId(agentId);
+            if (!includes(ROLES, role))
+                throw protocolError("invalid_event", `invalid invited role: ${role}`);
+            if (role === "observer" && !observerAllowed)
+                throw protocolError("role_not_allowed", "observers are not allowed");
+        }
+    }
+    if (policy.open_roles !== undefined) {
+        if (!Array.isArray(policy.open_roles) || new Set(policy.open_roles).size !== policy.open_roles.length) {
+            throw protocolError("invalid_event", "open_roles must be a list of unique roles");
+        }
+        for (const role of policy.open_roles) {
+            if (role !== "speaker" && role !== "observer")
+                throw protocolError("invalid_event", `open_roles cannot contain ${role}`);
+            if (role === "observer" && !observerAllowed)
+                throw protocolError("role_not_allowed", "observers are not allowed");
+        }
+    }
+}
+/**
+ * Section 8.3 rule tying the policy to the room's visibility: a private room
+ * admits agents only by invitation or review, so its `open_roles` must be empty.
+ */
+export function validateRoomVisibilityPolicy(visibility, policy) {
+    if (visibility === "private" && (policy?.open_roles?.length ?? 0) > 0) {
+        throw protocolError("invalid_event", "a private room cannot have open roles");
+    }
+}
+/**
+ * The roles any agent may take by direct `room.join` (Section 8.3): the
+ * explicit `open_roles`, or by default `observer` in a public room when
+ * observers are allowed, and none otherwise.
+ */
+export function effectiveOpenRoles(visibility, policy) {
+    if (policy?.open_roles !== undefined)
+        return [...policy.open_roles];
+    return visibility === "public" && policy?.observer_allowed !== false ? ["observer"] : [];
+}
+/**
+ * Section 9.2 direct-join eligibility: the actor is invited with exactly
+ * `role`, or `role` is one of the room's effective open roles. Bans and
+ * quotas are separate host checks.
+ */
+export function canJoinDirectly(visibility, policy, actor, role) {
+    if (policy?.invites?.[actor] === role)
+        return true;
+    return effectiveOpenRoles(visibility, policy).includes(role);
+}
 export function validateRoomCreatePayload(payload) {
+    try {
+        validateOrigin(payload.host);
+    }
+    catch {
+        throw protocolError("invalid_event", "room.create host must be an HTTPS origin");
+    }
     if (payload.topic.trim() === "") {
         throw protocolError("invalid_event", "room topic must not be empty");
     }
     if (payload.start_time >= payload.end_time) {
         throw protocolError("invalid_event", "start_time must be before end_time");
     }
-    const maxSpeakers = payload.policy?.max_speakers;
-    if (maxSpeakers !== undefined &&
-        (!Number.isInteger(maxSpeakers) || maxSpeakers < 1)) {
-        throw protocolError("invalid_event", "max_speakers must be a positive integer");
-    }
+    validateRoomPolicy(payload.policy);
+    validateRoomVisibilityPolicy(payload.visibility, payload.policy);
     for (const declaration of payload.types ?? []) {
         validateTypeDeclaration(declaration);
     }
 }
+/** Host binding check (Section 8.1): `host` must be the receiving host's API origin. */
+export function validateRoomCreateHost(payload, hostOrigin) {
+    if (payload.host !== hostOrigin) {
+        throw protocolError("host_mismatch", `room.create names ${payload.host}, not ${hostOrigin}`);
+    }
+}
 export function validateMessageCreatePayload(payload) {
-    if (payload.content_type.trim() === "") {
+    if (typeof payload.content_type !== "string" || payload.content_type.trim() === "") {
         throw protocolError("invalid_event", "content_type must not be empty");
     }
+    const content = payload.content;
+    if (typeof content !== "string" && (typeof content !== "object" || content === null || Array.isArray(content))) {
+        throw protocolError("invalid_event", "content must be a string or an object");
+    }
 }
 export function validateRoomJoinPayload(payload) {
+    for (const key of Object.keys(payload)) {
+        if (key !== "role" && key !== "perspective") {
+            throw protocolError("invalid_event", `unknown room.join payload field: ${key}`);
+        }
+    }
+    if (!includes(ROLES, payload.role)) {
+        throw protocolError("invalid_event", `invalid room role: ${payload.role}`);
+    }
+}
+export function validateRoomJoinRequestPayload(payload) {
+    for (const key of Object.keys(payload)) {
+        if (!["role", "perspective", "reason", "extra"].includes(key)) {
+            throw protocolError("invalid_event", `unknown room.join.request payload field: ${key}`);
+        }
+    }
     if (!includes(ROLES, payload.role)) {
         throw protocolError("invalid_event", `invalid room role: ${payload.role}`);
     }
-    if (payload.request_id !== undefined && payload.request_id.trim() === "") {
-        throw protocolError("invalid_event", "request_id must not be empty");
+}
+/**
+ * Verifies a signed `room.join.request` envelope for embedding or review:
+ * hash, signature, and shape — historical verification, without the live
+ * time window or nonce check.
+ */
+export function validateJoinRequestEnvelope(envelope, roomId) {
+    validateDiscourseEnvelope(envelope);
+    if (envelope.event.type !== eventType.ROOM_JOIN_REQUEST) {
+        throw protocolError("invalid_event", "embedded request must be a room.join.request");
+    }
+    if (roomId !== undefined && envelope.event.room_id !== roomId) {
+        throw protocolError("room_id_mismatch", "join request belongs to another room");
+    }
+    validateRoomJoinRequestPayload(envelope.event.payload);
+}
+/** Shape checks for `room.join.review`, including the embedded signed request. */
+export function validateRoomJoinReviewPayload(payload, roomId) {
+    validateJoinRequestEnvelope(payload.request, roomId);
+    if (payload.decision !== "approve" && payload.decision !== "reject") {
+        throw protocolError("invalid_event", `invalid review decision: ${payload.decision}`);
     }
-    if (payload.request_id !== undefined && payload.perspective !== undefined) {
-        throw protocolError("invalid_event", "room.join payload cannot include both request_id and perspective");
+    if (payload.decision === "approve" && !includes(ROLES, payload.role)) {
+        throw protocolError("invalid_event", "an approving review requires a role");
     }
 }
 const ROOM_UPDATE_FIELDS = [
@@ -375,11 +769,7 @@ export function validateRoomUpdatePayload(payload) {
         payload.start_time >= payload.end_time) {
         throw protocolError("invalid_event", "start_time must be before end_time");
     }
-    const maxSpeakers = payload.policy?.max_speakers;
-    if (maxSpeakers !== undefined &&
-        (!Number.isInteger(maxSpeakers) || maxSpeakers < 1)) {
-        throw protocolError("invalid_event", "max_speakers must be a positive integer");
-    }
+    validateRoomPolicy(payload.policy);
 }
 /**
  * Shape checks for a `room.member.remove` payload. Creator, self, and
@@ -395,36 +785,43 @@ export function validateRoomMemberRemovePayload(payload) {
 export class TypeRegistry {
     types = new Map();
     /**
-     * Materializes a registry from declarations, resolving pack imports from
-     * `packs`, keyed by registered pack id or external pack URI.
+     * Materializes a registry from the `room.create` declarations, resolving
+     * pack imports from `packs`, keyed by registered pack id or external pack
+     * URI. A type name may appear only once across these declarations.
      */
     static fromDeclarations(declarations, packs = {}) {
         const registry = new TypeRegistry();
+        const declared = new Set();
         for (const declaration of declarations) {
-            registry.apply(declaration, packs);
+            for (const name of registry.apply(declaration, packs)) {
+                if (declared.has(name)) {
+                    throw protocolError("type_conflict", `type ${name} is declared twice`);
+                }
+                declared.add(name);
+            }
         }
         return registry;
     }
     /**
-     * Applies one declaration: an inline definition or a pack import.
-     * Redefining an existing type replaces it; the latest definition wins.
+     * Applies one declaration — an inline definition or a pack import — and
+     * returns the type names it declared. Declaring an existing type is a
+     * redefinition: it must keep the type's kind, and the latest definition wins.
      */
     apply(declaration, packs = {}) {
         if (isPackImport(declaration)) {
-            this.import(declaration, packs);
+            return this.import(declaration, packs);
         }
-        else if (isTypeDef(declaration)) {
+        if (isTypeDef(declaration)) {
             this.define(declaration);
+            return [declaration.type];
         }
-        else {
-            throw protocolError("invalid_event", "type declaration must be an inline definition or a pack import");
-        }
+        throw protocolError("invalid_event", "type declaration must be an inline definition or a pack import");
     }
     define(def) {
         validateTypeDef(def);
         const existing = this.types.get(def.type);
         if (existing && existing.kind !== def.kind) {
-            throw protocolError("invalid_event", `type ${def.type} cannot change kind from ${existing.kind} to ${def.kind}`);
+            throw protocolError("type_conflict", `type ${def.type} cannot change kind from ${existing.kind} to ${def.kind}`);
         }
         this.types.set(def.type, def);
     }
@@ -435,25 +832,34 @@ export class TypeRegistry {
         if (!pack) {
             throw protocolError("pack_unavailable", `pack not available: ${reference}`);
         }
-        const available = new Set(pack.types.map((def) => def.type));
+        const available = new Set();
+        for (const def of pack.types) {
+            if (available.has(def.type)) {
+                throw protocolError("type_conflict", `pack ${reference} defines ${def.type} twice`);
+            }
+            available.add(def.type);
+        }
         for (const name of declaration.types ?? []) {
             if (!available.has(name)) {
-                throw protocolError("pack_unavailable", `type ${name} is not in pack ${reference}`);
+                throw protocolError("type_conflict", `type ${name} is not in pack ${reference}`);
             }
         }
         const subset = declaration.types !== undefined ? new Set(declaration.types) : undefined;
         for (const name of Object.keys(declaration.overrides ?? {})) {
             const imported = subset ? subset.has(name) : available.has(name);
             if (!imported) {
-                throw protocolError("invalid_event", `override target ${name} is not imported from pack ${reference}`);
+                throw protocolError("type_conflict", `override target ${name} is not imported from pack ${reference}`);
             }
         }
+        const declared = [];
         for (const def of pack.types) {
             if (subset && !subset.has(def.type))
                 continue;
             const override = declaration.overrides?.[def.type];
             this.define(override ? { ...def, ...override } : { ...def });
+            declared.push(def.type);
         }
+        return declared;
     }
     get(type) {
         return this.types.get(type);
@@ -498,10 +904,11 @@ export function validateEventAgainstRegistry(type, payload, registry) {
 }
 function compileSchema(schema) {
     try {
-        return new Validator(schema, "2020-12", false);
+        // Annotation keywords are never asserted (Section 12.3.1).
+        return new Validator(stripAnnotations(schema), "2020-12", false);
     }
     catch (error) {
-        throw protocolError("invalid_event", `invalid type schema: ${error}`);
+        throw protocolError("invalid_type_schema", `invalid type schema: ${error}`);
     }
 }
 /**
@@ -509,15 +916,12 @@ function compileSchema(schema) {
  * Supports `sha256` and `sha3-256`.
  */
 export function verifyPackDigest(bytes, digest) {
-    const separator = digest.indexOf(":");
-    if (separator < 0) {
+    if (!CONTENT_DIGEST_PATTERN.test(digest)) {
         throw protocolError("pack_unavailable", `invalid digest format: ${digest}`);
     }
+    const separator = digest.indexOf(":");
     const algorithm = digest.slice(0, separator);
     const expected = digest.slice(separator + 1);
-    if (algorithm !== "sha256" && algorithm !== "sha3-256") {
-        throw protocolError("pack_unavailable", `unsupported digest algorithm: ${algorithm}`);
-    }
     const actual = createHash(algorithm)
         .update(bytes)
         .digest("base64url");
@@ -525,34 +929,57 @@ export function verifyPackDigest(bytes, digest) {
         throw protocolError("pack_unavailable", "pack digest mismatch");
     }
 }
-export function serverRecordHashPayload(roomId, seq, preHash, envelopeHash, receivedAt) {
+export function serverRecordHashPayload(roomId, seq, preHash, envelopeHash, acceptedAt) {
     return {
         room_id: roomId,
         seq,
         pre_hash: preHash ?? null,
         envelope_hash: envelopeHash,
-        received_at: receivedAt,
+        accepted_at: acceptedAt,
     };
 }
-export function serverRecordHash(roomId, seq, preHash, envelopeHash, receivedAt) {
-    return hashCanonicalJson(serverRecordHashPayload(roomId, seq, preHash, envelopeHash, receivedAt));
+export function serverRecordHash(roomId, seq, preHash, envelopeHash, acceptedAt) {
+    return hashCanonicalJson(serverRecordHashPayload(roomId, seq, preHash, envelopeHash, acceptedAt));
 }
-export function buildServerRecord(roomId, seq, preHash, receivedAt, envelope) {
+export function buildServerRecord(roomId, seq, preHash, acceptedAt, envelope) {
     const normalizedPreHash = preHash ?? null;
     return {
         room_id: roomId,
         seq,
         pre_hash: normalizedPreHash,
-        hash: serverRecordHash(roomId, seq, normalizedPreHash, envelope.hash, receivedAt),
-        received_at: receivedAt,
+        hash: serverRecordHash(roomId, seq, normalizedPreHash, envelope.hash, acceptedAt),
+        accepted_at: acceptedAt,
         envelope,
     };
 }
+export function isRedactedEnvelope(value) {
+    return typeof value === "object" && value !== null && value.redacted === true;
+}
+export function isRedactedRecord(record) {
+    return isRedactedEnvelope(record.envelope);
+}
+/**
+ * Replaces a record's envelope with its redacted form (Section 14.1). Only
+ * `message.create` and custom-type records may be redacted.
+ */
+export function redactServerRecord(record) {
+    const type = record.envelope.event.type;
+    if (isBuiltinEventType(type) && type !== eventType.MESSAGE_CREATE) {
+        throw protocolError("invalid_event", `${type} records cannot be redacted`);
+    }
+    return { ...record, envelope: { hash: record.envelope.hash, redacted: true, type } };
+}
 export function verifyServerRecord(record) {
-    const expected = serverRecordHash(record.room_id, record.seq, record.pre_hash, record.envelope.hash, record.received_at);
+    const expected = serverRecordHash(record.room_id, record.seq, record.pre_hash, record.envelope.hash, record.accepted_at);
     if (record.hash !== expected) {
         throw protocolError("invalid_record_hash", `invalid server record hash: expected ${expected}, got ${record.hash}`);
     }
+    if (isRedactedRecord(record)) {
+        const type = record.envelope.type;
+        if (isBuiltinEventType(type) && type !== eventType.MESSAGE_CREATE) {
+            throw protocolError("invalid_record_chain", `${type} records cannot be redacted`);
+        }
+    }
 }
 export function verifyServerRecordChain(records) {
     let previous;
@@ -575,8 +1002,29 @@ export function verifyServerRecordChain(records) {
         previous = record;
     }
 }
-export function archiveEventsDigest(records) {
-    return hashCanonicalJson(records);
+/**
+ * Archive verification steps 1–3 (Section 18): a gap-free chain from seq 1 to
+ * `last_seq` ending in `last_hash`, and a valid signature on every record that
+ * is not redacted. Returns the sequence numbers of redacted records, which
+ * verifiers must report. State replay (step 4) is the caller's.
+ */
+export function verifyArchiveRecords(manifest, records) {
+    verifyServerRecordChain(records);
+    const last = records[records.length - 1];
+    if (!last || last.seq !== manifest.last_seq || last.hash !== manifest.last_hash) {
+        throw protocolError("invalid_record_chain", "archive does not end at last_seq / last_hash");
+    }
+    const redacted = [];
+    for (const record of records) {
+        if (record.room_id !== manifest.room_id) {
+            throw protocolError("invalid_record_chain", "record belongs to another room");
+        }
+        if (isRedactedRecord(record))
+            redacted.push(record.seq);
+        else
+            validateDiscourseEnvelope(record.envelope);
+    }
+    return redacted;
 }
 /** Default sender roles for each kind. The creator passes every role check. */
 export function defaultKindRoles(kind) {
@@ -598,9 +1046,12 @@ export function canSubmitEvent(type, context, registry = new TypeRegistry()) {
         case eventType.ROOM_CREATE:
             return true;
         case eventType.ROOM_JOIN:
-            return Boolean(context.publicJoinAllowed || context.joinRequestApproved);
+            return Boolean(context.directJoinAllowed) && !context.isCreator && context.role === undefined;
+        case eventType.ROOM_JOIN_REQUEST:
+            return !context.isCreator && context.role === undefined;
         case eventType.ROOM_LEAVE:
-            return Boolean(context.isCreator) || context.role !== undefined;
+            // The creator is a member until the room ends and cannot leave.
+            return !context.isCreator && context.role !== undefined;
         case eventType.ROOM_UPDATE:
         case eventType.ROOM_JOIN_REVIEW:
         case eventType.ROOM_MEMBER_ROLE_UPDATE:
@@ -629,7 +1080,8 @@ export function canSubmitEvent(type, context, registry = new TypeRegistry()) {
 export function canWriteInState(type, state) {
     switch (state) {
         case "scheduled":
-            return (type === eventType.ROOM_JOIN ||
+            return (type === eventType.ROOM_JOIN_REQUEST ||
+                type === eventType.ROOM_JOIN ||
                 type === eventType.ROOM_JOIN_REVIEW ||
                 type === eventType.ROOM_MEMBER_ROLE_UPDATE ||
                 type === eventType.ROOM_MEMBER_REMOVE ||