clock

type Clock ¶

type Clock interface {
	// Now returns ctx's effective-now if bound (clock.WithEffectiveNow),
	// otherwise wall-clock UTC. The ctx-binding shape replaces the
	// per-callsite ClockResolver pattern shipped in earlier ADR-029
	// fixes — ctx propagation gives compositional correctness without
	// every callsite having to remember to resolve.
	Now(ctx context.Context) time.Time
}

Clock provides the current time. The ctx parameter lets callers ride a request-scoped effective-now (a test clock's frozen_time) plumbed via WithEffectiveNow at operator entry points; without one, callers get wall-clock.

Why ctx-aware, not bare Now(): on a clock-pinned billing entity, every business-logic timestamp must be in the test clock's frozen_time domain (Stripe's "no semantic change" guarantee). A bare wall-clock Now() forces every callsite to remember to resolve the pin manually — exactly the leak we hit shipping ADR-029. With a ctx-aware Now(ctx), services bind effective-now once at the operator entry point and every downstream callsite (including stores) inherits automatically.

Callers that legitimately want wall-clock regardless of pinning (cron tick scheduler, webhook delivery timestamps, postgres updated_at columns, audit-log recorded_at) call time.Now().UTC() directly — we don't go through Clock for those, by design.

func Real() Clock

type Fake ¶

type Fake struct {
	// contains filtered or unexported fields
}

Fake is a controllable clock for testing. The bound effective-now from ctx still wins over Fake's `current` field — tests that want to exercise the ctx-binding path can do so without losing Fake's per-test deterministic value.

func NewFake(t time.Time) *Fake

func (c *Fake) Advance(d time.Duration)

func (c *Fake) Now(ctx context.Context) time.Time

func (c *Fake) Set(t time.Time)

type Pin ¶

type Pin struct {
	TenantID       string
	CustomerID     string
	SubscriptionID string
	InvoiceID      string
}

Pin describes which entity to resolve effective-now from. Exactly one of CustomerID / SubscriptionID / InvoiceID must be non-empty; callers pick the most specific id available. TenantID is always required.

type Resolver ¶

type Resolver interface {
	SimForCustomer(ctx context.Context, tenantID, customerID string) (Sim, error)
	SimForSubscription(ctx context.Context, tenantID, subscriptionID string) (Sim, error)
	SimForInvoice(ctx context.Context, tenantID, invoiceID string) (Sim, error)
}

Resolver maps an entity reference to its simulated-time context — the clock it is pinned to and that clock's frozen_time, or a bare wall-clock Sim (TestClockID "") when the entity is not pinned. Used at operator entry points to bind ctx via BindEffectiveNow, and at boundary code paths (Stripe webhook handlers, async workers) where there's no inherited ctx binding.

It returns the instant and the clock id TOGETHER, from one resolution, because they are two halves of one fact: the audit sim axis stamped from a clock id resolved separately from its instant is how you get a row claiming "clock C at wall-clock now" (ADR-090 §5).

Implemented by *billing.Engine. The platform/clock package owns the interface to avoid an import cycle (every domain that needs binding can depend on clock without depending on billing).

type Sim ¶ added in v0.2.0

type Sim struct {
	At          time.Time
	TestClockID string
}

Sim is the SIMULATED-TIME CONTEXT of a code path: which test clock's world it is acting in (TestClockID) and the simulated instant it lands at (At). The halves travel together and are only ever set from one read of the clock — "clock C, at wall-clock now" is a lie, and the audit log it would be stamped into is append-only, so the pairing is enforced by the type rather than by remembering.

TestClockID == "" means "not in any simulation": At is wall-clock, or a bare WithEffectiveNow binding whose clock is not known, and nothing is stamped on the sim axis.

func SimOf(ctx context.Context) (Sim, bool)

func (s Sim) Simulated() bool