@tenphi/akno-core 0.4.0 → 0.6.0

package/dist/write/retain.d.ts

@@ -1,67 +1,195 @@
+import { type ProvidedRetainCandidate, type RetainHoldReason, type RetainModelCallReceipt, type RetainSourceItem } from '@tenphi/akno-protocol';
 import { z } from 'zod';
-import { type ModelClient } from '../models/client.ts';
+import { type ModelClient, type ModelOutcome } from '../models/client.ts';
 import type { FolderCatalogEntry } from '../kb/folders.ts';
-/**
- * `page` is nullable rather than optional, and the prompt above says "null" rather than "omit"
- * for the same reason: OpenAI's strict mode rejects an optional property outright, and a schema
- * it rejects takes this call site off constrained decoding silently — the fallback to a plain
- * JSON request looks exactly like success. Nullable says the same thing and stays enforceable.
- *
- * The guards this cannot express stay downstream regardless: `cleanCandidates` drops
- * speculation, fragments, and any page whose folder is not one that actually exists.
- */
+/** All fields are required or nullable so constrained-decoding endpoints can keep strict mode. */
 export declare const RETAIN_SCHEMA: z.ZodObject<{
     candidates: z.ZodArray<z.ZodObject<{
         text: z.ZodString;
         subject: z.ZodString;
         page: z.ZodNullable<z.ZodString>;
-        origin: z.ZodEnum<{
-            user: "user";
-            assistant: "assistant";
-        }>;
-        evidence: z.ZodNullable<z.ZodString>;
-        frame: z.ZodNullable<z.ZodString>;
         kind: z.ZodEnum<{
+            question: "question";
             claim: "claim";
             decision: "decision";
             preference: "preference";
+            plan: "plan";
+            event: "event";
+        }>;
+        attribution: z.ZodObject<{
+            source_role: z.ZodEnum<{
+                unknown: "unknown";
+                external: "external";
+                user: "user";
+                assistant: "assistant";
+            }>;
+            source_speaker: z.ZodNullable<z.ZodString>;
+            chain: z.ZodArray<z.ZodObject<{
+                speaker: z.ZodString;
+                role: z.ZodNullable<z.ZodEnum<{
+                    unknown: "unknown";
+                    external: "external";
+                    user: "user";
+                    assistant: "assistant";
+                }>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        discourse: z.ZodObject<{
+            commitment: z.ZodEnum<{
+                none: "none";
+                tentative: "tentative";
+                asserted: "asserted";
+                hypothetical: "hypothetical";
+                counterfactual: "counterfactual";
+            }>;
+            disposition: z.ZodEnum<{
+                active: "active";
+                proposed: "proposed";
+                accepted: "accepted";
+                rejected: "rejected";
+                resolved: "resolved";
+                cancelled: "cancelled";
+                completed: "completed";
+                superseded: "superseded";
+            }>;
+        }, z.core.$strip>;
+        epistemic: z.ZodObject<{
+            basis: z.ZodEnum<{
+                self_attested: "self_attested";
+                source_report: "source_report";
+            }>;
+        }, z.core.$strip>;
+        polarity: z.ZodEnum<{
+            affirmed: "affirmed";
+            negated: "negated";
         }>;
+        support: z.ZodArray<z.ZodObject<{
+            quote: z.ZodString;
+            item_id: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        discourse_frame: z.ZodArray<z.ZodObject<{
+            quote: z.ZodString;
+            item_id: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        relations: z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                corrects: "corrects";
+                supersedes: "supersedes";
+                contradicts: "contradicts";
+                fulfills: "fulfills";
+                answers: "answers";
+                caused_by: "caused_by";
+            }>;
+            target_candidate: z.ZodNumber;
+            support: z.ZodArray<z.ZodObject<{
+                quote: z.ZodString;
+                item_id: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        time: z.ZodNullable<z.ZodObject<{
+            start: z.ZodNullable<z.ZodString>;
+            until: z.ZodNullable<z.ZodString>;
+            precision: z.ZodEnum<{
+                unknown: "unknown";
+                instant: "instant";
+                day: "day";
+                month: "month";
+                year: "year";
+            }>;
+            relation: z.ZodEnum<{
+                occurred: "occurred";
+                valid: "valid";
+                scheduled: "scheduled";
+                due: "due";
+            }>;
+            status: z.ZodEnum<{
+                scheduled: "scheduled";
+                actual: "actual";
+                planned: "planned";
+                tentative: "tentative";
+            }>;
+            timezone: z.ZodNullable<z.ZodString>;
+            mentioned_at: z.ZodNullable<z.ZodString>;
+            recurrence: z.ZodNullable<z.ZodObject<{
+                frequency: z.ZodEnum<{
+                    daily: "daily";
+                    weekly: "weekly";
+                    monthly: "monthly";
+                    yearly: "yearly";
+                }>;
+                interval: z.ZodNullable<z.ZodNumber>;
+                weekdays: z.ZodArray<z.ZodEnum<{
+                    mo: "mo";
+                    tu: "tu";
+                    we: "we";
+                    th: "th";
+                    fr: "fr";
+                    sa: "sa";
+                    su: "su";
+                }>>;
+                until: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     events: z.ZodArray<z.ZodObject<{
         date: z.ZodString;
         summary: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-export interface RetainCandidate {
-    text: string;
-    subject: string;
-    kind: string;
-    /**
-     * Where this would go if no page holds it yet. A suggestion, used only when routing finds
-     * nothing — which is the case `remember` used to have no answer for at all.
-     */
+export type RetainCandidate = ProvidedRetainCandidate & {
+    /** Taxonomy suggestion used only after ordinary routing finds no admitted existing page. */
     page?: string;
+    /** Compatibility fields consumed by the existing remember result and evidence archive. */
     origin?: 'user' | 'assistant';
-    /** Exact bounded input bytes retained privately so the managed sentence can be re-verified. */
     evidence?: string;
+};
+export interface RetainHeldCandidate {
+    candidate_id: string;
+    reason_code: RetainHoldReason;
+    reason: string;
 }
 export interface RetainResult {
     candidates: RetainCandidate[];
+    held: RetainHeldCandidate[];
     events: {
         date: string;
         summary: string;
     }[];
     error: string | null;
+    sourceHold: {
+        reason_code: RetainHoldReason;
+        reason: string;
+    } | null;
+    degradedReason: 'no_derive_model' | 'derive_failed' | 'retain_verification_failed' | null;
+    modelUsage: {
+        extraction: RetainModelCallReceipt | null;
+        verification: RetainModelCallReceipt | null;
+    };
+}
+export interface CandidateCleaningOptions {
+    folders?: readonly string[];
+    pages?: readonly string[];
+    sourceText?: string;
+    sourceItems?: readonly RetainSourceItem[];
+    sourceId?: string;
+    revision?: string;
+    mentionedAt?: string;
+    timezone?: string;
 }
 export declare function runRetain(text: string, model: ModelClient, options?: {
     mission?: string;
     mentionedAt?: string;
     timezone?: string;
     folders?: FolderCatalogEntry[];
+    sourceItems?: readonly RetainSourceItem[];
+    sourceId?: string;
+    revision?: string;
 }): Promise<RetainResult>;
-export declare function cleanCandidates(value: unknown, options?: {
-    folders?: readonly string[];
-    pages?: readonly string[];
-    sourceText?: string;
-}): RetainCandidate[];
+/** Kept public for the deterministic extraction guard tests. */
+export declare function cleanCandidates(value: unknown, options?: CandidateCleaningOptions): RetainCandidate[];
+export declare function cleanCandidateBatch(value: unknown, options: CandidateCleaningOptions): {
+    candidates: RetainCandidate[];
+    held: RetainHeldCandidate[];
+};
+export declare function modelCallReceipt(model: ModelClient, outcome: ModelOutcome<unknown>): RetainModelCallReceipt;
 //# sourceMappingURL=retain.d.ts.map

package/dist/write/retain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retain.d.ts","sourceRoot":"","sources":["../../src/write/retain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAsE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;iBAaxB,CAAC;AAEH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAC3B,GACL,OAAO,CAAC,YAAY,CAAC,CAyCvB;AA0DD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5F,eAAe,EAAE,CAkDnB"}
+{"version":3,"file":"retain.d.ts","sourceRoot":"","sources":["../../src/write/retain.ts"],"names":[],"mappings":"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"}