# Oprow Continuum

Oprow Continuum is a temporal verification firewall for coding agents. Before
an agent changes a repository, Oprow checks its structured assumptions or
unified diff against immutable version receipts and returns `allow`, `block`,
or `abstain` with exact evidence.

![Oprow architecture](docs/oprow-architecture.png)

The product contract is deliberately stricter than ordinary retrieval:

- CockroachDB stores immutable receipts and supersession edges;
- normal review activates a bounded evidence packet;
- contradicted assumptions block;
- unsupported semantics abstain rather than receive approval;
- review never mutates the repository;
- state-changing actions remain separately confirmation-gated.

## Status

The submitted product contract is
[`docs/AGENT_VERIFICATION_ENDGAME_2026-08-14.md`](docs/AGENT_VERIFICATION_ENDGAME_2026-08-14.md).
The concise calibration record is
[`docs/EVIDENCE_LEDGER.md`](docs/EVIDENCE_LEDGER.md); closed plans remain in
`docs/archive/`.

This repository contains a runnable trusted-core application, agent API, MCP
server, and operator UI.
It does not claim product superiority or bundle a trained semantic checkpoint.
The service exposes explicit version semantics, exact cited receipt reads,
confirmation-gated rollback proposals, stale-proposal rejection, fixed active
state accounting, and checkpoint/restore. The CockroachDB immutable point-read
adapter passed its first live Cloud gate on 2026-08-05.

The tested learned Shared-Stream Modus_X controller is excluded from the
product after the valid A2C/A2D failures. The system does **not** claim to
compress an entire codebase into one small controller or understand arbitrary
code semantics.

## Product Target

```text
repository history -> typed extraction -> CockroachDB temporal receipts
agent claim or diff -> bounded verification -> allow / block / abstain
                                         -> cited evidence -> human decision
```

Judges can connect a bounded public GitHub repository directly from the UI.
A self-hosted operator can also exercise the trusted core with a pinned event
stream at startup:

```powershell
python -m pip install -e ".[product,mcp]"
$env:OPROW_REASONER="disabled"
$env:OPROW_API_TOKEN="replace-with-a-long-random-value"
oprow serve --repository-id fastapi/fastapi `
  --events examples/fastapi_compatibility_events.jsonl
```

The bounded public demo connector accepts public GitHub repositories under
strict import-count, commit, event, checkout-size, and wall-time limits. Private
repositories remain unsupported.

## Hackathon

Oprow Continuum is registered for the CockroachDB x AWS Agentic Memory
Hackathon. CockroachDB will hold the transactional event ledger, capsule
metadata, and provenance. Oprow remains the fixed-size active semantic memory.
AWS provides CodeBuild/ECR packaging, Secrets Manager runtime credentials,
Bedrock reasoning, and the public HTTPS application environment.

See [docs/HACKATHON.md](docs/HACKATHON.md).

The component boundary is defined in
[docs/PRODUCT_ARCHITECTURE.md](docs/PRODUCT_ARCHITECTURE.md), with calibrated
claims and failures in [docs/EVIDENCE_LEDGER.md](docs/EVIDENCE_LEDGER.md).

## Development

```powershell
python -m pip install -e ".[dev,product,mcp]"
pytest
oprow demo
oprow db-smoke --env-file .env
oprow serve --repository-id fastapi/fastapi --events examples/fastapi_compatibility_events.jsonl
$env:OPROW_BASE_URL="http://127.0.0.1:8000"
oprow-mcp
powershell -ExecutionPolicy Bypass -File scripts/check_scope.ps1
```

FastAPI publishes the machine contract at `/openapi.json`; the review endpoint
is `POST /api/agent/review`. `oprow-mcp` exposes the same contract as four MCP
tools over stdio for Claude Code, Cursor, Codex, and other MCP clients.

The chat surface is available at `http://127.0.0.1:8000`. Without a
database URL it uses a process-local ledger. With `DATABASE_URL` or
`COCKROACH_DB_URL`, it uses the tested CockroachDB immutable receipt adapter and
automatically writes `.oprow/continuum.capsule` after accepted state changes.
The default reasoner is Amazon Nova 2 Lite through Bedrock. Set
`OPROW_REASONER=disabled` only for trusted-core diagnostics.

The deployed demo uses three pinned, non-synthetic FastAPI compatibility
migrations: dropping Python 3.9, admitting Starlette 1.0+, and raising the
Pydantic minimum. `scripts/build_fastapi_compatibility_demo.py` reproduces the
six events from the official Git history; the pinned commits and values are
recorded in `examples/fastapi_compatibility_manifest.json`.

Container smoke:

```bash
docker build -t oprow-continuum .
docker run --rm -p 8000:8000 -e OPROW_API_TOKEN=change-me oprow-continuum
```

Non-loopback binds are rejected unless `OPROW_API_TOKEN` is set. The operator
enters that token with the key button; it is retained only in browser session
storage and sent on state-changing requests.

## Judge Flow

1. Connect a supported public GitHub repository or use the pinned FastAPI demo.
2. Paste an agent-generated unified diff containing a repository assumption.
3. Observe `block` for contradicted history, `allow` for verified current
   assumptions, or `abstain` when Oprow lacks sufficient evidence.
4. Inspect immutable CockroachDB receipt citations and the stable review ID.
5. Repeat through `oprow-mcp` to use the same contract from a coding agent.

The review path never edits the repository. Durable history can grow in
CockroachDB while the active hot receipt cache remains bounded. This is not a
claim of infinite information capacity or universal code understanding.

## License

MIT. See [LICENSE](LICENSE).