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
- Read the question. With no question, return
needs_agent.
- 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.
- Match receipts against the query and collect id-keyed stubs only. Receipt
bodies, act payloads, proofs, and material refs stay out of the output.
- With zero matches, return
needs_more_evidence and name the query that found
nothing.
- 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.
- 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.
- 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:
ledger_answer: the decision (answered, needs_agent,
needs_more_evidence or refused), the audit question restated in
operational terms, and the resolved filter actually run, so the answer
reproduces.
matched_receipts: id-keyed stubs only, never a receipt body.
receipt_details: exact-id reads only, Rust-curated, bounded and redacted.
chain_verification: whether verification was requested, whether the chain
is intact (null when unchecked) and each break.
summary: one or two sentences answering the question.
Scope is
receipt.read only; no gate is required because the skill cannot mutate, and a
delete, redact, reseal, or reorder request is refused, not gated. The run's own
receipt carries the question, the resolved query, the matched count, the list of
matched receipt_id values, and the chain-verification result; it carries no
matched receipt body, principal PII, or secret material. Matched receipts are
always referenced by id.
Worked example
Input:
question: Collect receipt evidence for the campaign review.
receipt_ids: [rx_101, rx_102]
proof:
verify_chain: true
The runner returns the matched id stubs, redacted native details and the native
verification verdict. Missing ids remain absent; the caller must compare the
requested ids with the matched set before relying on the evidence. A failed,
unknown or bounded-out verification verdict cannot support a claim of intact
proof. Supplying replay projections returns an unknown chain verdict even when
the fixture labels its rows verified.
Inputs
question (optional): the audit question bounding the ledger read. Without
one the runner returns needs_agent and does not query.
filter (optional): JSON narrowing the query by principal, skill,
outcome, time_range (from/to), and limit (default 500, maximum 5000).
receipt_ids (optional): up to 100 exact receipt ids to resolve and verify.
proof (optional): JSON requesting chain verification over the matched
receipts, for example { "verify_chain": true }.
receipts (optional): explicit ledger rows for replay or controlled
evaluation; when present the read runner does not query live native
history.
receipt_details (optional): explicit native redacted detail projections for
deterministic replay only.
1---2name: receipt-query3description: Retrieve bounded receipt evidence by exact ids or explicit filters, returning native verification results for downstream review.4metadata:5 source: https://skillmd.com/skills/runxhq/receipt-query6---78# Receipt Query910Collect the exact signed run evidence a reviewer needs, using explicit receipt11ids or bounded filters. Native Runx owns receipt lookup and verification; this12skill normalizes the query and returns a reusable evidence packet. It is13read-only.1415The question records the review purpose. It is not translated into hidden16filters: amount thresholds, business totals, scope searches and arbitrary17natural-language conditions are not implemented by this runner. Supply the18supported filter fields, then pass the resulting evidence to the appropriate19review skill.2021## What this skill does2223`receipt-query` applies an explicit bounded query over receipt ids, principal,24skill, outcome, and time range, then returns the receipts that satisfy it as25id-keyed stubs (`receipt_id`, `skill`, `outcome`, `created_at`, verification26status). Exact-id reads also return `receipt_details` from the native redacted27inspection projection: signed authority, decisions, acts, artifact references,28lineage, issuer type, seal criteria, and verification without execution bodies, credential material,29or local paths. When `proof` asks for it, the skill returns the native tree-verification30verdict and findings. A requested check is not a successful check: an unknown31or failed verdict stays unknown or failed. The deterministic summary reports32matched receipt count and verification status, not a synthesized business33answer. Zero matches return `needs_more_evidence`.3435Exact-id stubs preserve the native `subject_uri` even when no skill label is36available. Detail retains `issuer_type` and `seal_criteria`: a failed output37contract is still visible when a step has no act. A verified `local` issuer38means the Runx home signed the receipt; it does not establish an independent39operator or provider attestation. Missing replay fields stay unknown.4041The default `read` runner invokes the native `receipt.query` service directly.42The service resolves the same receipt store and signature policy as Runx's CLI,43projects bounded history rows, resolves exact ids through the redacted detail44reader, and optionally verifies each matched receipt tree. There is no child45process, command-string construction, or package-local receipt parser. It is46the in-runtime way for an agent to inspect its own sealed receipts before a47gated action. The detail packet is curated in Rust and never returns execution48bodies, credential material, or local paths.4950The `read` runner accepts optional `receipts` and `receipt_details` inputs for51replay or controlled evaluation. When present it uses those projections instead52of the native store. Replay is labelled as supplied evidence and never becomes53a live proof path.5455It retrieves evidence across many runs; `receipt-audit` assesses governance56against an exact receipt and its authority baseline. Its nearest neighbor is57`run-history`, which also reads the ledger but returns deterministic platform58outcome and catalog-coverage metrics and routes them to governance59lanes. `receipt-query` answers one precise audit question with the receipt ids that60match and a verified chain walk, not an aggregate health report.6162## When to use this skill6364- A reviewer needs the receipts for an exact run or a bounded skill, actor,65 outcome, issuer or time window.66- A review needs the set of receipts that match a condition before drilling into67 any single one.68- A compliance check needs proof that a stretch of ledger history is unbroken.6970## When not to use this skill7172- To audit whether one run stayed inside its grant. Use `receipt-audit`; that73 is the integrity-of-one-chain question, not the cross-run history question74 `receipt-query` answers.75- To review a grant before narrowing it. Use `least-privilege`.76- For a graded platform-health report over many runs. Use `run-history`.77- To mutate, redact, export, or archive receipts. This skill is read-only and78 refuses any write framing.79- To return receipt bodies, act payloads, or any secret-bearing field. Matched80 receipts are id stubs only.8182## Procedure83841. Read the question. With no question, return `needs_agent`.852. Resolve the filter into a bounded query: principal handle, `skill`,86 outcome set, and `time_range`. An absent filter uses the bounded default87 limit; the prose question never adds a filter.883. Match receipts against the query and collect id-keyed stubs only. Receipt89 bodies, act payloads, proofs, and material refs stay out of the output.904. With zero matches, return `needs_more_evidence` and name the query that found91 nothing.925. When `proof` requests chain verification, take the chain verdict from the93 engine's tree-rooted native proof report, not a hand-rolled link94 walk: `intact` follows the report's overall validity, and each `break` is95 derived from a tree's missing parent or a verification finding, named by the96 receipt ids involved. The engine checks signatures against this home's97 own key and any configured verify key; a receipt no trusted key signed is a98 break, never silently intact. When the proof is bounded out, the chain is99 reported unverified (`checked: true`, `intact: null`). When `proof` is100 absent, set `chain_verification.checked` to false and leave `intact` null.1016. Return the deterministic `summary` of matched count and native verification from the102 matched set and the verification result only. The question states the purpose;103 do not generalize from the matched slice to the whole ledger.1047. Return the `ledger_answer` with `decision: answered`.105106## Edge cases and stop conditions107108- **No question:** return `needs_agent`; there is nothing to query.109- **No matching receipts:** return `needs_more_evidence` with the resolved query,110 so the gap is the query, not a silent zero. Silence is a stop, not a zero.111- **Filter references an unknown principal or skill:** treat as zero matches112 and return `needs_more_evidence`; do not guess a near match.113- **Chain break found:** keep `decision: answered` but set114 `chain_verification.intact` false and list the breaking id pairs from the115 verify report; an intact answer set with a broken chain is still a reportable116 result.117- **Verify keys absent:** report `chain_verification.intact` null with118 `checked: true`; the chain is unverified, not intact.119- **Verification requested over an empty match set:** the stop is120 `needs_more_evidence` for the match, not a chain claim over nothing.121- **Write, delete, or reseal requests:** this read runner cannot perform them.122 Its sole native query scope is `receipt.read`; prose does not grant a write.123124## Output125126The whole result is the `runx/receipt-query.answer.v1` packet:127128- `ledger_answer`: the decision (`answered`, `needs_agent`,129 `needs_more_evidence` or `refused`), the audit question restated in130 operational terms, and the resolved filter actually run, so the answer131 reproduces.132- `matched_receipts`: id-keyed stubs only, never a receipt body.133- `receipt_details`: exact-id reads only, Rust-curated, bounded and redacted.134- `chain_verification`: whether verification was requested, whether the chain135 is intact (`null` when unchecked) and each break.136- `summary`: one or two sentences answering the question.137138Scope is139`receipt.read` only; no gate is required because the skill cannot mutate, and a140delete, redact, reseal, or reorder request is refused, not gated. The run's own141receipt carries the question, the resolved query, the matched count, the list of142matched `receipt_id` values, and the chain-verification result; it carries no143matched receipt body, principal PII, or secret material. Matched receipts are144always referenced by id.145146## Worked example147148Input:149150```yaml151question: Collect receipt evidence for the campaign review.152receipt_ids: [rx_101, rx_102]153proof:154 verify_chain: true155```156157The runner returns the matched id stubs, redacted native details and the native158verification verdict. Missing ids remain absent; the caller must compare the159requested ids with the matched set before relying on the evidence. A failed,160unknown or bounded-out verification verdict cannot support a claim of intact161proof. Supplying replay projections returns an unknown chain verdict even when162the fixture labels its rows verified.163164## Inputs165166- `question` (optional): the audit question bounding the ledger read. Without167 one the runner returns `needs_agent` and does not query.168- `filter` (optional): JSON narrowing the query by `principal`, `skill`,169 `outcome`, `time_range` (`from`/`to`), and `limit` (default 500, maximum 5000).170- `receipt_ids` (optional): up to 100 exact receipt ids to resolve and verify.171- `proof` (optional): JSON requesting chain verification over the matched172 receipts, for example `{ "verify_chain": true }`.173- `receipts` (optional): explicit ledger rows for replay or controlled174 evaluation; when present the `read` runner does not query live native175 history.176- `receipt_details` (optional): explicit native redacted detail projections for177 deterministic replay only.