Corrections

CorrectionLog

The corrections ledger at ~/.cc-transcript/corrections.db.

Usage

CorrectionLog(engine)

A facade over the native engine. Only an empty database receives the exact v1 schema; every existing schema mismatch is rejected without repair. The opened ledger uses WAL mode and a busy timeout because writers across the family touch the same file concurrently. Durable by convention: rows are never auto-dropped. Requires a local disk — WAL does not work over NFS. The engine bundles its own SQLite, so within this process no other SQLite library may open the same file (see the module docstring).

Example

>>> async with await CorrectionLog.open() as log:
...     await log.append(correction)
...     await log.by_digest(session_id, incorrect_digest=digest)

Methods

Name	Description
append()	Appends `record` as a single `INSERT OR IGNORE`.
by_digest()	Corrections of the tool call with `incorrect_digest` in `session_id`.
close()	Closes the underlying connection; a second close is a no-op.
for_anchor()	The corrections harvested around one feedback `anchor_uuid`.
for_repo()	All corrections whose `detail.repo` is `repo`, ordered by timestamp.
for_session()	All records for `session_id`, ordered by timestamp.
open()	Opens (creating if needed) the ledger at `path`.
since()	Corrections with `ts_ms` strictly greater than `ts_ms`, oldest first.
sql()	Runs one raw SQL `statement` — the escape hatch behind `corrections sql`.

append()

Appends record as a single INSERT OR IGNORE.

Usage

Source

append(record)

Idempotent on the table’s UNIQUE key, so re-running a writer writes one row; SQLite treats NULL key columns as distinct, so rows whose key carries a NULL rely on the writer not repeating the same values.

by_digest()

Corrections of the tool call with incorrect_digest in session_id.

Usage

Source

by_digest(session_id, *, incorrect_digest)

The cross-consumer join: pass the tool_digest a hook recorded in the decisions ledger to learn whether that exact edit was later corrected.

close()

Closes the underlying connection; a second close is a no-op.

Usage

Source

close()

for_anchor()

The corrections harvested around one feedback anchor_uuid.

Usage

Source

for_anchor(session_id, anchor_uuid)

for_repo()

All corrections whose detail.repo is repo, ordered by timestamp.

Usage

Source

for_repo(repo)

The repo key producers stamp into detail so a per-repo consumer (the captain-hook reviewer) can pull every correction for its repo at once.

for_session()

All records for session_id, ordered by timestamp.

Usage

Source

for_session(session_id)

open()

Opens (creating if needed) the ledger at path.

Usage

Source

open(path=None)

Parameters

path: Path | None = None: The database file path; its parents are created if absent. Defaults to the ledger’s file under ~/.cc-transcript.

Returns

Self: The opened log.

since()

Corrections with ts_ms strictly greater than ts_ms, oldest first.

Usage

Source

since(ts_ms, *, source=None)

A cursor read for incremental consumers; pass source to scope to one producer.

sql()

Runs one raw SQL statement — the escape hatch behind corrections sql.

Usage

Source

sql(statement)

Correction

One incorrect edit and the correction that overwrote it.

Usage

Source

Correction(
    ts_ms,
    session_id,
    source,
    anchor_uuid,
    incorrect_digest,
    incorrect_file,
    incorrect_old,
    incorrect_new,
    correction_origin=None,
    correction_file=None,
    correction_old=None,
    correction_new=None,
    correction_commit=None,
    correction_text=None,
    overlap=0.0,
    detail=dict()
)

Attributes

ts_ms: int: Integer-millisecond timestamp of the incorrect edit.
session_id: SessionId: The Claude session UUID the edit fired in.
source: str: The writing system, e.g. cc-steer, captain-hook, cc-review.
anchor_uuid: EventUuid: The transcript uuid of the feedback the harvest anchored on, or review:<reviewID>:<commentID> for a human review correction.
incorrect_digest: ToolDigest | None: The cross-language content digest of the incorrect edit’s tool call — the join key shared with the decisions ledger. None for human review corrections, which join by anchor_uuid.
incorrect_file: str: The file the incorrect edit targeted.
incorrect_old: str: The content the incorrect edit replaced (hunks joined).
incorrect_new: str: The content the incorrect edit wrote (hunks joined).
correction_origin: Origin | None: 'session'/'git' for a mined code fix, 'review' for a human note, or None when no correction was found.
correction_file: str | None: The file the correction touched, when one exists.
correction_old: str | None: The content the correction replaced, when one exists.
correction_new: str | None: The content the correction wrote, when one exists.
correction_commit: str | None: The full commit hash, when the correction is a git fix.
correction_text: str | None: The reviewer’s verbatim natural-language correction, for 'review' rows; None for mined code corrections.
overlap: float: The hunk-overlap score linking incorrect and correction; 0.0 when there is no correction.
detail: Mapping[str, Any]: Structured extras (e.g. repo), serialized to detail_json.

Origin

Origin=Literal["session", "git", "review"]

CORRECTIONS_DDL

CORRECTIONS_DDL=literal_str("corrections.DDL")