Repository navigation
Description
Summary
In 8.0.0-beta.15, get_reporting_status derives next_expected_at exclusively from obligations already committed to the ledger. Because obligations are only committed after a period closes, the field is omitted for almost the entire life of a normal daily feed — precisely when a consumer most wants to know when its next report is due.
For a P1D period with a PT1H delivery SLA, next_expected_at is non-null only during the one-hour window between period close and the SLA deadline. For the other 23 hours of every day it is None.
Current behavior
adcp/reporting/ledger/status.py:
def _next_expected(
obligations: Sequence[ReportingObligationRecord], *, ledger_as_of: datetime
) -> str | None:
upcoming = [
item.period.expected_at
for item in obligations
if _utc(item.period.expected_at) > _utc(ledger_as_of)
]
return _iso(min(upcoming)) if upcoming else NoneIt is called from one place, the summary view (status.py:207). The periods view does not project it at all.
Since obligations contains only committed records, and a record's expected_at is period.end + delivery_sla, the predicate can only hold inside the SLA window of the most recently closed period. The active configuration's schedule — which fully determines every future boundary — is never consulted.
Reproduction
Two runs against the same store, differing only in schedule, with a live producer worker and a real active configuration:
A) P1D period / PT1H SLA (typical daily feed)
now = 2026-09-16T09:52:49Z
obligations = 3 committed
next_expected_at = None
B) PT1H period / PT1H SLA (period closed 53 min ago, still inside SLA)
now = 2026-09-16T09:52:49Z
obligations = 3 committed
next_expected_at = '2026-09-16T10:00:00Z'
Case A's configuration is active and ongoing: tomorrow's period is unambiguously owed, at a time the schedule already determines. The response simply declines to say so.
Why the current behavior is defensible but not sufficient
get-reporting-status-response.json describes the field as "Next obligation due time for an open scope. Omitted for a closed complete scope." In case A the projection reports scope_closed: true, because every period inside the request's implicit window has elapsed — so omission is schema-consistent.
But core/reporting-obligation.json explicitly permits the more useful reading:
The seller MAY derive future boundaries and
next_expected_atbefore close, but MUST NOT expose an obligation in a ledger snapshot whoseledger_as_ofis at or beforeperiod.end.
The spec separates two things the SDK currently conflates: projecting a future boundary (permitted) and exposing a premature obligation (forbidden). The SDK avoids the second by also giving up the first.
Required behavior
When at least one configuration generation in the selected scope is active at ledger_as_of, derive the next boundary from that configuration's ReportingScheduleSpec and report it, without committing or exposing any obligation for the open period.
next_expected_at = min(
derive_period(cfg.schedule, account_timezone=..., ordinal=next_ordinal_after(ledger_as_of)).expected_at
for cfg in active_configurations
)The existing obligation-derived value should still win when a committed obligation is closer — an overdue-but-inside-SLA period is a nearer truth than a projected boundary.
Acceptance criteria
- For an active
P1D/PT1Hconfiguration,next_expected_atis populated at everyledger_as_of, not only inside the post-close SLA window. - The value equals the earliest
expected_atacross active generations in scope, whether that boundary comes from a committed obligation or a projected future period. - No obligation is committed, leased, or exposed for a period whose
period.endis at or afterledger_as_of;obligation_counts,coverage, and the periods view are unchanged. - A configuration deactivated as of
ledger_as_ofcontributes no future boundary, and a scope with no active generation still omits the field. - Multi-generation scopes with differing schedules report the earliest boundary.
- Every page of one cursor reports an identical
next_expected_at, consistent with the existing snapshot guarantee. - Tests cover mid-period, post-close-inside-SLA, and post-SLA clock positions for a daily schedule.
Adopter impact
Embedded Sales Agent advertises Reliable Reporting Core with a daily UTC snapshot offering (P1D/PT1H), so this is the exact shape that degrades. Our buyer-side consumer cannot ask "when is my next report due?" and receive an answer; it must independently re-derive the cadence from the schedule echoed back in sync_accounts/list_accounts configuration state. That duplicates scheduling logic on the consumer side and makes the seller's own answer the less-authoritative one — the inverse of what a status endpoint should provide.
Related: #1172 (adapter-first service / DX umbrella).
Activity
bokelley commentedon Sep 16, 2026
Triage
Classification: Feature request
Bucket(s): handlers (
get_reporting_statusprojection — nohandlerslabel exists in this repo; noted in run summary)Status: ready-to-implement
Milestone: —
What the experts said:
core/reporting-obligation.json's MAY clause explicitly permits schedule-derived projection without committing any ledger row;min()over obligation-derived and schedule-derived candidates naturally handles the overdue-inside-SLA case; snapshot guarantee is preserved as long asledger_as_of(not wall-clock) is the projection anchor. Pre-existing nit:list_configurations()is not snapshot-bounded, so newly activated configs could appear; this gap predates this fix and is not worsened by it.config.activated_atfalls inside the current period (e.g., activated at 10:15 with an hourly schedule andledger_as_of = 10:30), the seekledger_as_of - duration + 1µsreturns the ordinal for[10:00, 11:00), which the configuration never covers. Fix: usemax(_utc(config.activated_at), _utc(ledger_as_of) - duration + timedelta(microseconds=1))as the seek tofirst_ordinal_after. Also:derive_periodandfirst_ordinal_afterare not in the existing import block and must be added.My take: The fix is spec-consistent and well-scoped. The activated-at floor is the one correctness nuance required — the existing
first_ordinal_afterbinary search is otherwise sound. No public API changes; the wire field gains values where previously absent, which is a strict improvement for consumers.Implementation brief:
src/adcp/reporting/ledger/status.py_next_expectedsignature and body (line 653):derive_period,first_ordinal_after, andiso_duration_to_timedeltato thefrom adcp.reporting.ledger.models import (...)block.iso_duration_to_timedeltais needed by the new body.configurationsto_next_expected;configurationsis already fetched two lines above.pytest tests/(especially any existingtest_status*files);mypy src/;ruff check .P1D/PT1Hschedule (issue AC); plus the code reviewer's added case: config activated mid-period (activated_at = ledger_as_of - 30mwith 1h periods → assertnext_expected_atis the boundary two half-periods out, not one); multi-generation scopes with differing schedules reporting the earliest boundary._next_expectedis internal; the only external change isnext_expected_atbeing non-null more often, which is additive and spec-permitted.Triaged by Claude Code. Session: https://claude.ai/code/session_01VQj4J6VjVwxC3dRTFz7S96
Generated by Claude Code