receipt-query

Files (12)

• SKILL.md
• composes-in-graph.yaml · fixtures/
• ledger-answer-with-chain-proof.yaml · fixtures/
• ledger-needs-question.yaml · fixtures/
• read-ledger-by-exact-id.yaml · fixtures/
• read-ledger-with-explicit-receipts.yaml · fixtures/
• composed.graph · fixtures/support/
• mark.svg
• receipt-query.mjs
• catalog.md · references/
• mark-license.md · references/
• run.yaml

SKILL.md (first lines)

# Receipt Query

Collect the exact signed run evidence a reviewer needs, using explicit receipt
ids or bounded filters. Native Runx owns receipt lookup and verification; this
skill normalizes the query and returns a reusable evidence packet. It is
read-only.

The question records the review purpose. It is not translated into hidden
filters: amount thresholds, business totals, scope searches and arbitrary
natural-language conditions are not implemented by this runner. Supply the
supported filter fields, then pass the resulting evidence to the appropriate
review skill.

## What this skill does

`receipt-query` applies an explicit bounded query over receipt ids, principal,
skill, outcome, and time range, then returns the receipts that satisfy it as
id-keyed stubs (`receipt_id`, `skill`, `outcome`, `created_at`, verification
status). Exact-id reads also return `receipt_details` from the native redacted
inspection projection: signed authority, decisions, acts, artifact references,
lineage, issuer type, seal criteria, and verification without execution bodies, credential material,
or local paths. When `proof` asks for it, the skill returns the native tree-verification
verdict and findings. A requested check is not a successful check: an unknown
or failed verdict stays unknown or failed. The deterministic summary reports
matched receipt count and verification status, not a synthesized business
answer. Zero matches return `needs_more_evidence`.

Exact-id stubs preserve the native `subject_uri` even when no skill label is
available. Detail retains `issuer_type` and `seal_criteria`: a failed output
contract is still visible when a step has no act. A verified `local` issuer
means the Runx home signed the receipt; it does not establish an independent
operator or provider attestation. Missing replay fields stay unknown.

The default `read` runner invokes the native `receipt.query` service directly.
The service resolves the same receipt store and signature policy as Runx's CLI,
projects bounded history rows, resolves exact ids through the redacted detail
reader, and optionally verifies each matched receipt tree. There is no child
process, command-string construction, or package-local receipt parser. It is
the in-runtime way for an agent to inspect its own sealed receipts before a
gated action. The detail packet is curated in Rust and never returns execution
bodies, credential material, or local paths.

The `read` runner accepts optional `receipts` and `receipt_details` inputs for
replay or controlled evaluation. When present it uses those projections instead
of the native store. Replay is labelled as supplied evidence and never becomes
a live proof path.

It retrieves evidence across many runs; `receipt-audit` assesses governance
against an exact receipt and its authority baseline. Its nearest neighbor is
`run-history`, which also reads the ledger but returns deterministic platform
outcome and catalog-coverage metrics and routes them to governance
lanes. `receipt-query` answers one precise audit question with the receipt ids that
match and a verified chain walk, not an aggregate health report.

## When to use this skill

- A reviewer needs the receipts for an exact run or a bounded skill, actor,
  outcome, issuer or time window.
- A review needs the set of receipts that match a condition before drilling into
  any single one.
- A compliance check needs proof that a stretch of ledger history is unbroken.

## When not to use this skill

- To audit whether one run stayed inside its grant. Use `receipt-audit`; that
  is the integrity-of-one-chain question, not the cross-run history question
  `receipt-query` answers.
- To review a grant before narrowing it. Use `least-privilege`.
- For a graded platform-health report over many runs. Use `run-history`.
- To mutate, redact, export, or archive receipts. This skill is read-only and
  refuses any write framing.
- To return receipt bodies, act payloads, or any secret-bearing field. Matched
  receipts are id stubs only.

## Procedure

1. Read the question. With no question, return `needs_agent`.
2. Resolve the filter into a bounded query: principal handle, `skill`,
   outcome set, and `time_range`. An absent filter uses the bounded default
   limit; the prose question never adds a filter.
3. Match receipts against the query and collect id-keyed stubs only. Receipt
   bodies, act payloads, proofs, and material refs stay out of the output.
4. With zero matches, return `needs_more_evidence` and name the query that found
   nothing.
5. When `proof` requests chain verification, take the chain verdict from the
   engine's tree-rooted native proof report, not a hand-rolled link
   walk: `intact` follows the report's overall validity, and each `break` is
   derived from a tree's missing parent or a verification finding, named by the
   receipt ids involved. The engine checks signatures against this home's
   own key and any configured verify key; a receipt no trusted key signed is a
   break, never silently intact. When the proof is bounded out, the chain is
   reported unverified (`checked: true`, `intact: null`). When `proof` is
   absent, set `chain_verification.checked` to false and leave `intact` null.
6. Return the deterministic `summary` of matched count and native verification from the
   matched set and the verification result only. The question states the purpose;
   do not generalize from the matched slice to the whole ledger.
7. Return the `ledger_answer` with `decision: answered`.

## Edge cases and stop conditions

- **No question:** return `needs_agent`; there is nothing to query.
- **No matching receipts:** return `needs_more_evidence` with the resolved query,
  so the gap is the query, not a silent zero. Silence is a stop, not a zero.
- **Filter references an unknown principal or skill:** treat as zero matches
  and return `needs_more_evidence`; do not guess a near match.
- **Chain break found:** keep `decision: answered` but set
  `chain_verification.intact` false and list the breaking id pairs from the
  verify report; an intact answer set with a broken chain is still a reportable
  result.
- **Verify keys absent:** report `chain_verification.intact` null with
  `checked: true`; the chain is unverified, not intact.
- **Verification requested over an empty match set:** the stop is
  `needs_more_evidence` for the match, not a chain claim over nothing.
- **Write, delete, or reseal requests:** this read runner cannot perform them.
  Its sole native query scope is `receipt.read`; prose does not grant a write.

## Output

The whole result is the `runx/receipt-query.answer.v1` packet:

From runxhq/runx, Apache-2.0.

More from runxhq/runx