Skip to content

feat(miner-hands): driver-level structured attempt log (JSONL event trace per attempt) #4294

Description

@JSONbored

An append-only, structured event trace of what a CodingAgentDriver (#4262) attempt actually did — start, tool calls/edits, end, error — so the iterate-loop orchestrator (maintainer-only issue #2333) and any post-hoc audit have a record independent of whatever the driver's own transcript format happens to be. Issue #2333's References section names this exact file: packages/gittensory-engine/src/miner/attempt-log.ts. The pure/IO split this repo already uses for its other local ledgers is the precedent to follow: packages/gittensory-miner/lib/governor-ledger.js (real SQLite IO, append-only, "IMMUTABILITY INVARIANT: INSERT + SELECT only") imports normalizeGovernorLedgerEvent from @jsonbored/gittensory-engine (packages/gittensory-engine/src/governor-ledger.ts) for the pure validation/normalization step — the engine package holds the pure event-shape logic, the miner package holds the actual SQLite persistence. packages/gittensory-miner/lib/event-ledger.js is the closer sibling in PURPOSE (a general miner-loop event ledger: discovered_issue, plan_built, plan_step_completed, pr_prepared, …) but has nothing attempt/driver-specific yet, and its module-maintained monotonic seq + UNIQUE(seq) constraint + JSON-round-trip-verified payload serialization is exactly the durability bar this new log needs too.

Deliverables

  • packages/gittensory-engine/src/miner/attempt-log.ts — pure event-shape definitions and a normalizeAttemptLogEvent-style validator, mirroring packages/gittensory-engine/src/governor-ledger.ts's GovernorLedgerEventType/GovernorLedgerEvent/normalizeGovernorLedgerEvent shape (fixed event-type vocabulary, fail-closed on an unknown type, JSON-round-trip-verified payload).
  • A fixed, enumerable vocabulary for attempt-lifecycle event types (attempt started, tool/edit event, attempt succeeded, attempt failed, attempt aborted — exact names TBD) analogous to GOVERNOR_LEDGER_EVENT_TYPES (packages/gittensory-engine/src/governor-ledger.ts:2-7), not a free-text string.
  • The actual persistence layer — decide whether this extends packages/gittensory-miner/lib/event-ledger.js (adding attempt-scoped event types to its existing general vocabulary) or is a new sibling SQLite store parallel to it (a new attempt-log.js mirroring governor-ledger.js's import-the-pure-normalizer-from-engine pattern). Either is defensible; pick one and document why, since event-ledger.js and governor-ledger.js are already very close prior art and a third near-identical local SQLite store with no clear differentiation would be its own kind of drift.
  • A JSONL export/read path (the title specifies "JSONL event trace per attempt") — even if the durable store is SQLite (matching every other local ledger in this package), provide a way to dump one attempt's events as JSONL, since that's the portable format the title commits to and what the driver-authoring guide (a separate issue in this batch) would show as an example.
  • Tests mirroring event-ledger.js's existing bar: monotonic ordering, rejection of a non-JSON-round-trippable payload, and — new to this issue — correct scoping/filtering by attempt id.

References

  • Issue maintainer: local create->score->self-review iterate-loop orchestrator (the control-flow core) #2333's References section — names packages/gittensory-engine/src/miner/attempt-log.ts as the exact expected path
  • packages/gittensory-engine/src/governor-ledger.ts:1-27 (GOVERNOR_LEDGER_EVENT_TYPES, GovernorLedgerEvent, NormalizedGovernorLedgerEvent — the pure normalization shape to mirror)
  • packages/gittensory-miner/lib/governor-ledger.js:1-9 (imports normalizeGovernorLedgerEvent from @jsonbored/gittensory-engine — the exact pure/IO split precedent)
  • packages/gittensory-miner/lib/event-ledger.js:7-13 (immutability invariant), :72-90 (serializePayload's JSON-round-trip verification), :103-145 (monotonic seq + UNIQUE(seq) schema)
  • Depends on feat(miner-hands): define the CodingAgentDriver interface seam #4262 (this batch) for what an "attempt" actually is — the event vocabulary needs to match the driver interface's lifecycle

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.gittensor:priorityMaintainer-selected Gittensor priority — scores a 1.5x multiplier.help wantedExtra attention is needed

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions