add virtuals-acp-evidence

CHANGELOG.md

@@ -12,6 +12,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 - Add a bounded agent-job result schema, documentation, and synthetic conforming example linked to source-manifest provenance.
 - Add backward-compatible cost, timeout, and freshness metadata to agent-job results.
 - Add a default-deny action-control schema, deterministic evaluator, documentation, and synthetic dry-run and authorized-action examples.
+- Add a deterministic local Virtuals ACP public-evidence verification service with a bounded request schema, conforming job-result receipts, hidden offering metadata, timeout/retry behavior, and synthetic buyer/provider lifecycle fixtures.
 
 ### Security
 

DESIGN.md

@@ -88,3 +88,7 @@ Cost, timeout, and freshness are optional, strictly bounded objects in the agent
 ### D10. Separate authorization from execution and default to denial
 
 The action-control evaluator computes a stable digest over a bounded public action and emits only a dry-run, authorized, or rejected decision. It never executes an action. Execute requests require an unexpired approval whose action identifier, type, and digest match exactly; missing, malformed, expired, rejected, future-issued, or mismatched approvals deny execution. A separate adapter must re-check authorization at its execution boundary.
+
+### D11. Use public-evidence verification as the first Virtuals ACP job
+
+The first ACP reference provider verifies a source manifest and agent-job result, checks their provenance linkage and public HTTPS locations, and returns the existing agent-job result contract as its receipt. This fills a portable checker gap without duplicating the official CLI, SDK, or on-chain evaluator showcases. Local mode models the documented buyer/provider lifecycle with zero measured cost and bounded timeout/retries, but performs no authentication, wallet, payment, signing, inference, network, or live ACP operation. A future live adapter remains separate and approval-gated.

README.md

@@ -2,7 +2,7 @@
 
 Open-source tools, adapters, schemas, and operational patterns for agent-native commerce, starting with Reppo and Virtuals ACP.
 
-> **Status:** v0.1.0 — read-only Reppo ecosystem inspector.
+> **Status:** v0.1.0 released; the deterministic local Virtuals ACP reference service is currently unreleased.
 
 ## Mission
 
@@ -65,6 +65,9 @@ agentic-commerce reppo status --pretty
 agentic-commerce reppo datanets --limit 20
 agentic-commerce reppo pods --limit 20
 agentic-commerce reppo snapshot --limit 10 --pretty
+agentic-commerce virtuals-acp verify-evidence \
+  --request examples/virtuals-acp-evidence/request-v1.example.json \
+  --pretty
 ```
 
 Runtime code uses only Python's standard library. Install the development-only schema and build tools before running the complete verification suite:
@@ -83,6 +86,8 @@ For portable public-source provenance records and bounded structured job results
 
 For deterministic dry-run and default-deny approval decisions, see [docs/action-controls.md](docs/action-controls.md), `schemas/action-control-v1.schema.json`, and `agentic_commerce.action_control`. The evaluator authorizes or rejects bounded actions but never executes them.
 
+For the selected Phase 3 Virtuals ACP job, see [docs/virtuals-acp-evidence-service.md](docs/virtuals-acp-evidence-service.md), `schemas/acp-evidence-request-v1.schema.json`, and `agentic_commerce.acp_evidence`. Local mode simulates a buyer/provider evidence-verification lifecycle, emits a conforming job-result receipt, and performs no wallet, payment, signing, inference, or network operation.
+
 For silent compatibility drift detection and bounded weekly project evidence, see [docs/automation.md](docs/automation.md). These helpers are read-only and never perform GitHub mutations.
 
 At the 2026-07-11 compatibility check, the datanet and pod catalogs were live. The documented public stats route returned HTTP 404, so `status` and `snapshot` correctly returned partial result code `2` while preserving catalog data. The upstream pods route also ignored its requested page size; the client applies the requested limit after a capped download.

ROADMAP.md

@@ -38,11 +38,11 @@ A phase is complete only when its artifacts are exercised and its verification g
 
 ## Phase 3 — Virtuals ACP reference service (`v0.3.0`)
 
-- [ ] Select one narrowly useful ACP job
-- [ ] Implement local/test mode before paid inference
-- [ ] Add bounded cost, timeout, and retry behavior
-- [ ] Return sources, limitations, and machine-readable receipts
-- [ ] Test buyer-to-provider flow
+- [x] Select one narrowly useful ACP job.
+- [x] Build a local/test mode before paid inference.
+- [x] Make cost, timeout, and retry behavior explicit.
+- [x] Expose sources, limitations, and machine-readable receipts.
+- [x] Test buyer-to-provider flow end to end with synthetic fixtures.
 
 **Gate:** end-to-end test job returns a sourced result with observable cost and failure behavior.
 

docs/README.md

@@ -4,6 +4,7 @@
 - [Provenance schemas](provenance-schemas.md)
 - [Agent job result schema](provenance-schemas.md#agent-job-result-v1)
 - [Dry-run and approval controls](action-controls.md)
+- [Virtuals ACP public-evidence reference service](virtuals-acp-evidence-service.md)
 - [Read-only maintenance automation](automation.md)
 - [Release process](releasing.md)
 

docs/virtuals-acp-evidence-service.md

@@ -0,0 +1,137 @@
+# Virtuals ACP public-evidence reference service
+
+## Selected Phase 3 job
+
+**Job type:** `virtuals-acp.public-evidence-verification`
+
+A buyer supplies two public artifacts:
+
+1. a candidate `source-manifest-v1` document;
+2. a candidate `agent-job-result-v1` document.
+
+The provider checks both contracts, verifies manifest and source-identifier linkage, applies a public HTTPS source-location policy, and returns an `agent-job-result-v1` receipt. This is narrowly useful for buyers that need a portable checker before accepting or composing an agent deliverable.
+
+The first implementation is deterministic **local mode**. It performs no ACP authentication, agent registration, wallet operation, signing, transaction, escrow funding, payment, inference call, or network request.
+
+## Why this job
+
+The job reuses the toolkit's provenance and result contracts instead of creating a parallel vocabulary. Its output can be checked independently, does not need inference, and remains useful without a grant, token, or hosted agent.
+
+It complements rather than duplicates current official examples:
+
+- the active ACP CLI supports offerings with JSON-schema requirements and deliverables;
+- the ACP Node SDK v2 documents an event-driven buyer/provider lifecycle and role-gated actions;
+- the official aiport showcase recomputes on-chain actions in ACP's evaluator role, whereas this service checks portable public evidence as a provider deliverable;
+- the official Agent Supply Chain showcase demonstrates deterministic local buyer-side planning, but not this evidence contract.
+
+## Public upstream observations
+
+Observed at `2026-07-15T12:09:27Z` from public Virtuals Protocol repositories:
+
+| Source | Observation |
+|---|---|
+| [`Virtual-Protocol/acp-cli`](https://github.com/Virtual-Protocol/acp-cli) | Active package version observed as `1.0.24`; supports JSON output, offering requirement/deliverable schemas, job queries, and the documented job lifecycle. |
+| [`Virtual-Protocol/acp-node-v2`](https://github.com/Virtual-Protocol/acp-node-v2) | Current Node v2 SDK documents event-driven `AcpAgent`/`JobSession` behavior and role-gated job tools. |
+| [`Virtual-Protocol/acp-cli-demos`](https://github.com/Virtual-Protocol/acp-cli-demos) | Public showcases include evaluator verification and deterministic local orchestration patterns. |
+| [`Virtual-Protocol/acp-python`](https://github.com/Virtual-Protocol/acp-python) | Public Python SDK remains available, but its documented live examples require wallet and agent configuration that local mode intentionally avoids. |
+
+The official repositories identify `openclaw-acp` and the older `acp-node` surface as deprecated. This reference therefore documents future integration against `acp-cli`/`acp-node-v2`, not those retired interfaces. Upstream behavior can drift; the offering example remains hidden and is not registered automatically.
+
+## Contracts
+
+### Request
+
+`schemas/acp-evidence-request-v1.schema.json` defines the bounded transport envelope:
+
+- stable request ID and job type;
+- explicit `local` or future `virtuals-acp` mode;
+- candidate source manifest;
+- candidate agent-job result;
+- no undeclared transport fields.
+
+The candidate documents are intentionally accepted as bounded objects at the transport boundary. The provider must be able to return useful contract findings for a malformed candidate rather than having the marketplace reject it before verification.
+
+The runtime also enforces a 1,000,000-byte canonical request limit.
+
+### Receipt
+
+The provider reuses `schemas/agent-job-result-v1.schema.json`. A successful service run records:
+
+- `verdict`: `pass` or `fail`;
+- four named checks and bounded findings;
+- sanitized public source references;
+- lifecycle states;
+- attempt count;
+- zero measured local cost;
+- timeout and freshness observations;
+- explicit limitations.
+
+A `fail` verdict means verification completed and found a contract, linkage, or location-policy problem. It is not a provider crash. Provider timeout or retry exhaustion instead returns `status: failed`, `result: null`, and a stable error code.
+
+## Run local mode
+
+From the repository root, without installation:
+
+```bash
+PYTHONPATH=src python3.11 -m agentic_commerce \
+  virtuals-acp verify-evidence \
+  --request examples/virtuals-acp-evidence/request-v1.example.json \
+  --pretty
+```
+
+The synthetic fixture returns exit code `0` and matches `receipt-v1.example.json` apart from ordinary clock/elapsed fields when a real clock is used.
+
+Exit codes:
+
+| Code | Meaning |
+|---:|---|
+| `0` | Provider completed verification and every check passed. |
+| `1` | Input could not be read, or the provider timed out/failed. |
+| `2` | Provider completed verification and one or more checks failed. |
+
+## Local buyer/provider lifecycle
+
+The passing fixture records:
+
+```text
+open → budget_set → funded → submitted → completed
+```
+
+These are simulated protocol states. `funded` means only that the synthetic buyer advanced through the local state machine; no funds are created or moved. A service-level failure ends at `rejected`.
+
+The provider retries only `TransientProviderError`, at most three attempts by default and never more than ten. Other exceptions fail immediately and their private exception text is not copied into the public receipt. Timeout is measured across all attempts.
+
+## Offering mapping
+
+`examples/virtuals-acp-evidence/offering-v1.example.json` is shaped for the current ACP CLI offering fields:
+
+- name and description;
+- fixed public price;
+- five-minute SLA;
+- JSON-schema requirements and deliverable summaries;
+- `requiredFunds: false`;
+- `isHidden: true`.
+
+The `0.01` price is illustrative metadata for a future test offering. Local execution always reports zero cost. The example has not been submitted to Virtuals ACP and must not be treated as a live listing.
+
+A future live adapter must remain separate from the verifier and require explicit approval before registration, job creation, funding, submission, completion, or rejection. It must not collect private keys or print authentication material.
+
+## Verification scope and limitations
+
+The provider checks:
+
+- bounded v1 contract shape and field semantics;
+- RFC 3339 timestamps and result timing order;
+- provenance manifest-ID equality;
+- referenced source IDs exist in the manifest;
+- source and manifest locations are public HTTPS URLs without user info, private IP literals, local hostnames, or non-HTTPS ports.
+
+A pass does **not** prove:
+
+- that a publisher's claims are true;
+- that a URL remains available;
+- that content has not changed unless a separately verified digest is present;
+- that an ACP payment or settlement occurred;
+- that a real provider, buyer, or evaluator participated.
+
+No live ACP operation should be inferred from the synthetic receipt.

examples/README.md

@@ -4,5 +4,6 @@
 - [Source manifest](source-manifest/README.md)
 - [Agent job result](agent-job-result/README.md)
 - [Dry-run and approval controls](action-control/README.md)
+- [Virtuals ACP public-evidence service](virtuals-acp-evidence/README.md)
 
 Tested, public-source-only examples live here.

examples/virtuals-acp-evidence/README.md

@@ -0,0 +1,31 @@
+# Virtuals ACP public-evidence examples
+
+These synthetic fixtures exercise the Phase 3 local buyer/provider reference flow:
+
+- `request-v1.example.json` bundles the existing public source-manifest and agent-job result examples.
+- `receipt-v1.example.json` is the deterministic provider output at `2026-07-15T12:15:00Z` with zero elapsed time.
+- `offering-v1.example.json` maps the job to the current public ACP CLI offering fields but remains hidden and unregistered.
+
+Regenerate the receipt from the request:
+
+```bash
+PYTHONPATH=src python3.11 - <<'PY'
+import json
+from pathlib import Path
+from agentic_commerce.acp_evidence import run_local_evidence_job
+
+request = json.loads(
+    Path("examples/virtuals-acp-evidence/request-v1.example.json").read_text()
+)
+receipt = run_local_evidence_job(
+    request,
+    clock=lambda: "2026-07-15T12:15:00Z",
+    monotonic=lambda: 100.0,
+)
+print(json.dumps(receipt, indent=2))
+PY
+```
+
+The committed request conforms to `schemas/acp-evidence-request-v1.schema.json`. The receipt conforms to the existing `schemas/agent-job-result-v1.schema.json`.
+
+The fixtures contain no ACP authentication, wallet identifiers, signatures, transactions, account data, paid inference, private runtime state, or claims of live marketplace execution.

examples/virtuals-acp-evidence/offering-v1.example.json

@@ -0,0 +1,49 @@
+{
+  "name": "Evidence Verify",
+  "description": "Validate a public source manifest and agent-job result, verify provenance linkage and public HTTPS source policy, and return a machine-readable receipt.",
+  "priceType": "fixed",
+  "priceValue": 0.01,
+  "slaMinutes": 5,
+  "requirements": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+      "schemaVersion",
+      "requestId",
+      "jobType",
+      "mode",
+      "sourceManifest",
+      "jobResult"
+    ],
+    "properties": {
+      "schemaVersion": {"const": "1.0"},
+      "requestId": {"type": "string", "minLength": 3, "maxLength": 100},
+      "jobType": {"const": "virtuals-acp.public-evidence-verification"},
+      "mode": {"enum": ["local", "virtuals-acp"]},
+      "sourceManifest": {"type": "object", "minProperties": 1, "maxProperties": 20},
+      "jobResult": {"type": "object", "minProperties": 1, "maxProperties": 30}
+    }
+  },
+  "deliverable": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "required": [
+      "schemaVersion",
+      "jobId",
+      "jobType",
+      "status",
+      "request",
+      "result",
+      "provenance",
+      "errors",
+      "limitations"
+    ],
+    "properties": {
+      "schemaVersion": {"const": "1.0"},
+      "jobType": {"const": "virtuals-acp.public-evidence-verification"}
+    }
+  },
+  "requiredFunds": false,
+  "isHidden": true
+}