Metadata-Version: 2.1
Name: retvest-ril
Version: 0.1.0a140
Summary: Retvest governed database language and accountability runtime
Author: Retvest AI
License: Proprietary
Project-URL: Source, https://github.com/retvest/retvest-ril
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: annotated-types==0.8.0
Requires-Dist: dnspython==2.8.0
Requires-Dist: email-validator==2.3.0
Requires-Dist: idna==3.18
Requires-Dist: pydantic==2.13.4
Requires-Dist: typing-extensions==4.16.0
Provides-Extra: postgres
Requires-Dist: psycopg[binary]==3.3.4; extra == "postgres"
Provides-Extra: test
Requires-Dist: build==1.2.2.post1; extra == "test"
Requires-Dist: psycopg[binary]==3.3.4; extra == "test"
Requires-Dist: pytest<9,>=8; extra == "test"
Requires-Dist: setuptools==75.6.0; extra == "test"
Requires-Dist: wheel==0.45.1; extra == "test"

# 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`.

## Governed DATA engines

RIL's default DATA target is its own append-only epoch engine:

```bash
ril data plan program.ril --tenant tenant_acme --json
ril data run program.ril --tenant tenant_acme --engine-dir .ril-data \
  --agent agent:triage --authority lease:triage-42 \
  --lease-token-file .secrets/lease.token --evidence evidence:packet-7 --json
```

Writes require an active lease in the engine and are authority-checked, fsynced,
hash-chained, time-travel readable, and replay-verifiable.

After a table or view is governed once, later authenticated programs do not
repeat its declaration. `ril data run` resolves standalone mutations and schema
statements against one verified durable-catalogue snapshot; embedded callers
use `ril.execute_program(...)`. The PostgreSQL facade's bounded single-column
`CREATE INDEX ... USING HASH` output can therefore backfill an existing table.
Native prepared programs validate at prepare and revalidate inside execution's
commit transaction so catalogue drift is refused before mutation.

`SELECT` accepts PostgreSQL-style named-window inheritance and inline existing-
window copies. Parent definitions resolve only in source order, inherited
partitioning and ordering are flattened into the closed execution AST, and the
PostgreSQL restrictions on `PARTITION BY`, `ORDER BY`, and framed parents fail
static checking before either native or compatibility execution.

Explicit windows accept `ROWS`, `RANGE`, and peer-counted `GROUPS` frames with
row-independent constant-expression bounds in `BETWEEN` and shorthand form.
Typed parameters and closed scalar expressions are supported; `ROWS`/`GROUPS`
must yield a non-negative `INT`, numeric `RANGE` must yield a non-negative
number, and NULL is refused. PostgreSQL 18 `EXCLUDE CURRENT ROW`, `GROUP`,
`TIES`, and `NO OTHERS` semantics are implemented by both the native evaluator
and compatibility compiler. Temporal `RANGE` interval offsets remain pending.

An `--evidence` value binds an identifier; it is not proof that external bytes
exist or are authentic. Library callers that need that stronger claim pass an
explicit `DataEvidenceAdmission` to `execute_log` or `execute_program`. Its
trusted resolver binds authenticated bytes to every final row receipt before
the atomic batch commits;
the CLI intentionally discovers no ambient resolver. See
[`evidence-reference-binding-v0.md`](../docs/evidence-reference-binding-v0.md).

Bootstrap a new local store entirely through the published CLI. This generates a
new bearer token in a private file (and refuses to overwrite an existing file),
then issues the `data`-namespace lease it needs:

```bash
ril data lease issue --tenant tenant_acme --engine-dir .ril-data \
  --agent agent:triage --authority lease:triage-42 \
  --lease-token-file .secrets/lease.token --valid-for-seconds 3600 --json
ril data run program.ril --tenant tenant_acme --engine-dir .ril-data \
  --agent agent:triage --authority lease:triage-42 \
  --lease-token-file .secrets/lease.token --evidence evidence:packet-7 --json
```

If `data run` finds no matching lease, it returns a structured
`data_lease_missing` error with the tenant, authority, agent, and the
`ril data lease issue` remediation command.

An application can use the same engine across a long-running process boundary.
`ril data serve` reads strict tenant/agent bindings from JSON while loading each
bearer value from a separate owner-only file, binds numeric IPv4 loopback only,
and publishes one readiness JSON line after the TCP port is live:

```bash
ril data serve --tenant tenant_acme --engine-dir .ril-data \
  --auth-bindings-file .ril-service/bindings.json --port 7432 --json
```

Use `NativeEngineDriver(NativeSocketTransport("127.0.0.1", 7432))` from Python.
The service preserves the bounded `ril.native_protocol.v0` request, result,
receipt, authentication, preparation, and cancellation semantics and closes
cleanly on `SIGINT` or `SIGTERM`. See
[`native-protocol-v0.md`](../docs/native-protocol-v0.md) for the exact operated
profile and remote-network boundary.

After handshake and authentication, `driver.observe()` returns the strict
`ril.native_operational_snapshot.v0` live view. It is capped at 16 KiB and
binds the current process, a one-way tenant digest, a monotonic sequence, and
all health/capacity/query/storage/recovery/refusal fields in one self-digest.
The driver rejects tampering and replay. Source text, parameters, row values,
record IDs, bearer/evidence material, peer data, and cross-tenant utilization
are absent by schema.

Large reads use `driver.query_stream(source, batch_rows=128)`. Opening returns
metadata only; each explicit `fetch_next()` pulls one row- and byte-bounded
chunk, while `close()` discards unread cursor state. Terminal count and
domain-separated result-digest verification detect missing or substituted
chunks. To stop evaluation before a cursor exists, create an operation ID and
use `query_stream_outcome(...)` plus `cancel_operation(...)`; direct reads use
the same pattern through `query_outcome(...)`. A verified
`ril.native_query_cancellation.v0` receipt proves that no row was returned and
no write committed.

Large writes use `driver.bulk_ingest(...)`: ordered typed row arrays cross
bounded multi-frame appends and become visible only through one final governed
storage batch. The authenticated tenant/agent and one lease/evidence context
bind every row; schema changes, type/constraint failures, resource denial, or
lease refusal roll back the complete ingest. The public profile caps a batch at
10,000 rows/8 MiB and exposes `open_bulk_ingest()` for explicit cancellation.

Exact AI retrieval uses `VECTOR(dimension, "model")` columns and `DATA SEARCH`.
Vector components cross Python, JSON, storage, receipts, and the PostgreSQL
oracle as plain-decimal strings, never binary floats. `driver.query(...)`
returns a verified `ril.data_vector_search_receipt.v0` with each search;
`query_stream(...)` refuses vector searches because its v0 envelope cannot
carry that receipt. Search is capped at 10,000 governed candidates and 100
results and deliberately makes no ANN or pgvector-scale claim.

PostgreSQL is an explicitly invoked compatibility/differential oracle, never a
native production default. Its optional governed-storage adapter can be used
only when an operator deliberately supplies a private DSN:

```bash
ril data run program.ril --tenant tenant_acme --engine postgres \
  --postgres-dsn-file .secrets/postgres.dsn \
  --agent agent:triage --authority lease:triage-42 \
  --lease-token-file .secrets/lease.token --evidence evidence:packet-7 --json
```

This is different from `ril data plan --target postgres`, which emits the
parameterised compatibility plan for adopting RIL around ordinary existing
tables. Neither command participates in the supported production inventory:
the epoch engine remains the available native authority when the optional
PostgreSQL toolchain is absent. See
[`RIL-NATIVE-PRODUCTION-WORKLOADS.md`](../docs/RIL-NATIVE-PRODUCTION-WORKLOADS.md).

Founder-facing proof:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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.

```python
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:

```text
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.

<!-- consumer-runtime-outcome-request:start -->
```json
{
  "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."
}
```
<!-- consumer-runtime-outcome-request:end -->

<!-- consumer-runtime-outcome-response:start -->
```json
{
  "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"
}
```
<!-- consumer-runtime-outcome-response:end -->

Operator-led paid-pilot proof:

```text
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:

```text
make ril-real-v0
```

Editor highlighting and file icons:

```text
make ril-editor-vscode-vsix
make ril-editor-vscode-install
```

Long syntax showcase:

```text
examples/ril/showcase/enterprise_compliance_showcase.ril
```

Developer commands:

```text
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.
