alkstore/tasks/core-pin-offset-initial-value.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
core-pin-offset-initial-value	Verify and pin EventReceiver::offset()'s pre-yield value (review 004 item 12)	completed		narrow	low	project	implementation	review-004-fixes core contract verification

Description

The named gap from docs/reviews/004-pre-release-general-review.md §"Findings recorded, not fixed" item 12: EventReceiver::offset() pins the post-yield value only; the pre-yield return (the seeded checkpoint vs 0) is unpinned in core-contract.md's receiver text.

Two steps, in order:

1. Verify the three engines' pre-yield values empirically — the review explicitly did not verify them this session. Probe per engine: a fresh consumer's offset() before any yield, and a consumer with a saved checkpoint's offset() before any yield. The contract suite is the natural home (a three-way equivalence leg, stamped per version_stamp.rs convention); per-engine tests are the acceptable alternative if the suite's harness shape fights the probe — implementer's choice, recorded.
2. Pin the semantics in the contract text — core-contract.md's EventReceiver::offset() paragraph gains the pre-yield return (dated annotation). Doc-only.

If the engines diverge: do NOT paper over with a doc pin — record the divergence precisely (which engine, which arm) and raise with the user; a contract-observable divergence is a fix-the-code-or-amend conversation, not a doc edit.

Acceptance Criteria

• The three engines' pre-yield offset() values verified equal by live runs (the probe/leg recorded; green on all three columns — pg against the harness server)
• core-contract.md's EventReceiver::offset() text pins the pre-yield return with a dated annotation
• If divergent instead: the divergence recorded and raised with the user (this AC replaces the doc pin, not supplements it)
• Doc gate green; any new suite leg green on all three columns

References

• docs/reviews/004-pre-release-general-review.md §"Findings recorded, not fixed" item 12 (the named gap)
• docs/architecture/core-contract.md (the receiver text, the verification backlog)
• alkstore-contract-suite (the three-column harness; the version-stamp convention)

Notes

• The engines were equal — the doc-pin branch applies, not the divergence branch. Read first (all three offset() bodies are self.position, and all three constructors initialize position: 0 unconditionally — mem alkstore-mem/src/stream.rs:353, sqlite alkstore-sqlite/src/stream.rs:399, pg alkstore-postgres/src/stream.rs:620), then verified live by the new suite leg on all three columns: 0 on every pre-yield arm (fresh, positive-checkpoint, negative-seed), no divergence to raise.
• Probe home: the contract suite (the task's first choice) — a new row receiver_offset_pre_yield_is_zero in alkstore-contract-suite/src/properties.rs, wired into all three engines' tests/contract_suite.rs executors. Four arms: fresh consumer, consumer with a stored positive checkpoint, consumer with a stored negative checkpoint (the ADR-023 §2 totality seed — the arm a checkpoint-seeded realization would surface on), and a first-observation composition leg (the attach read prefetches unobserved; the first recv moves offset() to the last-yielded offset). Stamp per the version_stamp convention: ADR-008 §8's EventReceiver shape + the core-contract.md pin (no ADR owns this property's pre-yield arm — the review item is the pin's origin, so the backlog row is the cited pin).
• Doc pin location: the task said "core-contract.md's EventReceiver::offset() paragraph" — no such standalone paragraph exists; the receiver's contract text lives in the streams/ subscribe(consumer) bullet (ADR-008 §8 pins only the shape comment "the receiver's current offset"). The pin landed there (dated annotation), and on offset()'s own trait doc in alkstore/src/event_receiver.rs (core's doc comments are contract text per AGENTS.md; dated the same). ADR-008 §8's shape comment was deliberately left untouched — a doc-only verification task takes no ADR amendment.
• Verification-backlog bullet added (core-contract.md), matching the section's evolved role: the new bullet records the verified pin with the row's name and the all-three-columns result, same posture as the review-004 suite legs before it.
• Frontmatter last_updated extended with the pin (dated), keeping the freeze note intact.

Summary

The pre-yield offset() question closed: all three engines return 0 before any yield regardless of stored checkpoint (positive, negative, or absent) — the no-yield sentinel, composing with the pinned pre-yield save_offset() no-op; the first recv/try_recv observation is the first move. Pinned in three places: the contract text (core-contract.md streams row + verification-backlog bullet, dated 2026-10-11), the core trait doc (event_receiver.rs::offset()), and the suite (new stamped row receiver_offset_pre_yield_is_zero on alkstore-contract-suite). Verified: the new row green on all three columns (pg against the harness server pglo-poc :15432), full pg column green (135+26+9), workspace tests green server-less, clippy -D warnings, cargo fmt --check, doc gate zero warnings, fuzz corpus replay 6/6, wasm32 mem check green. Contract-observation only — no engine code changed, no ADR amendment.