@kweaver-ai/kweaver-sdk 0.8.3 → 0.8.4

package/dist/trace-ai/exp/schemas.d.ts

@@ -1,9 +1,4 @@
 import { z } from "zod";
-export declare const NextChangeSchema: z.ZodObject<{
-    target: z.ZodString;
-    hypothesis: z.ZodString;
-    patch: z.ZodString;
-}, z.core.$strip>;
 declare const GuardrailSchema: z.ZodObject<{
     name: z.ZodString;
     kind: z.ZodEnum<{
@@ -12,38 +7,6 @@ declare const GuardrailSchema: z.ZodObject<{
     }>;
     rule: z.ZodString;
 }, z.core.$strip>;
-export declare const MissionSchema: z.ZodObject<{
-    schema_version: z.ZodLiteral<"trace-mission/v1">;
-    goal: z.ZodString;
-    max_rounds: z.ZodOptional<z.ZodNumber>;
-    provider: z.ZodOptional<z.ZodString>;
-    eval_sets: z.ZodArray<z.ZodObject<{
-        path: z.ZodString;
-        role: z.ZodEnum<{
-            seed: "seed";
-            regression: "regression";
-            holdout: "holdout";
-        }>;
-    }, z.core.$strip>>;
-    current_candidate: z.ZodObject<{
-        path: z.ZodString;
-    }, z.core.$strip>;
-    next_change: z.ZodOptional<z.ZodObject<{
-        target: z.ZodString;
-        hypothesis: z.ZodString;
-        patch: z.ZodString;
-    }, z.core.$strip>>;
-    guardrails: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodEnum<{
-            hard: "hard";
-            soft: "soft";
-        }>;
-        rule: z.ZodString;
-    }, z.core.$strip>>>;
-}, z.core.$strip>;
-export type Mission = z.infer<typeof MissionSchema>;
-export type NextChange = z.infer<typeof NextChangeSchema>;
 export { GuardrailSchema };
 export type Guardrail = z.infer<typeof GuardrailSchema>;
 export declare const BundleSchema: z.ZodObject<{
@@ -102,14 +65,14 @@ export type ExpEvent = {
     type: "aborted";
     round: number;
     reason: string;
+} | {
+    ts: string;
+    type: "TriageComplete";
+    round: number;
+    verdict: string;
+    summary: string;
+    failure_attribution: FailureAttribution[];
 };
-export interface LineageEntry {
-    version: number;
-    candidate_path: string;
-    next_change: NextChange;
-    status: "running" | "scored" | "guardrail_failed";
-    appended_at: string;
-}
 export interface ThreeAxisScores {
     outcome: number;
     trajectory: number;
@@ -130,6 +93,23 @@ export interface QueryResult {
         error_codes: string[];
     };
     raw_trace_id?: string;
+    conversation_id?: string;
+}
+export interface QueryFailureAnalysis {
+    query_id: string;
+    verdict: "fail" | "skip";
+    /** Assertion failure reason, truncated to 200 chars. */
+    assertion_reason: string;
+    /** Tool calls extracted from trace, e.g. ["kn_search(激光雷达)→data"]. Max 3 entries. */
+    tool_call_summary: string[];
+    /**
+     * Whether the agent actually retrieved KN data on this query, derived from the
+     * trace. "retrieved" = at least one KN tool call returned data; "errored"/
+     * "empty" = KN tool calls were made but none returned data; "no_kn_calls" =
+     * no KN tool was called; "no_trace" = trace unavailable. Lets triage see a
+     * mechanism failure (agent not retrieving data) instead of guessing at prompts.
+     */
+    retrieval_health: "retrieved" | "empty" | "errored" | "no_kn_calls" | "no_trace";
 }
 export interface RoundData {
     round: number;
@@ -145,3 +125,381 @@ export interface RoundData {
         cross_round_memory_ref?: string;
     };
 }
+export declare const PatchTargetSchema: z.ZodEnum<{
+    "agent.system_prompt": "agent.system_prompt";
+    "agent.skills": "agent.skills";
+    "kn.object_type": "kn.object_type";
+    "kn.relation_type": "kn.relation_type";
+    "skill.content": "skill.content";
+}>;
+export type PatchTarget = z.infer<typeof PatchTargetSchema>;
+export declare const FailureAttributionSchema: z.ZodObject<{
+    layer: z.ZodEnum<{
+        agent: "agent";
+        skill: "skill";
+        kn: "kn";
+    }>;
+    evidence: z.ZodString;
+    affected_queries: z.ZodArray<z.ZodString>;
+    suggested_target: z.ZodEnum<{
+        "agent.system_prompt": "agent.system_prompt";
+        "agent.skills": "agent.skills";
+        "kn.object_type": "kn.object_type";
+        "kn.relation_type": "kn.relation_type";
+        "skill.content": "skill.content";
+    }>;
+}, z.core.$strip>;
+export type FailureAttribution = z.infer<typeof FailureAttributionSchema>;
+export declare const KnDataPropertySchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodString;
+}, z.core.$strip>;
+export declare const KnObjectTypeDefSchema: z.ZodObject<{
+    concept_name: z.ZodString;
+    dataview_id: z.ZodString;
+    primary_keys: z.ZodArray<z.ZodString>;
+    data_properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type KnObjectTypeDef = z.infer<typeof KnObjectTypeDefSchema>;
+export declare const KnRelationTypeDefSchema: z.ZodObject<{
+    concept_name: z.ZodString;
+    source_object_type: z.ZodString;
+    target_object_type: z.ZodString;
+    join_key: z.ZodString;
+}, z.core.$strip>;
+export type KnRelationTypeDef = z.infer<typeof KnRelationTypeDefSchema>;
+export declare const KnPatchSchema: z.ZodObject<{
+    kn_id: z.ZodString;
+    add_object_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        concept_name: z.ZodString;
+        dataview_id: z.ZodString;
+        primary_keys: z.ZodArray<z.ZodString>;
+        data_properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    add_relation_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        concept_name: z.ZodString;
+        source_object_type: z.ZodString;
+        target_object_type: z.ZodString;
+        join_key: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type KnPatch = z.infer<typeof KnPatchSchema>;
+export declare const SkillContentPatchSchema: z.ZodObject<{
+    skill_id: z.ZodString;
+    append_section: z.ZodString;
+}, z.core.$strip>;
+export type SkillContentPatch = z.infer<typeof SkillContentPatchSchema>;
+export declare const SkillBindingSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+}, z.core.$strip>;
+export type SkillBinding = z.infer<typeof SkillBindingSchema>;
+export declare const AgentSkillsPatchSchema: z.ZodObject<{
+    unbind: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    bind: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type AgentSkillsPatch = z.infer<typeof AgentSkillsPatchSchema>;
+export declare const NextChangeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    target: z.ZodLiteral<"agent.system_prompt">;
+    hypothesis: z.ZodOptional<z.ZodString>;
+    patch: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+}, z.core.$strip>, z.ZodObject<{
+    target: z.ZodLiteral<"agent.skills">;
+    hypothesis: z.ZodOptional<z.ZodString>;
+    patch: z.ZodObject<{
+        unbind: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        bind: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    target: z.ZodLiteral<"kn.object_type">;
+    hypothesis: z.ZodString;
+    patch: z.ZodObject<{
+        kn_id: z.ZodString;
+        add_object_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            concept_name: z.ZodString;
+            dataview_id: z.ZodString;
+            primary_keys: z.ZodArray<z.ZodString>;
+            data_properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                type: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+        add_relation_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            concept_name: z.ZodString;
+            source_object_type: z.ZodString;
+            target_object_type: z.ZodString;
+            join_key: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    target: z.ZodLiteral<"kn.relation_type">;
+    hypothesis: z.ZodString;
+    patch: z.ZodObject<{
+        kn_id: z.ZodString;
+        add_object_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            concept_name: z.ZodString;
+            dataview_id: z.ZodString;
+            primary_keys: z.ZodArray<z.ZodString>;
+            data_properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                type: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+        add_relation_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            concept_name: z.ZodString;
+            source_object_type: z.ZodString;
+            target_object_type: z.ZodString;
+            join_key: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    target: z.ZodLiteral<"skill.content">;
+    hypothesis: z.ZodString;
+    patch: z.ZodObject<{
+        skill_id: z.ZodString;
+        append_section: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>], "target">;
+export type NextChange = z.infer<typeof NextChangeSchema>;
+export declare const MissionSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"trace-mission/v1">;
+    goal: z.ZodString;
+    max_rounds: z.ZodOptional<z.ZodNumber>;
+    provider: z.ZodOptional<z.ZodString>;
+    eval_sets: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        role: z.ZodEnum<{
+            seed: "seed";
+            regression: "regression";
+            holdout: "holdout";
+        }>;
+    }, z.core.$strip>>;
+    current_candidate: z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strip>;
+    next_change: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        target: z.ZodLiteral<"agent.system_prompt">;
+        hypothesis: z.ZodOptional<z.ZodString>;
+        patch: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+    }, z.core.$strip>, z.ZodObject<{
+        target: z.ZodLiteral<"agent.skills">;
+        hypothesis: z.ZodOptional<z.ZodString>;
+        patch: z.ZodObject<{
+            unbind: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            bind: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                version: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        target: z.ZodLiteral<"kn.object_type">;
+        hypothesis: z.ZodString;
+        patch: z.ZodObject<{
+            kn_id: z.ZodString;
+            add_object_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                concept_name: z.ZodString;
+                dataview_id: z.ZodString;
+                primary_keys: z.ZodArray<z.ZodString>;
+                data_properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    type: z.ZodString;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>>;
+            add_relation_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                concept_name: z.ZodString;
+                source_object_type: z.ZodString;
+                target_object_type: z.ZodString;
+                join_key: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        target: z.ZodLiteral<"kn.relation_type">;
+        hypothesis: z.ZodString;
+        patch: z.ZodObject<{
+            kn_id: z.ZodString;
+            add_object_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                concept_name: z.ZodString;
+                dataview_id: z.ZodString;
+                primary_keys: z.ZodArray<z.ZodString>;
+                data_properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    type: z.ZodString;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>>>;
+            add_relation_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                concept_name: z.ZodString;
+                source_object_type: z.ZodString;
+                target_object_type: z.ZodString;
+                join_key: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        target: z.ZodLiteral<"skill.content">;
+        hypothesis: z.ZodString;
+        patch: z.ZodObject<{
+            skill_id: z.ZodString;
+            append_section: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "target">>;
+    guardrails: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            hard: "hard";
+            soft: "soft";
+        }>;
+        rule: z.ZodString;
+    }, z.core.$strip>>>;
+    enabled_targets: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "agent.system_prompt": "agent.system_prompt";
+        "agent.skills": "agent.skills";
+        "kn.object_type": "kn.object_type";
+        "kn.relation_type": "kn.relation_type";
+        "skill.content": "skill.content";
+    }>>>;
+}, z.core.$strip>;
+export type Mission = z.infer<typeof MissionSchema>;
+export declare const VegaCatalogEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    columns: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type VegaCatalogEntry = z.infer<typeof VegaCatalogEntrySchema>;
+export declare const KnSchemaSnapshotSchema: z.ZodObject<{
+    object_types: z.ZodArray<z.ZodObject<{
+        concept_name: z.ZodString;
+        data_view_id: z.ZodOptional<z.ZodString>;
+        fields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    relation_types: z.ZodArray<z.ZodObject<{
+        concept_name: z.ZodString;
+        source: z.ZodString;
+        target: z.ZodString;
+        join_key: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type KnSchemaSnapshot = z.infer<typeof KnSchemaSnapshotSchema>;
+export declare const KnContextSchema: z.ZodObject<{
+    kn_id: z.ZodString;
+    existing_schema: z.ZodObject<{
+        object_types: z.ZodArray<z.ZodObject<{
+            concept_name: z.ZodString;
+            data_view_id: z.ZodOptional<z.ZodString>;
+            fields: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                type: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        relation_types: z.ZodArray<z.ZodObject<{
+            concept_name: z.ZodString;
+            source: z.ZodString;
+            target: z.ZodString;
+            join_key: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    available_dataviews: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        columns: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    data_probes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        concept_name: z.ZodString;
+        data_view_id: z.ZodString;
+        total_records: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type KnContext = z.infer<typeof KnContextSchema>;
+export declare const SkillContextSchema: z.ZodObject<{
+    bound_skills: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+        content: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SkillContext = z.infer<typeof SkillContextSchema>;
+export declare const CandidateSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"trace-candidate/v1">;
+    agent: z.ZodObject<{
+        description: z.ZodString;
+        system_prompt: z.ZodString;
+    }, z.core.$strip>;
+    kn: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        object_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            concept_name: z.ZodString;
+            dataview_id: z.ZodString;
+            primary_keys: z.ZodArray<z.ZodString>;
+            data_properties: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                type: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+        relation_types: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            concept_name: z.ZodString;
+            source_object_type: z.ZodString;
+            target_object_type: z.ZodString;
+            join_key: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Candidate = z.infer<typeof CandidateSchema>;
+export interface LineageEntry {
+    version: number;
+    candidate_path: string;
+    next_change: NextChange;
+    status: "running" | "scored" | "guardrail_failed";
+    appended_at: string;
+}
+export declare const SkillSetEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+}, z.core.$strip>;
+export type SkillSetEntry = z.infer<typeof SkillSetEntrySchema>;
+export declare const KnPatchLogEntrySchema: z.ZodObject<{
+    op: z.ZodEnum<{
+        add_object_type: "add_object_type";
+        add_relation_type: "add_relation_type";
+    }>;
+    concept_name: z.ZodString;
+    dataview_id: z.ZodOptional<z.ZodString>;
+    applied_at: z.ZodString;
+}, z.core.$strip>;
+export type KnPatchLogEntry = z.infer<typeof KnPatchLogEntrySchema>;
+export declare const LineageEntrySchema: z.ZodObject<{
+    version: z.ZodNumber;
+    agent_id: z.ZodString;
+    skill_set: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strip>>>;
+    kn_patch_log: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        op: z.ZodEnum<{
+            add_object_type: "add_object_type";
+            add_relation_type: "add_relation_type";
+        }>;
+        concept_name: z.ZodString;
+        dataview_id: z.ZodOptional<z.ZodString>;
+        applied_at: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type LineageEntryExtended = z.infer<typeof LineageEntrySchema>;

package/dist/trace-ai/exp/schemas.js

@@ -1,27 +1,9 @@
 import { z } from "zod";
-export const NextChangeSchema = z.object({
-    target: z.string().min(1),
-    hypothesis: z.string().min(1),
-    patch: z.string(),
-});
 const GuardrailSchema = z.object({
     name: z.string(),
     kind: z.enum(["hard", "soft"]),
     rule: z.string(),
 });
-export const MissionSchema = z.object({
-    schema_version: z.literal("trace-mission/v1"),
-    goal: z.string().min(1),
-    max_rounds: z.number().int().positive().optional(),
-    provider: z.string().optional(),
-    eval_sets: z.array(z.object({
-        path: z.string().min(1),
-        role: z.enum(["seed", "regression", "holdout"]),
-    })).min(1),
-    current_candidate: z.object({ path: z.string() }),
-    next_change: NextChangeSchema.optional(),
-    guardrails: z.array(GuardrailSchema).optional(),
-});
 export { GuardrailSchema };
 export const BundleSchema = z.object({
     schema_version: z.literal("trace-bundle/v1"),
@@ -48,3 +30,134 @@ export const ManifestSchema = z.object({
         risks: z.array(z.object({ query_id: z.string(), reason: z.string() })),
     }),
 });
+// ── Multilayer Patch ──────────────────────────────────────────────────────
+export const PatchTargetSchema = z.enum([
+    "agent.system_prompt",
+    "agent.skills",
+    "kn.object_type",
+    "kn.relation_type",
+    "skill.content",
+]);
+export const FailureAttributionSchema = z.object({
+    layer: z.enum(["kn", "skill", "agent"]),
+    evidence: z.string(),
+    affected_queries: z.array(z.string()),
+    suggested_target: PatchTargetSchema,
+});
+// ── KN Patch types ────────────────────────────────────────────────────────
+export const KnDataPropertySchema = z.object({ name: z.string(), type: z.string() });
+export const KnObjectTypeDefSchema = z.object({
+    concept_name: z.string(),
+    dataview_id: z.string(),
+    primary_keys: z.array(z.string()),
+    data_properties: z.array(KnDataPropertySchema).default([]),
+});
+export const KnRelationTypeDefSchema = z.object({
+    concept_name: z.string(),
+    source_object_type: z.string(),
+    target_object_type: z.string(),
+    join_key: z.string(),
+});
+export const KnPatchSchema = z.object({
+    kn_id: z.string(),
+    add_object_types: z.array(KnObjectTypeDefSchema).default([]),
+    add_relation_types: z.array(KnRelationTypeDefSchema).default([]),
+});
+// ── Skill Patch types ─────────────────────────────────────────────────────
+export const SkillContentPatchSchema = z.object({
+    skill_id: z.string(),
+    append_section: z.string(),
+});
+export const SkillBindingSchema = z.object({ id: z.string(), version: z.string() });
+export const AgentSkillsPatchSchema = z.object({
+    unbind: z.array(z.string()).default([]),
+    bind: z.array(SkillBindingSchema).default([]),
+});
+// ── NextChange discriminated union ────────────────────────────────────────
+export const NextChangeSchema = z.discriminatedUnion("target", [
+    z.object({ target: z.literal("agent.system_prompt"), hypothesis: z.string().optional(), patch: z.union([z.string(), z.record(z.string(), z.unknown())]) }),
+    z.object({ target: z.literal("agent.skills"), hypothesis: z.string().optional(), patch: AgentSkillsPatchSchema }),
+    z.object({ target: z.literal("kn.object_type"), hypothesis: z.string(), patch: KnPatchSchema }),
+    z.object({ target: z.literal("kn.relation_type"), hypothesis: z.string(), patch: KnPatchSchema }),
+    z.object({ target: z.literal("skill.content"), hypothesis: z.string(), patch: SkillContentPatchSchema }),
+]);
+// ── MissionSchema (depends on NextChangeSchema) ───────────────────────────
+export const MissionSchema = z.object({
+    schema_version: z.literal("trace-mission/v1"),
+    goal: z.string().min(1),
+    max_rounds: z.number().int().positive().optional(),
+    provider: z.string().optional(),
+    eval_sets: z.array(z.object({
+        path: z.string().min(1),
+        role: z.enum(["seed", "regression", "holdout"]),
+    })).min(1),
+    current_candidate: z.object({ path: z.string() }),
+    next_change: NextChangeSchema.optional(),
+    guardrails: z.array(GuardrailSchema).optional(),
+    /**
+     * Patch targets this experiment is allowed to iterate on. Limits the planner
+     * LLM's choices, gates KN/Skill client construction, and shapes prompt
+     * examples. Default = ["agent.system_prompt"] — safest for missions that
+     * predate the multilayer rollout. Opt-in to other layers as their backing
+     * API clients become production-ready.
+     */
+    enabled_targets: z.array(PatchTargetSchema).min(1).default(["agent.system_prompt"]),
+});
+// ── ContextAssembler types ────────────────────────────────────────────────
+export const VegaCatalogEntrySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    columns: z.array(z.object({ name: z.string(), type: z.string() })),
+});
+export const KnSchemaSnapshotSchema = z.object({
+    object_types: z.array(z.object({
+        concept_name: z.string(),
+        data_view_id: z.string().optional(),
+        fields: z.array(z.object({ name: z.string(), type: z.string() })),
+    })),
+    relation_types: z.array(z.object({
+        concept_name: z.string(),
+        source: z.string(),
+        target: z.string(),
+        join_key: z.string(),
+    })),
+});
+export const KnContextSchema = z.object({
+    kn_id: z.string(),
+    existing_schema: KnSchemaSnapshotSchema,
+    available_dataviews: z.array(VegaCatalogEntrySchema),
+    data_probes: z.array(z.object({
+        concept_name: z.string(),
+        data_view_id: z.string(),
+        total_records: z.number(),
+    })).optional(),
+});
+export const SkillContextSchema = z.object({
+    bound_skills: z.array(z.object({ id: z.string(), version: z.string(), content: z.string() })),
+});
+// ── CandidateSchema ───────────────────────────────────────────────────────
+export const CandidateSchema = z.object({
+    schema_version: z.literal("trace-candidate/v1"),
+    agent: z.object({
+        description: z.string(),
+        system_prompt: z.string(),
+    }),
+    kn: z.object({
+        id: z.string(),
+        object_types: z.array(KnObjectTypeDefSchema).default([]),
+        relation_types: z.array(KnRelationTypeDefSchema).default([]),
+    }).optional(),
+});
+export const SkillSetEntrySchema = z.object({ id: z.string(), version: z.string() });
+export const KnPatchLogEntrySchema = z.object({
+    op: z.enum(["add_object_type", "add_relation_type"]),
+    concept_name: z.string(),
+    dataview_id: z.string().optional(),
+    applied_at: z.string(),
+});
+export const LineageEntrySchema = z.object({
+    version: z.number(),
+    agent_id: z.string(),
+    skill_set: z.array(SkillSetEntrySchema).default([]),
+    kn_patch_log: z.array(KnPatchLogEntrySchema).default([]),
+});

package/dist/utils/deprecation.d.ts

@@ -0,0 +1 @@
+export declare function warnDeprecated(commandName: string, note: string): void;

package/dist/utils/deprecation.js

@@ -0,0 +1,18 @@
+// Print a one-line deprecation notice to stderr. No-op when the
+// KWEAVER_NO_DEPRECATION_WARNINGS env var is set (CI / scripted callers).
+// ANSI yellow only when stderr is a TTY, to keep piped output clean.
+let warned = new Set();
+// `note` is appended after a colon. Pass a "use X instead" hint when a
+// replacement exists, or a free-form explanation (e.g. "rename pending") when
+// the name is deprecated but no replacement is ready yet.
+export function warnDeprecated(commandName, note) {
+    if (process.env.KWEAVER_NO_DEPRECATION_WARNINGS)
+        return;
+    if (warned.has(commandName))
+        return;
+    warned.add(commandName);
+    const useColor = process.stderr.isTTY;
+    const yellow = useColor ? "\x1b[33m" : "";
+    const reset = useColor ? "\x1b[0m" : "";
+    process.stderr.write(`${yellow}warning:${reset} '${commandName}' is deprecated: ${note}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kweaver-ai/kweaver-sdk",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "KWeaver TypeScript SDK — CLI tool and programmatic API for knowledge networks and Decision Agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,6 +53,7 @@
     "node": ">=22"
   },
   "devDependencies": {
+    "@antv/g6": "^5.1.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.6.0",
     "@types/react": "^19.2.14",