@namzu/sdk 55.0.0 → 56.0.0

package/src/manager/resident/store.ts

@@ -28,7 +28,11 @@ export const residentDecisionSchema = z.discriminatedUnion('kind', [
 	z.object({ kind: z.literal('blocked'), summary: text }),
 ])
 
-/** @experimental One bounded step's durable disposition; silence is not completion. */
+/**
+ * @experimental One bounded step's durable disposition; silence is not completion.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentDecision = z.infer<typeof residentDecisionSchema>
 
 export const residentStateSchema = z
@@ -69,7 +73,11 @@ export const residentStateSchema = z
 		}
 	})
 
-/** @experimental Persisted identity and one pursuit, independent of a conversation. */
+/**
+ * @experimental Persisted identity and one pursuit, independent of a conversation.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentState = Readonly<z.infer<typeof residentStateSchema>>
 
 /** Bounded addressing for local resident state. Stored scope is still validated. */
@@ -80,10 +88,18 @@ export function residentKeySegment(key: string): string {
 		: `~sha256-${createHash('sha256').update(encoded).digest('hex')}`
 }
 
-/** @experimental Minimal atomic contract needed to execute an existing pursuit. */
+/**
+ * @experimental Minimal atomic contract needed to execute an existing pursuit.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentExecutionStore = Pick<ResidentStore, 'read' | 'claim' | 'settle'>
 
-/** @experimental Backends must atomically compare revisions and publish admission before work. */
+/**
+ * @experimental Backends must atomically compare revisions and publish admission before work.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentStore {
 	read(): Promise<ResidentState | null>
 	create(identity: string, objective: string): Promise<ResidentState>
@@ -92,7 +108,11 @@ export interface ResidentStore {
 	wake(expected: ResidentState, reason: string, now: number): Promise<ResidentState>
 }
 
-/** A competing owner advanced this resident's immutable revision. */
+/**
+ * A competing owner advanced this resident's immutable revision.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export class ResidentConflictError extends Error {
 	constructor() {
 		super('Resident state changed; read the current state before retrying.')
@@ -104,6 +124,8 @@ export class ResidentConflictError extends Error {
  * @experimental Local-filesystem state for one tenant/agent key and one pursuit.
  * A running claim never expires automatically: a crashed step may have effects.
  * Uses exclusive immutable revision publication, not a read/rename lock.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export class DiskResidentStore implements ResidentStore {
 	private readonly records = new DiskRevisionRecordStore<ResidentState>(

package/src/manager/resident/tool-evidence.ts

@@ -17,16 +17,28 @@ import type {
 	ResidentHistorySource,
 } from './history.js'
 
-/** @experimental Host authority for one pursuit, project and admission boundary. */
+/**
+ * @experimental Host authority for one pursuit, project and admission boundary.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentToolEvidenceScope extends ResidentHistoryScope {
 	readonly projectId: string
 }
-/** @experimental Identity of an agenda-verified settlement, not a fabricated transcript. */
+/**
+ * @experimental Identity of an agenda-verified settlement, not a fabricated transcript.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export type ResidentSettledInvocation = Pick<
 	ResidentHistoryMatch,
 	'revision' | 'claimId' | 'step' | 'kind'
 >
-/** @experimental Settlement is checked before the host resolves the attempt's invocation. */
+/**
+ * @experimental Settlement is checked before the host resolves the attempt's invocation.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentToolEvidenceOptions {
 	readonly history: ResidentHistorySource
 	readonly projectId: string
@@ -45,7 +57,11 @@ export interface ResidentToolEvidenceOptions {
 		signal?: AbortSignal,
 	) => Promise<SessionEvidenceSource>
 }
-/** @experimental An optional shared ceiling covers history, resolution and turn evidence. */
+/**
+ * @experimental An optional shared ceiling covers history, resolution and turn evidence.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentToolEvidenceSearchOptions {
 	readonly query?: string
 	/** Token discovery: 1–16 terms, matched case-insensitively. Combined query/filter JSON ≤512 UTF-8 bytes. */
@@ -60,7 +76,11 @@ export interface ResidentToolEvidenceSearchOptions {
 	readonly refineTerms?: readonly string[]
 	readonly maxReadBytes?: number
 }
-/** @experimental Tool records from at most one settled invocation per bounded search page. */
+/**
+ * @experimental Tool records from at most one settled invocation per bounded search page.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentToolEvidenceSearchResult {
 	readonly scope: ResidentToolEvidenceScope
 	readonly revision: number | null
@@ -75,20 +95,32 @@ export interface ResidentToolEvidenceSearchResult {
 	 */
 	readonly chargedBytes?: number
 }
-/** @experimental The revision is authorized anew on every read, including after restart. */
+/**
+ * @experimental The revision is authorized anew on every read, including after restart.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentToolEvidenceReadOptions
 	extends Omit<SessionEvidenceReadOptions, 'maxReadBytes'> {
 	readonly revision: number
 	/** Shared operation ceiling, at most 8 MiB; reserves at least 1 MiB for turn evidence reads. */
 	readonly maxReadBytes?: number
 }
-/** @experimental Exact invocation text plus the settled claim that authorized access. */
+/**
+ * @experimental Exact invocation text plus the settled claim that authorized access.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentToolEvidenceReadResult extends SessionEvidenceReadResult {
 	readonly revision: number
 	readonly claimId: string
 	readonly chargedBytes?: number
 }
-/** @experimental A host must bind tool access to the executing turn, not just this source. */
+/**
+ * @experimental A host must bind tool access to the executing turn, not just this source.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentToolEvidenceSource {
 	readonly scope: ResidentToolEvidenceScope
 	readonly supportsTermRefinement?: boolean
@@ -102,7 +134,11 @@ export interface ResidentToolEvidenceSource {
 	): Promise<ResidentToolEvidenceReadResult>
 }
 
-/** @experimental Reuses the immutable agenda boundary; it never enumerates arbitrary sessions. */
+/**
+ * @experimental Reuses the immutable agenda boundary; it never enumerates arbitrary sessions.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export function createResidentToolEvidenceSource(
 	options: ResidentToolEvidenceOptions,
 ): ResidentToolEvidenceSource {

package/src/prompt/resident-learning.ts

@@ -1,17 +1,25 @@
 import { z } from 'zod'
-import { freezeResidentLearning, projectResidentLearning } from '../manager/resident/learning.js'
+import { freezeLearning, projectLearning } from '../learning/skill.js'
 import { defineTool } from '../tools/defineTool.js'
 import type { ToolContext, ToolDefinition } from '../types/tool/index.js'
 import type { PromptContribution } from './contributions.js'
 import { type ResidentStepPromptOptions, createResidentStepContributions } from './resident-step.js'
 
-/** @experimental One admission's context and read-only access to its evaluated guidance. */
+/**
+ * @experimental One admission's context and read-only access to its evaluated guidance.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentStepContextBundle {
 	readonly contributions: readonly PromptContribution[]
 	readonly tools: readonly ToolDefinition[]
 }
 
-/** @experimental The host must reject reads from runs outside the admitted scope. */
+/**
+ * @experimental The host must reject reads from runs outside the admitted scope.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentStepContextOptions extends ResidentStepPromptOptions {
 	readonly authorizeLearningRead: (context: ToolContext) => boolean
 }
@@ -20,11 +28,13 @@ export interface ResidentStepContextOptions extends ResidentStepPromptOptions {
  * @experimental List guidance descriptions first; disclose complete bodies only
  * when requested. Selection is local to this admission, never persisted as a
  * preference or inferred from keywords. Mount both returned tools and context.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export function createResidentStepContext(
 	options: ResidentStepContextOptions,
 ): ResidentStepContextBundle {
-	const learning = options.learning ? freezeResidentLearning(options.learning) : undefined
+	const learning = options.learning ? freezeLearning(options.learning) : undefined
 	const contributions = createResidentStepContributions({
 		...options,
 		learning: learning ? { ...learning, skills: [] } : undefined,
@@ -35,8 +45,7 @@ export function createResidentStepContext(
 	const authorize = options.authorizeLearningRead
 	const resolveSources = options.resolveLearningSources
 	const selected = new Set<string>()
-	const profileChars = projectResidentLearning(learning, { maxChars: 12_000, skillNames: [] }).text
-		.length
+	const profileChars = projectLearning(learning, { maxChars: 12_000, skillNames: [] }).text.length
 	const project = (names: readonly string[], maxChars = 12_000) => {
 		let sources: ReturnType<NonNullable<typeof resolveSources>> = []
 		try {
@@ -44,7 +53,7 @@ export function createResidentStepContext(
 		} catch {
 			// Unavailable observations cannot establish a dependency match.
 		}
-		return projectResidentLearning(
+		return projectLearning(
 			{ ...learning, identity: undefined, preferences: [] },
 			{ maxChars, skillNames: names, sources },
 		)

package/src/prompt/resident-step.ts

@@ -1,10 +1,10 @@
-import type { ResidentHistoryScope } from '../manager/resident/history.js'
 import {
-	type ResidentLearningSource,
-	type ResidentLearningState,
-	freezeResidentLearning,
-	projectResidentLearning,
-} from '../manager/resident/learning.js'
+	type LearningSource,
+	type LearningState,
+	freezeLearning,
+	projectLearning,
+} from '../learning/skill.js'
+import type { ResidentHistoryScope } from '../manager/resident/history.js'
 import type { ResidentState } from '../manager/resident/store.js'
 import type { PromptContribution } from './contributions.js'
 
@@ -34,13 +34,17 @@ Use permitted reads and analysis. Do not change files, persistent memory or exte
 const HISTORY_GUIDANCE = `## Resident recall
 When the saved summary lacks an earlier decision or accepted input, use search_resident_history, then read_resident_history for exact retained text. Search without a query to browse recent steps. Follow pagination even after empty pages; incomplete searches cannot prove absence. Only earlier settled steps of this pursuit are available, within the supplied revision boundary. Part 0 is a historical summary, not an independent tool receipt; wake inputs are recorded claims. Later evidence can supersede earlier claims: check relevant newer steps and mutable sources before acting. Do not repeat an effect to recover its output. These tools do not restore unrecorded tool transcripts.`
 
-/** @experimental Host-selected context for one admitted resident step. */
+/**
+ * @experimental Host-selected context for one admitted resident step.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
+ */
 export interface ResidentStepPromptOptions {
 	readonly state: ResidentState
 	/** The host-approved learning snapshot bound to this admission. */
-	readonly learning?: ResidentLearningState
+	readonly learning?: LearningState
 	/** Host resolves current dependency revisions for each model request. No model-generated revisions. */
-	readonly resolveLearningSources?: () => readonly ResidentLearningSource[]
+	readonly resolveLearningSources?: () => readonly LearningSource[]
 	/** Bound historical source whose read-only tools the host has mounted. */
 	readonly history?: ResidentHistoryScope
 	/** The host mounted scoped search_resident_tools/read_resident_tool capabilities. */
@@ -64,6 +68,8 @@ export interface ResidentStepPromptOptions {
  *
  * Project instructions and authorization remain on their existing host/runtime
  * paths. These contributions neither load project files nor authorize work.
+ *
+ * @deprecated Residents are deprecated and removed in the next major release. Learning (`runLearningCycle` and the other `Learning*` names) keeps working, but `runLearningCycle` still takes a resident agenda until learning gets its own activation target in the next major release; for long-running work use scheduled tasks (`LocalTaskScheduler`), session goals and background agents.
  */
 export function createResidentStepContributions(
 	options: ResidentStepPromptOptions,
@@ -76,11 +82,11 @@ export function createResidentStepContributions(
 			options.history.pursuitId !== state.pursuitId)
 	)
 		throw new Error('Resident history context belongs to a different pursuit.')
-	const admittedLearning = options.learning ? freezeResidentLearning(options.learning) : undefined
+	const admittedLearning = options.learning ? freezeLearning(options.learning) : undefined
 	const boundNames =
 		admittedLearning?.skills.filter((skill) => skill.sources?.length).map((skill) => skill.name) ??
 		[]
-	const learning = projectResidentLearning(admittedLearning, {
+	const learning = projectLearning(admittedLearning, {
 		maxChars: 12_000,
 		skillNames:
 			admittedLearning?.skills
@@ -137,13 +143,13 @@ export function createResidentStepContributions(
 						id: 'namzu.resident-step.source-bound-learning',
 						placement: 'context' as const,
 						render: () => {
-							let sources: readonly ResidentLearningSource[] = []
+							let sources: readonly LearningSource[] = []
 							try {
 								sources = resolveSources?.() ?? []
 							} catch {
 								/* Unavailable evidence withholds bound instructions. */
 							}
-							const projection = projectResidentLearning(
+							const projection = projectLearning(
 								admittedLearning
 									? { ...admittedLearning, identity: undefined, preferences: [] }
 									: undefined,

package/src/public-runtime.ts

@@ -1473,6 +1473,8 @@ export {
 } from './runtime/query/auto-review/index.js'
 // What the model is told when a person declines a call without words of their own.
 export { DECLINED_TOOL_CALL_FEEDBACK } from './runtime/query/declined.js'
+// Whether a tool result answers a call the review did not let run, so a host counting failures can leave it out.
+export { isReviewRefusalResult } from './runtime/query/iteration/phases/per-call-review.js'
 
 // The system prompt is open: a contribution registry the assembler
 // consumes, with skills as its first contributor. See `prompt/contributions.ts`.
@@ -1651,11 +1653,31 @@ export { validateResidentProposal } from './manager/resident/proposal.js'
 export { deliverResidentMessage } from './manager/resident/outbox.js'
 export { createResidentDeliveryWindow } from './manager/resident/delivery-window.js'
 
+export { hashLearningSkill, projectLearning } from './learning/skill.js'
+export { runLearningCycle } from './learning/cycle.js'
 export {
-	hashResidentSkill,
-	projectResidentLearning,
-} from './manager/resident/learning.js'
-export { runResidentLearningCycle } from './manager/resident/learning-cycle.js'
+	LEARNING_FLOOR_COMPONENTS,
+	LEARNING_SURFACE_KINDS,
+	learningExperienceFromCycle,
+	proposeLearningCandidate,
+	resolveLearningSurface,
+} from './learning/generator.js'
+export {
+	LEARNING_CONFIDENCE_LEVELS,
+	LEARNING_EDIT_VERDICTS,
+	normalizeLearningExperience,
+	selectLearningExperience,
+} from './learning/experience.js'
+export {
+	LEARNING_EXPERIENCE_STORE_VERSION,
+	SqliteLearningExperienceStore,
+} from './learning/experience-store.js'
+export {
+	LearningLeakError,
+	assertNoLearningLeak,
+	createLearningCanary,
+	scanForLearningLeak,
+} from './learning/leak-tripwire.js'
 
 export {
 	createSessionEvidenceSource,
@@ -1670,11 +1692,19 @@ export { createResidentToolEvidenceSource } from './manager/resident/tool-eviden
 
 export { createResidentEvidenceRecallStep } from './manager/resident/evidence-recall.js'
 
+export {
+	SqliteLearningStore,
+	runStoredLearningCycle,
+	runStoredLearningFromObservations,
+} from './learning/store.js'
 export {
 	SqliteResidentLearningStore,
+	hashResidentSkill,
+	projectResidentLearning,
+	runResidentLearningCycle,
 	runStoredResidentLearningCycle,
 	runStoredResidentLearningFromObservations,
-} from './manager/resident/learning-store.js'
+} from './learning/deprecated.js'
 
 // ─── sessions, turns and the session log ─────────────────────────────────
 //

package/src/public-types.ts

@@ -607,29 +607,58 @@ export type {
 	ResidentContextualStep,
 } from './manager/resident/host.js'
 export type {
-	ResidentLearningEvidence,
-	ResidentSkillCandidate,
-	ResidentLearnedSkill,
-	ResidentLearningState,
-	ResidentProfileUpdate,
-	ResidentSkillEvaluation,
-	ResidentLearningProjectionOptions,
-	ResidentLearningSource,
-	ResidentLearningProjection,
-} from './manager/resident/learning.js'
-export type {
-	ResidentLearningStage,
-	ResidentLearningReceipt,
-	ResidentLearningConsumption,
-	ResidentLearningCycleEvent,
-	ResidentLearningCycleContext,
-	ResidentLearningGenerationContext,
-	ResidentLearningExplorationContext,
-	ResidentLearningExploration,
-	ResidentLearningEvaluationContext,
-	ResidentLearningCycleOptions,
-	ResidentLearningCycleResult,
-} from './manager/resident/learning-cycle.js'
+	LearningEvidence,
+	LearningSkillCandidate,
+	LearnedSkill,
+	LearningState,
+	LearningProfileUpdate,
+	LearningSkillEvaluation,
+	LearningProjectionOptions,
+	LearningSource,
+	LearningProjection,
+} from './learning/skill.js'
+export type {
+	LearningStage,
+	LearningReceipt,
+	LearningConsumption,
+	LearningCycleEvent,
+	LearningCycleContext,
+	LearningGenerationContext,
+	LearningExplorationContext,
+	LearningExploration,
+	LearningEvaluationContext,
+	LearningCycleOptions,
+	LearningCycleResult,
+} from './learning/cycle.js'
+
+export type {
+	LearningModel,
+	LearningModelReply,
+	LearningModelRequest,
+	LearningProposal,
+	LearningProposeOptions,
+	LearningProposedEdit,
+	LearningSurface,
+	LearningSurfaceKind,
+} from './learning/generator.js'
+
+export type {
+	LearningConfidence,
+	LearningEditRow,
+	LearningEditVerdict,
+	LearningExperienceEntry,
+	LearningExperienceInput,
+	LearningExperienceQuery,
+	LearningLesson,
+} from './learning/experience.js'
+export type { SqliteLearningExperienceStoreOptions } from './learning/experience-store.js'
+
+export type {
+	LearningLeakGuard,
+	LearningLeakKind,
+	LearningLeakFinding,
+	LearningLeakSubject,
+} from './learning/leak-tripwire.js'
 
 export type {
 	ResidentArchiveRequest,
@@ -678,18 +707,18 @@ export type {
 } from './turn/json-claim-verifier.js'
 
 export type {
-	SqliteResidentLearningStoreOptions,
-	ResidentLearningArtifact,
-	ResidentLearningRecordedUsage,
-	ResidentLearningCycleSummary,
-	ResidentLearningDiscoveryOptions,
-	ResidentLearningDiscoveryResult,
-} from './manager/resident/learning-store.js'
+	SqliteLearningStoreOptions,
+	LearningArtifact,
+	LearningRecordedUsage,
+	LearningCycleSummary,
+	LearningDiscoveryOptions,
+	LearningDiscoveryResult,
+} from './learning/store.js'
 export type {
-	ResidentLearningObservation,
-	ResidentLearningObservationRecord,
-	ResidentLearningTarget,
-} from './manager/resident/learning-observation.js'
+	LearningObservation,
+	LearningObservationRecord,
+	LearningTarget,
+} from './learning/observation.js'
 
 // ─── sessions, turns and the session log: paths and log lines ────────────
 // The session types themselves come through `./types/session/index.js` above.
@@ -818,3 +847,36 @@ export type {
 } from './pals/activity/subscription-policy.js'
 export type { PalActivitySubscriptionRunnerOptions } from './pals/activity/subscriptions.js'
 export type { PalActivityCausalityOptions } from './pals/activity/causality.js'
+
+// Deprecated resident-prefixed names, kept until the next major.
+export type {
+	ResidentLearningEvidence,
+	ResidentSkillCandidate,
+	ResidentLearnedSkill,
+	ResidentLearningState,
+	ResidentProfileUpdate,
+	ResidentSkillEvaluation,
+	ResidentLearningProjectionOptions,
+	ResidentLearningSource,
+	ResidentLearningProjection,
+	ResidentLearningStage,
+	ResidentLearningReceipt,
+	ResidentLearningConsumption,
+	ResidentLearningCycleEvent,
+	ResidentLearningCycleContext,
+	ResidentLearningGenerationContext,
+	ResidentLearningExplorationContext,
+	ResidentLearningExploration,
+	ResidentLearningEvaluationContext,
+	ResidentLearningCycleOptions,
+	ResidentLearningCycleResult,
+	SqliteResidentLearningStoreOptions,
+	ResidentLearningArtifact,
+	ResidentLearningRecordedUsage,
+	ResidentLearningCycleSummary,
+	ResidentLearningDiscoveryOptions,
+	ResidentLearningDiscoveryResult,
+	ResidentLearningObservation,
+	ResidentLearningObservationRecord,
+	ResidentLearningTarget,
+} from './learning/deprecated.js'

package/src/runtime/query/file-evidence-context.ts

@@ -29,6 +29,13 @@ import {
  */
 const MAX_RECEIPT_UNITS = 32_000
 
+/** The heading of the file-evidence block; a later block under it replaces an earlier one. */
+export const FILE_EVIDENCE_HEADING =
+	'Visible file evidence (as of this step; a later block with this heading replaces this one)'
+
+/** Said when the entries of an earlier block no longer hold and none replaces them. */
+export const FILE_EVIDENCE_NONE = `${FILE_EVIDENCE_HEADING}: no entry holds any longer.`
+
 interface FileEvidence {
 	readonly path: string
 	/** Absent on the write-rooted entries; `'read'` on a body that is a receipt. */
@@ -79,7 +86,7 @@ export function describeVisibleFileEvidence(
 		}
 	}
 	if (files.size === 0) return
-	return `Visible file evidence (this request only): each entry's current body is the complete body in the named successful write call, with the edit calls in editsInCalls — when present — applied in that order. An entry marked kind:"read" instead names a successful read call whose own receipt shows the file WHOLE, rendered with every line behind its own N<tab> prefix; that receipt is the body, and such an entry never carries editsInCalls. This runtime performed that reconstruction and checked it against its own file observation; it is not a derivation left to you. Reuse the body for a targeted edit; a read solely to recall it is unnecessary. This is NOT a fresh disk check, and after a resume the observation behind an entry may itself have been rebuilt from this conversation's own earlier calls rather than made while this process ran. Built-in edit/write still compare the disk body at mutation admission and refuse observed drift; on refusal inspect the current file and replan. Missing entries establish nothing.\n${JSON.stringify([...files.values()])}`
+	return `${FILE_EVIDENCE_HEADING}: each entry's current body is the complete body in the named successful write call, with the edit calls in editsInCalls — when present — applied in that order. An entry marked kind:"read" instead names a successful read call whose own receipt shows the file WHOLE, rendered with every line behind its own N<tab> prefix; that receipt is the body, and such an entry never carries editsInCalls. This runtime performed that reconstruction and checked it against its own file observation; it is not a derivation left to you. Reuse the body for a targeted edit; a read solely to recall it is unnecessary. This is NOT a fresh disk check, and after a resume the observation behind an entry may itself have been rebuilt from this conversation's own earlier calls rather than made while this process ran. Built-in edit/write still compare the disk body at mutation admission and refuse observed drift; on refusal inspect the current file and replan. Missing entries establish nothing.\n${JSON.stringify([...files.values()])}`
 }
 
 /** A full body that arrived whole in one call and is still the file's body. */

package/src/runtime/query/iteration/index.ts

@@ -28,6 +28,7 @@ import {
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js'
 import type { ToolManager } from '../../../toolsets/manager.js'
+import { splitAtEvidenceBlocks } from '../../../turn/evidence-recall.js'
 import type { CostInfo, TokenUsage } from '../../../types/common/index.js'
 import { NamzuError } from '../../../types/errors/index.js'
 import type { MessageId, SessionId, TurnId } from '../../../types/ids/index.js'
@@ -57,6 +58,7 @@ import { createCallbackInference } from '../callback-inference.js'
 import { SandboxAcquisitionStopped } from '../deferred-sandbox.js'
 import { deliverDurableInbound } from '../durable-inbound.js'
 import type { ToolCallOutcome } from '../executor.js'
+import { FILE_EVIDENCE_NONE } from '../file-evidence-context.js'
 import { projectObservationContext } from '../observation-context.js'
 import { applyLifecycleHookResults } from '../plugin-hooks.js'
 import {
@@ -102,14 +104,16 @@ import {
 	streamWithProviderRejectedImageRecovery,
 } from './provider-rejected-image.js'
 import { type MediaRemoval, RequestRepair } from './request-repair.js'
-import { placeBeforeLatestOperatorMessage } from './step-context.js'
+import { TurnContextCarry } from './step-context.js'
 import {
+	FILE_EVIDENCE_KEY,
 	type StepShaping,
 	appendWorkContext,
 	beforeStep,
 	prepareStep,
 	selectContextModel,
 	stepContextMessage,
+	workContextBlocks,
 } from './step-shaping.js'
 import { streamProviderTurn } from './stream-turn.js'
 
@@ -190,6 +194,8 @@ export class IterationOrchestrator {
 	 * one process must not suppress each other's first envelope.
 	 */
 	private lastEnvelopeKey: string | undefined
+	/** Where this turn's request-only data first went, so it stays there. */
+	private readonly turnContext = new TurnContextCarry()
 	private previousRequestContext: RequestContextSnapshot | undefined
 
 	private projectObservations(messages: Message[]): Message[] {
@@ -895,27 +901,35 @@ export class IterationOrchestrator {
 						? [...workingMemory.history, createSystemMessage(stepPreamble)]
 						: [...workingMemory.history]
 					if (workingMemory.context) requestHistory.push(workingMemory.context)
-					// The blocks of data that belong to this turn (recalled memory and
-					// evidence, the context contributions) sit just before the
-					// operator's latest message, so the request is the last thing the
-					// model reads. The short reminders and notices stay after it.
-					placeBeforeLatestOperatorMessage(
-						requestHistory,
-						[contextText, step.context]
-							.filter((text): text is string => Boolean(text))
-							.map(stepContextMessage),
-					)
 					// After the history, never ahead of it: a system message in front
 					// of the conversation moves the prefix every cached request shares,
 					// and a mode change would re-key the whole conversation.
 					if (policyNotice) requestHistory.push(stepContextMessage(policyNotice))
-					const messages = projectRequestRichContent(
+					const projected = projectRequestRichContent(
 						this.projectObservations(requestHistory),
 						this.ctx.turnConfig.maxRequestRichContentBytes ??
 							DEFAULT_MAX_REQUEST_RICH_CONTENT_BYTES,
 						{ imagesReadable: this.modelReadsImages(stepModel) },
 					)
-					appendWorkContext(shaping, messages, iterationNum, step)
+					// The blocks of data that belong to this turn (recalled memory and
+					// evidence, the context contributions, the work context) sit just
+					// before the operator's latest message the first time the model
+					// answers it, so the request is the last thing it reads. They stay
+					// there on every later call of the turn, and a block that first
+					// appears on a later call follows the history of that moment, so each
+					// request begins with the whole of the one before it. The short
+					// reminders and notices stay after the history.
+					const messages = [...projected]
+					this.turnContext.place(
+						messages,
+						requestHistory,
+						workingMemory.history.at(-1),
+						[contextText, ...(step.context ? splitAtEvidenceBlocks(step.context) : [])]
+							.filter((text): text is string => Boolean(text))
+							.map(stepContextMessage),
+						workContextBlocks(shaping, projected, iterationNum, step),
+						{ [FILE_EVIDENCE_KEY]: stepContextMessage(FILE_EVIDENCE_NONE) },
+					)
 					if (closingDirective) messages.push(closingDirective)
 					await this.reportUnsupportedToolResults(messages)
 					yield* this.ctx.drainPending()