@canonmsg/backend-contracts 8.5.0 → 8.6.0

package/dist/cjs/endpoint-unread.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeEndpointUnreadProjection = computeEndpointUnreadProjection;
+/** Metadata-only unread projection, shared by serving and the offline migration. */
+function computeEndpointUnreadProjection(principalId, conversation, member) {
+    if (!conversation || !member || !Array.isArray(conversation.memberIds) || !conversation.memberIds.includes(principalId))
+        return null;
+    const message = conversation.lastMessage;
+    if (!message || typeof message.senderId !== 'string' || message.senderId === principalId)
+        return null;
+    const at = time(message.timestamp);
+    if (at === null)
+        return null;
+    const floor = time(member.historyStartAt), read = time(member.lastReadTimestamp), deleted = time(member.deletedAt);
+    if ((floor !== null && at < floor) || (read !== null && at <= read) || (deleted !== null && at <= deleted))
+        return null;
+    return { unmutedAtMs: time(member.mutedUntil) ?? 0 };
+}
+function time(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string') {
+        const ms = Date.parse(value);
+        return Number.isFinite(ms) ? ms : null;
+    }
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value !== 'object')
+        return null;
+    const timestamp = value;
+    const ms = typeof timestamp.toMillis === 'function' ? timestamp.toMillis() : typeof timestamp.toDate === 'function' ? timestamp.toDate().getTime()
+        : typeof timestamp.seconds === 'number' ? timestamp.seconds * 1000 + (timestamp.nanoseconds ?? 0) / 1e6 : NaN;
+    return Number.isFinite(ms) ? ms : null;
+}

package/dist/cjs/endpoint.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENDPOINT_ACTION_PATTERN = exports.ENDPOINT_ID_PATTERN = exports.CANON_ENDPOINT_PROTOCOL = void 0;
+exports.isEndpointOperationRequest = isEndpointOperationRequest;
+exports.isEndpointOperationReceipt = isEndpointOperationReceipt;
+/** Plaintext endpoint protocol. Identity and authority come from authenticated transport. */
+exports.CANON_ENDPOINT_PROTOCOL = 'canon.endpoint.v1';
+exports.ENDPOINT_ID_PATTERN = /^[A-Za-z0-9_.:~-]{1,200}$/;
+exports.ENDPOINT_ACTION_PATTERN = /^[a-z][a-z0-9_.-]{0,95}$/;
+function isEndpointOperationRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const request = value;
+    const body = request.body;
+    return request.protocol === exports.CANON_ENDPOINT_PROTOCOL
+        && typeof request.operationId === 'string' && exports.ENDPOINT_ID_PATTERN.test(request.operationId)
+        && typeof request.installationId === 'string' && exports.ENDPOINT_ID_PATTERN.test(request.installationId)
+        && typeof request.action === 'string' && exports.ENDPOINT_ACTION_PATTERN.test(request.action)
+        && (request.ownershipVersion === undefined || Number.isSafeInteger(request.ownershipVersion) && request.ownershipVersion >= 0)
+        && !!body && body.encoding === 'json'
+        && !!body.value && typeof body.value === 'object' && !Array.isArray(body.value);
+}
+function isEndpointOperationReceipt(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const receipt = value;
+    return receipt.protocol === exports.CANON_ENDPOINT_PROTOCOL
+        && typeof receipt.operationId === 'string' && exports.ENDPOINT_ID_PATTERN.test(receipt.operationId)
+        && typeof receipt.installationId === 'string' && exports.ENDPOINT_ID_PATTERN.test(receipt.installationId)
+        && typeof receipt.action === 'string' && exports.ENDPOINT_ACTION_PATTERN.test(receipt.action)
+        && ['pending', 'succeeded', 'rejected', 'uncertain'].includes(String(receipt.status))
+        && typeof receipt.createdAt === 'string' && typeof receipt.updatedAt === 'string';
+}

package/dist/cjs/endpointContentPolicy.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EndpointContentPolicyError = exports.ENDPOINT_CONTENT_EVENTS = exports.ENDPOINT_CONTENT_EPHEMERAL_FAMILIES = exports.ENDPOINT_CONTENT_EPHEMERALS = exports.ENDPOINT_CONTENT_QUERIES = exports.ENDPOINT_CONTENT_FUNCTION_QUERIES = exports.ENDPOINT_CONTENT_ACTIONS = void 0;
+exports.endpointOperationRequestRetention = endpointOperationRequestRetention;
+exports.endpointContentBoundary = endpointContentBoundary;
+const verbWire_js_1 = require("./verbWire.js");
+exports.ENDPOINT_CONTENT_ACTIONS = [
+    'initialize_endpoint',
+    'sync_phone_contacts', 'request_work_session', 'resolve_work_session_request',
+    'update_agent_behavior_policy', 'update_conversation_agent_behavior_policy',
+    'send_message', 'delete_message', 'forward_message', 'react', 'verb_execute',
+    'send_contextual_message', 'create_interaction', 'consume_interaction',
+    'start_conversation', 'create_conversation', 'add_member', 'remove_member',
+    'leave_conversation', 'update_member_role', 'update_conversation', 'rename_conversation',
+    'update_topic', 'update_group_avatar', 'mark_read', 'cancel_queued_message',
+    'set_conversation_preferences', 'set_block', 'save_contact', 'remove_contact',
+    'respond_interaction', 'session_control', 'approve_contact_request',
+    'reject_contact_request', 'cancel_direct_request', 'update_message_disposition',
+    'create_upload', 'finalize_upload', 'delete_upload', 'retry_video_processing',
+    'finalize_memo_stream', 'abort_memo_stream', 'create_voice_session',
+    'join_voice_session', 'decline_voice_session', 'end_voice_session',
+    'consume_runtime_signal', 'generate_image',
+];
+exports.ENDPOINT_CONTENT_FUNCTION_QUERIES = [
+    'discover_agents', 'get_unread_summary', 'peek_runtime_signal',
+    'get_work_session_catalog', 'get_work_session_request', 'get_agent_behavior_policy',
+    'get_conversation_agent_behavior_policy', 'get_ephemeral', 'list_voice_sessions',
+    'list_contact_requests', 'list_conversations', 'list_messages', 'get_messages',
+    'admission_fences', 'list_contacts', 'get_contact', 'get_members', 'resolve_admission',
+    'resolve_group_admission', 'get_runtime_card_state', 'conversation',
+    'conversation_changes', 'get_upload', 'get_voice_session', 'get_image_generation',
+    'get_image_generation_status',
+];
+exports.ENDPOINT_CONTENT_QUERIES = [...exports.ENDPOINT_CONTENT_FUNCTION_QUERIES, 'admit_messages'];
+exports.ENDPOINT_CONTENT_EPHEMERALS = [
+    'create_memo_stream', 'publish_presence', 'publish_typing', 'publish_streaming',
+    'publish_turn', 'publish_runtime_status', 'append_memo_chunk',
+];
+exports.ENDPOINT_CONTENT_EPHEMERAL_FAMILIES = [
+    'typing', 'streaming', 'turn-state', 'agent-session', 'runtime-card-state',
+    'memo-streams', 'runtime-info', 'runtime-activity', 'runtime-suppression',
+    'runtime-silence', 'runtime-attention', 'call-attention', 'agent-runtime', 'presence',
+];
+exports.ENDPOINT_CONTENT_EVENTS = [
+    'connected', 'heartbeat', 'agent.context', 'replay.expired',
+    'message.created', 'message.snapshot', 'message.updated', 'message.deleted',
+    'message.media_terminal', 'conversation.updated', 'conversation.changed',
+    'conversation.removed', 'conversations.changed', 'contacts.changed',
+    'contact.added', 'contact.updated', 'contact.removed', 'presence', 'typing',
+    'runtime.updated', 'runtime.control', 'turn.updated',
+    'voice.session.started', 'voice.session.ended',
+    ...exports.ENDPOINT_CONTENT_EPHEMERAL_FAMILIES.map((family) => `ephemeral.${family}`),
+];
+class EndpointContentPolicyError extends Error {
+    code = 'ENDPOINT_CONTENT_UNCLASSIFIED';
+    constructor(lane, name) {
+        super(`Unclassified endpoint lane: ${lane}/${name}`);
+        this.name = 'EndpointContentPolicyError';
+    }
+}
+exports.EndpointContentPolicyError = EndpointContentPolicyError;
+const namesForLane = {
+    'operation.request': exports.ENDPOINT_CONTENT_ACTIONS,
+    'operation.receipt': exports.ENDPOINT_CONTENT_ACTIONS,
+    'query.request': exports.ENDPOINT_CONTENT_QUERIES,
+    'query.result': exports.ENDPOINT_CONTENT_QUERIES,
+    'ephemeral.request': exports.ENDPOINT_CONTENT_EPHEMERALS,
+    'ephemeral.result': exports.ENDPOINT_CONTENT_EPHEMERALS,
+    event: exports.ENDPOINT_CONTENT_EVENTS,
+};
+/** An explicit allowlist of routing/authorization fields, not a rule that all
+ * fields named `id` are public. Free text, previews, labels, media descriptors,
+ * paths, provider configuration, native snapshots and arbitrary metadata stay
+ * private. IDs/cursors/timing still reveal a communication graph. */
+const protocolPaths = [
+    'protocol', 'operationId', 'installationId', 'action', 'ownershipVersion',
+    'preconditions.conversationId', 'preconditions.membershipRevision',
+    'preconditions.admissionId', 'preconditions.targetAdmissionId', 'body.encoding',
+];
+// Fields are reviewed for a particular lane: e.g. an unknown `contactId` added
+// to send_message is still private, despite being a routing ID elsewhere.
+const actionRouting = {
+    send_message: ['conversationId', 'messageId', 'replyTo', 'mentions.*'],
+    delete_message: ['conversationId', 'messageId'], forward_message: ['sourceConversationId', 'targetConversationId', 'messageId'],
+    react: ['conversationId', 'messageId'], send_contextual_message: ['conversationId'],
+    create_interaction: ['conversationId', 'requestId', 'inputId', 'approvalId', 'cardId', 'planId', 'responseUserId'],
+    consume_interaction: ['conversationId', 'inputId', 'approvalId', 'cardId', 'planId'],
+    respond_interaction: ['conversationId', 'requestId'],
+    start_conversation: ['targetUserId'], create_conversation: ['memberIds.*'],
+    add_member: ['conversationId', 'userId', 'agentId'], remove_member: ['conversationId', 'userId', 'agentId', 'targetUserId'],
+    leave_conversation: ['conversationId'], update_member_role: ['conversationId', 'userId', 'targetUserId'],
+    update_conversation: ['conversationId'], rename_conversation: ['conversationId'], update_topic: ['conversationId'],
+    update_group_avatar: ['conversationId'], mark_read: ['conversationId'], cancel_queued_message: ['conversationId', 'messageId'],
+    set_conversation_preferences: ['conversationId'], set_block: ['targetUserId'], save_contact: ['contactUserId'], remove_contact: ['contactId', 'contactUserId'],
+    session_control: ['conversationId', 'agentId'], approve_contact_request: ['requestId'], reject_contact_request: ['requestId'], cancel_direct_request: ['requestId'],
+    update_message_disposition: ['conversationId', 'messageId'], create_upload: ['conversationId'], finalize_upload: ['uploadId'], delete_upload: ['uploadId'], retry_video_processing: ['uploadId'],
+    finalize_memo_stream: ['conversationId', 'streamId'], abort_memo_stream: ['streamId'],
+    create_voice_session: ['conversationId'], join_voice_session: ['conversationId', 'sessionId'], decline_voice_session: ['conversationId', 'sessionId'], end_voice_session: ['conversationId', 'sessionId'],
+    consume_runtime_signal: ['conversationId', 'expectedSignalId'], generate_image: ['conversationId', 'requestId'],
+    request_work_session: ['conversationId', 'agentId', 'requestId'], resolve_work_session_request: ['requestId'],
+    update_agent_behavior_policy: ['agentId'], update_conversation_agent_behavior_policy: ['conversationId', 'agentId'],
+};
+const queryRouting = {
+    admit_messages: ['conversationId', 'messageIds.*', 'admissionId'], conversation_changes: ['conversationId', 'cursor', 'limit'],
+    conversation: ['conversationId'], list_conversations: ['limit', 'before'], list_messages: ['conversationId', 'before', 'limit'], get_messages: ['conversationId', 'messageIds.*'],
+    list_contacts: ['limit', 'before'], get_contact: ['contactId', 'contactUserId', 'userId'], get_members: ['conversationId'],
+    list_contact_requests: ['direction', 'limit', 'before'], admission_fences: ['conversationId', 'targetUserId'],
+    resolve_admission: ['targetUserId'], resolve_group_admission: ['conversationId', 'targetUserId'], get_runtime_card_state: ['conversationId', 'cardId'],
+    get_ephemeral: ['family', 'scopeId'], peek_runtime_signal: ['conversationId'], list_voice_sessions: ['conversationId', 'limit'],
+    get_upload: ['uploadId'], get_voice_session: ['conversationId', 'sessionId'], get_image_generation: ['requestId'],
+    get_work_session_catalog: ['agentId'], get_work_session_request: ['requestId'], get_agent_behavior_policy: ['agentId'], get_conversation_agent_behavior_policy: ['conversationId', 'agentId'],
+};
+const transientRouting = {
+    create_memo_stream: ['conversationId', 'streamId'], append_memo_chunk: ['streamId'],
+    publish_presence: [], publish_typing: ['conversationId'], publish_streaming: ['conversationId'], publish_turn: ['conversationId'], publish_runtime_status: ['conversationId'],
+};
+function eventRouting(name) {
+    if (name.startsWith('ephemeral.'))
+        return ['conversationId', 'scopeId'];
+    if (name === 'connected')
+        return ['protocol', 'connectionId', 'agentId', 'principalId', 'principalType'];
+    if (name === 'heartbeat')
+        return ['timestamp'];
+    if (name === 'agent.context')
+        return ['agentId', 'ownerId', 'ownershipVersion'];
+    if (name === 'conversations.changed')
+        return ['conversationIds.*', 'removedConversationIds.*'];
+    if (name.startsWith('message.'))
+        return ['conversationId', 'messageId', 'eventId', 'id', 'message.id', 'message.conversationId', 'message.senderId', 'message.senderType', 'message.createdAt', 'message.replyTo', 'message.mentions.*'];
+    if (name.startsWith('conversation.'))
+        return ['conversationId'];
+    if (name.startsWith('contact.'))
+        return ['contactId'];
+    if (name.startsWith('voice.session.'))
+        return ['conversationId', 'sessionId'];
+    if (/^(runtime\.|turn\.|typing$|presence$)/.test(name))
+        return ['conversationId', 'agentId', 'userId', 'memberId'];
+    return [];
+}
+const secretSegments = new Set(['token', 'accessToken', 'refreshToken', 'uploadUrl', 'signedUrl', 'livekitToken', 'replyAuthority', 'credentials', 'password', 'secret', 'authorization', 'answer', 'answers', 'response', 'submittedValue']);
+const matches = (path, pattern) => {
+    const parts = pattern.split('.');
+    return parts.length === path.length && parts.every((part, index) => part === path[index] || part === '*' && /^\d+$/.test(path[index]));
+};
+const publicMatch = (path, patterns) => patterns.some((pattern) => matches(path, pattern));
+/** Local journal policy is separate from wire classification. Input answers and
+ * card values can carry passwords even when the response omits the original
+ * request's secret/sudo/field metadata. Only reviewed response shapes without
+ * those value bags may be retried from durable storage. Unknown response fields
+ * fail closed; a caller's `sensitive: false` cannot weaken this policy. */
+function endpointOperationRequestRetention(action, body, envelope) {
+    if (action !== 'respond_interaction')
+        return 'journal';
+    // Interaction services use the body exclusively. Unknown envelope additions
+    // must not bypass retention, including conflicting fields rejected by server.
+    if (envelope && Object.keys(envelope).length > 0)
+        return 'memory';
+    const routing = ['kind', 'conversationId', 'agentId', 'requestId'];
+    const hasOnly = (fields) => Object.keys(body).every((field) => fields.includes(field));
+    if (routing.some((field) => body[field] !== undefined && typeof body[field] !== 'string'))
+        return 'memory';
+    if ((body.kind === 'input' || body.kind === 'card') && hasOnly([...routing, 'status', 'actionId'])) {
+        if (!['submitted', 'cancelled'].includes(String(body.status)) || (body.actionId !== undefined && typeof body.actionId !== 'string'))
+            return 'memory';
+        // A card button or cancellation with no submitted values contains no answer
+        // plaintext. Input/card requests with value, answers or values stay in RAM,
+        // including non-secret clarification: that distinction is absent on wire.
+        return 'journal';
+    }
+    if (body.kind === 'approval' && hasOnly([...routing, 'decision', 'sessionRule'])) {
+        if (body.decision !== 'allow' && body.decision !== 'deny')
+            return 'memory';
+        const rule = body.sessionRule;
+        if (rule !== undefined && (!rule || typeof rule !== 'object' || Array.isArray(rule)
+            || !Object.entries(rule).every(([field, value]) => ['type', 'toolPattern', 'expiresAt'].includes(field)
+                && (typeof value === 'string' || field === 'expiresAt' && value === null))))
+            return 'memory';
+        return 'journal';
+    }
+    if (body.kind === 'plan' && hasOnly([...routing, 'decision', 'feedback', 'grantedPrompts'])) {
+        if (!['approve', 'revise', 'reject'].includes(String(body.decision)) || body.feedback !== undefined && typeof body.feedback !== 'string')
+            return 'memory';
+        // Plan feedback and granted tool prompts are ordinary authored instructions,
+        // not secret-entry fields. Preserve their established offline semantics.
+        const prompts = body.grantedPrompts;
+        if (prompts !== undefined && (!Array.isArray(prompts) || prompts.some((prompt) => !prompt || typeof prompt !== 'object'
+            || Array.isArray(prompt) || !Object.entries(prompt).every(([field, value]) => ['tool', 'prompt'].includes(field) && typeof value === 'string'))))
+            return 'memory';
+        return 'journal';
+    }
+    return 'memory';
+}
+/** Validate the lane before accepting/transmitting its payload. No body values
+ * are logged, copied into metadata, or claimed to be encrypted by this API. */
+function endpointContentBoundary(lane, name, payload) {
+    if (!namesForLane[lane]?.includes(name))
+        throw new EndpointContentPolicyError(lane, name);
+    const record = payload && typeof payload === 'object' ? payload : undefined;
+    if (lane === 'query.request' && name === 'get_ephemeral' && record && !exports.ENDPOINT_CONTENT_EPHEMERAL_FAMILIES.includes(record.family)) {
+        throw new EndpointContentPolicyError(lane, `${name}/unknown-family`);
+    }
+    const requestRoutingPaths = (actionRouting[name] ?? []).flatMap((field) => [`body.value.${field}`, `envelope.${field}`]);
+    const classify = (path) => {
+        if (path.some((part) => secretSegments.has(part)))
+            return 'restricted-secret';
+        if (lane === 'operation.request' && ['respond_interaction', 'sync_phone_contacts'].includes(name) && path[0] === 'body' && path[1] === 'value' && !publicMatch(path, requestRoutingPaths))
+            return 'restricted-secret';
+        if (lane === 'operation.receipt' && path[0] === 'result' && (['consume_interaction', 'respond_interaction'].includes(name) || record?.resultReference?.kind === 'interaction'))
+            return 'restricted-secret';
+        let selected = payload;
+        for (const part of path)
+            selected = selected && typeof selected === 'object' && Object.hasOwn(selected, part) ? selected[part] : undefined;
+        // An allowed scalar path cannot make arbitrary nested content public.
+        if (selected !== null && typeof selected === 'object')
+            return 'private-content';
+        if (lane === 'operation.request') {
+            if (publicMatch(path, protocolPaths) || publicMatch(path, requestRoutingPaths))
+                return 'public-metadata';
+            // All response content is treated as restricted, even for a non-secret
+            // interaction; classification cannot depend on a stale local kind flag.
+            if (name === 'respond_interaction' && path[0] === 'body' && path[1] === 'value')
+                return 'restricted-secret';
+            if (name === 'sync_phone_contacts' && path[0] === 'body' && path[1] === 'value')
+                return 'restricted-secret';
+            if (name === 'verb_execute') {
+                const wire = record?.body?.value;
+                const spec = verbWire_js_1.VERB_WIRE_ENVELOPE_FIELDS[wire?.verb];
+                if (path[0] === 'body' && path[1] === 'value') {
+                    if (path.length === 3 && ['wire', 'verb'].includes(path[2]))
+                        return 'public-metadata';
+                    if (path[2] === 'envelope' && spec) {
+                        const field = path[3];
+                        const allowed = [...spec.required, ...spec.optional];
+                        // Reuse verbWire's existing split. Nested metadata is deliberately
+                        // conservative: only declared scalar fields and numeric array IDs.
+                        if (field && allowed.includes(field) && (path.length === 4 || path.length === 5 && ['mentions', 'memberIds'].includes(field) && /^\d+$/.test(path[4])))
+                            return 'public-metadata';
+                    }
+                }
+            }
+        }
+        else if (lane === 'operation.receipt') {
+            if (publicMatch(path, [...protocolPaths, 'status', 'createdAt', 'updatedAt', 'error.code', 'error.status', 'error.retryable', 'error.retryAfterMs', 'resultError.code', 'resultError.status', 'resultReference.kind', 'resultReference.conversationId', 'resultReference.uploadId', 'resultReference.sessionId', 'resultReference.requestId']))
+                return 'public-metadata';
+            if (path[0] === 'result' && (name === 'consume_interaction' || name === 'respond_interaction' || record?.resultReference?.kind === 'interaction'))
+                return 'restricted-secret';
+        }
+        else if (lane === 'query.request') {
+            if (publicMatch(path, queryRouting[name] ?? []))
+                return 'public-metadata';
+        }
+        else if (lane === 'query.result' || lane === 'ephemeral.result') {
+            if (name === 'conversation_changes' && publicMatch(path, ['cursor', 'hasMore', 'reset', 'admissionId']))
+                return 'public-metadata';
+            if (name === 'get_ephemeral' && path[0] === 'value')
+                return 'private-content';
+        }
+        else if (lane === 'ephemeral.request') {
+            if (publicMatch(path, transientRouting[name] ?? []))
+                return 'public-metadata';
+        }
+        else if (lane === 'event') {
+            if (publicMatch(path, eventRouting(name)))
+                return 'public-metadata';
+        }
+        return 'private-content';
+    };
+    return Object.freeze({ lane, name, defaultClass: 'private-content', classify });
+}

package/dist/cjs/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeEndpointUnreadProjection = void 0;
 __exportStar(require("./diffRedaction.js"), exports);
 __exportStar(require("./environment.js"), exports);
 __exportStar(require("./media.js"), exports);
@@ -38,3 +39,8 @@ __exportStar(require("./replyAuthority.js"), exports);
 __exportStar(require("./runtimeDescriptor.js"), exports);
 __exportStar(require("./workSessions.js"), exports);
 __exportStar(require("./conversationMembership.js"), exports);
+__exportStar(require("./endpoint.js"), exports);
+__exportStar(require("./endpointContentPolicy.js"), exports);
+__exportStar(require("./plaintextProcessors.js"), exports);
+var endpoint_unread_js_1 = require("./endpoint-unread.js");
+Object.defineProperty(exports, "computeEndpointUnreadProjection", { enumerable: true, get: function () { return endpoint_unread_js_1.computeEndpointUnreadProjection; } });

package/dist/cjs/plaintextProcessors.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLAINTEXT_PROCESSORS = void 0;
+exports.runPlaintextProcessor = runPlaintextProcessor;
+/** Existing server content readers. Classification is not encryption: these
+ * processors intentionally inspect plaintext in the current JSON release.
+ * Their input boundary must be redesigned before enabling encrypted rooms. */
+exports.PLAINTEXT_PROCESSORS = {
+    preview: { current: 'Read message/display text to derive conversation and notification previews.', beforeMls: 'Derive on authorized endpoints; clear/reconcile deleted-message previews there.' },
+    push: { current: 'Send visible titles and message previews to FCM/APNs.', beforeMls: 'Use generic wake notifications or endpoint-decrypted notification extensions.' },
+    topic: { current: 'Derive the initial topic from message text.', beforeMls: 'Derive on an authorized endpoint and publish as encrypted conversation content.' },
+    forward: { current: 'Read source content and copy plaintext attachments into the target room.', beforeMls: 'Decrypt and re-encrypt on an authorized endpoint; keep server target admission checks.' },
+    message_validation: { current: 'Inspect text, attachment descriptors and rich content before storing messages.', beforeMls: 'Validate decrypted content on endpoints; retain bounded ciphertext/envelope checks on the server.' },
+    interaction_validation: { current: 'Validate card/input/approval/plan render contracts and submitted responses.', beforeMls: 'Validate content on authorized requesting/responding endpoints; retain public admission and lifecycle checks.' },
+    image_generation: { current: 'Send prompts/source image bytes to Vertex and persist generated output.', beforeMls: 'Require explicit provider disclosure and an authorized endpoint/processing participant; no silent server decryption.' },
+    video_processing: { current: 'Download plaintext video, normalize it and create a poster.', beforeMls: 'Process on an endpoint or an explicitly authorized processing participant before encrypted upload.' },
+    owner_observation: { current: 'Allow authenticated owners to inspect managed agent conversations without room membership.', beforeMls: 'Explicitly enroll authorized owner keyholders or retire content observation; ownership alone supplies no decryption keys.' },
+    moderation_evidence: { current: 'Accept user-selected plaintext message evidence for moderation.', beforeMls: 'Design explicit selective disclosure/authenticity (including franking policy); never infer access to room keys.' },
+};
+/** The callback is the actual content processor, not a telemetry hook. Keeping
+ * the codec explicit ensures an opaque body cannot accidentally be processed by
+ * the JSON path. This is not authorization; callers still enforce their domain
+ * policy and every enabled transport currently requires JSON. */
+function runPlaintextProcessor(name, input, process) {
+    if (!Object.hasOwn(exports.PLAINTEXT_PROCESSORS, name) || input.encoding !== 'json') {
+        throw new Error('PLAINTEXT_PROCESSOR_CODEC_REQUIRED');
+    }
+    return process(input.value);
+}

package/dist/endpoint-unread.d.ts

@@ -0,0 +1,4 @@
+/** Metadata-only unread projection, shared by serving and the offline migration. */
+export declare function computeEndpointUnreadProjection(principalId: string, conversation: Record<string, unknown> | undefined, member: Record<string, unknown> | undefined): {
+    unmutedAtMs: number;
+} | null;

package/dist/endpoint-unread.js

@@ -0,0 +1,31 @@
+/** Metadata-only unread projection, shared by serving and the offline migration. */
+export function computeEndpointUnreadProjection(principalId, conversation, member) {
+    if (!conversation || !member || !Array.isArray(conversation.memberIds) || !conversation.memberIds.includes(principalId))
+        return null;
+    const message = conversation.lastMessage;
+    if (!message || typeof message.senderId !== 'string' || message.senderId === principalId)
+        return null;
+    const at = time(message.timestamp);
+    if (at === null)
+        return null;
+    const floor = time(member.historyStartAt), read = time(member.lastReadTimestamp), deleted = time(member.deletedAt);
+    if ((floor !== null && at < floor) || (read !== null && at <= read) || (deleted !== null && at <= deleted))
+        return null;
+    return { unmutedAtMs: time(member.mutedUntil) ?? 0 };
+}
+function time(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string') {
+        const ms = Date.parse(value);
+        return Number.isFinite(ms) ? ms : null;
+    }
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value !== 'object')
+        return null;
+    const timestamp = value;
+    const ms = typeof timestamp.toMillis === 'function' ? timestamp.toMillis() : typeof timestamp.toDate === 'function' ? timestamp.toDate().getTime()
+        : typeof timestamp.seconds === 'number' ? timestamp.seconds * 1000 + (timestamp.nanoseconds ?? 0) / 1e6 : NaN;
+    return Number.isFinite(ms) ? ms : null;
+}

package/dist/endpoint.d.ts

@@ -0,0 +1,88 @@
+/** Plaintext endpoint protocol. Identity and authority come from authenticated transport. */
+export declare const CANON_ENDPOINT_PROTOCOL: "canon.endpoint.v1";
+export interface EndpointPreconditions {
+    conversationId?: string;
+    membershipRevision?: number;
+    admissionId?: string;
+    targetAdmissionId?: string;
+}
+export interface EndpointOperationRequest {
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    operationId: string;
+    installationId: string;
+    action: string;
+    /** Agent ownership generation selected when authored; absent for humans. */
+    ownershipVersion?: number;
+    envelope?: Record<string, unknown>;
+    preconditions?: EndpointPreconditions;
+    body: {
+        encoding: 'json';
+        value: Record<string, unknown>;
+    };
+}
+export interface EndpointOperationError {
+    code: string;
+    message: string;
+    status?: number;
+    retryable?: boolean;
+    retryAfterMs?: number;
+}
+export type EndpointReceiptStatus = 'pending' | 'succeeded' | 'rejected' | 'uncertain';
+export type EndpointResultReference = {
+    kind: 'interaction';
+    conversationId: string;
+    interactionKind: 'input' | 'approval' | 'card' | 'plan';
+    requestId: string;
+    operationKey: string;
+} | {
+    kind: 'upload';
+    uploadId: string;
+} | {
+    kind: 'voice';
+    conversationId: string;
+    sessionId: string;
+};
+export interface EndpointOperationReceipt<T = unknown> {
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    operationId: string;
+    installationId: string;
+    action: string;
+    status: EndpointReceiptStatus;
+    result?: T;
+    /** Sensitive/bearer results are hydrated for the response, never journaled. */
+    resultReference?: EndpointResultReference;
+    /** Transient hydration failure: the durable mutation remains succeeded. */
+    resultError?: EndpointOperationError;
+    error?: EndpointOperationError;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface EndpointQueryRequest {
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    query: string;
+    parameters: Record<string, unknown>;
+}
+export interface EndpointQueryResponse<T = unknown> {
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    result: T;
+}
+/** Durable application cursors differ from the live transport's reconnect token. */
+export interface EndpointEvent {
+    id: string;
+    kind: string;
+    conversationId?: string;
+    revision?: number;
+    cursor?: string;
+    durable: boolean;
+    data: Record<string, unknown>;
+}
+export interface EndpointCapabilities {
+    protocol: typeof CANON_ENDPOINT_PROTOCOL;
+    actions: string[];
+    queries: string[];
+    maintenance: boolean;
+}
+export declare const ENDPOINT_ID_PATTERN: RegExp;
+export declare const ENDPOINT_ACTION_PATTERN: RegExp;
+export declare function isEndpointOperationRequest(value: unknown): value is EndpointOperationRequest;
+export declare function isEndpointOperationReceipt(value: unknown): value is EndpointOperationReceipt;

package/dist/endpoint.js

@@ -0,0 +1,28 @@
+/** Plaintext endpoint protocol. Identity and authority come from authenticated transport. */
+export const CANON_ENDPOINT_PROTOCOL = 'canon.endpoint.v1';
+export const ENDPOINT_ID_PATTERN = /^[A-Za-z0-9_.:~-]{1,200}$/;
+export const ENDPOINT_ACTION_PATTERN = /^[a-z][a-z0-9_.-]{0,95}$/;
+export function isEndpointOperationRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const request = value;
+    const body = request.body;
+    return request.protocol === CANON_ENDPOINT_PROTOCOL
+        && typeof request.operationId === 'string' && ENDPOINT_ID_PATTERN.test(request.operationId)
+        && typeof request.installationId === 'string' && ENDPOINT_ID_PATTERN.test(request.installationId)
+        && typeof request.action === 'string' && ENDPOINT_ACTION_PATTERN.test(request.action)
+        && (request.ownershipVersion === undefined || Number.isSafeInteger(request.ownershipVersion) && request.ownershipVersion >= 0)
+        && !!body && body.encoding === 'json'
+        && !!body.value && typeof body.value === 'object' && !Array.isArray(body.value);
+}
+export function isEndpointOperationReceipt(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const receipt = value;
+    return receipt.protocol === CANON_ENDPOINT_PROTOCOL
+        && typeof receipt.operationId === 'string' && ENDPOINT_ID_PATTERN.test(receipt.operationId)
+        && typeof receipt.installationId === 'string' && ENDPOINT_ID_PATTERN.test(receipt.installationId)
+        && typeof receipt.action === 'string' && ENDPOINT_ACTION_PATTERN.test(receipt.action)
+        && ['pending', 'succeeded', 'rejected', 'uncertain'].includes(String(receipt.status))
+        && typeof receipt.createdAt === 'string' && typeof receipt.updatedAt === 'string';
+}

package/dist/endpointContentPolicy.d.ts

@@ -0,0 +1,33 @@
+/** Classification, not confidentiality: every enabled endpoint codec is JSON.
+ * Unknown fields are private content, including inside an `envelope`. Adding a
+ * lane requires review; adding content to an existing schema does not make it
+ * public. These definitions refer to existing payload schemas, not copies. */
+export type EndpointContentClass = 'public-metadata' | 'private-content' | 'restricted-secret';
+export type EndpointContentLane = 'operation.request' | 'operation.receipt' | 'query.request' | 'query.result' | 'ephemeral.request' | 'ephemeral.result' | 'event';
+export declare const ENDPOINT_CONTENT_ACTIONS: readonly ["initialize_endpoint", "sync_phone_contacts", "request_work_session", "resolve_work_session_request", "update_agent_behavior_policy", "update_conversation_agent_behavior_policy", "send_message", "delete_message", "forward_message", "react", "verb_execute", "send_contextual_message", "create_interaction", "consume_interaction", "start_conversation", "create_conversation", "add_member", "remove_member", "leave_conversation", "update_member_role", "update_conversation", "rename_conversation", "update_topic", "update_group_avatar", "mark_read", "cancel_queued_message", "set_conversation_preferences", "set_block", "save_contact", "remove_contact", "respond_interaction", "session_control", "approve_contact_request", "reject_contact_request", "cancel_direct_request", "update_message_disposition", "create_upload", "finalize_upload", "delete_upload", "retry_video_processing", "finalize_memo_stream", "abort_memo_stream", "create_voice_session", "join_voice_session", "decline_voice_session", "end_voice_session", "consume_runtime_signal", "generate_image"];
+export declare const ENDPOINT_CONTENT_FUNCTION_QUERIES: readonly ["discover_agents", "get_unread_summary", "peek_runtime_signal", "get_work_session_catalog", "get_work_session_request", "get_agent_behavior_policy", "get_conversation_agent_behavior_policy", "get_ephemeral", "list_voice_sessions", "list_contact_requests", "list_conversations", "list_messages", "get_messages", "admission_fences", "list_contacts", "get_contact", "get_members", "resolve_admission", "resolve_group_admission", "get_runtime_card_state", "conversation", "conversation_changes", "get_upload", "get_voice_session", "get_image_generation", "get_image_generation_status"];
+export declare const ENDPOINT_CONTENT_QUERIES: readonly ["discover_agents", "get_unread_summary", "peek_runtime_signal", "get_work_session_catalog", "get_work_session_request", "get_agent_behavior_policy", "get_conversation_agent_behavior_policy", "get_ephemeral", "list_voice_sessions", "list_contact_requests", "list_conversations", "list_messages", "get_messages", "admission_fences", "list_contacts", "get_contact", "get_members", "resolve_admission", "resolve_group_admission", "get_runtime_card_state", "conversation", "conversation_changes", "get_upload", "get_voice_session", "get_image_generation", "get_image_generation_status", "admit_messages"];
+export declare const ENDPOINT_CONTENT_EPHEMERALS: readonly ["create_memo_stream", "publish_presence", "publish_typing", "publish_streaming", "publish_turn", "publish_runtime_status", "append_memo_chunk"];
+export declare const ENDPOINT_CONTENT_EPHEMERAL_FAMILIES: readonly ["typing", "streaming", "turn-state", "agent-session", "runtime-card-state", "memo-streams", "runtime-info", "runtime-activity", "runtime-suppression", "runtime-silence", "runtime-attention", "call-attention", "agent-runtime", "presence"];
+export declare const ENDPOINT_CONTENT_EVENTS: readonly ["connected", "heartbeat", "agent.context", "replay.expired", "message.created", "message.snapshot", "message.updated", "message.deleted", "message.media_terminal", "conversation.updated", "conversation.changed", "conversation.removed", "conversations.changed", "contacts.changed", "contact.added", "contact.updated", "contact.removed", "presence", "typing", "runtime.updated", "runtime.control", "turn.updated", "voice.session.started", "voice.session.ended", ...string[]];
+export declare class EndpointContentPolicyError extends Error {
+    readonly code = "ENDPOINT_CONTENT_UNCLASSIFIED";
+    constructor(lane: string, name: string);
+}
+export interface EndpointContentBoundary {
+    readonly lane: EndpointContentLane;
+    readonly name: string;
+    readonly defaultClass: 'private-content';
+    /** Paths address the actual payload. Query/result/event paths are relative to
+     * their parameters/result/data; operation paths include body.value. */
+    classify(path: readonly string[]): EndpointContentClass;
+}
+/** Local journal policy is separate from wire classification. Input answers and
+ * card values can carry passwords even when the response omits the original
+ * request's secret/sudo/field metadata. Only reviewed response shapes without
+ * those value bags may be retried from durable storage. Unknown response fields
+ * fail closed; a caller's `sensitive: false` cannot weaken this policy. */
+export declare function endpointOperationRequestRetention(action: string, body: Record<string, unknown>, envelope?: Record<string, unknown>): 'journal' | 'memory';
+/** Validate the lane before accepting/transmitting its payload. No body values
+ * are logged, copied into metadata, or claimed to be encrypted by this API. */
+export declare function endpointContentBoundary(lane: EndpointContentLane, name: string, payload?: unknown): EndpointContentBoundary;

package/dist/endpointContentPolicy.js

@@ -0,0 +1,263 @@
+import { VERB_WIRE_ENVELOPE_FIELDS } from './verbWire.js';
+export const ENDPOINT_CONTENT_ACTIONS = [
+    'initialize_endpoint',
+    'sync_phone_contacts', 'request_work_session', 'resolve_work_session_request',
+    'update_agent_behavior_policy', 'update_conversation_agent_behavior_policy',
+    'send_message', 'delete_message', 'forward_message', 'react', 'verb_execute',
+    'send_contextual_message', 'create_interaction', 'consume_interaction',
+    'start_conversation', 'create_conversation', 'add_member', 'remove_member',
+    'leave_conversation', 'update_member_role', 'update_conversation', 'rename_conversation',
+    'update_topic', 'update_group_avatar', 'mark_read', 'cancel_queued_message',
+    'set_conversation_preferences', 'set_block', 'save_contact', 'remove_contact',
+    'respond_interaction', 'session_control', 'approve_contact_request',
+    'reject_contact_request', 'cancel_direct_request', 'update_message_disposition',
+    'create_upload', 'finalize_upload', 'delete_upload', 'retry_video_processing',
+    'finalize_memo_stream', 'abort_memo_stream', 'create_voice_session',
+    'join_voice_session', 'decline_voice_session', 'end_voice_session',
+    'consume_runtime_signal', 'generate_image',
+];
+export const ENDPOINT_CONTENT_FUNCTION_QUERIES = [
+    'discover_agents', 'get_unread_summary', 'peek_runtime_signal',
+    'get_work_session_catalog', 'get_work_session_request', 'get_agent_behavior_policy',
+    'get_conversation_agent_behavior_policy', 'get_ephemeral', 'list_voice_sessions',
+    'list_contact_requests', 'list_conversations', 'list_messages', 'get_messages',
+    'admission_fences', 'list_contacts', 'get_contact', 'get_members', 'resolve_admission',
+    'resolve_group_admission', 'get_runtime_card_state', 'conversation',
+    'conversation_changes', 'get_upload', 'get_voice_session', 'get_image_generation',
+    'get_image_generation_status',
+];
+export const ENDPOINT_CONTENT_QUERIES = [...ENDPOINT_CONTENT_FUNCTION_QUERIES, 'admit_messages'];
+export const ENDPOINT_CONTENT_EPHEMERALS = [
+    'create_memo_stream', 'publish_presence', 'publish_typing', 'publish_streaming',
+    'publish_turn', 'publish_runtime_status', 'append_memo_chunk',
+];
+export const ENDPOINT_CONTENT_EPHEMERAL_FAMILIES = [
+    'typing', 'streaming', 'turn-state', 'agent-session', 'runtime-card-state',
+    'memo-streams', 'runtime-info', 'runtime-activity', 'runtime-suppression',
+    'runtime-silence', 'runtime-attention', 'call-attention', 'agent-runtime', 'presence',
+];
+export const ENDPOINT_CONTENT_EVENTS = [
+    'connected', 'heartbeat', 'agent.context', 'replay.expired',
+    'message.created', 'message.snapshot', 'message.updated', 'message.deleted',
+    'message.media_terminal', 'conversation.updated', 'conversation.changed',
+    'conversation.removed', 'conversations.changed', 'contacts.changed',
+    'contact.added', 'contact.updated', 'contact.removed', 'presence', 'typing',
+    'runtime.updated', 'runtime.control', 'turn.updated',
+    'voice.session.started', 'voice.session.ended',
+    ...ENDPOINT_CONTENT_EPHEMERAL_FAMILIES.map((family) => `ephemeral.${family}`),
+];
+export class EndpointContentPolicyError extends Error {
+    code = 'ENDPOINT_CONTENT_UNCLASSIFIED';
+    constructor(lane, name) {
+        super(`Unclassified endpoint lane: ${lane}/${name}`);
+        this.name = 'EndpointContentPolicyError';
+    }
+}
+const namesForLane = {
+    'operation.request': ENDPOINT_CONTENT_ACTIONS,
+    'operation.receipt': ENDPOINT_CONTENT_ACTIONS,
+    'query.request': ENDPOINT_CONTENT_QUERIES,
+    'query.result': ENDPOINT_CONTENT_QUERIES,
+    'ephemeral.request': ENDPOINT_CONTENT_EPHEMERALS,
+    'ephemeral.result': ENDPOINT_CONTENT_EPHEMERALS,
+    event: ENDPOINT_CONTENT_EVENTS,
+};
+/** An explicit allowlist of routing/authorization fields, not a rule that all
+ * fields named `id` are public. Free text, previews, labels, media descriptors,
+ * paths, provider configuration, native snapshots and arbitrary metadata stay
+ * private. IDs/cursors/timing still reveal a communication graph. */
+const protocolPaths = [
+    'protocol', 'operationId', 'installationId', 'action', 'ownershipVersion',
+    'preconditions.conversationId', 'preconditions.membershipRevision',
+    'preconditions.admissionId', 'preconditions.targetAdmissionId', 'body.encoding',
+];
+// Fields are reviewed for a particular lane: e.g. an unknown `contactId` added
+// to send_message is still private, despite being a routing ID elsewhere.
+const actionRouting = {
+    send_message: ['conversationId', 'messageId', 'replyTo', 'mentions.*'],
+    delete_message: ['conversationId', 'messageId'], forward_message: ['sourceConversationId', 'targetConversationId', 'messageId'],
+    react: ['conversationId', 'messageId'], send_contextual_message: ['conversationId'],
+    create_interaction: ['conversationId', 'requestId', 'inputId', 'approvalId', 'cardId', 'planId', 'responseUserId'],
+    consume_interaction: ['conversationId', 'inputId', 'approvalId', 'cardId', 'planId'],
+    respond_interaction: ['conversationId', 'requestId'],
+    start_conversation: ['targetUserId'], create_conversation: ['memberIds.*'],
+    add_member: ['conversationId', 'userId', 'agentId'], remove_member: ['conversationId', 'userId', 'agentId', 'targetUserId'],
+    leave_conversation: ['conversationId'], update_member_role: ['conversationId', 'userId', 'targetUserId'],
+    update_conversation: ['conversationId'], rename_conversation: ['conversationId'], update_topic: ['conversationId'],
+    update_group_avatar: ['conversationId'], mark_read: ['conversationId'], cancel_queued_message: ['conversationId', 'messageId'],
+    set_conversation_preferences: ['conversationId'], set_block: ['targetUserId'], save_contact: ['contactUserId'], remove_contact: ['contactId', 'contactUserId'],
+    session_control: ['conversationId', 'agentId'], approve_contact_request: ['requestId'], reject_contact_request: ['requestId'], cancel_direct_request: ['requestId'],
+    update_message_disposition: ['conversationId', 'messageId'], create_upload: ['conversationId'], finalize_upload: ['uploadId'], delete_upload: ['uploadId'], retry_video_processing: ['uploadId'],
+    finalize_memo_stream: ['conversationId', 'streamId'], abort_memo_stream: ['streamId'],
+    create_voice_session: ['conversationId'], join_voice_session: ['conversationId', 'sessionId'], decline_voice_session: ['conversationId', 'sessionId'], end_voice_session: ['conversationId', 'sessionId'],
+    consume_runtime_signal: ['conversationId', 'expectedSignalId'], generate_image: ['conversationId', 'requestId'],
+    request_work_session: ['conversationId', 'agentId', 'requestId'], resolve_work_session_request: ['requestId'],
+    update_agent_behavior_policy: ['agentId'], update_conversation_agent_behavior_policy: ['conversationId', 'agentId'],
+};
+const queryRouting = {
+    admit_messages: ['conversationId', 'messageIds.*', 'admissionId'], conversation_changes: ['conversationId', 'cursor', 'limit'],
+    conversation: ['conversationId'], list_conversations: ['limit', 'before'], list_messages: ['conversationId', 'before', 'limit'], get_messages: ['conversationId', 'messageIds.*'],
+    list_contacts: ['limit', 'before'], get_contact: ['contactId', 'contactUserId', 'userId'], get_members: ['conversationId'],
+    list_contact_requests: ['direction', 'limit', 'before'], admission_fences: ['conversationId', 'targetUserId'],
+    resolve_admission: ['targetUserId'], resolve_group_admission: ['conversationId', 'targetUserId'], get_runtime_card_state: ['conversationId', 'cardId'],
+    get_ephemeral: ['family', 'scopeId'], peek_runtime_signal: ['conversationId'], list_voice_sessions: ['conversationId', 'limit'],
+    get_upload: ['uploadId'], get_voice_session: ['conversationId', 'sessionId'], get_image_generation: ['requestId'],
+    get_work_session_catalog: ['agentId'], get_work_session_request: ['requestId'], get_agent_behavior_policy: ['agentId'], get_conversation_agent_behavior_policy: ['conversationId', 'agentId'],
+};
+const transientRouting = {
+    create_memo_stream: ['conversationId', 'streamId'], append_memo_chunk: ['streamId'],
+    publish_presence: [], publish_typing: ['conversationId'], publish_streaming: ['conversationId'], publish_turn: ['conversationId'], publish_runtime_status: ['conversationId'],
+};
+function eventRouting(name) {
+    if (name.startsWith('ephemeral.'))
+        return ['conversationId', 'scopeId'];
+    if (name === 'connected')
+        return ['protocol', 'connectionId', 'agentId', 'principalId', 'principalType'];
+    if (name === 'heartbeat')
+        return ['timestamp'];
+    if (name === 'agent.context')
+        return ['agentId', 'ownerId', 'ownershipVersion'];
+    if (name === 'conversations.changed')
+        return ['conversationIds.*', 'removedConversationIds.*'];
+    if (name.startsWith('message.'))
+        return ['conversationId', 'messageId', 'eventId', 'id', 'message.id', 'message.conversationId', 'message.senderId', 'message.senderType', 'message.createdAt', 'message.replyTo', 'message.mentions.*'];
+    if (name.startsWith('conversation.'))
+        return ['conversationId'];
+    if (name.startsWith('contact.'))
+        return ['contactId'];
+    if (name.startsWith('voice.session.'))
+        return ['conversationId', 'sessionId'];
+    if (/^(runtime\.|turn\.|typing$|presence$)/.test(name))
+        return ['conversationId', 'agentId', 'userId', 'memberId'];
+    return [];
+}
+const secretSegments = new Set(['token', 'accessToken', 'refreshToken', 'uploadUrl', 'signedUrl', 'livekitToken', 'replyAuthority', 'credentials', 'password', 'secret', 'authorization', 'answer', 'answers', 'response', 'submittedValue']);
+const matches = (path, pattern) => {
+    const parts = pattern.split('.');
+    return parts.length === path.length && parts.every((part, index) => part === path[index] || part === '*' && /^\d+$/.test(path[index]));
+};
+const publicMatch = (path, patterns) => patterns.some((pattern) => matches(path, pattern));
+/** Local journal policy is separate from wire classification. Input answers and
+ * card values can carry passwords even when the response omits the original
+ * request's secret/sudo/field metadata. Only reviewed response shapes without
+ * those value bags may be retried from durable storage. Unknown response fields
+ * fail closed; a caller's `sensitive: false` cannot weaken this policy. */
+export function endpointOperationRequestRetention(action, body, envelope) {
+    if (action !== 'respond_interaction')
+        return 'journal';
+    // Interaction services use the body exclusively. Unknown envelope additions
+    // must not bypass retention, including conflicting fields rejected by server.
+    if (envelope && Object.keys(envelope).length > 0)
+        return 'memory';
+    const routing = ['kind', 'conversationId', 'agentId', 'requestId'];
+    const hasOnly = (fields) => Object.keys(body).every((field) => fields.includes(field));
+    if (routing.some((field) => body[field] !== undefined && typeof body[field] !== 'string'))
+        return 'memory';
+    if ((body.kind === 'input' || body.kind === 'card') && hasOnly([...routing, 'status', 'actionId'])) {
+        if (!['submitted', 'cancelled'].includes(String(body.status)) || (body.actionId !== undefined && typeof body.actionId !== 'string'))
+            return 'memory';
+        // A card button or cancellation with no submitted values contains no answer
+        // plaintext. Input/card requests with value, answers or values stay in RAM,
+        // including non-secret clarification: that distinction is absent on wire.
+        return 'journal';
+    }
+    if (body.kind === 'approval' && hasOnly([...routing, 'decision', 'sessionRule'])) {
+        if (body.decision !== 'allow' && body.decision !== 'deny')
+            return 'memory';
+        const rule = body.sessionRule;
+        if (rule !== undefined && (!rule || typeof rule !== 'object' || Array.isArray(rule)
+            || !Object.entries(rule).every(([field, value]) => ['type', 'toolPattern', 'expiresAt'].includes(field)
+                && (typeof value === 'string' || field === 'expiresAt' && value === null))))
+            return 'memory';
+        return 'journal';
+    }
+    if (body.kind === 'plan' && hasOnly([...routing, 'decision', 'feedback', 'grantedPrompts'])) {
+        if (!['approve', 'revise', 'reject'].includes(String(body.decision)) || body.feedback !== undefined && typeof body.feedback !== 'string')
+            return 'memory';
+        // Plan feedback and granted tool prompts are ordinary authored instructions,
+        // not secret-entry fields. Preserve their established offline semantics.
+        const prompts = body.grantedPrompts;
+        if (prompts !== undefined && (!Array.isArray(prompts) || prompts.some((prompt) => !prompt || typeof prompt !== 'object'
+            || Array.isArray(prompt) || !Object.entries(prompt).every(([field, value]) => ['tool', 'prompt'].includes(field) && typeof value === 'string'))))
+            return 'memory';
+        return 'journal';
+    }
+    return 'memory';
+}
+/** Validate the lane before accepting/transmitting its payload. No body values
+ * are logged, copied into metadata, or claimed to be encrypted by this API. */
+export function endpointContentBoundary(lane, name, payload) {
+    if (!namesForLane[lane]?.includes(name))
+        throw new EndpointContentPolicyError(lane, name);
+    const record = payload && typeof payload === 'object' ? payload : undefined;
+    if (lane === 'query.request' && name === 'get_ephemeral' && record && !ENDPOINT_CONTENT_EPHEMERAL_FAMILIES.includes(record.family)) {
+        throw new EndpointContentPolicyError(lane, `${name}/unknown-family`);
+    }
+    const requestRoutingPaths = (actionRouting[name] ?? []).flatMap((field) => [`body.value.${field}`, `envelope.${field}`]);
+    const classify = (path) => {
+        if (path.some((part) => secretSegments.has(part)))
+            return 'restricted-secret';
+        if (lane === 'operation.request' && ['respond_interaction', 'sync_phone_contacts'].includes(name) && path[0] === 'body' && path[1] === 'value' && !publicMatch(path, requestRoutingPaths))
+            return 'restricted-secret';
+        if (lane === 'operation.receipt' && path[0] === 'result' && (['consume_interaction', 'respond_interaction'].includes(name) || record?.resultReference?.kind === 'interaction'))
+            return 'restricted-secret';
+        let selected = payload;
+        for (const part of path)
+            selected = selected && typeof selected === 'object' && Object.hasOwn(selected, part) ? selected[part] : undefined;
+        // An allowed scalar path cannot make arbitrary nested content public.
+        if (selected !== null && typeof selected === 'object')
+            return 'private-content';
+        if (lane === 'operation.request') {
+            if (publicMatch(path, protocolPaths) || publicMatch(path, requestRoutingPaths))
+                return 'public-metadata';
+            // All response content is treated as restricted, even for a non-secret
+            // interaction; classification cannot depend on a stale local kind flag.
+            if (name === 'respond_interaction' && path[0] === 'body' && path[1] === 'value')
+                return 'restricted-secret';
+            if (name === 'sync_phone_contacts' && path[0] === 'body' && path[1] === 'value')
+                return 'restricted-secret';
+            if (name === 'verb_execute') {
+                const wire = record?.body?.value;
+                const spec = VERB_WIRE_ENVELOPE_FIELDS[wire?.verb];
+                if (path[0] === 'body' && path[1] === 'value') {
+                    if (path.length === 3 && ['wire', 'verb'].includes(path[2]))
+                        return 'public-metadata';
+                    if (path[2] === 'envelope' && spec) {
+                        const field = path[3];
+                        const allowed = [...spec.required, ...spec.optional];
+                        // Reuse verbWire's existing split. Nested metadata is deliberately
+                        // conservative: only declared scalar fields and numeric array IDs.
+                        if (field && allowed.includes(field) && (path.length === 4 || path.length === 5 && ['mentions', 'memberIds'].includes(field) && /^\d+$/.test(path[4])))
+                            return 'public-metadata';
+                    }
+                }
+            }
+        }
+        else if (lane === 'operation.receipt') {
+            if (publicMatch(path, [...protocolPaths, 'status', 'createdAt', 'updatedAt', 'error.code', 'error.status', 'error.retryable', 'error.retryAfterMs', 'resultError.code', 'resultError.status', 'resultReference.kind', 'resultReference.conversationId', 'resultReference.uploadId', 'resultReference.sessionId', 'resultReference.requestId']))
+                return 'public-metadata';
+            if (path[0] === 'result' && (name === 'consume_interaction' || name === 'respond_interaction' || record?.resultReference?.kind === 'interaction'))
+                return 'restricted-secret';
+        }
+        else if (lane === 'query.request') {
+            if (publicMatch(path, queryRouting[name] ?? []))
+                return 'public-metadata';
+        }
+        else if (lane === 'query.result' || lane === 'ephemeral.result') {
+            if (name === 'conversation_changes' && publicMatch(path, ['cursor', 'hasMore', 'reset', 'admissionId']))
+                return 'public-metadata';
+            if (name === 'get_ephemeral' && path[0] === 'value')
+                return 'private-content';
+        }
+        else if (lane === 'ephemeral.request') {
+            if (publicMatch(path, transientRouting[name] ?? []))
+                return 'public-metadata';
+        }
+        else if (lane === 'event') {
+            if (publicMatch(path, eventRouting(name)))
+                return 'public-metadata';
+        }
+        return 'private-content';
+    };
+    return Object.freeze({ lane, name, defaultClass: 'private-content', classify });
+}

package/dist/index.d.ts

@@ -22,3 +22,7 @@ export * from './replyAuthority.js';
 export * from './runtimeDescriptor.js';
 export * from './workSessions.js';
 export * from './conversationMembership.js';
+export * from './endpoint.js';
+export * from './endpointContentPolicy.js';
+export * from './plaintextProcessors.js';
+export { computeEndpointUnreadProjection } from './endpoint-unread.js';

package/dist/index.js

@@ -22,3 +22,7 @@ export * from './replyAuthority.js';
 export * from './runtimeDescriptor.js';
 export * from './workSessions.js';
 export * from './conversationMembership.js';
+export * from './endpoint.js';
+export * from './endpointContentPolicy.js';
+export * from './plaintextProcessors.js';
+export { computeEndpointUnreadProjection } from './endpoint-unread.js';

package/dist/plaintextProcessors.d.ts

@@ -0,0 +1,55 @@
+/** Existing server content readers. Classification is not encryption: these
+ * processors intentionally inspect plaintext in the current JSON release.
+ * Their input boundary must be redesigned before enabling encrypted rooms. */
+export declare const PLAINTEXT_PROCESSORS: {
+    readonly preview: {
+        readonly current: "Read message/display text to derive conversation and notification previews.";
+        readonly beforeMls: "Derive on authorized endpoints; clear/reconcile deleted-message previews there.";
+    };
+    readonly push: {
+        readonly current: "Send visible titles and message previews to FCM/APNs.";
+        readonly beforeMls: "Use generic wake notifications or endpoint-decrypted notification extensions.";
+    };
+    readonly topic: {
+        readonly current: "Derive the initial topic from message text.";
+        readonly beforeMls: "Derive on an authorized endpoint and publish as encrypted conversation content.";
+    };
+    readonly forward: {
+        readonly current: "Read source content and copy plaintext attachments into the target room.";
+        readonly beforeMls: "Decrypt and re-encrypt on an authorized endpoint; keep server target admission checks.";
+    };
+    readonly message_validation: {
+        readonly current: "Inspect text, attachment descriptors and rich content before storing messages.";
+        readonly beforeMls: "Validate decrypted content on endpoints; retain bounded ciphertext/envelope checks on the server.";
+    };
+    readonly interaction_validation: {
+        readonly current: "Validate card/input/approval/plan render contracts and submitted responses.";
+        readonly beforeMls: "Validate content on authorized requesting/responding endpoints; retain public admission and lifecycle checks.";
+    };
+    readonly image_generation: {
+        readonly current: "Send prompts/source image bytes to Vertex and persist generated output.";
+        readonly beforeMls: "Require explicit provider disclosure and an authorized endpoint/processing participant; no silent server decryption.";
+    };
+    readonly video_processing: {
+        readonly current: "Download plaintext video, normalize it and create a poster.";
+        readonly beforeMls: "Process on an endpoint or an explicitly authorized processing participant before encrypted upload.";
+    };
+    readonly owner_observation: {
+        readonly current: "Allow authenticated owners to inspect managed agent conversations without room membership.";
+        readonly beforeMls: "Explicitly enroll authorized owner keyholders or retire content observation; ownership alone supplies no decryption keys.";
+    };
+    readonly moderation_evidence: {
+        readonly current: "Accept user-selected plaintext message evidence for moderation.";
+        readonly beforeMls: "Design explicit selective disclosure/authenticity (including franking policy); never infer access to room keys.";
+    };
+};
+export type PlaintextProcessorName = keyof typeof PLAINTEXT_PROCESSORS;
+export interface PlaintextProcessorInput<T> {
+    encoding: 'json';
+    value: T;
+}
+/** The callback is the actual content processor, not a telemetry hook. Keeping
+ * the codec explicit ensures an opaque body cannot accidentally be processed by
+ * the JSON path. This is not authorization; callers still enforce their domain
+ * policy and every enabled transport currently requires JSON. */
+export declare function runPlaintextProcessor<T, R>(name: PlaintextProcessorName, input: PlaintextProcessorInput<T>, process: (value: T) => R): R;

package/dist/plaintextProcessors.js

@@ -0,0 +1,25 @@
+/** Existing server content readers. Classification is not encryption: these
+ * processors intentionally inspect plaintext in the current JSON release.
+ * Their input boundary must be redesigned before enabling encrypted rooms. */
+export const PLAINTEXT_PROCESSORS = {
+    preview: { current: 'Read message/display text to derive conversation and notification previews.', beforeMls: 'Derive on authorized endpoints; clear/reconcile deleted-message previews there.' },
+    push: { current: 'Send visible titles and message previews to FCM/APNs.', beforeMls: 'Use generic wake notifications or endpoint-decrypted notification extensions.' },
+    topic: { current: 'Derive the initial topic from message text.', beforeMls: 'Derive on an authorized endpoint and publish as encrypted conversation content.' },
+    forward: { current: 'Read source content and copy plaintext attachments into the target room.', beforeMls: 'Decrypt and re-encrypt on an authorized endpoint; keep server target admission checks.' },
+    message_validation: { current: 'Inspect text, attachment descriptors and rich content before storing messages.', beforeMls: 'Validate decrypted content on endpoints; retain bounded ciphertext/envelope checks on the server.' },
+    interaction_validation: { current: 'Validate card/input/approval/plan render contracts and submitted responses.', beforeMls: 'Validate content on authorized requesting/responding endpoints; retain public admission and lifecycle checks.' },
+    image_generation: { current: 'Send prompts/source image bytes to Vertex and persist generated output.', beforeMls: 'Require explicit provider disclosure and an authorized endpoint/processing participant; no silent server decryption.' },
+    video_processing: { current: 'Download plaintext video, normalize it and create a poster.', beforeMls: 'Process on an endpoint or an explicitly authorized processing participant before encrypted upload.' },
+    owner_observation: { current: 'Allow authenticated owners to inspect managed agent conversations without room membership.', beforeMls: 'Explicitly enroll authorized owner keyholders or retire content observation; ownership alone supplies no decryption keys.' },
+    moderation_evidence: { current: 'Accept user-selected plaintext message evidence for moderation.', beforeMls: 'Design explicit selective disclosure/authenticity (including franking policy); never infer access to room keys.' },
+};
+/** The callback is the actual content processor, not a telemetry hook. Keeping
+ * the codec explicit ensures an opaque body cannot accidentally be processed by
+ * the JSON path. This is not authorization; callers still enforce their domain
+ * policy and every enabled transport currently requires JSON. */
+export function runPlaintextProcessor(name, input, process) {
+    if (!Object.hasOwn(PLAINTEXT_PROCESSORS, name) || input.encoding !== 'json') {
+        throw new Error('PLAINTEXT_PROCESSOR_CODEC_REQUIRED');
+    }
+    return process(input.value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "8.5.0",
+  "version": "8.6.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@canonmsg/rich-cards": "^0.10.5",
+    "@canonmsg/rich-cards": "^0.10.6",
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
     "typescript": "~5.7.0",