Session Trace Mining

The sixteen gates

schema · ids · layout · provenance · verbatim · no-fabrication · direction · raw-isolation · relations · index · evidence-tier · diff-coverage · unit-normalization · wiki-overlap · pairing-integrity · anonymization

The six that carry the weight:

• provenance — re-resolves the set by name, the file by set-relative path, and every cited line by sha256(raw line)[:12]. Retargeting a citation fails; moving the whole archive to another absolute path still passes. A cited line with no digest is a failure too — without that clause the check silently does nothing, which is what the line-shift injection caught.
• verbatim — implementation.snippet must appear literally in packets/<seg>.diff. The gate and the distiller read the same file on purpose.
• no-fabrication — every number in worth.gain must be in the packet's evidence_text, or derivable from it by one of exactly two closed-form rules (before/after, or speedup=Nx). Derivation from arbitrary pairs of pool numbers is deliberately not allowed.
• unit-normalization — the delta must be reproducible from the measured levels, and no absolute time may appear inside worth.gain.
• wiki-overlap — nothing the committed store already covers: a colliding (operator, version) dedup key, a record id, or an episode_key. It scans kernel_wiki/records, and an empty scan is a failure, not a pass — an overlap gate whose index resolved to nothing would print OK forever.
• anonymization — the served layers must name no person, host or corpus path. Session transcripts are full of /home/<user>/..., and payload is what gets served. The record id is checked separately, because a home path flattened into a slug has no slash left for the path pattern to catch.

Never weaken a gate to make records pass, and never let a distilling agent edit scripts/. When a gate looks wrong, verify by injection: validate_store.py --injection-tests mutates a record (and, where the error lives there, its packet) and asserts that the named gate complains. Adding a gate without an injection test is how a store ends up falsely green — two of the eleven cases here were asleep on their first run.

Distillation

Spawn agents with references/distill-brief.md verbatim, substituting the placeholders. Batch by set and record type so a failure has a small blast radius, and point every agent at the one record that already passes as the worked example.

Require each agent to run validate_store.py itself and iterate to green, and to report which fields the packet was too thin to fill and which gate blocked it. That report is the main signal for improving the pipeline; treat a batch that reports no difficulties with suspicion.

When several agents write into one store concurrently, tell them explicitly to ignore gate failures naming records they do not own.

Porting to another corpus

Everything is corpus-agnostic except two places:

• scripts/config.py SETS — register the set: its path under the archive root, its transcript format, its candidate unit, and default scope. Defaults are fallbacks only; ingest.py detects hardware and DSL and records which happened in arch_basis / dsl_basis.
• scripts/transcripts.py — the only file that knows how a session log is shaped. A third agent product means one new parse_* function returning the same Event stream, plus a branch in detect_format. Everything downstream sees events and never a raw line.

Two corpus-specific details that will need attention on a new corpus: how a long-running benchmark's output is linked back to the command that launched it (in Codex logs it is a SESSION_ID=N handshake), and which label words name a whole implementation rather than a knob (partition.IMPL_LABEL_RE).

Decide the unit before writing any schema. It is what ids, pairing, dedup_key and the whole worth.gain ladder key on, so getting it wrong means re-doing the schema, the packets and three gates. Three probes exist for exactly that decision and should be re-run on a new corpus:

python3 $S/probe_versions.py <transcript> [...]   # per file: versions, edits, metrics, pairing
python3 $S/probe_set.py <set-root>                # does the ladder exist across the set?
python3 $S/probe_ab.py <set-root>                 # if not, how many measured A/Bs are there?

probe_versions.py answers "can I see versions in one file"; probe_set.py answers the question that actually matters for a ladder, since one session is one version; probe_ab.py sizes the fallback. Write the pass bars down before running them, and if a corpus fails its bar, change the unit rather than the bar.

Resources

• references/lessons.md — read before starting. Every pitfall found while building this, with the measured numbers behind each: why one session is one version, why the codex sets cannot be paired before/after, the s-for-seconds trap, the table column that inherited a unit it did not have, and the two gates that were asleep.
• references/distill-brief.md — the agent brief template.
• assets/schema/session-trace-1.0.schema.json — the record schema, generated by make_schema.py from clean-1.3.frozen.json, which is a pinned byte copy of this repository's schema/kernel/schema.json.