@namzu/sdk 38.2.1 → 39.0.0

package/dist/manager/resident/learning-cycle.js

@@ -0,0 +1,306 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { normalizeHarnessProtection, } from '../../eval/harness-protection.js';
+import { reviewHarnessCandidate, } from '../../eval/harness-verification.js';
+import { hashResidentSkill, normalizeResidentSkill, promoteResidentSkill, residentLearningEvidenceSchema, } from './learning.js';
+import { ResidentConflictError } from './store.js';
+const receiptSchema = z.object({
+    runId: z.string().uuid(),
+    tokens: z.number().int().nonnegative().safe().nullable(),
+    costUsd: z.number().nonnegative().finite().nullable(),
+});
+/**
+ * @experimental Generate one candidate, independently verify and confirm it, then
+ * activate through the existing exact-revision transaction. No internal inference
+ * loop, retry or model-generated success claim replaces the host's evaluator.
+ */
+export async function runResidentLearningCycle(options) {
+    const protection = normalizeHarnessProtection(options.protection);
+    const purpose = z.enum(['task', 'exploration']).parse(options.purpose ?? 'task');
+    const purposeContext = options.purpose === undefined ? {} : { purpose };
+    const skillName = z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9_-]{0,63}$/)
+        .parse(options.skillName);
+    const failure = Object.freeze({
+        evidence: Object.freeze(residentLearningEvidenceSchema.parse(options.failure.evidence)),
+        trace: z.string().trim().min(1).max(32_000).parse(options.failure.trace),
+    });
+    const resources = z
+        .object({ unit: z.enum(['tokens', 'usd']), maxUnits: z.number().positive().finite() })
+        .parse(options.resources);
+    const parentCycleId = options.parentCycleId === undefined ? undefined : z.string().uuid().parse(options.parentCycleId);
+    const cycleId = randomUUID();
+    const receipts = new Map();
+    let sequence = 0;
+    let pending = Promise.resolve();
+    let auditComplete = true;
+    let unfinishedStages = 0;
+    let candidate;
+    let candidateRevision;
+    let baselineRevision;
+    let review;
+    let activatedRevision;
+    let activationRequested = false;
+    const usage = () => ({
+        tokens: [...receipts.values()].reduce((n, r) => n + (r.tokens ?? 0), 0),
+        costUsd: [...receipts.values()].reduce((n, r) => n + (r.costUsd ?? 0), 0),
+        receipts: receipts.size,
+        unknownTokens: [...receipts.values()].filter((r) => r.tokens === null).length,
+        unknownCosts: [...receipts.values()].filter((r) => r.costUsd === null).length,
+        unfinishedStages,
+    });
+    const append = (kind, data, stage) => {
+        const event = Object.freeze({
+            cycleId,
+            sequence: ++sequence,
+            kind,
+            ...(stage ? { stage } : {}),
+            data: structuredClone(data),
+        });
+        pending = pending
+            .then(() => options.record(event))
+            .catch((error) => {
+            auditComplete = false;
+            throw error;
+        });
+        return pending;
+    };
+    const result = (status, reason) => ({
+        cycleId,
+        status,
+        reason,
+        ...(candidate ? { candidate, candidateRevision } : {}),
+        ...(baselineRevision ? { baselineRevision } : {}),
+        ...(review ? { review } : {}),
+        ...(activatedRevision !== undefined ? { agendaRevision: activatedRevision } : {}),
+        consumption: usage(),
+        auditComplete,
+    });
+    const resourceProblem = (needsWork = false) => {
+        const measured = usage();
+        if (unfinishedStages ||
+            (resources.unit === 'tokens' ? measured.unknownTokens : measured.unknownCosts))
+            return `Incomplete ${resources.unit} evidence prevents further learning stages or activation.`;
+        if ((resources.unit === 'tokens' ? measured.tokens : measured.costUsd) > resources.maxUnits)
+            return 'Recorded experiment consumption exceeds the declared resource allowance.';
+        if (needsWork &&
+            (resources.unit === 'tokens' ? measured.tokens : measured.costUsd) === resources.maxUnits)
+            return 'The recorded resource allowance is exhausted before the next stage.';
+        return null;
+    };
+    const execute = async () => {
+        options.signal.throwIfAborted();
+        const snapshot = structuredClone(await options.agenda.read());
+        if (!snapshot)
+            throw new Error('No resident agenda exists for this learning cycle.');
+        if (snapshot.paused || snapshot.pursuits.some((p) => p.state.phase === 'running'))
+            throw new Error('Resident learning requires an unpaused agenda without running pursuits.');
+        const current = snapshot.learning?.skills.find((s) => s.name === skillName);
+        if (current && (current.purpose ?? 'task') !== purpose)
+            throw new Error('The active skill has a different learning purpose; use a distinct skill name.');
+        const baseline = current ? normalizeResidentSkill(current) : null;
+        baselineRevision = baseline ? hashResidentSkill(baseline) : 'none';
+        await append('started', {
+            tenantId: snapshot.tenantId,
+            agentKey: snapshot.agentKey,
+            agendaRevision: snapshot.revision,
+            baselineRevision,
+            skillName,
+            ...purposeContext,
+            failure,
+            resources,
+            protection,
+            ...(options.explore ? { explorationEnabled: true } : {}),
+            ...(parentCycleId ? { parentCycleId } : {}),
+        });
+        const check = async () => {
+            options.signal.throwIfAborted();
+            const latest = await options.agenda.read();
+            options.signal.throwIfAborted();
+            if (!latest ||
+                latest.tenantId !== snapshot.tenantId ||
+                latest.agentKey !== snapshot.agentKey ||
+                latest.revision !== snapshot.revision)
+                throw new ResidentConflictError();
+        };
+        const stage = async (name, callback) => {
+            await check();
+            await append('stage-started', {}, name);
+            await check();
+            unfinishedStages++;
+            let open = true;
+            let receiptFailure;
+            const before = receipts.size;
+            try {
+                const measured = usage();
+                const context = Object.freeze({
+                    cycleId,
+                    stage: name,
+                    signal: options.signal,
+                    remainingUnits: Math.max(0, resources.maxUnits - (resources.unit === 'tokens' ? measured.tokens : measured.costUsd)),
+                    recordUsage: async (input) => {
+                        try {
+                            if (!open)
+                                throw new Error('A closed learning stage cannot record new usage.');
+                            const receipt = Object.freeze(receiptSchema.parse(input));
+                            const id = receipt.runId.toLowerCase();
+                            if (receipts.has(id))
+                                throw new Error('Duplicate learning execution receipt.');
+                            if (receipts.size >= 1024)
+                                throw new Error('Learning cycle receipt bound exceeded.');
+                            const totals = usage();
+                            if (!Number.isSafeInteger(totals.tokens + (receipt.tokens ?? 0)) ||
+                                !Number.isFinite(totals.costUsd + (receipt.costUsd ?? 0)))
+                                throw new Error('Learning cycle consumption overflow.');
+                            receipts.set(id, receipt);
+                            await append('usage', { receipt }, name);
+                        }
+                        catch (error) {
+                            receiptFailure = error;
+                            throw error;
+                        }
+                    },
+                });
+                const value = await callback(context);
+                open = false;
+                await pending;
+                if (receiptFailure)
+                    throw receiptFailure;
+                options.signal.throwIfAborted();
+                if (value.usageComplete === true && receipts.size > before)
+                    unfinishedStages--;
+                await append('stage-finished', {
+                    usageComplete: value.usageComplete === true && receipts.size > before,
+                    consumption: usage(),
+                }, name);
+                return value;
+            }
+            finally {
+                open = false;
+            }
+        };
+        let exploration;
+        if (options.explore) {
+            const explore = options.explore;
+            const observed = await stage('explore', (context) => explore(Object.freeze({ ...context, skillName, ...purposeContext, failure, baseline })));
+            exploration = Object.freeze({
+                evidence: Object.freeze(residentLearningEvidenceSchema.parse(observed.observations.evidence)),
+                trace: z.string().trim().min(1).max(32_000).parse(observed.observations.trace),
+            });
+            await append('exploration', {
+                observations: exploration,
+                digest: createHash('sha256').update(JSON.stringify(exploration)).digest('hex'),
+            }, 'explore');
+            const problem = resourceProblem(true);
+            if (problem)
+                return result('inconclusive', problem);
+        }
+        const generated = await stage('generate', (context) => options.generate(Object.freeze({
+            ...context,
+            skillName,
+            ...purposeContext,
+            failure,
+            baseline,
+            ...(exploration ? { exploration } : {}),
+        })));
+        candidateRevision = hashResidentSkill(generated.candidate);
+        candidate = normalizeResidentSkill(generated.candidate);
+        if ((candidate.purpose ?? 'task') !== purpose)
+            throw new Error('Generated skill purpose does not match the host-admitted learning purpose.');
+        if (candidate.name !== skillName)
+            throw new Error('Generated guidance must retain the requested skill name.');
+        await append('candidate', { candidate, candidateRevision, baselineRevision });
+        if (candidateRevision === baselineRevision)
+            return result('rejected', 'Generated guidance is identical to the active baseline.');
+        let problem = resourceProblem(true);
+        if (problem)
+            return result('inconclusive', problem);
+        const evaluate = async (name) => {
+            const measured = await stage(name, (context) => options.evaluate(Object.freeze({
+                ...context,
+                baseline,
+                candidate: candidate,
+                baselineRevision: baselineRevision,
+                candidateRevision: candidateRevision,
+            })));
+            const batch = structuredClone(measured.batch);
+            if (batch.baselineRevision !== baselineRevision ||
+                batch.candidateRevision !== candidateRevision)
+                throw new Error('Evaluation does not identify the admitted baseline and candidate.');
+            if (batch.baseline.length > 128 ||
+                batch.candidate.length > 128 ||
+                batch.attributions.length > 128)
+                throw new Error('A learning evaluation is bounded to 64 paired tasks.');
+            await append('evaluation', {
+                baselineRevision,
+                candidateRevision,
+                digest: createHash('sha256').update(JSON.stringify(batch)).digest('hex'),
+                baselineTrajectories: batch.baseline.map((t) => t.trajectoryId),
+                candidateTrajectories: batch.candidate.map((t) => t.trajectoryId),
+            }, name);
+            return batch;
+        };
+        const verification = await evaluate('verification');
+        review = reviewHarnessCandidate(verification, undefined, protection);
+        problem = resourceProblem(true);
+        if (problem)
+            return result('inconclusive', problem);
+        if (review.decision === 'reject')
+            return result('rejected', review.reason);
+        if (review.protection?.verification.status !== 'passed' ||
+            review.verification.unresolved.length ||
+            review.verification.tasks.length < 5 ||
+            review.verification.tasks.some((t) => t.trials !== 2))
+            return result('inconclusive', review.reason);
+        const confirmation = await evaluate('confirmation');
+        review = reviewHarnessCandidate(verification, confirmation, protection);
+        problem = resourceProblem();
+        if (problem)
+            return result('inconclusive', problem);
+        if (review.decision !== 'accept')
+            return result(review.decision === 'reject' ? 'rejected' : 'inconclusive', review.reason);
+        await check();
+        const evidence = {
+            key: cycleId,
+            source: `resident-learning-cycle:${cycleId}`,
+            reason: `Paired verification and fresh confirmation of guidance derived from evidence ${failure.evidence.key}.`,
+        };
+        // Validate all existing activation contracts before entering the ambiguous
+        // commit interval. The store repeats this against its atomic snapshot.
+        promoteResidentSkill(snapshot.learning, candidate, { verification, confirmation, protection }, evidence);
+        await append('activation-requested', {
+            baselineRevision,
+            candidateRevision,
+            agendaRevision: snapshot.revision,
+        });
+        options.signal.throwIfAborted();
+        activationRequested = true;
+        const updated = await options.agenda.promoteSkill(snapshot, candidate, { verification, confirmation, protection }, evidence);
+        activatedRevision = updated.revision;
+        return result('activated', 'Evaluated guidance was committed for subsequent admissions.');
+    };
+    let outcome;
+    try {
+        outcome = await execute();
+    }
+    catch (error) {
+        outcome = result(error instanceof ResidentConflictError
+            ? 'conflict'
+            : activationRequested
+                ? 'activation-unknown'
+                : options.signal.aborted
+                    ? 'cancelled'
+                    : 'failed', error instanceof Error ? error.message : String(error));
+    }
+    if (auditComplete) {
+        try {
+            await append('finished', { result: outcome });
+        }
+        catch {
+            /* A committed activation is not undone by a journal failure. */
+        }
+    }
+    return { ...outcome, auditComplete };
+}
+//# sourceMappingURL=learning-cycle.js.map

package/dist/manager/resident/learning-cycle.js.map

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

package/dist/manager/resident/learning-observation.d.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+export declare const learningTargetSchema: z.ZodObject<{
+    skillName: z.ZodString;
+    evaluatorRevision: z.ZodString;
+    baselineRevision: z.ZodUnion<[z.ZodLiteral<"none">, z.ZodString]>;
+}, "strip", z.ZodTypeAny, {
+    baselineRevision: string;
+    skillName: string;
+    evaluatorRevision: string;
+}, {
+    baselineRevision: string;
+    skillName: string;
+    evaluatorRevision: string;
+}>;
+export declare const learningObservationSchema: z.ZodObject<{
+    skillName: z.ZodString;
+    evaluatorRevision: z.ZodString;
+    baselineRevision: z.ZodUnion<[z.ZodLiteral<"none">, z.ZodString]>;
+} & {
+    runId: z.ZodEffects<z.ZodString, string, string>;
+    /** Stable task identity, including input/source revision; retries keep the same key. */
+    taskKey: z.ZodString;
+    outcome: z.ZodEnum<["passed", "failed", "execution-error", "unresolved"]>;
+    /** Host verified all execution receipts have settled. This is not a model assertion. */
+    usageComplete: z.ZodBoolean;
+    evidence: z.ZodObject<{
+        key: z.ZodString;
+        source: z.ZodString;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        key: string;
+        reason: string;
+    }, {
+        source: string;
+        key: string;
+        reason: string;
+    }>;
+    trace: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    runId: string;
+    outcome: "failed" | "unresolved" | "passed" | "execution-error";
+    baselineRevision: string;
+    evidence: {
+        source: string;
+        key: string;
+        reason: string;
+    };
+    usageComplete: boolean;
+    trace: string;
+    skillName: string;
+    evaluatorRevision: string;
+    taskKey: string;
+}, {
+    runId: string;
+    outcome: "failed" | "unresolved" | "passed" | "execution-error";
+    baselineRevision: string;
+    evidence: {
+        source: string;
+        key: string;
+        reason: string;
+    };
+    usageComplete: boolean;
+    trace: string;
+    skillName: string;
+    evaluatorRevision: string;
+    taskKey: string;
+}>;
+/** @experimental Host-scored observation; failures need retained traces and a versioned evaluator. */
+export type ResidentLearningObservation = Readonly<Omit<z.infer<typeof learningObservationSchema>, 'evidence'>> & {
+    readonly evidence: Readonly<z.infer<typeof learningObservationSchema>['evidence']>;
+};
+/** @experimental Current evaluator and installed skill revision authorized for one experiment. */
+export type ResidentLearningTarget = Readonly<z.infer<typeof learningTargetSchema>>;
+/** @experimental Stable insertion order; a claimed cycle may have no live executor. */
+export interface ResidentLearningObservationRecord extends ResidentLearningObservation {
+    readonly ordinal: number;
+    readonly attemptedCycleId: string | null;
+}
+//# sourceMappingURL=learning-observation.d.ts.map

package/dist/manager/resident/learning-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-observation.d.ts","sourceRoot":"","sources":["../../../src/manager/resident/learning-observation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAI/B,CAAA;AAEF,eAAO,MAAM,yBAAyB;;;;;;IAKrC,wFAAwF;;;IAGxF,wFAAwF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAIvF,CAAA;AAEF,sGAAsG;AACtG,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CACjD,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,EAAE,UAAU,CAAC,CAC3D,GAAG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;CAClF,CAAA;AAED,kGAAkG;AAClG,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAA;AAEnF,uFAAuF;AACvF,MAAM,WAAW,iCAAkC,SAAQ,2BAA2B;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CACxC"}

package/dist/manager/resident/learning-observation.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { residentLearningEvidenceSchema } from './learning.js';
+const label = z.string().trim().min(1).max(256);
+export const learningTargetSchema = z.object({
+    skillName: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/),
+    evaluatorRevision: label,
+    baselineRevision: z.union([z.literal('none'), z.string().regex(/^[a-f0-9]{64}$/)]),
+});
+export const learningObservationSchema = learningTargetSchema.extend({
+    runId: z
+        .string()
+        .uuid()
+        .transform((id) => id.toLowerCase()),
+    /** Stable task identity, including input/source revision; retries keep the same key. */
+    taskKey: label,
+    outcome: z.enum(['passed', 'failed', 'execution-error', 'unresolved']),
+    /** Host verified all execution receipts have settled. This is not a model assertion. */
+    usageComplete: z.boolean(),
+    evidence: residentLearningEvidenceSchema,
+    trace: z.string().trim().min(1).max(32_000),
+});
+//# sourceMappingURL=learning-observation.js.map

package/dist/manager/resident/learning-observation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learning-observation.js","sourceRoot":"","sources":["../../../src/manager/resident/learning-observation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,8BAA8B,EAAE,MAAM,eAAe,CAAA;AAE9D,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAC/C,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,4BAA4B,CAAC;IACzD,iBAAiB,EAAE,KAAK;IACxB,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC;CAClF,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG,oBAAoB,CAAC,MAAM,CAAC;IACpE,KAAK,EAAE,CAAC;SACN,MAAM,EAAE;SACR,IAAI,EAAE;SACN,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,wFAAwF;IACxF,OAAO,EAAE,KAAK;IACd,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,EAAE,YAAY,CAAC,CAAC;IACtE,wFAAwF;IACxF,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE;IAC1B,QAAQ,EAAE,8BAA8B;IACxC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;CAC3C,CAAC,CAAA"}

package/dist/manager/resident/learning-store.d.ts

@@ -0,0 +1,106 @@
+import type { ProjectId, TenantId } from '../../types/ids/index.js';
+import { type ResidentLearningCycleEvent, type ResidentLearningCycleOptions, type ResidentLearningCycleResult } from './learning-cycle.js';
+import { type ResidentLearningObservation, type ResidentLearningObservationRecord, type ResidentLearningTarget } from './learning-observation.js';
+/** @experimental Private parent directories and backup policy remain host responsibilities. */
+export interface SqliteResidentLearningStoreOptions {
+    readonly databasePath: string;
+    readonly artifactsPath: string;
+    readonly scope: {
+        readonly tenantId: TenantId;
+        readonly projectId: ProjectId;
+        readonly agentKey: string;
+    };
+    readonly readOnly?: boolean;
+}
+/** @experimental A content-addressed immutable JSON artifact, scoped through its owning cycle. */
+export interface ResidentLearningArtifact {
+    readonly name: string;
+    readonly hash: string;
+    readonly bytes: number;
+}
+/** @experimental Recorded lower bounds; absence of a final result means completeness is unknown. */
+export interface ResidentLearningRecordedUsage {
+    readonly tokens: number;
+    readonly costUsd: number;
+    readonly receipts: number;
+    readonly unknownTokens: number;
+    readonly unknownCosts: number;
+}
+/** @experimental Running/pending records require inspection; neither implies a live executor. */
+export interface ResidentLearningCycleSummary {
+    readonly cycleId: string;
+    readonly ordinal: number;
+    readonly parentCycleId: string | null;
+    readonly skillName: string | null;
+    readonly status: ResidentLearningCycleResult['status'] | 'running' | 'activation-pending';
+    readonly sequence: number;
+    readonly startedAt: number;
+    readonly updatedAt: number;
+    readonly candidateRevision: string | null;
+    readonly result: ResidentLearningCycleResult | null;
+    readonly recordedUsage: ResidentLearningRecordedUsage;
+}
+/**
+ * @experimental Authoritative experiment journal and query index in one transaction.
+ * Large JSON artifacts are published completely before their SQLite references.
+ * No database transaction spans an await, model request or artifact write. JSONL
+ * exports are observations, never a second writable authority or a replay queue.
+ */
+export declare class SqliteResidentLearningStore {
+    readonly databasePath: string;
+    readonly artifactsPath: string;
+    private readonly scope;
+    private readonly readOnly;
+    constructor(options: SqliteResidentLearningStoreOptions);
+    private use;
+    private owned;
+    /** Immutable, idempotent observations. Regrading requires a different evaluator revision. */
+    observe(input: ResidentLearningObservation): Promise<void>;
+    private observationsQuery;
+    private observationRecord;
+    /** Ordered inspection; summaries are host observations, not inferred task completion. */
+    observations(options?: {
+        readonly after?: number;
+        readonly limit?: number;
+    }): Promise<readonly ResidentLearningObservationRecord[]>;
+    /** Oldest eligible unattempted task across current targets; no model call or claim is made. */
+    selectObservation(input: readonly ResidentLearningTarget[]): Promise<ResidentLearningObservationRecord | null>;
+    private claimObservation;
+    /** Identical event retries are idempotent. Different content at the same sequence is refused. */
+    append(input: ResidentLearningCycleEvent): Promise<void>;
+    get(cycleId: string): Promise<ResidentLearningCycleSummary | null>;
+    list(options?: {
+        readonly before?: number;
+        readonly limit?: number;
+    }): Promise<readonly ResidentLearningCycleSummary[]>;
+    events(cycleId: string, options?: {
+        readonly after?: number;
+        readonly limit?: number;
+    }): Promise<readonly ResidentLearningCycleEvent[]>;
+    artifacts(cycleId: string): Promise<readonly ResidentLearningArtifact[]>;
+    /** Complete immutable bytes precede the reference; an interrupted publication may leave an unreferenced blob. */
+    putArtifact(cycleId: string, name: string, value: unknown): Promise<ResidentLearningArtifact>;
+    readArtifact(cycleId: string, name: string): Promise<unknown>;
+}
+/** @experimental Supply normal host callbacks; the store retains journal events and full paired batches. */
+export declare function runStoredResidentLearningCycle(store: SqliteResidentLearningStore, options: Omit<ResidentLearningCycleOptions, 'record'>): Promise<ResidentLearningCycleResult>;
+/** @experimental Host authorizes evaluators; the SDK selects a retained failure against the active skill. */
+export interface ResidentLearningDiscoveryOptions extends Omit<ResidentLearningCycleOptions, 'record' | 'failure' | 'skillName'> {
+    readonly evaluators: readonly {
+        readonly skillName: string;
+        readonly evaluatorRevision: string;
+    }[];
+}
+/** @experimental Null cycle means no eligible work. A failed claimed cycle is never silently replayed. */
+export interface ResidentLearningDiscoveryResult {
+    readonly observation: ResidentLearningObservationRecord | null;
+    readonly cycle: ResidentLearningCycleResult | null;
+}
+/**
+ * @experimental Admit at most one experiment from host-scored observations.
+ * Selection is local FIFO fairness, not an estimated probability of improvement.
+ * Claim and start are one SQLite transaction; concurrent selectors cannot run
+ * the same task/evaluator/baseline twice, even after a crash or reopened process.
+ */
+export declare function runStoredResidentLearningFromObservations(store: SqliteResidentLearningStore, options: ResidentLearningDiscoveryOptions): Promise<ResidentLearningDiscoveryResult>;
+//# sourceMappingURL=learning-store.d.ts.map

package/dist/manager/resident/learning-store.d.ts.map

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