retvest-ril 0.1.0a1

Retvest Intelligence Language CLI and dry-run transaction runtime

Retvest Intelligence Language

RIL is a local transaction proof for governed AI work.

v0.1 proves dry-run pass/block behavior. v0.2 adds explicit local vault commit proof. The current local slice also proves corpus-backed evidence packet generation, support verification, fake hosted model export control, and an explicit OpenAI provider adapter demo.

Full usage guide: docs/ril/USAGE.md.

Founder-facing proof:

make ril-demo

This writes .ril_runs/ril_demo/proof_summary.json and .ril_runs/ril_demo/proof_summary.md alongside the happy and blocked work packages.

Explicit local commit proof:

make ril-commit-demo

This writes a verified dry-run package, synthetic approval receipt, immutable vault package, commit receipt, duplicate commit block result, vault verify result, and proof summaries under .ril_runs/ril_commit_demo/.

Source corpus proof:

make ril-corpus-demo

This builds a Markdown/TXT source corpus, writes source_corpus.json, source_manifest.json, chunks.json, and classification.json, and proves unsupported file types block.

Corpus-backed evidence packet proof:

make ril-evidence-demo

This builds a source corpus, retrieves registry-declared keyword chunks, generates a structured evidence packet, writes retrieval_result.json, accepts the happy path, blocks an unresolved citation, and blocks an unsupported cited claim.

Hosted model export-control proof:

make ril-hosted-llm-export-demo

This proves ALLOW EXPORT/DENY EXPORT over a fake hosted model boundary: internal corpus with tenant consent calls the fake provider, while no-consent and secret corpus cases block before provider call.

Explicit OpenAI adapter proof:

make ril-openai-adapter-demo

This deterministic target proves OpenAI-compatible response parsing, local Ollama/vLLM endpoint routing without a real secret, remote no-key fail-closed behavior, and the same verifier gates used after provider output. Ollama defaults to native /api/chat; vLLM defaults to OpenAI-compatible /v1/chat/completions.

Consumer Runtime outcome helper example:

make runtime-outcome-example-check

The complete executable example is examples/consumer_runtime_outcome_receipt.py. Its request and response payloads are pinned to the shipped OpenAPI examples by the owner-repo gate.

from ril import (
    ConsumerRuntimeOutcomeReceipt,
    ConsumerRuntimeOutcomeRequest,
    RuntimeAuditReceipt,
    validate_consumer_runtime_outcome_receipt_pair,
)

request = ConsumerRuntimeOutcomeRequest.model_validate(request_payload)
response = ConsumerRuntimeOutcomeReceipt.model_validate(response_payload)
assert isinstance(response.receipt, RuntimeAuditReceipt)
validate_consumer_runtime_outcome_receipt_pair(
    request,
    response,
    tenant_ref="tenant_acme_bank",
    work_id="work_01J1RTVSTKYC00001",
)

The ConsumerRuntimeOutcomeRequest and ConsumerRuntimeOutcomeReceipt helpers are aliases for the shipped RuntimeOutcomeReceiptRequest and RuntimeOutcomeReceiptResponse contract types. Keep examples in the OpenAPI contract field shape; do not use stale camelCase helper payloads. DTO parsing enforces only the shipped field constraints. Call the pair validator to enforce route ownership, request/receipt bindings, receipt ordering, and audit-chain semantics. Pair validation also requires the final outcome's nested audit receipt to have a non-null previous_digest: generic runtime genesis receipts may be unchained, but an outcome must advance the existing work audit chain.

DB-backed Consumer Runtime ownership proof:

make consumer-runtime-db-proof-check
make consumer-runtime-postgres-proof-check

The first focused gate runs the full suite against a temporary SQLite database. The second starts an ephemeral real PostgreSQL server and exercises registration, heartbeat, bounded work lease, metadata-only evidence persistence, and competing lease serialization. Both prove stale heartbeats and stolen lease tokens fail closed without work or evidence side effects while appending privacy-minimized refusal facts. Bearer tokens are persisted only as SHA-256 digests, and all accepted and denied transitions form an immutable, replay-verifiable audit hash chain. This local executable proof does not own or replace platform API state.

{
  "agent_id": "agent_01J1RTVSTACME00001",
  "approval_id": "approval_01J1RTVSTKYC00001",
  "completed_at": "2026-06-27T11:18:44Z",
  "evidence_receipt_ids": [
    "evrec_01J1RTVSTKYC00001"
  ],
  "lease_token": "lease_tok_01J1RTVSTKYC00001",
  "outcome": "succeeded",
  "result_digest": "6666666666666666666666666666666666666666666666666666666666666666",
  "summary": "Daily KYC queue reconciliation completed with all evidence digests attached."
}

{
  "accepted_at": "2026-06-27T11:18:45Z",
  "outcome_receipt_id": "outrec_01J1RTVSTKYC00001",
  "receipt": {
    "agent_id": "agent_01J1RTVSTACME00001",
    "audit_uri": "audit://tenant_acme_bank/runtime/rtrec_01J1OUTCOME0001.json",
    "created_at": "2026-06-27T11:18:45Z",
    "digest": "6666666666666666666666666666666666666666666666666666666666666666",
    "previous_digest": "5555555555555555555555555555555555555555555555555555555555555555",
    "receipt_id": "rtrec_01J1OUTCOME0001",
    "receipt_type": "outcome",
    "tenant_ref": "tenant_acme_bank",
    "work_id": "work_01J1RTVSTKYC00001"
  },
  "tenant_ref": "tenant_acme_bank",
  "work_id": "work_01J1RTVSTKYC00001"
}

Operator-led paid-pilot proof:

make ril-pilot-operator-demo

This initializes a pilot workspace, creates a PASS review, records named customer approval, commits with review, verifies the vault, builds audit_packet.zip, and proves a REJECT review blocks commit.

Acceptance gate:

make ril-real-v0

Editor highlighting and file icons:

make ril-editor-vscode-vsix
make ril-editor-vscode-install

Long syntax showcase:

examples/ril/showcase/enterprise_compliance_showcase.ril

Developer commands:

apps/api/.venv/bin/pip install apps/ril --no-build-isolation
source apps/api/.venv/bin/activate

ril check examples/ril/compliance_evidence_packet/workflow.ril
ril corpus build examples/ril/source_corpus --name pilot_policy_corpus \
  --declared-class internal --out .ril_runs/source_corpus_demo
ril evidence build --registry .ril_runs/ril_evidence_demo/happy_path/ril.registry.json \
  --source-corpus policy_corpus --retriever keyword_retriever \
  --generator deterministic_evidence_packet --out .ril_runs/ril_evidence_demo/debug
ril explain examples/ril/compliance_evidence_packet/workflow.ril --json
ril preflight examples/ril/compliance_evidence_packet/workflow.ril \
  --registry examples/ril/compliance_evidence_packet/happy_path/ril.registry.json
ril run examples/ril/compliance_evidence_packet/workflow.ril --dry-run \
  --registry examples/ril/compliance_evidence_packet/happy_path/ril.registry.json
ril approve .ril_runs/.../work_package.json --role compliance_lead \
  --out .ril_runs/.../approval.json
ril commit .ril_runs/.../work_package.json \
  --registry examples/ril/compliance_evidence_packet/happy_path/ril.registry.json \
  --approval .ril_runs/.../approval.json
ril vault verify \
  --registry examples/ril/compliance_evidence_packet/happy_path/ril.registry.json \
  --target compliance_vault

make ril-real-v0 performs no real model provider API calls. The fake hosted provider remains the deterministic export-control proof. The OpenAI-compatible adapter proof is explicit, deterministic, and kept outside ril-real-v0. Dry-run remains non-committing but may still require EXPORT policy; real local vault writes require the explicit approve/commit command chain.

Real v0 accepts the repo-local non-editable install above. Editable pip install -e apps/ril support is tooling debt until the repo API venv loads editable paths correctly.