@gmickel/gno 2.3.3 → 2.5.1

package/src/core/retrieval-trace.ts

@@ -29,6 +29,7 @@ import {
   legacyLocalOnlyEgressLineage,
 } from "./egress-provenance";
 import { canonicalizeRetrievalTraceFilters } from "./retrieval-trace-filter-normalization";
+import { metadataPredicateSchema } from "./typed-metadata";
 
 const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
 const gnoUriSchema = z
@@ -57,6 +58,7 @@ export const traceFiltersSchema = z
     since: z.string().max(128).optional(),
     until: z.string().max(128).optional(),
     categories: z.array(z.string().max(512)).max(1000).optional(),
+    filter: metadataPredicateSchema.optional(),
     author: z.string().max(1024).optional(),
     intent: z.string().max(8192).optional(),
     exclude: z.array(z.string().max(1024)).max(1000).optional(),

package/src/core/setup-receipt.ts

@@ -12,6 +12,7 @@ import { dirname, join } from "node:path";
 import type { ActivationVerificationReceipt } from "../store/types";
 
 import { canonicalizeIndexName } from "../app/index-name";
+import { withWriteLock } from "./file-lock";
 
 export const SETUP_RECEIPT_SCHEMA_VERSION = "1.0" as const;
 
@@ -278,27 +279,33 @@ export async function persistSetupReceipt(
 ): Promise<void> {
   const receiptDir = dirname(receipt.paths.receipt);
   await mkdir(receiptDir, { recursive: true, mode: 0o700 });
-  await chmod(receiptDir, 0o700);
+  // Windows cannot reliably replace the same destination concurrently.
+  // Reuse the process-shared writer lock; each completed receipt stays atomic.
+  await withWriteLock(`${receipt.paths.receipt}.lock`, async () => {
+    await chmod(receiptDir, 0o700);
 
-  const tempPath = `${receipt.paths.receipt}.tmp.${crypto.randomUUID()}`;
-  let tempFile: Awaited<ReturnType<typeof open>> | null = null;
-  try {
-    tempFile = await open(tempPath, "wx", 0o600);
-    await tempFile.writeFile(serializeSetupReceipt(receipt), "utf8");
-    await tempFile.sync();
-    await tempFile.close();
-    tempFile = null;
-    await rename(tempPath, receipt.paths.receipt);
-    await chmod(receipt.paths.receipt, 0o600);
-  } catch (error) {
-    await tempFile?.close().catch(() => {
-      /* best-effort temporary receipt handle cleanup */
-    });
-    await unlink(tempPath).catch(() => {
-      /* best-effort temporary receipt cleanup */
-    });
-    throw error;
-  }
+    const tempPath = `${receipt.paths.receipt}.tmp.${crypto.randomUUID()}`;
+    let tempFile: Awaited<ReturnType<typeof open>> | null = null;
+    try {
+      tempFile = await open(tempPath, "wx", 0o600);
+      await tempFile.writeFile(serializeSetupReceipt(receipt), "utf8");
+      // Set permissions before publication. Opening the shared destination for
+      // chmod can prevent a concurrent atomic replacement on Windows.
+      await tempFile.chmod(0o600);
+      await tempFile.sync();
+      await tempFile.close();
+      tempFile = null;
+      await rename(tempPath, receipt.paths.receipt);
+    } catch (error) {
+      await tempFile?.close().catch(() => {
+        /* best-effort temporary receipt handle cleanup */
+      });
+      await unlink(tempPath).catch(() => {
+        /* best-effort temporary receipt cleanup */
+      });
+      throw error;
+    }
+  });
 }
 
 export async function loadSetupReceipt(

package/src/core/typed-metadata.ts

@@ -0,0 +1,228 @@
+/** Bounded custom metadata and the shared, type-strict retrieval predicate. */
+import { z } from "zod";
+
+export type MetadataScalar = string | number | boolean;
+export type TypedValue = MetadataScalar | MetadataScalar[];
+export type TypedMetadata = Record<string, TypedValue>;
+export type MetadataPredicate =
+  | { op: "and" | "or"; predicates: MetadataPredicate[] }
+  | { op: "not"; predicate: MetadataPredicate }
+  | { op: "eq" | "ne"; key: string; value: MetadataScalar }
+  | { op: "gt" | "gte" | "lt" | "lte"; key: string; value: number }
+  | { op: "in" | "nin" | "all"; key: string; values: MetadataScalar[] }
+  | { op: "exists"; key: string; value: boolean };
+
+export const METADATA_COVERAGE_GUIDANCE =
+  "Incomplete coverage is not proof of absence or of matching documents. Warnings describe the query scope, not a specific target. Keep requested filters unchanged. If an expected target is known, diagnose it with the same filter; otherwise report the coverage limit without inventing a target or broadening the search.";
+export const METADATA_FILTER_DESCRIPTION = `Typed custom metadata predicate; intersects existing scope. ${METADATA_COVERAGE_GUIDANCE}`;
+
+export const TYPED_METADATA_INGEST_VERSION = 7;
+export const METADATA_LIMITS = {
+  keys: 64,
+  keyLength: 128,
+  stringLength: 4096,
+  members: 128,
+  bytes: 65_536,
+  nodes: 128,
+  depth: 8,
+} as const;
+const reserved = new Set(["__proto__", "prototype", "constructor"]);
+const keySchema = z
+  .string()
+  .min(1)
+  .max(METADATA_LIMITS.keyLength)
+  .refine((key) => !reserved.has(key), "Reserved metadata key");
+const scalarSchema = z.union([
+  z.string().max(METADATA_LIMITS.stringLength),
+  z.number().finite(),
+  z.boolean(),
+]);
+const membersSchema = z
+  .array(scalarSchema)
+  .max(METADATA_LIMITS.members)
+  .refine(
+    (values) => values.every((value) => typeof value === typeof values[0]),
+    "Array members must have one scalar type"
+  );
+export const typedMetadataSchema = z
+  .unknown()
+  .superRefine((value, ctx) => {
+    if (
+      value &&
+      typeof value === "object" &&
+      Object.keys(value).some((key) => reserved.has(key))
+    ) {
+      ctx.addIssue({ code: "custom", message: "Reserved metadata key" });
+    }
+  })
+  .pipe(
+    z
+      .record(keySchema, z.union([scalarSchema, membersSchema]))
+      .refine(
+        (value) => Object.keys(value).length <= METADATA_LIMITS.keys,
+        "Too many metadata keys"
+      )
+      .refine(
+        (value) =>
+          new TextEncoder().encode(JSON.stringify(value)).length <=
+          METADATA_LIMITS.bytes,
+        "Metadata exceeds 64 KiB"
+      )
+  );
+
+const leafSchemas = [
+  z
+    .object({ op: z.enum(["eq", "ne"]), key: keySchema, value: scalarSchema })
+    .strict(),
+  z
+    .object({
+      op: z.enum(["gt", "gte", "lt", "lte"]),
+      key: keySchema,
+      value: z.number().finite(),
+    })
+    .strict(),
+  z
+    .object({
+      op: z.enum(["in", "nin", "all"]),
+      key: keySchema,
+      values: membersSchema.refine(
+        (v) => v.length > 0,
+        "Membership requires values"
+      ),
+    })
+    .strict(),
+  z
+    .object({ op: z.literal("exists"), key: keySchema, value: z.boolean() })
+    .strict(),
+] as const;
+
+/** Finite schema recursion rejects deep/cyclic SDK values before descending.
+ * Each level shares its child schema; MCP can export the real input contract. */
+function predicateAtDepth(depth: number): z.ZodType<MetadataPredicate> {
+  if (depth === METADATA_LIMITS.depth)
+    return z
+      .discriminatedUnion("op", leafSchemas)
+      .meta({ id: "gnoMetadataPredicateDepth8" });
+  const child = predicateAtDepth(depth + 1);
+  return z
+    .discriminatedUnion("op", [
+      ...leafSchemas,
+      z
+        .object({
+          op: z.enum(["and", "or"]),
+          predicates: z.array(child).min(1).max(128),
+        })
+        .strict(),
+      z.object({ op: z.literal("not"), predicate: child }).strict(),
+    ])
+    .meta({ id: `gnoMetadataPredicateDepth${depth}` });
+}
+
+export const metadataPredicateSchema = predicateAtDepth(1).superRefine(
+  (input, ctx) => {
+    const queue: MetadataPredicate[] = [input];
+    let nodes = 0;
+    while (queue.length) {
+      const node = queue.pop();
+      if (!node) break;
+      if (++nodes > METADATA_LIMITS.nodes) {
+        ctx.addIssue({ code: "custom", message: "Filter exceeds 128 nodes" });
+        return;
+      }
+      if ("predicates" in node) queue.push(...node.predicates);
+      if ("predicate" in node) queue.push(node.predicate);
+    }
+    if (
+      new TextEncoder().encode(JSON.stringify(input)).length >
+      METADATA_LIMITS.bytes
+    ) {
+      ctx.addIssue({ code: "custom", message: "Filter exceeds 64 KiB" });
+    }
+  }
+);
+
+export function normalizeMetadataPredicate(input: unknown): MetadataPredicate {
+  const predicate = metadataPredicateSchema.parse(input);
+  const normalize = (node: MetadataPredicate): MetadataPredicate => {
+    if ("predicates" in node) {
+      const unique = new Map(
+        node.predicates.map((child) => {
+          const value = normalize(child);
+          return [JSON.stringify(value), value];
+        })
+      );
+      return {
+        op: node.op,
+        predicates: [...unique.entries()]
+          .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+          .map(([, value]) => value),
+      };
+    }
+    if (node.op === "not")
+      return { op: "not", predicate: normalize(node.predicate) };
+    if ("values" in node)
+      return {
+        op: node.op,
+        key: node.key,
+        values: [...new Set(node.values)].sort((a, b) =>
+          JSON.stringify(a) < JSON.stringify(b)
+            ? -1
+            : JSON.stringify(a) > JSON.stringify(b)
+              ? 1
+              : 0
+        ),
+      };
+    return node;
+  };
+  return normalize(predicate);
+}
+
+export function matchesMetadataPredicate(
+  metadata: TypedMetadata,
+  predicate: MetadataPredicate
+): boolean {
+  if (predicate.op === "and")
+    return predicate.predicates.every((p) =>
+      matchesMetadataPredicate(metadata, p)
+    );
+  if (predicate.op === "or")
+    return predicate.predicates.some((p) =>
+      matchesMetadataPredicate(metadata, p)
+    );
+  if (predicate.op === "not")
+    return !matchesMetadataPredicate(metadata, predicate.predicate);
+  if (!("key" in predicate)) return false;
+  const present = Object.hasOwn(metadata, predicate.key);
+  if (predicate.op === "exists") return present === predicate.value;
+  if (!present) return false;
+  const field = metadata[predicate.key];
+  if ("values" in predicate) {
+    const values = Array.isArray(field) ? field : [field];
+    if (predicate.op === "all")
+      return (
+        Array.isArray(field) && predicate.values.every((v) => field.includes(v))
+      );
+    const match = values.some((v) =>
+      predicate.values.some((wanted) => wanted === v)
+    );
+    return predicate.op === "in" ? match : !match;
+  }
+  if (Array.isArray(field)) return false;
+  if (predicate.op === "eq") return field === predicate.value;
+  if (predicate.op === "ne")
+    return typeof field === typeof predicate.value && field !== predicate.value;
+  if (typeof field !== "number" || typeof predicate.value !== "number")
+    return false;
+  switch (predicate.op) {
+    case "gt":
+      return field > predicate.value;
+    case "gte":
+      return field >= predicate.value;
+    case "lt":
+      return field < predicate.value;
+    case "lte":
+      return field <= predicate.value;
+    default:
+      return false;
+  }
+}

package/src/core/validation.ts

@@ -9,7 +9,14 @@ import { realpath } from "node:fs/promises";
 // node:os for homedir (no Bun os utils)
 import { homedir } from "node:os";
 // node:path for path utils (no Bun path utils)
-import { isAbsolute, join, posix as pathPosix, relative, sep } from "node:path";
+import {
+  isAbsolute,
+  join,
+  parse,
+  posix as pathPosix,
+  relative,
+  sep,
+} from "node:path";
 
 import { toAbsolutePath } from "../config/paths";
 
@@ -87,7 +94,7 @@ export async function validateCollectionRoot(
     DANGEROUS_ROOT_PATTERNS.map((p) => resolveRealPathSafe(p))
   );
 
-  if (dangerousRoots.includes(realPath)) {
+  if (realPath === parse(realPath).root || dangerousRoots.includes(realPath)) {
     throw new Error(`Cannot add ${inputPath}: resolves to dangerous root`);
   }
 

package/src/core/windows-private-path.ts

@@ -0,0 +1,96 @@
+/** Windows owner-only evidence storage. Paths are data, never interpolated script.
+ * Fresh Windows objects may use the token default Owner instead of its User.
+ * Only those exact owner SIDs are accepted; allowed DACL entries remain User-only. */
+// Use framework APIs directly: module auto-discovery depends on profile paths
+// deliberately absent from isolated native workers.
+const ACL = `
+$ErrorActionPreference='Stop'
+$p=$env:GNO_PRIVATE_PATH
+$attributes=[IO.File]::GetAttributes($p)
+$isDirectory=($attributes -band [IO.FileAttributes]::Directory) -ne 0
+if (($attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'Reparse private path' }
+$identity=[Security.Principal.WindowsIdentity]::GetCurrent()
+$sid=$identity.User
+$defaultOwner=$identity.Owner
+$acl=if ($isDirectory) { [IO.Directory]::GetAccessControl($p) } else { [IO.File]::GetAccessControl($p) }
+$owner=$acl.GetOwner([Security.Principal.SecurityIdentifier])
+if ($owner.Value -ne $sid.Value -and $owner.Value -ne $defaultOwner.Value) { throw 'Foreign private owner' }
+if ($env:GNO_PRIVATE_CREATE -eq '1') {
+  if (-not $isDirectory) { throw 'Private directory required' }
+  $acl=[Security.AccessControl.DirectorySecurity]::new()
+  $acl.SetOwner($sid)
+  $acl.SetAccessRuleProtection($true,$false)
+  $rule=[Security.AccessControl.FileSystemAccessRule]::new($sid,'FullControl','ContainerInherit,ObjectInherit','None','Allow')
+  $acl.AddAccessRule($rule)
+  [IO.Directory]::SetAccessControl($p,$acl)
+  if ([IO.Directory]::GetFileSystemEntries($p).Length -ne 0) { throw 'Private directory must be empty' }
+}
+$acl=if ($isDirectory) { [IO.Directory]::GetAccessControl($p) } else { [IO.File]::GetAccessControl($p) }
+$owner=$acl.GetOwner([Security.Principal.SecurityIdentifier])
+if ($owner.Value -ne $sid.Value -and $owner.Value -ne $defaultOwner.Value) { throw 'Foreign private owner' }
+$rules=$acl.GetAccessRules($true,$true,[Security.Principal.SecurityIdentifier])
+$allowed=$false
+foreach ($rule in $rules) {
+  if ($rule.AccessControlType -eq 'Allow') {
+    if ($rule.IdentityReference.Value -ne $sid.Value) { throw 'Private ACL permits another principal' }
+    if (($rule.FileSystemRights -band [Security.AccessControl.FileSystemRights]::FullControl) -eq [Security.AccessControl.FileSystemRights]::FullControl) { $allowed=$true }
+  }
+}
+if (-not $allowed) { throw 'Private owner access unavailable' }
+`;
+
+export async function windowsPrivatePath(
+  path: string,
+  create = false
+): Promise<void> {
+  if (process.platform !== "win32")
+    throw new Error("Windows ACL operation requires Windows");
+  const started = performance.now();
+  const child = Bun.spawn(
+    [
+      "powershell.exe",
+      "-NoLogo",
+      "-NoProfile",
+      "-NonInteractive",
+      "-EncodedCommand",
+      Buffer.from(ACL, "utf16le").toString("base64"),
+    ],
+    {
+      env: {
+        ...process.env,
+        GNO_PRIVATE_PATH: path,
+        GNO_PRIVATE_CREATE: create ? "1" : "0",
+      },
+      stdin: "ignore",
+      // ACL checks return no data; do not allocate an unused stdout pipe.
+      stdout: "ignore",
+      stderr: "pipe",
+      timeout: 10000,
+    }
+  );
+  const reader = child.stderr.getReader();
+  try {
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 65536)
+        throw new Error("Private path ACL stderr exceeded 64 KiB");
+      chunks.push(value);
+    }
+    const exitCode = await child.exited;
+    if (exitCode !== 0) {
+      const stderr = new TextDecoder().decode(Buffer.concat(chunks)).trim();
+      throw new Error(
+        `Private path ACL unavailable (exit=${String(exitCode)}, signal=${String(child.signalCode)}, elapsedMs=${Math.round(performance.now() - started)}): ${stderr || "no stderr"}`
+      );
+    }
+  } finally {
+    reader.releaseLock();
+    if (child.exitCode === null && child.signalCode === null)
+      child.kill("SIGKILL");
+    await child.exited;
+  }
+}

package/src/index.ts

@@ -37,8 +37,8 @@ process.on("SIGINT", () => {
   });
 });
 
-// Run CLI and exit
-runCli(process.argv)
+// Await module completion so pending piped stdin keeps Windows Bun alive.
+await runCli(process.argv)
   .then((code) => cleanupAndExit(interruptExitCode || code))
   .catch((err) => {
     process.stderr.write(

package/src/ingestion/compiled-context.ts

@@ -0,0 +1,15 @@
+/** Generated context is derived evidence and must not feed recursive retrieval. */
+const SIDECAR_MARKER = /"artifactKind"\s*:\s*"gno_compiled_context_sidecar"/;
+export function isCompiledContextPath(path: string): boolean {
+  return path
+    .toLowerCase()
+    .split(/[\\/]/)
+    .some((part) => part.includes(".gno-context."));
+}
+export function isCompiledContextContent(prefix: Uint8Array): boolean {
+  const text = new TextDecoder().decode(prefix).trimStart();
+  return (
+    text.startsWith("<!-- gno:compiled-context ") ||
+    (text.startsWith("{") && SIDECAR_MARKER.test(text))
+  );
+}

package/src/ingestion/record-adapter-canonical.ts

@@ -7,9 +7,11 @@ import type {
   RecordAnchor,
   RecordMetadata,
 } from "../converters/types";
+import type { TypedMetadata } from "../core/typed-metadata";
 
 import { canonicalize, mirrorHash } from "../converters/canonicalize";
 import { RECORD_METADATA_LIMITS } from "../converters/types";
+import { validateRecordMetadata } from "./typed-metadata";
 
 const HASH_PATTERN = /^[a-f\d]{64}$/;
 const CONTROL_PATTERN = new RegExp(
@@ -33,6 +35,8 @@ const RECORD_ATTACHMENT_DISPOSITIONS = new Set<
 >(["inline", "attachment"]);
 
 export interface CanonicalRecord {
+  typedMetadata?: TypedMetadata;
+  metadataError?: string;
   recordKey: string;
   stableId: string;
   sourceLocator: string;
@@ -44,7 +48,7 @@ export interface CanonicalRecord {
   adapterFingerprint: string;
   title?: string;
   languageHint?: string;
-  metadata?: RecordMetadata;
+  metadata?: Omit<RecordMetadata, "custom">;
   anchors?: RecordAnchor[];
 }
 
@@ -187,7 +191,7 @@ const normalizeFailureReference = (
 
 const normalizeMetadata = (
   metadata: RecordMetadata | undefined
-): RecordMetadata | undefined => {
+): Omit<RecordMetadata, "custom"> | undefined => {
   if (!metadata) return undefined;
   const normalizeList = (
     values: string[] | undefined,
@@ -348,6 +352,10 @@ export const canonicalRecord = (
   const sourceLocator = normalizeLocator(record.sourceLocator);
   const markdown = canonicalize(record.markdown);
   const metadata = normalizeMetadata(record.metadata);
+  const custom =
+    record.metadata && Object.hasOwn(record.metadata, "custom")
+      ? validateRecordMetadata(record.metadata.custom, "metadata.custom")
+      : undefined;
   const anchors = normalizeAnchors(record.anchors);
   const title = boundedText(record.title, RECORD_METADATA_LIMITS.maxTitleChars);
   const languageHint = boundedText(
@@ -360,6 +368,7 @@ export const canonicalRecord = (
       languageHint,
       markdown,
       metadata,
+      ...custom,
       sourceLocator,
       stableId,
       title,
@@ -370,6 +379,7 @@ export const canonicalRecord = (
       anchors,
       languageHint,
       metadata,
+      ...custom,
       sourceLocator,
       stableId,
       title,
@@ -395,6 +405,7 @@ export const canonicalRecord = (
     title,
     languageHint,
     metadata,
+    ...custom,
     anchors,
     accountingChars: derivedSource.length,
     metadataChars,

package/src/ingestion/record-container.ts

@@ -1,6 +1,7 @@
 import type { NormalizedContentTypeRule } from "../config";
 import type { Collection } from "../config/types";
 import type { RecordAdapter, RecordMetadata } from "../converters/types";
+import type { TypedMetadata } from "../core/typed-metadata";
 import type {
   ChunkInput,
   DocumentRow,
@@ -36,6 +37,8 @@ interface RecordDocumentMetadata {
   author?: string;
   frontmatterDate?: string;
   dateFields?: Record<string, string>;
+  typedMetadata?: TypedMetadata;
+  metadataError?: string;
 }
 
 interface RecordContainerInput {
@@ -376,6 +379,12 @@ const persistRecord = async (
         author: record.metadata?.author ?? inferred.author,
         frontmatterDate: primaryDate(dateFields) ?? inferred.frontmatterDate,
         dateFields,
+        typedMetadata: record.metadataError
+          ? undefined
+          : (record.typedMetadata ?? inferred.typedMetadata),
+        metadataError:
+          record.metadataError ??
+          (record.typedMetadata ? undefined : inferred.metadataError),
         recordKey: record.recordKey,
         recordSourcePath: input.entry.relPath,
         recordSourceLocator: record.sourceLocator,