@eddacraft/anvil-kindling-integration 0.1.0

package/dist/query-contract.js

@@ -0,0 +1,314 @@
+/**
+ * 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';
+// =============================================================================
+// Schema Version
+// =============================================================================
+export const KINDLING_QUERY_CONTRACT_VERSION = '1.0.0';
+// =============================================================================
+// Query Scopes (Mandatory Boundary)
+// =============================================================================
+/**
+ * Every query must specify exactly one scope.
+ * No free-text search. No global scans. No cross-project reads.
+ */
+export const QueryScopeSchema = z.enum([
+    'session', // "What happened in this run?"
+    'plan', // "What happened because of this plan?"
+    'gate', // "Why did this gate pass/fail?"
+    'action', // "What exactly did this action do?"
+]);
+// =============================================================================
+// Result Shape
+// =============================================================================
+/**
+ * How results should be structured
+ */
+export const ResultShapeSchema = z.enum([
+    'timeline', // Ordered observations grouped by phase
+    'list', // Flat list of observations
+    'entity', // Single entity with metadata
+]);
+// =============================================================================
+// Output Format
+// =============================================================================
+/**
+ * Result serialisation format
+ */
+export const OutputFormatSchema = z.enum([
+    'json', // Machine-readable
+    'text', // Human-readable (for CLI)
+]);
+// =============================================================================
+// Query Request (Base)
+// =============================================================================
+/**
+ * Base query request with mandatory constraints
+ */
+export const QueryRequestBaseSchema = z.object({
+    scope: QueryScopeSchema.describe('Query scope (mandatory)'),
+    shape: ResultShapeSchema.describe('Result structure (mandatory)'),
+    format: OutputFormatSchema.default('json').describe('Output format'),
+    // Time bounds (optional but encouraged)
+    time_after: z.string().datetime().optional().describe('Include observations after this time'),
+    time_before: z.string().datetime().optional().describe('Include observations before this time'),
+    // Result limits (anti-vacuum-cleaner)
+    max_results: z
+        .number()
+        .int()
+        .positive()
+        .max(1000)
+        .default(100)
+        .describe('Maximum observations to return'),
+    max_payload_bytes: z
+        .number()
+        .int()
+        .positive()
+        .max(10 * 1024 * 1024) // 10MB
+        .default(1024 * 1024) // 1MB
+        .describe('Maximum total payload size'),
+});
+// =============================================================================
+// Session Query
+// =============================================================================
+/**
+ * Query: "What happened in this run?"
+ *
+ * Returns ordered observations grouped by phase (plan / gate / action / outcome).
+ * Raw payloads only, no summaries.
+ */
+export const SessionQuerySchema = QueryRequestBaseSchema.extend({
+    scope: z.literal('session'),
+    session_id: z.string().uuid().describe('Session/run ID (mandatory)'),
+    include_phases: z
+        .array(z.enum(['plan', 'gate', 'action', 'outcome', 'error']))
+        .optional()
+        .describe('Filter to specific phases'),
+});
+// =============================================================================
+// Plan Query
+// =============================================================================
+/**
+ * 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 const PlanQuerySchema = QueryRequestBaseSchema.extend({
+    scope: z.literal('plan'),
+    plan_id: z.string().describe('Plan ID (mandatory)'),
+    include_executions: z.boolean().default(true).describe('Include linked execution run IDs'),
+    include_versions: z.boolean().default(true).describe('Include plan version history'),
+});
+// =============================================================================
+// Gate Query
+// =============================================================================
+/**
+ * Query: "Why did this gate pass/fail?"
+ *
+ * Returns gate evaluation details with rule IDs, inputs (sanitised), and outcomes.
+ * No prose. No explanation layer.
+ */
+export const GateQuerySchema = QueryRequestBaseSchema.extend({
+    scope: z.literal('gate'),
+    gate_eval_id: z.string().describe('Gate evaluation ID (mandatory)'),
+});
+// =============================================================================
+// Action Query
+// =============================================================================
+/**
+ * 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 const ActionQuerySchema = QueryRequestBaseSchema.extend({
+    scope: z.literal('action'),
+    action_id: z.string().describe('Action ID (mandatory)'),
+    include_approval_chain: z
+        .boolean()
+        .default(true)
+        .describe('Include approval requirements and state'),
+});
+// =============================================================================
+// Query Request (Union)
+// =============================================================================
+/**
+ * All query types (discriminated union)
+ */
+export const QueryRequestSchema = z.discriminatedUnion('scope', [
+    SessionQuerySchema,
+    PlanQuerySchema,
+    GateQuerySchema,
+    ActionQuerySchema,
+]);
+// =============================================================================
+// Query Response (Output Guarantees)
+// =============================================================================
+/**
+ * Standard metadata for all responses
+ */
+export const QueryResponseMetadataSchema = z.object({
+    query_id: z.string().uuid().describe('Unique query identifier (for debugging)'),
+    executed_at: z.string().datetime().describe('When query was executed'),
+    contract_version: z.string().describe('Query contract version used'),
+    result_count: z.number().int().nonnegative().describe('Number of observations returned'),
+    truncated: z.boolean().describe('Whether results were truncated (hit limits)'),
+    truncation_reason: z
+        .enum(['max_results', 'max_payload_bytes', 'none'])
+        .optional()
+        .describe('Why truncation occurred'),
+});
+/**
+ * Standard provenance link
+ */
+export const ProvenanceLinkSchema = z.object({
+    type: z.enum(['caused_by', 'governed_by', 'approved_by', 'linked_to']).describe('Link type'),
+    entity_type: z
+        .enum(['session', 'plan', 'gate', 'action', 'human'])
+        .describe('Target entity type'),
+    entity_id: z.string().describe('Target entity ID'),
+    timestamp: z.string().datetime().describe('When link was created'),
+});
+/**
+ * Observation (base type for all returned data)
+ */
+export const ObservationSchema = z.object({
+    id: z.string().uuid().describe('Observation ID'),
+    kind: z
+        .enum([
+        'session_start',
+        'session_end',
+        'plan_created',
+        'plan_edited',
+        'plan_approved',
+        'plan_rejected',
+        'gate_evaluated',
+        'action_executed',
+        'constraint_applied',
+        'human_input',
+        'error',
+    ])
+        .describe('Observation kind'),
+    timestamp: z.string().datetime().describe('When observation was recorded'),
+    session_id: z.string().uuid().describe('Session this observation belongs to'),
+    // Provenance (explicit links)
+    provenance: z.array(ProvenanceLinkSchema).describe('Explicit links to other entities'),
+    // Payload (fact data, no inference)
+    payload: z.record(z.string(), z.unknown()).describe('Observation-specific data (raw facts only)'),
+});
+/**
+ * Query response
+ */
+export const QueryResponseSchema = z.object({
+    metadata: QueryResponseMetadataSchema.describe('Query execution metadata'),
+    observations: z.array(ObservationSchema).describe('Ordered observations (facts only)'),
+});
+// =============================================================================
+// Output Guarantees (Documented Requirements)
+// =============================================================================
+/**
+ * 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.
+ */
+// =============================================================================
+// Read-Only Enforcement (Anti-Pattern Markers)
+// =============================================================================
+/**
+ * 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.
+ */
+// =============================================================================
+// Explicit Non-Goals (v1 Boundary)
+// =============================================================================
+/**
+ * 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.
+ */
+// =============================================================================
+// Validation Utilities
+// =============================================================================
+/**
+ * Validate a query request
+ */
+export function validateQueryRequest(data) {
+    const result = QueryRequestSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error.format()._errors.join(', ') };
+}
+/**
+ * Validate a query response
+ */
+export function validateQueryResponse(data) {
+    const result = QueryResponseSchema.safeParse(data);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error.format()._errors.join(', ') };
+}
+// =============================================================================
+// CLI Command Mapping (Human-First, AI-Compatible)
+// =============================================================================
+/**
+ * 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.
+ */

package/dist/query-limits.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Query Limits Enforcement (KINDLING-010)
+ *
+ * Provides post-query truncation and metadata flagging.
+ * Used by KindlingQueryService before returning results to callers,
+ * as a defense-in-depth layer on top of store-level limits.
+ */
+import type { QueryResponse } from './query-contract.js';
+import type { QueryLimitConfig } from './config.js';
+/**
+ * Limits to enforce on a query response
+ */
+export interface QueryLimits {
+    /** Maximum number of observations to return */
+    max_results: number;
+    /** Maximum total payload size in bytes */
+    max_payload_bytes: number;
+}
+/**
+ * Enforce query limits on a response by truncating results if necessary.
+ *
+ * This is applied after the store returns results, as a safety net.
+ * If the store already respects limits, this is a no-op.
+ *
+ * Sets the `truncated` and `truncation_reason` metadata flags when
+ * results are truncated.
+ *
+ * @param response - The query response from the store
+ * @param limits - The limits to enforce
+ * @returns A new QueryResponse with limits enforced
+ */
+export declare function enforceQueryLimits(response: QueryResponse, limits: QueryLimits): QueryResponse;
+/**
+ * Create QueryLimits from a QueryLimitConfig.
+ *
+ * @param config - Query limit configuration
+ * @returns QueryLimits object
+ */
+export declare function limitsFromConfig(config: QueryLimitConfig): QueryLimits;
+//# sourceMappingURL=query-limits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-limits.d.ts","sourceRoot":"","sources":["../src/query-limits.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAyB,MAAM,qBAAqB,CAAC;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAMpD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,GAAG,aAAa,CAkD9F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,WAAW,CAKtE"}

package/dist/query-limits.js

@@ -0,0 +1,79 @@
+/**
+ * Query Limits Enforcement (KINDLING-010)
+ *
+ * Provides post-query truncation and metadata flagging.
+ * Used by KindlingQueryService before returning results to callers,
+ * as a defense-in-depth layer on top of store-level limits.
+ */
+// =============================================================================
+// Enforcement
+// =============================================================================
+/**
+ * Enforce query limits on a response by truncating results if necessary.
+ *
+ * This is applied after the store returns results, as a safety net.
+ * If the store already respects limits, this is a no-op.
+ *
+ * Sets the `truncated` and `truncation_reason` metadata flags when
+ * results are truncated.
+ *
+ * @param response - The query response from the store
+ * @param limits - The limits to enforce
+ * @returns A new QueryResponse with limits enforced
+ */
+export function enforceQueryLimits(response, limits) {
+    let observations = response.observations;
+    let truncated = response.metadata.truncated;
+    let truncationReason = response.metadata.truncation_reason;
+    // Check max_results
+    if (observations.length > limits.max_results) {
+        observations = observations.slice(0, limits.max_results);
+        truncated = true;
+        truncationReason = 'max_results';
+    }
+    // Check max_payload_bytes
+    const serialized = JSON.stringify(observations);
+    const payloadBytes = new TextEncoder().encode(serialized).byteLength;
+    if (payloadBytes > limits.max_payload_bytes) {
+        // Binary search for the maximum number of observations that fit
+        let lo = 0;
+        let hi = observations.length;
+        while (lo < hi) {
+            const mid = Math.floor((lo + hi + 1) / 2);
+            const slice = observations.slice(0, mid);
+            const sliceBytes = new TextEncoder().encode(JSON.stringify(slice)).byteLength;
+            if (sliceBytes <= limits.max_payload_bytes) {
+                lo = mid;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        observations = observations.slice(0, lo);
+        truncated = true;
+        // Only override reason if not already set (max_results takes precedence)
+        truncationReason = truncationReason === 'max_results' ? 'max_results' : 'max_payload_bytes';
+    }
+    const metadata = {
+        ...response.metadata,
+        result_count: observations.length,
+        truncated,
+        truncation_reason: truncated ? truncationReason : 'none',
+    };
+    return {
+        metadata,
+        observations,
+    };
+}
+/**
+ * Create QueryLimits from a QueryLimitConfig.
+ *
+ * @param config - Query limit configuration
+ * @returns QueryLimits object
+ */
+export function limitsFromConfig(config) {
+    return {
+        max_results: config.max_results,
+        max_payload_bytes: config.max_payload_bytes,
+    };
+}

package/dist/query-service.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Kindling Query Service (KINDLING-009)
+ *
+ * High-level query interface that wraps KindlingService.query() with
+ * convenience methods for each query scope. Applies query limit enforcement
+ * before returning results.
+ *
+ * This is the primary read API for Anvil CLI commands and tooling.
+ */
+import type { KindlingService } from './kindling-service.js';
+import type { QueryResponse, ResultShape, OutputFormat } from './query-contract.js';
+/**
+ * Common options for all query methods
+ */
+export interface QueryOptions {
+    /** Result structure (default: 'list') */
+    shape?: ResultShape;
+    /** Output format (default: 'json') */
+    format?: OutputFormat;
+    /** Include observations after this time */
+    time_after?: string;
+    /** Include observations before this time */
+    time_before?: string;
+    /** Maximum observations to return (capped by config) */
+    max_results?: number;
+    /** Maximum total payload size in bytes (capped by config) */
+    max_payload_bytes?: number;
+}
+/**
+ * Options specific to session queries
+ */
+export interface SessionQueryOptions extends QueryOptions {
+    /** Filter to specific phases */
+    include_phases?: Array<'plan' | 'gate' | 'action' | 'outcome' | 'error'>;
+}
+/**
+ * Options specific to plan queries
+ */
+export interface PlanQueryOptions extends QueryOptions {
+    /** Include linked execution run IDs (default: true) */
+    include_executions?: boolean;
+    /** Include plan version history (default: true) */
+    include_versions?: boolean;
+}
+/**
+ * Options specific to action queries
+ */
+export interface ActionQueryOptions extends QueryOptions {
+    /** Include approval chain (default: true) */
+    include_approval_chain?: boolean;
+}
+/**
+ * High-level query service for Kindling observations.
+ *
+ * Provides typed convenience methods for each query scope and enforces
+ * query limits from the service configuration.
+ */
+export declare class KindlingQueryService {
+    private readonly service;
+    constructor(service: KindlingService);
+    /**
+     * Query: "What happened in this run?"
+     *
+     * Returns ordered observations for a specific session, optionally
+     * filtered by phase.
+     *
+     * @param sessionId - Session/run ID
+     * @param options - Query options
+     * @returns Query response with session observations
+     */
+    querySession(sessionId: string, options?: SessionQueryOptions): Promise<QueryResponse>;
+    /**
+     * Query: "What happened because of this plan?"
+     *
+     * Returns plan metadata, versions, and linked executions.
+     * This is the only cross-session read allowed.
+     *
+     * @param planId - Plan ID
+     * @param options - Query options
+     * @returns Query response with plan observations
+     */
+    queryPlan(planId: string, options?: PlanQueryOptions): Promise<QueryResponse>;
+    /**
+     * Query: "Why did this gate pass/fail?"
+     *
+     * Returns gate evaluation details with rule IDs, inputs, and outcomes.
+     *
+     * @param gateEvalId - Gate evaluation ID
+     * @param options - Query options
+     * @returns Query response with gate observations
+     */
+    queryGate(gateEvalId: string, options?: QueryOptions): Promise<QueryResponse>;
+    /**
+     * Query: "What exactly did this action do?"
+     *
+     * Returns action execution details with redacted command, environment,
+     * and linked governance.
+     *
+     * @param actionId - Action ID
+     * @param options - Query options
+     * @returns Query response with action observations
+     */
+    queryAction(actionId: string, options?: ActionQueryOptions): Promise<QueryResponse>;
+    /**
+     * Apply query limits from the service configuration as a defense-in-depth layer.
+     */
+    private applyLimits;
+}
+//# sourceMappingURL=query-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-service.d.ts","sourceRoot":"","sources":["../src/query-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EACV,aAAa,EAKb,WAAW,EACX,YAAY,EACb,MAAM,qBAAqB,CAAC;AAU7B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sCAAsC;IACtC,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,gCAAgC;IAChC,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC;CAC1E;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD,6CAA6C;IAC7C,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAMD;;;;;GAKG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;gBAE9B,OAAO,EAAE,eAAe;IAIpC;;;;;;;;;OASG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC;IAmBhG;;;;;;;;;OASG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC;IAoBvF;;;;;;;;OAQG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAkBvF;;;;;;;;;OASG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC;IAuB7F;;OAEG;IACH,OAAO,CAAC,WAAW;CAIpB"}

package/dist/query-service.js

@@ -0,0 +1,140 @@
+/**
+ * Kindling Query Service (KINDLING-009)
+ *
+ * High-level query interface that wraps KindlingService.query() with
+ * convenience methods for each query scope. Applies query limit enforcement
+ * before returning results.
+ *
+ * This is the primary read API for Anvil CLI commands and tooling.
+ */
+import { enforceQueryLimits, limitsFromConfig } from './query-limits.js';
+import { createDebugger } from './utils/debug.js';
+const debug = createDebugger('kindling');
+// =============================================================================
+// Query Service
+// =============================================================================
+/**
+ * High-level query service for Kindling observations.
+ *
+ * Provides typed convenience methods for each query scope and enforces
+ * query limits from the service configuration.
+ */
+export class KindlingQueryService {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    /**
+     * Query: "What happened in this run?"
+     *
+     * Returns ordered observations for a specific session, optionally
+     * filtered by phase.
+     *
+     * @param sessionId - Session/run ID
+     * @param options - Query options
+     * @returns Query response with session observations
+     */
+    async querySession(sessionId, options = {}) {
+        debug('querySession', { sessionId, shape: options.shape });
+        const request = {
+            scope: 'session',
+            session_id: sessionId,
+            shape: options.shape ?? 'timeline',
+            format: options.format ?? 'json',
+            time_after: options.time_after,
+            time_before: options.time_before,
+            max_results: options.max_results ?? this.service.configuration.query_limits.max_results,
+            max_payload_bytes: options.max_payload_bytes ?? this.service.configuration.query_limits.max_payload_bytes,
+            include_phases: options.include_phases,
+        };
+        const response = await this.service.query(request);
+        return this.applyLimits(response);
+    }
+    /**
+     * Query: "What happened because of this plan?"
+     *
+     * Returns plan metadata, versions, and linked executions.
+     * This is the only cross-session read allowed.
+     *
+     * @param planId - Plan ID
+     * @param options - Query options
+     * @returns Query response with plan observations
+     */
+    async queryPlan(planId, options = {}) {
+        debug('queryPlan', { planId, shape: options.shape });
+        const request = {
+            scope: 'plan',
+            plan_id: planId,
+            shape: options.shape ?? 'entity',
+            format: options.format ?? 'json',
+            time_after: options.time_after,
+            time_before: options.time_before,
+            max_results: options.max_results ?? this.service.configuration.query_limits.max_results,
+            max_payload_bytes: options.max_payload_bytes ?? this.service.configuration.query_limits.max_payload_bytes,
+            include_executions: options.include_executions ?? true,
+            include_versions: options.include_versions ?? true,
+        };
+        const response = await this.service.query(request);
+        return this.applyLimits(response);
+    }
+    /**
+     * Query: "Why did this gate pass/fail?"
+     *
+     * Returns gate evaluation details with rule IDs, inputs, and outcomes.
+     *
+     * @param gateEvalId - Gate evaluation ID
+     * @param options - Query options
+     * @returns Query response with gate observations
+     */
+    async queryGate(gateEvalId, options = {}) {
+        debug('queryGate', { gateEvalId });
+        const request = {
+            scope: 'gate',
+            gate_eval_id: gateEvalId,
+            shape: options.shape ?? 'entity',
+            format: options.format ?? 'json',
+            time_after: options.time_after,
+            time_before: options.time_before,
+            max_results: options.max_results ?? this.service.configuration.query_limits.max_results,
+            max_payload_bytes: options.max_payload_bytes ?? this.service.configuration.query_limits.max_payload_bytes,
+        };
+        const response = await this.service.query(request);
+        return this.applyLimits(response);
+    }
+    /**
+     * Query: "What exactly did this action do?"
+     *
+     * Returns action execution details with redacted command, environment,
+     * and linked governance.
+     *
+     * @param actionId - Action ID
+     * @param options - Query options
+     * @returns Query response with action observations
+     */
+    async queryAction(actionId, options = {}) {
+        debug('queryAction', { actionId });
+        const request = {
+            scope: 'action',
+            action_id: actionId,
+            shape: options.shape ?? 'entity',
+            format: options.format ?? 'json',
+            time_after: options.time_after,
+            time_before: options.time_before,
+            max_results: options.max_results ?? this.service.configuration.query_limits.max_results,
+            max_payload_bytes: options.max_payload_bytes ?? this.service.configuration.query_limits.max_payload_bytes,
+            include_approval_chain: options.include_approval_chain ?? true,
+        };
+        const response = await this.service.query(request);
+        return this.applyLimits(response);
+    }
+    // ===========================================================================
+    // Private
+    // ===========================================================================
+    /**
+     * Apply query limits from the service configuration as a defense-in-depth layer.
+     */
+    applyLimits(response) {
+        const limits = limitsFromConfig(this.service.configuration.query_limits);
+        return enforceQueryLimits(response, limits);
+    }
+}