@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

package/src/domains/trace/tracePlugin.ts

@@ -0,0 +1,159 @@
+/**
+ * KE plugin for query access tracing.
+ *
+ * Intercepts `onQuery` and `onResult` hooks to record every
+ * `store.query()` call as an NDJSON line in a session-scoped log file.
+ *
+ * Activation: conditional — only instantiated when `PRAGMA_TRACE=1` or
+ * `trace: true` in pragma.config.json.
+ * Correlation: closure variable `pending` — safe because KE calls
+ * `onQuery` → Oxigraph WASM (sync) → `onResult` with no interleaving.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { definePlugin } from "@canonical/ke";
+import type { TraceApi, TracePluginOptions, TraceRecord } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// FNV-1a 32-bit hash
+// ---------------------------------------------------------------------------
+
+const FNV_OFFSET = 0x811c9dc5;
+const FNV_PRIME = 0x01000193;
+
+function fnv1a(input: string): string {
+  let hash = FNV_OFFSET;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+// ---------------------------------------------------------------------------
+// Session ID generation
+// ---------------------------------------------------------------------------
+
+function generateSessionId(): string {
+  const now = new Date();
+  const date = [
+    now.getFullYear(),
+    String(now.getMonth() + 1).padStart(2, "0"),
+    String(now.getDate()).padStart(2, "0"),
+  ].join("");
+  const time = [
+    String(now.getHours()).padStart(2, "0"),
+    String(now.getMinutes()).padStart(2, "0"),
+    String(now.getSeconds()).padStart(2, "0"),
+  ].join("");
+  const rand = Math.random().toString(16).slice(2, 6);
+  return `${date}-${time}-${rand}`;
+}
+
+// ---------------------------------------------------------------------------
+// Record builder
+// ---------------------------------------------------------------------------
+
+function buildRecord(
+  sessionId: string,
+  seq: number,
+  sparql: string,
+  startMs: number,
+  result: import("@canonical/ke").QueryResult,
+  maxBindings: number,
+): TraceRecord {
+  const ms = Math.round((performance.now() - startMs) * 100) / 100;
+  const qh = fnv1a(sparql);
+
+  const base = {
+    ts: new Date().toISOString(),
+    sid: sessionId,
+    seq,
+    qh,
+    q: sparql,
+    ms,
+  };
+
+  switch (result.type) {
+    case "select":
+      return {
+        ...base,
+        type: "select",
+        count: result.bindings.length,
+        vars: result.variables,
+        bindings: result.bindings.slice(0, maxBindings),
+      };
+    case "construct":
+      return {
+        ...base,
+        type: "construct",
+        count: result.triples.length,
+        triples: result.triples.slice(0, maxBindings).map((t) => ({
+          s: t.subject,
+          p: t.predicate,
+          o: t.object,
+        })),
+      };
+    case "ask":
+      return {
+        ...base,
+        type: "ask",
+        count: 1,
+        ask: result.result,
+      };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plugin factory
+// ---------------------------------------------------------------------------
+
+export function createTracePlugin(options: TracePluginOptions) {
+  const maxBindings = options.maxBindings ?? 200;
+  const sessionId = options.sessionId ?? generateSessionId();
+  const logPath = join(options.traceDir, `${sessionId}.ndjson`);
+
+  let seq = 0;
+  let pendingQuery: string | undefined;
+  let pendingStart: number | undefined;
+
+  return definePlugin<TraceApi>({
+    name: "trace",
+
+    onReady() {
+      mkdirSync(options.traceDir, { recursive: true });
+      return {
+        sessionId,
+        logPath,
+        get queryCount() {
+          return seq;
+        },
+      };
+    },
+
+    onQuery(sparql) {
+      pendingQuery = sparql;
+      pendingStart = performance.now();
+      return undefined;
+    },
+
+    onResult(result) {
+      if (pendingQuery !== undefined && pendingStart !== undefined) {
+        const record = buildRecord(
+          sessionId,
+          seq,
+          pendingQuery,
+          pendingStart,
+          result,
+          maxBindings,
+        );
+        appendFileSync(logPath, `${JSON.stringify(record)}\n`);
+        seq++;
+        pendingQuery = undefined;
+        pendingStart = undefined;
+      }
+      return undefined;
+    },
+  });
+}

package/src/domains/trace/types.ts

@@ -0,0 +1,65 @@
+/**
+ * Types for query access tracing.
+ *
+ * One NDJSON record per `store.query()` call. The trace plugin writes
+ * these to session-scoped log files; the CLI reads them back.
+ */
+
+/** A single trace record — one per store.query() call. */
+export interface TraceRecord {
+  /** ISO-8601 timestamp. */
+  ts: string;
+  /** Session identifier. */
+  sid: string;
+  /** Monotonic query index within the session. */
+  seq: number;
+  /** FNV-1a hash of the query string (8 hex chars). */
+  qh: string;
+  /** SPARQL query string (after prefix expansion). */
+  q: string;
+  /** Execution duration in milliseconds. */
+  ms: number;
+  /** Result type discriminant. */
+  type: "select" | "construct" | "ask";
+  /** True result count (bindings / triples / 1). */
+  count: number;
+  /** SELECT variable names. */
+  vars?: string[];
+  /** SELECT result rows (capped at maxBindings). */
+  bindings?: Record<string, string>[];
+  /** CONSTRUCT triples (capped at maxBindings). */
+  triples?: { s: string; p: string; o: string }[];
+  /** ASK result. */
+  ask?: boolean;
+}
+
+/** API exposed via `store.api<TraceApi>("trace")`. */
+export interface TraceApi {
+  readonly sessionId: string;
+  readonly logPath: string;
+  readonly queryCount: number;
+}
+
+/** Options for creating the trace plugin. */
+export interface TracePluginOptions {
+  /** Directory for trace log files. */
+  traceDir: string;
+  /** Session identifier (generated if omitted). */
+  sessionId?: string;
+  /** Max bindings/triples to record per query. Default: 200. */
+  maxBindings?: number;
+}
+
+/** A trace session on disk. */
+export interface TraceSession {
+  /** Session identifier (derived from filename). */
+  sessionId: string;
+  /** Absolute path to the NDJSON file. */
+  path: string;
+  /** Number of query records in the file. */
+  queryCount: number;
+  /** File size in bytes. */
+  sizeBytes: number;
+  /** File creation time. */
+  createdAt: Date;
+}

package/src/error/PragmaError.ts

@@ -1,4 +1,9 @@
-import type { ErrorCode, PragmaErrorData, Recovery } from "./types.js";
+import type {
+  CrossDomainRecovery,
+  ErrorCode,
+  PragmaErrorData,
+  Recovery,
+} from "./types.js";
 
 /**
  * Structured error for all pragma domain operations.
@@ -16,6 +21,8 @@ class PragmaError extends Error {
   readonly suggestions: string[];
   /** Structured recovery hint with optional CLI command or MCP tool call. */
   readonly recovery: Recovery | undefined;
+  /** Cross-domain redirect when name exists in another domain. */
+  readonly crossDomain: CrossDomainRecovery | undefined;
   /** Active filters at the time of the error, for diagnostic context. */
   readonly filters: Record<string, string> | undefined;
   /** Enumerated valid options when input was rejected. */
@@ -31,6 +38,7 @@ class PragmaError extends Error {
     this.entity = data.entity;
     this.suggestions = data.suggestions ?? [];
     this.recovery = data.recovery;
+    this.crossDomain = data.crossDomain;
     this.filters = data.filters;
     this.validOptions = data.validOptions;
   }
@@ -49,6 +57,7 @@ class PragmaError extends Error {
     opts: {
       suggestions?: string[];
       recovery?: Recovery;
+      crossDomain?: CrossDomainRecovery;
     } = {},
   ): PragmaError {
     return new PragmaError({
@@ -57,6 +66,7 @@ class PragmaError extends Error {
       entity: { type: entityType, name: entityName },
       suggestions: opts.suggestions,
       recovery: opts.recovery,
+      crossDomain: opts.crossDomain,
     });
   }
 
@@ -70,15 +80,18 @@ class PragmaError extends Error {
   static emptyResults(
     entityType: string,
     opts: {
+      message?: string;
       filters?: Record<string, string>;
       recovery?: Recovery;
+      validOptions?: string[];
     } = {},
   ): PragmaError {
     return new PragmaError({
       code: "EMPTY_RESULTS",
-      message: `No ${entityType}s found.`,
+      message: opts.message ?? `No ${entityType}s found.`,
       filters: opts.filters,
       recovery: opts.recovery,
+      validOptions: opts.validOptions,
     });
   }
 

package/src/error/types.ts

@@ -20,6 +20,18 @@ interface Recovery {
   mcp?: { tool: string; params?: Record<string, unknown> };
 }
 
+/** Hint pointing the user/agent to a different domain when a name exists there. */
+interface CrossDomainRecovery {
+  /** Domain where the name was found (e.g., "modifier"). */
+  domain: string;
+  /** Entity type label for messages. */
+  entityType: string;
+  /** CLI command to run. */
+  cli: string;
+  /** MCP tool invocation. */
+  mcp: { tool: string; params: Record<string, unknown> };
+}
+
 /** Raw data payload used to construct a PragmaError. */
 interface PragmaErrorData {
   /** Machine-readable error classification. */
@@ -32,10 +44,12 @@ interface PragmaErrorData {
   suggestions?: string[];
   /** Recovery hint for CLI and MCP adapters. */
   recovery?: Recovery;
+  /** Cross-domain redirect when name exists in another domain. */
+  crossDomain?: CrossDomainRecovery;
   /** Active filters at the time of the error. */
   filters?: Record<string, string>;
   /** Enumerated valid options when input was rejected. */
   validOptions?: string[];
 }
 
-export type { ErrorCode, PragmaErrorData, Recovery };
+export type { CrossDomainRecovery, ErrorCode, PragmaErrorData, Recovery };

package/src/mcp/error/serializeErrorPayload.ts

@@ -21,6 +21,13 @@ export default function serializeErrorPayload(
     message: error.message,
     ...(error.suggestions.length > 0 && { suggestions: error.suggestions }),
     ...(recovery && { recovery }),
+    ...(error.crossDomain && {
+      crossDomain: {
+        domain: error.crossDomain.domain,
+        tool: error.crossDomain.mcp.tool,
+        params: error.crossDomain.mcp.params,
+      },
+    }),
     ...(error.filters && { filters: error.filters }),
     ...(error.validOptions && { validOptions: error.validOptions }),
   };

package/src/mcp/error/types.ts

@@ -28,11 +28,19 @@ export interface McpRecovery {
  * Structured MCP error payload embedded in tool response content.
  * Returned as JSON text content with `isError: true`.
  */
+/** Cross-domain redirect hint for agents. */
+export interface McpCrossDomainHint {
+  readonly domain: string;
+  readonly tool: string;
+  readonly params: Record<string, unknown>;
+}
+
 export interface McpErrorPayload {
   readonly code: ErrorCode;
   readonly message: string;
   readonly suggestions?: readonly string[];
   readonly recovery?: McpRecovery;
+  readonly crossDomain?: McpCrossDomainHint;
   readonly filters?: Record<string, string>;
   readonly validOptions?: readonly string[];
 }