@gmickel/gno 1.25.1 → 1.27.0

package/spec/output-schemas/status.schema.json

@@ -15,6 +15,7 @@
     "recentErrors",
     "activePreset",
     "capabilities",
+    "contentTypeBoost",
     "activation",
     "onboarding",
     "health",
@@ -136,6 +137,29 @@
         }
       }
     },
+    "contentTypeBoost": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rulesFingerprint", "rules"],
+      "properties": {
+        "rulesFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "searchBoost"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "searchBoost": { "type": "number", "minimum": 0.5, "maximum": 2 }
+            }
+          }
+        }
+      }
+    },
     "activation": {
       "type": "object",
       "additionalProperties": false,

package/spec/project-profile.schema.json

@@ -0,0 +1,303 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://gno.sh/schemas/project-profile-1.0.json",
+  "title": "GNO project retrieval profile",
+  "description": "Portable, declarative retrieval state for a single project collection.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "collection"],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "collection": {
+      "$ref": "#/definitions/collection"
+    },
+    "contexts": {
+      "type": "array",
+      "maxItems": 64,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/definitions/context"
+      },
+      "default": []
+    },
+    "contentTypes": {
+      "type": "object",
+      "maxProperties": 64,
+      "propertyNames": {
+        "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/contentType"
+      },
+      "default": {}
+    },
+    "affinityDefaults": {
+      "$ref": "#/definitions/affinityDefaults"
+    },
+    "recommendedCapabilities": {
+      "type": "array",
+      "maxItems": 32,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9._-]{0,63}$"
+      },
+      "default": []
+    }
+  },
+  "definitions": {
+    "portableRule": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 512,
+      "allOf": [
+        {
+          "not": {
+            "type": "string",
+            "pattern": "^(?:[/\\\\]|[A-Za-z]:|~)"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "[{}]"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "^!"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "[<>:\"|\\u0000-\\u001f]"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "(?:^|[\\\\/])(?:[cC][oO][nN]|[pP][rR][nN]|[aA][uU][xX]|[nN][uU][lL]|[cC][oO][mM][1-9]|[lL][pP][tT][1-9])(?:\\.[^\\\\/]*)?(?:[\\\\/]|$)"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "(?:^|[\\\\/])(?:[^.\\\\/][^\\\\/]*|\\.[^\\\\/]+)[. ](?:[\\\\/]|$)"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "(?:\\$\\{|\\$[A-Za-z_]|%[A-Za-z_][A-Za-z0-9_]*%)"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "\\u0000"
+          }
+        }
+      ]
+    },
+    "portablePath": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/portableRule"
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "[*?\\[\\]{}]"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "(?:^|[\\\\/])\\.[gG][nN][oO](?:[\\\\/]|$)"
+          }
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "\\.(?:[dD][bB]|[sS][qQ][lL][iI][tT][eE](?:3)?|[gG][gG][uU][fF]|[lL][oO][cC][kK])$"
+          }
+        }
+      ]
+    },
+    "portableInclude": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/portableRule"
+        },
+        {
+          "not": {
+            "type": "string",
+            "pattern": "(?:^|[\\\\/])\\.[gG][nN][oO](?:[\\\\/]|$)|\\.(?:[dD][bB]|[sS][qQ][lL][iI][tT][eE](?:3)?|[gG][gG][uU][fF]|[lL][oO][cC][kK])$"
+          }
+        }
+      ]
+    },
+    "collection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+        },
+        "root": {
+          "$ref": "#/definitions/portablePath",
+          "default": "."
+        },
+        "include": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 128,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/portableInclude"
+          },
+          "default": ["**/*"]
+        },
+        "exclude": {
+          "type": "array",
+          "maxItems": 128,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/portableRule"
+          },
+          "default": []
+        },
+        "languageHint": {
+          "type": "string",
+          "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z]{2}|-[A-Za-z]{4})?$"
+        },
+        "modelPreset": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+        }
+      }
+    },
+    "inlineContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text"],
+      "properties": {
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 65536
+        }
+      }
+    },
+    "fileContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["file"],
+      "properties": {
+        "file": {
+          "allOf": [
+            {
+              "$ref": "#/definitions/portablePath"
+            },
+            {
+              "not": {
+                "type": "string",
+                "pattern": "(?:^|[\\\\/])(?:\\.[eE][nN][vV](?:\\..*)?|[cC][rR][eE][dD][eE][nN][tT][iI][aA][lL][sS]?(?:\\..*)?|[iI][dD]_(?:[rR][sS][aA]|[dD][sS][aA]|[eE][cC][dD][sS][aA]|[eE][dD]25519)(?:\\..*)?|[sS][eE][cC][rR][eE][tT][sS]?(?:\\..*)?|[^\\\\/]+\\.(?:[kK][eE][yY]|[pP][eE][mM]|[pP]12|[pP][fF][xX]))$"
+              }
+            }
+          ]
+        }
+      }
+    },
+    "context": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/inlineContext"
+        },
+        {
+          "$ref": "#/definitions/fileContext"
+        }
+      ]
+    },
+    "contentType": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["prefixes", "preset"],
+      "properties": {
+        "prefixes": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/portablePath"
+          }
+        },
+        "preset": {
+          "enum": [
+            "blank",
+            "project-note",
+            "research-note",
+            "decision-note",
+            "prompt-pattern",
+            "source-summary",
+            "idea-original",
+            "person",
+            "company-project",
+            "meeting"
+          ]
+        },
+        "graphHints": {
+          "type": "array",
+          "maxItems": 16,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          }
+        },
+        "searchBoost": {
+          "type": "number",
+          "minimum": 0.5,
+          "maximum": 2
+        },
+        "temporal": {
+          "type": "boolean"
+        }
+      }
+    },
+    "affinityDefaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true
+        },
+        "contribution": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 0.03,
+          "default": 0.03
+        }
+      },
+      "default": {
+        "enabled": true,
+        "contribution": 0.03
+      }
+    }
+  }
+}

package/src/app/context-runtime-contract.ts

@@ -26,7 +26,10 @@ const fingerprint = (value: unknown): string =>
 
 export const contextRuntimeConfigFingerprint = (
   deps: Pick<ContextCapsuleRuntimeDeps, "config">
-): string => fingerprint(deps.config);
+): string =>
+  fingerprint(
+    JSON.parse(JSON.stringify(deps.config)) as Record<string, unknown>
+  );
 
 const configuredContextFingerprint = (
   deps: ContextCapsuleRuntimeDeps

package/src/app/context-runtime-types.ts

@@ -55,6 +55,8 @@ export interface ContextCapsuleRuntimeDeps {
   projectAffinity?: ProjectAffinityScoringInput;
   /** Optional non-canonical receipt session owned by the calling surface. */
   traceSession?: RetrievalTraceSession;
+  /** Internal non-canonical retrieval explanation request. */
+  explain?: boolean;
 }
 
 export type ContextRuntimeErrorCode =

package/src/app/context-runtime.ts

@@ -4,6 +4,7 @@ import type {
   ContextCapsuleV1,
   ContextCapsuleVerification,
 } from "../core/context-capsule";
+import type { SearchExplain } from "../pipeline/types";
 import type {
   ContextCapsuleBuildInput,
   ContextCapsuleRuntimeDeps,
@@ -36,6 +37,19 @@ export type {
 } from "./context-runtime-types";
 export { ContextRuntimeError } from "./context-runtime-types";
 
+export const CONTEXT_CAPSULE_EXPLAIN_METADATA = Symbol(
+  "gno.contextCapsuleExplainMetadata"
+);
+
+export const getContextCapsuleExplain = (
+  capsule: ContextCapsuleV1
+): SearchExplain | undefined =>
+  (
+    capsule as ContextCapsuleV1 & {
+      [CONTEXT_CAPSULE_EXPLAIN_METADATA]?: SearchExplain;
+    }
+  )[CONTEXT_CAPSULE_EXPLAIN_METADATA];
+
 /** Build one strict Capsule through the shared compiler composition. */
 export const buildContextCapsule = async (
   input: ContextCapsuleBuildInput,
@@ -72,6 +86,7 @@ export const buildContextCapsule = async (
       limit: normalized.limit,
       candidateLimit: normalized.candidateLimit,
       temporalNow: now,
+      explain: deps.explain,
       limits: {
         requestedBytes: normalized.budgetBytes,
         requestedTokens: normalized.budgetTokens,
@@ -134,6 +149,17 @@ export const buildContextCapsule = async (
       traceResult.error.cause
     );
   }
+  if (plan.explain) {
+    Object.defineProperty(
+      plan.projection.value,
+      CONTEXT_CAPSULE_EXPLAIN_METADATA,
+      {
+        configurable: true,
+        enumerable: false,
+        value: plan.explain,
+      }
+    );
+  }
   return plan.projection.value;
 };
 

package/src/app/verified-ask.ts

@@ -16,6 +16,7 @@ import { attachCitationTraceMetadata } from "../pipeline/trace-metadata";
 import { CITATION_TRACE_METADATA } from "../pipeline/types";
 import {
   buildContextCapsule,
+  getContextCapsuleExplain,
   verifyContextCapsuleRuntime,
 } from "./context-runtime";
 import { contextRuntimeConfigFingerprint } from "./context-runtime-contract";
@@ -199,7 +200,7 @@ export const buildVerifiedAsk = async (
       budgetBytes: options.contextBudgetBytes,
       depthPolicy: "balanced",
     },
-    deps
+    { ...deps, explain: options.explain }
   );
   const freshness = await verifyContextCapsuleRuntime(capsule, deps);
   return synthesizeVerifiedAsk(query, options, capsule, freshness, deps);
@@ -258,6 +259,9 @@ export const synthesizeVerifiedAsk = async (
     citationEvidenceIds(verification, new Set(["supported", "contradicted"]))
   );
   await recordRetainedCitations(deps.traceSession, traceCitations);
+  const retrievalExplain = options.explain
+    ? getContextCapsuleExplain(capsule)
+    : undefined;
   return {
     query,
     mode: capsule.capabilities.semanticSearch ? "hybrid" : "bm25_only",
@@ -276,6 +280,7 @@ export const synthesizeVerifiedAsk = async (
       exclude: capsule.retrieval.request.exclude,
       answerGenerated: generated.ok,
       totalResults: capsule.evidence.length,
+      ...(retrievalExplain ? { explain: retrievalExplain } : {}),
       verificationRequested: true,
       abstained: verification.verification.abstained,
     },

package/src/cli/commands/ask.ts

@@ -48,7 +48,10 @@ export { formatAsk } from "./ask-format";
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type AskCommandOptions = Omit<AskOptions, "projectAffinity"> &
+export type AskCommandOptions = Omit<
+  AskOptions,
+  "contentTypeRules" | "projectAffinity"
+> &
   CliProjectAffinityRequest & {
     /** Override config path */
     configPath?: string;
@@ -318,6 +321,7 @@ export async function ask(
       noExpand: options.noExpand,
       noRerank: options.noRerank,
       candidateLimit: options.candidateLimit,
+      explain: options.explain,
       projectAffinity,
       traceSession,
     });
@@ -397,6 +401,9 @@ export async function ask(
         answerGenerated,
         totalResults: results.length,
         answerContext,
+        ...(options.explain && searchResult.value.meta.explain
+          ? { explain: searchResult.value.meta.explain }
+          : {}),
       },
     };
 

package/src/cli/commands/collection/add.ts

@@ -3,12 +3,8 @@
  */
 
 import { addCollection } from "../../../collection";
-import {
-  loadConfig,
-  pathExists,
-  saveConfig,
-  toAbsolutePath,
-} from "../../../config";
+import { pathExists, toAbsolutePath } from "../../../config";
+import { applyConfigFileChange } from "../../../core/config-mutation";
 import { CliError } from "../../errors";
 
 interface AddOptions {
@@ -18,6 +14,7 @@ interface AddOptions {
   include?: string;
   exclude?: string;
   update?: string;
+  configPath?: string;
 }
 
 export async function collectionAdd(
@@ -36,52 +33,49 @@ export async function collectionAdd(
     throw new CliError("VALIDATION", `Path does not exist: ${absolutePath}`);
   }
 
-  // Load config
-  const configResult = await loadConfig();
-  if (!configResult.ok) {
-    throw new CliError(
-      "RUNTIME",
-      `Failed to load config: ${configResult.error.message}`
-    );
-  }
-
-  // Add collection using shared module
-  const result = await addCollection(configResult.value, {
-    path,
-    name: options.name,
-    pattern: options.pattern,
-    include: options.include,
-    exclude: options.exclude,
-    models: options.embedModel
-      ? {
-          embed: options.embedModel,
-        }
-      : undefined,
-    updateCmd: options.update,
-  });
+  const mutation = await applyConfigFileChange(
+    { configPath: options.configPath },
+    async (config) => {
+      const result = await addCollection(config, {
+        path,
+        name: options.name!,
+        pattern: options.pattern,
+        include: options.include,
+        exclude: options.exclude,
+        models: options.embedModel
+          ? {
+              embed: options.embedModel,
+            }
+          : undefined,
+        updateCmd: options.update,
+      });
+      return result.ok
+        ? {
+            ok: true as const,
+            config: result.config,
+            value: result.collection,
+          }
+        : {
+            ok: false as const,
+            error: result.message,
+            code: result.code,
+          };
+    }
+  );
 
-  if (!result.ok) {
+  if (!mutation.ok) {
     // Map collection error codes to CLI error codes
     const cliCode =
-      result.code === "VALIDATION" ||
-      result.code === "PATH_NOT_FOUND" ||
-      result.code === "DUPLICATE"
+      mutation.code === "VALIDATION" ||
+      mutation.code === "PATH_NOT_FOUND" ||
+      mutation.code === "DUPLICATE"
         ? "VALIDATION"
         : "RUNTIME";
-    throw new CliError(cliCode, result.message);
-  }
-
-  // Save config
-  const saveResult = await saveConfig(result.config);
-  if (!saveResult.ok) {
-    throw new CliError(
-      "RUNTIME",
-      `Failed to save config: ${saveResult.error.message}`
-    );
+    throw new CliError(cliCode, mutation.error);
   }
 
   process.stdout.write(
-    `Collection "${result.collection.name}" added successfully\n`
+    `Collection "${mutation.value?.name}" added successfully\n`
   );
-  process.stdout.write(`Path: ${result.collection.path}\n`);
+  process.stdout.write(`Path: ${mutation.value?.path}\n`);
 }

package/src/cli/commands/collection/remove.ts

@@ -3,43 +3,43 @@
  */
 
 import { removeCollection } from "../../../collection";
-import { loadConfig, saveConfig } from "../../../config";
+import { applyConfigFileChange } from "../../../core/config-mutation";
 import { CliError } from "../../errors";
 
-export async function collectionRemove(name: string): Promise<void> {
-  // Load config
-  const configResult = await loadConfig();
-  if (!configResult.ok) {
-    throw new CliError(
-      "RUNTIME",
-      `Failed to load config: ${configResult.error.message}`
-    );
-  }
-
-  // Remove collection using shared module
-  const result = removeCollection(configResult.value, { name });
+export async function collectionRemove(
+  name: string,
+  options: { configPath?: string } = {}
+): Promise<void> {
+  const mutation = await applyConfigFileChange(
+    { configPath: options.configPath },
+    (config) => {
+      const result = removeCollection(config, { name });
+      return result.ok
+        ? {
+            ok: true as const,
+            config: result.config,
+            value: result.collection,
+          }
+        : {
+            ok: false as const,
+            error: result.message,
+            code: result.code,
+          };
+    }
+  );
 
-  if (!result.ok) {
+  if (!mutation.ok) {
     // Map collection error codes to CLI error codes
     const cliCode =
-      result.code === "VALIDATION" ||
-      result.code === "NOT_FOUND" ||
-      result.code === "HAS_REFERENCES"
+      mutation.code === "VALIDATION" ||
+      mutation.code === "NOT_FOUND" ||
+      mutation.code === "HAS_REFERENCES"
         ? "VALIDATION"
         : "RUNTIME";
-    throw new CliError(cliCode, result.message);
-  }
-
-  // Save config
-  const saveResult = await saveConfig(result.config);
-  if (!saveResult.ok) {
-    throw new CliError(
-      "RUNTIME",
-      `Failed to save config: ${saveResult.error.message}`
-    );
+    throw new CliError(cliCode, mutation.error);
   }
 
   process.stdout.write(
-    `Collection "${result.collection.name}" removed successfully\n`
+    `Collection "${mutation.value?.name}" removed successfully\n`
   );
 }