@gmickel/gno 1.22.0 → 1.24.0

package/spec/output-schemas/setup-receipt.schema.json

@@ -0,0 +1,258 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/setup-receipt@1.0",
+  "title": "GNO Verified Folder Setup Receipt",
+  "description": "Canonical local receipt for resumable lexical-first folder setup.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "status",
+    "generatedAt",
+    "input",
+    "fingerprints",
+    "collection",
+    "paths",
+    "stages",
+    "pending",
+    "failure",
+    "activation"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "status": {
+      "enum": ["in_progress", "failed", "completed"]
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "folder",
+        "folderFingerprint",
+        "indexName",
+        "requestedName",
+        "excludes",
+        "secretRiskAuthorized"
+      ],
+      "properties": {
+        "folder": { "type": "string", "minLength": 1 },
+        "folderFingerprint": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "indexName": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "requestedName": {
+          "type": ["string", "null"],
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "excludes": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "secretRiskAuthorized": { "type": "boolean" }
+      }
+    },
+    "fingerprints": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["input", "config", "index"],
+      "properties": {
+        "input": { "$ref": "#/definitions/fingerprint" },
+        "config": {
+          "oneOf": [{ "$ref": "#/definitions/fingerprint" }, { "type": "null" }]
+        },
+        "index": {
+          "oneOf": [{ "$ref": "#/definitions/fingerprint" }, { "type": "null" }]
+        }
+      }
+    },
+    "collection": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "path", "disposition"],
+      "properties": {
+        "name": {
+          "type": ["string", "null"],
+          "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+        },
+        "path": { "type": "string", "minLength": 1 },
+        "disposition": {
+          "enum": ["pending", "created", "reused"]
+        }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["config", "receipt"],
+      "properties": {
+        "config": { "type": "string", "minLength": 1 },
+        "receipt": { "type": "string", "minLength": 1 }
+      }
+    },
+    "stages": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "preflight",
+        "config_saved",
+        "store_synced",
+        "lexical_indexed",
+        "lexical_proved",
+        "completed"
+      ],
+      "properties": {
+        "preflight": { "$ref": "#/definitions/stage" },
+        "config_saved": { "$ref": "#/definitions/stage" },
+        "store_synced": { "$ref": "#/definitions/stage" },
+        "lexical_indexed": { "$ref": "#/definitions/stage" },
+        "lexical_proved": { "$ref": "#/definitions/stage" },
+        "completed": { "$ref": "#/definitions/stage" }
+      }
+    },
+    "pending": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "failure": {
+      "oneOf": [{ "$ref": "#/definitions/failure" }, { "type": "null" }]
+    },
+    "activation": {
+      "oneOf": [
+        { "$ref": "gno://schemas/activation-verification@1.0" },
+        { "type": "null" }
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "type": "object",
+        "properties": { "status": { "const": "completed" } },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "failure": { "type": "null" },
+          "activation": {
+            "allOf": [
+              { "$ref": "gno://schemas/activation-verification@1.0" },
+              {
+                "type": "object",
+                "properties": { "ready": { "const": true } },
+                "required": ["ready"]
+              }
+            ]
+          },
+          "stages": {
+            "type": "object",
+            "properties": {
+              "preflight": {
+                "type": "object",
+                "properties": { "status": { "const": "passed" } }
+              },
+              "config_saved": {
+                "type": "object",
+                "properties": { "status": { "const": "passed" } }
+              },
+              "store_synced": {
+                "type": "object",
+                "properties": { "status": { "const": "passed" } }
+              },
+              "lexical_indexed": {
+                "type": "object",
+                "properties": { "status": { "const": "passed" } }
+              },
+              "lexical_proved": {
+                "type": "object",
+                "properties": { "status": { "const": "passed" } }
+              },
+              "completed": {
+                "type": "object",
+                "properties": { "status": { "const": "passed" } }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "type": "object",
+        "properties": { "status": { "const": "failed" } },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "failure": { "$ref": "#/definitions/failure" }
+        }
+      }
+    }
+  ],
+  "definitions": {
+    "fingerprint": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "stage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "token",
+        "startedAt",
+        "completedAt",
+        "code",
+        "remediation"
+      ],
+      "properties": {
+        "status": {
+          "enum": ["pending", "in_progress", "passed", "failed"]
+        },
+        "token": {
+          "type": ["string", "null"],
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "startedAt": {
+          "type": ["string", "null"],
+          "format": "date-time"
+        },
+        "completedAt": {
+          "type": ["string", "null"],
+          "format": "date-time"
+        },
+        "code": { "type": ["string", "null"] },
+        "remediation": { "type": ["string", "null"] }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stage", "code", "message", "remediation"],
+      "properties": {
+        "stage": {
+          "enum": [
+            "preflight",
+            "config_saved",
+            "store_synced",
+            "lexical_indexed",
+            "lexical_proved",
+            "completed"
+          ]
+        },
+        "code": { "type": "string", "minLength": 1 },
+        "message": { "type": "string", "minLength": 1 },
+        "remediation": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/spec/output-schemas/setup-semantic-receipt.schema.json

@@ -0,0 +1,195 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/setup-semantic@1.0",
+  "title": "GNO Setup Semantic Handoff Receipt",
+  "description": "Privacy-bounded state for one standalone collection-scoped semantic setup worker.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "status",
+    "generatedAt",
+    "startedAt",
+    "completedAt",
+    "jobId",
+    "collection",
+    "indexName",
+    "folderFingerprint",
+    "pid",
+    "offline",
+    "setupReceiptFingerprint",
+    "setupReceiptPath",
+    "receiptPath",
+    "logPath",
+    "resumeCommand",
+    "counts",
+    "error"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "status": {
+      "enum": [
+        "scheduled",
+        "running",
+        "completed",
+        "failed",
+        "pending",
+        "skipped"
+      ]
+    },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "startedAt": {
+      "type": ["string", "null"],
+      "format": "date-time"
+    },
+    "completedAt": {
+      "type": ["string", "null"],
+      "format": "date-time"
+    },
+    "jobId": { "$ref": "#/definitions/fingerprint" },
+    "collection": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$"
+    },
+    "indexName": { "type": "string", "minLength": 1, "maxLength": 64 },
+    "folderFingerprint": { "$ref": "#/definitions/fingerprint" },
+    "pid": {
+      "type": ["integer", "null"],
+      "minimum": 1
+    },
+    "offline": { "type": "boolean" },
+    "setupReceiptFingerprint": { "$ref": "#/definitions/fingerprint" },
+    "setupReceiptPath": { "type": "string", "minLength": 1 },
+    "receiptPath": { "type": "string", "minLength": 1 },
+    "logPath": { "type": "string", "minLength": 1 },
+    "resumeCommand": {
+      "type": "string",
+      "pattern": "^gno .* embed "
+    },
+    "counts": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["embedded", "errors"],
+          "properties": {
+            "embedded": { "type": "integer", "minimum": 0 },
+            "errors": { "type": "integer", "minimum": 0 }
+          }
+        },
+        { "type": "null" }
+      ]
+    },
+    "error": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["message", "remediation"],
+          "properties": {
+            "message": { "type": "string", "minLength": 1, "maxLength": 500 },
+            "remediation": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 8192
+            }
+          }
+        },
+        { "type": "null" }
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "status": { "const": "scheduled" } },
+        "required": ["status"]
+      },
+      "then": {
+        "properties": {
+          "startedAt": { "type": "null" },
+          "completedAt": { "type": "null" },
+          "counts": { "type": "null" },
+          "error": { "type": "null" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "status": { "const": "running" } },
+        "required": ["status"]
+      },
+      "then": {
+        "properties": {
+          "pid": { "type": "integer", "minimum": 1 },
+          "startedAt": { "type": "string", "format": "date-time" },
+          "completedAt": { "type": "null" },
+          "counts": { "type": "null" },
+          "error": { "type": "null" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "status": { "const": "completed" } },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "pid": { "type": "null" },
+          "counts": { "type": "object" },
+          "error": { "type": "null" },
+          "completedAt": { "type": "string", "format": "date-time" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "status": { "const": "failed" } },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "pid": { "type": "null" },
+          "error": { "type": "object" },
+          "completedAt": { "type": "string", "format": "date-time" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "status": { "const": "pending" } },
+        "required": ["status"]
+      },
+      "then": {
+        "properties": {
+          "completedAt": { "type": "null" },
+          "counts": { "type": "null" },
+          "error": { "type": "object" }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": { "status": { "const": "skipped" } },
+        "required": ["status"]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "counts": { "type": "null" },
+          "error": { "type": "null" },
+          "completedAt": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  ],
+  "definitions": {
+    "fingerprint": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    }
+  }
+}

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

@@ -4,6 +4,7 @@ import type { ContextEvidenceCompilerDeps } from "../core/context-evidence";
 import type { ContextVerifierDeps } from "../core/context-verifier";
 import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { EmbeddingPort, RerankPort } from "../llm/types";
+import type { ProjectAffinityScoringInput } from "../pipeline/project-affinity";
 import type { QueryModeInput } from "../pipeline/types";
 import type { StorePort } from "../store/types";
 import type { VectorIndexPort } from "../store/vector";
@@ -50,6 +51,8 @@ export interface ContextCapsuleRuntimeDeps {
   countTokens?: (accountingJson: string) => number;
   tokenizerFingerprint?: string | null;
   resolveCurrentRanks?: ContextVerifierDeps["resolveCurrentRanks"];
+  /** Trusted, already-resolved project affinity; never accepts raw inputs. */
+  projectAffinity?: ProjectAffinityScoringInput;
   /** Optional non-canonical receipt session owned by the calling surface. */
   traceSession?: RetrievalTraceSession;
 }

package/src/app/context-runtime.ts

@@ -96,6 +96,7 @@ export const buildContextCapsule = async (
           {
             ...request,
             noRerank: requestNoRerank,
+            projectAffinity: deps.projectAffinity,
             traceSession: deps.traceSession,
           }
         );

package/src/app/context-surface.ts

@@ -44,6 +44,7 @@ export const contextBuildSurfaceSchema = z
     safetyMarginTokens: nonnegativeInteger.optional(),
     safetyMarginBytes: nonnegativeInteger.optional(),
     depthPolicy: z.enum(["fast", "balanced", "thorough"]).optional(),
+    projectHints: z.array(z.string()).max(16).optional(),
     format: z.enum(["json", "md"]).optional(),
   })
   .strict();
@@ -60,6 +61,7 @@ export type ContextSurfaceFormat = "json" | "md";
 export interface ParsedContextBuildSurfaceInput {
   input: ContextCapsuleBuildInput;
   format: ContextSurfaceFormat;
+  projectHints?: string[];
 }
 
 export interface ParsedContextVerifySurfaceInput {
@@ -117,8 +119,8 @@ export const parseContextBuildSurfaceInput = (
 ): ParsedContextBuildSurfaceInput => {
   const parsed = contextBuildSurfaceSchema.safeParse(value);
   if (!parsed.success) throw invalidInput(parsed.error);
-  const { format = "json", ...input } = parsed.data;
-  return { input: { ...input, indexName }, format };
+  const { format = "json", projectHints, ...input } = parsed.data;
+  return { input: { ...input, indexName }, format, projectHints };
 };
 
 export const parseContextVerifySurfaceInput = (

package/src/cli/commands/ask.ts

@@ -5,6 +5,7 @@
  * @module src/cli/commands/ask
  */
 
+import type { CliProjectAffinityRequest } from "../../core/project-affinity-surface";
 import type { RetrievalTraceSurfaceMetadata } from "../../core/retrieval-trace-session";
 import type { RetrievalTraceSession } from "../../core/retrieval-trace-session";
 import type {
@@ -15,6 +16,7 @@ import type {
 import type { AskOptions, AskResult, Citation } from "../../pipeline/types";
 
 import { buildVerifiedAsk } from "../../app/verified-ask";
+import { resolveCliProjectAffinity } from "../../core/project-affinity-surface";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -46,24 +48,25 @@ export { formatAsk } from "./ask-format";
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type AskCommandOptions = AskOptions & {
-  /** Override config path */
-  configPath?: string;
-  /** Override embedding model */
-  embedModel?: string;
-  /** Override expansion model */
-  expandModel?: string;
-  /** Override answer generation model */
-  genModel?: string;
-  /** Override rerank model */
-  rerankModel?: string;
-  /** Output as JSON */
-  json?: boolean;
-  /** Output as Markdown */
-  md?: boolean;
-  /** Show all retrieved sources (not just cited) */
-  showSources?: boolean;
-};
+export type AskCommandOptions = Omit<AskOptions, "projectAffinity"> &
+  CliProjectAffinityRequest & {
+    /** Override config path */
+    configPath?: string;
+    /** Override embedding model */
+    embedModel?: string;
+    /** Override expansion model */
+    expandModel?: string;
+    /** Override answer generation model */
+    genModel?: string;
+    /** Override rerank model */
+    rerankModel?: string;
+    /** Output as JSON */
+    json?: boolean;
+    /** Output as Markdown */
+    md?: boolean;
+    /** Show all retrieved sources (not just cited) */
+    showSources?: boolean;
+  };
 
 export type AskCommandResult =
   | {
@@ -108,6 +111,12 @@ export async function ask(
   let traceSession: RetrievalTraceSession | undefined;
 
   try {
+    const { projectAffinityDisabled, projectRoots, ...askOptions } = options;
+    const projectAffinity = await resolveCliProjectAffinity(config, {
+      cwd: process.cwd(),
+      disabled: projectAffinityDisabled,
+      projectRoots,
+    });
     const verificationRequested = options.verify === true;
     const answerRequested =
       verificationRequested || Boolean(options.answer && !options.noAnswer);
@@ -141,7 +150,7 @@ export async function ask(
       store,
       config,
       query,
-      filters: retrievalTraceFilters({ ...options, limit }),
+      filters: retrievalTraceFilters({ ...askOptions, limit }),
       pipeline: "ask",
       indexName: globals.index,
       modelUris: [embedUri, expandUri, answerUri, rerankUri].filter(
@@ -264,7 +273,7 @@ export async function ask(
     if (verificationRequested && answerPort) {
       const verified = await buildVerifiedAsk(
         query,
-        { ...options, limit },
+        { ...askOptions, limit, projectAffinity },
         {
           store,
           config,
@@ -273,6 +282,7 @@ export async function ask(
           embedPort,
           rerankPort,
           genPort: answerPort,
+          projectAffinity,
           traceSession,
         }
       );
@@ -308,6 +318,7 @@ export async function ask(
       noExpand: options.noExpand,
       noRerank: options.noRerank,
       candidateLimit: options.candidateLimit,
+      projectAffinity,
       traceSession,
     });
 

package/src/cli/commands/completion/scripts.ts

@@ -14,6 +14,7 @@ export const SUPPORTED_SHELLS: Shell[] = ["bash", "zsh", "fish"];
  */
 const COMMANDS = [
   "init",
+  "setup",
   "index",
   "update",
   "embed",
@@ -317,6 +318,7 @@ export function getCompletionScript(shell: Shell): string {
 function getCommandDescription(cmd: string): string {
   const descriptions: Record<string, string> = {
     init: "Initialize GNO configuration",
+    setup: "Add and verify a folder",
     index: "Index files from collections",
     update: "Sync files from disk",
     embed: "Generate embeddings",