@namzu/sdk 38.2.1 → 40.0.0

package/src/manager/resident/learning.ts

@@ -1,5 +1,9 @@
 import { createHash } from 'node:crypto'
 import { z } from 'zod'
+import {
+	type HarnessProtectionPlan,
+	normalizeHarnessProtection,
+} from '../../eval/harness-protection.js'
 import {
 	type HarnessVerificationBatch,
 	reviewHarnessCandidate,
@@ -17,14 +21,45 @@ export const residentLearningEvidenceSchema = z.object({
 /** @experimental Host provenance for a correction, evaluated activation or rollback. */
 export type ResidentLearningEvidence = Readonly<z.infer<typeof residentLearningEvidenceSchema>>
 
+const sourceSchema = z.object({ key: label, revision: label })
+/** @experimental Host-owned source identity and revision; neither is a model assertion. */
+export type ResidentLearningSource = Readonly<z.infer<typeof sourceSchema>>
+
+const sourcesSchema = z
+	.array(sourceSchema)
+	.min(1)
+	.max(8)
+	.superRefine((sources, context) => {
+		if (new Set(sources.map((source) => source.key)).size !== sources.length)
+			context.addIssue({ code: z.ZodIssueCode.custom, message: 'Duplicate learning source keys.' })
+	})
+	.transform((sources) => sources.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0)))
+
 const candidateSchema = z.object({
 	name,
+	/** Omitted means ordinary task guidance; exploration policies require explicit projection. */
+	purpose: z.enum(['task', 'exploration']).optional(),
 	description: z.string().trim().min(1).max(1_000),
 	body: z.string().trim().min(1).max(4_000),
+	/** Optional dependencies whose revisions must still match before projection. */
+	sources: sourcesSchema.optional(),
 })
 
 /** @experimental Instructional guidance only; never executable assets or tool permissions. */
-export type ResidentSkillCandidate = Readonly<z.infer<typeof candidateSchema>>
+export type ResidentSkillCandidate = Readonly<Omit<z.infer<typeof candidateSchema>, 'sources'>> & {
+	readonly sources?: readonly ResidentLearningSource[]
+}
+
+/** Internal canonical snapshot, including immutable source bindings. */
+export function normalizeResidentSkill(input: ResidentSkillCandidate): ResidentSkillCandidate {
+	const candidate = candidateSchema.parse(input)
+	return Object.freeze({
+		...candidate,
+		...(candidate.sources
+			? { sources: Object.freeze(candidate.sources.map((source) => Object.freeze(source))) }
+			: {}),
+	})
+}
 
 const learnedSkillSchema = candidateSchema.extend({
 	hash: digest,
@@ -35,11 +70,21 @@ const learnedSkillSchema = candidateSchema.extend({
 		evidenceDigest: digest,
 		verificationTasks: z.number().int().min(5).max(64),
 		confirmationTasks: z.number().int().min(5).max(64),
+		/** Absent only on historical activations made before protection was required. */
+		protection: z
+			.object({
+				verificationTasks: z.number().int().min(1).max(63),
+				confirmationTasks: z.number().int().min(1).max(63),
+				planDigest: digest,
+			})
+			.optional(),
 	}),
 })
 
 /** @experimental Immutable evaluated content and evidence identity. */
-export type ResidentLearnedSkill = Readonly<z.infer<typeof learnedSkillSchema>>
+export type ResidentLearnedSkill = Readonly<Omit<z.infer<typeof learnedSkillSchema>, 'sources'>> & {
+	readonly sources?: readonly ResidentLearningSource[]
+}
 
 export const residentLearningSchema = z
 	.object({
@@ -104,6 +149,8 @@ export interface ResidentProfileUpdate {
 
 /** @experimental Recorded paired runs; hosts own execution, scoring and independent attribution. */
 export interface ResidentSkillEvaluation {
+	/** Host-owned task selection fixed before generating the candidate. */
+	readonly protection: HarnessProtectionPlan
 	readonly verification: HarnessVerificationBatch
 	readonly confirmation?: HarnessVerificationBatch
 }
@@ -128,8 +175,16 @@ export function freezeResidentLearning(input: ResidentLearningState): ResidentLe
 			state.skills.map((skill) =>
 				Object.freeze({
 					...skill,
+					...(skill.sources
+						? { sources: Object.freeze(skill.sources.map((source) => Object.freeze(source))) }
+						: {}),
 					evidence: Object.freeze(skill.evidence),
-					verification: Object.freeze(skill.verification),
+					verification: Object.freeze({
+						...skill.verification,
+						...(skill.verification.protection
+							? { protection: Object.freeze(skill.verification.protection) }
+							: {}),
+					}),
 				}),
 			),
 		),
@@ -214,11 +269,19 @@ export function reviseResidentProfile(
 	})
 }
 
-/** @experimental Bind evaluation to the exact normalized name, description and body. */
+/** @experimental Bind evaluation to normalized content and any declared source dependencies. */
 export function hashResidentSkill(input: ResidentSkillCandidate): string {
 	const candidate = candidateSchema.parse(input)
 	return createHash('sha256')
-		.update(JSON.stringify([candidate.name, candidate.description, candidate.body]))
+		.update(
+			JSON.stringify([
+				candidate.name,
+				candidate.description,
+				candidate.body,
+				...(candidate.sources ? [candidate.sources] : []),
+				...(candidate.purpose === 'exploration' ? [{ purpose: candidate.purpose }] : []),
+			]),
+		)
 		.digest('hex')
 }
 
@@ -229,9 +292,13 @@ export function promoteResidentSkill(
 	evaluation: ResidentSkillEvaluation,
 	inputEvidence: ResidentLearningEvidence,
 ): ResidentLearningState {
+	const protection = normalizeHarnessProtection(evaluation.protection)
 	const candidate = candidateSchema.parse(input)
 	const hash = hashResidentSkill(candidate)
-	const baselineHash = current?.skills.find((s) => s.name === candidate.name)?.hash ?? 'none'
+	const baseline = current?.skills.find((s) => s.name === candidate.name)
+	if (baseline && (baseline.purpose ?? 'task') !== (candidate.purpose ?? 'task'))
+		throw new Error('A skill cannot change learning purpose; use a distinct skill name.')
+	const baselineHash = baseline?.hash ?? 'none'
 	const evidence = evidenceFor(current, inputEvidence)
 	for (const batch of [evaluation.verification, evaluation.confirmation]) {
 		if (!batch) continue
@@ -252,7 +319,11 @@ export function promoteResidentSkill(
 				throw new Error('Inconsistent recorded skill evaluation outcome.')
 		}
 	}
-	const review = reviewHarnessCandidate(evaluation.verification, evaluation.confirmation)
+	const review = reviewHarnessCandidate(
+		evaluation.verification,
+		evaluation.confirmation,
+		protection,
+	)
 	if (review.decision !== 'accept')
 		throw new Error(`Resident skill promotion ${review.decision}: ${review.reason}`)
 	const skill: ResidentLearnedSkill = {
@@ -262,9 +333,16 @@ export function promoteResidentSkill(
 		verification: {
 			baselineHash,
 			candidateHash: hash,
-			evidenceDigest: createHash('sha256').update(JSON.stringify(evaluation)).digest('hex'),
+			evidenceDigest: createHash('sha256')
+				.update(JSON.stringify({ ...evaluation, protection }))
+				.digest('hex'),
 			verificationTasks: review.verification.tasks.length,
 			confirmationTasks: review.confirmation?.tasks.length ?? 0,
+			protection: {
+				verificationTasks: protection.verification.length,
+				confirmationTasks: protection.confirmation.length,
+				planDigest: createHash('sha256').update(JSON.stringify(protection)).digest('hex'),
+			},
 		},
 	}
 	const next = base(current, evidence)
@@ -298,6 +376,10 @@ export function restoreResidentSkill(
 export interface ResidentLearningProjectionOptions {
 	readonly maxChars: number
 	readonly skillNames: readonly string[]
+	/** Defaults to task guidance. Exploration policies never enter ordinary task context. */
+	readonly purpose?: 'task' | 'exploration'
+	/** Fresh host observations for this projection; absent/mismatched dependencies withhold guidance. */
+	readonly sources?: readonly ResidentLearningSource[]
 }
 
 /** @experimental Omitted entries are counted; no partial skill instruction is emitted. */
@@ -306,6 +388,11 @@ export interface ResidentLearningProjection {
 	readonly revision: number | null
 	readonly includedSkills: readonly string[]
 	readonly omitted: number
+	readonly withheldSkills: readonly {
+		readonly name: string
+		readonly reason: 'changed-source' | 'unverified-source' | 'different-purpose'
+		readonly sourceKeys: readonly string[]
+	}[]
 }
 
 /** @experimental Bounded context data; never registers tools, loads files or executes a skill. */
@@ -316,17 +403,27 @@ export function projectResidentLearning(
 	if (!Number.isSafeInteger(options.maxChars) || options.maxChars < 0 || options.maxChars > 64_000)
 		throw new TypeError('Resident learning context requires maxChars between 0 and 64000.')
 	const selected = z.array(name).max(16).parse(options.skillNames)
+	const purpose = z.enum(['task', 'exploration']).parse(options.purpose ?? 'task')
 	if (new Set(selected).size !== selected.length) throw new Error('Duplicate selected skill names.')
+	const sources = z
+		.array(sourceSchema)
+		.max(128)
+		.parse(options.sources ?? [])
+	if (new Set(sources.map((source) => source.key)).size !== sources.length)
+		throw new Error('Duplicate observed learning source keys.')
+	const observed = new Map(sources.map((source) => [source.key, source.revision]))
 	if (!current)
 		return Object.freeze({
 			text: '',
 			revision: null,
 			includedSkills: Object.freeze([]),
 			omitted: selected.length,
+			withheldSkills: Object.freeze([]),
 		})
 	const state = freezeResidentLearning(current)
 	const pieces: string[] = []
 	const includedSkills: string[] = []
+	const withheldSkills: ResidentLearningProjection['withheldSkills'][number][] = []
 	let omitted = 0
 	let length = 0
 	const add = (value: unknown): boolean => {
@@ -348,6 +445,32 @@ export function projectResidentLearning(
 			omitted++
 			continue
 		}
+		if ((skill.purpose ?? 'task') !== purpose) {
+			omitted++
+			withheldSkills.push(
+				Object.freeze({
+					name: skill.name,
+					reason: 'different-purpose',
+					sourceKeys: Object.freeze([]),
+				}),
+			)
+			continue
+		}
+		const mismatched =
+			skill.sources?.filter((source) => observed.get(source.key) !== source.revision) ?? []
+		if (mismatched.length) {
+			omitted++
+			withheldSkills.push(
+				Object.freeze({
+					name: skill.name,
+					reason: mismatched.some((source) => observed.has(source.key))
+						? 'changed-source'
+						: 'unverified-source',
+					sourceKeys: Object.freeze(mismatched.map((source) => source.key)),
+				}),
+			)
+			continue
+		}
 		if (
 			add({
 				kind: 'evaluated-guidance',
@@ -365,5 +488,6 @@ export function projectResidentLearning(
 		revision: state.revision,
 		includedSkills: Object.freeze(includedSkills),
 		omitted,
+		withheldSkills: Object.freeze(withheldSkills),
 	})
 }

package/src/manager/resident/store.ts

@@ -11,6 +11,17 @@ import { asTenantId } from '../../utils/id.js'
 
 const text = z.string().trim().min(1).max(8_000)
 const time = z.number().int().nonnegative().safe()
+const MAX_WAKE_EVIDENCE_CHARS = 16_000
+const wakeEvidence = z
+	.array(z.object({ reason: text, receivedAt: time }).readonly())
+	.min(1)
+	.max(16, 'Resident has 16 pending wake inputs; process them before adding more.')
+	.refine(
+		(entries) =>
+			entries.reduce((total, entry) => total + entry.reason.length, 0) <= MAX_WAKE_EVIDENCE_CHARS,
+		'Resident wake evidence exceeds 16000 characters; process pending evidence before adding more.',
+	)
+	.readonly()
 export const residentDecisionSchema = z.discriminatedUnion('kind', [
 	z.object({ kind: z.literal('wait'), summary: text, wakeAt: time.nullable() }),
 	z.object({ kind: z.literal('complete'), summary: text }),
@@ -32,6 +43,8 @@ export const residentStateSchema = z
 		phase: z.enum(['waiting', 'running', 'complete', 'blocked']),
 		wakeAt: time.nullable(),
 		reason: text,
+		/** Accepted wake inputs, in commit order, retained until this step settles. */
+		wakeEvidence: wakeEvidence.optional(),
 		summary: text.nullable(),
 		claimId: z.string().uuid().nullable(),
 	})
@@ -48,6 +61,12 @@ export const residentStateSchema = z
 				message: 'Only waiting state may have a wake time.',
 			})
 		}
+		if (state.wakeEvidence && state.phase !== 'waiting' && state.phase !== 'running') {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: 'Only waiting or unresolved running work may retain wake evidence.',
+			})
+		}
 	})
 
 /** @experimental Persisted identity and one pursuit, independent of a conversation. */
@@ -88,7 +107,7 @@ export class ResidentConflictError extends Error {
  */
 export class DiskResidentStore implements ResidentStore {
 	private readonly records = new DiskRevisionRecordStore<ResidentState>(
-		defineSchema({ kind: 'resident', current: 1, migrations: {} }),
+		defineSchema({ kind: 'resident', current: 2, migrations: { 1: (record) => record } }),
 		'resident store',
 		(record) => record.revision,
 	)
@@ -207,8 +226,11 @@ export function settleResidentState(
 	if (outcome.kind === 'wait' && outcome.wakeAt !== null && outcome.wakeAt <= now)
 		throw new Error('A scheduled continuation must be in the future.')
 	if (state.phase !== 'running') throw new Error('Resident has no admitted step to settle.')
+	// Admission alone is not acknowledgment: an interrupted step retains every
+	// input. Only successful exact-claim settlement consumes the captured batch.
+	const { wakeEvidence: _consumed, ...settled } = state
 	return {
-		...state,
+		...settled,
 		phase: outcome.kind === 'wait' ? 'waiting' : outcome.kind,
 		wakeAt: outcome.kind === 'wait' ? outcome.wakeAt : null,
 		summary: outcome.summary,
@@ -225,5 +247,11 @@ export function wakeResidentState(
 	time.parse(now)
 	const evidence = text.parse(reason)
 	if (state.phase !== 'waiting') throw new Error('Only a waiting resident can be woken.')
-	return { ...state, wakeAt: now, reason: evidence }
+	// Never evict an accepted input to admit another. Backpressure leaves both
+	// the durable state and its revision untouched, so the sender can retry later.
+	const pending = wakeEvidence.parse([
+		...(state.wakeEvidence ?? []),
+		{ reason: evidence, receivedAt: now },
+	])
+	return { ...state, wakeAt: now, reason: evidence, wakeEvidence: pending }
 }