@gmickel/gno 1.16.0 → 1.18.0

package/src/mcp/tools/status.ts

@@ -8,6 +8,7 @@ import type { IndexStatus } from "../../store/types";
 import type { ToolContext } from "../server";
 
 import { resolveModelUri } from "../../llm/registry";
+import { createStandaloneResidentStatus } from "../../serve/resident-status";
 import { runTool, type ToolResult } from "./index";
 
 type StatusInput = Record<string, never>;
@@ -22,6 +23,14 @@ function formatStatus(status: IndexStatus): string {
   lines.push(`Config: ${status.configPath}`);
   lines.push(`Database: ${status.dbPath}`);
   lines.push(`Health: ${status.healthy ? "OK" : "DEGRADED"}`);
+  if ("resident" in status) {
+    const resident = status.resident as NonNullable<
+      ReturnType<NonNullable<ToolContext["getResidentStatus"]>>
+    >;
+    lines.push(
+      `Runtime: ${resident.mode}${resident.resident ? ` (${resident.transport.activeSessions} sessions)` : " (standalone)"}`
+    );
+  }
   lines.push("");
 
   if (status.collections.length === 0) {
@@ -78,6 +87,8 @@ export function handleStatus(
       return {
         ...result.value,
         configPath: ctx.actualConfigPath,
+        resident:
+          ctx.getResidentStatus?.() ?? createStandaloneResidentStatus("stdio"),
       };
     },
     formatStatus

package/src/mcp/tools/sync.ts

@@ -11,6 +11,7 @@ import type { ToolContext } from "../server";
 import { MCP_ERRORS } from "../../core/errors";
 import { acquireWriteLock, type WriteLockHandle } from "../../core/file-lock";
 import { JobError } from "../../core/job-manager";
+import { recordContentMutation } from "../../core/mutation-generations";
 import { normalizeCollectionName } from "../../core/validation";
 import { defaultSyncService, withContentTypeRules } from "../../ingestion";
 import { runTool, type ToolResult } from "./index";
@@ -113,20 +114,21 @@ export function handleSync(
           "sync",
           lock,
           async () => {
-            if (collection) {
-              const result = await defaultSyncService.syncCollection(
-                collection,
-                ctx.store,
-                options
-              );
-              return wrapSingleSync(result);
-            }
-
-            return defaultSyncService.syncAll(
-              ctx.collections,
-              ctx.store,
-              options
-            );
+            const result = collection
+              ? wrapSingleSync(
+                  await defaultSyncService.syncCollection(
+                    collection,
+                    ctx.store,
+                    options
+                  )
+                )
+              : await defaultSyncService.syncAll(
+                  ctx.collections,
+                  ctx.store,
+                  options
+                );
+            recordContentMutation(result, ctx.markContentMutation);
+            return result;
           }
         );
 

package/src/mcp/tools/workspace-write.ts

@@ -27,6 +27,7 @@ import {
   planMoveRefactor,
   planRenameRefactor,
 } from "../../core/file-refactors";
+import { recordContentMutation } from "../../core/mutation-generations";
 import { defaultSyncService, withContentTypeRules } from "../../ingestion";
 import { runTool, type ToolResult } from "./index";
 
@@ -210,11 +211,12 @@ export function handleRenameNote(
         const currentPath = join(collection.path, doc.relPath);
         const nextPath = join(collection.path, plan.nextRelPath);
         await renameFilePath(currentPath, nextPath);
-        await defaultSyncService.syncCollection(
+        const syncResult = await defaultSyncService.syncCollection(
           collection,
           ctx.store,
           withContentTypeRules({ runUpdateCmd: false }, ctx.config)
         );
+        recordContentMutation(syncResult, ctx.markContentMutation);
         return {
           uri: plan.nextUri,
           relPath: plan.nextRelPath,
@@ -255,11 +257,12 @@ export function handleMoveNote(
         const nextPath = join(collection.path, plan.nextRelPath);
         await mkdir(dirname(nextPath), { recursive: true });
         await renameFilePath(currentPath, nextPath);
-        await defaultSyncService.syncCollection(
+        const syncResult = await defaultSyncService.syncCollection(
           collection,
           ctx.store,
           withContentTypeRules({ runUpdateCmd: false }, ctx.config)
         );
+        recordContentMutation(syncResult, ctx.markContentMutation);
         return {
           uri: plan.nextUri,
           relPath: plan.nextRelPath,
@@ -308,11 +311,12 @@ export function handleDuplicateNote(
         const nextPath = join(collection.path, plan.nextRelPath);
         await mkdir(dirname(nextPath), { recursive: true });
         await copyFilePath(currentPath, nextPath);
-        await defaultSyncService.syncCollection(
+        const syncResult = await defaultSyncService.syncCollection(
           collection,
           ctx.store,
           withContentTypeRules({ runUpdateCmd: false }, ctx.config)
         );
+        recordContentMutation(syncResult, ctx.markContentMutation);
         return {
           uri: plan.nextUri,
           relPath: plan.nextRelPath,

package/src/pipeline/chunk-lookup.ts

@@ -42,3 +42,36 @@ export function createChunkLookup(
     return bySeq.get(seq);
   };
 }
+
+/**
+ * Prove that persisted chunk coordinates still address the exact stored
+ * canonical mirror bytes. Chunk text may begin or end mid-line; callers that
+ * need citation spans must expand it to full lines separately.
+ */
+export function chunkMatchesCanonicalContent(
+  chunk: ChunkRow,
+  content: string
+): boolean {
+  if (
+    content.includes("\r") ||
+    chunk.pos < 0 ||
+    chunk.startLine < 1 ||
+    chunk.endLine < chunk.startLine ||
+    chunk.text.length === 0 ||
+    chunk.pos + chunk.text.length > content.length
+  ) {
+    return false;
+  }
+  if (content.slice(chunk.pos, chunk.pos + chunk.text.length) !== chunk.text) {
+    return false;
+  }
+  let startLine = 1;
+  let endLine = 1;
+  const endOffset = chunk.pos + chunk.text.length - 1;
+  for (let offset = 0; offset < endOffset; offset += 1) {
+    if (content[offset] !== "\n") continue;
+    if (offset < chunk.pos) startLine += 1;
+    endLine += 1;
+  }
+  return startLine === chunk.startLine && endLine === chunk.endLine;
+}

package/src/pipeline/hybrid.ts

@@ -54,7 +54,10 @@ import {
   resolveTemporalRange,
   shouldSortByRecency,
 } from "./temporal";
-import { DEFAULT_PIPELINE_CONFIG } from "./types";
+import {
+  DEFAULT_PIPELINE_CONFIG,
+  SEARCH_RESULT_PLANNER_METADATA,
+} from "./types";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Dependencies
@@ -719,7 +722,16 @@ export async function searchHybrid(
   }
 
   // Build lookup maps.
-  const docByMirrorHash = new Map<string, (typeof docsResult.value)[number]>();
+  const docsByMirrorHash = new Map<
+    string,
+    (typeof docsResult.value)[number][]
+  >();
+  const addDocument = (doc: (typeof docsResult.value)[number]): void => {
+    if (!doc.mirrorHash) return;
+    const docs = docsByMirrorHash.get(doc.mirrorHash) ?? [];
+    docs.push(doc);
+    docsByMirrorHash.set(doc.mirrorHash, docs);
+  };
   const matchesMetadataFilters = (
     doc: (typeof docsResult.value)[number]
   ): boolean => {
@@ -761,7 +773,7 @@ export async function searchHybrid(
       candidateDocs.push(doc);
     } else {
       if (matchesMetadataFilters(doc)) {
-        docByMirrorHash.set(doc.mirrorHash, doc);
+        addDocument(doc);
       }
     }
   }
@@ -789,12 +801,20 @@ export async function searchHybrid(
         }
 
         if (doc.mirrorHash && matchesMetadataFilters(doc)) {
-          docByMirrorHash.set(doc.mirrorHash, doc);
+          addDocument(doc);
         }
       }
     }
   }
 
+  for (const docs of docsByMirrorHash.values()) {
+    docs.sort((left, right) => {
+      if (left.uri < right.uri) return -1;
+      if (left.uri > right.uri) return 1;
+      return left.docid < right.docid ? -1 : left.docid > right.docid ? 1 : 0;
+    });
+  }
+
   const collectionPaths = new Map<string, string>();
   if (collectionsResult.ok) {
     for (const c of collectionsResult.value) {
@@ -823,34 +843,19 @@ export async function searchHybrid(
   const seenDocids = new Set<string>();
 
   // Iterate until we have enough results (don't slice early - deduping may skip candidates)
-  for (const candidate of filteredCandidates) {
+  for (const [candidateIndex, candidate] of filteredCandidates.entries()) {
     // Stop when we have enough results
     if (results.length >= assemblyLimit) {
       break;
     }
 
     // Find document from pre-fetched map
-    const doc = docByMirrorHash.get(candidate.mirrorHash);
-    if (!doc) {
+    const candidateDocs = docsByMirrorHash.get(candidate.mirrorHash) ?? [];
+    if (candidateDocs.length === 0) {
       continue;
     }
 
     const docChunks = chunksMap.get(candidate.mirrorHash) ?? [];
-    const filterEval = evaluateDocumentChunkFilters(
-      query,
-      doc,
-      docChunks,
-      options
-    );
-    if (!filterEval.matches) {
-      continue;
-    }
-
-    // For --full mode, de-dupe by docid (keep best scoring candidate per doc)
-    if (options.full && seenDocids.has(doc.docid)) {
-      continue;
-    }
-
     // Get chunk via O(1) lookup
     // For doc-level FTS (seq=0), fall back to first available chunk if exact lookup fails
     let chunk = getChunk(candidate.mirrorHash, candidate.seq);
@@ -868,10 +873,6 @@ export async function searchHybrid(
       continue;
     }
 
-    docidMap.set(`${candidate.mirrorHash}:${candidate.seq}`, doc.docid);
-
-    const collectionPath = collectionPaths.get(doc.collection);
-
     // For --full mode, fetch full mirror content
     const snippetChunk =
       options.full || !options.intent?.trim()
@@ -907,37 +908,58 @@ export async function searchHybrid(
       // Fallback to chunk text if content unavailable
     }
 
-    seenDocids.add(doc.docid);
-
-    results.push({
-      docid: doc.docid,
-      score: candidate.blendedScore,
-      uri: doc.uri,
-      title: doc.title ?? undefined,
-      contentType: doc.contentType ?? undefined,
-      categories: doc.categories ?? undefined,
-      line: snippetChunk.startLine,
-      snippet,
-      snippetLanguage: chunk.language ?? undefined,
-      snippetRange,
-      source: {
-        relPath: doc.relPath,
-        absPath: collectionPath
-          ? `${collectionPath}/${doc.relPath}`
-          : undefined,
-        mime: doc.sourceMime,
-        ext: doc.sourceExt,
-        modifiedAt: doc.sourceMtime,
-        documentDate: doc.frontmatterDate ?? undefined,
-        sizeBytes: doc.sourceSize,
-        sourceHash: doc.sourceHash,
-      },
-      conversion: {
-        mirrorHash: candidate.mirrorHash,
-        converterId: doc.converterId ?? undefined,
-        converterVersion: doc.converterVersion ?? undefined,
-      },
-    });
+    for (const doc of candidateDocs) {
+      if (results.length >= assemblyLimit) break;
+      const filterEval = evaluateDocumentChunkFilters(
+        query,
+        doc,
+        docChunks,
+        options
+      );
+      if (!filterEval.matches || (options.full && seenDocids.has(doc.docid))) {
+        continue;
+      }
+      const docidKey = `${candidate.mirrorHash}:${candidate.seq}`;
+      if (!docidMap.has(docidKey)) docidMap.set(docidKey, doc.docid);
+      const collectionPath = collectionPaths.get(doc.collection);
+      seenDocids.add(doc.docid);
+      results.push({
+        docid: doc.docid,
+        score: candidate.blendedScore,
+        uri: doc.uri,
+        title: doc.title ?? undefined,
+        contentType: doc.contentType ?? undefined,
+        categories: doc.categories ?? undefined,
+        line: snippetChunk.startLine,
+        snippet,
+        snippetLanguage: chunk.language ?? undefined,
+        snippetRange,
+        source: {
+          relPath: doc.relPath,
+          absPath: collectionPath
+            ? `${collectionPath}/${doc.relPath}`
+            : undefined,
+          mime: doc.sourceMime,
+          ext: doc.sourceExt,
+          modifiedAt: doc.sourceMtime,
+          documentDate: doc.frontmatterDate ?? undefined,
+          sizeBytes: doc.sourceSize,
+          sourceHash: doc.sourceHash,
+        },
+        conversion: {
+          mirrorHash: candidate.mirrorHash,
+          converterId: doc.converterId ?? undefined,
+          converterVersion: doc.converterVersion ?? undefined,
+        },
+        [SEARCH_RESULT_PLANNER_METADATA]: {
+          retrievalRank: candidateIndex + 1,
+          mirrorHash: candidate.mirrorHash,
+          seq: snippetChunk.seq,
+          sources: [...candidate.sources].sort(),
+          graphExpanded: candidate.sources.includes("graph"),
+        },
+      });
+    }
   }
   timings.assemblyMs = performance.now() - assemblyStartedAt;
   timings.totalMs = performance.now() - runStartedAt;

package/src/pipeline/types.ts

@@ -37,6 +37,19 @@ export interface SnippetRange {
   endLine: number;
 }
 
+/** Symbol-keyed planner metadata; omitted from JSON/API projections. */
+export const SEARCH_RESULT_PLANNER_METADATA = Symbol(
+  "gno.searchResultPlannerMetadata"
+);
+
+export interface SearchResultPlannerMetadata {
+  retrievalRank: number;
+  mirrorHash: string;
+  seq: number;
+  sources: FusionSource[];
+  graphExpanded: boolean;
+}
+
 /** Single search result matching output schema */
 export interface SearchResult {
   docid: string;
@@ -53,6 +66,7 @@ export interface SearchResult {
   context?: string;
   source: SearchResultSource;
   conversion?: SearchResultConversion;
+  [SEARCH_RESULT_PLANNER_METADATA]?: SearchResultPlannerMetadata;
 }
 
 /** Search mode enum */

package/src/sdk/client.ts

@@ -22,6 +22,9 @@ import type {
   GnoCreateFolderResult,
   GnoCreateNoteOptions,
   GnoCreateNoteResult,
+  GnoContextInput,
+  GnoContextResult,
+  GnoContextVerificationResult,
   GnoClientInitOptions,
   GnoDuplicateNoteOptions,
   GnoEmbedOptions,
@@ -39,8 +42,21 @@ import type {
   GnoVectorSearchOptions,
 } from "./types";
 
-import { decorateUriForIndex, getIndexDbPath } from "../app/constants";
-import { INDEX_NAME_REQUIREMENTS, isValidIndexName } from "../app/index-name";
+import {
+  decorateUriForIndex,
+  DEFAULT_INDEX_NAME,
+  getIndexDbPath,
+} from "../app/constants";
+import {
+  buildContextCapsule,
+  validateContextCapsuleBuildInput,
+  verifyContextCapsuleRuntime,
+} from "../app/context-runtime";
+import {
+  canonicalizeIndexName,
+  INDEX_NAME_REQUIREMENTS,
+  isValidIndexName,
+} from "../app/index-name";
 import {
   ConfigSchema,
   loadConfig,
@@ -108,7 +124,7 @@ interface OpenedClientState {
   store: SqliteAdapter;
   llm: LlmAdapter;
   downloadPolicy: DownloadPolicy;
-  indexName?: string;
+  indexName: string;
 }
 
 interface RuntimePorts {
@@ -161,7 +177,10 @@ async function resolveClientState(
     configSource = "file";
   }
 
-  const dbPath = options.dbPath ?? getIndexDbPath(options.indexName);
+  const indexName = canonicalizeIndexName(
+    options.indexName ?? DEFAULT_INDEX_NAME
+  );
+  const dbPath = options.dbPath ?? getIndexDbPath(indexName);
   await mkdir(dirname(dbPath), { recursive: true });
 
   const store = new SqliteAdapter();
@@ -179,7 +198,7 @@ async function resolveClientState(
     llm: new LlmAdapter(config, options.cacheDir),
     downloadPolicy:
       options.downloadPolicy ?? resolveDownloadPolicy(process.env, {}),
-    indexName: options.indexName,
+    indexName,
   };
 }
 
@@ -192,7 +211,7 @@ class GnoClientImpl implements GnoClient {
   private readonly store: SqliteAdapter;
   private readonly llm: LlmAdapter;
   private readonly downloadPolicy: DownloadPolicy;
-  private readonly indexName?: string;
+  private readonly indexName: string;
   private closed = false;
 
   constructor(state: OpenedClientState) {
@@ -644,6 +663,49 @@ class GnoClientImpl implements GnoClient {
     }
   }
 
+  async context(input: GnoContextInput): Promise<GnoContextResult> {
+    this.assertOpen();
+    validateContextCapsuleBuildInput(
+      { ...input, indexName: this.indexName },
+      this.indexName,
+      this.config.collections.map((collection) => collection.name)
+    );
+    const collection =
+      input.collections?.length === 1 ? input.collections[0] : undefined;
+    const useModels = input.depthPolicy !== "fast";
+    const ports = await this.createRuntimePorts({
+      embed: useModels,
+      rerank: useModels,
+      collection,
+    });
+    try {
+      return await buildContextCapsule(
+        { ...input, indexName: this.indexName },
+        {
+          store: this.store,
+          config: this.config,
+          indexName: this.indexName,
+          vectorIndex: ports.vectorIndex,
+          embedPort: ports.embedPort,
+          rerankPort: ports.rerankPort,
+        }
+      );
+    } finally {
+      await this.disposeRuntimePorts(ports);
+    }
+  }
+
+  async verifyContext(
+    capsule: GnoContextResult
+  ): Promise<GnoContextVerificationResult> {
+    this.assertOpen();
+    return verifyContextCapsuleRuntime(capsule, {
+      store: this.store,
+      config: this.config,
+      indexName: this.indexName,
+    });
+  }
+
   async get(ref: string, options: GnoGetOptions = {}) {
     this.assertOpen();
     const resolution = resolveEffectiveIndex([ref], this.indexName);

package/src/sdk/index.ts

@@ -31,6 +31,10 @@ export type {
   GnoAskOptions,
   GnoCaptureOptions,
   GnoCaptureResult,
+  GnoContextErrorCode,
+  GnoContextInput,
+  GnoContextResult,
+  GnoContextVerificationResult,
   GnoClient,
   GnoClientInitOptions,
   GnoEmbedOptions,
@@ -51,3 +55,20 @@ export type {
   GnoUpdateOptions,
   GnoVectorSearchOptions,
 } from "./types";
+export {
+  ContextCapsuleContractError,
+  type ContextCapsuleErrorCode,
+  type ContextCapsuleV1,
+} from "../core/context-capsule";
+export {
+  ContextEvidenceError,
+  type ContextEvidenceErrorCode,
+} from "../core/context-evidence";
+export {
+  ContextVerifierError,
+  type ContextVerifierErrorCode,
+} from "../core/context-verifier";
+export {
+  ContextRuntimeError,
+  type ContextRuntimeErrorCode,
+} from "../app/context-runtime";

package/src/sdk/types.ts

@@ -4,8 +4,19 @@
  * @module src/sdk/types
  */
 
+import type {
+  ContextCapsuleBuildInput,
+  ContextRuntimeErrorCode,
+} from "../app/context-runtime";
 import type { Config } from "../config/types";
 import type { CaptureInput, CaptureReceipt } from "../core/capture";
+import type {
+  ContextCapsuleErrorCode,
+  ContextCapsuleV1,
+  ContextCapsuleVerification,
+} from "../core/context-capsule";
+import type { ContextEvidenceErrorCode } from "../core/context-evidence";
+import type { ContextVerifierErrorCode } from "../core/context-verifier";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
 import type { DocumentSection } from "../core/sections";
@@ -65,6 +76,15 @@ export type GnoVectorSearchOptions = SearchOptions & {
   model?: string;
 };
 
+export type GnoContextInput = Omit<ContextCapsuleBuildInput, "indexName">;
+export type GnoContextResult = ContextCapsuleV1;
+export type GnoContextVerificationResult = ContextCapsuleVerification;
+export type GnoContextErrorCode =
+  | ContextRuntimeErrorCode
+  | ContextCapsuleErrorCode
+  | ContextEvidenceErrorCode
+  | ContextVerifierErrorCode;
+
 export interface GnoGetOptions {
   from?: number;
   limit?: number;
@@ -185,6 +205,10 @@ export interface GnoClient {
   ): Promise<SearchResults>;
   query(query: string, options?: GnoQueryOptions): Promise<SearchResults>;
   ask(query: string, options?: GnoAskOptions): Promise<AskResult>;
+  context(input: GnoContextInput): Promise<GnoContextResult>;
+  verifyContext(
+    capsule: ContextCapsuleV1
+  ): Promise<GnoContextVerificationResult>;
   get(
     ref: string,
     options?: GnoGetOptions