@namzu/sdk 55.0.0 → 56.0.0

package/src/learning/experience-store.ts

@@ -0,0 +1,202 @@
+import { mkdirSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, resolve } from 'node:path'
+import type { DatabaseSync } from 'node:sqlite'
+import { z } from 'zod'
+import type { ProjectId, TenantId } from '../types/ids/index.js'
+import { asProjectId, asTenantId } from '../utils/id.js'
+import {
+	type LearningExperienceEntry,
+	type LearningExperienceInput,
+	type LearningExperienceQuery,
+	assertExperienceHasNoLeak,
+	normalizeLearningExperience,
+	selectLearningExperience,
+} from './experience.js'
+
+const SCHEMA = `
+CREATE TABLE experience (
+  ordinal INTEGER PRIMARY KEY AUTOINCREMENT,
+  tenant_id TEXT NOT NULL, project_id TEXT NOT NULL, agent_key TEXT NOT NULL,
+  domain TEXT NOT NULL, cycle_id TEXT NOT NULL, evaluator_revision TEXT NOT NULL,
+  decision TEXT NOT NULL, body TEXT NOT NULL,
+  UNIQUE(tenant_id, project_id, agent_key, cycle_id)
+);
+CREATE INDEX experience_read ON experience(
+  tenant_id, project_id, agent_key, domain, evaluator_revision, ordinal
+);
+`
+
+/** The schema version this store reads and writes. */
+export const LEARNING_EXPERIENCE_STORE_VERSION = 1
+
+/** @experimental Where the library lives; a separate file from the observation journal. */
+export interface SqliteLearningExperienceStoreOptions {
+	readonly databasePath: string
+	readonly scope: {
+		readonly tenantId: TenantId
+		readonly projectId: ProjectId
+		readonly agentKey: string
+	}
+	readonly readOnly?: boolean
+}
+
+type Row = { ordinal: number; body: string }
+
+/**
+ * @experimental Durable experience library. Entries are immutable: recording
+ * the same cycle again with identical content returns the stored entry, with
+ * different content is refused. The artefact is stored whole.
+ */
+export class SqliteLearningExperienceStore {
+	readonly databasePath: string
+	private readonly scope: SqliteLearningExperienceStoreOptions['scope']
+	private readonly readOnly: boolean
+
+	constructor(options: SqliteLearningExperienceStoreOptions) {
+		this.databasePath = resolve(options.databasePath)
+		this.scope = Object.freeze({
+			tenantId: asTenantId(options.scope.tenantId.toLowerCase()),
+			projectId: asProjectId(options.scope.projectId.toLowerCase()),
+			agentKey: z
+				.string()
+				.regex(/^[a-z0-9][a-z0-9_-]{0,63}$/)
+				.parse(options.scope.agentKey),
+		})
+		this.readOnly = options.readOnly === true
+	}
+
+	private use<T>(write: boolean, operation: (db: DatabaseSync) => T, whenEmpty?: () => T): T {
+		if (write && this.readOnly) throw new Error('Learning experience database is read-only.')
+		let Database: typeof DatabaseSync
+		try {
+			Database = (createRequire(import.meta.url)('node:sqlite') as typeof import('node:sqlite'))
+				.DatabaseSync
+		} catch (error) {
+			throw new Error('SqliteLearningExperienceStore requires Node.js 22.13 or newer.', {
+				cause: error,
+			})
+		}
+		if (!this.readOnly) mkdirSync(dirname(this.databasePath), { recursive: true, mode: 0o700 })
+		const db = new Database(this.databasePath, { readOnly: this.readOnly })
+		try {
+			db.exec('PRAGMA busy_timeout = 5000;')
+			if (!this.readOnly) db.exec('PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL;')
+			db.exec(write ? 'BEGIN IMMEDIATE' : 'BEGIN')
+			try {
+				const version = Number(db.prepare('PRAGMA user_version').get()?.user_version)
+				if (version === 0 && write) {
+					db.exec(`${SCHEMA} PRAGMA user_version = ${LEARNING_EXPERIENCE_STORE_VERSION};`)
+				} else if (version === 0) {
+					if (whenEmpty) {
+						db.exec('COMMIT')
+						return whenEmpty()
+					}
+					throw new Error(
+						'Learning experience database is not initialized; open it for writing first.',
+					)
+				} else if (version !== LEARNING_EXPERIENCE_STORE_VERSION)
+					throw new Error(
+						`Learning experience database is at schema version ${version}; this store reads version ${LEARNING_EXPERIENCE_STORE_VERSION} only.`,
+					)
+				const value = operation(db)
+				db.exec('COMMIT')
+				return value
+			} catch (error) {
+				db.exec('ROLLBACK')
+				throw error
+			}
+		} finally {
+			db.close()
+		}
+	}
+
+	private scopeArgs(): [string, string, string] {
+		return [this.scope.tenantId, this.scope.projectId, this.scope.agentKey]
+	}
+
+	private decode(row: Row): LearningExperienceEntry {
+		return {
+			...(JSON.parse(row.body) as Omit<LearningExperienceEntry, 'ordinal'>),
+			ordinal: row.ordinal,
+		}
+	}
+
+	/** Record one finished cycle. Throws `LearningLeakError` when the entry carries evaluator-side material. */
+	async record(input: LearningExperienceInput): Promise<LearningExperienceEntry> {
+		if (!input.leakGuard) throw new Error('Recording an experience entry requires a leakGuard.')
+		const entry = normalizeLearningExperience(input)
+		assertExperienceHasNoLeak(entry, input.leakGuard)
+		const body = JSON.stringify(entry)
+		return this.use(true, (db) => {
+			const existing = db
+				.prepare(
+					'SELECT ordinal, body FROM experience WHERE tenant_id=? AND project_id=? AND agent_key=? AND cycle_id=?',
+				)
+				.get(...this.scopeArgs(), entry.cycleId) as Row | undefined
+			if (existing) {
+				if (existing.body !== body)
+					throw new Error(
+						'This cycle already has a different experience entry; entries are immutable.',
+					)
+				return this.decode(existing)
+			}
+			const result = db
+				.prepare(
+					'INSERT INTO experience (tenant_id, project_id, agent_key, domain, cycle_id, evaluator_revision, decision, body) VALUES (?,?,?,?,?,?,?,?)',
+				)
+				.run(
+					...this.scopeArgs(),
+					entry.domain,
+					entry.cycleId,
+					entry.evaluatorRevision,
+					entry.decision,
+					body,
+				)
+			return { ...entry, ordinal: Number(result.lastInsertRowid) }
+		})
+	}
+
+	/** The ordinal the next entry will be recorded after; pass it as `beforeOrdinal` to read everything so far. */
+	async nextOrdinal(): Promise<number> {
+		return this.use(
+			false,
+			(db) => {
+				const row = db
+					.prepare(
+						'SELECT MAX(ordinal) AS last FROM experience WHERE tenant_id=? AND project_id=? AND agent_key=?',
+					)
+					.get(...this.scopeArgs()) as { last: number | null }
+				return (row.last ?? 0) + 1
+			},
+			() => 1,
+		)
+	}
+
+	/** Entries of one domain and evaluator revision recorded before `beforeOrdinal`, newest first. */
+	async retrieve(query: LearningExperienceQuery): Promise<LearningExperienceEntry[]> {
+		const rows = this.use(
+			false,
+			(db) =>
+				db
+					.prepare(
+						'SELECT ordinal, body FROM experience WHERE tenant_id=? AND project_id=? AND agent_key=? AND domain=? AND evaluator_revision=? AND ordinal<? ORDER BY ordinal DESC',
+					)
+					.all(
+						...this.scopeArgs(),
+						query.domain,
+						query.evaluatorRevision,
+						query.beforeOrdinal,
+					) as Row[],
+			() => [],
+		)
+		if (!query.leakGuard) throw new Error('Retrieving experience entries requires a leakGuard.')
+		const selected = selectLearningExperience(
+			rows.map((row) => this.decode(row)),
+			query,
+		)
+		for (const { ordinal: _ordinal, ...entry } of selected)
+			assertExperienceHasNoLeak(entry, query.leakGuard)
+		return selected
+	}
+}

package/src/learning/experience.ts

@@ -0,0 +1,238 @@
+import { z } from 'zod'
+import { type LearningLeakGuard, assertNoLearningLeak } from './leak-tripwire.js'
+import {
+	type LearningSkillCandidate,
+	hashLearningSkill,
+	learningEvidenceSchema,
+	normalizeLearningSkill,
+} from './skill.js'
+
+/**
+ * The experience library: what an earlier cycle tried and what came of it,
+ * kept beside the observations so a later generator can read it. Three rules
+ * hold throughout. An entry stores the adopted or rejected artefact whole,
+ * never a summary of it. Retrieval is limited to one domain and to entries
+ * recorded before a stated point. And a verdict never claims more than the
+ * evidence can separate: when a candidate changed several components at once,
+ * the result belongs to the whole change, so each row says `confounded`.
+ */
+
+const label = z.string().trim().min(1).max(256)
+const text = z.string().trim().min(1).max(2_000)
+const domainLabel = z.string().regex(/^[a-z0-9][a-z0-9_.-]{0,63}$/)
+
+export const LEARNING_EDIT_VERDICTS = [
+	'helped',
+	'hurt',
+	'no observed effect',
+	'confounded',
+] as const
+/** @experimental What one edit did, as far as the evidence can separate it from the others. */
+export type LearningEditVerdict = (typeof LEARNING_EDIT_VERDICTS)[number]
+
+export const LEARNING_CONFIDENCE_LEVELS = ['high', 'medium', 'low'] as const
+/** @experimental How far a lesson can be trusted. */
+export type LearningConfidence = (typeof LEARNING_CONFIDENCE_LEVELS)[number]
+
+const editSchema = z.object({
+	/** The part of the harness the edit touched, such as `instruction-skill`. */
+	surface: label,
+	/** What changed, in a sentence. */
+	change: text,
+	verdict: z.enum(LEARNING_EDIT_VERDICTS),
+	/**
+	 * True only when this edit was tried alone (an ablation), so its verdict is
+	 * separable even though the candidate changed several components. The store
+	 * trusts this flag from the caller; it does not check that an ablation ran.
+	 */
+	isolated: z.boolean().optional(),
+})
+
+const lessonSchema = z.object({
+	/** The shape of the situation the lesson applies to, not the incident itself. */
+	cue: text,
+	lesson: text,
+	/** References into the observations, session log or verification receipts. */
+	evidence: z.array(learningEvidenceSchema).min(1).max(16),
+	confidence: z.enum(LEARNING_CONFIDENCE_LEVELS),
+	confidenceReason: text,
+	/** Indexes into the entry's edits that the lesson rests on. */
+	edits: z.array(z.number().int().min(0).max(63)).max(64).optional(),
+})
+
+/** @experimental One edit row of the typed ledger. */
+export type LearningEditRow = Readonly<z.infer<typeof editSchema>>
+/** @experimental A lesson, with the confidence the evidence supports. */
+export type LearningLesson = Readonly<
+	Omit<z.infer<typeof lessonSchema>, 'evidence' | 'edits'> & {
+		readonly evidence: readonly Readonly<z.infer<typeof learningEvidenceSchema>>[]
+		readonly edits?: readonly number[]
+	}
+>
+
+/** What a host passes when it records one finished cycle. */
+export interface LearningExperienceInput {
+	/** The kind of task the cycle was about; retrieval never crosses domains. */
+	readonly domain: string
+	/** The cycle that produced the entry; one entry per cycle. */
+	readonly cycleId: string
+	/** The evaluator that judged the candidate. Lessons are only comparable under the same revision. */
+	readonly evaluatorRevision: string
+	readonly decision: 'adopted' | 'rejected'
+	/** Why, as the verification recorded it. */
+	readonly reason: string
+	/** The whole artefact, as proposed. */
+	readonly candidate: LearningSkillCandidate
+	readonly edits: readonly LearningEditRow[]
+	readonly lessons?: readonly LearningLesson[]
+	/**
+	 * Evaluator-side material to refuse in anything the entry would keep. Required:
+	 * pass `{}` to apply only the built-in markers and secret shapes.
+	 */
+	readonly leakGuard: LearningLeakGuard
+}
+
+const inputSchema = z.object({
+	domain: domainLabel,
+	cycleId: z.string().uuid(),
+	evaluatorRevision: label,
+	decision: z.enum(['adopted', 'rejected']),
+	reason: text,
+	edits: z.array(editSchema).min(1).max(64),
+	lessons: z.array(lessonSchema).max(32).optional(),
+})
+
+/** @experimental A stored entry. `ordinal` is its position in recording order. */
+export interface LearningExperienceEntry {
+	readonly ordinal: number
+	readonly domain: string
+	readonly cycleId: string
+	readonly evaluatorRevision: string
+	readonly decision: 'adopted' | 'rejected'
+	readonly reason: string
+	/** The full artefact as proposed, unabridged. */
+	readonly candidate: LearningSkillCandidate
+	readonly candidateRevision: string
+	readonly edits: readonly LearningEditRow[]
+	readonly lessons: readonly LearningLesson[]
+}
+
+const CAP: Record<LearningConfidence, number> = { low: 0, medium: 1, high: 2 }
+const BY_RANK: readonly LearningConfidence[] = ['low', 'medium', 'high']
+
+/**
+ * Apply the rules that keep a record honest. Several components in one
+ * candidate share a single outcome, so unless a row was tried alone its
+ * verdict becomes `confounded`. A lesson that rests on a confounded edit is
+ * capped at medium; one that rests only on confounded edits is low, and its
+ * reason says why.
+ */
+export function normalizeLearningExperience(
+	input: LearningExperienceInput,
+): Omit<LearningExperienceEntry, 'ordinal'> {
+	const { leakGuard: _guard, candidate: rawCandidate, ...rest } = input
+	const parsed = inputSchema.parse(rest)
+	const candidate = normalizeLearningSkill(rawCandidate)
+	// More than one edit row changed together, whatever its component label.
+	const several = parsed.edits.length > 1
+	const edits: LearningEditRow[] = parsed.edits.map((edit) => {
+		const { isolated, ...row } = edit
+		if (several && isolated !== true) return { ...row, verdict: 'confounded' as const }
+		return isolated === true ? { ...row, isolated } : row
+	})
+	const lessons: LearningLesson[] = (parsed.lessons ?? []).map((lesson) => {
+		// A lesson that cites no edits rests on all of them.
+		const refs = lesson.edits?.length ? lesson.edits : edits.map((_, index) => index)
+		for (const index of refs)
+			if (index >= edits.length) throw new Error(`Lesson refers to edit ${index}, which is absent.`)
+		const confounded = refs.filter((index) => edits[index]?.verdict === 'confounded').length
+		if (confounded === 0) return lesson
+		const all = confounded === refs.length
+		const cap = all ? 'low' : 'medium'
+		if (CAP[lesson.confidence] <= CAP[cap]) {
+			return {
+				...lesson,
+				confidenceReason: `${lesson.confidenceReason} (Stands on confounded edits.)`,
+			}
+		}
+		return {
+			...lesson,
+			confidence: BY_RANK[CAP[cap]] as LearningConfidence,
+			confidenceReason: `${lesson.confidenceReason} (Narrowed to ${cap}: ${
+				all ? 'every' : 'some'
+			} edit it rests on changed together with others.)`,
+		}
+	})
+	return {
+		domain: parsed.domain,
+		cycleId: parsed.cycleId.toLowerCase(),
+		evaluatorRevision: parsed.evaluatorRevision,
+		decision: parsed.decision,
+		reason: parsed.reason,
+		candidate,
+		candidateRevision: hashLearningSkill(candidate),
+		edits,
+		lessons,
+	}
+}
+
+function collectStrings(
+	value: unknown,
+	subject: string,
+	out: { subject: string; text: string }[],
+): void {
+	if (typeof value === 'string') out.push({ subject, text: value })
+	else if (Array.isArray(value)) value.forEach((v, i) => collectStrings(v, `${subject}[${i}]`, out))
+	else if (value && typeof value === 'object')
+		for (const [key, v] of Object.entries(value)) collectStrings(v, `${subject}.${key}`, out)
+}
+
+/**
+ * Refuse an entry that would keep evaluator-side material. Every string the
+ * entry holds is scanned, found by walking the entry rather than by naming
+ * fields; source keys are also tried as paths. Throws {@link LearningLeakError}.
+ */
+export function assertExperienceHasNoLeak(
+	entry: Omit<LearningExperienceEntry, 'ordinal'>,
+	guard: LearningLeakGuard | undefined,
+): void {
+	const subjects: { subject: string; text?: string; paths?: readonly string[] }[] = []
+	const texts: { subject: string; text: string }[] = []
+	collectStrings(entry, 'experience', texts)
+	subjects.push(...texts)
+	for (const [i, source] of (entry.candidate.sources ?? []).entries())
+		subjects.push({ subject: `experience.candidate.sources[${i}].path`, paths: [source.key] })
+	assertNoLearningLeak(guard, subjects)
+}
+
+/** @experimental Where retrieval may look. */
+export interface LearningExperienceQuery {
+	readonly domain: string
+	/** The evaluator the reader is judged by; entries from another revision are not comparable. */
+	readonly evaluatorRevision: string
+	/** Evaluator-side material; entries are scanned again before they are returned. */
+	readonly leakGuard: LearningLeakGuard
+	/** Only entries recorded before this ordinal. The reader's own entry is never among them. */
+	readonly beforeOrdinal: number
+	readonly decision?: 'adopted' | 'rejected'
+	/** Newest first; default 20. */
+	readonly limit?: number
+}
+
+/** The retrieval rule, shared by every store: same domain, same evaluator, strictly earlier. */
+export function selectLearningExperience(
+	entries: readonly LearningExperienceEntry[],
+	query: LearningExperienceQuery,
+): LearningExperienceEntry[] {
+	const limit = Math.max(1, Math.min(query.limit ?? 20, 200))
+	return entries
+		.filter(
+			(entry) =>
+				entry.domain === query.domain &&
+				entry.evaluatorRevision === query.evaluatorRevision &&
+				entry.ordinal < query.beforeOrdinal &&
+				(query.decision === undefined || entry.decision === query.decision),
+		)
+		.sort((a, b) => b.ordinal - a.ordinal)
+		.slice(0, limit)
+}