PatchDocket

Graph-proven context and test obligations for AI-generated patches.

An AI can produce a plausible diff while missing a distant caller, framework entrypoint, configuration dependency, or test. PatchDocket analyzes a TypeScript repository into a source-backed graph, maps a proposed diff to changed symbols, and returns the context a reviewer must inspect and the tests the patch must pass. Every recommendation includes its graph path. If static analysis cannot support a claim, PatchDocket reports the unsupported change instead.

PatchDocket is a Hack Hydra 2026 project.

Why a graph

Code impact is relational, not merely similar text. PatchDocket records symbols, types, files, entrypoints, configuration reads, and tests as nodes; calls, imports, inheritance, type references, startup/route registration, containment, coverage, and patch changes are typed edges. HydraDB is the durable retrieval engine for native bounded algo.SSpaths reverse traversals from changed symbols. The returned paths are retained as evidence in the patch contract and can be rendered as a deterministic, budgeted context pack for an IDE assistant.

This is meaningful HydraDB usage: ingestion and patch review are separate operations over a persistent graph, and impact is established by traversable relationships rather than a visualization or a hard-coded lookup. POST /v1/repositories/ingest builds the durable graph once; POST /v1/patches/analyze-ingested then reviews a revision-matched patch without rerunning the repository analyzer or re-ingesting graph facts. An ingestion-state marker makes these reads fail closed if replacement is incomplete or the active graph changes during review.

Architecture

TypeScript repository --> deterministic analyzer --> HydraDB property graph
          patch diff --> changed-symbol mapper --> bounded reverse traversal
                                                   |
                                                   v
                                     evidence paths + test obligations
                                                   |
                                                   v
                                      context pack --> IDE assistant
                                            |
                                            v
                                            API --> web review UI

Workspace	Responsibility
packages/analyzer	Repository facts, diff mapping, and conservative static edges
packages/context-pack	Deterministic, source-confined IDE context packs
packages/hydradb	Idempotent graph persistence and bounded impact queries
packages/mcp	Curated PatchDocket tools for MCP-compatible IDE assistants
apps/api	Ingestion, patch-analysis, context-pack, demo, and health endpoints
apps/web	Focused evidence and test-obligation review
evals	Equal-budget retrieval comparisons and real-history measurements
benchmarks/real-world	Pinned, independently verifiable Valibot patch corpus
infra	HydraDB bootstrap and live write/read verification

See ARCHITECTURE.md for system boundaries and docs/GRAPH_SCHEMA.md for the schema and query rationale.

Local setup

Requirements

• Docker Engine with Compose v2
• Node.js 22 or newer for host development
• curl for the HydraDB smoke test
• openssl to generate the local auth token (or set a token explicitly)

The local runtime follows HydraDB OSS's documented single-node requirements: object-store-local mode, pre-created durable and cache directories, file-based auth, a 32 MiB Rust thread stack, and explicit plaintext transport for local development. Ports bind only to 127.0.0.1.

# Creates ignored hydradb-data/{store,cache}, a 0600 auth token, and compose.env.
./infra/bootstrap-hydradb.sh

# Start HydraDB and prove readiness plus an authenticated write/read round trip.
docker compose --env-file hydradb-data/compose.env up -d hydradb
./infra/hydradb-smoke.sh

# Install and run the application on the host.
npm ci
npm run build
npm run start -w @patchproof/api

In another terminal, start the UI in its built-in demo/fallback mode:

npm run dev -w @patchproof/web

Open http://localhost:5173. The API health endpoint is http://localhost:3001/health.

To run the complete containerized stack instead:

docker compose --env-file hydradb-data/compose.env --profile app up --build -d
./infra/patchdocket-smoke.sh

The containerized UI analyzes the bundled checkout fixture through the real API and HydraDB on first load. The app-level smoke script verifies that the response contains changed symbols, graph-backed context, owed tests, and graph metrics. Nginx exposes the API through a same-origin /api proxy, so browsers do not need cross-origin access. API settings are baked at build time; override them only when the browser must reach a different API origin that permits CORS:

VITE_PATCHDOCKET_API_URL=https://patchdocket-api.example \
VITE_PATCHDOCKET_API_MODE=api \
VITE_PATCHDOCKET_ANALYZE_PATH=/v1/patches/analyze \
  docker compose --env-file hydradb-data/compose.env --profile app up --build -d

HydraDB image pin

Compose pins ghcr.io/hydra-db/hydradb@sha256:db78309a233be54662db29744047e985a39b51c45a270d1a1f47c31a62cdb709. On 2026-08-15, docker manifest inspect showed that digest as the official latest OCI index with both linux/amd64 and linux/arm64 images. HydraDB's public repository did not expose a stable release through GitHub's "latest release" endpoint at verification time, so the digest is reproducible but has no confirmed semantic-version label.

If the registry retires that digest, inspect an official tag and override it without editing Compose:

docker buildx imagetools inspect ghcr.io/hydra-db/hydradb:latest
HYDRADB_IMAGE=ghcr.io/hydra-db/hydradb:<verified-tag-or-digest> \
  docker compose --env-file hydradb-data/compose.env up -d hydradb

Do not use an unverified moving tag for a judged or reproduced run.

Demo workflow

1. Ingest the bundled TypeScript repository fixture.
2. Submit its unified diff for analysis.
3. Inspect changed symbols, ranked context, and runnable test obligations.
4. Expand an obligation to verify the source-backed path.
5. Review unsupported changes instead of treating missing evidence as safety.

The timed presentation is in docs/DEMO.md.

IDE context packs

POST /v1/context-pack runs the same live analysis and returns deterministic JSON or Markdown containing changed symbols, ranked snippets, owed test commands, complete graph evidence, unsupported changes, source-resolution status, and a stable SHA-256 ETag. Character and estimated-token budgets are independently bounded. The package also exposes the patchdocket-context-pack CLI.

See docs/CONTEXT_PACK.md for the API, CLI, deterministic hashing contract, and repository-confinement rules.

IDE integration

The stdio MCP server exposes curated health, ingest_repository, analyze_patch, and build_context_pack tools without exposing raw Cypher. It works with MCP-compatible clients including VS Code, Copilot, Cursor, and Claude. See docs/MCP.md for setup and deployment boundaries.

Evaluation

Run the checked-in test and evaluation surfaces:

npm test
npm run typecheck
npm run build
npm run evaluate -w @patchproof/evals

The controlled 12-scenario comparison gives every method 2,000 characters, 500 estimated tokens, and three tests. With the current analyzer, graph retrieval beats lexical file/symbol recall (63.9% / 65.3% versus 61.1% / 62.5%), returns 170/170 valid evidence paths, and reduces disconnected hits from 12.5% to 0%. Hybrid retains the graph result while raising test recall from 70.8% to 75.0%; lexical reaches 93.1% test recall but only 50.0% precision and has no evidence paths.

The separate real-world run analyzes seven exact historical Valibot revisions: four accepted fixes and three documentation/CI negative controls. Graph and hybrid retain 75% affected-file recall and produce 0% negative-control false positives; lexical also reaches 75% recall but retrieves code and tests for 100% of negative controls. Acquisition pins full Git SHAs and the MIT license digest and is reproducible offline after the first fetch.

The matched-budget Pareto report repeats the same comparison at 1,000, 2,000, 4,000, and 8,000 characters. Graph file recall rises from 37.5% to 87.5% as budget grows; lexical reaches 100% at the largest budget but incurs a 62.5% disconnected-hit rate, while graph remains at 0% throughout. Hybrid reaches 100% recall with 0% disconnected hits at 4,000 characters, but rises to 50% disconnected hits when expanded to the 8,000-character budget.

Reports are committed under evals/reports/. Methodology and caveats are in docs/EVALUATION.md, and corpus provenance is in docs/REAL_WORLD_BENCHMARK.md. This README makes no unmeasured throughput, language-compatibility, or correctness claims.

Exact teardown

Stop application containers while preserving the graph:

docker compose --env-file hydradb-data/compose.env --profile app down

The graph remains in hydradb-data/store. To remove only PatchDocket's local HydraDB data, first stop the stack, then delete the named paths explicitly:

rm -rf hydradb-data/store hydradb-data/cache
rm -f hydradb-data/auth-token hydradb-data/compose.env

These commands do not prune Docker globally and do not remove unrelated volumes, images, containers, or directories.

Limitations

• The hackathon MVP analyzes TypeScript repositories only.
• Static analysis is conservative; dynamic imports, reflection, runtime dependency injection, and generated code may be reported as unsupported.
• A graph path is evidence of a dependency, not proof that a patch is correct.
• Traversal depth and result count are bounded, so very deep impacts can be omitted by configuration.
• The local Compose profile is single-node, plaintext, and loopback-only. It is not a production HydraDB deployment.

Attribution and compliance

PatchDocket is an original Hack Hydra 2026 submission built during the event. It uses the open-source HydraDB graph database, distributed separately under AGPL-3.0, through its published container image and documented Bolt/HTTP interfaces. PatchDocket is licensed under Apache-2.0; HydraDB is not vendored or relicensed here.

No hosted service, benchmark result, compatibility guarantee, or HydraDB endorsement is implied. The demo can be reproduced locally from the commands above, and the included evaluation uses checked-in fixtures rather than private data.