@gmickel/gno 1.25.1 → 1.27.0

package/src/core/config-mutation.ts

@@ -1,5 +1,5 @@
 /**
- * Config mutation helper shared by Web UI and MCP.
+ * Canonical config mutation helper shared by every config writer.
  *
  * @module src/core/config-mutation
  */
@@ -9,27 +9,42 @@ import type { SqliteAdapter } from "../store/sqlite/adapter";
 
 import {
   formatConfigWarnings,
+  getConfigPaths,
   loadConfig,
   normalizeConfigContentTypes,
   saveConfig,
 } from "../config";
+import { resolveConfigWriteTarget } from "./config-write-lock";
 import { withWriteLock } from "./file-lock";
 
-export interface ConfigMutationContext {
-  store: SqliteAdapter;
+export interface ConfigFileMutationContext {
   configPath?: string;
-  onConfigUpdated: (config: Config) => void;
   /**
-   * Optional cross-process serialization boundary. The in-memory mutex remains
-   * authoritative within one process; callers sharing a config across
-   * processes must additionally share this OS-backed lock path.
+   * Optional first-run config factory. Callers must opt in explicitly; existing
+   * mutation surfaces keep treating a missing config as an error.
+   */
+  createConfigIfMissing?: () => Config;
+  onConfigUpdated?: (config: Config) => void;
+}
+
+export interface ConfigMutationContext extends ConfigFileMutationContext {
+  store: SqliteAdapter;
+  /**
+   * Optional targeted store projection. The default reconciles the complete
+   * config. Create/update-only callers can project a bounded subset without
+   * deleting DB-only recovery state.
    */
-  writeLockPath?: string;
+  projectStore?: (
+    store: SqliteAdapter,
+    config: Config
+  ) => Promise<{ ok: true } | { ok: false; error: string }>;
   /**
    * Runs after the selected config is durably present and before store projection.
    * Setup recovery uses this boundary to persist a truthful resumable receipt.
    */
   afterConfigSaved?: (config: Config) => Promise<void> | void;
+  /** Runs after config projection succeeds while the write lock is still held. */
+  afterStoreSynced?: (config: Config) => Promise<void> | void;
 }
 
 export type MutationResult<T = void> =
@@ -40,68 +55,130 @@ export type ApplyConfigResult<T = void> =
   | { ok: true; config: Config; value?: T }
   | { ok: false; error: string; code: string };
 
-/**
- * In-memory mutex for serializing config mutations.
- * Prevents lost updates when multiple requests try to modify config concurrently.
- */
-let configMutex: Promise<void> = Promise.resolve();
+export interface ConfigMutationState {
+  created: boolean;
+}
 
-export async function applyConfigChange<T = void>(
-  ctx: ConfigMutationContext,
-  mutate: (config: Config) => Promise<MutationResult<T>> | MutationResult<T>
+type PersistedConfigHook = (
+  config: Config
+) => Promise<{ ok: true } | { ok: false; error: string; code: string }>;
+
+async function applySerializedConfigChange<T>(
+  ctx: ConfigFileMutationContext,
+  mutate: (
+    config: Config,
+    state: ConfigMutationState
+  ) => Promise<MutationResult<T>> | MutationResult<T>,
+  afterPersist?: PersistedConfigHook
 ): Promise<ApplyConfigResult<T>> {
-  const previousMutex = configMutex;
-  let resolveMutex: () => void = () => {
-    /* no-op until assigned */
-  };
-
-  configMutex = new Promise((resolve) => {
-    resolveMutex = resolve;
-  });
-
-  try {
-    await previousMutex;
-
-    const applyFreshConfigChange = async (): Promise<ApplyConfigResult<T>> => {
-      const loadResult = await loadConfig(ctx.configPath);
-      if (!loadResult.ok) {
-        return {
-          ok: false,
-          error: loadResult.error.message,
-          code: "LOAD_ERROR",
-        };
-      }
+  const requestedConfigPath = ctx.configPath ?? getConfigPaths().configFile;
+  const writeTarget = await resolveConfigWriteTarget(requestedConfigPath);
+  const selectedConfigPath = writeTarget.configPath;
+  const applyFreshConfigChange = async (): Promise<ApplyConfigResult<T>> => {
+    const loadResult = await loadConfig(selectedConfigPath);
+    if (
+      !loadResult.ok &&
+      !(loadResult.error.code === "NOT_FOUND" && ctx.createConfigIfMissing)
+    ) {
+      return {
+        ok: false,
+        error: loadResult.error.message,
+        code: "LOAD_ERROR",
+      };
+    }
+    if (loadResult.ok) {
       for (const warning of formatConfigWarnings(loadResult.warnings)) {
         console.warn(warning);
       }
+    }
+
+    const currentConfig = loadResult.ok
+      ? loadResult.value
+      : ctx.createConfigIfMissing?.();
+    if (!currentConfig) {
+      return {
+        ok: false,
+        error: "Config file is missing",
+        code: "LOAD_ERROR",
+      };
+    }
+    const mutationResult = await mutate(currentConfig, {
+      created: !loadResult.ok,
+    });
+    if (!mutationResult.ok) {
+      return {
+        ok: false,
+        error: mutationResult.error,
+        code: mutationResult.code,
+      };
+    }
 
-      const mutationResult = await mutate(loadResult.value);
-      if (!mutationResult.ok) {
+    const normalized = normalizeConfigContentTypes(mutationResult.config);
+    for (const warning of formatConfigWarnings(normalized.warnings)) {
+      console.warn(warning);
+    }
+    const newConfig = normalized.config;
+    if (!mutationResult.skipSave) {
+      const saveResult = await saveConfig(newConfig, selectedConfigPath);
+      if (!saveResult.ok) {
         return {
           ok: false,
-          error: mutationResult.error,
-          code: mutationResult.code,
+          error: saveResult.error.message,
+          code: "SAVE_ERROR",
         };
       }
+    }
 
-      const normalized = normalizeConfigContentTypes(mutationResult.config);
-      for (const warning of formatConfigWarnings(normalized.warnings)) {
-        console.warn(warning);
-      }
-      const newConfig = normalized.config;
-      if (!mutationResult.skipSave) {
-        const saveResult = await saveConfig(newConfig, ctx.configPath);
-        if (!saveResult.ok) {
-          return {
-            ok: false,
-            error: saveResult.error.message,
-            code: "SAVE_ERROR",
-          };
-        }
-      }
+    const persisted = await afterPersist?.(newConfig);
+    if (persisted && !persisted.ok) return persisted;
+    ctx.onConfigUpdated?.(newConfig);
+
+    return { ok: true, config: newConfig, value: mutationResult.value };
+  };
+
+  try {
+    return await withWriteLock(writeTarget.lockPath, applyFreshConfigChange);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith("LOCKED:")) {
+      return { ok: false, error: error.message, code: "LOCKED" };
+    }
+    throw error;
+  }
+}
 
-      await ctx.afterConfigSaved?.(newConfig);
+/** Mutate only the selected config file under the canonical shared lock. */
+export async function applyConfigFileChange<T = void>(
+  ctx: ConfigFileMutationContext,
+  mutate: (
+    config: Config,
+    state: ConfigMutationState
+  ) => Promise<MutationResult<T>> | MutationResult<T>
+): Promise<ApplyConfigResult<T>> {
+  return applySerializedConfigChange(ctx, mutate);
+}
+
+/** Mutate config and project it to the selected store in one locked boundary. */
+export async function applyConfigChange<T = void>(
+  ctx: ConfigMutationContext,
+  mutate: (
+    config: Config,
+    state: ConfigMutationState
+  ) => Promise<MutationResult<T>> | MutationResult<T>
+): Promise<ApplyConfigResult<T>> {
+  return applySerializedConfigChange(ctx, mutate, async (newConfig) => {
+    await ctx.afterConfigSaved?.(newConfig);
 
+    if (ctx.projectStore) {
+      const projection = await ctx.projectStore(ctx.store, newConfig);
+      if (!projection.ok) {
+        console.warn(`Config saved but DB sync failed: ${projection.error}`);
+        return {
+          ok: false,
+          error: `DB sync failed: ${projection.error}`,
+          code: "SYNC_ERROR",
+        };
+      }
+    } else {
       const syncCollResult = await ctx.store.syncCollections(
         newConfig.collections
       );
@@ -129,24 +206,9 @@ export async function applyConfigChange<T = void>(
           code: "SYNC_ERROR",
         };
       }
-
-      ctx.onConfigUpdated(newConfig);
-
-      return { ok: true, config: newConfig, value: mutationResult.value };
-    };
-
-    if (!ctx.writeLockPath) {
-      return await applyFreshConfigChange();
-    }
-    try {
-      return await withWriteLock(ctx.writeLockPath, applyFreshConfigChange);
-    } catch (error) {
-      if (error instanceof Error && error.message.startsWith("LOCKED:")) {
-        return { ok: false, error: error.message, code: "LOCKED" };
-      }
-      throw error;
     }
-  } finally {
-    resolveMutex();
-  }
+
+    await ctx.afterStoreSynced?.(newConfig);
+    return { ok: true };
+  });
 }

package/src/core/config-write-lock.ts

@@ -0,0 +1,89 @@
+/**
+ * Canonical cross-process lock identity for all config writers.
+ *
+ * @module src/core/config-write-lock
+ */
+
+// node:fs/promises provides symlink-aware path operations; Bun has no equivalent for canonical path identity.
+import { lstat, readlink, realpath } from "node:fs/promises";
+// node:path provides structural path operations; Bun has no path utilities.
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+
+import { expandPath } from "../config/paths";
+
+const MISSING_PATH_ERROR_CODES = new Set(["ENOENT", "ENOTDIR"]);
+
+function isMissingPathError(cause: unknown): boolean {
+  return (
+    cause instanceof Error &&
+    "code" in cause &&
+    typeof cause.code === "string" &&
+    MISSING_PATH_ERROR_CODES.has(cause.code)
+  );
+}
+
+async function canonicalizeProspectivePath(
+  absolutePath: string,
+  seenLinks: Set<string>
+): Promise<string> {
+  const unresolved: string[] = [];
+  let candidate = absolutePath;
+
+  while (true) {
+    try {
+      const info = await lstat(candidate);
+      if (info.isSymbolicLink()) {
+        if (seenLinks.has(candidate)) {
+          throw new Error(`Config path contains a symlink loop: ${candidate}`);
+        }
+        seenLinks.add(candidate);
+
+        const linkTarget = await readlink(candidate);
+        const absoluteTarget = isAbsolute(linkTarget)
+          ? linkTarget
+          : resolve(dirname(candidate), linkTarget);
+        const canonicalTarget = await canonicalizeProspectivePath(
+          absoluteTarget,
+          seenLinks
+        );
+        return resolve(canonicalTarget, ...unresolved.reverse());
+      }
+
+      const canonicalAncestor = await realpath(candidate);
+      return resolve(canonicalAncestor, ...unresolved.reverse());
+    } catch (cause) {
+      if (!isMissingPathError(cause)) throw cause;
+
+      const parent = dirname(candidate);
+      if (parent === candidate) return absolutePath;
+      unresolved.push(basename(candidate));
+      candidate = parent;
+    }
+  }
+}
+
+/**
+ * Resolve an existing path, or resolve its nearest existing ancestor while
+ * retaining unresolved path components. This makes aliases of the same config
+ * file converge before the file exists and after it is created.
+ */
+export async function canonicalOperationalPath(path: string): Promise<string> {
+  return canonicalizeProspectivePath(resolve(expandPath(path)), new Set());
+}
+
+/** One stable sibling lock for every writer of the selected config file. */
+export async function resolveConfigWriteTarget(
+  configPath: string
+): Promise<{ configPath: string; lockPath: string }> {
+  const canonicalConfigPath = await canonicalOperationalPath(configPath);
+  return {
+    configPath: canonicalConfigPath,
+    lockPath: `${canonicalConfigPath}.write.lock`,
+  };
+}
+
+export async function getConfigWriteLockPath(
+  configPath: string
+): Promise<string> {
+  return (await resolveConfigWriteTarget(configPath)).lockPath;
+}

package/src/core/context-compiler.ts

@@ -11,6 +11,7 @@ import type {
   HybridSearchOptions,
   QueryModeInput,
   SearchMeta,
+  SearchExplain,
   SearchResult,
   SearchResults,
 } from "../pipeline/types";
@@ -113,6 +114,8 @@ export interface ContextCompilerInput {
   limits: ContextBudgetLimits;
   /** One caller-owned, successfully loaded context snapshot for this plan. */
   contextSnapshot: ContextRow[];
+  /** Internal non-canonical retrieval explanation request. */
+  explain?: boolean;
 }
 
 export interface ContextRetrievalPlan {
@@ -159,6 +162,8 @@ export interface ContextEvidencePlan<
   uriPrefix: string | null;
   retrieval: ContextRetrievalPlan;
   configuredContexts: ContextConfiguredGuidance[];
+  /** Non-canonical scoring sidecar; never included in Capsule projection. */
+  explain?: SearchExplain;
 }
 
 const compareCodeUnits = (left: string, right: string): number => {
@@ -365,6 +370,7 @@ export const planContextEvidence = async <T, P>(
         limit: resultLimit === undefined ? undefined : Math.max(1, resultLimit),
         candidateLimit:
           rerankLimit === undefined ? undefined : Math.max(1, rerankLimit),
+        explain: input.explain,
       })
     );
   }
@@ -393,6 +399,33 @@ export const planContextEvidence = async <T, P>(
     .slice(0, input.limit ?? decoratedResults.length)
     .map(({ result }) => result)
     .sort(compareSearchResults);
+  const explainByResult = new Map<string, SearchExplain["results"][number]>();
+  for (const response of responses) {
+    for (const [index, result] of response.results.entries()) {
+      const detail = response.meta.explain?.results[index];
+      if (detail) explainByResult.set(`${result.docid}\0${result.uri}`, detail);
+    }
+  }
+  const explain = input.explain
+    ? {
+        lines: responses.flatMap(
+          (response) => response.meta.explain?.lines ?? []
+        ),
+        results: results.flatMap((result) => {
+          const detail = explainByResult.get(`${result.docid}\0${result.uri}`);
+          const retrievalRank = plannerMeta(result)?.retrievalRank;
+          return detail
+            ? [
+                {
+                  ...detail,
+                  rank: retrievalRank ?? detail.rank,
+                  score: result.score,
+                },
+              ]
+            : [];
+        }),
+      }
+    : undefined;
   const uriPrefix =
     input.uriPrefix === null || input.uriPrefix === undefined
       ? null
@@ -528,5 +561,9 @@ export const planContextEvidence = async <T, P>(
     projectCanonical: (state) =>
       deps.projectCanonical({ ...baseDraft, selection: state }),
   });
-  return { ...baseDraft, ...selection };
+  return {
+    ...baseDraft,
+    ...selection,
+    ...(explain ? { explain } : {}),
+  };
 };

package/src/core/context-identity.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical identity helpers for persisted context records.
+ *
+ * @module src/core/context-identity
+ */
+
+const BYTE_ORDER_MARK_PATTERN = /^\uFEFF/u;
+const CARRIAGE_RETURN_PATTERN = /\r\n?/g;
+
+export function normalizePersistedContextText(text: string): string {
+  return text
+    .replace(BYTE_ORDER_MARK_PATTERN, "")
+    .replace(CARRIAGE_RETURN_PATTERN, "\n")
+    .normalize("NFC")
+    .trim();
+}

package/src/core/context-resolver.ts

@@ -1,9 +1,7 @@
 import type { ContextRow, StorePort } from "../store/types";
 
 import { parseUri } from "../app/constants";
-
-const CARRIAGE_RETURN_PATTERN = /\r\n?/g;
-const BYTE_ORDER_MARK_PATTERN = /^\uFEFF/u;
+import { normalizePersistedContextText } from "./context-identity";
 
 export interface ContextDocumentIdentity {
   collection: string;
@@ -73,14 +71,6 @@ function normalizeIdentity(
   return { collection, relPath };
 }
 
-function normalizeText(text: string): string {
-  return text
-    .replace(BYTE_ORDER_MARK_PATTERN, "")
-    .replace(CARRIAGE_RETURN_PATTERN, "\n")
-    .normalize("NFC")
-    .trim();
-}
-
 function byteKey(text: string): string {
   return [...new TextEncoder().encode(text)].join(",");
 }
@@ -95,7 +85,7 @@ function normalizeContext(
   context: ContextRow,
   identity: NormalizedIdentity
 ): MatchingContext | null {
-  const text = normalizeText(context.text);
+  const text = normalizePersistedContextText(context.text);
   if (!text) {
     return null;
   }

package/src/core/folder-setup-planning.ts

@@ -24,13 +24,7 @@ import { isCanonicalPathContained, validateCollectionRoot } from "./validation";
 
 const INVALID_NAME_CHARS = /[^a-z0-9_-]/g;
 const LEADING_NON_ALPHANUMERIC = /^[^a-z0-9]+/;
-const SECRET_FILE_PATTERNS = [
-  /^\.env(?:\.|$)/,
-  /^credentials?(?:\.|$)/,
-  /^id_(?:rsa|dsa|ecdsa|ed25519)(?:\.|$)/,
-  /^secrets?(?:\.|$)/,
-  /\.(?:key|pem|p12|pfx)$/i,
-];
+import { hasLikelySecretPath, matchesCollectionExclusion } from "./path-rules";
 
 export type FolderSetupErrorCode =
   | "folder_not_found"
@@ -110,18 +104,6 @@ export function setupInjectedFailure(checkpoint: string): FolderSetupError {
   );
 }
 
-function isExcluded(relPath: string, excludes: string[]): boolean {
-  const parts = relPath.split("/");
-  return excludes.some(
-    (exclude) => parts.includes(exclude) || relPath.startsWith(`${exclude}/`)
-  );
-}
-
-function hasSecretRisk(relPath: string): boolean {
-  const fileName = basename(relPath).toLowerCase();
-  return SECRET_FILE_PATTERNS.some((pattern) => pattern.test(fileName));
-}
-
 async function listFolderFiles(folder: string): Promise<string[]> {
   const files: string[] = [];
   const glob = new Bun.Glob("**/*");
@@ -345,7 +327,7 @@ export async function preflightFolder(
   let files: string[];
   try {
     files = (await listFolderFiles(folder)).filter(
-      (path) => !isExcluded(path, excludes)
+      (path) => !matchesCollectionExclusion(path, excludes)
     );
   } catch {
     return setupError(
@@ -361,7 +343,10 @@ export async function preflightFolder(
       "Add supported documents or choose another folder."
     );
   }
-  if (!secretRiskAuthorized && files.some((path) => hasSecretRisk(path))) {
+  if (
+    !secretRiskAuthorized &&
+    files.some((path) => hasLikelySecretPath(path))
+  ) {
     return setupError(
       "secret_risk",
       `Folder contains likely credential or secret files: ${folder}`,

package/src/core/folder-setup.ts

@@ -12,6 +12,7 @@ import { DEFAULT_EXCLUDES, loadConfig } from "../config";
 import { defaultSyncService, withContentTypeRules } from "../ingestion";
 import { verifyLexicalActivation } from "./activation-verifier";
 import { applyConfigChange } from "./config-mutation";
+import { getConfigWriteLockPath } from "./config-write-lock";
 import {
   type CollectionSelection,
   type FolderSetupError,
@@ -60,6 +61,11 @@ export interface FolderSetupOptions {
   name?: string;
   exclude?: string[];
   secretRiskAuthorized?: boolean;
+  /**
+   * Preserve store-only recovery state while projecting the selected
+   * collection. Project-profile setup uses this after its own additive apply.
+   */
+  additiveStoreProjection?: boolean;
   /** Test-only deterministic interruption hook. */
   failureInjection?: FolderSetupFailurePoint;
   /** Test-only concurrency seam before the serialized config boundary. */
@@ -149,7 +155,7 @@ export async function setupFolder(
     indexName: storeIdentity.indexName,
     folderRealpath: folder,
   });
-  const configLockPath = `${options.configPath}.setup.lock`;
+  const configLockPath = await getConfigWriteLockPath(options.configPath);
   const unsafeOutput = await validateSetupOutputPaths(folder, [
     { label: "Data directory", path: options.dataDir },
     { label: "Setup receipt", path: receiptPath },
@@ -250,7 +256,6 @@ export async function setupFolder(
       {
         store: options.store,
         configPath: options.configPath,
-        writeLockPath: configLockPath,
         onConfigUpdated: (config) => {
           activeConfig = config;
         },
@@ -292,6 +297,29 @@ export async function setupFolder(
             throw new SetupAbort(storeReceiptFailure);
           }
         },
+        projectStore: options.additiveStoreProjection
+          ? async (store, config) => {
+              const selected = activeSelection;
+              if (!selected) {
+                return {
+                  ok: false,
+                  error: "Setup collection selection was not established",
+                };
+              }
+              const collectionResult = await store.upsertCollections([
+                selected.collection,
+              ]);
+              if (!collectionResult.ok) {
+                return { ok: false, error: collectionResult.error.message };
+              }
+              const contextResult = await store.upsertContexts(
+                config.contexts ?? []
+              );
+              return contextResult.ok
+                ? { ok: true }
+                : { ok: false, error: contextResult.error.message };
+            }
+          : undefined,
       },
       async (config) => {
         const fresh = await selectFolderCollection(

package/src/core/path-rules.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared path-rule semantics for profile validation, setup preflight, and
+ * ingestion. Paths use repository-relative POSIX form at this boundary.
+ *
+ * @module src/core/path-rules
+ */
+
+const GLOB_META_PATTERN = /[*?[\]{}]/;
+const SECRET_FILE_PATTERNS = [
+  /^\.env(?:\.|$)/i,
+  /^credentials?(?:\.|$)/i,
+  /^id_(?:rsa|dsa|ecdsa|ed25519)(?:\.|$)/i,
+  /^secrets?(?:\.|$)/i,
+  /\.(?:key|pem|p12|pfx)$/i,
+];
+
+export function hasLikelySecretPath(path: string): boolean {
+  const normalized = path.replaceAll("\\", "/");
+  const fileName = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return SECRET_FILE_PATTERNS.some((pattern) => pattern.test(fileName));
+}
+
+export function hasGlobMeta(pattern: string): boolean {
+  return GLOB_META_PATTERN.test(pattern);
+}
+
+/**
+ * Bare values preserve historical component/prefix semantics. Values with
+ * glob metacharacters match the complete normalized relative path.
+ */
+export function matchesCollectionExclusion(
+  relPath: string,
+  excludes: readonly string[]
+): boolean {
+  const normalizedPath = relPath.replaceAll("\\", "/");
+  const parts = normalizedPath.split("/");
+
+  for (const rawPattern of excludes) {
+    const pattern = rawPattern.replaceAll("\\", "/");
+    if (hasGlobMeta(pattern)) {
+      if (new Bun.Glob(pattern).match(normalizedPath)) return true;
+      continue;
+    }
+    if (
+      parts.includes(pattern) ||
+      normalizedPath === pattern ||
+      normalizedPath.startsWith(`${pattern}/`)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}