@namzu/sdk 49.0.0 → 50.1.0

package/src/pals/activity/subscription-types.ts

@@ -0,0 +1,48 @@
+import type { PalAddress } from '../communication/types.js'
+import type { PalActivityCursor, PalActivityFact, PalActivityScope } from './types.js'
+
+/** Host-owned, immutable observation scope and destination, with separately revocable consent. */
+export interface PalActivitySubscription {
+	readonly v: 1
+	readonly id: string
+	readonly revision: number
+	readonly configurationRevision: number
+	readonly scope: PalActivityScope
+	readonly recipient: PalAddress
+	readonly enabled: boolean
+	readonly cursor: PalActivityCursor | null
+}
+
+export interface PalActivitySubscriptionStore {
+	get(id: string): Promise<PalActivitySubscription | null>
+	create(input: {
+		readonly id: string
+		readonly scope: PalActivityScope
+		readonly recipient: PalAddress
+		readonly enabled: boolean
+	}): Promise<PalActivitySubscription>
+	setEnabled(input: {
+		readonly id: string
+		readonly expectedRevision: number
+		readonly enabled: boolean
+	}): Promise<PalActivitySubscription>
+	/** Only an unchanged cursor emitted by the trusted original-journal source may be committed. */
+	advance(
+		subscription: PalActivitySubscription,
+		cursor: PalActivityCursor,
+	): Promise<PalActivitySubscription>
+}
+
+export interface PalActivitySubscriptionAuthorizationRequest {
+	/** `accept` requires observe, disclose and receive together immediately before inbox acceptance. */
+	readonly phase: 'observe' | 'disclose' | 'receive' | 'accept'
+	readonly subscription: PalActivitySubscription
+	readonly fact?: PalActivityFact
+}
+
+export interface PalActivitySubscriptionResult {
+	readonly subscription: PalActivitySubscription
+	readonly accepted: readonly string[]
+	readonly suppressed: readonly string[]
+	readonly complete: boolean
+}

package/src/pals/activity/subscriptions.ts

@@ -0,0 +1,209 @@
+import { isDeepStrictEqual } from 'node:util'
+import { z } from 'zod'
+import { ingressIntentDigest, ingressIntentId } from '../communication/ingress-schema.js'
+import type { PalIngressStore, PalObservationIntent } from '../communication/ingress-types.js'
+import { freezeCommunicationValue, hash, label } from '../communication/schema.js'
+import type { PalMessageAuthorization, PalMessageGrant } from '../communication/types.js'
+import type { PalStore } from '../types.js'
+import { createPalActivitySource } from './source.js'
+import { subscriptionSchema } from './subscription-schema.js'
+import type {
+	PalActivitySubscriptionAuthorizationRequest,
+	PalActivitySubscriptionResult,
+	PalActivitySubscriptionStore,
+} from './subscription-types.js'
+import type {
+	PalActivityFact,
+	PalActivityReadOptions,
+	PalActivityScope,
+	PalActivitySourceOptions,
+} from './types.js'
+
+export class PalActivitySubscriptionDeniedError extends Error {
+	override readonly name = 'PalActivitySubscriptionDeniedError'
+	constructor() {
+		super('Current Pal observation, disclosure and recipient consent are required.')
+	}
+}
+
+export interface PalActivitySubscriptionRunnerOptions {
+	readonly subscriptions: PalActivitySubscriptionStore
+	readonly ingress: PalIngressStore
+	readonly pals: PalStore
+	readonly openJournal: PalActivitySourceOptions['openJournal']
+	/**
+	 * Trusted current host policy. Observation, disclosure and receipt are independent decisions;
+	 * the final `accept` phase must require all three together under current consent.
+	 */
+	readonly authorize: (
+		request: PalActivitySubscriptionAuthorizationRequest,
+		signal: AbortSignal,
+	) => Promise<PalMessageAuthorization>
+	/**
+	 * Resolve prior subscription IDs from original turn delivery evidence retained by the host.
+	 * An independent turn yields []; unknown or incomplete evidence must reject. Never accept
+	 * a model, renderer or remote client's assertion about its own provenance.
+	 */
+	readonly resolveCausality: (
+		scope: PalActivityScope,
+		fact: PalActivityFact,
+		signal: AbortSignal,
+	) => Promise<readonly string[]>
+	readonly now?: () => number
+	/** Hint only. Observer failures and pending promises cannot prevent acceptance/progress. */
+	readonly notify?: (palId: string) => void | Promise<void>
+}
+
+/** One bounded page, no daemon and no inference. Progress follows durable inbox acceptance. */
+export async function publishPalActivityOnce(
+	options: PalActivitySubscriptionRunnerOptions,
+	id: string,
+	input: Omit<PalActivityReadOptions, 'cursor'>,
+): Promise<PalActivitySubscriptionResult> {
+	const subscriptionId = z.string().uuid().parse(id)
+	const { signal } = input
+	const { subscriptions, ingress, pals, openJournal, authorize, resolveCausality, notify } = options
+	const now = options.now ?? Date.now
+	if (
+		typeof authorize !== 'function' ||
+		typeof resolveCausality !== 'function' ||
+		typeof openJournal !== 'function'
+	)
+		throw new TypeError(
+			'Pal subscriptions require trusted policy, causality and original journal ports.',
+		)
+	signal.throwIfAborted()
+	const stored = await subscriptions.get(subscriptionId)
+	if (!stored) throw new PalActivitySubscriptionDeniedError()
+	const subscription = freezeCommunicationValue(subscriptionSchema.parse(stored))
+	async function current() {
+		signal.throwIfAborted()
+		const value = await subscriptions.get(subscriptionId)
+		signal.throwIfAborted()
+		if (
+			!value?.enabled ||
+			value.configurationRevision !== subscription.configurationRevision ||
+			!isDeepStrictEqual(value.scope, subscription.scope) ||
+			!isDeepStrictEqual(value.recipient, subscription.recipient)
+		)
+			throw new PalActivitySubscriptionDeniedError()
+	}
+	async function permitted(
+		phase: PalActivitySubscriptionAuthorizationRequest['phase'],
+		fact?: PalActivityFact,
+	): Promise<PalMessageGrant> {
+		await current()
+		const decision = await authorize(
+			freezeCommunicationValue({
+				phase,
+				subscription,
+				...(fact ? { fact } : {}),
+			}),
+			signal,
+		)
+		signal.throwIfAborted()
+		if (!decision.allow) throw new PalActivitySubscriptionDeniedError()
+		const grant = freezeCommunicationValue(
+			z.object({ id: label, revision: label }).strict().parse(decision.grant),
+		)
+		await current()
+		return grant
+	}
+	const source = createPalActivitySource({
+		scope: subscription.scope,
+		pals,
+		openJournal,
+		async authorize() {
+			await permitted('observe')
+			return true
+		},
+	})
+	const page = await source.read({
+		signal,
+		maxRecords: input.maxRecords,
+		maxReadBytes: input.maxReadBytes,
+		...(subscription.cursor ? { cursor: subscription.cursor } : {}),
+	})
+	const accepted: string[] = []
+	const suppressed: string[] = []
+	for (const fact of page.facts) {
+		const observed = await permitted('observe', fact)
+		const lineage = z
+			.array(z.string().uuid())
+			.refine((ids) => new Set(ids).size === ids.length)
+			.parse(await resolveCausality(subscription.scope, fact, signal))
+		signal.throwIfAborted()
+		await current()
+		if (lineage.includes(subscription.id)) {
+			suppressed.push(fact.id)
+			continue
+		}
+		const disclosed = await permitted('disclose', fact)
+		const received = await permitted('receive', fact)
+		const recipient = pals.get(subscription.recipient.palId)
+		if (!recipient) throw new PalActivitySubscriptionDeniedError()
+		const acceptedGrant = await permitted('accept', fact)
+		const draft = {
+			kind: 'observation' as const,
+			operationId: fact.id,
+			source: {
+				kind: 'host-observation' as const,
+				subscriptionId: subscription.id,
+				scope: subscription.scope,
+			},
+			recipient: subscription.recipient,
+			routeKey: {
+				v: 1 as const,
+				kind: 'observation' as const,
+				recipient: subscription.recipient,
+				subscriptionId: subscription.id,
+				scope: subscription.scope,
+			},
+			fact,
+			subscriptionTrail: [...lineage, subscription.id],
+			replyTo: null,
+			grant: {
+				id: hash([
+					'pal-observation-grants/1',
+					subscription.id,
+					observed.id,
+					disclosed.id,
+					received.id,
+					acceptedGrant.id,
+				]),
+				revision: hash([
+					subscription.configurationRevision,
+					observed.revision,
+					disclosed.revision,
+					received.revision,
+					acceptedGrant.revision,
+				]),
+			},
+			createdAt: now(),
+		}
+		const intentId = ingressIntentId(draft)
+		const intent = freezeCommunicationValue({
+			...draft,
+			id: intentId,
+			digest: ingressIntentDigest({ ...draft, id: intentId }),
+		}) as PalObservationIntent
+		await ingress.acceptIngress(intent, recipient.revision)
+		accepted.push(intent.id)
+		if (notify) {
+			try {
+				Promise.resolve(notify(subscription.recipient.palId)).catch(() => {})
+			} catch {}
+		}
+	}
+	await permitted('observe')
+	const next =
+		subscription.cursor && isDeepStrictEqual(subscription.cursor, page.cursor)
+			? subscription
+			: await subscriptions.advance(subscription, page.cursor)
+	return freezeCommunicationValue({
+		subscription: next,
+		accepted,
+		suppressed,
+		complete: page.complete,
+	})
+}

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
+		}
+	}
+}