@tcpcore1/verifier 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TCPcore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,466 @@
-# Temporary Holding Version
+# @tcpcore1/verifier
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Did the agent's claimed actions follow from the facts it was given?**
+
+`tcpcore verify` reads a session log and a set of typed facts, and answers that question
+action by action. It prints four numbers, the findings behind them, and a Merkle root over
+the session so a report can be pasted into a review and re-checked later.
+
+No account, no server, no model. One command, one report, exit codes a CI job can branch on.
+
+```bash
+npx @tcpcore1/verifier verify examples/one-fabricated.jsonl --facts examples/facts.jsonl
+```
+
+That command runs against a file in this package, and it exits `1` because the second action
+cites a fact that is not in the facts file. There is nothing to prepare, no service to start
+and no capture to make first.
+
+> The package is published as `@tcpcore1/verifier` because that is the scope this
+> workspace owns. The bin is called `tcpcore` and does not change with the scope, so
+> `npx @tcpcore1/verifier …` and a globally installed `tcpcore …` are the same command.
+> **No publish has been performed from this repository.** That is the operator's action.
+>
+> The package has **no runtime dependencies**. The parts of the truth kernel it needs (the
+> Merkle tree, the fact types, `AdversarialVerifier`) are copied into `src/vendor/` at build
+> time by `scripts/bundle-kernel.mjs`, because the kernel is not on npm and a published
+> tarball may not declare a `workspace:` dependency. A parity test asserts the copy produces
+> byte-identical Merkle roots to the kernel; see [The Merkle roots](#the-merkle-roots).
+
+---
+
+## The three examples
+
+`examples/` ships with the package, so all three of these run from a fresh install. Every
+file's first line carries a `_note` saying the session is synthetic - a real agent that does
+not log grounding facts will show more `ungrounded` than grounded, and that is the tool
+working, not the tool failing.
+
+```bash
+# 1. Nothing to find: two actions, both grounded. Exit 0.
+npx @tcpcore1/verifier verify examples/clean-session.jsonl --facts examples/clean-facts.jsonl
+
+# 2. One citation of a fact that does not exist. Exit 1.
+npx @tcpcore1/verifier verify examples/one-fabricated.jsonl --facts examples/facts.jsonl
+
+# 3. A fact in force when it was cited, withdrawn later in the same session. Exit 1.
+npx @tcpcore1/verifier verify examples/mid-session-retraction.jsonl --facts examples/facts.jsonl
+```
+
+The second command prints:
+
+```
+tcpcore verify - examples/one-fabricated.jsonl
+3 fact(s) from examples/facts.jsonl, session example-one-fabricated
+
+  2 actions
+  1 grounded
+  1 fabricated   <- accusations
+  0 retracted
+  0 ungrounded   <- the tool could not adjudicate
+
+fabricated:
+  a2    billing.apply_discount  2026-11-03T09:00:20.000Z
+        cites fact f-annual-discount, which is not in the facts file
+        cites: f-annual-discount (declared)
+
+merkle (tcpcore.merkle.sha256.v1)
+  actions    36bdb02e9721d4350f888f7da5efdb42e711687dce1a28df15ff478ac286c5bd
+  citations  c433fb55f3c8a8df20e9e82771d14fa8c55278c088f01df29d51eb6f872daca0
+
+exit 1 - 1 fabricated: 1 citation(s) of a fact that does not exist
+```
+
+The third prints `1 retracted`, naming `f-refund-window`, and the reason spells out both
+times: _in force at 2026-11-03T09:15:00.000Z and retracted at 2026-11-03T09:30:00.000Z, later
+in the session_. That is the cascade the report exists to make visible.
+
+---
+
+## The two commands a contributor needs
+
+`fixtures/` is the test corpus, not part of the published package: every adapter has a committed
+fixture and a test that pins its mapping, and `fixtures/sessions/langchain.tcpcore.jsonl` is the
+golden output of the `langchain` adapter. The `*.tcpcore.jsonl` names are the fixtures' own and
+predate the versioned format name; the format they contain is `tcpcore.session.v1`.
+
+```bash
+# 1. Verify the committed example: seven actions, and every branch of the report.
+npx tsx src/index.ts verify fixtures/sessions/langchain.tcpcore.jsonl \
+  --facts fixtures/facts/acme.jsonl
+
+# 2. Adapt a framework log into the canonical format, then verify it.
+npx tsx src/index.ts adapt fixtures/claude-code/transcript.jsonl --from claude-code \
+  -o /tmp/session.jsonl
+npx tsx src/index.ts verify /tmp/session.jsonl --facts fixtures/facts/acme.jsonl
+```
+
+The output of the first command is:
+
+```
+  7 actions
+  2 grounded
+  2 fabricated   <- accusations
+  1 retracted
+  2 ungrounded   <- the tool could not adjudicate
+```
+
+then the findings, each naming the fact it contradicts or rests on, then the two roots,
+then `exit 1`.
+
+---
+
+## The headline is four numbers, always
+
+```
+147 actions
+132 grounded
+  4 fabricated     <- accusations
+  0 retracted
+ 11 ungrounded     <- the tool could not adjudicate
+```
+
+Not "4 hallucinations found". A developer who reads **4 fabricated** without **11
+ungrounded** beside it will over-trust the report and under-invest in the logging this tool
+needs in order to see more. `ungrounded` means the tool could not adjudicate the action - the
+log did not say which facts it rested on, or it withheld the result. That number is the
+tool's honesty about its own blind spot, and burying it would make the report look more
+certain than it is.
+
+The four categories:
+
+| Category     | Meaning                                                                                                        | Fails the run?       |
+| ------------ | -------------------------------------------------------------------------------------------------------------- | -------------------- |
+| `grounded`   | Every cited fact exists and was in force when the action happened.                                             | no                   |
+| `fabricated` | A cited fact does not exist in the facts file, **or** the truth kernel contradicted the action's stated claim. | **yes**              |
+| `retracted`  | Every citation exists, but at least one was withdrawn - before the action, or later in the same session.       | **yes**              |
+| `ungrounded` | Nothing to adjudicate: no citation and no supplied facts, or the source log redacted the result.               | only with `--strict` |
+
+`ungrounded` is a fourth bucket rather than a third category of failure, because folding it
+into `grounded` is the "silence is a pass" inversion and folding it into `fabricated` accuses
+the agent of a lie it did not tell.
+
+---
+
+## `tcpcore-v1.jsonl` - the session format (v1)
+
+A session file is named for its format version: **`tcpcore-v1.jsonl`**. The older unversioned
+name `tcpcore.jsonl` is accepted too - the format is identified by the `schema` literal inside
+the file (`"tcpcore.session.v1"`), not by the filename, so both names parse identically. The
+versioned name is the one to write today; `spec/tcpcore-v1.md` is the normative document.
+
+**A v2 will be added**, as `tcpcore-v2.jsonl` with `"schema": "tcpcore.session.v2"`. The
+verifier will accept v1 and v2 **for one major release**, long enough to migrate without a
+flag day; after that, v1 input is refused by name rather than reinterpreted. Until then there
+is no extension mechanism: a new field is a new version, and `args` is the place for anything
+a tool call carries.
+
+One JSON object per line, UTF-8, LF. An optional first line is a header; every other line is
+one action.
+
+```json
+{"type":"session","schema":"tcpcore.session.v1","sessionId":"cc-session-1"}
+{"id":"run_3","action":"billing.read_invoice","ts":"2026-11-03T09:00:10.000Z","args":{"orderId":"O-1","grounding":["f-price-acme"]},"result":{"amount":400},"grounding":["f-price-acme"]}
+```
+
+### Action fields
+
+| Field       | Type        | Required           | Meaning                                                                                                                                |
+| ----------- | ----------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`    | string      | **yes**            | The operation name: `read_file`, `run_tests`, `refund.create`. The claim of having done something.                                     |
+| `ts`        | string      | **yes**            | `YYYY-MM-DDTHH:MM:SS.sssZ`, exactly. The retraction check is a time comparison, so only one spelling is accepted.                      |
+| `args`      | object      | **yes**            | The structured input. An object, because a tool call has named parameters.                                                             |
+| `result`    | any JSON    | **yes**            | What the tool returned. `null`, `""` and `{}` stay distinct: "no output", "empty output" and "empty object" are three different facts. |
+| `grounding` | string[]    | no (`[]`)          | Fact ids this action rests on.                                                                                                         |
+| `id`        | string      | no (`a1`, `a2`, …) | Stable handle used in the report. Must be unique.                                                                                      |
+| `claim`     | object      | no                 | `{subject, predicate, object}`: a structured assertion, adjudicated by the truth kernel.                                               |
+| `agent`     | string      | no                 | Which agent or sub-agent produced it.                                                                                                  |
+| `turn`      | integer ≥ 1 | no                 | Attribution only; never decisive.                                                                                                      |
+
+### Header fields
+
+`type` must be `"session"`; `schema` must be `"tcpcore.session.v1"`; `sessionId` and `agent`
+are optional. A header that is not the first line is refused.
+
+`_note` is optional and is the one field that carries no semantics: a free-form string, allowed
+on the header and nowhere else. No root commits to the header and no verdict reads it, so it
+cannot change a finding - it is how a shipped example states in the file itself that it is
+synthetic. On an action it is still an unknown key, because every action field is hashed and a
+field outside the hash is a field that can be edited without the root noticing.
+
+### Rules, and why each one is a rule
+
+- **Unknown keys are refused**, naming the key and the line. A permissive parser is a silent
+  pass at the format layer: it accepts `"grouding"`, drops it, and reports the agent as
+  ungrounded because of our typo.
+- **Timestamps must not go backwards.** The retraction check compares `ts` against
+  `retractedAt`; a file with no causal order would still produce confident verdicts.
+- **A session with no actions is invalid input (exit 2).** A verification run over nothing is
+  not a pass.
+- **A blank line is skipped** - it carries no information, and hand-edited JSONL collects
+  trailing newlines.
+
+## `facts-v1.jsonl` - the facts format (v1)
+
+```json
+{
+  "id": "f-seat-limit",
+  "subject": "acme",
+  "predicate": "max_seats",
+  "object": "25",
+  "ts": "2026-01-05T00:00:00.000Z",
+  "source": { "name": "Acme master agreement 2026, schedule 2", "quote": "not more than 25 seats" },
+  "factType": "CONSTRAINT"
+}
+```
+
+| Field                            | Required                | Meaning                                                                                                                                                              |
+| -------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                             | **yes**                 | What `grounding` cites. Unique across the file.                                                                                                                      |
+| `subject`, `predicate`, `object` | **yes**                 | The triple the kernel compares.                                                                                                                                      |
+| `ts`                             | **yes**                 | When the fact was recorded, in canonical UTC.                                                                                                                        |
+| `source`                         | no                      | `{name, url?, quote?}`. A bare string is refused: an unquoted, unlinked source is not evidence.                                                                      |
+| `status`                         | no                      | One of the kernel's five. Defaults to **`VERIFIED` when a `source` is present and `ASSERTED` when it is not** - the kernel's own rule, applied rather than invented. |
+| `factType`                       | no                      | One of the six. Defaults to `ASSERTION`, the one type that can never make a claim fail.                                                                              |
+| `retractedAt`                    | iff `status: RETRACTED` | When it was withdrawn. Required, because "withdrawn before the agent acted" and "withdrawn afterwards" are different findings.                                       |
+
+## How a claim is judged
+
+For each action, the citations are the set the agent **declared** (`args.grounding`), or - if
+it declared none - the facts the session had already **supplied** to it, accumulated from
+calls to tools named with `--fact-tool`. Declared citations replace the context rather than
+adding to it: an agent that names its evidence has told us which facts it used, and padding
+that list with everything it ever saw would let one irrelevant fact decide the verdict.
+
+Each citation is judged against the facts file:
+
+| Condition                                | Finding                                                                                             |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| the fact id is not in the facts file     | **fabricated**                                                                                      |
+| `status: RETRACTED`, `retractedAt <= ts` | **retracted** (before the action)                                                                   |
+| `status: RETRACTED`, `retractedAt > ts`  | **retracted** (_cascade_: in force then, withdrawn later in the session)                            |
+| `status: SUPERSEDED`                     | grounded, with a note - the kernel's own rule is that a superseded fact was in force in its version |
+| otherwise                                | grounded                                                                                            |
+
+When an action also carries a `claim`, the fact set is presented to
+`@tcpcore1/truth-kernel`'s `AdversarialVerifier` - reached as a generated copy under
+`src/vendor/truth-kernel/`, for the reason given under [The Merkle roots](#the-merkle-roots) -
+and its verdict is folded in: `CONTRADICTED`
+makes the action **fabricated** and names the fact that decided it, `SILENT` falls back to the
+grounding finding. The comparison rules - normalised text, equal number sets, `CONSTRAINT` and
+`POLICY` checked before support, a `DEFINITION` of non-existence outranking everything,
+retracted facts silent - are the kernel's, not a second copy of them.
+
+An action's category is the worst of its findings, in the order
+`fabricated > retracted > ungrounded > grounded` - the same "a conflict's safe reading is the
+refusal" order the API's verdict gate uses for approvals.
+
+## The Merkle roots
+
+Two roots, both computed by the truth kernel's `corpusRoot` - the same construction that
+commits a published corpus, with its `0x00`/`0x01` domain bytes, sorted leaves and odd-node
+promotion. **This package contains no Merkle implementation of its own**; it hashes records and
+calls the kernel's helper. A second tree would be a divergence waiting to happen, and this
+repository has been bitten by exactly that.
+
+The kernel is not on npm, so "calls the kernel's helper" is delivered as a generated copy:
+`scripts/bundle-kernel.mjs` rewrites `packages/truth-kernel/src/merkle.ts` into
+`src/vendor/truth-kernel/merkle.ts` on every build, and the copy carries a banner naming its
+source and forbidding hand edits. Two tests keep that honest, and they are the reason a copy is
+safe here: `src/__tests__/merkle-parity.test.ts` asserts this package's roots are
+**byte-identical** to the kernel's over empty input, one leaf, two leaves, an odd count,
+unicode content and JSON containing a nested array; and
+`packages/truth-kernel/src/__tests__/merkle-parity.test.ts` makes the same assertion from the
+kernel's side, so a change to the kernel's tree fails the kernel's own suite rather than the
+next build. `src/__tests__/vendor-drift.test.ts` fails if any vendored copy stops being a fresh
+copy of its source.
+
+- **`actions`** commits to every field of every action. This is the tamper-evident one:
+  change one byte of an argument, a result or a citation and the root changes.
+- **`citations`** commits to the _set_ of fact ids the session cites, deduplicated - the value
+  a second party can compare against a fact set they obtained elsewhere.
+
+Because `corpusRoot` sorts its leaves, both roots commit to a multiset and not to line order.
+For citations that is exactly right. For actions it means a file with the same actions and
+the same `ts` values in a different line order shares a root - which is correct, because the
+session's semantics are the (action, ts) pairs.
+
+To use the root as a tamper check, paste it into a review and re-run with it:
+
+```bash
+tcpcore verify session.jsonl --facts facts.jsonl --expect-root <64 hex>
+```
+
+A mismatch exits `1` and prints both roots.
+
+## Exit codes
+
+| Code | Meaning                                                                                                                                                                    |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | Every action grounded, or ungrounded without `--strict`.                                                                                                                   |
+| `1`  | At least one **fabricated**, at least one **retracted**, or the session does not match `--expect-root`.                                                                    |
+| `2`  | Invalid input: unreadable file, bad JSON, schema violation, unknown flag or adapter, duplicate id, a `RETRACTED` fact with no `retractedAt`, or a session with no actions. |
+
+`2` also covers an internal error, deliberately: a crash must never be read as a verdict, and
+a CI job that saw `1` must not have to wonder whether the tool or the agent failed. The message
+says `internal error`, so a human can tell them apart.
+
+`retracted` fails the run because a report that reads green while a cited fact was withdrawn
+mid-session is the exact defect this tool exists to find. `--strict` is the only path on which
+`ungrounded` becomes fatal.
+
+## CLI
+
+```
+tcpcore verify <session.jsonl> --facts <facts.jsonl>
+        [--json] [--out <path>] [--html <path>] [--merkle]
+        [--expect-root <64 hex>] [--strict] [--fact-tool <name>]...
+tcpcore adapt <input|url> --from <adapter> [-o session.jsonl]
+tcpcore adapt --list
+```
+
+- `--json` prints the machine-readable report (schema: `tcpcore.report.v1`).
+- `--out` writes that JSON report to a file; the human summary stays on the terminal.
+- `--html` writes a self-contained page, no JavaScript, no external stylesheet - a report that
+  needs a CDN to render is not evidence.
+- `--merkle` also prints the per-action leaves, in the order the tree sorts them.
+- `--fact-tool` names a tool whose results supply facts. **Repeatable.** The verifier reads
+  fact ids from `{"facts": [{"id": "..."}]}` in that tool's result, and refuses a result it
+  cannot read rather than reporting every later action as ungrounded.
+
+## Adapters
+
+`tcpcore adapt` maps a framework's own log into `tcpcore-v1.jsonl`. Every adapter is a real
+mapping module with a committed fixture and a test, and every row below states **where the
+knowledge of that format came from**. This build ships **eleven** adapters: the five of Wave 0
+and the six of W1.3. **Exactly one of the eleven is `captured`** - the DeepSeek Harness one,
+from a real session store on the machine this was built on. The other ten are `documented`
+against a pinned package, type definition or doc page, named in the row and in
+`fixtures/PROVENANCE.md`. None is `inferred`.
+
+| Adapter                | Format followed                                                                                                                                                             | Provenance                                               | What it cannot express                                                                                                                                                                                                                                    |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `langchain`            | `@langchain/core@1.3.3` `StreamEvent` (`dist/tracers/event_stream.d.ts:42-85`), `astreamEvents` v2                                                                          | **documented** (pinned type definition)                  | A `StreamEvent` has **no timestamp**, so each capture line must carry its own `"at"`; a log without them is refused, never dated with the verifier's clock.                                                                                               |
+| `langgraph`            | `@langchain/langgraph@1.6.0` `streamEvents` v2 (`dist/pregel/types.d.ts:19`, `dist/pregel/index.d.ts:493-498`), `metadata.langgraph_node`                                   | **documented** (pinned type definition)                  | Only `streamEvents` v2 is read. `updates`-mode chunks carry no timestamp and no run id, and the v3 protocol's shape was not verifiable here, so both are refused by name.                                                                                 |
+| `claude-code`          | Claude Code session transcript JSONL (hooks' `transcript_path`; third-party field reference)                                                                                | **documented** (third-party; not re-verified)            | Anthropic does not publish the transcript schema and there was no Claude Code install to capture from. A `tool_use` with no `tool_result` is refused rather than reported as grounded or failed.                                                          |
+| `deepseek-harness`     | DeepSeek Harness v4 session log, verified field by field from a real capture                                                                                                | **captured** (redacted fixture)                          | The on-disk log is multi-frame zstd and Node decompresses only the first frame, so the input must be `zstd -d`'d first; a compressed file is refused rather than partially read.                                                                          |
+| `cursor`               | Cursor agent hooks (`cursor.com/docs/hooks`): generic `preToolUse` / `postToolUse` / `postToolUseFailure` payloads with `tool_name`, `tool_input`, `tool_output`, `isError` | **documented** (`cursor.com/docs/hooks`)                 | Hooks carry no call id, so pairing is by conversation, tool name and order; an unmatched payload **or two outstanding calls to one tool in one conversation** is refused rather than paired by guess. MCP output redaction is described below.            |
+| `openai-assistants`    | Assistants API run steps (`openai@7.47.0`, `resources/beta/threads/runs/steps.d.ts`): `FunctionToolCall.function.{name,arguments,output}`, `created_at` in seconds          | **documented** (pinned type definition)                  | Only function calls. `file_search` carries no arguments and `code_interpreter` carries code, so both are refused; a `null` output means the outputs were never submitted and is refused too.                                                              |
+| `aws-bedrock-agents`   | Trace parts (`@aws-sdk/client-bedrock-agent-runtime@3.1161.0`, `dist-types/models/models_0.d.ts:3595`): `orchestrationTrace.invocationInput` / `.observation`               | **documented** (pinned type definition)                  | Trace parts carry no call id, so pairing is positional **and interleaved invocations are refused** rather than mispaired: a trace it accepts is a trace it could pair. Parameters are name-to-string, so a declared grounding cannot be expressed at all. |
+| `google-vertex-agents` | ADK session events (`google-adk@2.13.0`, `google/adk/events/event.py`): `content.parts[].function_call` / `function_response`                                               | **documented** (pinned wheel source)                     | A call is paired by invocation and function name; two outstanding calls to one function are refused as ambiguous, and a call with no response (a long-running tool) is refused.                                                                           |
+| `microsoft-autogen`    | `autogen_core` structured logging (`autogen-core@0.7.5`, `autogen_core/logging.py:160-199`): `{"type":"ToolCall","tool_name","arguments","result","agent_id"}`              | **documented** (pinned wheel source)                     | The event payload carries **no timestamp**, so every line must carry `ts`/`timestamp`/`asctime`; a line without one is refused rather than dated with the verifier clock.                                                                                 |
+| `crewai`               | Event bus (`crewai 1.15.34`): `ToolUsageStartedEvent` / `ToolUsageFinishedEvent` / `ToolUsageErrorEvent` from `docs.crewai.com` and `lib/crewai/src/crewai/events/`         | **documented** (docs + GitHub source, fetched this wave) | Only the event bus is read - see below. A started tool with no finished event is refused, and a tool-reported `failure` has no representation in the canonical format.                                                                                    |
+| `custom-http`          | Canonical JSONL over a file or an HTTP GET (`spec/tcpcore-v1.md`)                                                                                                           | **documented** (specified by us)                         | It reads canonical records and nothing else: a producer must emit `tcpcore.session.v1` actions itself. A JSON array body is refused, because line framing is part of the format.                                                                          |
+
+Provenance, in one line each: **captured** means a real log from that framework was used;
+**documented** means the format was read from a pinned package, type definition or doc page,
+named in the row; **inferred** means neither was available and the README would say so. No
+adapter in this build is `inferred`.
+
+### CrewAI: the event bus, not `TaskOutput`
+
+CrewAI also exposes `CrewOutput` / `TaskOutput.tools_used[]`, and it is the smaller surface to
+read. It is not used here, because each entry is `{ tool, input, output }` and **`input` is a
+string** - the model's raw tool-call text. A string is not a structured argument set: mapping it
+would mean parsing prose to invent `args`, which is exactly the coercion this format refuses.
+The event bus carries `tool_args` as a dict and the tool's own `output`, so it is the surface
+that already speaks in structured claims. `tool_usage_finished` is the unit mapped (it carries
+`tool_name`, `tool_args`, `started_at` and `output`), and `started_at` is the action's
+timestamp.
+
+### custom-http: the escape hatch
+
+The twelfth framework should not need a twelfth module. `tcpcore adapt <url> --from custom-http`
+performs one HTTP GET (ten-second timeout, 5 MB body cap, non-2xx is invalid input) and reads
+canonical JSONL; a file path works the same way. It is a reader, not a service, and it validates
+through the same parser as a hand-written session, so an unknown key fails with the same message
+it would anywhere else.
+
+### Cursor and redacted MCP output
+
+Cursor's `postToolUse` hook **redacts MCP tool output** for HTTP MCP servers - it receives
+`{"redacted": true}` (with `isError` when known) instead of the result. Sessions that rely on
+MCP therefore report more `ungrounded` actions than grounded. This is a limitation of Cursor's
+logging, not of the verifier: when the log redacts the result, the action is marked
+`ungrounded` rather than `fabricated`, so the report stays honest about what it cannot
+adjudicate.
+
+The reserved result shape `{"redacted": true}` is how that reaches the report: the adapter
+passes the hook's payload through unchanged, and the engine treats an action that would
+otherwise be grounded as ungrounded. A fabricated or retracted citation still wins, because
+those findings come from the grounding, which the log did give us.
+
+### The third-party-hooks question
+
+Cursor's "Third Party Hooks" page documents that Cursor **loads Claude Code hook
+configurations** and maps hook names and response formats. It says nothing about the _input
+payload_ matching Claude Code's. So the conclusion is **configuration compatibility, not
+payload compatibility**: `claude-code.ts` reads a transcript, `cursor.ts` reads hook payloads,
+and they are two independent parsers that share the tool-call mapping in `adapters/tool-call.ts`
+rather than an envelope.
+
+## What this does not prove
+
+- **It does not prove an adapter is right.** Eleven adapters, **one `captured`**, **ten
+  `documented`**, and **no adapter silently guesses**: where a framework's log does not carry
+  what the format needs, the adapter refuses with a message naming the field rather than
+  inventing a value, and where a pairing would be ambiguous - two Bedrock invocations before an
+  observation, two Cursor calls to one tool in one conversation - it refuses the trace instead
+  of pairing it by guess. **A `documented` adapter is a claim about a document, not about your
+  logs**: it was written against a pinned package, type definition or doc page, and if the real
+  format differs the adapter fails on the field rather than mapping around it.
+- **It does not prove the facts are true.** A fact is a typed assertion with a source; a
+  source can be wrong. Verify against a kernel full of `VERIFIED` facts and the report is a
+  statement about well-sourced beliefs, not about reality.
+- **It does not judge whether a citation is apt.** An agent can cite a real, live, irrelevant
+  fact and be reported `grounded`. Detecting that needs semantic entailment, which is unsolved;
+  self-declared citations are marked `declared: true` so a reader can see which claims rest on
+  the agent's own account of its evidence.
+- **It does not extract claims from prose.** Claims and grounding come only from structured
+  fields. An adapter that guessed would manufacture the findings the tool exists to detect.
+- **It does not replay publication history.** The fact set is treated as one corpus in force.
+  "Which version was current at time T" is the kernel's question, and it has its own model for
+  it.
+- **It does not detect a deleted action.** The roots commit to the actions that are in the
+  file. A session with a line removed is a different session with a different root - which is
+  what `--expect-root` is for - but nothing in a single log can prove that nothing was removed
+  before the root was computed.
+- **It does not replace reading the findings.** Four numbers are a summary. The value is in the
+  lines that name the action and the fact.
+- **Plausible-zero detection is not in this build.** The design's W1.4 checks ("claimed zero
+  issues but checked no files", "claimed success but returned an empty result", "claimed to
+  have run tests but never invoked a test tool", "claimed to have read a file but never called
+  read") need semantics this wave does not have. The report carries a `plausibleZero` array,
+  empty, and the registry it will be filled from; a session with no actions is refused
+  outright, which is the plausible-zero rule applied to the session itself.
+
+## Development
+
+```bash
+pnpm --filter @tcpcore1/verifier build       # bundle the kernel, then tsc -> dist
+pnpm --filter @tcpcore1/verifier typecheck
+pnpm --filter @tcpcore1/verifier test        # vitest run --silent
+pnpm --filter @tcpcore1/verifier check:vendor   # is src/vendor a fresh copy of the kernel?
+pnpm --filter @tcpcore1/verifier check:tarball  # pack, extract, refuse a tarball that cannot install
+npx eslint packages/verifier
+```
+
+`build` runs `node scripts/bundle-kernel.mjs` before `tsc`, so `src/vendor/` is rewritten from
+`packages/truth-kernel` and `packages/claim-graph` on every build. Never edit `src/vendor/`: the
+copy is generated, it says so in its header, and `src/__tests__/vendor-drift.test.ts` fails if
+it stops being a fresh copy. `prepublishOnly` runs both checks, so a stale copy or a tarball
+carrying a `workspace:`/`file:` dependency cannot be published.
+
+Adding this package to a checkout needs one `pnpm install`: `@tcpcore1/truth-kernel` is a
+**devDependency** (tests and typecheck import the real kernel; consumers never install it), and
+the workspace link plus the `pnpm-lock.yaml` importer entry have to exist. The lockfile change is
+the operator's - and moving a dependency between `dependencies` and `devDependencies` in
+`package.json` requires regenerating that importer, because CI installs with
+`--frozen-lockfile`.
+
+## Licence
+
+MIT. See [LICENSE](./LICENSE).
+
+Every committed fixture states where its shape came from; see
+[`fixtures/PROVENANCE.md`](./fixtures/PROVENANCE.md).

package/bin/tcpcore.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * `tcpcore` bin shim.
+ *
+ * Deliberately tiny: it resolves the built entry point and, if the package has not
+ * been built, says which command builds it. That failure is the one a developer
+ * hits after `npm i` from a git checkout, and "Cannot find module" is a worse
+ * message than the two lines below.
+ *
+ * Nothing else lives here. Every decision - argv, exit codes, output - belongs in
+ * `src/`, where it is importable and testable. A bin that contains logic is a bin
+ * whose logic cannot be unit-tested.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const entry = join(here, '..', 'dist', 'index.js');
+
+if (!existsSync(entry)) {
+  process.stderr.write(
+    [
+      'tcpcore is not built yet.',
+      '',
+      '  pnpm --filter @tcpcore1/verifier build',
+      '',
+      `Expected: ${entry}`,
+      '',
+    ].join('\n'),
+  );
+  process.exit(2);
+}
+
+await import(pathToFileURL(entry).href);

package/dist/adapters/aws-bedrock-agents.d.ts

@@ -0,0 +1,46 @@
+/**
+ * AWS Bedrock Agents adapter: the `trace` parts of an `InvokeAgent` response, or
+ * `GetAgentTrace` output.
+ *
+ * ## The format, and where it was read
+ *
+ * `@aws-sdk/client-bedrock-agent-runtime@3.1161.0`,
+ * `dist-types/models/models_0.d.ts`:
+ *
+ *   - `TracePart { sessionId?, trace?: Trace, callerChain?, eventTime?: Date,
+ *      collaboratorName?, agentId?, agentAliasId?, agentVersion? }` (line 3595)
+ *   - `Trace` is a tagged union (line 3460); the interesting arm is
+ *     `trace.orchestrationTrace`, itself a union carrying `invocationInput`,
+ *     `observation` or `rationale`.
+ *   - `orchestrationTrace.invocationInput.actionGroupInvocationInput`:
+ *     `{ actionGroupName, verb, apiPath, parameters?: Parameter[], requestBody?, … }`
+ *   - `orchestrationTrace.observation.actionGroupInvocationOutput: { text?, metadata? }`
+ *   - `Parameter { name?, type?, value? }`
+ *
+ * ## Pairing: positional, and refusing to guess
+ *
+ * **The trace parts carry no call id**, so an invocation is paired with the next
+ * `actionGroupInvocationOutput` in file order. Every case where that pairing would be a
+ * guess is a hard error:
+ *
+ *   - an invocation with no following observation (the outcome is unknown);
+ *   - an observation with no preceding invocation (the call is missing);
+ *   - **a second invocation before the first observation** - interleaved calls cannot be
+ *     paired positionally, and a guessed pairing would put one call's output against
+ *     another call's claim *silently*, which is the one failure this package exists to
+ *     find in other people's output and must not produce itself.
+ *
+ * So the contract is narrow and true: **a trace this adapter accepts is a trace it could
+ * pair.** It refuses to verify a trace it would have to guess about.
+ *
+ * ## Events that are not actions
+ *
+ * `rationale` (the agent's reasoning), `modelInvocationInput`/`Output` (prompt
+ * plumbing), `preProcessingTrace`, `postProcessingTrace`, `guardrailTrace` and
+ * `failureTrace` are not mapped. They are not claims about what was done, and turning
+ * a rationale into an action would invent one.
+ */
+import { type Adapter } from './types.js';
+/** The Bedrock Agents adapter. */
+export declare const awsBedrockAgentsAdapter: Adapter;
+//# sourceMappingURL=aws-bedrock-agents.d.ts.map

package/dist/adapters/aws-bedrock-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws-bedrock-agents.d.ts","sourceRoot":"","sources":["../../src/adapters/aws-bedrock-agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAIH,OAAO,EAAyB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AA4BjE,kCAAkC;AAClC,eAAO,MAAM,uBAAuB,EAAE,OA4IrC,CAAC"}