@gmickel/gno 1.20.0 → 1.21.0

package/spec/output-schemas/saved-capsule-registration.schema.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/saved-capsule-registration@1.0",
+  "title": "GNO Saved Context Capsule Registration",
+  "description": "Metadata-only registration for one caller-owned Context Capsule file. Capsule and passage bytes are never embedded in this payload.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "registrationId",
+    "filePath",
+    "fileHash",
+    "capsuleId",
+    "indexName",
+    "question",
+    "label",
+    "notificationPreference",
+    "registeredAtMs",
+    "updatedAtMs",
+    "lastAttemptedSequence",
+    "evidence",
+    "verification"
+  ],
+  "properties": {
+    "registrationId": {
+      "type": "string",
+      "pattern": "^capsule-[a-f0-9]{40}$"
+    },
+    "filePath": { "type": "string", "minLength": 1, "maxLength": 8192 },
+    "fileHash": { "$ref": "#/definitions/sha256" },
+    "capsuleId": { "$ref": "#/definitions/sha256" },
+    "indexName": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "question": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "maxLength": 8192
+    },
+    "label": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "maxLength": 512
+    },
+    "notificationPreference": { "enum": ["none", "local"] },
+    "registeredAtMs": { "type": "integer", "minimum": 0 },
+    "updatedAtMs": { "type": "integer", "minimum": 0 },
+    "lastAttemptedSequence": { "type": "integer", "minimum": 0 },
+    "evidence": {
+      "type": "array",
+      "maxItems": 10000,
+      "items": { "$ref": "#/definitions/evidenceReference" }
+    },
+    "verification": {
+      "anyOf": [{ "$ref": "#/definitions/verification" }, { "type": "null" }]
+    }
+  },
+  "definitions": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "evidenceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "evidenceId",
+        "canonicalUri",
+        "collection",
+        "sourceHash",
+        "mirrorHash",
+        "passageHash"
+      ],
+      "properties": {
+        "evidenceId": { "$ref": "#/definitions/sha256" },
+        "canonicalUri": { "type": "string", "pattern": "^gno://.+" },
+        "collection": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "sourceHash": { "$ref": "#/definitions/sha256" },
+        "mirrorHash": { "$ref": "#/definitions/sha256" },
+        "passageHash": { "$ref": "#/definitions/sha256" }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "registrationId",
+        "triggerKind",
+        "fromSequence",
+        "throughSequence",
+        "operationStatus",
+        "affectedQuestionState",
+        "affectedReasons",
+        "receiptJson",
+        "receiptHash",
+        "errorCode",
+        "errorMessage",
+        "verifiedAtMs"
+      ],
+      "properties": {
+        "registrationId": {
+          "type": "string",
+          "pattern": "^capsule-[a-f0-9]{40}$"
+        },
+        "triggerKind": { "enum": ["manual", "journal"] },
+        "fromSequence": { "type": "integer", "minimum": 0 },
+        "throughSequence": { "type": "integer", "minimum": 0 },
+        "operationStatus": { "enum": ["completed", "failed"] },
+        "affectedQuestionState": {
+          "enum": ["unaffected", "affected", "unknown"]
+        },
+        "affectedReasons": {
+          "type": "array",
+          "maxItems": 4,
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "content_stale",
+              "content_missing",
+              "ranking_changed",
+              "fingerprint_changed"
+            ]
+          }
+        },
+        "receiptJson": {
+          "type": ["string", "null"],
+          "maxLength": 16777216
+        },
+        "receiptHash": {
+          "anyOf": [{ "$ref": "#/definitions/sha256" }, { "type": "null" }]
+        },
+        "errorCode": {
+          "type": ["string", "null"],
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "errorMessage": {
+          "type": ["string", "null"],
+          "minLength": 1,
+          "maxLength": 4096
+        },
+        "verifiedAtMs": { "type": "integer", "minimum": 0 }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "operationStatus": { "const": "completed" } },
+            "required": ["operationStatus"]
+          },
+          "then": {
+            "properties": {
+              "affectedQuestionState": {
+                "enum": ["unaffected", "affected"]
+              },
+              "receiptJson": { "type": "string", "minLength": 1 },
+              "receiptHash": { "$ref": "#/definitions/sha256" },
+              "errorCode": { "type": "null" },
+              "errorMessage": { "type": "null" }
+            }
+          },
+          "else": {
+            "properties": {
+              "affectedQuestionState": { "const": "unknown" },
+              "affectedReasons": { "type": "array", "maxItems": 0 },
+              "receiptJson": { "type": "null" },
+              "receiptHash": { "type": "null" },
+              "errorCode": { "type": "string", "minLength": 1 },
+              "errorMessage": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/spec/output-schemas/saved-capsule-reverification.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/saved-capsule-reverification@1.0",
+  "title": "GNO Saved Context Capsule Reverification Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "registration", "verification", "receipt"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "registration": {
+      "$ref": "gno://schemas/saved-capsule-registration@1.0"
+    },
+    "verification": {
+      "$ref": "gno://schemas/saved-capsule-registration@1.0#/definitions/verification"
+    },
+    "receipt": {
+      "anyOf": [
+        { "$ref": "gno://schemas/context-capsule-verification@1.0" },
+        { "type": "null" }
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "verification": {
+            "type": "object",
+            "properties": { "operationStatus": { "const": "completed" } },
+            "required": ["operationStatus"]
+          }
+        },
+        "required": ["verification"]
+      },
+      "then": {
+        "properties": {
+          "verification": {
+            "type": "object",
+            "properties": { "triggerKind": { "const": "manual" } },
+            "required": ["triggerKind"]
+          },
+          "receipt": {
+            "$ref": "gno://schemas/context-capsule-verification@1.0"
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "verification": {
+            "type": "object",
+            "properties": { "triggerKind": { "const": "manual" } },
+            "required": ["triggerKind"]
+          },
+          "receipt": { "type": "null" }
+        }
+      }
+    }
+  ]
+}

package/spec/output-schemas/saved-capsule-unwatch.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/saved-capsule-unwatch@1.0",
+  "title": "GNO Saved Context Capsule Unwatch Receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "registrationId", "removed"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "registrationId": {
+      "type": "string",
+      "pattern": "^capsule-[a-f0-9]{40}$"
+    },
+    "removed": { "const": true }
+  }
+}

package/spec/output-schemas/saved-capsule-watch.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/saved-capsule-watch@1.0",
+  "title": "GNO Saved Context Capsule Watch Result",
+  "allOf": [
+    {
+      "$ref": "gno://schemas/saved-capsule-registration@1.0"
+    },
+    {
+      "type": "object",
+      "properties": {
+        "verification": { "type": "null" }
+      },
+      "required": ["verification"]
+    }
+  ]
+}

package/src/cli/commands/changes.ts

@@ -0,0 +1,160 @@
+/** CLI adapters and readable formatters for knowledge delta read services. */
+
+import type {
+  KnowledgeChangesResult,
+  KnowledgeDeltaServiceResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
+} from "../../core/knowledge-delta";
+import type { StorePort } from "../../store/types";
+
+import {
+  analyzeKnowledgeImpact,
+  getKnowledgeDiff,
+  listKnowledgeChanges,
+} from "../../core/knowledge-delta";
+import { initStore } from "./shared";
+
+export interface KnowledgeDeltaCliContext {
+  configPath?: string;
+  indexName?: string;
+}
+
+export const changesRead = (
+  store: StorePort,
+  input: ListKnowledgeChangesInput = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeChangesResult>> =>
+  listKnowledgeChanges(store, input);
+
+export const diffRead = (
+  store: StorePort,
+  ref: string,
+  changeId?: string
+): Promise<KnowledgeDeltaServiceResult<KnowledgeDiffResult>> =>
+  getKnowledgeDiff(store, ref, changeId);
+
+export const impactRead = (
+  store: StorePort,
+  ref: string,
+  input: KnowledgeImpactInput = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeImpactResult>> =>
+  analyzeKnowledgeImpact(store, ref, input);
+
+const withStore = async <T>(
+  context: KnowledgeDeltaCliContext,
+  operation: (store: StorePort) => Promise<KnowledgeDeltaServiceResult<T>>
+): Promise<KnowledgeDeltaServiceResult<T>> => {
+  const initialized = await initStore({
+    configPath: context.configPath,
+    indexName: context.indexName,
+    syncConfig: false,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) {
+    return { success: false, error: initialized.error };
+  }
+  try {
+    return await operation(initialized.store);
+  } finally {
+    await initialized.store.close();
+  }
+};
+
+export const changes = (
+  input: ListKnowledgeChangesInput,
+  context: KnowledgeDeltaCliContext = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeChangesResult>> =>
+  withStore(context, (store) => changesRead(store, input));
+
+export const diff = (
+  ref: string,
+  changeId: string | undefined,
+  context: KnowledgeDeltaCliContext = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeDiffResult>> =>
+  withStore(context, (store) => diffRead(store, ref, changeId));
+
+export const impact = (
+  ref: string,
+  input: KnowledgeImpactInput,
+  context: KnowledgeDeltaCliContext = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeImpactResult>> =>
+  withStore(context, (store) => impactRead(store, ref, input));
+
+const json = (value: unknown): string => JSON.stringify(value, null, 2);
+
+export function formatChanges(
+  result: KnowledgeChangesResult,
+  format: "terminal" | "json"
+): string {
+  if (format === "json") return json(result);
+  const lines = [`${result.changes.length} retained changes`];
+  for (const change of result.changes) {
+    const uri = change.current?.uri ?? change.previous?.uri ?? "(unknown)";
+    lines.push(
+      `${change.observedAt}  ${change.kind.padEnd(10)}  ${uri}  ${change.id}`
+    );
+  }
+  if (result.page.cursorExpired) {
+    lines.push(`Cursor expired; earliest: ${result.page.earliestCursor}`);
+  } else if (result.page.nextCursor) {
+    lines.push(`Next cursor: ${result.page.nextCursor}`);
+  }
+  for (const warning of result.warnings) {
+    lines.push(`Warning: ${warning}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatDiff(
+  result: KnowledgeDiffResult,
+  format: "terminal" | "json"
+): string {
+  if (format === "json") return json(result);
+  const lines = [
+    `Structural diff for ${result.document.uri}`,
+    `Status: ${result.status}`,
+    `History: ${result.history.status}${result.history.reason ? ` (${result.history.reason})` : ""}`,
+    "Content: not retained (metadata-only journal)",
+  ];
+  if (result.change) {
+    const delta = result.change.structureDelta;
+    lines.push(
+      `Change: ${result.change.kind} at ${result.change.observedAt} (${result.change.id})`,
+      `Headings: +${delta.headings.added.length} -${delta.headings.removed.length}`,
+      `Links: +${delta.links.added.length} -${delta.links.removed.length}`,
+      `Typed edges: +${delta.typedEdges.added.length} -${delta.typedEdges.removed.length}`,
+      `Dates: +${delta.dates.added.length} -${delta.dates.removed.length} ~${delta.dates.changed.length}`
+    );
+  }
+  for (const warning of result.warnings) {
+    lines.push(`Warning: ${warning}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatImpact(
+  result: KnowledgeImpactResult,
+  format: "terminal" | "json"
+): string {
+  if (format === "json") return json(result);
+  const lines = [
+    `${result.impacted.length} documents depend on ${result.root.uri}`,
+  ];
+  for (const item of result.impacted) {
+    const path = item.evidencePath
+      .map(
+        (step) => `${step.source.uri} -[${step.edgeType}]-> ${step.target.uri}`
+      )
+      .join(" -> ");
+    lines.push(`depth ${item.depth}  ${item.document.uri}`, `  ${path}`);
+  }
+  if (result.meta.truncated) {
+    lines.push("Traversal truncated by configured caps");
+  }
+  for (const warning of result.meta.warnings) {
+    lines.push(`Warning: ${warning}`);
+  }
+  return lines.join("\n");
+}

package/src/cli/commands/context-saved.ts

@@ -0,0 +1,189 @@
+/** CLI lifecycle for explicitly saved Context Capsules. */
+
+import type { Config } from "../../config/types";
+import type { SqliteAdapter } from "../../store/sqlite/adapter";
+import type { SavedCapsuleRegistrationRecord } from "../../store/types";
+
+import { DEFAULT_INDEX_NAME } from "../../app/constants";
+import { canonicalizeIndexName } from "../../app/index-name";
+import {
+  canonicalSavedCapsuleRegistryJson,
+  listSavedCapsules,
+  loadSavedCapsuleFile,
+  registerSavedCapsule,
+  unregisterSavedCapsule,
+} from "../../core/capsule-registry";
+import { reverifySavedCapsuleManually } from "../../core/capsule-reverification";
+import { CliError } from "../errors";
+import { contextCliError } from "./context-build";
+import { initStore } from "./shared";
+
+export interface SavedCapsuleCommandOptions {
+  configPath?: string;
+  indexName?: string;
+  format: "terminal" | "json";
+}
+
+export interface WatchSavedCapsuleCommandOptions extends SavedCapsuleCommandOptions {
+  explicitIndexName?: string;
+  question?: string;
+  label?: string;
+  notify?: boolean;
+}
+
+export interface ReverifySavedCapsuleCommandResult {
+  output: string;
+  operationStatus: "completed" | "failed";
+  errorMessage: string | null;
+}
+
+const withStore = async <T>(
+  options: SavedCapsuleCommandOptions,
+  operation: (input: {
+    store: SqliteAdapter;
+    config: Config;
+    indexName: string;
+  }) => Promise<T>
+): Promise<T> => {
+  const indexName = canonicalizeIndexName(
+    options.indexName ?? DEFAULT_INDEX_NAME
+  );
+  const initialized = await initStore({
+    configPath: options.configPath,
+    indexName,
+    syncConfig: true,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) throw new CliError("RUNTIME", initialized.error);
+  try {
+    return await operation({
+      store: initialized.store,
+      config: initialized.config,
+      indexName,
+    });
+  } finally {
+    await initialized.store.close();
+  }
+};
+
+const formatRegistration = (
+  registration: SavedCapsuleRegistrationRecord
+): string =>
+  [
+    `${registration.registrationId}  ${registration.label ?? registration.capsuleId}`,
+    `  file: ${registration.filePath}`,
+    `  index: ${registration.indexName}`,
+    `  evidence: ${registration.evidence.length}`,
+    `  notify: ${registration.notificationPreference}`,
+    `  state: ${registration.verification?.affectedQuestionState ?? "not_verified"}`,
+  ].join("\n");
+
+export const watchSavedCapsule = async (
+  filePath: string,
+  options: WatchSavedCapsuleCommandOptions
+): Promise<string> => {
+  try {
+    const loaded = await loadSavedCapsuleFile(filePath);
+    const explicit = options.explicitIndexName
+      ? canonicalizeIndexName(options.explicitIndexName)
+      : undefined;
+    if (explicit && explicit !== loaded.capsule.scope.indexName) {
+      throw Object.assign(
+        new Error(
+          `Context Capsule index ${loaded.capsule.scope.indexName} does not match --index ${explicit}`
+        ),
+        { code: "invalid_filter" }
+      );
+    }
+    return await withStore(
+      { ...options, indexName: loaded.capsule.scope.indexName },
+      async ({ store, indexName }) => {
+        const registration = await registerSavedCapsule(store, indexName, {
+          filePath,
+          question: options.question,
+          label: options.label,
+          notificationPreference: options.notify ? "local" : "none",
+        });
+        return options.format === "json"
+          ? canonicalSavedCapsuleRegistryJson(registration)
+          : formatRegistration(registration);
+      }
+    );
+  } catch (error) {
+    throw contextCliError(error);
+  }
+};
+
+export const listWatchedCapsules = async (
+  options: SavedCapsuleCommandOptions
+): Promise<string> =>
+  withStore(options, async ({ store }) => {
+    const registrations = await listSavedCapsules(store);
+    if (options.format === "json") {
+      return canonicalSavedCapsuleRegistryJson({
+        schemaVersion: "1.0",
+        registrations,
+      });
+    }
+    return registrations.length === 0
+      ? "No saved Context Capsules are watched."
+      : registrations.map(formatRegistration).join("\n\n");
+  }).catch((error) => {
+    throw contextCliError(error);
+  });
+
+export const unwatchSavedCapsule = async (
+  registrationId: string,
+  options: SavedCapsuleCommandOptions
+): Promise<string> =>
+  withStore(options, async ({ store }) => {
+    await unregisterSavedCapsule(store, registrationId);
+    return options.format === "json"
+      ? canonicalSavedCapsuleRegistryJson({
+          schemaVersion: "1.0",
+          registrationId,
+          removed: true,
+        })
+      : `Stopped watching ${registrationId}.`;
+  }).catch((error) => {
+    throw contextCliError(error);
+  });
+
+export const reverifyWatchedCapsule = async (
+  registrationId: string,
+  options: SavedCapsuleCommandOptions
+): Promise<ReverifySavedCapsuleCommandResult> =>
+  withStore(options, async ({ store, config, indexName }) => {
+    const outcome = await reverifySavedCapsuleManually(registrationId, {
+      store,
+      config,
+      indexName,
+    });
+    const errorMessage =
+      outcome.verification.operationStatus === "failed"
+        ? `${outcome.verification.errorCode ?? "verification_failed"}: ${
+            outcome.verification.errorMessage ??
+            "Saved Context Capsule verification failed"
+          }`
+        : null;
+    const output =
+      options.format === "json"
+        ? canonicalSavedCapsuleRegistryJson({
+            schemaVersion: "1.0",
+            registration: outcome.registration,
+            verification: outcome.verification,
+            receipt: outcome.receipt,
+          })
+        : [
+            formatRegistration(outcome.registration),
+            `  operation: ${outcome.verification.operationStatus}`,
+            ...(errorMessage ? [`  error: ${errorMessage}`] : []),
+          ].join("\n");
+    return {
+      output,
+      operationStatus: outcome.verification.operationStatus,
+      errorMessage,
+    };
+  }).catch((error) => {
+    throw contextCliError(error);
+  });

package/src/cli/options.ts

@@ -35,6 +35,7 @@ export const CMD = {
   contextCheck: "context.check",
   contextBuild: "context.build",
   contextVerify: "context.verify",
+  contextSaved: "context.saved",
   modelsList: "models.list",
   tagsList: "tags.list",
   linksList: "links.list",
@@ -42,6 +43,9 @@ export const CMD = {
   similar: "similar",
   graph: "graph",
   graphQuery: "graph.query",
+  changes: "changes",
+  diff: "diff",
+  impact: "impact",
   capture: "capture",
 } as const;
 
@@ -64,6 +68,7 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.contextCheck]: ["terminal", "json", "md"],
   [CMD.contextBuild]: ["terminal", "json", "md"],
   [CMD.contextVerify]: ["terminal", "json", "md"],
+  [CMD.contextSaved]: ["terminal", "json"],
   [CMD.modelsList]: ["terminal", "json"],
   [CMD.tagsList]: ["terminal", "json", "md"],
   [CMD.linksList]: ["terminal", "json", "md"],
@@ -72,6 +77,9 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   // graph uses custom --dot/--mermaid flags (not OutputFormat) and writes via terminal output
   [CMD.graph]: ["json", "terminal"],
   [CMD.graphQuery]: ["terminal", "json"],
+  [CMD.changes]: ["terminal", "json"],
+  [CMD.diff]: ["terminal", "json"],
+  [CMD.impact]: ["terminal", "json"],
   [CMD.capture]: ["terminal", "json"],
 };