@gmickel/gno 1.18.0 → 1.20.0

package/src/cli/commands/vsearch.ts

@@ -5,8 +5,18 @@
  * @module src/cli/commands/vsearch
  */
 
+import type {
+  RetrievalTraceSession,
+  RetrievalTraceSurfaceMetadata,
+} from "../../core/retrieval-trace-session";
+import type { EmbeddingPort } from "../../llm/types";
 import type { SearchOptions, SearchResults } from "../../pipeline/types";
 
+import {
+  finishRetrievalTraceAfterError,
+  retrievalTraceFilters,
+  startRetrievalTraceRequest,
+} from "../../core/retrieval-trace-request";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveModelUri } from "../../llm/registry";
 import { formatQueryForEmbedding } from "../../pipeline/contextual";
@@ -47,7 +57,11 @@ export type VsearchCommandOptions = SearchOptions & {
 };
 
 export type VsearchResult =
-  | { success: true; data: SearchResults }
+  | {
+      success: true;
+      data: SearchResults;
+      metadata?: RetrievalTraceSurfaceMetadata;
+    }
   | { success: false; error: string };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -78,6 +92,8 @@ export async function vsearch(
   }
 
   const { store, config } = initResult;
+  let embedPort: EmbeddingPort | null = null;
+  let traceSession: RetrievalTraceSession | undefined;
 
   try {
     // Get model URI from preset
@@ -87,67 +103,74 @@ export async function vsearch(
       options.model,
       options.collection
     );
+    const traceStart = await startRetrievalTraceRequest({
+      store,
+      config,
+      query,
+      filters: retrievalTraceFilters({ ...options, limit }),
+      pipeline: "vector",
+      indexName: options.indexName,
+      modelUris: [modelUri],
+    });
+    if (!traceStart.ok) {
+      return { success: false, error: traceStart.error.message };
+    }
+    traceSession = traceStart.value ?? undefined;
 
     // Create LLM adapter for embeddings
     const llm = new LlmAdapter(config);
     const embedResult = await llm.createEmbeddingPort(modelUri);
     if (!embedResult.ok) {
+      await traceSession?.finish("failed");
       return { success: false, error: embedResult.error.message };
     }
 
-    const embedPort = embedResult.value;
-
-    try {
-      // Embed query with contextual formatting (also determines dimensions)
-      const queryEmbedResult = await embedPort.embed(
-        formatQueryForEmbedding(query, embedPort.modelUri)
-      );
-      if (!queryEmbedResult.ok) {
-        return { success: false, error: queryEmbedResult.error.message };
-      }
-      const queryEmbedding = new Float32Array(queryEmbedResult.value);
-      const dimensions = queryEmbedding.length;
-
-      // Create vector index port
-      const db = store.getRawDb();
-      const vectorResult = await createVectorIndexPort(db, {
-        model: modelUri,
-        dimensions,
-      });
-
-      if (!vectorResult.ok) {
-        return { success: false, error: vectorResult.error.message };
-      }
-
-      const vectorIndex = vectorResult.value;
-
-      const deps: VectorSearchDeps = {
-        store,
-        vectorIndex,
-        embedPort,
-        config,
-      };
-
-      // Pass pre-computed embedding to avoid double-embed
-      const result = await searchVectorWithEmbedding(
-        deps,
-        query,
-        queryEmbedding,
-        { ...options, limit }
-      );
-
-      if (!result.ok) {
-        return { success: false, error: result.error.message };
-      }
-
-      return {
-        success: true,
-        data: decorateSearchResultsForIndex(result.value, options.indexName),
-      };
-    } finally {
-      await embedPort.dispose();
+    embedPort = embedResult.value;
+    const queryEmbedResult = await embedPort.embed(
+      formatQueryForEmbedding(query, embedPort.modelUri)
+    );
+    if (!queryEmbedResult.ok) {
+      await traceSession?.finish("failed");
+      return { success: false, error: queryEmbedResult.error.message };
     }
+    const queryEmbedding = new Float32Array(queryEmbedResult.value);
+    const vectorResult = await createVectorIndexPort(store.getRawDb(), {
+      model: modelUri,
+      dimensions: queryEmbedding.length,
+    });
+    if (!vectorResult.ok) {
+      await traceSession?.finish("failed");
+      return { success: false, error: vectorResult.error.message };
+    }
+    const deps: VectorSearchDeps = {
+      store,
+      vectorIndex: vectorResult.value,
+      embedPort,
+      config,
+    };
+    const result = await searchVectorWithEmbedding(
+      deps,
+      query,
+      queryEmbedding,
+      { ...options, limit, traceSession }
+    );
+    if (!result.ok) {
+      await traceSession?.finish("failed");
+      return { success: false, error: result.error.message };
+    }
+    return {
+      success: true,
+      data: decorateSearchResultsForIndex(result.value, options.indexName),
+      metadata: traceSession?.metadata(),
+    };
+  } catch (cause) {
+    await finishRetrievalTraceAfterError(traceSession, cause);
+    return {
+      success: false,
+      error: cause instanceof Error ? cause.message : "Vector search failed",
+    };
   } finally {
+    await embedPort?.dispose();
     await store.close();
   }
 }
@@ -194,7 +217,6 @@ export function formatVsearch(
         })
       : `Error: ${result.error}`;
   }
-
   const formatOpts: FormatOptions = {
     format: getFormatType(options),
     full: options.full,

package/src/cli/program.ts

@@ -164,6 +164,15 @@ async function writeOutput(
   }
 }
 
+/** Emit opt-in trace identity without changing command stdout payloads. */
+export function writeRetrievalTraceReceipt(
+  metadata: { traceId: string } | undefined
+): void {
+  if (metadata) {
+    process.stderr.write(`Trace: ${metadata.traceId}\n`);
+  }
+}
+
 async function resolveTerminalLinkPolicy(
   format: "terminal" | "json" | "files" | "csv" | "md" | "xml"
 ): Promise<
@@ -292,6 +301,7 @@ export function createProgram(): Command {
   wireOnboardingCommands(program);
   wireCaptureCommand(program);
   wireManagementCommands(program);
+  wireTraceCommands(program);
   wirePublishCommand(program);
   wireVecCommands(program);
   wireRetrievalCommands(program);
@@ -315,6 +325,244 @@ Report issues: ${ISSUES_URL}`
   return program;
 }
 
+function wireTraceCommands(program: Command): void {
+  const traceCmd = program
+    .command("trace")
+    .description("Inspect and manage private local retrieval traces");
+
+  const outputFormat = (options: Record<string, unknown>): "json" | "md" =>
+    getFormat(options) === "json" ? "json" : "md";
+
+  traceCmd
+    .command("list")
+    .description("List bounded, redacted retrieval trace summaries")
+    .option("-n, --limit <num>", "maximum traces", "50")
+    .option("--cursor <cursor>", "continue from a previous list receipt")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const { traceList } = await import("./commands/trace");
+      const output = await traceList(
+        {
+          limit: parsePositiveInt("limit", cmdOpts.limit),
+          cursor: cmdOpts.cursor as string | undefined,
+        },
+        {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        }
+      );
+      process.stdout.write(output);
+    });
+
+  traceCmd
+    .command("show <trace-id>")
+    .description("Inspect one bounded retrieval trace receipt")
+    .option("--detail-limit <num>", "maximum records per detail section", "500")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const { traceShow } = await import("./commands/trace");
+      const output = await traceShow(
+        traceId,
+        {
+          detailLimit: parsePositiveInt("detail-limit", cmdOpts.detailLimit),
+        },
+        {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        }
+      );
+      process.stdout.write(output);
+    });
+
+  traceCmd
+    .command("label <trace-id>")
+    .description("Append an explicit retrieval relevance judgment")
+    .requiredOption(
+      "--label <label>",
+      "relevant, irrelevant, or missing-expected"
+    )
+    .requiredOption("--target <ref>", "evidence or expected-document reference")
+    .option("--target-kind <kind>", "document, chunk, or span")
+    .option("--from-line <num>", "exact evidence start line")
+    .option("--to-line <num>", "exact evidence end line")
+    .option("--source-hash <sha256>", "expected immutable source hash")
+    .option("--docid <docid>", "expected document ID")
+    .option("--idempotency-key <key>", "caller retry key")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const rawLabel = String(cmdOpts.label).replace("-", "_");
+      if (!["relevant", "irrelevant", "missing_expected"].includes(rawLabel)) {
+        throw new CliError(
+          "VALIDATION",
+          "--label must be relevant, irrelevant, or missing-expected"
+        );
+      }
+      const rawTargetKind = cmdOpts.targetKind;
+      if (
+        rawTargetKind !== undefined &&
+        (typeof rawTargetKind !== "string" ||
+          !["document", "chunk", "span"].includes(rawTargetKind))
+      ) {
+        throw new CliError(
+          "VALIDATION",
+          "--target-kind must be document, chunk, or span"
+        );
+      }
+      const { traceLabel } = await import("./commands/trace");
+      const output = await traceLabel(
+        {
+          traceId,
+          label: rawLabel as "relevant" | "irrelevant" | "missing_expected",
+          targetRef: String(cmdOpts.target),
+          targetKind: rawTargetKind as
+            | "document"
+            | "chunk"
+            | "span"
+            | undefined,
+          startLine:
+            cmdOpts.fromLine === undefined
+              ? undefined
+              : parsePositiveInt("from-line", cmdOpts.fromLine),
+          endLine:
+            cmdOpts.toLine === undefined
+              ? undefined
+              : parsePositiveInt("to-line", cmdOpts.toLine),
+          sourceHash: cmdOpts.sourceHash as string | undefined,
+          docid: cmdOpts.docid as string | undefined,
+          idempotencyKey: cmdOpts.idempotencyKey as string | undefined,
+        },
+        {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        }
+      );
+      process.stdout.write(output);
+    });
+
+  traceCmd
+    .command("export <trace-ids...>")
+    .description("Export immutable terminal traces as one local receipt")
+    .option("--format <format>", "agentic-receipt or qrels", "agentic-receipt")
+    .option("--output <path>", "write canonical artifact atomically")
+    .option("--json", "JSON output")
+    .action(async (traceIds: string[], cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const exportFormat = String(cmdOpts.format);
+      if (!["agentic-receipt", "qrels"].includes(exportFormat)) {
+        throw new CliError(
+          "VALIDATION",
+          "--format must be agentic-receipt or qrels"
+        );
+      }
+      const { traceExport } = await import("./commands/trace");
+      process.stdout.write(
+        await traceExport(traceIds, {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: "json",
+          output: cmdOpts.output as string | undefined,
+          exportFormat: exportFormat as "agentic-receipt" | "qrels",
+        })
+      );
+    });
+
+  traceCmd
+    .command("replay <export-id>")
+    .description("Compare one immutable qrels baseline with a candidate")
+    .requiredOption("--candidate <type>", "bm25, vector, or hybrid")
+    .option("-n, --limit <num>", "result cutoff")
+    .option("--candidate-limit <num>", "candidate pool size")
+    .option("--no-expand", "disable query expansion")
+    .option("--no-rerank", "disable reranking")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (exportId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const candidateType = String(cmdOpts.candidate);
+      if (!["bm25", "vector", "hybrid"].includes(candidateType)) {
+        throw new CliError(
+          "VALIDATION",
+          "--candidate must be bm25, vector, or hybrid"
+        );
+      }
+      const { traceReplay } = await import("./commands/replay");
+      process.stdout.write(
+        await traceReplay(
+          exportId,
+          {
+            id: `cli-${candidateType}`,
+            type: candidateType as "bm25" | "vector" | "hybrid",
+            limit:
+              cmdOpts.limit === undefined
+                ? undefined
+                : parsePositiveInt("limit", cmdOpts.limit),
+            candidateLimit:
+              cmdOpts.candidateLimit === undefined
+                ? undefined
+                : parsePositiveInt("candidate-limit", cmdOpts.candidateLimit),
+            noExpand: cmdOpts.expand === false,
+            noRerank: cmdOpts.rerank === false,
+          },
+          {
+            configPath: globals.config,
+            indexName: globals.index,
+            format: outputFormat(cmdOpts),
+            offline: globals.offline,
+          }
+        )
+      );
+    });
+
+  traceCmd
+    .command("delete <trace-id>")
+    .description("Delete one trace and every owned local record")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (traceId: string, cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      const { traceDelete } = await import("./commands/trace");
+      process.stdout.write(
+        await traceDelete(traceId, {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        })
+      );
+    });
+
+  traceCmd
+    .command("purge")
+    .description("Delete every local retrieval trace receipt")
+    .option("--json", "JSON output")
+    .option("--md", "Markdown output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const globals = getGlobals();
+      if (!globals.yes) {
+        throw new CliError(
+          "VALIDATION",
+          "Trace purge requires the global --yes confirmation"
+        );
+      }
+      const { tracePurge } = await import("./commands/trace");
+      process.stdout.write(
+        await tracePurge({
+          configPath: globals.config,
+          indexName: globals.index,
+          format: outputFormat(cmdOpts),
+        })
+      );
+    });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Search Commands (search, vsearch, query, ask)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -387,7 +635,9 @@ function wireSearchCommands(program: Command): void {
 
       const limit = cmdOpts.limit
         ? parsePositiveInt("limit", cmdOpts.limit)
-        : getDefaultLimit(format);
+        : cmdOpts.verify
+          ? 5
+          : getDefaultLimit(format);
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
 
@@ -435,6 +685,7 @@ function wireSearchCommands(program: Command): void {
         terminalLinks: await resolveTerminalLinkPolicy(format),
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // vsearch - Vector similarity search
@@ -547,6 +798,7 @@ function wireSearchCommands(program: Command): void {
         terminalLinks: await resolveTerminalLinkPolicy(format),
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // query - Hybrid search with expansion and reranking
@@ -768,6 +1020,7 @@ function wireSearchCommands(program: Command): void {
         terminalLinks: await resolveTerminalLinkPolicy(format),
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // bench - Retrieval benchmark fixture runner
@@ -857,8 +1110,16 @@ function wireSearchCommands(program: Command): void {
     )
     .option("-C, --candidate-limit <num>", "max candidates passed to reranking")
     .option("--answer", "generate short grounded answer")
+    .option(
+      "--verify",
+      "generate and verify every claim against a closed Context Capsule"
+    )
     .option("--no-answer", "force retrieval-only output")
     .option("--max-answer-tokens <num>", "max answer tokens")
+    .option("--context-budget-tokens <num>", "verified Context token budget")
+    .option("--context-budget-bytes <num>", "verified Context byte budget")
+    .option("--min-score <score>", "minimum retrieval score (0-1)")
+    .option("--graph", "include bounded graph expansion")
     .option("--show-sources", "show all retrieved sources (not just cited)")
     .option("--json", "JSON output")
     .option("--md", "Markdown output")
@@ -889,6 +1150,22 @@ function wireSearchCommands(program: Command): void {
       const maxAnswerTokens = cmdOpts.maxAnswerTokens
         ? parsePositiveInt("max-answer-tokens", cmdOpts.maxAnswerTokens)
         : undefined;
+      const contextBudgetTokens = cmdOpts.contextBudgetTokens
+        ? parsePositiveInt("context-budget-tokens", cmdOpts.contextBudgetTokens)
+        : undefined;
+      const contextBudgetBytes = cmdOpts.contextBudgetBytes
+        ? parsePositiveInt("context-budget-bytes", cmdOpts.contextBudgetBytes)
+        : undefined;
+      const minScore = parseOptionalFloat("min-score", cmdOpts.minScore);
+      if (minScore !== undefined && (minScore < 0 || minScore > 1)) {
+        throw new CliError("VALIDATION", "min-score must be between 0 and 1");
+      }
+      if (cmdOpts.verify && cmdOpts.noAnswer) {
+        throw new CliError(
+          "VALIDATION",
+          "--verify cannot be combined with --no-answer"
+        );
+      }
       const categories = parseCsvValues(cmdOpts.category);
       const exclude = parseCsvValues(cmdOpts.exclude);
 
@@ -937,6 +1214,8 @@ function wireSearchCommands(program: Command): void {
         author: cmdOpts.author as string | undefined,
         intent: cmdOpts.intent as string | undefined,
         exclude,
+        minScore,
+        graph: Boolean(cmdOpts.graph),
         queryModes,
         noExpand: depthPolicy.noExpand,
         noRerank: depthPolicy.noRerank,
@@ -945,7 +1224,10 @@ function wireSearchCommands(program: Command): void {
         // Commander creates separate cmdOpts.noAnswer for --no-answer flag
         answer: Boolean(cmdOpts.answer),
         noAnswer: Boolean(cmdOpts.noAnswer),
+        verify: Boolean(cmdOpts.verify),
         maxAnswerTokens,
+        contextBudgetTokens,
+        contextBudgetBytes,
         showSources,
         json: format === "json",
         md: format === "md",
@@ -960,6 +1242,7 @@ function wireSearchCommands(program: Command): void {
         showSources,
       });
       await writeOutput(output, format);
+      writeRetrievalTraceReceipt(result.metadata);
     });
 }
 
@@ -1191,6 +1474,7 @@ function wireRetrievalCommands(program: Command): void {
       parsePositiveInt.bind(null, "limit")
     )
     .option("--line-numbers", "Prefix lines with numbers")
+    .option("--trace-id <id>", "Continue an open retrieval trace")
     .option("--source", "Include source metadata")
     .option("--json", "JSON output")
     .option("--md", "Markdown output")
@@ -1209,6 +1493,7 @@ function wireRetrievalCommands(program: Command): void {
         source: Boolean(cmdOpts.source),
         json: format === "json",
         md: format === "md",
+        traceId: cmdOpts.traceId as string | undefined,
       });
 
       if (!result.success) {
@@ -1225,6 +1510,7 @@ function wireRetrievalCommands(program: Command): void {
           md: format === "md",
         })}\n`
       );
+      writeRetrievalTraceReceipt(result.metadata);
     });
 
   // multi-get - Retrieve multiple documents

package/src/config/index.ts

@@ -70,3 +70,12 @@ export {
   ScopeTypeSchema,
 } from "./types";
 export type { HttpGatewayConfig } from "./types";
+export {
+  RETRIEVAL_TRACE_DEFAULT_RETENTION,
+  type RetrievalTraceConfig,
+  RetrievalTraceConfigSchema,
+  type RetrievalTraceRedactionMode,
+  RetrievalTraceRedactionModeSchema,
+  type RetrievalTraceRetention,
+  RetrievalTraceRetentionSchema,
+} from "./retrieval-traces";

package/src/config/retrieval-traces.ts

@@ -0,0 +1,56 @@
+/** Opt-in retrieval trace configuration and bounded-retention defaults. */
+
+import { z } from "zod";
+
+export const RETRIEVAL_TRACE_DEFAULT_RETENTION = {
+  maxAgeDays: 30,
+  maxTraces: 1_000,
+  maxRecordsPerTrace: 10_000,
+  maxBytes: 16 * 1024 * 1024,
+} as const;
+
+export const RetrievalTraceRetentionSchema = z
+  .object({
+    maxAgeDays: z.number().int().min(1).max(3_650),
+    maxTraces: z.number().int().min(1).max(1_000_000),
+    maxRecordsPerTrace: z.number().int().min(1).max(100_000),
+    maxBytes: z
+      .number()
+      .int()
+      .min(64 * 1024)
+      .max(1024 * 1024 * 1024),
+  })
+  .strict();
+
+export const RetrievalTraceRedactionModeSchema = z.enum(["metadata", "replay"]);
+
+const DisabledRetrievalTraceConfigSchema = z
+  .object({
+    enabled: z.literal(false),
+  })
+  .strict();
+
+const EnabledRetrievalTraceConfigSchema = z
+  .object({
+    enabled: z.literal(true),
+    /**
+     * `replay` stores replay inputs such as the raw query and filters. Choosing
+     * it is explicit consent; the safer metadata-only projection is recommended.
+     */
+    redactionMode: RetrievalTraceRedactionModeSchema,
+    retention: RetrievalTraceRetentionSchema,
+  })
+  .strict();
+
+export const RetrievalTraceConfigSchema = z.discriminatedUnion("enabled", [
+  DisabledRetrievalTraceConfigSchema,
+  EnabledRetrievalTraceConfigSchema,
+]);
+
+export type RetrievalTraceConfig = z.infer<typeof RetrievalTraceConfigSchema>;
+export type RetrievalTraceRetention = z.infer<
+  typeof RetrievalTraceRetentionSchema
+>;
+export type RetrievalTraceRedactionMode = z.infer<
+  typeof RetrievalTraceRedactionModeSchema
+>;

package/src/config/types.ts

@@ -8,6 +8,7 @@
 import { z } from "zod";
 
 import { URI_PREFIX } from "../app/constants";
+import { RetrievalTraceConfigSchema } from "./retrieval-traces";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
@@ -338,6 +339,9 @@ export const ConfigSchema = z.object({
 
   /** Resident Streamable HTTP MCP gateway configuration */
   gateway: HttpGatewayConfigSchema.optional(),
+
+  /** Private local retrieval trace recording. Absent means recording off. */
+  retrievalTraces: RetrievalTraceConfigSchema.optional(),
 });
 
 export type Config = Omit<z.infer<typeof ConfigSchema>, "contentTypes"> & {

package/src/core/context-budget.ts

@@ -6,6 +6,8 @@
  * canonical Capsule payload, including coverage, omissions, and guidance.
  */
 
+import type { FusionSource } from "../pipeline/types";
+
 export const CONTEXT_OMISSION_REASONS = [
   "duplicate",
   "overlap",
@@ -43,6 +45,10 @@ export interface MaterializedContextCandidate<
   text: string;
   facets: string[];
   retrievalRank: number;
+  /** Absent only for legacy results that predate planner provenance metadata. */
+  retrievalSources?: FusionSource[];
+  /** Absent only for legacy results that predate planner provenance metadata. */
+  graphExpanded?: boolean;
   value: T;
 }
 

package/src/core/context-capsule-retrieval-schema.ts

@@ -59,10 +59,14 @@ export const contextCapsuleRetrievalSchema = z
       .object({
         author: z.string().min(1).max(256).nullable(),
         lang: z.string().min(1).max(64).nullable(),
+        intent: z.string().min(1).max(16_384).nullable().optional(),
+        exclude: z.array(nonEmptyText.max(256)).max(128).optional(),
+        minScore: z.number().min(0).max(1).nullable().optional(),
         queryModes: z.array(queryModeSchema).max(128),
         limit: z.number().int().positive(),
         candidateLimit: z.number().int().positive(),
         graphRequested: z.boolean(),
+        rerankRequested: z.boolean().optional(),
       })
       .strict(),
     capabilityStates: z