Phase 1: the neutral session representation and the capture port (ADR-0006) - #23
Merged
Conversation
The representation is the contract everything downstream reads, so a field
named for one agent's internal concept couples the whole program to that
vendor while crossing no import boundary and naming nobody. ADR-0005's guards
cannot see that; this is where it is closed or left open.
Three decisions changed after re-running a measurement the earlier survey had
already collected and never looked at:
- the model belongs to a turn, not a session. 54 of 2,459 local transcripts
used more than one model and 3 used three. The survey gathered models as a
set and checked the size of the working-directory set beside it.
- session identity keeps a parent pointer, which is a measured field rather
than an inference: a record type the survey skipped as bookkeeping carries
it explicitly.
- file changes carry content, because the stream holding it was likewise
skipped, and without it a patch-similarity assertion cannot be computed.
Observability is declared and the declaration is enforced. Nothing else
separates "this did not happen" from "this adapter cannot see it", and
conflating them turns our own blind spot into the model's regression. A
capability governs every field, a test fails if any field is governed by none,
and an adapter reporting something it did not declare fails the shared kit.
Partial observation is its own state: compaction and truncation are ordinary,
and a capability declared whole when it is partial fails an assertion on
evidence that was never complete.
A tool result carries how the call ended rather than whether it failed. A
refused call, a cap hit and a call that never returned are not regressions, and
a boolean cannot say so. The exit code is kept because test runners distinguish
"the tests failed" from "what you named does not exist".
The conformance kit ships a second implementation shaped deliberately unlike
the harness measured first: no turn structure, consecutive agent turns, a model
change mid-stream, delegated work as unreferenced siblings, tokens without
money, pre-split commands, no version control. A merely poorer implementation
would have exercised nothing, since leaving fields empty satisfies any shape.
Sentinel errors are constants of a defined string type. An earlier draft
proposed relaxing ADR-0005's no-package-state rule to allow error vars, which
was unnecessary and would have meant amending an accepted record in passing.
Also records, without correcting, that S2's two published sidecar counts
disagree and the store has grown too much to settle which was right.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ew64uotJqtvVDN3twMAVEQ
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
Capability.MarshalText had no coverage at all, which is the path every committed artifact goes through: names are the only wire form, so a break there reinterprets baselines silently rather than failing. Also covers the out-of-range guards, which would otherwise wrap to an unrelated capability, and the query narrowings that exist so the port did not have to be broken later to add them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ew64uotJqtvVDN3twMAVEQ
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Second of three Phase 1 records. Adds
internal/assay(the harness-neutralsession representation),
internal/port(the capture interface over it), andinternal/adapter/conformance(the shared kit plus a second implementation).The measurement changed the design
Three independent adversarial reviews all pointed at the same gap: the evidence
for several decisions was already on this machine and had never been read. It
was run, and it moved three decisions.
fork-context-refrecords carryparentSessionIdfile-history-snapshot/-deltacarrysnapshot,backup,trackingPathThe first survey had gathered the model set and checked the size of the
working-directory set sitting beside it. The other two record types it had
classified as bookkeeping and skipped.
The part that has teeth
Observability is declared per adapter and the declaration is enforced, not
documented. A capability governs every field; a test fails if any field is
governed by none; an adapter that reports something it did not declare fails
the kit. Both were verified by planting violations:
varin the leaf → rejected, naming the fileSidechainUIDfield onSession→ rejected, naming the field and what to doPartial observation is its own state. Compaction and truncation are ordinary,
and a capability declared whole when it is partial fails an assertion on
evidence that was never complete — the manufactured regression the whole
mechanism exists to prevent.
A tool result carries how the call ended, not whether it "failed". A refused
call, a cap hit, and a call that never returned are not regressions, and one
boolean cannot say so. The exit code is kept because test runners distinguish
"the tests failed" from "what you named does not exist".
The second implementation
Shaped deliberately unlike the harness measured first: no turn structure,
consecutive agent turns, a model change mid-stream, delegated work as
unreferenced siblings, tokens without money, pre-split commands, no version
control. A merely poorer stub would have exercised nothing — leaving fields
empty satisfies any shape, and shape is where single-vendor assumptions hide.
Stated rather than claimed
are flat record streams. Where an adapter draws boundaries determines any
turn-counting metric.
loud rather than hidden behind neutral names.
token-denominated; absolute caps apply where a price is actually reported.
of a second, and a reference written by the same hand. A check, not a proof.
Also records — without correcting — that S2's two published subagent-sidecar
counts disagree and the store has grown too much to settle which was right.
Choosing one of two irreproducible numbers would be worse than saying so.
make verifygreen: coverage 88.1%, 0 lint issues, 0 vulnerabilities.