Skip to content

Phase 1: the neutral session representation and the capture port (ADR-0006) - #23

Merged
JumpTechCode merged 2 commits into
mainfrom
phase1/session-ir
Jul 26, 2026
Merged

Phase 1: the neutral session representation and the capture port (ADR-0006)#23
JumpTechCode merged 2 commits into
mainfrom
phase1/session-ir

Conversation

@JumpTechCode

Copy link
Copy Markdown
Collaborator

Second of three Phase 1 records. Adds internal/assay (the harness-neutral
session representation), internal/port (the capture interface over it), and
internal/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.

Measured Consequence
54 of 2,459 local transcripts used more than one model; 3 used three the model belongs to a turn, not a session
fork-context-ref records carry parentSessionId session lineage keeps a parent pointer, measured rather than inferred
file-history-snapshot/-delta carry snapshot, backup, trackingPath file changes carry content, without which patch-similarity is uncomputable

The 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:

  • a package-level var in the leaf → rejected, naming the file
  • a new SidechainUID field on Session → rejected, naming the field and what to do

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 — 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

  • The turn is a reconstruction. Neither harness examined stores turns; both
    are flat record streams. Where an adapter draws boundaries determines any
    turn-counting metric.
  • Workspace assumes a local filesystem and a content-addressed VCS, said out
    loud rather than hidden behind neutral names.
  • Cost is close to a single-vendor feature. Relative comparisons are
    token-denominated; absolute caps apply where a price is actually reported.
  • Neutrality is not demonstrated here. One measured harness, a paper reading
    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 verify green: coverage 88.1%, 0 lint issues, 0 vulnerabilities.

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

codecov Bot commented Jul 26, 2026

Copy link
Copy Markdown

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
@JumpTechCode
JumpTechCode merged commit 9a9d3f8 into main Jul 26, 2026
5 of 6 checks passed
@JumpTechCode
JumpTechCode deleted the phase1/session-ir branch July 26, 2026 21:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant