data-refinery-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{data_refinery_cli-0.4.0 → data_refinery_cli-0.5.0}/AGENTS.colleague.md

@@ -15,10 +15,14 @@ behavior, update both.
 
 data-refinery-cli owns the **storage + data-quality infrastructure layer** split
 out of eidetic-cli (issue #1): the mongo + neo4j substrate, the docker stack
-(published to GHCR), and a **consumer-agnostic** data-quality surface (validate,
-dedup, integrity, freshness). It treats stored data as **opaque documents** and
-never interprets them as "memories" — that semantics stays in eidetic, the first
-consumer over a subprocess-not-import boundary.
+(published to GHCR), a storage-neutral **store** (`store put/get/list` over a
+files/mongo/neo4j `Backend`, also importable as `data_refinery.store`), and a
+**consumer-agnostic** data-quality surface (`validate`, `dedup`, `integrity`,
+`freshness`). It treats stored data as **opaque envelopes**
+(`{id, hash, content, scope, metadata}`) and never interprets them as "memories"
+— that semantics stays in eidetic, the first consumer over a
+subprocess-not-import boundary. Waves 1 (stack) and 2 (store + quality) are
+built; Wave 3 (the pinned verb contract + eidetic consumption) is open.
 
 ## Names (keep them straight)
 
@@ -35,10 +39,11 @@ consumer over a subprocess-not-import boundary.
   (`0` ok, `1` user error, `2` environment error, `3+` reserved).
 - **`--json` on every command**; results to stdout, errors/diagnostics to
   stderr, never mixed.
-- **Runtime deps stay empty by default.** `dependencies = []`. Heavy store
-  drivers (`neo4j`, `pymongo`, Wave 2) go behind an optional extra and are
-  lazy-imported inside function bodies, exiting `CliError(code=2)` with an
-  install `hint:` when absent.
+- **Runtime deps stay empty by default.** `dependencies = []`. The `files`
+  backend is stdlib-only; the heavy store drivers (`neo4j`, `pymongo`) live
+  behind the optional `[store]` extra and are lazy-imported inside function
+  bodies, exiting `CliError(code=2)` with an install `hint:` when absent (a
+  static test asserts no top-level driver import).
 - **Idempotent dedup** (by `id`/`hash`) and the **public/private scope no-leak**
   (a private-scope document is never returned by a public-scope fetch) are
   load-bearing across the consumer boundary.

{data_refinery_cli-0.4.0 → data_refinery_cli-0.5.0}/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-06-20
+
+### Added
+
+- Generic storage-neutral envelope {id,hash,content,scope{name,visibility},metadata} with no memory semantics (data_refinery/store/envelope.py)
+- Importable store library data_refinery.store.put/get/list, mirrored by the data-refinery store put/get/list CLI noun over one shared implementation
+- Backend Protocol with files (dependency-free default), mongo, and neo4j adapters; neo4j/pymongo live behind the optional [store] extra and are lazy-imported (dependencies = [] stays the default)
+- Data-quality verbs validate, dedup (idempotent by id/hash), integrity (hash matches content), and freshness (age/staleness facts) — all --json
+- Public/private scope no-leak (can_serve) enforced by every backend get/list; a private-scope document is never returned by a public-scope fetch
+
+### Changed
+
+- docs/contract.md bumped to contract version 2 documenting the store + data-quality verb JSON shapes and the [store] extra
+- README, CLAUDE.md, AGENTS.colleague.md, learn, overview, and the explain catalog updated for the Wave 2 surface
+
+### Fixed
+
+- mongo/neo4j store put now dedups by content hash within the scope on insert, matching the files backend and the documented "dedups by hash on insert" contract (Qodo PR #5 review)
+- neo4j adapter guards metadata JSON parsing: a corrupt node surfaces as a structured exit-2 error with a remediation instead of an uncaught JSONDecodeError wrapped as a generic "unexpected" (Qodo PR #5 review)
+- SonarCloud new-code cleanups (PR #5), behaviour-preserving: single-exit store get/list handlers (S3516), repeated literals extracted into `_add_json_flag` helpers / a `_JSONL_GLOB` constant (S1192), and `validate_payload` cognitive complexity reduced via a `_scope_errors` helper (S3776)
+
+### Security
+
+- Scope visibility is validated at ingestion (store put / from_dict reject any value other than public|private with exit 1) and the can_serve no-leak check fails closed — an unrecognised visibility is treated as private, never served across scopes (Qodo PR #5 review)
+
 ## [0.4.0] - 2026-06-20
 
 ### Added

{data_refinery_cli-0.4.0 → data_refinery_cli-0.5.0}/CLAUDE.md

@@ -10,19 +10,25 @@ and freshness of data as it is stored and fetched. It is being split out of
 **eidetic-cli** so eidetic keeps the agent-memory layer; it is a sibling to
 **daria** (the Data Refinery Intelligent Agent).
 
-**Current state — read this first.** **Wave 1 of issue #1 is built**: the
-storage substrate (`docker-compose.yml` — mongo 27018 + neo4j 7687/apoc) and the
-`data-refinery stack up/down/status` verb that wraps `docker compose`, plus the
-GHCR publish workflow (`.github/workflows/publish-stack.yml`) and the pinnable
-docs (`docs/stack-image.md`, `docs/contract.md`). Runtime `dependencies = []`
-still holds — `stack` shells out to docker via stdlib `subprocess`, no driver
-deps. The **store adapters + data-quality verbs are Wave 2** (still unbuilt;
-tracked as a follow-up issue): the generic envelope, files/cypher/mongo
-adapters behind an optional `[store]` extra, and validate/dedup/integrity/
-freshness. The rest of the code is the inherited *agent-first introspection
-scaffold* (`whoami` / `learn` / `explain` / `overview` / `doctor` + a `cli`
-noun), cited from [teken](https://github.com/agentculture/teken)'s `python-cli`
-reference. The build order lives in **issue #1** (see "Domain roadmap").
+**Current state — read this first.** **Waves 1 and 2 of issue #1 are built.**
+*Wave 1* (issue #1): the storage substrate (`docker-compose.yml` — mongo 27018 +
+neo4j 7687/apoc) and the `data-refinery stack up/down/status` verb wrapping
+`docker compose`, plus the GHCR publish workflow
+(`.github/workflows/publish-stack.yml`) and the pinnable docs
+(`docs/stack-image.md`, `docs/contract.md`). *Wave 2* (issue #3): the
+storage-neutral **store** — the generic envelope (`data_refinery/store/`), the
+importable `data_refinery.store.put/get/list` library mirrored by `data-refinery
+store put/get/list`, and the files/mongo/neo4j adapters behind a `Backend`
+Protocol; plus the **data-quality verbs** (`validate` / `dedup` / `integrity` /
+`freshness` in `data_refinery/quality/`). Runtime `dependencies = []` still holds
+— the `files` backend is stdlib-only (default) and `neo4j`/`pymongo` are
+lazy-imported behind the optional `[store]` extra. The remaining code is the
+inherited *agent-first introspection scaffold* (`whoami` / `learn` / `explain` /
+`overview` / `doctor` + a `cli` noun), cited from
+[teken](https://github.com/agentculture/teken)'s `python-cli` reference. **Wave
+3** (the full pinnable verb-JSON contract + eidetic consuming the surface over
+the subprocess boundary) is still open; the build order lives in **issue #1** /
+**issue #3** (see "Domain roadmap").
 
 ## Names: there are three, and they differ on purpose
 
@@ -235,18 +241,24 @@ repo's call (it owns the surface) but must be documented so eidetic can pin.
 
 ## Remaining gaps / next steps
 
-Wave 1 of issue #1 is built (the stack: compose + `stack` verb + GHCR publish +
-contract docs). README, `AGENTS.colleague.md`, and `overview` were realigned to
-the data-quality domain during that work. What is still open:
-
-1. **Wave 2 — the store + data-quality surface** (tracked as a follow-up issue):
-   the generic opaque envelope `{id,hash,content,scope,metadata}`, the
-   files/cypher/mongo store adapters behind an optional `[store]` extra
-   (lazy-imported, `dependencies = []` stays the default), and the
-   validate/dedup/integrity/freshness verbs. Idempotent dedup + the public/private
-   scope no-leak are the load-bearing invariants. This is the substantive work.
-2. **Wave 3 — the full pinnable verb contract + eidetic consumption** over the
-   subprocess boundary (eidetic drops/thins `neo4j`+`pymongo`).
+Waves 1 and 2 of the split are built. *Wave 1* = the stack (compose + `stack`
+verb + GHCR publish + contract docs). *Wave 2* (issue #3) = the store +
+data-quality surface: the generic opaque envelope `{id,hash,content,scope,
+metadata}` (`data_refinery/store/envelope.py`), the `Backend` Protocol +
+files/mongo/neo4j adapters (`data_refinery/store/backends/`, the driver-backed
+two behind the optional `[store]` extra, lazy-imported, `dependencies = []` stays
+the default), the importable `data_refinery.store.put/get/list` mirrored by the
+`store` CLI noun, and the `validate`/`dedup`/`integrity`/`freshness` verbs
+(`data_refinery/quality/`). Idempotent dedup + the public/private scope no-leak
+(`can_serve`, enforced by every backend's `get`/`list`) are the load-bearing
+invariants. README, `AGENTS.colleague.md`, `learn`, `overview`, the explain
+catalog, and `docs/contract.md` (now contract version 2) were updated for the
+surface. What is still open:
+
+1. **Wave 3 — the full pinnable verb contract + eidetic consumption** over the
+   subprocess boundary (eidetic drops/thins `neo4j`+`pymongo`). The verb-JSON
+   shapes are documented in `docs/contract.md`; Wave 3 freezes them as the pinned
+   surface eidetic consumes process-to-process.
 
 ## Renaming / scaffold lineage
 

{data_refinery_cli-0.4.0 → data_refinery_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-refinery-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Agent and CLI for data quality in storage and retrieval — validating, deduplicating, and checking the integrity and freshness of data as it is stored and fetched. Split out of eidetic-cli so eidetic keeps agent-memory; sibling to daria, the Data Refinery Intelligent Agent.
 Project-URL: Homepage, https://github.com/agentculture/data-refinery-cli
 Project-URL: Issues, https://github.com/agentculture/data-refinery-cli/issues
@@ -13,6 +13,9 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
+Provides-Extra: store
+Requires-Dist: neo4j>=5; extra == 'store'
+Requires-Dist: pymongo>=4; extra == 'store'
 Description-Content-Type: text/markdown
 
 # data-refinery-cli
@@ -40,12 +43,12 @@ The split ships in waves:
 | Wave | Scope | Status |
 |------|-------|--------|
 | **1** | docker stack (mongo 27018 + neo4j 7687), GHCR publish, `stack` CLI verb, pinnable contract | **shipped** |
-| **2** | generic storage envelope, files/cypher/mongo store adapters (optional `[store]` extra), data-quality verbs (validate, dedup, integrity, freshness) | planned |
+| **2** | generic storage envelope + importable store API, files/mongo/neo4j adapters (optional `[store]` extra), data-quality verbs (validate, dedup, integrity, freshness) | **shipped** |
 | **3** | full pinnable verb contract + eidetic consumption over the process boundary | planned |
 
 The runtime package has **no third-party dependencies** by default; the heavy
-store drivers (`neo4j`, `pymongo`) arrive in Wave 2 behind an optional extra,
-lazy-imported.
+store drivers (`neo4j`, `pymongo`) live behind the optional `[store]` extra and
+are lazy-imported, so the `files` backend (the default) stays dependency-free.
 
 ## Quickstart
 
@@ -57,6 +60,23 @@ uv run data-refinery stack status --json
 uv run data-refinery stack down
 uv run data-refinery whoami            # identity from culture.yaml
 uv run teken cli doctor . --strict     # the agent-first rubric gate CI runs
+
+# Store + quality (files backend is dependency-free; no docker needed):
+echo '{"id":"a","content":"hello"}' | uv run data-refinery store put --json
+uv run data-refinery store get a --json
+uv run data-refinery store list --json
+uv run data-refinery integrity --json          # hash matches content?
+uv run data-refinery dedup --json              # collapse same-hash dups (idempotent)
+echo '{"id":"a","content":"x"}' | uv run data-refinery validate --json
+```
+
+The store is also importable — shell out **or** `import data_refinery.store`:
+
+```python
+import data_refinery.store as store
+store.put(store.Envelope(id="a", content="hello"))
+store.get("a")        # -> Envelope | None
+store.list()          # -> list[Envelope]
 ```
 
 ## CLI
@@ -64,6 +84,11 @@ uv run teken cli doctor . --strict     # the agent-first rubric gate CI runs
 | Verb | What it does |
 |------|--------------|
 | `stack up\|down\|status` | Manage the storage substrate (mongo + neo4j) via docker compose. |
+| `store put\|get\|list` | Put/get/list opaque envelopes (`--backend files\|mongo\|neo4j`). |
+| `validate` | Check envelope shape for JSON piped on stdin. |
+| `dedup` | Collapse same-hash-same-scope duplicates in the store (idempotent). |
+| `integrity` | Check every stored hash matches `sha256(content)`. |
+| `freshness` | Report age/staleness facts from a metadata timestamp field. |
 | `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
 | `learn` | Print a structured self-teaching prompt. |
 | `explain <path>` | Markdown docs for any noun/verb path. |
@@ -71,6 +96,11 @@ uv run teken cli doctor . --strict     # the agent-first rubric gate CI runs
 | `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
 | `cli overview` | Describe the CLI surface itself. |
 
+The **envelope** is storage-neutral — `{id, hash, content, scope{name,
+visibility}, metadata}` with no memory semantics — and the store enforces a
+public/private **scope no-leak**: a private-scope document is never returned by a
+public-scope fetch, across every backend.
+
 Every command supports `--json`. Results go to stdout, errors/diagnostics to
 stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
 error (e.g. docker absent — always with a `hint:`, never a traceback), `3+`

{data_refinery_cli-0.4.0 → data_refinery_cli-0.5.0}/README.md

@@ -23,12 +23,12 @@ The split ships in waves:
 | Wave | Scope | Status |
 |------|-------|--------|
 | **1** | docker stack (mongo 27018 + neo4j 7687), GHCR publish, `stack` CLI verb, pinnable contract | **shipped** |
-| **2** | generic storage envelope, files/cypher/mongo store adapters (optional `[store]` extra), data-quality verbs (validate, dedup, integrity, freshness) | planned |
+| **2** | generic storage envelope + importable store API, files/mongo/neo4j adapters (optional `[store]` extra), data-quality verbs (validate, dedup, integrity, freshness) | **shipped** |
 | **3** | full pinnable verb contract + eidetic consumption over the process boundary | planned |
 
 The runtime package has **no third-party dependencies** by default; the heavy
-store drivers (`neo4j`, `pymongo`) arrive in Wave 2 behind an optional extra,
-lazy-imported.
+store drivers (`neo4j`, `pymongo`) live behind the optional `[store]` extra and
+are lazy-imported, so the `files` backend (the default) stays dependency-free.
 
 ## Quickstart
 
@@ -40,6 +40,23 @@ uv run data-refinery stack status --json
 uv run data-refinery stack down
 uv run data-refinery whoami            # identity from culture.yaml
 uv run teken cli doctor . --strict     # the agent-first rubric gate CI runs
+
+# Store + quality (files backend is dependency-free; no docker needed):
+echo '{"id":"a","content":"hello"}' | uv run data-refinery store put --json
+uv run data-refinery store get a --json
+uv run data-refinery store list --json
+uv run data-refinery integrity --json          # hash matches content?
+uv run data-refinery dedup --json              # collapse same-hash dups (idempotent)
+echo '{"id":"a","content":"x"}' | uv run data-refinery validate --json
+```
+
+The store is also importable — shell out **or** `import data_refinery.store`:
+
+```python
+import data_refinery.store as store
+store.put(store.Envelope(id="a", content="hello"))
+store.get("a")        # -> Envelope | None
+store.list()          # -> list[Envelope]
 ```
 
 ## CLI
@@ -47,6 +64,11 @@ uv run teken cli doctor . --strict     # the agent-first rubric gate CI runs
 | Verb | What it does |
 |------|--------------|
 | `stack up\|down\|status` | Manage the storage substrate (mongo + neo4j) via docker compose. |
+| `store put\|get\|list` | Put/get/list opaque envelopes (`--backend files\|mongo\|neo4j`). |
+| `validate` | Check envelope shape for JSON piped on stdin. |
+| `dedup` | Collapse same-hash-same-scope duplicates in the store (idempotent). |
+| `integrity` | Check every stored hash matches `sha256(content)`. |
+| `freshness` | Report age/staleness facts from a metadata timestamp field. |
 | `whoami` | Report this agent's nick, version, backend, and model from `culture.yaml`. |
 | `learn` | Print a structured self-teaching prompt. |
 | `explain <path>` | Markdown docs for any noun/verb path. |
@@ -54,6 +76,11 @@ uv run teken cli doctor . --strict     # the agent-first rubric gate CI runs
 | `doctor` | Check the agent-identity invariants (prompt-file-present, backend-consistency). |
 | `cli overview` | Describe the CLI surface itself. |
 
+The **envelope** is storage-neutral — `{id, hash, content, scope{name,
+visibility}, metadata}` with no memory semantics — and the store enforces a
+public/private **scope no-leak**: a private-scope document is never returned by a
+public-scope fetch, across every backend.
+
 Every command supports `--json`. Results go to stdout, errors/diagnostics to
 stderr (never mixed). Exit codes: `0` success, `1` user error, `2` environment
 error (e.g. docker absent — always with a `hint:`, never a traceback), `3+`

{data_refinery_cli-0.4.0 → data_refinery_cli-0.5.0}/data_refinery/cli/__init__.py

@@ -67,7 +67,9 @@ def _build_parser() -> argparse.ArgumentParser:
     from data_refinery.cli._commands import explain as _explain_cmd
     from data_refinery.cli._commands import learn as _learn_cmd
     from data_refinery.cli._commands import overview as _overview_cmd
+    from data_refinery.cli._commands import quality as _quality_cmd
     from data_refinery.cli._commands import stack as _stack_group
+    from data_refinery.cli._commands import store as _store_group
     from data_refinery.cli._commands import whoami as _whoami_cmd
 
     parser = _CliArgumentParser(
@@ -90,6 +92,8 @@ def _build_parser() -> argparse.ArgumentParser:
     _doctor_cmd.register(sub)
     _cli_group.register(sub)
     _stack_group.register(sub)
+    _store_group.register(sub)
+    _quality_cmd.register(sub)
     # Register your own noun groups here:
     #   from data_refinery.cli._commands import my_noun as _my_noun_group
     #   _my_noun_group.register(sub)

{data_refinery_cli-0.4.0 → data_refinery_cli-0.5.0}/data_refinery/cli/_commands/learn.py

@@ -18,9 +18,9 @@ Purpose
 -------
 Validate, deduplicate, and check the integrity and freshness of data as it is
 stored and fetched. Split out of eidetic-cli so eidetic keeps agent-memory;
-sibling to daria. The data-quality verbs are not built yet (see issue #1) —
-today this exposes the agent-first introspection surface below on a
-self-contained runtime (no third-party dependencies).
+sibling to daria. The store moves OPAQUE envelopes — no memory semantics. The
+default runtime has no third-party dependencies; the mongo/neo4j store backends
+live behind the optional [store] extra (lazy-imported).
 
 Commands
 --------
@@ -30,6 +30,12 @@ Commands
   data-refinery overview           Descriptive snapshot of the agent.
   data-refinery doctor             Check the agent-identity invariants.
   data-refinery cli overview       Describe the CLI surface itself.
+  data-refinery stack up|down|status   Manage the storage substrate.
+  data-refinery store put|get|list     Put/get/list opaque envelopes.
+  data-refinery validate           Check envelope shape (JSON on stdin).
+  data-refinery dedup              Collapse same-hash duplicates (idempotent).
+  data-refinery integrity          Check stored hash matches sha256(content).
+  data-refinery freshness          Report age/staleness facts from metadata.
 
 Machine-readable output
 -----------------------
@@ -61,6 +67,12 @@ def _as_json_payload() -> dict[str, object]:
             {"path": ["overview"], "summary": "Descriptive snapshot of the agent."},
             {"path": ["doctor"], "summary": "Check the agent-identity invariants."},
             {"path": ["cli", "overview"], "summary": "Describe the CLI surface."},
+            {"path": ["stack"], "summary": "Manage the storage substrate (up/down/status)."},
+            {"path": ["store"], "summary": "Put/get/list opaque envelopes in the store."},
+            {"path": ["validate"], "summary": "Check envelope shape (JSON on stdin)."},
+            {"path": ["dedup"], "summary": "Collapse same-hash duplicates (idempotent)."},
+            {"path": ["integrity"], "summary": "Check stored hash matches sha256(content)."},
+            {"path": ["freshness"], "summary": "Report age/staleness facts from metadata."},
         ],
         "exit_codes": {
             "0": "success",

{data_refinery_cli-0.4.0 → data_refinery_cli-0.5.0}/data_refinery/cli/_commands/overview.py

@@ -31,6 +31,8 @@ _VERBS = [
     "overview — this descriptive snapshot",
     "doctor — check the agent-identity invariants",
     "stack up|down|status — manage the storage substrate (mongo + neo4j)",
+    "store put|get|list — put/get/list opaque envelopes in the store",
+    "validate|dedup|integrity|freshness — data-quality checks over the store",
 ]
 
 

data_refinery_cli-0.5.0/data_refinery/cli/_commands/quality.py

@@ -0,0 +1,185 @@
+"""``data-refinery validate|dedup|integrity|freshness`` — data-quality verbs.
+
+Consumer-agnostic checks over the store, mirroring :mod:`data_refinery.quality`.
+All are global verbs (not a noun group) and all support ``--json``.
+
+Exit policy (consistent with ``stack status``): the command exits ``0`` when the
+check *ran* — findings ride in the payload (``valid: false`` / ``ok: false`` /
+duplicate groups / stale counts). A non-zero exit means the command could not
+run: ``1`` for unparseable input, ``2`` for a missing backend driver. No
+traceback ever.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+
+from data_refinery.cli._errors import EXIT_USER_ERROR, CliError
+from data_refinery.cli._output import emit_result
+from data_refinery.quality import checks
+from data_refinery.store import get_backend
+
+_BACKENDS = ("files", "mongo", "neo4j")
+
+
+def _add_backend_flag(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--backend",
+        choices=_BACKENDS,
+        default="files",
+        help="Store backend (default: files; mongo/neo4j need the [store] extra).",
+    )
+
+
+def _add_json_flag(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+
+
+def _read_stdin_json() -> object:
+    if sys.stdin is None or sys.stdin.isatty():
+        raise CliError(
+            code=EXIT_USER_ERROR,
+            message="validate expects a JSON envelope (or array) on stdin",
+            remediation='pipe input, e.g. echo \'{"id":"a","content":"x"}\' | '
+            "data-refinery validate",
+        )
+    raw = sys.stdin.read().strip()
+    if not raw:
+        raise CliError(
+            code=EXIT_USER_ERROR,
+            message="no input on stdin",
+            remediation='pipe a JSON envelope or array, e.g. {"id":"a","content":"x"}',
+        )
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise CliError(
+            code=EXIT_USER_ERROR,
+            message=f"invalid JSON on stdin: {exc}",
+            remediation="pipe a single envelope object or a JSON array of them",
+        ) from exc
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    payload = _read_stdin_json()
+    objs = payload if isinstance(payload, list) else [payload]
+    result = checks.validate_many(objs)
+    if json_mode:
+        emit_result(result, json_mode=True)
+    else:
+        valid_n = sum(1 for r in result["results"] if r["valid"])
+        lines = [f"valid: {valid_n}/{result['count']}"]
+        for r in result["results"]:
+            if not r["valid"]:
+                lines.append(f"- {r['id']}: {'; '.join(r['errors'])}")
+        emit_result("\n".join(lines), json_mode=False)
+    return 0
+
+
+def cmd_dedup(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    result = checks.dedup(get_backend(args.backend))
+    if json_mode:
+        emit_result(result, json_mode=True)
+    else:
+        emit_result(
+            f"dedup: removed {result['duplicates_removed']} duplicate(s), "
+            f"{result['kept']} kept",
+            json_mode=False,
+        )
+    return 0
+
+
+def cmd_integrity(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    result = checks.integrity(get_backend(args.backend).all())
+    if json_mode:
+        emit_result(result, json_mode=True)
+    else:
+        lines = [f"ok: {result['ok']} ({result['checked']} checked)"]
+        for m in result["mismatches"]:
+            lines.append(f"- {m['id']}: stored {m['stored_hash'][:12]} != {m['actual_hash'][:12]}")
+        emit_result("\n".join(lines), json_mode=False)
+    return 0
+
+
+def cmd_freshness(args: argparse.Namespace) -> int:
+    json_mode = bool(getattr(args, "json", False))
+    now = None
+    if getattr(args, "now", None):
+        try:
+            now = datetime.fromisoformat(args.now)
+        except ValueError as exc:
+            raise CliError(
+                code=EXIT_USER_ERROR,
+                message=f"--now is not a valid ISO-8601 timestamp: {args.now}",
+                remediation="pass e.g. --now 2026-06-20T00:00:00+00:00",
+            ) from exc
+    result = checks.freshness(
+        get_backend(args.backend).all(),
+        field=args.field,
+        max_age=args.max_age,
+        now=now,
+    )
+    if json_mode:
+        emit_result(result, json_mode=True)
+    else:
+        emit_result(
+            f"freshness: {result['checked']} checked, {result['stale']} stale "
+            f"(field='{result['field']}', max_age={result['max_age']})",
+            json_mode=False,
+        )
+    return 0
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    validate = sub.add_parser(
+        "validate",
+        help="Validate envelope shape for JSON piped on stdin (object or array).",
+    )
+    _add_json_flag(validate)
+    validate.set_defaults(func=cmd_validate)
+
+    dedup = sub.add_parser(
+        "dedup",
+        help="Collapse same-hash-same-scope duplicates in the store (idempotent).",
+    )
+    _add_backend_flag(dedup)
+    _add_json_flag(dedup)
+    dedup.set_defaults(func=cmd_dedup)
+
+    integrity = sub.add_parser(
+        "integrity",
+        help="Check that every stored hash matches sha256(content).",
+    )
+    _add_backend_flag(integrity)
+    _add_json_flag(integrity)
+    integrity.set_defaults(func=cmd_integrity)
+
+    freshness = sub.add_parser(
+        "freshness",
+        help="Report age/staleness facts from a metadata timestamp field.",
+    )
+    _add_backend_flag(freshness)
+    freshness.add_argument(
+        "--field",
+        default="created",
+        help="metadata key holding an ISO-8601 timestamp (default: created).",
+    )
+    freshness.add_argument(
+        "--max-age",
+        type=float,
+        default=None,
+        help="seconds; an envelope older than this is marked stale.",
+    )
+    freshness.add_argument(
+        "--now",
+        default=None,
+        help="ISO-8601 'now' override (default: current UTC time). For determinism.",
+    )
+    _add_json_flag(freshness)
+    freshness.set_defaults(func=cmd_freshness)