@tenphi/akno-protocol 0.1.0

package/dist/ops/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/ops/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,cAAc;;;EAAqC,CAAC;AACjE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,gBAAgB;;;;;;iBAG3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsCrB,CAAC;AACL,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,eAAO,MAAM,oBAAoB;;;;;;;;;;;iBAM/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAuBxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/ops/context.js

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+import { Card, PageRole, RecallMode, RecallQualification, RecallResult, ResultEnvelope, SlugFilter, } from "../common.js";
+import { TimelineResult } from "./timeline.js";
+export const ContextProfile = z.enum(['default', 'auto_recall']);
+export const ConversationTurn = z.object({
+    role: z.enum(['user', 'assistant']),
+    content: z.string().min(1).max(2000),
+});
+/**
+ * One budget, one assembly. `context` composes the whole pre-turn bundle —
+ * pinned pages, recent timeline, structure tree, and this turn's recall —
+ * against a single budget. Separate injections with separate budgets overrun
+ * together. Normally called by the host, not by the agent.
+ */
+export const ContextInput = z
+    .object({
+    query: z.string().min(1).optional(),
+    /** `auto_recall` is a conservative evidence-only host injection, not an answer operation. */
+    profile: ContextProfile.optional(),
+    /** Bounded recent turns used only to resolve a local reference in `query`. */
+    conversation_context: z.array(ConversationTurn).max(6).optional(),
+    /** Defaults to 20,000 for the broad profile and 1,200 for auto-recall. */
+    budget: z.number().int().positive().optional(),
+    /** Slugs always included, before anything else competes for room. Ignored by auto-recall. */
+    pinned: z.array(z.string()).optional(),
+    /** Days of ledger to include. 0 omits the section. Ignored by auto-recall. */
+    timeline_days: z.number().int().nonnegative().optional(),
+    /** Include a folder outline so the agent knows what exists. Ignored by auto-recall. */
+    structure: z.boolean().optional(),
+    mode: RecallMode.optional(),
+    include: z.array(PageRole).optional(),
+    filter: SlugFilter.optional(),
+})
+    .superRefine((input, check) => {
+    if (input.profile === 'auto_recall' && !input.query) {
+        check.addIssue({
+            code: 'custom',
+            path: ['query'],
+            message: 'query is required for the auto_recall context profile',
+        });
+    }
+    const conversationChars = (input.conversation_context ?? []).reduce((total, turn) => total + turn.content.length, 0);
+    if (conversationChars > 6000) {
+        check.addIssue({
+            code: 'custom',
+            path: ['conversation_context'],
+            message: 'recent conversation context must not exceed 6000 characters',
+        });
+    }
+});
+export const AutoRecallActivation = z.object({
+    activated: z.boolean(),
+    basis: z.enum(['exact', 'semantic', 'qualified', 'none']),
+    candidates: z.number().int().nonnegative(),
+    selected: z.number().int().nonnegative(),
+    qualification_run: z.boolean(),
+});
+export const ContextOutput = ResultEnvelope.extend({
+    profile: ContextProfile.optional(),
+    /** Content-free receipt for the precision-first auto-recall activation decision. */
+    activation: AutoRecallActivation.optional(),
+    pinned: z.array(Card),
+    /** Mixed page/document results for this turn's recall. */
+    results: z.array(RecallResult),
+    /** Recent authored events and typed orphan-document date evidence. */
+    timeline: z.array(TimelineResult),
+    structure: z.string().optional(),
+    searched: z.array(z.string()),
+    coverage: z.record(z.string(), z.boolean()).optional(),
+    qualification: RecallQualification.optional(),
+    budget_used: z.number().int().nonnegative(),
+    /** What was dropped to fit, and how much of it. A silent trim reads as
+     *  "that's everything" when it wasn't — default to visible. */
+    dropped: z
+        .object({
+        pinned: z.number().int().nonnegative(),
+        results: z.number().int().nonnegative(),
+        timeline: z.number().int().nonnegative(),
+    })
+        .optional(),
+});
+//# sourceMappingURL=context.js.map

package/dist/ops/context.js.map

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

package/dist/ops/folder.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+/**
+ * **Declare a folder before writing into it.**
+ *
+ * A folder used to appear the moment a page was written under it, and a new top-level one
+ * became a question for the owner. Both halves were wrong. The owner does not want to be
+ * asked where an agent's research note goes; and a folder that appears with no statement of
+ * what belongs in it is a folder the next caller has to guess about — which is how evidence
+ * and claims end up in the same place, and how a rent figure from a transcript gets filed as
+ * a defence strategy.
+ *
+ * So this op is **never gated**: nothing here waits on a human. What it costs instead is a
+ * sentence. Saying what the folder is for is the whole point of the step, which is why
+ * `description` is required and everything else is optional.
+ */
+export declare const FolderInput: z.ZodObject<{
+    path: z.ZodString;
+    description: z.ZodString;
+    role: z.ZodOptional<z.ZodEnum<{
+        knowledge: "knowledge";
+        source: "source";
+        inference: "inference";
+        ignored: "ignored";
+    }>>;
+    remember: z.ZodOptional<z.ZodEnum<{
+        deny: "deny";
+        integrate: "integrate";
+    }>>;
+    about: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    type: z.ZodOptional<z.ZodString>;
+    ingest: z.ZodOptional<z.ZodEnum<{
+        file: "file";
+        page: "page";
+        document: "document";
+        auto: "auto";
+        ignore: "ignore";
+    }>>;
+    rank: z.ZodOptional<z.ZodNumber>;
+    route: z.ZodOptional<z.ZodBoolean>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type FolderInput = z.infer<typeof FolderInput>;
+export declare const FolderOutput: z.ZodObject<{
+    status: z.ZodEnum<{
+        ok: "ok";
+        empty: "empty";
+        degraded: "degraded";
+        unavailable: "unavailable";
+    }>;
+    degraded: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        no_embedding_model: "no_embedding_model";
+        no_reranker: "no_reranker";
+        no_derive_model: "no_derive_model";
+        no_expansion_model: "no_expansion_model";
+        embedding_failed: "embedding_failed";
+        rerank_failed: "rerank_failed";
+        derive_failed: "derive_failed";
+        expansion_failed: "expansion_failed";
+        no_vector_index: "no_vector_index";
+        partial_index: "partial_index";
+        no_document_text: "no_document_text";
+        document_source_missing: "document_source_missing";
+        no_graph_index: "no_graph_index";
+        no_entity_index: "no_entity_index";
+        entity_resolution_failed: "entity_resolution_failed";
+        partial_graph_index: "partial_graph_index";
+        graph_traversal_limited: "graph_traversal_limited";
+        no_answer_model: "no_answer_model";
+        answer_failed: "answer_failed";
+        answer_verification_failed: "answer_verification_failed";
+        answer_truncated: "answer_truncated";
+    }>>>;
+    note: z.ZodOptional<z.ZodString>;
+    outcome: z.ZodEnum<{
+        ok: "ok";
+        noop: "noop";
+    }>;
+    glob: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    rule: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    rules_file: z.ZodOptional<z.ZodString>;
+    change_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FolderOutput = z.infer<typeof FolderOutput>;
+//# sourceMappingURL=folder.d.ts.map

package/dist/ops/folder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder.d.ts","sourceRoot":"","sources":["../../src/ops/folder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAWvB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/ops/folder.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { PageRole, RememberManagement, ResultEnvelope } from "../common.js";
+/**
+ * **Declare a folder before writing into it.**
+ *
+ * A folder used to appear the moment a page was written under it, and a new top-level one
+ * became a question for the owner. Both halves were wrong. The owner does not want to be
+ * asked where an agent's research note goes; and a folder that appears with no statement of
+ * what belongs in it is a folder the next caller has to guess about — which is how evidence
+ * and claims end up in the same place, and how a rent figure from a transcript gets filed as
+ * a defence strategy.
+ *
+ * So this op is **never gated**: nothing here waits on a human. What it costs instead is a
+ * sentence. Saying what the folder is for is the whole point of the step, which is why
+ * `description` is required and everything else is optional.
+ */
+export const FolderInput = z.object({
+    /** The folder, as a slug prefix: `research`, `household/appliances`. No globs, no `.md`. */
+    path: z.string().min(1),
+    /**
+     * What belongs here, in a sentence, written for a caller who has never seen this knowledge
+     * base. It is returned by `list` and carried in the pre-turn bundle, so it is the thing that
+     * makes the folder self-explanatory later.
+     */
+    description: z.string().min(1).max(500),
+    /** `knowledge` for canonical claims, `source` for quoted evidence, `inference` for
+     * model conclusions, and `ignored` for material outside memory. */
+    role: PageRole.optional(),
+    /** Whether `remember` may place canonical claims in pages in this folder. When omitted,
+     * a declared knowledge folder integrates and every non-knowledge role denies. The resolved
+     * value is persisted in the rule rather than inherited from a global default. */
+    remember: RememberManagement.optional(),
+    /** Canonical entities pages in this folder are about. */
+    about: z.array(z.string()).optional(),
+    /** Default `type` for pages here, when the folder has one. */
+    type: z.string().optional(),
+    ingest: z.enum(['page', 'document', 'file', 'auto', 'ignore']).optional(),
+    /** Multiplied into the recall score. Demotes without hiding. */
+    rank: z.number().min(0).max(2).optional(),
+    /** Makes this an inbox: arrivals are extracted, named and moved out of it. */
+    route: z.boolean().optional(),
+    dry_run: z.boolean().optional(),
+});
+export const FolderOutput = ResultEnvelope.extend({
+    /** `noop` when the folder was already declared — its existing rule comes back unchanged. */
+    outcome: z.enum(['ok', 'noop']),
+    /** The glob the rule was filed under, e.g. `research/**`. */
+    glob: z.string().optional(),
+    path: z.string().optional(),
+    /** The rule now in force for this folder. */
+    rule: z.record(z.string(), z.unknown()).optional(),
+    /** The file the rule was written to, so a caller can say where the taxonomy lives. */
+    rules_file: z.string().optional(),
+    change_id: z.string().optional(),
+});
+//# sourceMappingURL=folder.js.map

package/dist/ops/folder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder.js","sourceRoot":"","sources":["../../src/ops/folder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,4FAA4F;IAC5F,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB;;;;OAIG;IACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACvC;uEACmE;IACnE,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE;IACzB;;qFAEiF;IACjF,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,EAAE;IACvC,yDAAyD;IACzD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrC,8DAA8D;IAC9D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzE,gEAAgE;IAChE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzC,8EAA8E;IAC9E,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC7B,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC,MAAM,CAAC;IAChD,4FAA4F;IAC5F,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/B,6DAA6D;IAC7D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,6CAA6C;IAC7C,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IAClD,sFAAsF;IACtF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC"}

package/dist/ops/graph.d.ts

@@ -0,0 +1,352 @@
+import { z } from 'zod';
+export declare const GraphDirection: z.ZodEnum<{
+    out: "out";
+    in: "in";
+    both: "both";
+}>;
+export type GraphDirection = z.infer<typeof GraphDirection>;
+/** One exact seed form. Query seeds still resolve only evidence-declared names. */
+export declare const GraphInput: z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    entity: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    direction: z.ZodOptional<z.ZodEnum<{
+        out: "out";
+        in: "in";
+        both: "both";
+    }>>;
+    relations: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        canonical_record: "canonical_record";
+        links_to: "links_to";
+        mentions: "mentions";
+        about: "about";
+        has_attribute: "has_attribute";
+        related_entity: "related_entity";
+        owns_document: "owns_document";
+        participates_in: "participates_in";
+    }>>>;
+    max_hops: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>]>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    include_history: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GraphInput = z.infer<typeof GraphInput>;
+export declare const GraphEdgeRef: z.ZodObject<{
+    id: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    relation: z.ZodEnum<{
+        canonical_record: "canonical_record";
+        links_to: "links_to";
+        mentions: "mentions";
+        about: "about";
+        has_attribute: "has_attribute";
+        related_entity: "related_entity";
+        owns_document: "owns_document";
+        participates_in: "participates_in";
+    }>;
+    predicate: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodNumber;
+    derivation: z.ZodEnum<{
+        fact: "fact";
+        structural: "structural";
+    }>;
+    resolution: z.ZodEnum<{
+        exact: "exact";
+        contextual: "contextual";
+    }>;
+    evidence: z.ZodObject<{
+        kind: z.ZodEnum<{
+            document: "document";
+            page_line: "page_line";
+            fact_line: "fact_line";
+            frontmatter: "frontmatter";
+        }>;
+        slug: z.ZodOptional<z.ZodString>;
+        document: z.ZodOptional<z.ZodString>;
+        event: z.ZodOptional<z.ZodString>;
+        fact: z.ZodOptional<z.ZodString>;
+        line_start: z.ZodOptional<z.ZodNumber>;
+        line_end: z.ZodOptional<z.ZodNumber>;
+        field: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    valid_from: z.ZodOptional<z.ZodString>;
+    valid_to: z.ZodOptional<z.ZodString>;
+    historical: z.ZodBoolean;
+}, z.core.$strip>;
+export type GraphEdgeRef = z.infer<typeof GraphEdgeRef>;
+export declare const GraphSeed: z.ZodObject<{
+    form: z.ZodEnum<{
+        entity: "entity";
+        slug: "slug";
+        query: "query";
+    }>;
+    value: z.ZodString;
+    node: z.ZodString;
+}, z.core.$strip>;
+export type GraphSeed = z.infer<typeof GraphSeed>;
+export declare const GraphPath: z.ZodObject<{
+    seed: z.ZodString;
+    nodes: z.ZodArray<z.ZodString>;
+    edges: z.ZodArray<z.ZodString>;
+    hops: z.ZodNumber;
+    confidence: z.ZodNumber;
+    evidence: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            document: "document";
+            page_line: "page_line";
+            fact_line: "fact_line";
+            frontmatter: "frontmatter";
+        }>;
+        slug: z.ZodOptional<z.ZodString>;
+        document: z.ZodOptional<z.ZodString>;
+        event: z.ZodOptional<z.ZodString>;
+        fact: z.ZodOptional<z.ZodString>;
+        line_start: z.ZodOptional<z.ZodNumber>;
+        line_end: z.ZodOptional<z.ZodNumber>;
+        field: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GraphPath = z.infer<typeof GraphPath>;
+export declare const GraphAmbiguity: z.ZodObject<{
+    mention: z.ZodString;
+    normalized: z.ZodString;
+    candidates: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fact: "fact";
+            entity: "entity";
+            page: "page";
+            document: "document";
+            event: "event";
+        }>;
+        slug: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodEnum<{
+            knowledge: "knowledge";
+            source: "source";
+            inference: "inference";
+            ignored: "ignored";
+        }>>;
+        entity: z.ZodOptional<z.ZodString>;
+        entity_type: z.ZodOptional<z.ZodEnum<{
+            event: "event";
+            person: "person";
+            organization: "organization";
+            place: "place";
+            product: "product";
+            concept: "concept";
+            other: "other";
+        }>>;
+        document: z.ZodOptional<z.ZodString>;
+        fact: z.ZodOptional<z.ZodString>;
+        event: z.ZodOptional<z.ZodString>;
+        date: z.ZodOptional<z.ZodString>;
+        line_start: z.ZodOptional<z.ZodNumber>;
+        line_end: z.ZodOptional<z.ZodNumber>;
+        availability: z.ZodOptional<z.ZodEnum<{
+            degraded: "degraded";
+            unavailable: "unavailable";
+            available: "available";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GraphAmbiguity = z.infer<typeof GraphAmbiguity>;
+export declare const GraphOutput: z.ZodObject<{
+    status: z.ZodEnum<{
+        ok: "ok";
+        empty: "empty";
+        degraded: "degraded";
+        unavailable: "unavailable";
+    }>;
+    degraded: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        no_embedding_model: "no_embedding_model";
+        no_reranker: "no_reranker";
+        no_derive_model: "no_derive_model";
+        no_expansion_model: "no_expansion_model";
+        embedding_failed: "embedding_failed";
+        rerank_failed: "rerank_failed";
+        derive_failed: "derive_failed";
+        expansion_failed: "expansion_failed";
+        no_vector_index: "no_vector_index";
+        partial_index: "partial_index";
+        no_document_text: "no_document_text";
+        document_source_missing: "document_source_missing";
+        no_graph_index: "no_graph_index";
+        no_entity_index: "no_entity_index";
+        entity_resolution_failed: "entity_resolution_failed";
+        partial_graph_index: "partial_graph_index";
+        graph_traversal_limited: "graph_traversal_limited";
+        no_answer_model: "no_answer_model";
+        answer_failed: "answer_failed";
+        answer_verification_failed: "answer_verification_failed";
+        answer_truncated: "answer_truncated";
+    }>>>;
+    note: z.ZodOptional<z.ZodString>;
+    seeds: z.ZodArray<z.ZodObject<{
+        form: z.ZodEnum<{
+            entity: "entity";
+            slug: "slug";
+            query: "query";
+        }>;
+        value: z.ZodString;
+        node: z.ZodString;
+    }, z.core.$strip>>;
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            fact: "fact";
+            entity: "entity";
+            page: "page";
+            document: "document";
+            event: "event";
+        }>;
+        slug: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodEnum<{
+            knowledge: "knowledge";
+            source: "source";
+            inference: "inference";
+            ignored: "ignored";
+        }>>;
+        entity: z.ZodOptional<z.ZodString>;
+        entity_type: z.ZodOptional<z.ZodEnum<{
+            event: "event";
+            person: "person";
+            organization: "organization";
+            place: "place";
+            product: "product";
+            concept: "concept";
+            other: "other";
+        }>>;
+        document: z.ZodOptional<z.ZodString>;
+        fact: z.ZodOptional<z.ZodString>;
+        event: z.ZodOptional<z.ZodString>;
+        date: z.ZodOptional<z.ZodString>;
+        line_start: z.ZodOptional<z.ZodNumber>;
+        line_end: z.ZodOptional<z.ZodNumber>;
+        availability: z.ZodOptional<z.ZodEnum<{
+            degraded: "degraded";
+            unavailable: "unavailable";
+            available: "available";
+        }>>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+        relation: z.ZodEnum<{
+            canonical_record: "canonical_record";
+            links_to: "links_to";
+            mentions: "mentions";
+            about: "about";
+            has_attribute: "has_attribute";
+            related_entity: "related_entity";
+            owns_document: "owns_document";
+            participates_in: "participates_in";
+        }>;
+        predicate: z.ZodOptional<z.ZodString>;
+        confidence: z.ZodNumber;
+        derivation: z.ZodEnum<{
+            fact: "fact";
+            structural: "structural";
+        }>;
+        resolution: z.ZodEnum<{
+            exact: "exact";
+            contextual: "contextual";
+        }>;
+        evidence: z.ZodObject<{
+            kind: z.ZodEnum<{
+                document: "document";
+                page_line: "page_line";
+                fact_line: "fact_line";
+                frontmatter: "frontmatter";
+            }>;
+            slug: z.ZodOptional<z.ZodString>;
+            document: z.ZodOptional<z.ZodString>;
+            event: z.ZodOptional<z.ZodString>;
+            fact: z.ZodOptional<z.ZodString>;
+            line_start: z.ZodOptional<z.ZodNumber>;
+            line_end: z.ZodOptional<z.ZodNumber>;
+            field: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        valid_from: z.ZodOptional<z.ZodString>;
+        valid_to: z.ZodOptional<z.ZodString>;
+        historical: z.ZodBoolean;
+    }, z.core.$strip>>;
+    paths: z.ZodArray<z.ZodObject<{
+        seed: z.ZodString;
+        nodes: z.ZodArray<z.ZodString>;
+        edges: z.ZodArray<z.ZodString>;
+        hops: z.ZodNumber;
+        confidence: z.ZodNumber;
+        evidence: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                document: "document";
+                page_line: "page_line";
+                fact_line: "fact_line";
+                frontmatter: "frontmatter";
+            }>;
+            slug: z.ZodOptional<z.ZodString>;
+            document: z.ZodOptional<z.ZodString>;
+            event: z.ZodOptional<z.ZodString>;
+            fact: z.ZodOptional<z.ZodString>;
+            line_start: z.ZodOptional<z.ZodNumber>;
+            line_end: z.ZodOptional<z.ZodNumber>;
+            field: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    ambiguities: z.ZodArray<z.ZodObject<{
+        mention: z.ZodString;
+        normalized: z.ZodString;
+        candidates: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                fact: "fact";
+                entity: "entity";
+                page: "page";
+                document: "document";
+                event: "event";
+            }>;
+            slug: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            role: z.ZodOptional<z.ZodEnum<{
+                knowledge: "knowledge";
+                source: "source";
+                inference: "inference";
+                ignored: "ignored";
+            }>>;
+            entity: z.ZodOptional<z.ZodString>;
+            entity_type: z.ZodOptional<z.ZodEnum<{
+                event: "event";
+                person: "person";
+                organization: "organization";
+                place: "place";
+                product: "product";
+                concept: "concept";
+                other: "other";
+            }>>;
+            document: z.ZodOptional<z.ZodString>;
+            fact: z.ZodOptional<z.ZodString>;
+            event: z.ZodOptional<z.ZodString>;
+            date: z.ZodOptional<z.ZodString>;
+            line_start: z.ZodOptional<z.ZodNumber>;
+            line_end: z.ZodOptional<z.ZodNumber>;
+            availability: z.ZodOptional<z.ZodEnum<{
+                degraded: "degraded";
+                unavailable: "unavailable";
+                available: "available";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodEnum<{
+        seed_not_found: "seed_not_found";
+        no_paths: "no_paths";
+        graph_index_unreadable: "graph_index_unreadable";
+    }>>;
+}, z.core.$strip>;
+export type GraphOutput = z.infer<typeof GraphOutput>;
+export { GraphEvidenceLocator, GraphNodeRef, GraphRelation } from '../common.ts';
+export type { GraphNodeKind } from '../common.ts';
+//# sourceMappingURL=graph.d.ts.map

package/dist/ops/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/ops/graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,cAAc;;;;EAAgC,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,mFAAmF;AACnF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;iBAcnB,CAAC;AACL,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAavB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,eAAO,MAAM,SAAS;;;;;;;;iBAIpB,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;iBAOpB,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAIzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAStB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACjF,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}

package/dist/ops/graph.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { GraphEvidenceLocator, GraphNodeRef, GraphRelation, ResultEnvelope } from "../common.js";
+export const GraphDirection = z.enum(['out', 'in', 'both']);
+/** One exact seed form. Query seeds still resolve only evidence-declared names. */
+export const GraphInput = z
+    .object({
+    slug: z.string().trim().min(1).optional(),
+    entity: z.string().trim().min(1).optional(),
+    query: z.string().trim().min(1).optional(),
+    direction: GraphDirection.optional(),
+    relations: z.array(GraphRelation).min(1).max(GraphRelation.options.length).optional(),
+    max_hops: z.union([z.literal(1), z.literal(2), z.literal(3)]).optional(),
+    /** Maximum returned paths. Nodes, edges, and per-node fan-out have separate hard caps. */
+    limit: z.number().int().positive().max(100).optional(),
+    include_history: z.boolean().optional(),
+})
+    .refine((value) => [value.slug, value.entity, value.query].filter(Boolean).length === 1, {
+    message: 'graph requires exactly one of: slug, entity, query',
+});
+export const GraphEdgeRef = z.object({
+    id: z.string(),
+    from: z.string(),
+    to: z.string(),
+    relation: GraphRelation,
+    predicate: z.string().optional(),
+    confidence: z.number().min(0).max(1),
+    derivation: z.enum(['structural', 'fact']),
+    resolution: z.enum(['exact', 'contextual']),
+    evidence: GraphEvidenceLocator,
+    valid_from: z.string().optional(),
+    valid_to: z.string().optional(),
+    historical: z.boolean(),
+});
+export const GraphSeed = z.object({
+    form: z.enum(['slug', 'entity', 'query']),
+    value: z.string(),
+    node: z.string(),
+});
+export const GraphPath = z.object({
+    seed: z.string(),
+    nodes: z.array(z.string()).min(2).max(4),
+    edges: z.array(z.string()).min(1).max(3),
+    hops: z.number().int().positive().max(3),
+    confidence: z.number().min(0).max(1),
+    evidence: z.array(GraphEvidenceLocator).min(1).max(3),
+});
+export const GraphAmbiguity = z.object({
+    mention: z.string(),
+    normalized: z.string(),
+    candidates: z.array(GraphNodeRef),
+});
+export const GraphOutput = ResultEnvelope.extend({
+    seeds: z.array(GraphSeed),
+    nodes: z.array(GraphNodeRef),
+    edges: z.array(GraphEdgeRef),
+    paths: z.array(GraphPath),
+    ambiguities: z.array(GraphAmbiguity),
+    total: z.number().int().nonnegative(),
+    truncated: z.boolean(),
+    reason: z.enum(['seed_not_found', 'no_paths', 'graph_index_unreadable']).optional(),
+});
+export { GraphEvidenceLocator, GraphNodeRef, GraphRelation } from "../common.js";
+//# sourceMappingURL=graph.js.map