@gmickel/gno 2.3.3 → 2.4.0

package/README.md

@@ -20,6 +20,10 @@ gno agents install --target claude # teach retrieval and writing discipline
 gno agents verify --target claude
 ```
 
+Custom fields such as project, approval status, and numeric confidence can
+constrain retrieval with [typed metadata filters](docs/TYPED-METADATA.md),
+across CLI, MCP, SDK, REST, and the Web UI.
+
 ## What you get
 
 **One local index across everything you have.** Markdown, PDFs, Office documents, plain text, source code, and portable mail, calendar and transcript exports. Point it at a folder that mixes all of them and it handles the mix.
@@ -126,7 +130,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current source version: **v2.3.3**. See [CHANGELOG.md](./CHANGELOG.md).
+> Current source version: **v2.4.0**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 
@@ -1186,7 +1190,7 @@ bun test
 bun run lint && bun run typecheck
 ```
 
-> **Contributing**: [CONTRIBUTING.md](.github/CONTRIBUTING.md)
+> **Contributing**: See [checks and release policy](.github/CONTRIBUTING.md). Documentation-only and CI-only changes do not require a product version bump or release.
 
 ### Evals and Benchmark Deltas
 
@@ -1203,6 +1207,13 @@ bun run eval:hybrid:delta
 - Benchmark guide: [evals/README.md](./evals/README.md)
 - Latest baseline snapshot: [evals/fixtures/hybrid-baseline/latest.json](./evals/fixtures/hybrid-baseline/latest.json)
 
+Document-level benchmark hits do not prove that every answer-bearing passage
+survives retrieval and a context budget. The opt-in
+[adversarial evidence gate](./evals/README.md#adversarial-evidence-coverage-development-only)
+checks complete required source spans, multi-source coverage, and fixed-reader
+abstention with replay and explicit cached-model native runs. It preserves baseline
+misses and does not change ranking defaults.
+
 ### Code Embedding Benchmark Harness
 
 GNO also has a dedicated harness for comparing alternate embedding models on code retrieval without touching product defaults:

package/assets/skill/SKILL.md

@@ -647,3 +647,33 @@ MCP-equivalent write tool:
 | Complete CLI reference (all commands, options, flags) | [cli-reference.md](cli-reference.md) |
 | MCP server setup and tools                            | [mcp-reference.md](mcp-reference.md) |
 | Usage examples and patterns                           | [examples.md](examples.md)           |
+
+## Custom metadata filters
+
+Use fixed flags for existing collection/tag/date/author/category fields. Custom
+fields must be indexed from nested YAML `gno.metadata`; arbitrary frontmatter
+keys are not automatically custom fields. CLI retrieval accepts `--filter`
+JSON; MCP/SDK/REST accept the same `filter` object:
+
+```json
+{
+  "op": "and",
+  "predicates": [
+    { "op": "eq", "key": "project", "value": "atlas" },
+    { "op": "gte", "key": "confidence", "value": 0.8 }
+  ]
+}
+```
+
+Membership operators `in`, `nin`, and `all` use plural `values`, not `value`:
+`{"op":"all","key":"reviewers","values":["ana","sam"]}`.
+Other leaves use singular `value`. `not` uses `predicate`; `and/or` use `predicates`.
+
+Strings are case-sensitive and never coerced to numbers or booleans. `eq/ne`
+accept scalars, ordering accepts numbers, `in/nin` test scalar/array membership,
+`all` requires an array, and `exists` takes a boolean. `ne/nin` require presence;
+`not(eq)`/`not(in)` can include missing fields. Invalid metadata is excluded even
+under negation. Never silently remove a requested filter. If coverage is
+incomplete, inspect warnings and diagnose the expected target with the same
+filter before relaxing it; correct source metadata and run `gno update` when
+repair is authorized. Preserve collection, authority, and memory scope.

package/assets/skill/cli-reference.md

@@ -1062,3 +1062,15 @@ gno completion output <bash|zsh|fish>
 | 1    | Validation error (bad args)                                          |
 | 2    | Runtime error (IO, DB, model)                                        |
 | 3    | `NOT_RUNNING` — `--status` / `--stop` found no live matching process |
+
+## Custom metadata filters
+
+```bash
+gno search "rollout" --filter '{"op":"eq","key":"status","value":"approved"}'
+gno query diagnose "rollout" --target gno://docs/decision.md --filter '{"op":"gte","key":"confidence","value":0.8}'
+```
+
+The same `--filter` JSON works on `vsearch`, `query`, `ask`, and `context build`.
+Use only indexed `gno.metadata` fields. See SKILL.md for strict types,
+missing-field semantics, and diagnose-before-relaxing guidance. Repair metadata
+with `gno update` when authorized; no predicate expands existing scope.

package/assets/skill/examples.md

@@ -467,3 +467,18 @@ Press **N** in `gno serve`, write the note, and open **Source** only when you
 need provenance fields such as URL, author, observed date, or external id. The
 success view reports the write result, FTS sync state, and embed state
 separately.
+
+## Custom metadata filters
+
+Find Atlas decisions reviewed by both Ana and Sam:
+
+```bash
+gno query "rollout decision" --filter '{"op":"and","predicates":[{"op":"eq","key":"project","value":"atlas"},{"op":"all","key":"reviewers","values":["ana","sam"]}]}'
+```
+
+This requires indexed nested `gno.metadata` with `project: atlas` and a
+`reviewers` string array. To include documents without a status, use
+`{"op":"not","predicate":{"op":"eq","key":"status","value":"archived"}}`.
+To require a present non-archived string status, use
+`{"op":"ne","key":"status","value":"archived"}`. Invalid metadata matches
+neither; check coverage and diagnose before relaxing the query.

package/assets/skill/mcp-reference.md

@@ -201,3 +201,19 @@ transport session, never from tool arguments.
 gno mcp uninstall
 gno mcp uninstall -t claude-code
 ```
+
+## Custom metadata filters
+
+`gno_search`, `gno_vsearch`, `gno_query`, `gno_ask`, and `gno_context` accept
+`filter` alongside their existing scope fields:
+
+```json
+{
+  "query": "rollout",
+  "filter": { "op": "gte", "key": "confidence", "value": 0.8 }
+}
+```
+
+Pass the object, not a JSON-encoded string. Preserve the filter on retries;
+inspect coverage warnings rather than silently broadening retrieval. See
+SKILL.md for strict types and missing-field semantics.

package/browser-extension/artifacts/gno-browser-clipper-v2.4.0.zip.sha256

@@ -0,0 +1 @@
+ae739d8da342a7f932f8097e1d4d852ff7c46b722b8e979303b1213eaf2d76a5  gno-browser-clipper-v2.4.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "2.3.3"
+  "version": "2.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "2.3.3",
+  "version": "2.4.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -4171,3 +4171,33 @@ because reindexing is temporarily unavailable
 - [MCP Specification](./mcp.md)
 - [Output Schemas](./output-schemas/)
 - [PRD](../docs/prd.md)
+
+### Typed metadata predicates
+
+Retrieval commands accept `--filter '<JSON>'`. The same `filter` object is
+accepted by SDK, MCP and REST retrieval inputs. Metadata comes from the nested
+YAML `gno.metadata` map; ordinary frontmatter keys remain unchanged.
+
+The bounded recursive contract is:
+
+- `{op:"and"|"or", predicates: Predicate[]}` (nonempty).
+- `{op:"not", predicate: Predicate}`.
+- `{op:"eq"|"ne", key:string, value:string|number|boolean}`.
+- `{op:"gt"|"gte"|"lt"|"lte", key:string, value:number}`.
+- `{op:"in"|"nin"|"all", key:string, values:Scalar[]}` (nonempty, homogeneous).
+- `{op:"exists", key:string, value:boolean}`.
+
+Comparison is type-strict and text is exact/case-sensitive. Positive comparisons,
+`ne` and `nin` require a present field. Logical `not` negates the complete child,
+so missing fields satisfy `not(eq(...))`. `eq/ne` require scalar fields; `in/nin`
+accept scalar or array fields; `all` requires an array. Invalid metadata and
+documents awaiting ingestion repair are ineligible for every typed predicate,
+including negation. Filtered queries report incomplete coverage until repaired.
+Limits: 64 metadata keys, 128-character keys, 4096-character strings, 128 array
+members, 64 KiB serialized metadata/filter, 128 predicate nodes, depth 8.
+Keys `__proto__`, `prototype`, and `constructor` are reserved.
+
+For executable examples and the missing-field truth table, see
+[Typed metadata filters](../docs/TYPED-METADATA.md). `ne` additionally requires
+the field's scalar type to match the operand; `nin` matches a present scalar or
+array with no exact typed member match. Ordering never coerces strings.

package/spec/db/schema.sql

@@ -121,6 +121,8 @@ CREATE TABLE IF NOT EXISTS contexts (
 -- ─────────────────────────────────────────────────────────────────────────────
 
 CREATE TABLE IF NOT EXISTS documents (
+  typed_metadata TEXT, -- validated gno.metadata, NULL until extraction
+  metadata_error TEXT, -- bounded path-only extraction diagnostic
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   collection TEXT NOT NULL,
   rel_path TEXT NOT NULL,

package/spec/evals.md

@@ -1110,3 +1110,51 @@ ordering, and rerank interaction without LLM or fixture drift.
    - CONTRIBUTING.md updated with DoD eval requirements
    - This spec (spec/evals.md) matches implementation
 ````
+
+## Adversarial evidence gate (development only)
+
+`bun evals/acceptance/evidence-cli.ts --input <observations.json> --output <report.json>`
+validates and scores a frozen `gno-evidence-run-v1` observation bundle. Native
+collection is explicit (`--native --output <new-directory>`), uses only cached
+models and isolated synthetic indexes, and compares current defaults with
+`noExpand: true`. This is not a public GNO command or a default CI eval.
+
+The fixture contract `gno-evidence-fixtures-v1` contains documents (URI, title,
+exact content and SHA-256), verified required spans (stable ID, source hash,
+1-based inclusive line range and span hash), and cases. Cases pin query/intent,
+collection, family, usable token budget, independent UTF-8 byte cap, acceptable
+alternative sets of required span IDs, answerability, expected literal answer
+values, and a must-cover flag. Empty answerable evidence sets, invalid ranges,
+duplicate IDs, stale hashes, unknown span references and answer-bearing names
+in synthetic paths are rejected. Fixture bytes are pinned separately; baseline
+pins are never regenerated to hide a failure.
+
+Every observation names a case, arm (`current` or `noExpand`), fixture digest,
+runtime/model/settings identity, native coverage and invalid-run reasons. Its
+stages (`retrieval`, `fusion`, `rerank_input`, `delivery`) contain observed
+passages with URI, source hash, UTF-16 source offsets, exact text and an input
+identity. Stages not captured are null, not empty successful stages. Clipping
+metadata retains the original selected extent when known. Passage validity is
+checked against the pinned source. A required span survives only when verified
+passages in one actual input together cover every character; separate reranker
+inputs cannot pool coverage. Partial, clipped, split-across-inputs, missing and
+unknown outcomes remain distinct. Duplicate appearances cannot add coverage.
+
+The `gno-evidence-report-v1` output retains per-span/stage outcomes, all-required
+and any-required evidence coverage, first observed loss stage, fixed-reader
+answer/abstention outcome, UTF-8 bytes, declared-estimator token cost, exact native
+tokenization observations when available, elapsed time and resource samples.
+Actual tokenizer observations are not mislabeled as total inference billing;
+missing observations remain null. Reader outcomes use delivered verified spans,
+expected fixture values and the actual answer verification result, not document
+hits or reconstructed snippets. Retrieval-only runs have a null reader outcome.
+
+Comparison requires exactly one observation per case/arm, matching fixture,
+model/runtime identity and budgets; only the declared noExpand setting differs.
+Native fallback or missing required model execution invalidates a native pair.
+Replay success never certifies native execution. Both arms and baseline misses
+are retained. Candidate adoption requires all deterministic guard cases and
+must-cover cases, no reduction in held-out complete evidence or fixed-reader
+success, and valid comparisons. A baseline miss is a finding; this gate does not
+change ranking defaults to make itself green. The exact strict JSON schemas
+ship beside the other evaluation output schemas.

package/spec/mcp.md

@@ -3054,3 +3054,15 @@ Schemas: `collection-egress-policy.schema.json`,
 - [CLI Specification](./cli.md)
 - [Output Schemas](./output-schemas/)
 - [MCP Protocol Specification](https://modelcontextprotocol.io/specification/)
+
+### Typed metadata retrieval filter
+
+Applicable retrieval tools accept the same bounded `filter` predicate documented
+in `spec/cli.md`. Invalid filters fail validation with a field path. Predicates
+intersect caller scope before candidate limits and never expand authority.
+
+`gno_search`, `gno_vsearch`, `gno_query`, `gno_ask`, and `gno_context` expose
+`filter`. The strict discriminated contract is recorded in
+[metadata-predicate.schema.json](output-schemas/metadata-predicate.schema.json).
+See [Typed metadata filters](../docs/TYPED-METADATA.md) for exact membership,
+missing-field, invalid-document, and bounded-input semantics.

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

@@ -28,6 +28,18 @@
             "type": "object",
             "required": ["verificationRequested", "abstained"],
             "properties": {
+              "warnings": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["code", "message"],
+                  "properties": {
+                    "code": { "type": "string" },
+                    "message": { "type": "string" }
+                  }
+                }
+              },
               "verificationRequested": { "const": true },
               "abstained": {}
             }