@namzu/sdk 54.0.0 → 55.1.0

package/dist/learning/experience-store.js

@@ -0,0 +1,143 @@
+import { mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+import { asProjectId, asTenantId } from '../utils/id.js';
+import { 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 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 {
+    databasePath;
+    scope;
+    readOnly;
+    constructor(options) {
+        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;
+    }
+    use(write, operation, whenEmpty) {
+        if (write && this.readOnly)
+            throw new Error('Learning experience database is read-only.');
+        let Database;
+        try {
+            Database = createRequire(import.meta.url)('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();
+        }
+    }
+    scopeArgs() {
+        return [this.scope.tenantId, this.scope.projectId, this.scope.agentKey];
+    }
+    decode(row) {
+        return {
+            ...JSON.parse(row.body),
+            ordinal: row.ordinal,
+        };
+    }
+    /** Record one finished cycle. Throws `LearningLeakError` when the entry carries evaluator-side material. */
+    async record(input) {
+        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);
+            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() {
+        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());
+            return (row.last ?? 0) + 1;
+        }, () => 1);
+    }
+    /** Entries of one domain and evaluator revision recorded before `beforeOrdinal`, newest first. */
+    async retrieve(query) {
+        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), () => []);
+        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;
+    }
+}
+//# sourceMappingURL=experience-store.js.map

package/dist/learning/experience-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experience-store.js","sourceRoot":"","sources":["../../src/learning/experience-store.ts"],"names":[],"mappings":"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"}

package/dist/learning/experience.d.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { type LearningLeakGuard } from './leak-tripwire.js';
+import { type LearningSkillCandidate, learningEvidenceSchema } from './skill.js';
+export declare const LEARNING_EDIT_VERDICTS: readonly ["helped", "hurt", "no observed effect", "confounded"];
+/** @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 declare const LEARNING_CONFIDENCE_LEVELS: readonly ["high", "medium", "low"];
+/** @experimental How far a lesson can be trusted. */
+export type LearningConfidence = (typeof LEARNING_CONFIDENCE_LEVELS)[number];
+declare const editSchema: z.ZodObject<{
+    /** The part of the harness the edit touched, such as `instruction-skill`. */
+    surface: z.ZodString;
+    /** What changed, in a sentence. */
+    change: z.ZodString;
+    verdict: z.ZodEnum<["helped", "hurt", "no observed effect", "confounded"]>;
+    /**
+     * 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.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    verdict: "helped" | "hurt" | "no observed effect" | "confounded";
+    change: string;
+    surface: string;
+    isolated?: boolean | undefined;
+}, {
+    verdict: "helped" | "hurt" | "no observed effect" | "confounded";
+    change: string;
+    surface: string;
+    isolated?: boolean | undefined;
+}>;
+declare const lessonSchema: z.ZodObject<{
+    /** The shape of the situation the lesson applies to, not the incident itself. */
+    cue: z.ZodString;
+    lesson: z.ZodString;
+    /** References into the observations, session log or verification receipts. */
+    evidence: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        source: z.ZodString;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        reason: string;
+        source: string;
+    }, {
+        key: string;
+        reason: string;
+        source: string;
+    }>, "many">;
+    confidence: z.ZodEnum<["high", "medium", "low"]>;
+    confidenceReason: z.ZodString;
+    /** Indexes into the entry's edits that the lesson rests on. */
+    edits: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+}, "strip", z.ZodTypeAny, {
+    confidence: "low" | "medium" | "high";
+    evidence: {
+        key: string;
+        reason: string;
+        source: string;
+    }[];
+    cue: string;
+    lesson: string;
+    confidenceReason: string;
+    edits?: number[] | undefined;
+}, {
+    confidence: "low" | "medium" | "high";
+    evidence: {
+        key: string;
+        reason: string;
+        source: string;
+    }[];
+    cue: string;
+    lesson: string;
+    confidenceReason: string;
+    edits?: number[] | undefined;
+}>;
+/** @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;
+}
+/** @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[];
+}
+/**
+ * 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 declare function normalizeLearningExperience(input: LearningExperienceInput): Omit<LearningExperienceEntry, 'ordinal'>;
+/**
+ * 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 declare function assertExperienceHasNoLeak(entry: Omit<LearningExperienceEntry, 'ordinal'>, guard: LearningLeakGuard | undefined): void;
+/** @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 declare function selectLearningExperience(entries: readonly LearningExperienceEntry[], query: LearningExperienceQuery): LearningExperienceEntry[];
+export {};
+//# sourceMappingURL=experience.d.ts.map

package/dist/learning/experience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experience.d.ts","sourceRoot":"","sources":["../../src/learning/experience.ts"],"names":[],"mappings":"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"}

package/dist/learning/experience.js

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import { assertNoLearningLeak } from './leak-tripwire.js';
+import { 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',
+];
+export const LEARNING_CONFIDENCE_LEVELS = ['high', 'medium', 'low'];
+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(),
+});
+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(),
+});
+const CAP = { low: 0, medium: 1, high: 2 };
+const BY_RANK = ['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) {
+    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 = parsed.edits.map((edit) => {
+        const { isolated, ...row } = edit;
+        if (several && isolated !== true)
+            return { ...row, verdict: 'confounded' };
+        return isolated === true ? { ...row, isolated } : row;
+    });
+    const lessons = (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]],
+            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, subject, out) {
+    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, guard) {
+    const subjects = [];
+    const texts = [];
+    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);
+}
+/** The retrieval rule, shared by every store: same domain, same evaluator, strictly earlier. */
+export function selectLearningExperience(entries, query) {
+    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);
+}
+//# sourceMappingURL=experience.js.map

package/dist/learning/experience.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experience.js","sourceRoot":"","sources":["../../src/learning/experience.ts"],"names":[],"mappings":"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"}

package/dist/learning/generator.d.ts

@@ -0,0 +1,118 @@
+import type { LearningCycleResult } from './cycle.js';
+import type { LearningReceipt } from './cycle.js';
+import type { LearningExperienceEntry, LearningExperienceInput } from './experience.js';
+import { type LearningLeakGuard } from './leak-tripwire.js';
+import type { LearningObservationRecord } from './observation.js';
+import { type LearningSkillCandidate } from './skill.js';
+/**
+ * The built-in generator, first version: one step, one surface. It reads what
+ * conversations kept and what earlier cycles learned in the same domain, asks a
+ * model for one revision of an instruction skill, and checks the answer against
+ * the editable surface before anything else sees it. It never judges its own
+ * work: the candidate goes to the learning cycle's paired verification.
+ */
+/** The parts of the harness a candidate may edit. Only instruction text today. */
+export declare const LEARNING_SURFACE_KINDS: readonly ["instruction-skill"];
+/** @experimental A part of the harness a generator may edit. */
+export type LearningSurfaceKind = (typeof LEARNING_SURFACE_KINDS)[number];
+/**
+ * The safety floor. These are never editable by a learning cycle, whatever a
+ * configuration says: a candidate cannot be admitted that changes how
+ * permissions are reviewed, which paths are protected, which command patterns
+ * are always refused, or the learning code itself.
+ */
+export declare const LEARNING_FLOOR_COMPONENTS: readonly ["permission-review", "protected-paths", "dangerous-patterns", "learning-code"];
+/** @experimental The allowlist of what a generator may propose to change. */
+export interface LearningSurface {
+    readonly kinds: readonly LearningSurfaceKind[];
+}
+/**
+ * Validate a surface configuration. Unknown kinds and every safety-floor
+ * component are refused, so a misconfiguration fails loudly instead of widening
+ * what a generator may touch. Omitted means the default surface.
+ */
+export declare function resolveLearningSurface(config?: {
+    readonly kinds?: readonly string[];
+}): LearningSurface;
+/** One call to the model the host configured. */
+export interface LearningModelRequest {
+    readonly system: string;
+    readonly prompt: string;
+    readonly maxTokens: number;
+    readonly signal: AbortSignal;
+}
+/** What the model said and what it cost. A null count means the host could not measure it. */
+export interface LearningModelReply {
+    readonly text: string;
+    readonly tokens: number | null;
+    readonly costUsd: number | null;
+}
+/** @experimental The model seam. The host chooses the model and counts the spend. */
+export type LearningModel = (request: LearningModelRequest) => Promise<LearningModelReply>;
+/** One change a proposal makes, as the typed edit ledger records it. */
+export interface LearningProposedEdit {
+    readonly surface: LearningSurfaceKind;
+    readonly change: string;
+}
+export interface LearningProposeOptions {
+    /** The skill this proposal revises; the candidate keeps exactly this name. */
+    readonly skillName: string;
+    /** The active revision, or null when none exists. */
+    readonly baseline: LearningSkillCandidate | null;
+    /** The domain's observations, newest last. Only fixed-wording records, never copied text. */
+    readonly observations: readonly LearningObservationRecord[];
+    /** Earlier cycles of the same domain and evaluator, already retrieved. */
+    readonly experience?: readonly LearningExperienceEntry[];
+    readonly surface?: LearningSurface;
+    /** Evaluator-side material to keep out of the prompt and out of the candidate. */
+    readonly leakGuard: LearningLeakGuard;
+    readonly model: LearningModel;
+    readonly signal: AbortSignal;
+    /** Called once per model call so the cycle can count the spend. */
+    readonly recordUsage?: (receipt: LearningReceipt) => Promise<void>;
+    /** The session the receipts belong to. */
+    readonly sessionId?: string;
+    /** Per call output bound; default 1,500 tokens. */
+    readonly maxTokens?: number;
+}
+/** @experimental The result of one proposal. */
+export type LearningProposal = {
+    readonly status: 'proposed';
+    readonly candidate: LearningSkillCandidate;
+    readonly edits: readonly LearningProposedEdit[];
+    readonly attempts: number;
+    /** Every model call reported a token count. */
+    readonly usageComplete: boolean;
+} | {
+    readonly status: 'refused';
+    readonly reason: string;
+    /** What the last answer tried to touch outside the surface, by name; never its text. */
+    readonly offSurface: readonly string[];
+    readonly attempts: number;
+    readonly usageComplete: boolean;
+};
+/**
+ * Ask the model for one revision of the skill and admit it only when every
+ * edit sits on the surface and the text stays clear of the safety floor. A
+ * problem is reported back to the model once with the part that failed; a
+ * second failure refuses the proposal. The model is never asked to judge its
+ * own result.
+ */
+export declare function proposeLearningCandidate(options: LearningProposeOptions): Promise<LearningProposal>;
+/**
+ * The experience entry a finished cycle leaves behind. An activated cycle is
+ * `adopted` and its edit `helped`; a rejected one is `rejected`, `hurt` when
+ * the review found a regression and `no observed effect` otherwise. A cycle
+ * that did not reach a verdict (inconclusive, failed, cancelled) leaves
+ * nothing, because there is nothing true to record about its edits.
+ */
+export declare function learningExperienceFromCycle(input: {
+    readonly domain: string;
+    readonly evaluatorRevision: string;
+    readonly proposal: Extract<LearningProposal, {
+        status: 'proposed';
+    }>;
+    readonly result: LearningCycleResult;
+    readonly leakGuard: LearningLeakGuard;
+}): LearningExperienceInput | null;
+//# sourceMappingURL=generator.d.ts.map

package/dist/learning/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/learning/generator.ts"],"names":[],"mappings":"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"}