@namzu/sdk 38.1.0 → 39.0.0

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

@@ -0,0 +1,726 @@
+import { z } from 'zod';
+import { type HarnessProtectionPlan } from '../../eval/harness-protection.js';
+import { type HarnessVerificationBatch } from '../../eval/harness-verification.js';
+export declare const residentLearningEvidenceSchema: 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;
+}>;
+/** @experimental Host provenance for a correction, evaluated activation or rollback. */
+export type ResidentLearningEvidence = Readonly<z.infer<typeof residentLearningEvidenceSchema>>;
+declare const sourceSchema: z.ZodObject<{
+    key: z.ZodString;
+    revision: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    revision: string;
+}, {
+    key: string;
+    revision: string;
+}>;
+/** @experimental Host-owned source identity and revision; neither is a model assertion. */
+export type ResidentLearningSource = Readonly<z.infer<typeof sourceSchema>>;
+declare const candidateSchema: z.ZodObject<{
+    name: z.ZodString;
+    /** Omitted means ordinary task guidance; exploration policies require explicit projection. */
+    purpose: z.ZodOptional<z.ZodEnum<["task", "exploration"]>>;
+    description: z.ZodString;
+    body: z.ZodString;
+    /** Optional dependencies whose revisions must still match before projection. */
+    sources: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        revision: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        revision: string;
+    }, {
+        key: string;
+        revision: string;
+    }>, "many">, {
+        key: string;
+        revision: string;
+    }[], {
+        key: string;
+        revision: string;
+    }[]>, {
+        key: string;
+        revision: string;
+    }[], {
+        key: string;
+        revision: string;
+    }[]>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    body: string;
+    sources?: {
+        key: string;
+        revision: string;
+    }[] | undefined;
+    purpose?: "task" | "exploration" | undefined;
+}, {
+    name: string;
+    description: string;
+    body: string;
+    sources?: {
+        key: string;
+        revision: string;
+    }[] | undefined;
+    purpose?: "task" | "exploration" | undefined;
+}>;
+/** @experimental Instructional guidance only; never executable assets or tool permissions. */
+export type ResidentSkillCandidate = Readonly<Omit<z.infer<typeof candidateSchema>, 'sources'>> & {
+    readonly sources?: readonly ResidentLearningSource[];
+};
+/** Internal canonical snapshot, including immutable source bindings. */
+export declare function normalizeResidentSkill(input: ResidentSkillCandidate): ResidentSkillCandidate;
+declare const learnedSkillSchema: z.ZodObject<{
+    name: z.ZodString;
+    /** Omitted means ordinary task guidance; exploration policies require explicit projection. */
+    purpose: z.ZodOptional<z.ZodEnum<["task", "exploration"]>>;
+    description: z.ZodString;
+    body: z.ZodString;
+    /** Optional dependencies whose revisions must still match before projection. */
+    sources: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        revision: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        revision: string;
+    }, {
+        key: string;
+        revision: string;
+    }>, "many">, {
+        key: string;
+        revision: string;
+    }[], {
+        key: string;
+        revision: string;
+    }[]>, {
+        key: string;
+        revision: string;
+    }[], {
+        key: string;
+        revision: string;
+    }[]>>;
+} & {
+    hash: z.ZodString;
+    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;
+    }>;
+    verification: z.ZodObject<{
+        baselineHash: z.ZodUnion<[z.ZodString, z.ZodLiteral<"none">]>;
+        candidateHash: z.ZodString;
+        evidenceDigest: z.ZodString;
+        verificationTasks: z.ZodNumber;
+        confirmationTasks: z.ZodNumber;
+        /** Absent only on historical activations made before protection was required. */
+        protection: z.ZodOptional<z.ZodObject<{
+            verificationTasks: z.ZodNumber;
+            confirmationTasks: z.ZodNumber;
+            planDigest: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            verificationTasks: number;
+            confirmationTasks: number;
+            planDigest: string;
+        }, {
+            verificationTasks: number;
+            confirmationTasks: number;
+            planDigest: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        baselineHash: string;
+        candidateHash: string;
+        evidenceDigest: string;
+        verificationTasks: number;
+        confirmationTasks: number;
+        protection?: {
+            verificationTasks: number;
+            confirmationTasks: number;
+            planDigest: string;
+        } | undefined;
+    }, {
+        baselineHash: string;
+        candidateHash: string;
+        evidenceDigest: string;
+        verificationTasks: number;
+        confirmationTasks: number;
+        protection?: {
+            verificationTasks: number;
+            confirmationTasks: number;
+            planDigest: string;
+        } | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    verification: {
+        baselineHash: string;
+        candidateHash: string;
+        evidenceDigest: string;
+        verificationTasks: number;
+        confirmationTasks: number;
+        protection?: {
+            verificationTasks: number;
+            confirmationTasks: number;
+            planDigest: string;
+        } | undefined;
+    };
+    body: string;
+    hash: string;
+    evidence: {
+        source: string;
+        key: string;
+        reason: string;
+    };
+    sources?: {
+        key: string;
+        revision: string;
+    }[] | undefined;
+    purpose?: "task" | "exploration" | undefined;
+}, {
+    name: string;
+    description: string;
+    verification: {
+        baselineHash: string;
+        candidateHash: string;
+        evidenceDigest: string;
+        verificationTasks: number;
+        confirmationTasks: number;
+        protection?: {
+            verificationTasks: number;
+            confirmationTasks: number;
+            planDigest: string;
+        } | undefined;
+    };
+    body: string;
+    hash: string;
+    evidence: {
+        source: string;
+        key: string;
+        reason: string;
+    };
+    sources?: {
+        key: string;
+        revision: string;
+    }[] | undefined;
+    purpose?: "task" | "exploration" | undefined;
+}>;
+/** @experimental Immutable evaluated content and evidence identity. */
+export type ResidentLearnedSkill = Readonly<Omit<z.infer<typeof learnedSkillSchema>, 'sources'>> & {
+    readonly sources?: readonly ResidentLearningSource[];
+};
+export declare const residentLearningSchema: z.ZodEffects<z.ZodObject<{
+    revision: z.ZodNumber;
+    identity: z.ZodOptional<z.ZodObject<{
+        text: z.ZodString;
+        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;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        text: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    }, {
+        text: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    }>>;
+    preferences: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        value: z.ZodString;
+        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;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        key: string;
+        value: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    }, {
+        key: string;
+        value: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    }>, "many">;
+    skills: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        /** Omitted means ordinary task guidance; exploration policies require explicit projection. */
+        purpose: z.ZodOptional<z.ZodEnum<["task", "exploration"]>>;
+        description: z.ZodString;
+        body: z.ZodString;
+        /** Optional dependencies whose revisions must still match before projection. */
+        sources: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            revision: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            key: string;
+            revision: string;
+        }, {
+            key: string;
+            revision: string;
+        }>, "many">, {
+            key: string;
+            revision: string;
+        }[], {
+            key: string;
+            revision: string;
+        }[]>, {
+            key: string;
+            revision: string;
+        }[], {
+            key: string;
+            revision: string;
+        }[]>>;
+    } & {
+        hash: z.ZodString;
+        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;
+        }>;
+        verification: z.ZodObject<{
+            baselineHash: z.ZodUnion<[z.ZodString, z.ZodLiteral<"none">]>;
+            candidateHash: z.ZodString;
+            evidenceDigest: z.ZodString;
+            verificationTasks: z.ZodNumber;
+            confirmationTasks: z.ZodNumber;
+            /** Absent only on historical activations made before protection was required. */
+            protection: z.ZodOptional<z.ZodObject<{
+                verificationTasks: z.ZodNumber;
+                confirmationTasks: z.ZodNumber;
+                planDigest: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            }, {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            }>>;
+        }, "strip", z.ZodTypeAny, {
+            baselineHash: string;
+            candidateHash: string;
+            evidenceDigest: string;
+            verificationTasks: number;
+            confirmationTasks: number;
+            protection?: {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            } | undefined;
+        }, {
+            baselineHash: string;
+            candidateHash: string;
+            evidenceDigest: string;
+            verificationTasks: number;
+            confirmationTasks: number;
+            protection?: {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            } | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        verification: {
+            baselineHash: string;
+            candidateHash: string;
+            evidenceDigest: string;
+            verificationTasks: number;
+            confirmationTasks: number;
+            protection?: {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            } | undefined;
+        };
+        body: string;
+        hash: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+        sources?: {
+            key: string;
+            revision: string;
+        }[] | undefined;
+        purpose?: "task" | "exploration" | undefined;
+    }, {
+        name: string;
+        description: string;
+        verification: {
+            baselineHash: string;
+            candidateHash: string;
+            evidenceDigest: string;
+            verificationTasks: number;
+            confirmationTasks: number;
+            protection?: {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            } | undefined;
+        };
+        body: string;
+        hash: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+        sources?: {
+            key: string;
+            revision: string;
+        }[] | undefined;
+        purpose?: "task" | "exploration" | undefined;
+    }>, "many">;
+    lastChange: 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;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    skills: {
+        name: string;
+        description: string;
+        verification: {
+            baselineHash: string;
+            candidateHash: string;
+            evidenceDigest: string;
+            verificationTasks: number;
+            confirmationTasks: number;
+            protection?: {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            } | undefined;
+        };
+        body: string;
+        hash: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+        sources?: {
+            key: string;
+            revision: string;
+        }[] | undefined;
+        purpose?: "task" | "exploration" | undefined;
+    }[];
+    revision: number;
+    preferences: {
+        key: string;
+        value: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    }[];
+    lastChange: {
+        source: string;
+        key: string;
+        reason: string;
+    };
+    identity?: {
+        text: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    } | undefined;
+}, {
+    skills: {
+        name: string;
+        description: string;
+        verification: {
+            baselineHash: string;
+            candidateHash: string;
+            evidenceDigest: string;
+            verificationTasks: number;
+            confirmationTasks: number;
+            protection?: {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            } | undefined;
+        };
+        body: string;
+        hash: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+        sources?: {
+            key: string;
+            revision: string;
+        }[] | undefined;
+        purpose?: "task" | "exploration" | undefined;
+    }[];
+    revision: number;
+    preferences: {
+        key: string;
+        value: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    }[];
+    lastChange: {
+        source: string;
+        key: string;
+        reason: string;
+    };
+    identity?: {
+        text: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    } | undefined;
+}>, {
+    skills: {
+        name: string;
+        description: string;
+        verification: {
+            baselineHash: string;
+            candidateHash: string;
+            evidenceDigest: string;
+            verificationTasks: number;
+            confirmationTasks: number;
+            protection?: {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            } | undefined;
+        };
+        body: string;
+        hash: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+        sources?: {
+            key: string;
+            revision: string;
+        }[] | undefined;
+        purpose?: "task" | "exploration" | undefined;
+    }[];
+    revision: number;
+    preferences: {
+        key: string;
+        value: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    }[];
+    lastChange: {
+        source: string;
+        key: string;
+        reason: string;
+    };
+    identity?: {
+        text: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    } | undefined;
+}, {
+    skills: {
+        name: string;
+        description: string;
+        verification: {
+            baselineHash: string;
+            candidateHash: string;
+            evidenceDigest: string;
+            verificationTasks: number;
+            confirmationTasks: number;
+            protection?: {
+                verificationTasks: number;
+                confirmationTasks: number;
+                planDigest: string;
+            } | undefined;
+        };
+        body: string;
+        hash: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+        sources?: {
+            key: string;
+            revision: string;
+        }[] | undefined;
+        purpose?: "task" | "exploration" | undefined;
+    }[];
+    revision: number;
+    preferences: {
+        key: string;
+        value: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    }[];
+    lastChange: {
+        source: string;
+        key: string;
+        reason: string;
+    };
+    identity?: {
+        text: string;
+        evidence: {
+            source: string;
+            key: string;
+            reason: string;
+        };
+    } | undefined;
+}>;
+/** @experimental Versioned behavioral overlay; the original resident mandate remains unchanged. */
+export interface ResidentLearningState {
+    readonly revision: number;
+    readonly identity?: {
+        readonly text: string;
+        readonly evidence: ResidentLearningEvidence;
+    };
+    readonly preferences: readonly {
+        readonly key: string;
+        readonly value: string;
+        readonly evidence: ResidentLearningEvidence;
+    }[];
+    readonly skills: readonly ResidentLearnedSkill[];
+    readonly lastChange: ResidentLearningEvidence;
+}
+/** @experimental Corrections name the current preference evidence they supersede. */
+export interface ResidentProfileUpdate {
+    readonly identity?: string;
+    readonly preferences?: readonly {
+        readonly key: string;
+        readonly value: string;
+        readonly supersedes: string | null;
+    }[];
+    readonly evidence: ResidentLearningEvidence;
+}
+/** @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;
+}
+/** Internal immutable snapshot used by storage and admitted context. */
+export declare function freezeResidentLearning(input: ResidentLearningState): ResidentLearningState;
+/** Internal pure profile transition; storage owns exact agenda CAS and idle admission. */
+export declare function reviseResidentProfile(current: ResidentLearningState | undefined, input: ResidentProfileUpdate): ResidentLearningState;
+/** @experimental Bind evaluation to normalized content and any declared source dependencies. */
+export declare function hashResidentSkill(input: ResidentSkillCandidate): string;
+/** Internal pure activation; reuse the kernel's conservative two-round verification gate. */
+export declare function promoteResidentSkill(current: ResidentLearningState | undefined, input: ResidentSkillCandidate, evaluation: ResidentSkillEvaluation, inputEvidence: ResidentLearningEvidence): ResidentLearningState;
+/** Internal rollback appends a new learning version while preserving current profile values. */
+export declare function restoreResidentSkill(current: ResidentLearningState | undefined, historical: ResidentLearningState | undefined, skillName: string, inputEvidence: ResidentLearningEvidence): ResidentLearningState;
+/** @experimental Exact skill selection and a character cap, independent of provider token budgets. */
+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. */
+export interface ResidentLearningProjection {
+    readonly text: string;
+    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. */
+export declare function projectResidentLearning(current: ResidentLearningState | undefined, options: ResidentLearningProjectionOptions): ResidentLearningProjection;
+export {};
+//# sourceMappingURL=learning.d.ts.map