@namzu/sdk 48.3.1 → 50.0.0

package/src/pals/activity/types.ts

@@ -0,0 +1,108 @@
+import type { LogBytes } from '../../store/session-log/chain.js'
+import type { SessionLog } from '../../store/session-log/core.js'
+import type { ActivityStatus, ActivityType } from '../../types/activity/index.js'
+import type {
+	ActivityId,
+	CheckpointId,
+	ProjectId,
+	SessionId,
+	TenantId,
+	ToolUseId,
+	TurnId,
+} from '../../types/ids/index.js'
+import type { RecordPointer } from '../../types/session/records.js'
+import type { PalStore } from '../types.js'
+
+export interface PalActivityScope {
+	readonly tenantId: TenantId
+	readonly projectId: ProjectId
+	readonly palId: string
+	readonly profileRevision: number
+	readonly sessionId: SessionId
+}
+
+/**
+ * An unchanged previously emitted cursor, stored and resolved by the trusted host.
+ * Never accept a model, renderer or remote client's anchor directly. scopeHash binds
+ * ownership but does not authenticate a cursor; consumed prefixes are not rescanned.
+ */
+export interface PalActivityCursor {
+	readonly v: 1
+	readonly scopeHash: string
+	readonly root: RecordPointer
+	readonly after: RecordPointer
+	readonly generation: number
+}
+
+export type PalActivityFactType =
+	| 'turn_started'
+	| 'turn_resuming'
+	| 'turn_paused'
+	| 'turn_completed'
+	| 'turn_failed'
+	| 'activity_created'
+	| 'activity_updated'
+	| 'tool_executing'
+	| 'tool_completed'
+	| 'tool_review_requested'
+	| 'tool_review_completed'
+	| 'checkpoint_created'
+
+/** Allow-listed facts only. No descriptions, tool names, arguments, results or errors. */
+export interface PalActivityFact {
+	readonly id: string
+	readonly type: PalActivityFactType
+	readonly sessionId: SessionId
+	readonly turnId?: TurnId
+	readonly seq: number
+	readonly generation: number
+	readonly at: string
+	readonly activityId?: ActivityId
+	readonly activityType?: ActivityType
+	readonly status?: ActivityStatus
+	readonly toolUseId?: ToolUseId
+	readonly checkpointId?: CheckpointId
+	readonly reviewDecision?: 'approved' | 'modified' | 'rejected'
+}
+
+/** Host-owned read ports MUST address the same original journal, never a transcript cache. */
+export interface PalActivityJournal {
+	readonly log: Pick<SessionLog, 'sessionId'>
+	readonly bytes: LogBytes
+}
+
+export interface PalActivitySourceOptions {
+	readonly scope: PalActivityScope
+	readonly pals: PalStore
+	/** Current observation consent; checked before opening, original byte reads and output. */
+	readonly authorize: (scope: PalActivityScope, signal: AbortSignal) => Promise<boolean>
+	readonly openJournal: (
+		scope: PalActivityScope,
+		signal: AbortSignal,
+	) => Promise<PalActivityJournal>
+}
+
+export interface PalActivityReadOptions {
+	readonly signal: AbortSignal
+	/** Trusted host-stored output of an earlier read; never untrusted client input. */
+	readonly cursor?: PalActivityCursor
+	/** Maximum new history records inspected, including omitted records, excluding anchors (1–256). */
+	readonly maxRecords: number
+	/** Total bytes requested from the journal, including root/cursor anchors (1–16 MiB). */
+	readonly maxReadBytes: number
+}
+
+export interface PalActivityPage {
+	readonly scope: PalActivityScope
+	readonly facts: readonly PalActivityFact[]
+	readonly cursor: PalActivityCursor
+	/** Only the captured byte boundary was reached; later appends require another read. */
+	readonly complete: boolean
+	readonly scannedRecords: number
+	readonly readBytes: number
+}
+
+export interface PalActivitySource {
+	readonly scope: PalActivityScope
+	read(options: PalActivityReadOptions): Promise<PalActivityPage>
+}

package/src/pals/channels/ingress.ts

@@ -0,0 +1,153 @@
+import { isDeepStrictEqual } from 'node:util'
+import {
+	ingressIntentDigest,
+	ingressIntentId,
+	ingressIntentSchema,
+} from '../communication/ingress-schema.js'
+import type { PalChannelIdentity, PalChannelIntent } from '../communication/ingress-types.js'
+import { addressSchema, freezeCommunicationValue } from '../communication/schema.js'
+import {
+	captureConnection,
+	checkedDecision,
+	checkedIdentity,
+	verifiedMessageSchema,
+} from './schema.js'
+import type { PalChannelAuthorizationRequest, PalChannelIngressOptions } from './types.js'
+
+/** Authenticated channel ingress. Raw event fields never choose host credentials or Namzu identities. */
+export class PalChannelIngress {
+	private readonly connection
+	private readonly options: PalChannelIngressOptions
+	constructor(options: PalChannelIngressOptions) {
+		if (
+			typeof options.verify !== 'function' ||
+			typeof options.authorize !== 'function' ||
+			typeof options.selectRecipient !== 'function'
+		)
+			throw new Error(
+				'Channel ingress requires trusted verification, target selection and current authorization.',
+			)
+		this.connection = captureConnection(options.connection)
+		this.options = Object.freeze({ ...options })
+	}
+	async accept(raw: unknown, signal: AbortSignal = new AbortController().signal) {
+		signal.throwIfAborted()
+		// Capture before the verifier's first asynchronous boundary, including JavaScript host input.
+		const event = freezeCommunicationValue(
+			verifiedMessageSchema.parse(
+				await this.options.verify(structuredClone(raw), this.connection, signal),
+			),
+		)
+		signal.throwIfAborted()
+		const source = checkedIdentity(this.connection, {
+			externalTenantId: event.externalTenantId,
+			nativeConversationId: event.nativeConversationId,
+			nativeChannelId: event.nativeChannelId,
+			nativeThreadId: event.nativeThreadId,
+			actorId: event.actorId,
+			eventId: event.eventId,
+			kind: 'channel',
+			tenantId: this.connection.tenantId,
+			provider: this.connection.provider,
+			connectionId: this.connection.connectionId,
+		})
+		const identity: PalChannelIdentity = {
+			provider: source.provider,
+			connectionId: source.connectionId,
+			externalTenantId: source.externalTenantId,
+			nativeConversationId: source.nativeConversationId,
+			nativeChannelId: source.nativeChannelId,
+			nativeThreadId: source.nativeThreadId,
+		}
+		const { routes, pals, store } = this.options
+		const existing = await routes.get(this.connection, identity)
+		let decision = existing ? checkedDecision(existing) : null
+		if (!decision) {
+			const recipient = freezeCommunicationValue(
+				addressSchema.parse(await this.options.selectRecipient(event, this.connection)),
+			)
+			if (recipient.tenantId !== this.connection.tenantId)
+				throw new Error('Cross-tenant channel routing is refused.')
+			const pal = pals.get(recipient.palId)
+			if (!pal) throw new Error('Channel recipient Pal is unavailable.')
+			decision = checkedDecision({
+				v: 1,
+				revision: 1,
+				identity,
+				recipient,
+				profileRevision: pal.revision,
+			})
+		}
+		const request: PalChannelAuthorizationRequest = freezeCommunicationValue({
+			phase: 'accept',
+			kind: 'channel',
+			source,
+			recipient: decision.recipient,
+			routeKey: {
+				v: 1,
+				kind: 'channel',
+				...identity,
+				recipient: decision.recipient,
+			},
+			body: event.body,
+			replyTo: null,
+		})
+		let allowed = freezeCommunicationValue(structuredClone(await this.options.authorize(request)))
+		signal.throwIfAborted()
+		if (allowed.allow !== true) throw new Error(`Channel ingress refused: ${allowed.reason}`)
+		// Only authorized traffic can publish a routing decision. Concurrent first events share one target.
+		const reserved = checkedDecision(await routes.reserve(decision))
+		if (!isDeepStrictEqual(reserved, decision))
+			throw new Error('Channel routing decision changed during acceptance.')
+		decision = reserved
+		pals.getRevision(decision.recipient.palId, decision.profileRevision)
+		if (!pals.get(decision.recipient.palId))
+			throw new Error('Channel recipient Pal is unavailable.')
+		// Routing publication can await another process. Re-read event authority before committing its input.
+		allowed = freezeCommunicationValue(structuredClone(await this.options.authorize(request)))
+		signal.throwIfAborted()
+		if (allowed.allow !== true) throw new Error(`Channel ingress refused: ${allowed.reason}`)
+		const intent = {
+			kind: 'channel' as const,
+			source,
+			recipient: decision.recipient,
+			routeKey: request.routeKey,
+			body: event.body,
+			replyTo: null,
+			operationId: source.eventId,
+			grant: allowed.grant,
+			createdAt: (this.options.now ?? Date.now)(),
+		}
+		const identified = { ...intent, id: ingressIntentId(intent) }
+		const immutable = freezeCommunicationValue(
+			ingressIntentSchema.parse({
+				...identified,
+				digest: ingressIntentDigest(identified),
+			}),
+		) as PalChannelIntent
+		signal.throwIfAborted()
+		const receipt = await store.acceptIngress(immutable, decision.profileRevision)
+		const binding = await store.routeIngress(immutable.routeKey)
+		if (
+			!binding ||
+			binding.sessionId !== receipt.sessionId ||
+			binding.profileRevision !== decision.profileRevision
+		)
+			throw new Error('Channel acceptance does not match its immutable target binding.')
+		const report = (error: unknown) => {
+			try {
+				void Promise.resolve(this.options.onNotificationError?.(error, receipt)).catch(
+					() => undefined,
+				)
+			} catch {
+				/* Committed receipt remains accepted. */
+			}
+		}
+		try {
+			void Promise.resolve(this.options.host?.notify?.(decision.recipient)).catch(report)
+		} catch (error) {
+			report(error)
+		}
+		return receipt
+	}
+}

package/src/pals/channels/routes.ts

@@ -0,0 +1,118 @@
+import { chmodSync, lstatSync, mkdirSync, readdirSync, realpathSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import { DiskRevisionRecordStore } from '../../store/kv/revision-record-store.js'
+import { defineSchema } from '../../store/schema.js'
+import { channelRouteKeySchema } from '../communication/ingress-schema.js'
+import type { PalChannelIdentity } from '../communication/ingress-types.js'
+import { captureConnection, checkedDecision, decisionId } from './schema.js'
+import type { PalChannelConnection, PalChannelRouteDecision, PalChannelRoutes } from './types.js'
+
+export class PalChannelRouteConflictError extends Error {
+	override readonly name = 'PalChannelRouteConflictError'
+}
+class ExistingDecision extends Error {
+	constructor(readonly decision: PalChannelRouteDecision) {
+		super('Existing immutable channel route.')
+	}
+}
+function storedDecision(value: PalChannelRouteDecision): PalChannelRouteDecision {
+	// DiskRecordStore validates its own envelope; it is not part of the public route identity.
+	const { schemaVersion: _version, ...body } = value as PalChannelRouteDecision & {
+		schemaVersion?: number
+	}
+	return checkedDecision(body)
+}
+
+/** Immutable target decisions only. Session and delivery ownership remain in PalIngressStore. */
+export class DiskPalChannelRoutes implements PalChannelRoutes {
+	private readonly root: string
+	private readonly secure: (path: string) => void
+	private readonly records = new DiskRevisionRecordStore<PalChannelRouteDecision>(
+		defineSchema({ kind: 'pal-channel-route', current: 1, migrations: {} }),
+		'Pal channel route',
+		(record) => record.revision,
+	)
+	constructor(options: {
+		root: string
+		secureDirectory?: (path: string) => void
+	}) {
+		this.root = resolve(options.root)
+		this.secure =
+			options.secureDirectory ??
+			((path) => {
+				if (process.platform !== 'win32') chmodSync(path, 0o700)
+			})
+		this.directory(this.root)
+	}
+	private directory(path: string) {
+		mkdirSync(path, { recursive: true, mode: 0o700 })
+		const entry = lstatSync(path)
+		if (!entry.isDirectory() || entry.isSymbolicLink() || realpathSync(path) !== path)
+			throw new Error('Channel routes require real directories without aliases.')
+		this.secure(path)
+	}
+	private location(id: string) {
+		this.directory(this.root)
+		const directory = join(this.root, id)
+		this.directory(directory)
+		const revisionsDir = join(directory, 'revisions')
+		this.directory(revisionsDir)
+		for (const name of readdirSync(revisionsDir)) {
+			if (!/^[1-9][0-9]*\.json$/u.test(name)) continue
+			const entry = lstatSync(join(revisionsDir, name))
+			if (!entry.isFile() || entry.isSymbolicLink())
+				throw new Error('Channel route commits must be real files.')
+		}
+		const legacyPath = join(directory, 'route.json')
+		try {
+			const legacy = lstatSync(legacyPath)
+			if (!legacy.isFile() || legacy.isSymbolicLink())
+				throw new Error('Channel route projections must be real files.')
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+		}
+		return { legacyPath, revisionsDir, publishLegacyProjection: false }
+	}
+	async get(input: PalChannelConnection, value: PalChannelIdentity) {
+		const connection = captureConnection(input)
+		const identity = channelRouteKeySchema
+			.omit({ v: true, kind: true, recipient: true })
+			.parse(value)
+		if (
+			identity.provider !== connection.provider ||
+			identity.connectionId !== connection.connectionId ||
+			identity.externalTenantId !== connection.externalTenantId
+		)
+			throw new Error('Foreign channel route connection.')
+		const id = decisionId({
+			identity,
+			recipient: { tenantId: connection.tenantId, palId: '' },
+		})
+		const stored = await this.records.read(this.location(id))
+		if (!stored) return null
+		const decision = storedDecision(stored)
+		if (decisionId(decision) !== id || !isDeepStrictEqual(decision.identity, identity))
+			throw new Error('Channel route identity changed.')
+		return decision
+	}
+	async reserve(input: PalChannelRouteDecision) {
+		const decision = checkedDecision(input)
+		try {
+			return await this.records.transact(this.location(decisionId(decision)), (stored) => {
+				if (stored) {
+					const current = storedDecision(stored)
+					if (!isDeepStrictEqual(current, decision))
+						throw new PalChannelRouteConflictError(
+							'This native conversation already has an immutable Pal target.',
+						)
+					throw new ExistingDecision(current)
+				}
+				return { record: decision, result: decision }
+			})
+		} catch (error) {
+			if (error instanceof ExistingDecision) return error.decision
+			throw error
+		}
+	}
+}

package/src/pals/channels/routing.ts

@@ -0,0 +1,197 @@
+import { isDeepStrictEqual } from 'node:util'
+import { z } from 'zod'
+import type { SessionId } from '../../types/ids/index.js'
+import type { InboundDeliveryRef } from '../../types/message/inbound-delivery.js'
+import { isEntityId } from '../../utils/id.js'
+import { ingressInboxSchema } from '../communication/ingress-schema.js'
+import type { PalChannelIntent } from '../communication/ingress-types.js'
+import { PAL_CHANNEL_NAMESPACE, ingressMessageRef } from '../communication/ingress-types.js'
+import { addressSchema, freezeCommunicationValue, label } from '../communication/schema.js'
+import { verifyIngressRecorded } from '../communication/verify.js'
+import { captureConnection, nativeTuple, verifiedActionSchema } from './schema.js'
+import type {
+	PalChannelExecutionContext,
+	PalChannelResolvedRoute,
+	PalChannelRouterOptions,
+	PalChannelVerifiedAction,
+} from './types.js'
+
+const contextSchema = z
+	.object({
+		recipient: addressSchema,
+		sessionId: z.custom<SessionId>((value) => isEntityId(value, 'session')),
+		profileRevision: z.number().int().positive().safe(),
+	})
+	.strict()
+const refSchema = z
+	.object({
+		namespace: z.literal(PAL_CHANNEL_NAMESPACE),
+		id: z.string().regex(/^[a-f0-9]{64}$/),
+		digest: z.string().regex(/^[a-f0-9]{64}$/),
+	})
+	.strict()
+
+/** Resolves original authenticated destinations. It does not imply remote delivery. */
+export class PalChannelRouter {
+	private readonly options: PalChannelRouterOptions
+	private readonly connection
+	constructor(options: PalChannelRouterOptions) {
+		if (typeof options.verify !== 'function' || typeof options.authorize !== 'function')
+			throw new Error('Channel routing requires trusted verification and current authorization.')
+		this.options = Object.freeze({ ...options })
+		this.connection = captureConnection(options.connection)
+	}
+	private assertRecipient(context: PalChannelExecutionContext) {
+		if (context.recipient.tenantId !== this.connection.tenantId)
+			throw new Error('Foreign channel response tenant.')
+		const pal = this.options.pals.get(context.recipient.palId)
+		if (!pal || pal.paused) throw new Error('Channel response Pal is paused or unavailable.')
+		return this.options.pals.getRevision(pal.id, context.profileRevision)
+	}
+	private async recorded(
+		input: InboundDeliveryRef,
+		context: PalChannelExecutionContext,
+		signal: AbortSignal,
+	) {
+		const ref = freezeCommunicationValue(refSchema.parse(input))
+		const definition = this.assertRecipient(context)
+		const snapshot = await this.options.store.readIngress(context.recipient)
+		const found = snapshot?.messages.find((message) => message.id === ref.id)
+		if (!found) throw new Error('Channel response does not name an accepted delivery.')
+		const message = freezeCommunicationValue(ingressInboxSchema.parse(found))
+		if (
+			!('kind' in message) ||
+			message.kind !== 'channel' ||
+			message.phase !== 'recorded' ||
+			!message.receipt ||
+			!isDeepStrictEqual(ingressMessageRef(message), ref)
+		)
+			throw new Error('Channel response requires the exact recorded channel delivery.')
+		if (
+			message.source.tenantId !== this.connection.tenantId ||
+			message.source.provider !== this.connection.provider ||
+			message.source.connectionId !== this.connection.connectionId ||
+			message.source.externalTenantId !== this.connection.externalTenantId
+		)
+			throw new Error('Channel response belongs to another connection.')
+		if (!isDeepStrictEqual(nativeTuple(message.source), nativeTuple(message.routeKey)))
+			throw new Error('Channel message source does not match its original native route.')
+		const binding = await this.options.store.routeIngress(message.routeKey)
+		if (
+			!binding ||
+			binding.id !== message.routeId ||
+			binding.phase !== 'active' ||
+			binding.sessionId !== context.sessionId ||
+			binding.profileRevision !== context.profileRevision ||
+			binding.key.recipient.palId !== context.recipient.palId ||
+			binding.key.recipient.tenantId !== context.recipient.tenantId
+		)
+			throw new Error('Channel response belongs to another Pal conversation or profile.')
+		signal.throwIfAborted()
+		await verifyIngressRecorded(message, message.receipt, {
+			binding,
+			definition,
+			access: await this.options.host.openConversation(binding, signal),
+		})
+		signal.throwIfAborted()
+		this.assertRecipient(context)
+		return { ...message, receipt: message.receipt }
+	}
+	private async resolve(
+		input: InboundDeliveryRef,
+		context: PalChannelExecutionContext,
+		signal: AbortSignal,
+		action?: PalChannelVerifiedAction,
+	): Promise<PalChannelResolvedRoute> {
+		const message = await this.recorded(input, context, signal)
+		if (
+			action &&
+			(action.externalTenantId !== message.source.externalTenantId ||
+				!isDeepStrictEqual(
+					nativeTuple({
+						...action,
+						provider: this.connection.provider,
+						connectionId: this.connection.connectionId,
+					}),
+					nativeTuple(message.source),
+				))
+		)
+			throw new Error('Channel action belongs to another native conversation, channel or thread.')
+		const allowed = await this.options.authorize(
+			freezeCommunicationValue({
+				phase: action ? 'action' : 'reply',
+				message: message as PalChannelIntent,
+				context,
+				actorId: action?.actorId ?? message.source.actorId,
+				...(action ? { action } : {}),
+			}),
+		)
+		signal.throwIfAborted()
+		if (allowed.allow !== true) throw new Error(`Channel routing refused: ${allowed.reason}`)
+		this.assertRecipient(context)
+		return freezeCommunicationValue({
+			connection: this.connection,
+			identity: {
+				provider: message.source.provider,
+				connectionId: message.source.connectionId,
+				externalTenantId: message.source.externalTenantId,
+				nativeConversationId: message.source.nativeConversationId,
+				nativeChannelId: message.source.nativeChannelId,
+				nativeThreadId: message.source.nativeThreadId,
+			},
+			deliveryRef: {
+				namespace: PAL_CHANNEL_NAMESPACE,
+				id: message.id,
+				digest: message.digest,
+			},
+			recordedReceipt: message.receipt,
+			eventActorId: message.source.actorId,
+			currentActorId: action?.actorId ?? message.source.actorId,
+			context,
+		})
+	}
+	async replyRoute(
+		input: InboundDeliveryRef,
+		execution: PalChannelExecutionContext,
+		signal: AbortSignal = new AbortController().signal,
+	) {
+		const context = freezeCommunicationValue(contextSchema.parse(execution))
+		const ref = refSchema.parse(input)
+		signal.throwIfAborted()
+		return this.resolve(ref, context, signal)
+	}
+	async actionRoute(
+		raw: unknown,
+		execution: PalChannelExecutionContext,
+		signal: AbortSignal = new AbortController().signal,
+	) {
+		const context = freezeCommunicationValue(contextSchema.parse(execution))
+		signal.throwIfAborted()
+		const action = freezeCommunicationValue(
+			verifiedActionSchema.parse(
+				await this.options.verify(structuredClone(raw), this.connection, signal),
+			),
+		)
+		signal.throwIfAborted()
+		const route = await this.resolve(action.deliveryRef, context, signal, action)
+		return freezeCommunicationValue({ route, action })
+	}
+	async executeAction(
+		raw: unknown,
+		execution: PalChannelExecutionContext,
+		signal: AbortSignal = new AbortController().signal,
+	) {
+		if (!this.options.actions)
+			throw new Error('Channel action execution is unsupported by this host.')
+		const context = await this.actionRoute(raw, execution, signal)
+		signal.throwIfAborted()
+		this.assertRecipient(context.route.context)
+		const result = await this.options.actions.execute(context, signal)
+		return freezeCommunicationValue(
+			z
+				.object({ status: z.enum(['applied', 'rejected']), receiptId: label })
+				.strict()
+				.parse(result),
+		)
+	}
+}

package/src/pals/channels/schema.ts

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import { channelRouteKeySchema, channelSourceSchema } from '../communication/ingress-schema.js'
+import type { PalChannelIdentity } from '../communication/ingress-types.js'
+import { addressSchema, freezeCommunicationValue, hash, label } from '../communication/schema.js'
+import type { PalChannelConnection, PalChannelRouteDecision } from './types.js'
+
+export const connectionSchema = z
+	.object({
+		tenantId: addressSchema.shape.tenantId,
+		provider: label,
+		connectionId: label,
+		externalTenantId: label,
+	})
+	.strict()
+const verifiedIdentity = {
+	externalTenantId: label,
+	nativeConversationId: label,
+	nativeChannelId: label.nullable(),
+	nativeThreadId: label.nullable(),
+	actorId: label,
+	eventId: label,
+}
+export const verifiedMessageSchema = z
+	.object({
+		...verifiedIdentity,
+		kind: z.literal('message'),
+		body: z
+			.string()
+			.min(1)
+			.max(32_000)
+			.refine((value) => !value.includes('\0')),
+	})
+	.strict()
+export const verifiedActionSchema = z
+	.object({
+		...verifiedIdentity,
+		kind: z.literal('action'),
+		deliveryRef: z
+			.object({
+				namespace: z.literal('namzu-pal-channel/1'),
+				id: z.string().regex(/^[a-f0-9]{64}$/),
+				digest: z.string().regex(/^[a-f0-9]{64}$/),
+			})
+			.strict(),
+		actionId: label,
+		payloadDigest: z.string().regex(/^[a-f0-9]{64}$/),
+		payload: z
+			.string()
+			.min(1)
+			.max(32_000)
+			.refine((value) => !value.includes('\0')),
+	})
+	.strict()
+	.refine(
+		(value) => createHash('sha256').update(value.payload).digest('hex') === value.payloadDigest,
+		'Channel action payload does not match its authenticated digest.',
+	)
+export const routeDecisionSchema = z
+	.object({
+		v: z.literal(1),
+		revision: z.literal(1),
+		identity: channelRouteKeySchema.omit({
+			v: true,
+			kind: true,
+			recipient: true,
+		}),
+		recipient: addressSchema,
+		profileRevision: z.number().int().positive().safe(),
+	})
+	.strict()
+
+export function captureConnection(input: PalChannelConnection): PalChannelConnection {
+	return freezeCommunicationValue(connectionSchema.parse(input))
+}
+
+export function checkedIdentity(connection: PalChannelConnection, event: unknown) {
+	const source = channelSourceSchema.parse(event)
+	if (
+		source.tenantId !== connection.tenantId ||
+		source.provider !== connection.provider ||
+		source.connectionId !== connection.connectionId ||
+		source.externalTenantId !== connection.externalTenantId
+	)
+		throw new Error('Channel identity does not belong to the authenticated connection.')
+	return freezeCommunicationValue(source)
+}
+
+export function nativeTuple(identity: PalChannelIdentity): readonly unknown[] {
+	return [
+		identity.provider,
+		identity.connectionId,
+		identity.externalTenantId,
+		identity.nativeConversationId,
+		identity.nativeChannelId,
+		identity.nativeThreadId,
+	]
+}
+
+export function decisionId(
+	decision: Pick<PalChannelRouteDecision, 'identity' | 'recipient'>,
+): string {
+	return hash([1, decision.recipient.tenantId, nativeTuple(decision.identity)])
+}
+
+export function checkedDecision(input: unknown): PalChannelRouteDecision {
+	return freezeCommunicationValue(routeDecisionSchema.parse(input))
+}