@meshline/sdk 0.0.0-stage → 0.1.0-alpha.1

package/src/messages/receiver.ts

@@ -0,0 +1,86 @@
+import { decryptMessage, type MessageDecryptor } from '../crypto/messages.js';
+import { ProtocolError } from '../errors.js';
+import { certificateId, type DeviceCertificate } from '../models/identity.js';
+import { directMessageCodec, messageTimelinePageCodec, validateDirectMessage, validateMessageTimelinePage, type MessageTimelineEntry } from '../models/messages.js';
+import type { NetworkContext } from '../protocol/context.js';
+import type { JsonObject, JsonValue } from '../protocol/json.js';
+import { AsyncGate } from '../runtime/async-gate.js';
+import { throwIfAborted } from '../runtime/clock.js';
+import { MessageRepository, type MessageEffects, type MessageInfo } from './repository.js';
+
+export interface MessageReceptionPolicy {
+    /** Performs current authority checks and prepares a synchronous transaction effect. No mutations before commit. */
+    prepare(entry: MessageTimelineEntry, payload: JsonObject, signal?: AbortSignal): Promise<MessageEffects | undefined>;
+    /** Only permanent business validation failures qualify. Network, key access and storage failures must remain retryable. */
+    isPermanentRejection(error: unknown): error is ProtocolError;
+}
+export interface ReceptionResult { readonly messages: readonly MessageInfo[]; readonly rejected: readonly { readonly sequence: number; readonly error: ProtocolError }[]; readonly inserted: number }
+export interface TimelineSource { read(after: number, signal?: AbortSignal): Promise<JsonValue> }
+const permanentCryptographyCodes = new Set(['invalid_signature', 'invalid_identity', 'invalid_length', 'invalid_ciphertext', 'invalid_key', 'invalid_type',
+    'invalid_size', 'invalid_field', 'missing_field', 'invalid_null', 'unsupported_algorithm', 'invalid_identifier', 'invalid_account', 'invalid_json',
+    'duplicate_key', 'invalid_integer', 'invalid_unicode', 'invalid_utf8', 'invalid_object', 'invalid_encoding', 'invalid_base64url', 'invalid_context', 'invalid_model', 'conflicting_extension', 'invalid_number', 'invalid_depth']);
+
+/** A serial receiver keeps the first transiently failing entry ahead of the persisted cursor. */
+export class MessageReceiver {
+    readonly #gate = new AsyncGate();
+    constructor(readonly repository: MessageRepository, readonly context: NetworkContext, readonly device: MessageDecryptor, readonly policy: MessageReceptionPolicy) {}
+    /** Results are emitted after every committed page; callbacks must not block on stopping the owning runtime. */
+    synchronize(relayId: string, source: TimelineSource, committed: (result: ReceptionResult) => void, signal?: AbortSignal): Promise<void> {
+        return this.#gate.run(async () => {
+            while (true) {
+                throwIfAborted(signal);
+                const after = (await this.repository.getProgress(relayId, signal)).sequence;
+                const page = messageTimelinePageCodec.decode(await source.read(after, signal)); validateMessageTimelinePage(page, this.context, after);
+                const certificates = new Map(page.certificates.map(value => [certificateId(value, this.context), value]));
+                const messages: MessageInfo[] = []; const rejected: { sequence: number; error: ProtocolError }[] = []; let inserted = 0;
+                try {
+                    for (const entry of page.items) {
+                        const result = await this.#receive(relayId, entry, certificates.get(entry.envelope.fromDeviceId)!, page.hasRetentionGap === true, signal);
+                        if (result.error) rejected.push({ sequence: entry.sequence, error: result.error });
+                        if (result.inserted) { inserted++; if (result.message) messages.push(result.message); }
+                    }
+                    if (!page.items.length) await this.repository.acceptEmptyPage(relayId, page.hasRetentionGap === true, signal);
+                } finally {
+                    // Earlier entries stay committed if a later entry fails, and their notifications must not be lost.
+                    if (inserted || rejected.length) committed({ messages, rejected, inserted });
+                }
+                if (!page.hasMore) return;
+            }
+        }, signal);
+    }
+    async #receive(relayId: string, entry: MessageTimelineEntry, sender: DeviceCertificate, hasRetentionGap: boolean, signal?: AbortSignal): Promise<{ inserted: boolean; error?: ProtocolError; message?: MessageInfo }> {
+        if (await this.repository.acceptKnown(relayId, entry, hasRetentionGap, signal)) return { inserted: false };
+        let payload: JsonObject;
+        try { payload = await decryptMessage({ context: this.context, receiver: this.device, envelope: entry.envelope, keyBox: entry.keyBox, sender, ...(signal ? { signal } : {}) }); }
+        catch (error) {
+            throwIfAborted(signal);
+            if (!(error instanceof ProtocolError) || !permanentCryptographyCodes.has(error.code)) throw error;
+            await this.repository.reject(relayId, entry.sequence, error, hasRetentionGap, signal); return { inserted: false, error };
+        }
+        // The plaintext direct-message schema is deterministic; its rejection does not depend on local key/storage availability.
+        if (payload['$type'] === 'meshline.message.direct') {
+            try { validateDirectMessage(directMessageCodec.decode(payload)); }
+            catch (error) {
+                if (!(error instanceof ProtocolError)) throw error;
+                await this.repository.reject(relayId, entry.sequence, error, hasRetentionGap, signal); return { inserted: false, error };
+            }
+        }
+        let effects: MessageEffects | undefined;
+        try { effects = await this.policy.prepare(entry, payload, signal); }
+        catch (error) { return this.#rejectBusiness(relayId, entry, error, hasRetentionGap, signal); }
+        // Protection failures are local infrastructure failures, even when the protector throws a ProtocolError.
+        const message = await this.repository.prepare(entry.envelope, payload, signal);
+        try {
+            const result = await this.repository.accept(relayId, entry, message, hasRetentionGap, effects, signal);
+            return { ...result, ...(result.inserted && message.payloadType === 'meshline.message.direct' ? { message: {
+                ...directMessageCodec.decode(payload), key: { sender: message.sender, messageId: message.messageId }, senderDeviceId: message.senderDeviceId, recipient: message.recipient, createdAt: message.createdAt,
+            } } : {}) };
+        }
+        catch (error) { return this.#rejectBusiness(relayId, entry, error, hasRetentionGap, signal); }
+    }
+    async #rejectBusiness(relayId: string, entry: MessageTimelineEntry, error: unknown, hasRetentionGap: boolean, signal?: AbortSignal): Promise<{ inserted: false; error: ProtocolError }> {
+        throwIfAborted(signal);
+        if (!this.policy.isPermanentRejection(error)) throw error;
+        await this.repository.reject(relayId, entry.sequence, error, hasRetentionGap, signal); return { inserted: false, error };
+    }
+}

package/src/messages/repository.ts

@@ -0,0 +1,230 @@
+import { ProtocolError, StateConflictError } from '../errors.js';
+import { validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId, validateRelayId } from '../identity/neo.js';
+import type { SecretProtector } from '../interactions.js';
+import { directMessageCodec, messagePayloadCodec, validateDirectMessage, type DirectMessage, type MessageEnvelope, type MessageTimelineEntry } from '../models/messages.js';
+import type { NetworkContext } from '../protocol/context.js';
+import { decodeBase64Url, encodeBase64Url } from '../protocol/encoding.js';
+import { canonicalBytes, canonicalJson, parseJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { throwIfAborted, type RuntimeClock } from '../runtime/clock.js';
+import { requireBatchCount, type MeshlineStore, type QueryReader, type RecordKey, type RecordQuery, type StoredRecord, type StoreMutation, type StoreSnapshot } from '../storage/store.js';
+import { updateStore } from '../storage/transaction.js';
+import { encodeOutbox, outboxKey, type OutboxRecord } from './outbox.js';
+
+export interface MessageKey { readonly sender: string; readonly messageId: string }
+export interface MessageInfo extends DirectMessage {
+    readonly key: MessageKey; readonly senderDeviceId: string; readonly recipient: string; readonly createdAt: number;
+}
+export interface AccountMessage {
+    readonly localSequence: number; readonly sender: string; readonly senderDeviceId: string; readonly recipient: string; readonly messageId: string; readonly payload: JsonObject;
+}
+export interface StoredMessage extends MessageKey {
+    readonly senderDeviceId: string; readonly recipient: string; readonly createdAt: number; readonly payloadType: string;
+    readonly payload?: JsonObject; readonly protectedPayload?: string; readonly localSequence: number;
+}
+export type PreparedMessage = Omit<StoredMessage, 'localSequence'>;
+export interface TimelineProgress { readonly sequence: number; readonly hasRetentionGap: boolean; readonly lastSynchronizedAt?: number }
+export interface RecordGuard { readonly query: RecordKey; readonly value: JsonObject | undefined }
+/** Synchronous business validation and mutations join the same compare-and-commit as messages and cursors. */
+export interface MessageEffects {
+    readonly queries: readonly RecordQuery[];
+    plan(snapshot: StoreSnapshot): readonly StoreMutation[];
+    /** Owning runtime notification only; it must return immediately without awaiting application observers. */
+    committed?(snapshot: StoreSnapshot, mutations: readonly StoreMutation[]): void;
+}
+export interface MessageRepositoryOptions {
+    readonly store: MeshlineStore; readonly context: NetworkContext; readonly accountId: string; readonly deviceId: () => string;
+    readonly clock: RuntimeClock; readonly secretProtector?: SecretProtector;
+}
+export const messageKey = (value: MessageKey): RecordKey => {
+    validateAccountId(value.sender); validateIdentifier('message', value.messageId); return { collection: 'messages', key: `${value.sender}|${value.messageId}` };
+};
+export const timelineKey = (relayId: string): RecordKey => { validateRelayId(relayId); return { collection: 'message_timelines', key: relayId }; };
+const sequenceKey: RecordKey = { collection: 'message_meta', key: 'local_sequence' };
+const secretTypes = new Set(['meshline.account.group.state.sync', 'meshline.account.group.history_secret.sync']);
+const fingerprint = (value: JsonObject | undefined): string => canonicalJson(value ?? null);
+function progress(value: JsonObject | undefined): TimelineProgress {
+    if (!value) return { sequence: -1, hasRetentionGap: false };
+    requireSafeInteger(value.sequence, -1);
+    if (typeof value.hasRetentionGap !== 'boolean') throw new ProtocolError('invalid_storage', 'Invalid persisted timeline retention flag.');
+    if (value.lastSynchronizedAt !== undefined) requireSafeInteger(value.lastSynchronizedAt, 0);
+    return { sequence: value.sequence, hasRetentionGap: value.hasRetentionGap, ...(value.lastSynchronizedAt === undefined ? {} : { lastSynchronizedAt: value.lastSynchronizedAt }) };
+}
+function encodeMessage(value: StoredMessage): JsonObject {
+    return { sender: value.sender, messageId: value.messageId, senderDeviceId: value.senderDeviceId, recipient: value.recipient, createdAt: value.createdAt,
+        payloadType: value.payloadType, localSequence: value.localSequence, ...(value.payload === undefined ? {} : { payload: value.payload }),
+        ...(value.protectedPayload === undefined ? {} : { protectedPayload: value.protectedPayload }) };
+}
+function decodeMessage(row: StoredRecord): StoredMessage {
+    const value = row.value;
+    for (const name of ['sender', 'messageId', 'senderDeviceId', 'recipient', 'payloadType']) if (typeof value[name] !== 'string') throw new ProtocolError('invalid_storage', `Stored message has no ${name}.`);
+    const key = { sender: value.sender as string, messageId: value.messageId as string };
+    if (messageKey(key).key !== row.key) throw new ProtocolError('invalid_storage', 'Stored message identity differs from its key.');
+    validateAccountId(value.recipient as string); validateIdentifier('device', value.senderDeviceId as string); requireSafeInteger(value.createdAt, 0); requireSafeInteger(value.localSequence, 1);
+    const secret = secretTypes.has(value.payloadType as string);
+    if (secret ? value.payload !== undefined || typeof value.protectedPayload !== 'string' : value.protectedPayload !== undefined || value.payload === undefined)
+        throw new ProtocolError('invalid_storage', 'Message payload protection differs from its declared type.');
+    const payload = secret ? undefined : messagePayloadCodec.decode(value.payload!);
+    if (payload && payload['$type'] !== value.payloadType) throw new ProtocolError('invalid_storage', 'Stored message type differs from its payload.');
+    if (secret && decodeBase64Url(value.protectedPayload as string).length === 0) throw new ProtocolError('invalid_storage', 'Protected payload cannot be empty.');
+    return { ...key, senderDeviceId: value.senderDeviceId as string, recipient: value.recipient as string, createdAt: value.createdAt, payloadType: value.payloadType as string,
+        localSequence: value.localSequence, ...(payload ? { payload } : { protectedPayload: value.protectedPayload as string }) };
+}
+
+/** Internal persistence; callers must verify envelope signatures, decryption and business authorization before preparing an incoming record. */
+export class MessageRepository {
+    constructor(readonly options: MessageRepositoryOptions) {}
+    #belongsToAccount(value: Pick<StoredMessage, 'sender' | 'recipient'>): void {
+        if (value.sender !== this.options.accountId && value.recipient !== this.options.accountId) throw new ProtocolError('invalid_identity', 'Message does not belong to this account.');
+    }
+    #purpose(value: MessageKey): string {
+        const deviceId = this.options.deviceId(); validateIdentifier('device', deviceId);
+        return `Meshline/${this.options.context}/${this.options.accountId}/${deviceId}/messages/${value.sender}/${value.messageId}`;
+    }
+    async prepare(envelope: MessageEnvelope, source: JsonObject, signal?: AbortSignal): Promise<PreparedMessage> {
+        throwIfAborted(signal);
+        const payload = messagePayloadCodec.decode(source); const type = payload['$type'] as string;
+        if (type === 'meshline.message.direct') validateDirectMessage(directMessageCodec.decode(payload));
+        const value = { sender: envelope.from, messageId: envelope.messageId, senderDeviceId: envelope.fromDeviceId, recipient: envelope.to, createdAt: envelope.createdAt, payloadType: type };
+        messageKey(value); this.#belongsToAccount(value); validateIdentifier('device', value.senderDeviceId); requireSafeInteger(value.createdAt, 0);
+        if (!secretTypes.has(type)) return { ...value, payload };
+        const protector = this.options.secretProtector; if (!protector) throw new ProtocolError('protector_required', 'A secret protector is required to store group synchronization secrets.');
+        const plaintext = canonicalBytes(payload);
+        try {
+            const protectedData = await protector.protect(plaintext, this.#purpose(value), signal); throwIfAborted(signal);
+            if (!(protectedData instanceof Uint8Array) || !protectedData.length) throw new ProtocolError('invalid_protection', 'Secret protector returned no protected payload.');
+            return { ...value, protectedPayload: encodeBase64Url(protectedData) };
+        } finally { plaintext.fill(0); }
+    }
+    async #payload(value: StoredMessage, signal?: AbortSignal): Promise<JsonObject> {
+        this.#belongsToAccount(value); throwIfAborted(signal);
+        if (value.payload) return messagePayloadCodec.decode(value.payload);
+        const protector = this.options.secretProtector; if (!protector) throw new ProtocolError('protector_required', 'A secret protector is required to read group synchronization secrets.');
+        const plaintext = await protector.unprotect(decodeBase64Url(value.protectedPayload!), this.#purpose(value), signal);
+        try {
+            throwIfAborted(signal); const payload = messagePayloadCodec.decode(parseJson(plaintext));
+            if (payload['$type'] !== value.payloadType) throw new ProtocolError('invalid_storage', 'Unprotected payload type differs from the stored type.');
+            return payload;
+        } finally { plaintext.fill(0); }
+    }
+    async get(key: MessageKey, signal?: AbortSignal): Promise<MessageInfo | undefined> {
+        const row = (await this.options.store.read([messageKey(key)], signal)).sets[0]![0];
+        if (!row) return undefined; const value = decodeMessage(row); this.#belongsToAccount(value);
+        if (value.payloadType !== 'meshline.message.direct') return undefined;
+        return this.#info(value);
+    }
+    async contains(key: MessageKey, signal?: AbortSignal): Promise<boolean> {
+        const row = (await this.options.store.read([messageKey(key)], signal)).sets[0]![0];
+        if (!row) return false; this.#belongsToAccount(decodeMessage(row)); return true;
+    }
+    /** A previously committed message can advance another relay's cursor without needing historical decryption keys again. */
+    async acceptKnown(relayId: string, entry: MessageTimelineEntry, hasRetentionGap: boolean, signal?: AbortSignal): Promise<boolean> {
+        const key = timelineKey(relayId); requireSafeInteger(entry.sequence, 0); requireSafeInteger(entry.acceptedAt, 0);
+        const now = this.options.clock.nowSeconds(); requireSafeInteger(now, 0);
+        return updateStore(this.options.store, [key, messageKey({ sender: entry.envelope.from, messageId: entry.envelope.messageId })], snapshot => {
+            const known = snapshot.sets[1]![0]; if (!known) return { mutations: [], result: false };
+            this.#belongsToAccount(decodeMessage(known)); const current = progress(snapshot.sets[0]![0]?.value);
+            return { mutations: current.sequence >= entry.sequence ? [] : [{ kind: 'put', ...key, value: { sequence: entry.sequence, hasRetentionGap: current.hasRetentionGap || hasRetentionGap, lastSynchronizedAt: now } }], result: true };
+        }, signal);
+    }
+    #info(value: StoredMessage): MessageInfo {
+        this.#belongsToAccount(value); const direct = directMessageCodec.decode(value.payload!); validateDirectMessage(direct);
+        return { ...direct, key: { sender: value.sender, messageId: value.messageId }, senderDeviceId: value.senderDeviceId, recipient: value.recipient, createdAt: value.createdAt };
+    }
+    async history(peer?: string, signal?: AbortSignal): Promise<QueryReader<MessageInfo>> {
+        if (peer !== undefined) validateAccountId(peer);
+        const snapshot = await this.options.store.read([{ collection: 'messages' }], signal);
+        const records = snapshot.sets[0]!.map(decodeMessage).filter(value => value.payloadType === 'meshline.message.direct' && (peer === undefined
+            || value.sender === this.options.accountId && value.recipient === peer || value.sender === peer && value.recipient === this.options.accountId))
+            .sort((a, b) => a.createdAt - b.createdAt || compare(a.messageId, b.messageId) || compare(a.sender, b.sender));
+        return snapshotReader(records.map(value => this.#info(value)));
+    }
+    async readTimeline(after: number, count: number, signal?: AbortSignal): Promise<readonly AccountMessage[]> {
+        requireSafeInteger(after, 0); requireBatchCount(count);
+        const snapshot = await this.options.store.read([{ collection: 'messages' }], signal);
+        const records = snapshot.sets[0]!.map(decodeMessage).filter(value => value.localSequence > after).sort((a, b) => a.localSequence - b.localSequence).slice(0, count);
+        const results: AccountMessage[] = [];
+        for (const value of records) results.push({ localSequence: value.localSequence, sender: value.sender, senderDeviceId: value.senderDeviceId, recipient: value.recipient,
+            messageId: value.messageId, payload: await this.#payload(value, signal) });
+        return results;
+    }
+    async getProgress(relayId: string, signal?: AbortSignal): Promise<TimelineProgress> {
+        return progress((await this.options.store.read([timelineKey(relayId)], signal)).sets[0]![0]?.value);
+    }
+    async observeRelay(relayId: string, signal?: AbortSignal): Promise<void> {
+        const key = timelineKey(relayId);
+        await updateStore(this.options.store, [key], snapshot => ({ mutations: snapshot.sets[0]!.length ? [] : [{ kind: 'put', ...key, value: { sequence: -1, hasRetentionGap: false } }], result: undefined }), signal);
+    }
+    /** The caller provides state fingerprints captured before signing; unrelated store writes may be retried without signing again. */
+    async enqueue(outbox: OutboxRecord, message: PreparedMessage | undefined, guards: readonly RecordGuard[], effects?: MessageEffects, signal?: AbortSignal): Promise<void> {
+        const envelope = outbox.request.envelope; const key = outboxKey(envelope.messageId);
+        if (envelope.from !== this.options.accountId || outbox.state !== 'queued' || outbox.acceptedAt !== undefined) throw new ProtocolError('invalid_outbox', 'Only new local queued messages may be enqueued.');
+        if (outbox.isDirect !== Boolean(message) || message && message.payloadType !== 'meshline.message.direct') throw new ProtocolError('invalid_outbox', 'Only direct outgoing messages are inserted into local history at enqueue time.');
+        if (message && !matchesEnvelope(message, envelope)) throw new ProtocolError('invalid_outbox', 'Local message identity differs from the outgoing envelope.');
+        const queries: RecordQuery[] = [key, messageKey({ sender: envelope.from, messageId: envelope.messageId }), sequenceKey, ...guards.map(value => value.query), ...effects?.queries ?? []];
+        const document = encodeOutbox(outbox);
+        const committed = await updateStore(this.options.store, queries, snapshot => {
+            if (snapshot.sets[0]!.length || snapshot.sets[1]!.length) throw new StateConflictError('Outgoing message ID already exists.');
+            guards.forEach((guard, index) => { if (fingerprint(snapshot.sets[index + 3]![0]?.value) !== fingerprint(guard.value)) throw new StateConflictError('Message authorization changed while preparing the encrypted request.'); });
+            const mutations: StoreMutation[] = [{ kind: 'put', ...key, value: document }];
+            if (message) mutations.push(...insertMessage(message, snapshot.sets[2]![0]?.value));
+            const effectSnapshot = { ...snapshot, sets: snapshot.sets.slice(3 + guards.length) }; const effectMutations = effects?.plan(effectSnapshot) ?? [];
+            mutations.push(...effectMutations);
+            return { mutations, result: { snapshot: effectSnapshot, mutations: effectMutations } };
+        }, signal);
+        effects?.committed?.(committed.snapshot, committed.mutations);
+    }
+    async accept(relayId: string, entry: MessageTimelineEntry, message: PreparedMessage, hasRetentionGap: boolean, effects?: MessageEffects, signal?: AbortSignal): Promise<{ readonly advanced: boolean; readonly inserted: boolean }> {
+        if (!matchesEnvelope(message, entry.envelope)) throw new ProtocolError('invalid_message', 'Prepared message identity differs from the timeline envelope.');
+        this.#belongsToAccount(message); requireSafeInteger(entry.sequence, 0); requireSafeInteger(entry.acceptedAt, 0);
+        const key = timelineKey(relayId); const now = this.options.clock.nowSeconds(); requireSafeInteger(now, 0);
+        const result = await updateStore<{ advanced: boolean; inserted: boolean; snapshot?: StoreSnapshot; mutations?: readonly StoreMutation[] }>(this.options.store, [key, messageKey(message), sequenceKey, ...effects?.queries ?? []], snapshot => {
+            const current = progress(snapshot.sets[0]![0]?.value);
+            if (current.sequence >= entry.sequence) return { mutations: [], result: { advanced: false, inserted: false } };
+            const inserted = !snapshot.sets[1]!.length;
+            const mutations: StoreMutation[] = [{ kind: 'put', ...key, value: { sequence: entry.sequence, hasRetentionGap: hasRetentionGap || current.hasRetentionGap, lastSynchronizedAt: now } }];
+            const effectSnapshot = { ...snapshot, sets: snapshot.sets.slice(3) }; const effectMutations = inserted ? effects?.plan(effectSnapshot) ?? [] : [];
+            if (inserted) {
+                mutations.push(...effectMutations);
+                mutations.push(...insertMessage(message, snapshot.sets[2]![0]?.value));
+            }
+            return { mutations, result: { advanced: true, inserted, snapshot: effectSnapshot, mutations: effectMutations } };
+        }, signal);
+        if (result.inserted) effects?.committed?.(result.snapshot!, result.mutations!); return { advanced: result.advanced, inserted: result.inserted };
+    }
+    /** Rejected authenticated entries advance only when the receiver classifies the error as permanent protocol rejection. */
+    async reject(relayId: string, sequence: number, error: ProtocolError, hasRetentionGap: boolean, signal?: AbortSignal): Promise<boolean> {
+        requireSafeInteger(sequence, 0); const key = timelineKey(relayId); const now = this.options.clock.nowSeconds(); requireSafeInteger(now, 0);
+        return updateStore(this.options.store, [key], snapshot => {
+            const current = progress(snapshot.sets[0]![0]?.value); if (current.sequence >= sequence) return { mutations: [], result: false };
+            return { mutations: [
+                { kind: 'put', ...key, value: { sequence, hasRetentionGap: hasRetentionGap || current.hasRetentionGap, lastSynchronizedAt: now } },
+                { kind: 'put', collection: 'message_rejections', key: `${relayId}|${sequence.toString().padStart(16, '0')}`, value: { relayId, sequence, code: error.code, message: error.message, rejectedAt: now } },
+            ], result: true };
+        }, signal);
+    }
+    async acceptEmptyPage(relayId: string, hasRetentionGap: boolean, signal?: AbortSignal): Promise<void> {
+        const key = timelineKey(relayId); const now = this.options.clock.nowSeconds(); requireSafeInteger(now, 0);
+        await updateStore(this.options.store, [key], snapshot => {
+            const current = progress(snapshot.sets[0]![0]?.value);
+            return { mutations: [{ kind: 'put', ...key, value: { sequence: current.sequence, hasRetentionGap: current.hasRetentionGap || hasRetentionGap, lastSynchronizedAt: now } }], result: undefined };
+        }, signal);
+    }
+}
+function insertMessage(value: PreparedMessage, meta: JsonObject | undefined): StoreMutation[] {
+    const previous = meta?.sequence ?? 0; requireSafeInteger(previous, 0); const sequence = previous + 1; requireSafeInteger(sequence, 1);
+    return [{ kind: 'put', ...messageKey(value), value: encodeMessage({ ...value, localSequence: sequence }) }, { kind: 'put', ...sequenceKey, value: { sequence } }];
+}
+function matchesEnvelope(value: PreparedMessage, envelope: MessageEnvelope): boolean {
+    return value.sender === envelope.from && value.messageId === envelope.messageId && value.senderDeviceId === envelope.fromDeviceId && value.recipient === envelope.to && value.createdAt === envelope.createdAt;
+}
+function compare(a: string, b: string): number { return a < b ? -1 : a > b ? 1 : 0; }
+/** Materialized immutable query results; caller mutation of a returned page cannot affect later pages. */
+export function snapshotReader<T>(source: readonly T[]): QueryReader<T> {
+    let values: readonly T[] | undefined = source; let offset = 0;
+    return {
+        async readNext(count, signal) { throwIfAborted(signal); requireBatchCount(count); if (!values) throw new ProtocolError('disposed', 'Query reader is disposed.');
+            const result = values.slice(offset, offset + count); offset += result.length; return result; },
+        async dispose() { values = undefined; },
+    };
+}

package/src/models/authentication.ts

@@ -0,0 +1,63 @@
+import { ProtocolError } from '../errors.js';
+import { bytes, defineCodec, enumeration, integer, text, type ExtensibleModel } from '../protocol/codec.js';
+import { NetworkContext, signingInput } from '../protocol/context.js';
+import { encodeBase64Url } from '../protocol/encoding.js';
+import { requireSafeInteger } from '../protocol/json.js';
+import { validateCompleteObject } from '../protocol/validation.js';
+import { validateRelayId } from '../identity/neo.js';
+import { relayOrigin } from '../transport/endpoint.js';
+import { certificateId, deviceCertificateCodec, type DeviceCertificate } from './identity.js';
+
+export type SessionMode = 'account' | 'device';
+export interface AuthenticationChallenge extends ExtensibleModel { readonly nonce: string; readonly createdAt: number; readonly expiresAt: number }
+/** The token is a credential: never include this object in diagnostic logs. */
+export interface SessionCredentials extends ExtensibleModel { readonly token: string; readonly mode: SessionMode; readonly expiresAt: number }
+export interface AccountAuthenticationRequest extends ExtensibleModel { readonly nonce: string; readonly accountPublicKey: Uint8Array; readonly accountSignature: Uint8Array }
+export interface DeviceAuthenticationRequest extends ExtensibleModel { readonly nonce: string; readonly timestamp: number; readonly signerCertificate: DeviceCertificate; readonly deviceSignature: Uint8Array }
+
+export const authenticationChallengeCodec = defineCodec<AuthenticationChallenge>({
+    nonce: { wire: 'nonce', codec: text }, createdAt: { wire: 'created_at', codec: integer }, expiresAt: { wire: 'expires_at', codec: integer },
+});
+export const sessionCredentialsCodec = defineCodec<SessionCredentials>({
+    token: { wire: 'token', codec: text }, mode: { wire: 'mode', codec: enumeration('account', 'device') }, expiresAt: { wire: 'expires_at', codec: integer },
+});
+export const accountAuthenticationCodec = defineCodec<AccountAuthenticationRequest>({
+    nonce: { wire: 'nonce', codec: text }, accountPublicKey: { wire: 'account_public_key', codec: bytes }, accountSignature: { wire: 'account_signature', codec: bytes },
+});
+export const deviceAuthenticationCodec = defineCodec<DeviceAuthenticationRequest>({
+    nonce: { wire: 'nonce', codec: text }, timestamp: { wire: 'timestamp', codec: integer },
+    signerCertificate: { wire: 'signer_certificate', codec: deviceCertificateCodec }, deviceSignature: { wire: 'device_signature', codec: bytes },
+});
+
+export function validateAuthToken(value: string): void {
+    if (typeof value !== 'string' || value.length < 1 || value.length > 256 || /[^\x21-\x7e]/.test(value))
+        throw new ProtocolError('invalid_auth_token', 'Authentication tokens must contain 1 to 256 visible ASCII characters.');
+}
+
+export function validateChallenge(challenge: AuthenticationChallenge): void {
+    validateCompleteObject(authenticationChallengeCodec.encode(challenge));
+    validateAuthToken(challenge.nonce);
+    requireSafeInteger(challenge.createdAt, 0);
+    requireSafeInteger(challenge.expiresAt, 0);
+    if (challenge.expiresAt <= challenge.createdAt) throw new ProtocolError('invalid_time', 'Challenge expiry must follow its creation time.');
+}
+
+export function validateSession(credentials: SessionCredentials): void {
+    validateCompleteObject(sessionCredentialsCodec.encode(credentials));
+    validateAuthToken(credentials.token);
+    requireSafeInteger(credentials.expiresAt, 1);
+    if (credentials.mode !== 'account' && credentials.mode !== 'device') throw new ProtocolError('invalid_mode', 'Invalid session mode.');
+}
+
+/** Method-defined projection: request extensions cannot override the trusted target. */
+export function accountAuthenticationInput(request: AccountAuthenticationRequest, account: string, relayId: string, endpoint: string, context: NetworkContext): Uint8Array {
+    validateRelayId(relayId);
+    return signingInput({ $type: 'meshline.relay.account_auth', relay_id: relayId, origin: relayOrigin(endpoint),
+        account, account_public_key: encodeBase64Url(request.accountPublicKey), nonce: request.nonce }, context, []);
+}
+
+export function deviceAuthenticationInput(request: DeviceAuthenticationRequest, relayId: string, endpoint: string, context: NetworkContext): Uint8Array {
+    validateRelayId(relayId);
+    return signingInput({ $type: 'meshline.relay.auth', relay_id: relayId, origin: relayOrigin(endpoint), account: request.signerCertificate.account,
+        device_id: certificateId(request.signerCertificate, context), nonce: request.nonce, timestamp: request.timestamp }, context, []);
+}

package/src/models/channels.ts

@@ -0,0 +1,155 @@
+import { requireLength, verifyDevice } from '../crypto/primitives.js';
+import { ProtocolError } from '../errors.js';
+import { deriveResourceId, validateIdentifier } from '../identity/identifiers.js';
+import { validateAccountId, validateRelayId } from '../identity/neo.js';
+import { array, boolean, bytes, defineCodec, enumeration, integer, text, type ExtensibleModel, type ValueCodec } from '../protocol/codec.js';
+import { signingInput, type NetworkContext } from '../protocol/context.js';
+import { encodeUtf8 } from '../protocol/encoding.js';
+import { canonicalJson, requireObject, requireSafeInteger, type JsonObject } from '../protocol/json.js';
+import { validateCompleteObject } from '../protocol/validation.js';
+import { containsNonWhitespace, contentReferenceCodec, messageBodyCodec, validateAttachments, validateMessageBody, type ContentReference, type MessageBody } from './content.js';
+import { certificateId, deviceCertificateCodec, validateCertificate, type DeviceCertificate } from './identity.js';
+
+export interface ChannelRef { readonly channelId: string; readonly relayId: string }
+export interface ChannelPostRef { readonly channel: ChannelRef; readonly sequence: number }
+export function validateChannelRef(value: ChannelRef): void { validateIdentifier('channel', value.channelId); validateRelayId(value.relayId); }
+export function validateChannelPostRef(value: ChannelPostRef): void { validateChannelRef(value.channel); requireSafeInteger(value.sequence, 1); }
+export interface ChannelDescriptor extends ExtensibleModel {
+    readonly channelId: string; readonly nonce: Uint8Array; readonly creator: string; readonly relayId: string;
+    readonly name: string; readonly description?: string; readonly moderators?: readonly string[];
+    readonly revision: number; readonly status: 'active' | 'closed'; readonly createdAt: number; readonly updatedAt: number; readonly deviceSignature: Uint8Array;
+}
+export const channelDescriptorCodec = defineCodec<ChannelDescriptor>({
+    channelId: { wire: 'channel_id', codec: text }, nonce: { wire: 'nonce', codec: bytes }, creator: { wire: 'creator', codec: text }, relayId: { wire: 'relay_id', codec: text },
+    name: { wire: 'name', codec: text }, description: { wire: 'description', codec: text, optional: true }, moderators: { wire: 'moderators', codec: array(text), optional: true },
+    revision: { wire: 'revision', codec: integer }, status: { wire: 'status', codec: enumeration('active', 'closed') },
+    createdAt: { wire: 'created_at', codec: integer }, updatedAt: { wire: 'updated_at', codec: integer }, deviceSignature: { wire: 'device_signature', codec: bytes },
+}, 'meshline.channel.descriptor');
+export const channelDescriptorInput = (value: ChannelDescriptor, context: NetworkContext): Uint8Array => signingInput(channelDescriptorCodec.encode(value), context, ['device_signature']);
+function size(value: JsonObject, limit: number): void { if (encodeUtf8(canonicalJson(value)).length > limit) throw new ProtocolError('invalid_size', `Channel document exceeds ${limit} canonical JSON bytes.`); }
+export function validateChannelDescriptor(value: ChannelDescriptor, context: NetworkContext): void {
+    const wire = channelDescriptorCodec.encode(value); validateCompleteObject(wire); validateChannelRef(value); validateAccountId(value.creator); requireLength(value.nonce, 16, 'Channel nonce');
+    if (!containsNonWhitespace(value.name) || encodeUtf8(value.name).length > 256) throw new ProtocolError('invalid_name', 'Channel name requires text and at most 256 UTF-8 bytes.');
+    if (value.description !== undefined && value.description.length > 0 && (!containsNonWhitespace(value.description) || encodeUtf8(value.description).length > 4096)) throw new ProtocolError('invalid_description', 'Nonempty channel description requires text and at most 4096 UTF-8 bytes.');
+    requireSafeInteger(value.revision, 0); requireSafeInteger(value.createdAt, 0); requireSafeInteger(value.updatedAt, 0); requireLength(value.deviceSignature, 64, 'Channel signature');
+    if (value.revision === 0 && (value.status !== 'active' || value.createdAt !== value.updatedAt)) throw new ProtocolError('invalid_initial_state', 'Initial channel descriptor must be active with equal creation and update times.');
+    if (value.moderators) {
+        if (value.moderators.length > 10) throw new ProtocolError('invalid_size', 'At most ten channel moderators are permitted.');
+        const seen = new Set([value.creator]); for (const account of value.moderators) { validateAccountId(account); if (seen.has(account)) throw new ProtocolError('duplicate_moderator', 'Moderators must be distinct and cannot include the creator.'); seen.add(account); }
+    }
+    if (deriveResourceId('channel', value.creator, value.relayId, value.nonce, context) !== value.channelId) throw new ProtocolError('invalid_identity', 'Channel ID does not bind its creator, relay, nonce and context.'); size(wire, 8192);
+}
+export interface ChannelPost extends ExtensibleModel { readonly channelId: string; readonly messageId: string; readonly body?: MessageBody; readonly attachments?: readonly ContentReference[]; readonly deviceSignature: Uint8Array }
+export const channelPostCodec = defineCodec<ChannelPost>({ channelId: { wire: 'channel_id', codec: text }, messageId: { wire: 'message_id', codec: text }, body: { wire: 'body', codec: messageBodyCodec, optional: true },
+    attachments: { wire: 'attachments', codec: array(contentReferenceCodec), optional: true }, deviceSignature: { wire: 'device_signature', codec: bytes } }, 'meshline.channel.post');
+export const channelPostInput = (value: ChannelPost, context: NetworkContext): Uint8Array => signingInput(channelPostCodec.encode(value), context, ['device_signature']);
+export function validateChannelPost(value: ChannelPost): void {
+    const wire = channelPostCodec.encode(value); validateCompleteObject(wire); validateIdentifier('channel', value.channelId); validateIdentifier('message', value.messageId); requireLength(value.deviceSignature, 64, 'Post signature');
+    if (!value.body && !value.attachments?.length) throw new ProtocolError('content_required', 'Channel posts require a body or at least one attachment.');
+    if (value.body) validateMessageBody(value.body); if (value.attachments) validateAttachments(value.attachments); size(wire, 65536);
+}
+export interface ChannelPostEdit extends ExtensibleModel { readonly channelId: string; readonly targetSequence: number; readonly body?: MessageBody | null; readonly attachments?: readonly ContentReference[] | null; readonly deviceSignature: Uint8Array }
+export const channelPostEditCodec = defineCodec<ChannelPostEdit>({ channelId: { wire: 'channel_id', codec: text }, targetSequence: { wire: 'target_sequence', codec: integer },
+    body: { wire: 'body', codec: messageBodyCodec, optional: true, nullable: true }, attachments: { wire: 'attachments', codec: array(contentReferenceCodec), optional: true, nullable: true },
+    deviceSignature: { wire: 'device_signature', codec: bytes } }, 'meshline.channel.post.edit');
+export const channelPostEditInput = (value: ChannelPostEdit, context: NetworkContext): Uint8Array => signingInput(channelPostEditCodec.encode(value), context, ['device_signature']);
+export function validateChannelPostEdit(value: ChannelPostEdit): void {
+    const wire = channelPostEditCodec.encode(value); validateIdentifier('channel', value.channelId); requireSafeInteger(value.targetSequence, 1); requireLength(value.deviceSignature, 64, 'Post edit signature');
+    if (value.body === undefined && value.attachments === undefined && !Object.keys(value.additionalProperties ?? {}).length) throw new ProtocolError('empty_edit', 'A channel edit must change at least one field.');
+    for (const key of Object.keys(value.additionalProperties ?? {})) if (['$type', '$context', 'channel_id', 'message_id', 'body', 'attachments', 'device_signature'].includes(key)) throw new ProtocolError('invalid_extension', 'Edit extensions cannot replace defined post fields or context.');
+    // Only root field deletion markers may be null. Nested values remain complete objects.
+    for (const [key, field] of Object.entries(wire)) if (field !== null) validateCompleteObject({ [key]: field });
+    if (value.body) validateMessageBody(value.body); if (value.attachments) validateAttachments(value.attachments);
+    if (value.body === null && (value.attachments === null || value.attachments?.length === 0)) throw new ProtocolError('content_required', 'An edit cannot remove both body and every attachment.'); size(wire, 65536);
+}
+/** Applies replacement/deletion/omission in acceptance order and validates the resulting complete post. Does not alter signed evidence. */
+export function applyChannelPostEdit(post: ChannelPost, edit: ChannelPostEdit): ChannelPost {
+    validateChannelPost(post); validateChannelPostEdit(edit);
+    if (post.channelId !== edit.channelId) throw new ProtocolError('invalid_binding', 'Post edit belongs to another channel.');
+    const wire = channelPostCodec.encode(post); const changes = channelPostEditCodec.encode(edit);
+    for (const [key, value] of Object.entries(changes)) if (!['$type', 'channel_id', 'target_sequence', 'device_signature'].includes(key)) { if (value === null) delete wire[key]; else wire[key] = value; }
+    const result = channelPostCodec.decode(wire); validateChannelPost(result); return result;
+}
+export interface ChannelPostDelete extends ExtensibleModel { readonly channelId: string; readonly targetSequence: number; readonly reason?: string; readonly deviceSignature: Uint8Array }
+export const channelPostDeleteCodec = defineCodec<ChannelPostDelete>({ channelId: { wire: 'channel_id', codec: text }, targetSequence: { wire: 'target_sequence', codec: integer }, reason: { wire: 'reason', codec: text, optional: true }, deviceSignature: { wire: 'device_signature', codec: bytes } }, 'meshline.channel.post.delete');
+export const channelPostDeleteInput = (value: ChannelPostDelete, context: NetworkContext): Uint8Array => signingInput(channelPostDeleteCodec.encode(value), context, ['device_signature']);
+export function validateChannelPostDelete(value: ChannelPostDelete): void {
+    const wire = channelPostDeleteCodec.encode(value); validateCompleteObject(wire); validateIdentifier('channel', value.channelId); requireSafeInteger(value.targetSequence, 1); requireLength(value.deviceSignature, 64, 'Post deletion signature');
+    if (value.reason !== undefined && !containsNonWhitespace(value.reason)) throw new ProtocolError('invalid_reason', 'Deletion reason must contain text when present.'); size(wire, 65536);
+}
+export type ChannelPayload = { readonly kind: 'descriptor'; readonly value: ChannelDescriptor } | { readonly kind: 'post'; readonly value: ChannelPost } | { readonly kind: 'edit'; readonly value: ChannelPostEdit } | { readonly kind: 'delete'; readonly value: ChannelPostDelete };
+export const channelPayloadCodec: ValueCodec<ChannelPayload> = {
+    decode(value) { switch (requireObject(value)['$type']) {
+        case 'meshline.channel.descriptor': return { kind: 'descriptor', value: channelDescriptorCodec.decode(value) };
+        case 'meshline.channel.post': return { kind: 'post', value: channelPostCodec.decode(value) };
+        case 'meshline.channel.post.edit': return { kind: 'edit', value: channelPostEditCodec.decode(value) };
+        case 'meshline.channel.post.delete': return { kind: 'delete', value: channelPostDeleteCodec.decode(value) };
+        default: throw new ProtocolError('unsupported_type', 'Unsupported channel event payload.');
+    } },
+    encode(payload) { switch (payload.kind) { case 'descriptor': return channelDescriptorCodec.encode(payload.value); case 'post': return channelPostCodec.encode(payload.value); case 'edit': return channelPostEditCodec.encode(payload.value); case 'delete': return channelPostDeleteCodec.encode(payload.value); } },
+};
+export function validateChannelPayload(payload: ChannelPayload, context: NetworkContext): void {
+    switch (payload.kind) { case 'descriptor': return validateChannelDescriptor(payload.value, context); case 'post': return validateChannelPost(payload.value); case 'edit': return validateChannelPostEdit(payload.value); case 'delete': return validateChannelPostDelete(payload.value); }
+}
+export const channelPayloadInput = (payload: ChannelPayload, context: NetworkContext): Uint8Array => signingInput(requireObject(channelPayloadCodec.encode(payload)), context, ['device_signature']);
+export interface ChannelEvent extends ExtensibleModel { readonly sequence: number; readonly descriptorRev: number; readonly payload: ChannelPayload; readonly acceptedAt: number; readonly signerDeviceId: string }
+export const channelEventCodec = defineCodec<ChannelEvent>({ sequence: { wire: 'sequence', codec: integer }, descriptorRev: { wire: 'descriptor_rev', codec: integer }, payload: { wire: 'payload', codec: channelPayloadCodec }, acceptedAt: { wire: 'accepted_at', codec: integer }, signerDeviceId: { wire: 'signer_device_id', codec: text } });
+export function validateChannelEvent(value: ChannelEvent, context: NetworkContext): void {
+    const { payload, ...outer } = channelEventCodec.encode(value); validateCompleteObject(outer); validateChannelPayload(value.payload, context);
+    requireSafeInteger(value.sequence, 0); requireSafeInteger(value.descriptorRev, 0); requireSafeInteger(value.acceptedAt, 0); validateIdentifier('device', value.signerDeviceId);
+    if (value.sequence === 0 && (value.payload.kind !== 'descriptor' || value.payload.value.revision !== 0)) throw new ProtocolError('invalid_sequence', 'Sequence zero requires the initial channel descriptor.');
+    if (value.payload.kind === 'descriptor' && (value.payload.value.revision !== value.descriptorRev || value.sequence > 0 && value.payload.value.revision === 0)) throw new ProtocolError('invalid_revision', 'Descriptor event revision or initial sequence is inconsistent.');
+    if ((value.payload.kind === 'edit' || value.payload.kind === 'delete') && value.payload.value.targetSequence >= value.sequence) throw new ProtocolError('invalid_sequence', 'A channel edit or deletion must target an earlier positive post sequence.');
+}
+export interface ChannelResolveResult extends ExtensibleModel { readonly descriptor: ChannelDescriptor; readonly signerCertificate: DeviceCertificate }
+export const channelResolveResultCodec = defineCodec<ChannelResolveResult>({ descriptor: { wire: 'descriptor', codec: channelDescriptorCodec }, signerCertificate: { wire: 'signer_certificate', codec: deviceCertificateCodec } });
+export function verifyChannelDescriptor(value: ChannelResolveResult, context: NetworkContext, channel: ChannelRef): void {
+    validateCompleteObject(channelResolveResultCodec.encode(value)); validateChannelRef(channel); validateChannelDescriptor(value.descriptor, context); validateCertificate(value.signerCertificate, context);
+    if (value.descriptor.channelId !== channel.channelId || value.descriptor.relayId !== channel.relayId || value.signerCertificate.account !== value.descriptor.creator) throw new ProtocolError('invalid_binding', 'Channel descriptor or signer belongs to another resource or account.');
+    if (!verifyDevice(channelDescriptorInput(value.descriptor, context), value.descriptor.deviceSignature, value.signerCertificate.signingPublicKey)) throw new ProtocolError('invalid_signature', 'Invalid channel descriptor signature.');
+}
+export function verifyChannelEvent(value: ChannelEvent, certificate: DeviceCertificate, descriptor: ChannelDescriptor, context: NetworkContext, channel: ChannelRef): void {
+    validateChannelEvent(value, context); validateCertificate(certificate, context); validateChannelRef(channel);
+    if (certificateId(certificate, context) !== value.signerDeviceId || value.payload.value.channelId !== channel.channelId) throw new ProtocolError('invalid_binding', 'Channel event signer or resource binding is invalid.');
+    if (value.payload.kind === 'descriptor') { verifyChannelDescriptor({ descriptor: value.payload.value, signerCertificate: certificate }, context, channel); return; }
+    validateChannelDescriptor(descriptor, context);
+    if (descriptor.channelId !== channel.channelId || descriptor.relayId !== channel.relayId || descriptor.revision !== value.descriptorRev || descriptor.status !== 'active'
+        || descriptor.creator !== certificate.account && !descriptor.moderators?.includes(certificate.account)) throw new ProtocolError('unauthorized_event', 'Channel content signer is not authorized by the accepted descriptor revision.');
+    if (!verifyDevice(channelPayloadInput(value.payload, context), value.payload.value.deviceSignature, certificate.signingPublicKey)) throw new ProtocolError('invalid_signature', 'Invalid channel content signature.');
+}
+export interface ChannelReadQuery extends ExtensibleModel { readonly channelId: string; readonly before?: number; readonly after?: number; readonly limit?: number }
+export const channelReadQueryCodec = defineCodec<ChannelReadQuery>({ channelId: { wire: 'channel_id', codec: text }, before: { wire: 'before', codec: integer, optional: true }, after: { wire: 'after', codec: integer, optional: true }, limit: { wire: 'limit', codec: integer, optional: true } });
+export function validateChannelReadQuery(value: ChannelReadQuery): void {
+    validateCompleteObject(channelReadQueryCodec.encode(value)); validateIdentifier('channel', value.channelId); if (value.before !== undefined) requireSafeInteger(value.before, 0); if (value.after !== undefined) requireSafeInteger(value.after, -1); if (value.limit !== undefined) requireSafeInteger(value.limit, 1);
+    if (value.before !== undefined && value.after !== undefined) throw new ProtocolError('invalid_bounds', 'Channel before and after cursors cannot be combined.');
+}
+export interface ChannelReadPage extends ExtensibleModel { readonly events: readonly ChannelEvent[]; readonly certificates: readonly DeviceCertificate[]; readonly hasMore: boolean }
+export const channelReadPageCodec = defineCodec<ChannelReadPage>({ events: { wire: 'events', codec: array(channelEventCodec) }, certificates: { wire: 'certificates', codec: array(deviceCertificateCodec) }, hasMore: { wire: 'has_more', codec: boolean } });
+/** Validates page boundaries and historical certificate coverage; descriptor authorization is checked by the reader before persistence. */
+export function validateChannelReadPage(value: ChannelReadPage, query: ChannelReadQuery, context: NetworkContext): ReadonlyMap<string, DeviceCertificate> {
+    validateChannelReadQuery(query); const { events, ...outer } = channelReadPageCodec.encode(value); validateCompleteObject(outer);
+    if (value.hasMore && !value.events.length || query.limit !== undefined && value.events.length > query.limit) throw new ProtocolError('invalid_page', 'Invalid channel page size or pagination.');
+    const certificates = new Map<string, DeviceCertificate>();
+    for (const certificate of value.certificates) { validateCertificate(certificate, context); const id = certificateId(certificate, context); if (certificates.has(id)) throw new ProtocolError('duplicate_certificate', 'Channel page contains duplicate device identities.'); certificates.set(id, certificate); }
+    let previous = query.after ?? -1; const revisions = new Set<number>();
+    for (const event of value.events) {
+        validateChannelEvent(event, context);
+        if (event.sequence <= previous || query.before !== undefined && event.sequence >= query.before) throw new ProtocolError('invalid_sequence', 'Channel page violates requested bounds or sequence order.'); previous = event.sequence;
+        if (!certificates.has(event.signerDeviceId)) throw new ProtocolError('missing_certificate', 'Channel event lacks signing evidence.');
+        if (event.payload.kind === 'descriptor') { if (revisions.has(event.descriptorRev)) throw new ProtocolError('duplicate_revision', 'Descriptor revision occurs twice in one page.'); revisions.add(event.descriptorRev); }
+    }
+    return certificates;
+}
+export interface ChannelResolveQuery extends ExtensibleModel { readonly channelId: string; readonly revision?: number }
+export const channelResolveQueryCodec = defineCodec<ChannelResolveQuery>({ channelId: { wire: 'channel_id', codec: text }, revision: { wire: 'revision', codec: integer, optional: true } });
+export interface ChannelCloseRequest extends ExtensibleModel { readonly channelId: string; readonly revision: number; readonly updatedAt: number; readonly deviceSignature: Uint8Array }
+export const channelCloseRequestCodec = defineCodec<ChannelCloseRequest>({ channelId: { wire: 'channel_id', codec: text }, revision: { wire: 'revision', codec: integer }, updatedAt: { wire: 'updated_at', codec: integer }, deviceSignature: { wire: 'device_signature', codec: bytes } });
+export interface ChannelReportRequest extends ExtensibleModel { readonly channelId: string; readonly targetSequence: number; readonly reason: string }
+export const channelReportRequestCodec = defineCodec<ChannelReportRequest>({ channelId: { wire: 'channel_id', codec: text }, targetSequence: { wire: 'target_sequence', codec: integer }, reason: { wire: 'reason', codec: text } });
+export function validateChannelReportRequest(value: ChannelReportRequest): void { validateCompleteObject(channelReportRequestCodec.encode(value)); validateIdentifier('channel', value.channelId); requireSafeInteger(value.targetSequence, 1); if (!containsNonWhitespace(value.reason)) throw new ProtocolError('invalid_reason', 'A channel report requires a reason.'); }
+export interface ChannelSubscriptionRequest extends ExtensibleModel { readonly channelIds: readonly string[] }
+export const channelSubscriptionRequestCodec = defineCodec<ChannelSubscriptionRequest>({ channelIds: { wire: 'channel_ids', codec: array(text) } });
+export function validateChannelSubscriptionRequest(value: ChannelSubscriptionRequest): void { validateCompleteObject(channelSubscriptionRequestCodec.encode(value)); const seen = new Set<string>(); for (const id of value.channelIds) { validateIdentifier('channel', id); if (seen.has(id)) throw new ProtocolError('duplicate_channel', 'Subscription contains a duplicate channel.'); seen.add(id); } }
+export interface ChannelTimelineChangedNotification extends ExtensibleModel { readonly channelId: string; readonly head: number }
+export const channelTimelineChangedCodec = defineCodec<ChannelTimelineChangedNotification>({ channelId: { wire: 'channel_id', codec: text }, head: { wire: 'head', codec: integer } });
+export function validateChannelTimelineChanged(value: ChannelTimelineChangedNotification): void { validateCompleteObject(channelTimelineChangedCodec.encode(value)); validateIdentifier('channel', value.channelId); requireSafeInteger(value.head, 0); }