T-9IXF-build-lease-commit-overridable-commit-date

Status: closed/obsoleted · Impact: medium · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to open/ready before picking up.

Goal

Codify and document the commit_date override on build_lease_commit (in plugin/lib/lease/tree.py) that T-174G-archive-records-closing-timestamp-for-post-mortem-detector introduced. The closing-timestamp fix needed a way for release_to_archive to stamp a real now() commit-time on the archive ref while the rest of the lease-protocol library kept the deterministic-epoch default for reproducibility. The override now exists, but the API contract (when to pass it, what it means, why most callers should not) is implicit. This task makes the override an intentional, tested, documented part of the lease-protocol library so future bug fixes in this area don’t accidentally break reproducibility for the callers that depend on the epoch default.

Today

Location	Role today
`plugin/lib/lease/tree.py` (`build_lease_commit`)	Now accepts an optional `commit_date` parameter; defaults to the deterministic epoch when omitted. The parameter is undocumented and untested as a public contract.
`plugin/lib/lease/runtime.py` (`release_to_archive`)	The only caller currently passing `commit_date=now()`. Implicit dependency on the parameter shape.
Other `build_lease_commit` callers (acquire, replace, etc.)	Rely on the epoch default for reproducibility; CAS proofs and ref-existence assertions depend on identical commit bytes across operator machines.

Empirical evidence: the closing-timestamp task hit this gap mid-implementation — the spec said “modify runtime.py only” but the actual fix required threading a parameter through tree.py. The reach was unsurprising in retrospect but invisible at scoping time.

Proposed

build_lease_commit’s commit_date parameter is part of the public lease-protocol API with documented semantics: pass None (or omit) for the deterministic-epoch default; pass a datetime for live-clock commits where the commit time itself is observable downstream (e.g. the archive ref’s commit time IS the close-out marker). Tests pin both behaviors. The lease-protocol convention doc (or the function’s docstring) calls out the rule “default to the epoch unless the commit time is a load-bearing observation”.

Approach

Add a module-level docstring section in tree.py (or a short note in plugin/conventions/lease-protocol.md if that’s where the protocol contract lives) describing the commit_date parameter, when to use it, and why the default is the epoch.
Add explicit type annotations on build_lease_commit’s signature (commit_date: datetime | None = None).
Add pytest cases: (a) default invocation produces a byte-identical commit object across two calls (reproducibility guard); (b) explicit commit_date produces a commit whose %ct matches within tolerance.
Audit existing callers (acquire, replace, etc.) to confirm none accidentally rely on commit_date being settable to anything other than None. Add a smoke test that calls each via its public path and verifies the resulting commit’s timestamp is the epoch.

Files to touch

Location	Kind	Change
`plugin/lib/lease/tree.py`	modify	Document `commit_date` parameter; tighten type annotation.
`plugin/lib/lease/tests/test_tree.py`	modify	Add reproducibility-guard test and explicit-`commit_date` test.
`plugin/conventions/lease-protocol.md`	modify	Add a one-paragraph note on the `commit_date` rule (epoch default; live-clock only when the commit time is the observation).

Acceptance criteria

AC-1: build_lease_commit’s commit_date parameter is documented in the docstring with the rule “default epoch; live-clock only when the commit time is observable downstream”. Verified by reading the file.
AC-2: Two calls to build_lease_commit(payload) (no commit_date) produce byte-identical commit objects. Verified by test_build_lease_commit_default_is_reproducible.
AC-3: A call with commit_date=now() produces a commit whose %ct is within 5s of the call. Verified by test_build_lease_commit_commit_date_lands_in_commit_metadata.
AC-4: All existing tests pass; no caller other than release_to_archive passes a non-None commit_date. Verified by inspection + suite green.

Out of scope

Reworking the lease-commit signature beyond the commit_date parameter.
Making the epoch default configurable.

Dependencies

This task strictly follows T-174G-archive-records-closing-timestamp-for-post-mortem-detector (which introduced the commit_date parameter). It can land any time after that task’s PR merges.

Discovery context

Spawned by /sdlc:task-work post-mortem of T-174G-archive-records-closing-timestamp-for-post-mortem-detector on 2026-05-26.

Dedup search (spawn-from-post-mortem)

Bullet: The build_lease_commit API didn’t previously support overriding commit_date; it always used the deterministic epoch for reproducibility. The fix needed a commit_date parameter so the closing commit’s timestamp could be now() (which is the whole point of this task). Touching tree.py was implicit broader scope than the spec’s ‘modify runtime.py only’ — worth surfacing because future bug fixes in this area may also need similar reach. Keywords searched: build_lease_commit, reproducibility, deterministic, commit_date, previously, overriding, parameter, timestamp Excluded: 2026-05-26-archive-records-closing-timestamp-for-post-mortem-detector Top candidates (score / status / headline):

17 / closed/done / 2026-05-21-pr-check-cursor-bootstrap-misses-existing-comments — pr-check cursor: pin bootstrap behavior and filter self-posted orchestrator comments
16 / closed/done / 2026-05-23-add-lease-protocol-library-and-schemas — Add lease-protocol library and payload schemas
12 / closed/done / 2026-05-17-add-astro-docs-site — Bootstrap Astro Starlight docs site and /dev-update-docs skill
7 / closed/done / 2026-05-24-task-work-lease-integration-model-b — Convert /sdlc:task-work to lease-aware Model B (exit at PR open)
6 / closed/done / 2026-05-19-task-work-uses-per-project-quality-checks — Make /sdlc:task-work quality-check commands per-project configurable Decision: SPAWNED

← Back to Tasks