@namzu/sdk 48.3.1 → 50.0.0

package/src/types/errors/catalog.ts

@@ -144,8 +144,10 @@ export const DEFAULT_ERROR_RULES: readonly ErrorCatalogRule[] = [
 		// separates them when the provider sent it.
 		id: 'provider.permission',
 		when: (facts) => facts.status === 403,
-		message: 'The credentials are valid but not permitted to use this model.',
-		hint: 'The key authenticated, so this is an entitlement rather than a secret problem: check the model name and whether the account has access to it.',
+		// A 403 says the request was refused, not that a key was accepted: some providers answer
+		// a request that carried no key at all (a keyless free tier) with the same status.
+		message: 'The provider refused this request.',
+		hint: 'Check the model name and whether the account behind your key has access to it. If no key was sent, add one or choose another provider.',
 	},
 	{
 		id: 'provider.auth',

package/src/types/harness/schema.ts

@@ -0,0 +1,203 @@
+import { z } from 'zod'
+import { isEntityId } from '../../utils/id.js'
+import type { MessageId, TurnId } from '../ids/index.js'
+import type { HarnessEvent, HarnessJson } from './session.js'
+
+const opaque = z
+	.string()
+	.min(1)
+	.max(4096)
+	.refine((v) => !Array.from(v).some((c) => c.charCodeAt(0) < 32))
+const text = z.string().max(1024 * 1024)
+const digest = z.string().regex(/^[a-f0-9]{64}$/)
+const turnId = z.custom<TurnId>((v) => isEntityId(v, 'turn'))
+const messageId = z.custom<MessageId>((v) => isEntityId(v, 'message'))
+
+function validJson(value: unknown, depth = 0, budget = { nodes: 0 }): boolean {
+	if (depth > 32 || ++budget.nodes > 50000) return false
+	if (value === null || typeof value === 'boolean') return true
+	if (typeof value === 'number') return Number.isFinite(value)
+	if (typeof value === 'string') return value.length <= 1024 * 1024
+	if (Array.isArray(value)) return value.every((v) => validJson(v, depth + 1, budget))
+	if (typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) return false
+	return Object.entries(value).every(
+		([k, v]) => k.length <= 4096 && validJson(v, depth + 1, budget),
+	)
+}
+const json = z
+	.custom<HarnessJson>((v) => validJson(v))
+	.refine((v) => JSON.stringify(v).length <= 1024 * 1024)
+
+export const HarnessBindingSchema = z
+	.object({
+		v: z.literal(1),
+		engineId: opaque,
+		profileRef: opaque,
+		nativeSessionId: opaque,
+		cwd: opaque,
+		initialModel: opaque,
+	})
+	.strict()
+const nativeTurn = {
+	nativeSessionId: opaque,
+	nativeTurnId: opaque,
+	turnIdSource: z.enum(['engine', 'operation']).optional(),
+}
+const nativeItem = { ...nativeTurn, nativeItemId: opaque }
+export const HarnessNativeTurnSchema = z.object(nativeTurn).strict()
+export const HarnessReviewRequestSchema = z
+	.object({
+		...nativeTurn,
+		requestId: opaque,
+		nativeItemId: opaque.optional(),
+		kind: z.enum(['command', 'file-change', 'tool']),
+		title: opaque,
+		input: json,
+		decisions: z
+			.array(z.enum(['approve-once', 'reject', 'cancel']))
+			.min(1)
+			.max(3),
+	})
+	.strict()
+export const HarnessDecisionSchema = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('approve-once'), updatedInput: json.optional() }).strict(),
+	z.object({ kind: z.literal('reject'), feedback: text.optional() }).strict(),
+	z.object({ kind: z.literal('cancel') }).strict(),
+])
+const part = z
+	.object({ id: opaque, text, phase: z.enum(['commentary', 'final_answer']).optional() })
+	.strict()
+export const HarnessEventSchema: z.ZodType<HarnessEvent> = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('turn-started'), ...nativeTurn, model: opaque.optional() }).strict(),
+	z.object({ kind: z.literal('message-started'), ...nativeItem }).strict(),
+	z
+		.object({
+			kind: z.literal('text-delta'),
+			...nativeItem,
+			text,
+			part: part.omit({ text: true }).optional(),
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('message-completed'),
+			...nativeItem,
+			content: text,
+			parts: z.array(part).max(10000).optional(),
+			stopReason: z.enum([
+				'end_turn',
+				'tool_use',
+				'max_tokens',
+				'stop_sequence',
+				'pause_turn',
+				'refusal',
+				'forced_finalize',
+				'cancelled',
+			]),
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('reasoning'),
+			...nativeItem,
+			blockId: opaque,
+			status: z.enum(['pending', 'completed']),
+			text: text.optional(),
+		})
+		.strict(),
+	z.object({ kind: z.literal('tool-started'), ...nativeItem, name: opaque, input: json }).strict(),
+	z.object({ kind: z.literal('tool-output'), ...nativeItem, text }).strict(),
+	z
+		.object({
+			kind: z.literal('tool-completed'),
+			...nativeItem,
+			name: opaque,
+			result: text,
+			status: z.enum(['completed', 'failed', 'declined', 'cancelled']),
+			durationMs: z.number().int().nonnegative().safe().optional(),
+		})
+		.strict(),
+	z.object({ kind: z.literal('review-requested'), request: HarnessReviewRequestSchema }).strict(),
+	z.object({ kind: z.literal('review-resolved'), ...nativeTurn, requestId: opaque }).strict(),
+	z
+		.object({
+			kind: z.literal('turn-completed'),
+			...nativeTurn,
+			status: z.enum(['completed', 'failed', 'cancelled']),
+			finalItemId: opaque.optional(),
+			result: text.optional(),
+			error: z.object({ code: opaque, message: text }).strict().optional(),
+		})
+		.strict(),
+	z
+		.object({ kind: z.literal('connection-lost'), code: opaque, mayBeRunning: z.boolean() })
+		.strict(),
+])
+
+export const HarnessJournalTransitionSchema = z.discriminatedUnion('kind', [
+	z
+		.object({
+			kind: z.literal('dispatch-prepared'),
+			model: opaque.optional(),
+			effort: z
+				.enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'])
+				.optional(),
+			permissionMode: z.enum(['prompt', 'auto', 'accept-edits', 'plan', 'strict']).optional(),
+			operationId: opaque,
+			turnId,
+			promptId: messageId,
+			digest,
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('dispatch-accepted'),
+			operationId: opaque,
+			turnId,
+			nativeTurn: HarnessNativeTurnSchema,
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('item-bound'),
+			turnId,
+			nativeItem: z.object(nativeItem).strict(),
+			messageId: messageId.optional(),
+			toolUseId: opaque.optional(),
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('review-requested'),
+			turnId,
+			request: HarnessReviewRequestSchema,
+			digest,
+		})
+		.strict(),
+	z
+		.object({
+			kind: z.literal('review-decided'),
+			turnId,
+			requestId: opaque,
+			requestDigest: digest,
+			decisionDigest: digest,
+			decision: HarnessDecisionSchema,
+		})
+		.strict(),
+	z.object({ kind: z.literal('review-resolved'), turnId, requestId: opaque }).strict(),
+	z
+		.object({ kind: z.literal('connection-lost'), turnId: turnId.optional(), code: opaque })
+		.strict(),
+])
+
+/** Clone at ingress, before any host callback can suspend, and freeze every nested value. */
+export function harnessSnapshot<T>(value: T): T {
+	const copy = structuredClone(value)
+	const freeze = (v: unknown): void => {
+		if (!v || typeof v !== 'object') return
+		for (const entry of Object.values(v)) freeze(entry)
+		Object.freeze(v)
+	}
+	freeze(copy)
+	return copy
+}

package/src/types/harness/session.ts

@@ -0,0 +1,306 @@
+import type { ReviewMode } from '../../runtime/query/review-policy.js'
+import type { SessionLog } from '../../store/session-log/index.js'
+/**
+ * A session whose execution and tools belong to a host-composed external harness.
+ * SDK code contains no vendor import, process runner or credential discovery.
+ * Existing Namzu query/LLMProvider/tool execution is unchanged.
+ */
+import type {
+	MessageId,
+	ProjectId,
+	SessionId,
+	TenantId,
+	ToolUseId,
+	TopicId,
+	TurnId,
+} from '../ids/index.js'
+import type { Message } from '../message/index.js'
+import type { ReasoningEffort } from '../provider/index.js'
+import type { SessionEvent } from '../session/events.js'
+
+export type HarnessJson =
+	| null
+	| boolean
+	| number
+	| string
+	| readonly HarnessJson[]
+	| { readonly [key: string]: HarnessJson }
+
+/** Native IDs remain opaque strings and are NEVER parsed as Namzu UUIDs. */
+export interface HarnessBinding {
+	readonly v: 1
+	readonly engineId: string
+	/** Host-owned opaque identity for executable/state-home/account selection; no credentials. */
+	readonly profileRef: string
+	/** Exact native conversation/thread identifier, not a shared root or Namzu session ID. */
+	readonly nativeSessionId: string
+	/** Canonical absolute native execution directory, confirmed by the adapter. */
+	readonly cwd: string
+	/** Verified initial selection; later changes are captured per turn, never engine changes. */
+	readonly initialModel: string
+}
+
+export interface HarnessScope {
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+	readonly projectId: ProjectId
+	readonly topicId: TopicId
+	readonly cwd: string
+}
+
+/** Values established from the installed engine/protocol, never copied from Namzu providers. */
+export interface HarnessCapabilities {
+	readonly persistentSessions: boolean
+	readonly history: 'snapshot' | 'unavailable'
+	readonly models: 'discover' | 'configured' | 'unavailable'
+	readonly permissions: 'interactive' | 'deny-only' | 'unavailable'
+	readonly interrupt: 'native-terminal' | 'process-stop' | 'unavailable'
+	readonly attachments: readonly ('image' | 'file')[]
+	readonly effortLevels?: readonly ReasoningEffort[]
+	/** Common UI may offer only modes actually mapped by this engine. */
+	readonly reviewModes: readonly ReviewMode[]
+}
+
+export interface HarnessModel {
+	readonly id: string
+	readonly label: string
+	readonly effortLevels?: readonly ReasoningEffort[]
+	readonly defaultEffort?: ReasoningEffort
+}
+
+export interface HarnessNativeTurn {
+	readonly nativeSessionId: string
+	readonly nativeTurnId: string
+	/** Explicit operation correlation when the engine exposes no native turn ID. */
+	readonly turnIdSource?: 'engine' | 'operation'
+}
+
+export interface HarnessNativeItem extends HarnessNativeTurn {
+	readonly nativeItemId: string
+}
+
+export interface HarnessPublicTextPart {
+	readonly id: string
+	readonly text: string
+	readonly phase?: 'commentary' | 'final_answer'
+}
+
+export type HarnessDecision =
+	| { readonly kind: 'approve-once'; readonly updatedInput?: HarnessJson }
+	| { readonly kind: 'reject'; readonly feedback?: string }
+	| { readonly kind: 'cancel' }
+
+export interface HarnessReviewRequest extends HarnessNativeTurn {
+	readonly requestId: string
+	readonly nativeItemId?: string
+	readonly kind: 'command' | 'file-change' | 'tool'
+	readonly title: string
+	/** Public proposed operation only. No raw RPC frame, credentials or private thinking. */
+	readonly input: HarnessJson
+	readonly decisions: readonly HarnessDecision['kind'][]
+}
+
+/** A NEW, namespaced port union. No new existing SessionEvent discriminants. */
+export type HarnessEvent =
+	| (HarnessNativeTurn & { readonly kind: 'turn-started'; readonly model?: string })
+	| (HarnessNativeItem & { readonly kind: 'message-started' })
+	| (HarnessNativeItem & {
+			readonly kind: 'text-delta'
+			readonly text: string
+			readonly part?: Pick<HarnessPublicTextPart, 'id' | 'phase'>
+	  })
+	| (HarnessNativeItem & {
+			readonly kind: 'message-completed'
+			readonly content: string
+			readonly parts?: readonly HarnessPublicTextPart[]
+			readonly stopReason: import('../session/stop-reason.js').MessageStopReason
+	  })
+	| (HarnessNativeItem & {
+			readonly kind: 'reasoning'
+			readonly blockId: string
+			readonly status: 'pending' | 'completed'
+			/** Only engine-documented public summary/thinking; never replay/signature material. */
+			readonly text?: string
+	  })
+	| (HarnessNativeItem & {
+			readonly kind: 'tool-started'
+			readonly name: string
+			readonly input: HarnessJson
+	  })
+	| (HarnessNativeItem & { readonly kind: 'tool-output'; readonly text: string })
+	| (HarnessNativeItem & {
+			readonly kind: 'tool-completed'
+			readonly name: string
+			readonly result: string
+			readonly status: 'completed' | 'failed' | 'declined' | 'cancelled'
+			readonly durationMs?: number
+	  })
+	| { readonly kind: 'review-requested'; readonly request: HarnessReviewRequest }
+	| (HarnessNativeTurn & { readonly kind: 'review-resolved'; readonly requestId: string })
+	| (HarnessNativeTurn & {
+			readonly kind: 'turn-completed'
+			readonly status: 'completed' | 'failed' | 'cancelled'
+			readonly finalItemId?: string
+			readonly result?: string
+			readonly error?: { readonly code: string; readonly message: string }
+	  })
+	| {
+			readonly kind: 'connection-lost'
+			readonly code: string
+			/** True never implies that native work stopped. */
+			readonly mayBeRunning: boolean
+	  }
+
+/** Resolve after validation/persistence/publication, never await a human answer here. */
+export type HarnessEventSink = (event: HarnessEvent) => Promise<void>
+
+export interface HarnessPrompt {
+	/** Actual host operation identity for this admitted prompt, persisted before send. */
+	readonly operationId: string
+	readonly prompt: string
+	readonly model: string
+	readonly effort?: ReasoningEffort
+	readonly permissionMode: ReviewMode
+	readonly signal?: AbortSignal
+}
+
+export interface HarnessHistorySnapshot {
+	readonly binding: HarnessBinding
+	readonly activeTurn?: HarnessNativeTurn
+	/** Authoritative lifecycle/items, not byte-for-byte replay of ephemeral deltas. */
+	readonly events: readonly Exclude<
+		HarnessEvent,
+		{ readonly kind: 'text-delta' | 'tool-output' | 'connection-lost' }
+	>[]
+	readonly pendingReviews: readonly HarnessReviewRequest[]
+	readonly complete: boolean
+}
+
+export interface HarnessConnection {
+	readonly binding: HarnessBinding
+	readonly capabilities: HarnessCapabilities
+	models(signal?: AbortSignal): Promise<readonly HarnessModel[]>
+	/** ACK may follow terminal event. It must not resurrect a finished turn. */
+	dispatch(input: HarnessPrompt): Promise<HarnessNativeTurn>
+	/** Receipt means requested only; SDK waits for correlated terminal/confirmed owned stop. */
+	interrupt(turn: HarnessNativeTurn): Promise<{ readonly requested: true }>
+	/** Validate exact current native request, then send one of that request's decisions. */
+	respond(
+		request: HarnessReviewRequest,
+		decision: HarnessDecision,
+	): Promise<{ readonly sent: true }>
+	/** Never resends a prompt. Absence/incomplete history leaves explicit reconciliation required. */
+	readHistory(signal?: AbortSignal): Promise<HarnessHistorySnapshot>
+	/** Success confirms own process/children stopped; rejection retains handle for retry. */
+	close(): Promise<{ readonly stopped: true }>
+}
+
+export interface HarnessAdapter {
+	readonly engineId: string
+	readonly profileRef: string
+	/** Subscribe BEFORE spawn/initialize/open/resume so early items/requests cannot be lost. */
+	open(
+		input: {
+			readonly cwd: string
+			readonly model?: string
+			readonly resume?: HarnessBinding
+			readonly signal?: AbortSignal
+		},
+		onEvent: HarnessEventSink,
+	): Promise<HarnessConnection>
+}
+
+export interface HarnessAdmissionRequest {
+	readonly kind: 'open' | 'run' | 'approval' | 'reconnect'
+	readonly scope: HarnessScope
+	readonly binding?: HarnessBinding
+	readonly nativeTurn?: HarnessNativeTurn
+	readonly review?: HarnessReviewRequest
+}
+
+export interface HarnessSessionOptions {
+	readonly scope: HarnessScope
+	readonly sessionLog: SessionLog
+	readonly adapter: HarnessAdapter
+	/** REQUIRED current trusted host boundary: canonical cwd/trust/user ownership, ordinary only. */
+	readonly assertAdmission: (
+		request: HarnessAdmissionRequest,
+		signal?: AbortSignal,
+	) => Promise<void>
+	readonly onEvent: (event: SessionEvent) => void | Promise<void>
+	readonly onReview: (request: HarnessReviewRequest) => void | Promise<void>
+}
+
+export interface HarnessTurnOutcome {
+	readonly turnId: TurnId
+	readonly nativeTurn: HarnessNativeTurn
+	readonly status: 'completed' | 'failed' | 'cancelled'
+	readonly messages: readonly Message[]
+}
+
+export interface HarnessSession {
+	readonly scope: HarnessScope
+	readonly binding: HarnessBinding | undefined
+	/** Exact admitted turn pointer for host cancellation; never a model-supplied ID. */
+	readonly currentTurnId: TurnId | undefined
+	readonly status:
+		| 'disconnected'
+		| 'idle'
+		| 'running'
+		| 'waiting'
+		| 'reconciliation-required'
+		| 'closed'
+	/** Public durable text only; no native process startup. */
+	history(): Promise<readonly Message[]>
+	/** Reject concurrent turn operations. CLI/desktop owns its visible queue. */
+	run(input: Omit<HarnessPrompt, 'operationId'>): Promise<HarnessTurnOutcome>
+	/** Exact expected turn pointer prevents a stale Stop from cancelling the next turn. */
+	cancel(expectedTurnId: TurnId): Promise<{ readonly stopped: true; readonly turnId: TurnId }>
+	/** SDK adds current writer generation/request digest internally; renderer cannot supply authority. */
+	respond(request: HarnessReviewRequest, decision: HarnessDecision): Promise<void>
+	reconnect(signal?: AbortSignal): Promise<void>
+	close(): Promise<void>
+}
+
+/** Typed journal receipts stored in the existing session_updated record. */
+export type HarnessJournalTransition =
+	| {
+			readonly kind: 'dispatch-prepared'
+			/** Actual admitted selection; engine binding remains immutable. */
+			readonly model?: string
+			readonly effort?: ReasoningEffort
+			readonly permissionMode?: ReviewMode
+			readonly operationId: string
+			readonly turnId: TurnId
+			readonly promptId: MessageId
+			readonly digest: string
+	  }
+	| {
+			readonly kind: 'dispatch-accepted'
+			readonly operationId: string
+			readonly turnId: TurnId
+			readonly nativeTurn: HarnessNativeTurn
+	  }
+	| {
+			readonly kind: 'item-bound'
+			readonly turnId: TurnId
+			readonly nativeItem: HarnessNativeItem
+			readonly messageId?: MessageId
+			readonly toolUseId?: ToolUseId
+	  }
+	| {
+			readonly kind: 'review-requested'
+			readonly turnId: TurnId
+			readonly request: HarnessReviewRequest
+			readonly digest: string
+	  }
+	| {
+			readonly kind: 'review-decided'
+			readonly turnId: TurnId
+			readonly requestId: string
+			readonly requestDigest: string
+			readonly decisionDigest: string
+			readonly decision: HarnessDecision
+	  }
+	| { readonly kind: 'review-resolved'; readonly turnId: TurnId; readonly requestId: string }
+	| { readonly kind: 'connection-lost'; readonly turnId?: TurnId; readonly code: string }

package/src/types/hitl/index.ts

@@ -3,6 +3,12 @@ import type { CheckpointId, PlanId, SessionId, TurnId } from '../ids/index.js'
 
 export type { CheckpointId }
 
+/** A person's No to a tool call. See the `declined` field of `reject_tools`. */
+export interface ToolCallDeclined {
+	/** What the person said about it, in their own words. */
+	readonly note?: string
+}
+
 export type HITLResumeDecision =
 	| { action: 'continue' }
 	| { action: 'approve_plan'; feedback?: string }
@@ -56,7 +62,17 @@ export type HITLResumeDecision =
 			/** See the `approve_tools` field of the same name. */
 			confirmedEscalations?: readonly string[]
 	  }
-	| { action: 'reject_tools'; feedback: string }
+	| {
+			action: 'reject_tools'
+			feedback: string
+			/**
+			 * Present only when a person answered No. `feedback` is what the
+			 * MODEL is told and a policy refusal fills it too, so it cannot say
+			 * who refused; this does. `note` is the person's own words, apart
+			 * from any wrapper a host put around them in `feedback`.
+			 */
+			declined?: ToolCallDeclined
+	  }
 	| {
 			action: 'answer_question'
 			selectedOptionIds: string[]

package/src/types/job/index.ts

@@ -0,0 +1,42 @@
+/** A literal condition on one existing background job's output. */
+export interface BackgroundJobOutputWaitOptions {
+	/** Non-empty UTF-8 literal, at most 4096 bytes. Never a regular expression. */
+	readonly literal: string
+	/** Match each pipe independently; `either` never joins stdout to stderr. */
+	readonly stream?: 'stdout' | 'stderr' | 'either'
+	/** Combined output byte cursor, as returned by `read` or an earlier wait. */
+	readonly fromOffset?: number
+	/** Required wall bound, from 1 millisecond through one hour. */
+	readonly timeoutMs: number
+	/** Optional silence bound, reset by output from either pipe. */
+	readonly idleTimeoutMs?: number
+	/** Cancels this observation, without stopping the process. */
+	readonly signal?: AbortSignal
+}
+
+/** Evidence and cursor common to every readiness wait outcome. */
+export interface BackgroundJobOutputWaitProgress {
+	readonly status: string
+	readonly exitCode?: number
+	/** Why the command never started, when it could not. */
+	readonly error?: string
+	/** Mixed stdout/stderr tail, at most 32 KiB. Treat process output as untrusted. */
+	readonly output: string
+	readonly nextOffset: number
+	/** Bytes unavailable because the job's normal output cap discarded them. */
+	readonly droppedBytes: number
+	/** Available output excluded from matching by the bounded channel history. */
+	readonly unsearchedBytes: number
+	/** Earlier observed bytes omitted from the bounded result text. */
+	readonly omittedOutputBytes: number
+}
+
+/** A matched marker proves its appearance, not process completion or service health. */
+export type BackgroundJobOutputWaitResult = BackgroundJobOutputWaitProgress &
+	(
+		| { readonly kind: 'matched'; readonly matchedStream: 'stdout' | 'stderr' }
+		| { readonly kind: 'exited' }
+		| { readonly kind: 'stopped' }
+		| { readonly kind: 'timeout'; readonly cause: 'wall' | 'idle'; readonly elapsedMs: number }
+		| { readonly kind: 'aborted' }
+	)

package/src/types/memory/index.ts

@@ -80,6 +80,11 @@ export interface MemoryRecord {
 	readonly content: MemoryContent
 }
 
+/** A full record and an opaque token for that exact logical snapshot. */
+export interface VersionedMemoryRecord extends MemoryRecord {
+	readonly revision: string
+}
+
 export interface MemorySearchParams {
 	readonly query?: string
 	readonly tags?: string[]
@@ -87,11 +92,22 @@ export interface MemorySearchParams {
 	readonly limit?: number
 	/** Match at least one exact normalized word token before limiting results. Empty means no constraint. */
 	readonly requiredIdentifiers?: readonly string[]
+	/** Maximum indexed candidates to examine in one page; omitted scans all. */
+	readonly maxScanned?: number
+	/** Skip this many candidates in newest-first scan order; a new search starts at zero. */
+	readonly scanOffset?: number
 }
 
 export interface MemorySearchResult {
 	readonly entries: readonly MemoryIndexEntry[]
+	/** Exact unless truncated is true; then counts matches in the scanned candidates only. */
 	readonly totalCount: number
+	/** True when the search stopped before examining all eligible candidates. */
+	readonly truncated?: boolean
+	/** Number of eligible candidates examined in this page. */
+	readonly scannedCount?: number
+	/** Pass as scanOffset to inspect the next page; absent when this scan reached the end. */
+	readonly nextScanOffset?: number
 }
 
 export interface CreateMemoryParams {
@@ -128,6 +144,33 @@ export interface MemoryStore {
 	list(params?: MemorySearchParams): Promise<MemorySearchResult>
 }
 
+/**
+ * Opt-in compare-and-set operations. A supplied revision is checked together
+ * with the mutation, under the store's own coordination boundary. Implementing
+ * only one of these methods is not enough to advertise conditional writes.
+ */
+export interface ConditionalMemoryStore extends MemoryStore {
+	/** The record and a token covering its complete logical snapshot. */
+	getVersionedRecord(id: MemoryId): Promise<VersionedMemoryRecord | undefined>
+	/** Throw MemoryRevisionConflictError if the record changed or disappeared. */
+	updateIfRevision(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision: string,
+	): Promise<MemoryIndexEntry>
+	/** Throw MemoryRevisionConflictError if the record changed or disappeared. */
+	deleteIfRevision(id: MemoryId, expectedRevision: string): Promise<void>
+}
+
+export function hasConditionalMemoryWrites(store: MemoryStore): store is ConditionalMemoryStore {
+	const candidate = store as Partial<ConditionalMemoryStore>
+	return (
+		typeof candidate.getVersionedRecord === 'function' &&
+		typeof candidate.updateIfRevision === 'function' &&
+		typeof candidate.deleteIfRevision === 'function'
+	)
+}
+
 export interface MemoryIndex {
 	search(params: MemorySearchParams): MemorySearchResult
 	getEntry(id: MemoryId): MemoryIndexEntry | undefined