@eddacraft/anvil-kindling-integration 0.1.0

package/dist/query-contract.d.ts

@@ -0,0 +1,463 @@
+/**
+ * Kindling Query Contract (v1)
+ *
+ * Defines the read-only, bounded query surface for Kindling observations.
+ * This is a system of record, not a reasoning engine.
+ *
+ * GOVERNING RULE:
+ * Queries may retrieve facts; interpretation is the caller's responsibility.
+ * User-supplied AI may read, but may not mutate, infer, or generalise via Kindling.
+ *
+ * @see plans/modules/kindling-integration.aps.md for integration plan
+ */
+import { z } from 'zod';
+export declare const KINDLING_QUERY_CONTRACT_VERSION = "1.0.0";
+/**
+ * Every query must specify exactly one scope.
+ * No free-text search. No global scans. No cross-project reads.
+ */
+export declare const QueryScopeSchema: z.ZodEnum<{
+    session: "session";
+    plan: "plan";
+    gate: "gate";
+    action: "action";
+}>;
+export type QueryScope = z.infer<typeof QueryScopeSchema>;
+/**
+ * How results should be structured
+ */
+export declare const ResultShapeSchema: z.ZodEnum<{
+    timeline: "timeline";
+    list: "list";
+    entity: "entity";
+}>;
+export type ResultShape = z.infer<typeof ResultShapeSchema>;
+/**
+ * Result serialisation format
+ */
+export declare const OutputFormatSchema: z.ZodEnum<{
+    json: "json";
+    text: "text";
+}>;
+export type OutputFormat = z.infer<typeof OutputFormatSchema>;
+/**
+ * Base query request with mandatory constraints
+ */
+export declare const QueryRequestBaseSchema: z.ZodObject<{
+    scope: z.ZodEnum<{
+        session: "session";
+        plan: "plan";
+        gate: "gate";
+        action: "action";
+    }>;
+    shape: z.ZodEnum<{
+        timeline: "timeline";
+        list: "list";
+        entity: "entity";
+    }>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>>;
+    time_after: z.ZodOptional<z.ZodString>;
+    time_before: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    max_payload_bytes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type QueryRequestBase = z.infer<typeof QueryRequestBaseSchema>;
+/**
+ * Query: "What happened in this run?"
+ *
+ * Returns ordered observations grouped by phase (plan / gate / action / outcome).
+ * Raw payloads only, no summaries.
+ */
+export declare const SessionQuerySchema: z.ZodObject<{
+    shape: z.ZodEnum<{
+        timeline: "timeline";
+        list: "list";
+        entity: "entity";
+    }>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>>;
+    time_after: z.ZodOptional<z.ZodString>;
+    time_before: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    max_payload_bytes: z.ZodDefault<z.ZodNumber>;
+    scope: z.ZodLiteral<"session">;
+    session_id: z.ZodString;
+    include_phases: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        outcome: "outcome";
+        error: "error";
+        plan: "plan";
+        gate: "gate";
+        action: "action";
+    }>>>;
+}, z.core.$strip>;
+export type SessionQuery = z.infer<typeof SessionQuerySchema>;
+/**
+ * Query: "What happened because of this plan?"
+ *
+ * Returns plan metadata, versions, and linked executions.
+ * This is the ONLY cross-session read allowed, via explicit plan_id.
+ */
+export declare const PlanQuerySchema: z.ZodObject<{
+    shape: z.ZodEnum<{
+        timeline: "timeline";
+        list: "list";
+        entity: "entity";
+    }>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>>;
+    time_after: z.ZodOptional<z.ZodString>;
+    time_before: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    max_payload_bytes: z.ZodDefault<z.ZodNumber>;
+    scope: z.ZodLiteral<"plan">;
+    plan_id: z.ZodString;
+    include_executions: z.ZodDefault<z.ZodBoolean>;
+    include_versions: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PlanQuery = z.infer<typeof PlanQuerySchema>;
+/**
+ * Query: "Why did this gate pass/fail?"
+ *
+ * Returns gate evaluation details with rule IDs, inputs (sanitised), and outcomes.
+ * No prose. No explanation layer.
+ */
+export declare const GateQuerySchema: z.ZodObject<{
+    shape: z.ZodEnum<{
+        timeline: "timeline";
+        list: "list";
+        entity: "entity";
+    }>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>>;
+    time_after: z.ZodOptional<z.ZodString>;
+    time_before: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    max_payload_bytes: z.ZodDefault<z.ZodNumber>;
+    scope: z.ZodLiteral<"gate">;
+    gate_eval_id: z.ZodString;
+}, z.core.$strip>;
+export type GateQuery = z.infer<typeof GateQuerySchema>;
+/**
+ * Query: "What exactly did this action do?"
+ *
+ * Returns action details with redacted command, environment, and linked governance.
+ * This is the atomic unit of accountability.
+ */
+export declare const ActionQuerySchema: z.ZodObject<{
+    shape: z.ZodEnum<{
+        timeline: "timeline";
+        list: "list";
+        entity: "entity";
+    }>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>>;
+    time_after: z.ZodOptional<z.ZodString>;
+    time_before: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    max_payload_bytes: z.ZodDefault<z.ZodNumber>;
+    scope: z.ZodLiteral<"action">;
+    action_id: z.ZodString;
+    include_approval_chain: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ActionQuery = z.infer<typeof ActionQuerySchema>;
+/**
+ * All query types (discriminated union)
+ */
+export declare const QueryRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    shape: z.ZodEnum<{
+        timeline: "timeline";
+        list: "list";
+        entity: "entity";
+    }>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>>;
+    time_after: z.ZodOptional<z.ZodString>;
+    time_before: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    max_payload_bytes: z.ZodDefault<z.ZodNumber>;
+    scope: z.ZodLiteral<"session">;
+    session_id: z.ZodString;
+    include_phases: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        outcome: "outcome";
+        error: "error";
+        plan: "plan";
+        gate: "gate";
+        action: "action";
+    }>>>;
+}, z.core.$strip>, z.ZodObject<{
+    shape: z.ZodEnum<{
+        timeline: "timeline";
+        list: "list";
+        entity: "entity";
+    }>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>>;
+    time_after: z.ZodOptional<z.ZodString>;
+    time_before: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    max_payload_bytes: z.ZodDefault<z.ZodNumber>;
+    scope: z.ZodLiteral<"plan">;
+    plan_id: z.ZodString;
+    include_executions: z.ZodDefault<z.ZodBoolean>;
+    include_versions: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+    shape: z.ZodEnum<{
+        timeline: "timeline";
+        list: "list";
+        entity: "entity";
+    }>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>>;
+    time_after: z.ZodOptional<z.ZodString>;
+    time_before: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    max_payload_bytes: z.ZodDefault<z.ZodNumber>;
+    scope: z.ZodLiteral<"gate">;
+    gate_eval_id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    shape: z.ZodEnum<{
+        timeline: "timeline";
+        list: "list";
+        entity: "entity";
+    }>;
+    format: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        text: "text";
+    }>>;
+    time_after: z.ZodOptional<z.ZodString>;
+    time_before: z.ZodOptional<z.ZodString>;
+    max_results: z.ZodDefault<z.ZodNumber>;
+    max_payload_bytes: z.ZodDefault<z.ZodNumber>;
+    scope: z.ZodLiteral<"action">;
+    action_id: z.ZodString;
+    include_approval_chain: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>], "scope">;
+export type QueryRequest = z.infer<typeof QueryRequestSchema>;
+/**
+ * Standard metadata for all responses
+ */
+export declare const QueryResponseMetadataSchema: z.ZodObject<{
+    query_id: z.ZodString;
+    executed_at: z.ZodString;
+    contract_version: z.ZodString;
+    result_count: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    truncation_reason: z.ZodOptional<z.ZodEnum<{
+        max_results: "max_results";
+        max_payload_bytes: "max_payload_bytes";
+        none: "none";
+    }>>;
+}, z.core.$strip>;
+export type QueryResponseMetadata = z.infer<typeof QueryResponseMetadataSchema>;
+/**
+ * Standard provenance link
+ */
+export declare const ProvenanceLinkSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        approved_by: "approved_by";
+        caused_by: "caused_by";
+        governed_by: "governed_by";
+        linked_to: "linked_to";
+    }>;
+    entity_type: z.ZodEnum<{
+        human: "human";
+        session: "session";
+        plan: "plan";
+        gate: "gate";
+        action: "action";
+    }>;
+    entity_id: z.ZodString;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type ProvenanceLink = z.infer<typeof ProvenanceLinkSchema>;
+/**
+ * Observation (base type for all returned data)
+ */
+export declare const ObservationSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        session_start: "session_start";
+        session_end: "session_end";
+        error: "error";
+        plan_created: "plan_created";
+        plan_edited: "plan_edited";
+        plan_approved: "plan_approved";
+        plan_rejected: "plan_rejected";
+        action_executed: "action_executed";
+        gate_evaluated: "gate_evaluated";
+        constraint_applied: "constraint_applied";
+        human_input: "human_input";
+    }>;
+    timestamp: z.ZodString;
+    session_id: z.ZodString;
+    provenance: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            approved_by: "approved_by";
+            caused_by: "caused_by";
+            governed_by: "governed_by";
+            linked_to: "linked_to";
+        }>;
+        entity_type: z.ZodEnum<{
+            human: "human";
+            session: "session";
+            plan: "plan";
+            gate: "gate";
+            action: "action";
+        }>;
+        entity_id: z.ZodString;
+        timestamp: z.ZodString;
+    }, z.core.$strip>>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type Observation = z.infer<typeof ObservationSchema>;
+/**
+ * Query response
+ */
+export declare const QueryResponseSchema: z.ZodObject<{
+    metadata: z.ZodObject<{
+        query_id: z.ZodString;
+        executed_at: z.ZodString;
+        contract_version: z.ZodString;
+        result_count: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        truncation_reason: z.ZodOptional<z.ZodEnum<{
+            max_results: "max_results";
+            max_payload_bytes: "max_payload_bytes";
+            none: "none";
+        }>>;
+    }, z.core.$strip>;
+    observations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            session_start: "session_start";
+            session_end: "session_end";
+            error: "error";
+            plan_created: "plan_created";
+            plan_edited: "plan_edited";
+            plan_approved: "plan_approved";
+            plan_rejected: "plan_rejected";
+            action_executed: "action_executed";
+            gate_evaluated: "gate_evaluated";
+            constraint_applied: "constraint_applied";
+            human_input: "human_input";
+        }>;
+        timestamp: z.ZodString;
+        session_id: z.ZodString;
+        provenance: z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                approved_by: "approved_by";
+                caused_by: "caused_by";
+                governed_by: "governed_by";
+                linked_to: "linked_to";
+            }>;
+            entity_type: z.ZodEnum<{
+                human: "human";
+                session: "session";
+                plan: "plan";
+                gate: "gate";
+                action: "action";
+            }>;
+            entity_id: z.ZodString;
+            timestamp: z.ZodString;
+        }, z.core.$strip>>;
+        payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type QueryResponse = z.infer<typeof QueryResponseSchema>;
+/**
+ * Every Kindling response guarantees:
+ *
+ * 1. Stable field names - No field names change between queries
+ * 2. Explicit timestamps - Every observation has ISO8601 timestamp
+ * 3. Explicit links - Provenance via typed links (caused_by, governed_by, approved_by)
+ * 4. No hidden inference - Payload contains only raw facts
+ * 5. No reordered history - Observations returned in recorded order
+ *
+ * This makes Kindling LLM-safe by construction.
+ *
+ * AI can:
+ * - Narrate events
+ * - Summarise outcomes
+ * - Explain facts
+ *
+ * But AI will always be explaining facts, not ghosts.
+ */
+/**
+ * Operations that MUST NOT exist in the query API:
+ *
+ * ❌ write()
+ * ❌ update()
+ * ❌ delete()
+ * ❌ annotate()
+ * ❌ tag()
+ * ❌ learn()
+ * ❌ embed()
+ * ❌ infer()
+ *
+ * If user AI wants memory, it must bring its own store.
+ */
+/**
+ * The following are explicitly OUT OF SCOPE for v1:
+ *
+ * ❌ Semantic search
+ * ❌ Similarity queries
+ * ❌ Embeddings
+ * ❌ Cross-plan discovery
+ * ❌ Learned relevance
+ * ❌ Auto-summaries (stored in Kindling)
+ * ❌ AI-generated annotations stored in Kindling
+ *
+ * These belong to Edda / Ember, not Kindling v1.
+ */
+/**
+ * Validate a query request
+ */
+export declare function validateQueryRequest(data: unknown): {
+    success: boolean;
+    data?: QueryRequest;
+    error?: string;
+};
+/**
+ * Validate a query response
+ */
+export declare function validateQueryResponse(data: unknown): {
+    success: boolean;
+    data?: QueryResponse;
+    error?: string;
+};
+/**
+ * All queries have CLI equivalents:
+ *
+ * anvil run show <run_id> --json
+ * → SessionQuery { scope: 'session', session_id: run_id, shape: 'timeline' }
+ *
+ * anvil plan trace <plan_id> --json
+ * → PlanQuery { scope: 'plan', plan_id: plan_id, shape: 'entity' }
+ *
+ * anvil gate show <gate_eval_id> --json
+ * → GateQuery { scope: 'gate', gate_eval_id: gate_eval_id, shape: 'entity' }
+ *
+ * anvil action show <action_id> --json
+ * → ActionQuery { scope: 'action', action_id: action_id, shape: 'entity' }
+ *
+ * The CLI is a thin wrapper over this query surface.
+ * That symmetry is intentional.
+ */
+//# sourceMappingURL=query-contract.d.ts.map

package/dist/query-contract.d.ts.map

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