mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
docs(adr): ADR-0010 — E6 session-log miner is BUILD-NATIVE (Closes age-membrane-memory-arch-tz2s.6.1)
E6.0 adopt-vs-build spike, cross-family decided. cass (session search) and cm (procedural memory) stay adopted for their lanes but neither owns the output the membrane needs — deterministic per-inference PROV-O events. The miner's product IS the provenance graph (AgentOps's owned core, ADR-0004), so renting that to cass/cm is the wrong dependency boundary. Build native over the existing cli/internal/parser + the ASSAY --mine-cmd slot; steal cass's incremental-index discipline (stale-usable, skip-consumed, bounded, recover-loud); no langchain. Scopes E6.1 (...6.2): ao provenance mine-session --file --state --json emitting schema-validated tool_call/context_entered/context_missed events with stable idempotent IDs + checksum rollback detection + Claude/Codex fixtures. - docs/adr/ADR-0010-e6-session-log-miner-build-native.md - docs/documentation-index.md (ADR index entry) Closes age-membrane-memory-arch-tz2s.6.1
This commit is contained in:
@@ -0,0 +1,81 @@
|
||||
# ADR-0010: The E6 session-log miner is BUILD-NATIVE — own the PROV-O graph
|
||||
|
||||
> **Status:** Accepted (2026-06-22). Resolves the E6.0 spike
|
||||
> (`age-membrane-memory-arch-tz2s.6.1`). Cross-family decided (Claude + Codex).
|
||||
> Scopes E6.1 (`...6.2`) and constrains E6.TEST (`...6.3`).
|
||||
|
||||
## Context
|
||||
|
||||
E6 mines session JSONL — the raw ore — into **per-inference typed provenance
|
||||
events** (`tool_call`, `context_entered`, `context_missed`) for the membrane.
|
||||
Parsing is expensive, so the miner must be **incremental** (watermark + dedup).
|
||||
The spike question: **adopt** Jeffrey-Emanuel flywheel tools (cass / `cm`) or
|
||||
**build native**? E6.1's stated rule: *steal technique, build native, own the
|
||||
PROV-O graph; no langchain core dep.*
|
||||
|
||||
Verified during the spike:
|
||||
|
||||
- **cass** (`ADOPT-UPSTREAM`) is a *unified TUI **search**/index over agent
|
||||
histories* — it does not emit typed PROV-O provenance events.
|
||||
- **`cm`/cass-memory** (`ADOPT-UPSTREAM`) is *procedural **memory*** (`cm
|
||||
context`) — a learning-loop substrate, not a provenance miner.
|
||||
- **`ms`/meta-skill** turns mined know-how into skill artifacts — *downstream*
|
||||
of mining, not the miner.
|
||||
- **OpenKB port** (`cli/internal/llmwiki`) compiles *sources → wiki artifacts*
|
||||
(summary/concept/entity/index) — a related extraction pattern, but its product
|
||||
is the wiki, not the provenance graph.
|
||||
- The build foundation is **already native**: `cli/internal/parser/parser.go`
|
||||
parses session transcripts into a `ParseResult` (the same parser `ao yield
|
||||
tokens` uses), and `scripts/assay/self-improvement-tick.sh` is the existing
|
||||
bounded ASSAY orchestration with a **pluggable `--mine-cmd`** that "does NOT
|
||||
rebuild any miner."
|
||||
|
||||
## Decision
|
||||
|
||||
**BUILD-NATIVE.** There is no adoption case for cass/`cm` *as the miner*. Neither
|
||||
owns the output AgentOps needs — deterministic per-inference PROV-O events — and
|
||||
the miner's *product is the provenance graph itself*, which is AgentOps's owned
|
||||
core (the membrane's gradient is deterministic provenance, ADR-0004). Renting
|
||||
that core to cass/`cm` creates the wrong dependency boundary. cass and `cm` stay
|
||||
adopted **for their own lanes** (session search, procedural memory).
|
||||
|
||||
- **STEAL (technique, not code):** cass's incremental-index discipline —
|
||||
*stale-is-usable*, *skip consumed input*, *bounded refresh*, *recover loudly*,
|
||||
*never rebuild expensive state unnecessarily*.
|
||||
- **OWN:** the native Go parser extension, the event schema, idempotent event
|
||||
IDs, the PROV-O relation mapping, ledger/write semantics, tests, and gate
|
||||
compatibility. **No langchain core dep.**
|
||||
|
||||
## E6.1 scope (`...6.2`)
|
||||
|
||||
Implement `ao provenance mine-session --file <session.jsonl> --state
|
||||
<state.json> --json` as a native MVP over `cli/internal/parser`:
|
||||
|
||||
- Emit schema-validated JSONL events for `tool_call`, `context_entered`,
|
||||
`context_missed` **only** when deterministically evidenced by the
|
||||
transcript/tool output (no inference of un-evidenced "missed context").
|
||||
- Stable event IDs keyed by `session / source-line / kind / tool identity` (so
|
||||
reruns are idempotent).
|
||||
- Incremental state with last-line/size/checksum **rollback detection** (a
|
||||
truncated/rewritten transcript re-mines cleanly).
|
||||
- Fixtures for **Claude and Codex** tool-call shapes; tests proving **idempotent
|
||||
reruns** and **append-only incremental mining**.
|
||||
|
||||
## Consequences
|
||||
|
||||
- E6.TEST (`...6.3`) asserts: skips consumed, dedups, emits typed edges.
|
||||
- ASSAY wires `mine-session` as a possible `--mine-cmd`; ASSAY policy is otherwise
|
||||
unchanged.
|
||||
|
||||
## Deferred
|
||||
|
||||
cass/`cm` integration into the miner; semantic/vector inference of missed
|
||||
context; cross-session clustering; TUI/search UX; memory promotion; meta-skill
|
||||
generation; broad graph visualization.
|
||||
|
||||
## What would reverse this
|
||||
|
||||
A structured, deterministic per-inference provenance **export** appearing in
|
||||
cass/`cm` upstream (tool-call + context events with stable IDs) that we'd be
|
||||
foolish to re-implement — at which point re-evaluate adopt-the-export while still
|
||||
owning the PROV-O relation mapping + ledger semantics.
|
||||
@@ -73,6 +73,7 @@ Bridge / framing docs:
|
||||
- [ADR-0007: Deterministic /evolve Loop — Only the Operator Stops It](adr/ADR-0007-deterministic-loop-only-operator-stops.md) — Mechanical pre-cycle gate (`scripts/evolve/halt-check.sh`): operator-only markers, goal-regression halt, revert-on-red; ported from the mt-olympus unbounded-evolve substrate
|
||||
- [ADR-0008: /evolve Operating Model — Intelligent-Agile, Not Waterfall](adr/ADR-0008-evolve-intelligent-agile-operating-model.md) — Three-layer loop contract (intent re-read each cycle / locked architecture / bounded shaping authority) + the scope-precondition audit that prevents building-the-wrong-thing drift
|
||||
- [ADR-0009: Delete the Daemon — AgentOps Is In-Session Only](adr/ADR-0009-daemon-deletion-in-session-only.md) — Why the standalone daemon/scheduler/overnight-runner was deleted (not deprecated): AgentOps is a Gas City reference config with no core to protect, the in-session loop is the zero-dependency sovereignty floor, always-on opts into Gas City; names the rejected deprecate-keep-standalone alternative and the e2e-proof GC dispatch gap
|
||||
- [ADR-0010: E6 Session-Log Miner Is Build-Native](adr/ADR-0010-e6-session-log-miner-build-native.md) — The E6.0 spike decision (cross-family): build the session-JSONL→typed-PROV-O miner native over `cli/internal/parser` + the ASSAY `--mine-cmd` slot; cass/`cm` stay adopted for search/memory only (neither owns the provenance graph). Steals cass's incremental-index discipline; no langchain core dep; scopes `ao provenance mine-session` (E6.1/`...6.2`)
|
||||
- [PDC Framework](architecture/pdc-framework.md) — Prevent, Detect, Correct quality control approach
|
||||
- [FAAFO Alignment](architecture/faafo-alignment.md) — FAAFO promise framework for vibe coding value
|
||||
- [Failure Patterns](architecture/failure-patterns.md) — The 12 failure patterns reference guide
|
||||
|
||||
Reference in New Issue
Block a user