Module op_log 

Module: op_log

Durable SQLite op-log writer — phase 1 of the operation-scoped drift model (#op-scoped-drift-1, tasks/agent-doc/plan-operation-scoped-drift.md).

Spec

• Persists node-keyed document operations (agent_doc_core::op_log::DocumentOp) tagged with actor + causal (Lamport / session-origin) clock to a derived sqlite database at .agent-doc/op-log.db.
• The durable store owns Lamport assignment: each appended op gets the next monotonic per-document tick, so the log is totally ordered per document. The caller’s clock.lamport is ignored; clock.origin_session is honored.
• Append is idempotent against the most recent op for the same node: a repeated preflight pass over the same uncommitted diff does not duplicate rows or advance the clock.
• The DB is rebuildable derived state; like the archive index it is best effort and may be dropped without losing canonical document history.

Agentic Contracts

• The DB lives under the project root that owns .agent-doc.
• append_ops opens (creating if needed) the DB, ensures the schema, and writes the batch in a single transaction.
• read_ops returns rows for a document in Lamport order for inspection and for the phase-2/3 readers.

Evals

• append_assigns_monotonic_lamport: sequential appends get increasing ticks
• append_is_idempotent_for_repeated_op: re-appending the same op is a no-op
• lamport_is_per_document: independent documents keep independent clocks
• read_ops_returns_lamport_order: rows come back ordered by Lamport tick

Functions

append_ops

Append a batch of ops, assigning a monotonic per-document Lamport tick to each new op. Returns the number of ops actually written (deduped ops are skipped). Best-effort: callers should log and continue on error rather than failing the cycle.

db_path

Path to the derived op-log database for a project root.

read_ops

Read persisted ops for a document in Lamport order (most recent last), capped at limit rows (0 = unlimited).