@namzu/sdk 49.0.0 → 50.0.0

package/src/pals/activity/source.ts

@@ -0,0 +1,240 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import { parseSessionLogLine } from '../../session/log-hash.js'
+import { SessionLogChain, type SessionLogEntry } from '../../store/session-log/chain.js'
+import { type RecordPointer, SESSION_RECORD_MAX_BYTES } from '../../types/session/records.js'
+import { isEntityId } from '../../utils/id.js'
+import { projectPalActivity } from './projection.js'
+import type {
+	PalActivityCursor,
+	PalActivityFact,
+	PalActivityReadOptions,
+	PalActivityScope,
+	PalActivitySource,
+	PalActivitySourceOptions,
+} from './types.js'
+
+export class PalActivityAccessDeniedError extends Error {
+	override readonly name = 'PalActivityAccessDeniedError'
+	constructor() {
+		super('Current Pal activity observation permission is required.')
+	}
+}
+export class PalActivityIntegrityError extends Error {
+	override readonly name = 'PalActivityIntegrityError'
+	constructor() {
+		super('Pal activity journal ownership or anchor evidence is invalid or incomplete.')
+	}
+}
+export class PalActivityReadLimitError extends Error {
+	override readonly name = 'PalActivityReadLimitError'
+	constructor() {
+		super('The Pal activity byte budget cannot cover another complete record and its anchors.')
+	}
+}
+
+const positive = z.number().int().positive().safe()
+const digest = z.string().regex(/^[a-f0-9]{64}$/)
+const pointer = z
+	.object({
+		seq: positive,
+		offset: z.number().int().nonnegative().safe(),
+		length: positive.max(SESSION_RECORD_MAX_BYTES),
+		sha256: digest,
+	})
+	.strict()
+const scopeSchema = z
+	.object({
+		tenantId: z.custom<PalActivityScope['tenantId']>((v) => isEntityId(v, 'tenant')),
+		projectId: z.custom<PalActivityScope['projectId']>((v) => isEntityId(v, 'project')),
+		sessionId: z.custom<PalActivityScope['sessionId']>((v) => isEntityId(v, 'session')),
+		palId: z.string().uuid(),
+		profileRevision: positive,
+	})
+	.strict()
+const cursorSchema = z
+	.object({
+		v: z.literal(1),
+		scopeHash: digest,
+		root: pointer,
+		after: pointer,
+		generation: z.number().int().nonnegative().safe(),
+	})
+	.strict()
+function samePointer(one: RecordPointer, two: RecordPointer): boolean {
+	return (
+		one.seq === two.seq &&
+		one.offset === two.offset &&
+		one.length === two.length &&
+		one.sha256 === two.sha256
+	)
+}
+function immutableCursor(value: PalActivityCursor): PalActivityCursor {
+	return Object.freeze({
+		...value,
+		root: Object.freeze({ ...value.root }),
+		after: Object.freeze({ ...value.after }),
+	})
+}
+
+/** Bounded original-byte reads, with current host consent and exact Pal-root admission. */
+export function createPalActivitySource(options: PalActivitySourceOptions): PalActivitySource {
+	const scope = Object.freeze(scopeSchema.parse(options.scope))
+	const { pals, authorize, openJournal } = options
+	if (typeof authorize !== 'function' || typeof openJournal !== 'function')
+		throw new TypeError('Pal activity requires explicit authorization and original-journal ports.')
+	return {
+		scope,
+		async read(input: PalActivityReadOptions) {
+			const { signal } = input
+			const maxRecords = positive.max(256).parse(input.maxRecords)
+			const maxReadBytes = positive.max(16 * 1024 * 1024).parse(input.maxReadBytes)
+			const supplied = input.cursor ? cursorSchema.parse(input.cursor) : undefined
+			signal.throwIfAborted()
+			if ((await authorize(scope, signal)) !== true) throw new PalActivityAccessDeniedError()
+			signal.throwIfAborted()
+			const definition = pals.getRevision(scope.palId, scope.profileRevision)
+			if (definition.id !== scope.palId || definition.revision !== scope.profileRevision)
+				throw new PalActivityIntegrityError()
+			const workspace = definition.workspace
+			const scopeHash = createHash('sha256')
+				.update(
+					JSON.stringify([
+						'pal-activity/1',
+						scope.tenantId,
+						scope.projectId,
+						scope.palId,
+						scope.profileRevision,
+						scope.sessionId,
+						workspace,
+					]),
+				)
+				.digest('hex')
+			if (supplied && supplied.scopeHash !== scopeHash) throw new PalActivityIntegrityError()
+			const journal = await openJournal(scope, signal)
+			signal.throwIfAborted()
+			if (journal.log.sessionId !== scope.sessionId) throw new PalActivityIntegrityError()
+			const bytes = journal.bytes
+			const size = await bytes.size()
+			signal.throwIfAborted()
+			if (!Number.isSafeInteger(size) || size < 1) throw new PalActivityIntegrityError()
+			if ((await authorize(scope, signal)) !== true) throw new PalActivityAccessDeniedError()
+			signal.throwIfAborted()
+			let readBytes = 0
+			const read = async (offset: number, length: number): Promise<Uint8Array> => {
+				signal.throwIfAborted()
+				if (length > maxReadBytes - readBytes) throw new PalActivityReadLimitError()
+				readBytes += length
+				const raw = await bytes.read(offset, length)
+				signal.throwIfAborted()
+				if (raw.byteLength !== length) throw new PalActivityIntegrityError()
+				return Uint8Array.from(raw)
+			}
+			const lineAt = async (offset: number): Promise<Uint8Array> => {
+				const parts: Uint8Array[] = []
+				let length = 0
+				while (offset + length < size) {
+					const available = maxReadBytes - readBytes
+					if (available === 0) throw new PalActivityReadLimitError()
+					const chunk = await read(
+						offset + length,
+						Math.min(1024, available, size - offset - length),
+					)
+					const newline = chunk.indexOf(10)
+					const part = newline < 0 ? chunk : chunk.subarray(0, newline + 1)
+					parts.push(part)
+					length += part.byteLength
+					if (length > SESSION_RECORD_MAX_BYTES) throw new PalActivityReadLimitError()
+					if (newline >= 0) return Buffer.concat(parts)
+				}
+				throw new PalActivityIntegrityError()
+			}
+			const first = await lineAt(0)
+			let root: SessionLogEntry
+			try {
+				root = new SessionLogChain({ head: null, sessionId: scope.sessionId }).accept(first, 0)
+			} catch {
+				throw new PalActivityIntegrityError()
+			}
+			const owner = root.record
+			if (
+				owner.type !== 'session_started' ||
+				owner.parent ||
+				owner.forkedFrom ||
+				owner.tenantId !== scope.tenantId ||
+				owner.projectId !== scope.projectId ||
+				owner.cwd !== workspace ||
+				owner.origin?.protocol !== 'desktop' ||
+				owner.origin.externalSessionId !==
+					JSON.stringify(['namzu-pal', scope.palId, scope.profileRevision, scope.sessionId])
+			)
+				throw new PalActivityIntegrityError()
+			if ((await read(size - 1, 1))[0] !== 10) throw new PalActivityIntegrityError()
+			let after = root.pointer
+			let generation = root.record.gen
+			if (supplied) {
+				const anchorEnd = supplied.after.offset + supplied.after.length
+				if (
+					!samePointer(root.pointer, supplied.root) ||
+					!Number.isSafeInteger(anchorEnd) ||
+					anchorEnd > size ||
+					supplied.after.seq < 1 ||
+					(supplied.after.seq > 1 && supplied.after.offset < root.pointer.length)
+				)
+					throw new PalActivityIntegrityError()
+				let anchor: ReturnType<typeof parseSessionLogLine>
+				try {
+					anchor = parseSessionLogLine(await read(supplied.after.offset, supplied.after.length))
+				} catch (error) {
+					signal.throwIfAborted()
+					if (error instanceof PalActivityReadLimitError) throw error
+					throw new PalActivityIntegrityError()
+				}
+				if (
+					anchor.sha256 !== supplied.after.sha256 ||
+					anchor.record.sessionId !== scope.sessionId ||
+					anchor.record.seq !== supplied.after.seq ||
+					anchor.record.gen !== supplied.generation ||
+					(supplied.after.seq === 1 && !samePointer(supplied.after, root.pointer))
+				)
+					throw new PalActivityIntegrityError()
+				after = supplied.after
+				generation = anchor.record.gen
+			}
+			const chain = new SessionLogChain({
+				head: after,
+				sessionId: scope.sessionId,
+				gen: generation,
+			})
+			const facts: PalActivityFact[] = []
+			let scannedRecords = 0
+			while (chain.end < size && scannedRecords < maxRecords) {
+				const raw = await lineAt(chain.end)
+				let entry: SessionLogEntry
+				let fact: PalActivityFact | null
+				try {
+					entry = chain.accept(raw, chain.end)
+					fact = projectPalActivity(entry, scopeHash)
+				} catch {
+					throw new PalActivityIntegrityError()
+				}
+				scannedRecords++
+				if (fact) facts.push(fact)
+				after = entry.pointer
+				generation = entry.record.gen
+			}
+			if ((await bytes.size()) < size) throw new PalActivityIntegrityError()
+			signal.throwIfAborted()
+			if ((await authorize(scope, signal)) !== true) throw new PalActivityAccessDeniedError()
+			signal.throwIfAborted()
+			return Object.freeze({
+				scope,
+				facts: Object.freeze(facts),
+				cursor: immutableCursor({ v: 1, scopeHash, root: root.pointer, after, generation }),
+				complete: chain.end === size,
+				scannedRecords,
+				readBytes,
+			})
+		},
+	}
+}

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

@@ -0,0 +1,230 @@
+import { chmodSync, lstatSync, mkdirSync, readdirSync, realpathSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import { z } from 'zod'
+import { DiskRevisionRecordStore } from '../../store/kv/revision-record-store.js'
+import { defineSchema } from '../../store/schema.js'
+import {
+	observationRouteKeySchema,
+	observationSourceSchema,
+} from '../communication/ingress-schema.js'
+import type { PalIngressAuthorizationRequest } from '../communication/ingress-types.js'
+import { addressSchema, freezeCommunicationValue } from '../communication/schema.js'
+import type { PalMessageAuthorization } from '../communication/types.js'
+import { subscriptionSchema } from './subscription-schema.js'
+import type {
+	PalActivitySubscriptionAuthorizationRequest,
+	PalActivitySubscriptionStore,
+} from './subscription-types.js'
+
+export interface PalActivitySubscriptionPermission {
+	readonly v: 1
+	readonly subscriptionId: string
+	readonly revision: number
+	readonly observe: boolean
+	readonly disclose: boolean
+	readonly receive: boolean
+	readonly wake: boolean
+}
+export interface PalActivitySubscriptionPermissionUpdate
+	extends Omit<PalActivitySubscriptionPermission, 'v' | 'revision'> {
+	readonly expectedRevision: number
+}
+export class PalActivitySubscriptionPermissionConflictError extends Error {
+	override readonly name = 'PalActivitySubscriptionPermissionConflictError'
+}
+const permissionSchema = z
+	.object({
+		v: z.literal(1),
+		subscriptionId: z.string().uuid(),
+		revision: z.number().int().positive().safe(),
+		observe: z.boolean(),
+		disclose: z.boolean(),
+		receive: z.boolean(),
+		wake: z.boolean(),
+	})
+	.strict()
+const updateSchema = permissionSchema
+	.omit({ v: true, revision: true })
+	.extend({ expectedRevision: z.number().int().nonnegative().safe() })
+const denied = (): PalMessageAuthorization => ({
+	allow: false,
+	reason: 'No current permission for this exact Pal activity subscription.',
+})
+
+/** Explicit local operator consent. Missing rules deny and each phase rereads current records. */
+export class DiskPalActivitySubscriptionPolicy {
+	private readonly root: string
+	private readonly secure: (path: string) => void
+	private readonly subscriptions: PalActivitySubscriptionStore
+	private readonly records = new DiskRevisionRecordStore<PalActivitySubscriptionPermission>(
+		defineSchema({
+			kind: 'pal-activity-subscription-permission',
+			current: 1,
+			migrations: {},
+		}),
+		'Pal activity subscription permission',
+		(value) => value.revision,
+	)
+	constructor(options: {
+		root: string
+		subscriptions: PalActivitySubscriptionStore
+		secureDirectory?: (path: string) => void
+	}) {
+		this.root = resolve(options.root)
+		this.subscriptions = options.subscriptions
+		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 stat = lstatSync(path)
+		if (!stat.isDirectory() || stat.isSymbolicLink() || realpathSync(path) !== path)
+			throw new Error('Pal activity permissions require real directories without aliases.')
+		this.secure(path)
+	}
+	private location(id: string) {
+		const key = z.string().uuid().parse(id)
+		this.directory(this.root)
+		const directory = join(this.root, key)
+		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 stat = lstatSync(join(revisionsDir, name))
+			if (!stat.isFile() || stat.isSymbolicLink())
+				throw new Error('Pal permission commits must be real files.')
+		}
+		return {
+			legacyPath: join(directory, 'permission.json'),
+			revisionsDir,
+			publishLegacyProjection: false,
+		}
+	}
+	private checked(input: unknown, id: string) {
+		const { schemaVersion: _schemaVersion, ...value } = permissionSchema
+			.extend({ schemaVersion: z.literal(1).optional() })
+			.parse(input)
+		if (value.subscriptionId !== id) throw new Error('Foreign Pal subscription permission.')
+		return freezeCommunicationValue(value)
+	}
+	async get(id: string): Promise<PalActivitySubscriptionPermission | null> {
+		const record = await this.records.read(this.location(id))
+		return record === null ? null : this.checked(record, id)
+	}
+	async update(
+		input: PalActivitySubscriptionPermissionUpdate,
+	): Promise<PalActivitySubscriptionPermission> {
+		const captured = updateSchema.parse(input)
+		if (!(await this.subscriptions.get(captured.subscriptionId)))
+			throw new Error('Unknown Pal activity subscription.')
+		return this.records.transact(this.location(captured.subscriptionId), (stored) => {
+			const current = stored === null ? null : this.checked(stored, captured.subscriptionId)
+			if ((current?.revision ?? 0) !== captured.expectedRevision)
+				throw new PalActivitySubscriptionPermissionConflictError(
+					'Subscription permission changed; reload before updating.',
+				)
+			const { expectedRevision, ...values } = captured
+			const record = this.checked(
+				{ ...values, v: 1, revision: expectedRevision + 1 },
+				values.subscriptionId,
+			)
+			return { record, result: record }
+		})
+	}
+	async authorizeSubscription(
+		request: PalActivitySubscriptionAuthorizationRequest,
+	): Promise<PalMessageAuthorization> {
+		const phase = z.enum(['observe', 'disclose', 'receive', 'accept']).parse(request.phase)
+		const permitted = (rule: PalActivitySubscriptionPermission | null) =>
+			phase === 'accept' ? rule?.observe && rule.disclose && rule.receive : rule?.[phase]
+		const captured = freezeCommunicationValue(subscriptionSchema.parse(request.subscription))
+		const stored = await this.subscriptions.get(captured.id)
+		const subscription = stored ? freezeCommunicationValue(subscriptionSchema.parse(stored)) : null
+		if (
+			!subscription?.enabled ||
+			subscription.configurationRevision !== captured.configurationRevision ||
+			!isDeepStrictEqual(subscription.scope, captured.scope) ||
+			!isDeepStrictEqual(subscription.recipient, captured.recipient)
+		)
+			return denied()
+		const observed = await this.get(subscription.id)
+		if (!permitted(observed)) return denied()
+		const current = await this.subscriptions.get(subscription.id)
+		if (
+			!current?.enabled ||
+			current.configurationRevision !== captured.configurationRevision ||
+			!isDeepStrictEqual(current.scope, captured.scope) ||
+			!isDeepStrictEqual(current.recipient, captured.recipient)
+		)
+			return denied()
+		const rule = await this.get(subscription.id)
+		if (!rule || !permitted(rule)) return denied()
+		return {
+			allow: true,
+			grant: {
+				id: `pal-subscription:${subscription.id}:${phase}`,
+				revision: String(rule.revision),
+			},
+		}
+	}
+	async authorizeIngress(input: PalIngressAuthorizationRequest): Promise<PalMessageAuthorization> {
+		if (!('kind' in input) || input.kind !== 'observation') return denied()
+		const request = freezeCommunicationValue(
+			z
+				.object({
+					kind: z.literal('observation'),
+					phase: z.enum(['accept', 'deliver', 'wake']),
+					source: observationSourceSchema,
+					routeKey: observationRouteKeySchema,
+					recipient: addressSchema,
+				})
+				.parse(input),
+		)
+		const id = z.string().uuid().parse(request.source.subscriptionId)
+		const phase = z.enum(['accept', 'deliver', 'wake']).parse(request.phase)
+		const stored = await this.subscriptions.get(id)
+		const subscription = stored ? freezeCommunicationValue(subscriptionSchema.parse(stored)) : null
+		if (
+			!subscription?.enabled ||
+			request.routeKey.kind !== 'observation' ||
+			request.routeKey.subscriptionId !== id ||
+			!isDeepStrictEqual(request.source.scope, subscription.scope) ||
+			!isDeepStrictEqual(request.routeKey.scope, subscription.scope) ||
+			!isDeepStrictEqual(request.recipient, subscription.recipient) ||
+			!isDeepStrictEqual(request.routeKey.recipient, subscription.recipient)
+		)
+			return denied()
+		const observed = await this.get(id)
+		if (
+			!observed?.observe ||
+			!observed.disclose ||
+			!observed.receive ||
+			(phase === 'wake' && !observed.wake)
+		)
+			return denied()
+		const current = await this.subscriptions.get(id)
+		if (
+			!current?.enabled ||
+			current.configurationRevision !== subscription.configurationRevision ||
+			!isDeepStrictEqual(current.scope, subscription.scope) ||
+			!isDeepStrictEqual(current.recipient, subscription.recipient)
+		)
+			return denied()
+		const rule = await this.get(id)
+		if (!rule?.observe || !rule.disclose || !rule.receive || (phase === 'wake' && !rule.wake))
+			return denied()
+		return {
+			allow: true,
+			grant: {
+				id: `pal-subscription:${id}:${phase}`,
+				revision: String(rule.revision),
+			},
+		}
+	}
+}

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

@@ -0,0 +1,27 @@
+import { z } from 'zod'
+import { activityCursorSchema, activityScopeSchema } from '../communication/ingress-schema.js'
+import { addressSchema } from '../communication/schema.js'
+
+const positive = z.number().int().positive().safe()
+export const subscriptionScopeSchema = activityScopeSchema
+export const subscriptionCursorSchema = activityCursorSchema
+const subscriptionObjectSchema = z
+	.object({
+		v: z.literal(1),
+		id: z.string().uuid(),
+		revision: positive,
+		configurationRevision: positive,
+		scope: subscriptionScopeSchema,
+		recipient: addressSchema,
+		enabled: z.boolean(),
+		cursor: subscriptionCursorSchema.nullable(),
+	})
+	.strict()
+export const subscriptionSchema = subscriptionObjectSchema.refine(
+	(v) => v.scope.tenantId === v.recipient.tenantId,
+	'Cross-tenant observation is refused.',
+)
+export const storedSubscriptionSchema = subscriptionObjectSchema
+	.extend({ schemaVersion: z.literal(1).optional() })
+	.transform(({ schemaVersion: _schemaVersion, ...value }) => value)
+	.pipe(subscriptionSchema)

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

@@ -0,0 +1,172 @@
+import { chmodSync, lstatSync, mkdirSync, readdirSync, realpathSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import { z } from 'zod'
+import { DiskRevisionRecordStore } from '../../store/kv/revision-record-store.js'
+import { defineSchema } from '../../store/schema.js'
+import { freezeCommunicationValue } from '../communication/schema.js'
+import {
+	storedSubscriptionSchema,
+	subscriptionCursorSchema,
+	subscriptionSchema,
+} from './subscription-schema.js'
+import type { PalActivitySubscription, PalActivitySubscriptionStore } from './subscription-types.js'
+import type { PalActivityCursor } from './types.js'
+
+export class PalActivitySubscriptionConflictError extends Error {
+	override readonly name = 'PalActivitySubscriptionConflictError'
+}
+
+/** Private immutable revision commits. No cursors are accepted from a client or model. */
+export class DiskPalActivitySubscriptionStore implements PalActivitySubscriptionStore {
+	private readonly root: string
+	private readonly secure: (path: string) => void
+	private readonly records = new DiskRevisionRecordStore<PalActivitySubscription>(
+		defineSchema({
+			kind: 'pal-activity-subscription',
+			current: 1,
+			migrations: {},
+		}),
+		'Pal activity subscription',
+		(value) => value.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 stat = lstatSync(path)
+		if (!stat.isDirectory() || stat.isSymbolicLink() || realpathSync(path) !== path)
+			throw new Error('Pal subscriptions require real directories without aliases.')
+		this.secure(path)
+	}
+	private location(input: string) {
+		const id = z.string().uuid().parse(input)
+		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 stat = lstatSync(join(revisionsDir, name))
+			if (!stat.isFile() || stat.isSymbolicLink())
+				throw new Error('Pal subscription commits must be real files.')
+		}
+		return {
+			legacyPath: join(directory, 'subscription.json'),
+			revisionsDir,
+			publishLegacyProjection: false,
+		}
+	}
+	private checked(input: unknown, id: string): PalActivitySubscription {
+		const value = storedSubscriptionSchema.parse(input)
+		if (value.id !== id || value.configurationRevision > value.revision)
+			throw new Error('Foreign or invalid Pal activity subscription.')
+		return freezeCommunicationValue(value)
+	}
+	async get(id: string): Promise<PalActivitySubscription | null> {
+		const value = await this.records.read(this.location(id))
+		return value === null ? null : this.checked(value, id)
+	}
+	/** Complete current records for trusted host projection; a bad record rejects the whole list. */
+	async list(): Promise<readonly PalActivitySubscription[]> {
+		try {
+			const entry = lstatSync(this.root)
+			if (!entry.isDirectory() || entry.isSymbolicLink() || realpathSync(this.root) !== this.root)
+				throw new Error('Pal subscriptions require real directories without aliases.')
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') return Object.freeze([])
+			throw error
+		}
+		const subscriptions: PalActivitySubscription[] = []
+		for (const name of readdirSync(this.root).sort()) {
+			if (!z.string().uuid().safeParse(name).success) continue
+			const value = await this.get(name)
+			if (value) subscriptions.push(value)
+		}
+		return Object.freeze(subscriptions)
+	}
+	async create(input: Parameters<PalActivitySubscriptionStore['create']>[0]) {
+		const value = subscriptionSchema.parse({
+			...input,
+			v: 1,
+			revision: 1,
+			configurationRevision: 1,
+			cursor: null,
+		})
+		const proposed = this.checked(value, value.id)
+		return this.records.transact(this.location(proposed.id), (stored) => {
+			if (stored !== null)
+				throw new PalActivitySubscriptionConflictError('Subscription identity already exists.')
+			return { record: proposed, result: proposed }
+		})
+	}
+	async setEnabled(input: Parameters<PalActivitySubscriptionStore['setEnabled']>[0]) {
+		const captured = z
+			.object({
+				id: z.string().uuid(),
+				expectedRevision: z.number().int().positive().safe(),
+				enabled: z.boolean(),
+			})
+			.strict()
+			.parse(input)
+		return this.records.transact(this.location(captured.id), (stored) => {
+			const current = stored === null ? null : this.checked(stored, captured.id)
+			if (!current || current.revision !== captured.expectedRevision)
+				throw new PalActivitySubscriptionConflictError(
+					'Subscription changed; reload before changing consent.',
+				)
+			const record = this.checked(
+				{
+					...current,
+					enabled: captured.enabled,
+					revision: current.revision + 1,
+					configurationRevision: current.configurationRevision + 1,
+				},
+				current.id,
+			)
+			return { record, result: record }
+		})
+	}
+	async advance(input: PalActivitySubscription, inputCursor: PalActivityCursor) {
+		const parsed = subscriptionSchema.parse(input)
+		const captured = this.checked(parsed, parsed.id)
+		const cursor = freezeCommunicationValue(subscriptionCursorSchema.parse(inputCursor))
+		if (cursor.after.seq < cursor.root.seq || cursor.after.offset < cursor.root.offset)
+			throw new Error('Subscription cursor cannot precede its root.')
+		if (captured.cursor) {
+			const previous = captured.cursor
+			if (
+				cursor.scopeHash !== previous.scopeHash ||
+				!isDeepStrictEqual(cursor.root, previous.root) ||
+				cursor.after.seq < previous.after.seq ||
+				cursor.after.offset < previous.after.offset ||
+				cursor.generation < previous.generation ||
+				(cursor.after.seq === previous.after.seq && !isDeepStrictEqual(cursor, previous))
+			)
+				throw new Error('Subscription cursor identity changed or moved backwards.')
+		}
+		return this.records.transact(this.location(captured.id), (stored) => {
+			const current = stored === null ? null : this.checked(stored, captured.id)
+			if (!current || !current.enabled || !isDeepStrictEqual(current, captured))
+				throw new PalActivitySubscriptionConflictError(
+					'Subscription changed before accepted progress could commit.',
+				)
+			const record = this.checked(
+				{ ...current, revision: current.revision + 1, cursor },
+				current.id,
+			)
+			return { record, result: record }
+		})
+	}
+}