@itsthelore/proofkeeper 2026.6.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work, excluding
+          those notices that do not pertain to any part of the Derivative
+          Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Tom Ballard and the Lore Proofkeeper contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,10 @@
+Lore Proofkeeper
+Copyright 2026 Tom Ballard and the Lore Proofkeeper contributors
+
+This product is part of the Lore family (https://github.com/itsthelore).
+It is a contract consumer of Lore (RAC): it reads the published
+`rac export --graph` contract and proposes `## Verified By` write-back links
+through human-reviewed pull requests. It does not depend on or embed the Lore
+engine's internals.
+
+Licensed under the Apache License, Version 2.0. See the LICENSE file.

package/README.md

@@ -0,0 +1,207 @@
+# Proofkeeper
+
+<!--
+Banner: add docs/assets/proofkeeper-header-{dark,light}.png, then uncomment.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/itsthelore/proofkeeper/main/docs/assets/proofkeeper-header-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/itsthelore/proofkeeper/main/docs/assets/proofkeeper-header-light.png">
+  <img alt="Proofkeeper — the verification arm of Lore. A BYOK agent that drives your app and proves every capability with a real test." src="https://raw.githubusercontent.com/itsthelore/proofkeeper/main/docs/assets/proofkeeper-header-light.png">
+</picture>
+-->
+
+<p align="center">
+<a href="#quickstart">Quickstart</a> ·
+<a href="#how-it-compares">How it compares</a> ·
+<a href="#how-it-works">How it works</a> ·
+<a href="#write-back">Write-back</a> ·
+<a href="#origin">Origin</a> ·
+<a href="./CHANGELOG.md">Changelog</a>
+</p>
+
+<p align="center">
+<a href="https://github.com/itsthelore/proofkeeper/actions/workflows/ci.yml"><img src="https://github.com/itsthelore/proofkeeper/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+<a href="https://www.npmjs.com/package/@itsthelore/proofkeeper"><img src="https://img.shields.io/npm/v/@itsthelore/proofkeeper" alt="npm"></a>
+<img src="https://img.shields.io/badge/node-%E2%89%A520-blue" alt="Node >= 20">
+<img src="https://img.shields.io/badge/types-TypeScript-blue.svg" alt="TypeScript">
+<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache 2.0"></a>
+</p>
+
+> **rac-core captures what your product should do. Proofkeeper proves it does — a BYOK agent that drives your app and verifies each capability with a real test.**
+
+[Lore (rac-core)](https://github.com/itsthelore/rac-core) keeps your product's capabilities as typed, read-only knowledge — requirements as code. Proofkeeper is the **verification arm** of that corpus: a bring-your-own-model agent that reads the capabilities Lore already records (over the published `rac export --graph` contract), drives your product to exercise each one, compiles the working session into a durable end-to-end test, and proposes linking that test back to the capability it proves. It produces **verification evidence and nothing else** — not code review, not codegen. It is a **contract consumer** of Lore, never an extension of its engine: Lore owns the knowledge; Proofkeeper produces and runs the evidence.
+
+## How it compares
+
+Proofkeeper isn't a record-and-watch tool or an automated reviewer — it turns an agent's exploratory run into a **re-runnable test a human reviews**. The differentiator is the durable artifact: a committed Playwright test plus its replayable trace, gated on fidelity, rather than a watch-once recording or a one-off review pass.
+
+| | Proofkeeper | Record-and-watch (e.g. Devin) | Automated review (e.g. Factory) |
+|---|---|---|---|
+| Output of a verification | committed test **+ replayable trace** | watch-once annotated video | a review pass on the PR |
+| Re-runnable | yes — `npx playwright test` | no | n/a |
+| Flakiness handling | the **fidelity gate** (N green re-runs) | none | n/a |
+| Knowledge write-back | `## Verified By` via PR (ADR-084) | proposes a Skill via PR | AGENTS.md conventions |
+| Model | **bring your own** | bundled | bundled |
+
+## Quickstart
+
+1. **Install** dependencies (Node ≥ 20):
+
+   ```bash
+   npm install && npm run build
+   ```
+
+2. **See what's unverified** in a Lore corpus (shells out to `rac export --graph`, or pass a graph file):
+
+   ```bash
+   proofkeeper coverage --corpus path/to/rac/
+   ```
+
+3. **Scaffold** a config from the same graph (one capability per requirement):
+
+   ```bash
+   proofkeeper init --corpus path/to/rac/ --url http://localhost:3000
+   ```
+
+4. **Verify** a capability end-to-end — drive, compile, fidelity-gate, and (optionally) propose the write-back:
+
+   ```bash
+   ANTHROPIC_API_KEY=… proofkeeper qa --corpus path/to/rac/ --url http://localhost:3000/
+   ```
+
+The bundled Claude adapter is used when `ANTHROPIC_API_KEY` is set; bring any other provider by calling `runQa()` from the library with your own `ModelClient`.
+
+## Install
+
+| Command | Gets you |
+|---|---|
+| `npm install` | the library and the `proofkeeper` CLI |
+| `npx playwright install chromium` | the browser the drive and runner need |
+| `npm i @anthropic-ai/sdk` | the optional reference Claude adapter (BYO-model otherwise) |
+
+Requires Node ≥ 20. Published as `@itsthelore/proofkeeper`; the CLI binary is `proofkeeper`. The model SDK is an **optional** peer dependency — installing Proofkeeper never pulls in a model.
+
+## How it works
+
+<!-- Given a capability Lore records, Proofkeeper drives → compiles → fidelity-gates → runs → proposes. -->
+
+- **Drives** your product the way a developer would — an agent loop with a **browser, a terminal, and HTTP** (ADR-083, ADR-085), using *your* model. It records only what succeeds.
+- **Compiles** that working session into a durable Playwright `.spec.ts` with a deterministic emitter — record and replay agree.
+- **Gates on fidelity** by re-running each emitted test N times and keeping only the green, stable ones. This faithful session→test conversion is the moat.
+- **Runs** the compiled suite fast, emitting a replayable trace per run.
+- **Reports** which Lore capabilities are unverified, and proposes `## Verified By` links back to the corpus through a **human-reviewed pull request** (ADR-065) — never a direct write.
+
+## The boundary
+
+Proofkeeper is a **contract consumer** of Lore, and the boundary is load-bearing:
+
+- **Reads the published contract only.** It consumes `rac export --graph` to learn which capabilities lack a verifying test. It never imports the Lore engine's internals.
+- **Bring-your-own-model.** No model or inference is bundled; the agent runtime lives here, never in the Lore engine.
+- **Write-back is a proposal, never a mutation.** It opens a pull request a human reviews (ADR-065) — it never writes a corpus directly.
+- **Verification only.** Proofkeeper "produces verification evidence and nothing else"; code review and codegen are explicit non-goals, owned by sibling products.
+
+## The coverage signal
+
+A requirement node in `rac export --graph` is a product **capability**; the engine emits a typed `verified_by` edge from a capability to each test that verifies it (an external-target reference, ADR-084). A capability is **unverified** when it has no such edge — a pure, deterministic signal, no browser and no model required.
+
+```bash
+proofkeeper coverage --graph-file graph.json          # from a graph export
+proofkeeper coverage --corpus path/to/rac/ --json     # shell out to rac; machine-readable
+```
+
+Exit codes are a stable contract: `0` everything verified, `1` one or more unverified (gates cleanly in CI), `2` usage error.
+
+## Verify a capability
+
+`proofkeeper qa` (alias `verify`) runs the whole loop behind one command: pick an unverified capability → drive → compile → fidelity → run → optionally propose the write-back. With `--config`, it scopes to a pull request — driving every unverified capability the changed files touch, concurrently and context-isolated, and posting the evidence as a single comment that updates in place.
+
+```bash
+# Verify a specific capability and, when stable, open the write-back PR:
+ANTHROPIC_API_KEY=… GITHUB_TOKEN=… proofkeeper qa \
+  --corpus path/to/rac/ --url http://localhost:3000/ \
+  --capability REQ-CHECKOUT --n 5 \
+  --propose --repo itsthelore/your-corpus --target-path rac/requirements/checkout.md
+```
+
+Pass `--plan` to have the model write a human-readable test plan before driving. The drive has a **browser, a terminal, and HTTP**: `run_command` / `expect_output` / `expect_exit` for CLI capabilities, and `request` / `expect_status` / `expect_json` for API capabilities — a session may interleave all three.
+
+## Write-back
+
+Once a test is stable, Proofkeeper proposes linking it to the capability it verifies by opening a **human-reviewed pull request** against the target's Lore corpus — it never commits the base branch (ADR-065). The `## Verified By` section records bare reference paths (the test and its replayable trace), so the engine's `verified_by` edge targets stay clean. Repository operations go through an injected `RepoGateway`, so there is no hard GitHub dependency.
+
+The PR carries readable evidence — a numbered step summary of the driven flow and a `npx playwright show-trace` hint — so a reviewer reads what was exercised, then re-runs the committed test to confirm. The merged artifact validates against the real engine, and the new `verified_by` edge flips the capability to verified in `proofkeeper coverage`.
+
+## Bring your own model
+
+Proofkeeper bundles no model — you implement `ModelClient` against your provider, or use the optional reference `ClaudeModelClient` (lazily imports `@anthropic-ai/sdk`).
+
+```ts
+import { AutonomousDriver, CodegenCompiler, PlaywrightRunner, assessFidelity } from "@itsthelore/proofkeeper";
+import { chromium } from "@playwright/test";
+
+const model = {
+  async complete(request) {
+    /* call your LLM with request.transcript and request.tools */
+    return { toolCalls: [/* { name, arguments } */] };
+  },
+};
+
+const page = await (await chromium.launch()).newPage();
+const { session } = await new AutonomousDriver(page, model, {
+  capabilityId: "REQ-VERIFY",
+  title: "verify flips status to verified",
+  startUrl: "http://localhost:3000/",
+  goal: "Click Verify and confirm the status changes to 'verified'.",
+}).drive();
+
+const candidate = await new CodegenCompiler({ outDir: "tests/generated" }).compile(session);
+const verdict = await assessFidelity(new PlaywrightRunner(), candidate, {
+  n: 5,
+  target: { name: "dev", baseURL: "http://localhost:3000/" },
+});
+```
+
+## Failure-learning
+
+When a drive doesn't finish or its compiled test fails the fidelity gate, the run is recorded against the capability through a pluggable `LearningStore`. The next drive of that capability is handed the prior reasons, so the model steers away from the same dead ends. The config's `failureLearning` strategy controls how the catalog is *surfaced* — the default `suggest_in_report` adds a "Known failure modes" section to the scoped-QA PR comment; repo-writing strategies stay behind the propose-only boundary (ADR-065).
+
+## Origin
+
+Proofkeeper is a sibling of **[Lore / RAC](https://github.com/itsthelore/rac-core)**, split out because **verification is a runtime concern, not a knowledge one** — the same reasoning that separated [Wayfinder](https://github.com/itsthelore/wayfinder-router) (prompt-complexity routing) from the engine. Lore records *what* a product should do and serves it read-only; Proofkeeper drives the product to prove it does, and proposes the evidence back through a human-reviewed PR. The two compose over the published `rac export --graph` contract (ADR-063, ADR-083): no engine change is required, and the `verified_by` edge already exists in the engine. Proofkeeper produces and runs the evidence; Lore records it.
+
+> **Naming.** The product is **Proofkeeper**; the display brand is **Lore Proofkeeper** where disambiguation helps. It is unrelated to Epic Games' "Lore" version-control system — different audience, different tool.
+
+## Repository layout
+
+```text
+lore-proofkeeper/
+  src/              the library: coverage read-model, agent drive, session→test
+                    compiler, fidelity gate, runner, and the write-back proposer
+  src/cli.ts        the `proofkeeper` CLI (coverage, init, qa / verify)
+  lore-proofkeeper/ the dogfood corpus — the requirements, designs, and roadmap
+                    that govern Proofkeeper itself (verified by its own tests)
+  tests/            vitest unit tests plus browser-gated e2e (PROOFKEEPER_E2E)
+  examples/         the demo corpus, product page, and generated specs
+  docs/             the build-shape and competitive notes
+```
+
+## Test
+
+```bash
+npm run typecheck   # strict TypeScript
+npm test            # vitest unit tests (fast, hermetic — no browser)
+npm run build       # emit dist/
+
+# Browser-driven end-to-end checks (real Chromium), opt-in:
+npx playwright install chromium
+PROOFKEEPER_E2E=1 npx vitest run tests/runner.integration.test.ts
+```
+
+The default `npm test` is fully hermetic. The browser-driven integration tests are gated behind `PROOFKEEPER_E2E` so they run only when you opt in (and in the CI `e2e` job).
+
+## Project status
+
+Proofkeeper is an early **v0.0.1** prototype, evolving quickly: the full drive → compile → fidelity → run → write-back pipeline works end-to-end against a real corpus graph, and Proofkeeper verifies its own capabilities (`proofkeeper coverage --corpus lore-proofkeeper/` reports them green). Contributions and experiments welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+[Apache-2.0](./LICENSE). Contributions require a DCO sign-off — see [CONTRIBUTING.md](./CONTRIBUTING.md).

package/dist/agent/adapters/claude.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A reference {@link ModelClient} adapter for the Anthropic Claude API.
+ *
+ * Proofkeeper bundles no model (ADR-035, ADR-002) — this adapter is OPTIONAL
+ * and sits behind the `ModelClient` boundary. `@anthropic-ai/sdk` is an
+ * optional peer dependency, imported lazily, so installing Proofkeeper does not
+ * pull in a model SDK. Bring your own provider by implementing `ModelClient`
+ * directly; this adapter is one worked example, not a requirement.
+ *
+ * Defaults to `claude-opus-4-8`. The translation functions are pure and
+ * exported so the request/response mapping is unit-testable without the SDK or
+ * the network.
+ */
+import type { ModelClient, ModelRequest, ModelResponse } from "../model.js";
+/** The model used unless overridden. */
+export declare const DEFAULT_CLAUDE_MODEL = "claude-opus-4-8";
+/** Minimal structural shape of the Anthropic Messages API we depend on. */
+interface AnthropicCreateParams {
+    model: string;
+    max_tokens: number;
+    system?: string;
+    messages: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+    tools?: {
+        name: string;
+        description: string;
+        input_schema: Record<string, unknown>;
+    }[];
+    thinking?: {
+        type: "adaptive";
+    };
+    output_config?: {
+        effort: string;
+    };
+}
+interface AnthropicContentBlock {
+    type: string;
+    text?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+}
+interface AnthropicMessage {
+    stop_reason?: string;
+    content: AnthropicContentBlock[];
+}
+/** The slice of the Anthropic SDK client this adapter calls. */
+export interface AnthropicLike {
+    messages: {
+        create(params: AnthropicCreateParams): Promise<AnthropicMessage>;
+    };
+}
+export interface ClaudeModelClientOptions {
+    /** API key; falls back to the ANTHROPIC_API_KEY environment variable. */
+    apiKey?: string;
+    /** Model id. Defaults to {@link DEFAULT_CLAUDE_MODEL}. */
+    model?: string;
+    /** Output token cap per turn. Defaults to 4096 (tool decisions are small). */
+    maxTokens?: number;
+    /** Enable adaptive thinking. Off by default to keep the text transcript self-contained. */
+    thinking?: boolean;
+    /** Optional effort level (low | medium | high | xhigh | max). */
+    effort?: "low" | "medium" | "high" | "xhigh" | "max";
+    /** Inject a pre-constructed client (or a test double); skips the SDK import. */
+    client?: AnthropicLike;
+}
+/** Split the transcript into the Anthropic `system` string and message turns. */
+export declare function toAnthropicMessages(transcript: ModelRequest["transcript"]): {
+    system?: string;
+    messages: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+};
+/** Map Proofkeeper tool definitions to Anthropic tool definitions. */
+export declare function toAnthropicTools(tools: ModelRequest["tools"]): {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}[];
+/** Reduce an Anthropic response to a {@link ModelResponse}. */
+export declare function fromAnthropicResponse(message: AnthropicMessage): ModelResponse;
+export declare class ClaudeModelClient implements ModelClient {
+    private readonly options;
+    private client;
+    constructor(options?: ClaudeModelClientOptions);
+    /** Lazily construct the SDK client, importing the optional peer dependency. */
+    private getClient;
+    complete(request: ModelRequest): Promise<ModelResponse>;
+}
+export {};
+//# sourceMappingURL=claude.d.ts.map

package/dist/agent/adapters/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../../src/agent/adapters/claude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAEtF,wCAAwC;AACxC,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD,2EAA2E;AAC3E,UAAU,qBAAqB;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAC;IACvF,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC;IAChC,aAAa,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,UAAU,gBAAgB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,qBAAqB,EAAE,CAAC;CAClC;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE;QAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;KAAE,CAAC;CAChF;AAED,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;IACrD,gFAAgF;IAChF,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,GAAG;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7D,CAYA;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,EAAE,CAMhF;AAED,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAY9E;AAED,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,MAAM,CAA4B;gBAE9B,OAAO,GAAE,wBAA6B;IAKlD,+EAA+E;YACjE,SAAS;IAgBjB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;CAgB9D"}

package/dist/agent/adapters/claude.js

@@ -0,0 +1,96 @@
+/**
+ * A reference {@link ModelClient} adapter for the Anthropic Claude API.
+ *
+ * Proofkeeper bundles no model (ADR-035, ADR-002) — this adapter is OPTIONAL
+ * and sits behind the `ModelClient` boundary. `@anthropic-ai/sdk` is an
+ * optional peer dependency, imported lazily, so installing Proofkeeper does not
+ * pull in a model SDK. Bring your own provider by implementing `ModelClient`
+ * directly; this adapter is one worked example, not a requirement.
+ *
+ * Defaults to `claude-opus-4-8`. The translation functions are pure and
+ * exported so the request/response mapping is unit-testable without the SDK or
+ * the network.
+ */
+/** The model used unless overridden. */
+export const DEFAULT_CLAUDE_MODEL = "claude-opus-4-8";
+/** Split the transcript into the Anthropic `system` string and message turns. */
+export function toAnthropicMessages(transcript) {
+    const systemParts = [];
+    const messages = [];
+    for (const turn of transcript) {
+        if (turn.role === "system") {
+            systemParts.push(turn.content);
+        }
+        else {
+            messages.push({ role: turn.role, content: turn.content });
+        }
+    }
+    const system = systemParts.length > 0 ? systemParts.join("\n\n") : undefined;
+    return system === undefined ? { messages } : { system, messages };
+}
+/** Map Proofkeeper tool definitions to Anthropic tool definitions. */
+export function toAnthropicTools(tools) {
+    return tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.inputSchema ?? { type: "object", properties: {} },
+    }));
+}
+/** Reduce an Anthropic response to a {@link ModelResponse}. */
+export function fromAnthropicResponse(message) {
+    const toolCalls = [];
+    const textParts = [];
+    for (const block of message.content) {
+        if (block.type === "tool_use" && block.name) {
+            toolCalls.push({ name: block.name, arguments: block.input ?? {} });
+        }
+        else if (block.type === "text" && block.text) {
+            textParts.push(block.text);
+        }
+    }
+    if (toolCalls.length > 0)
+        return { toolCalls };
+    return { done: textParts.join("\n") };
+}
+export class ClaudeModelClient {
+    options;
+    client;
+    constructor(options = {}) {
+        this.options = options;
+        this.client = options.client;
+    }
+    /** Lazily construct the SDK client, importing the optional peer dependency. */
+    async getClient() {
+        if (this.client)
+            return this.client;
+        let mod;
+        try {
+            mod = (await import("@anthropic-ai/sdk"));
+        }
+        catch {
+            throw new Error("ClaudeModelClient needs the optional peer dependency '@anthropic-ai/sdk'. " +
+                "Install it (`npm install @anthropic-ai/sdk`) or pass your own `client`.");
+        }
+        const Anthropic = mod.default;
+        this.client = new Anthropic({ apiKey: this.options.apiKey });
+        return this.client;
+    }
+    async complete(request) {
+        const client = await this.getClient();
+        const { system, messages } = toAnthropicMessages(request.transcript);
+        const params = {
+            model: this.options.model ?? DEFAULT_CLAUDE_MODEL,
+            max_tokens: this.options.maxTokens ?? 4096,
+            messages,
+            tools: toAnthropicTools(request.tools),
+        };
+        if (system !== undefined)
+            params.system = system;
+        if (this.options.thinking)
+            params.thinking = { type: "adaptive" };
+        if (this.options.effort)
+            params.output_config = { effort: this.options.effort };
+        return fromAnthropicResponse(await client.messages.create(params));
+    }
+}
+//# sourceMappingURL=claude.js.map

package/dist/agent/adapters/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../../src/agent/adapters/claude.ts"],"names":[],"mappings":"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"}