Specifies storage, interfaces, validation, access, freshness, monitoring, and failure behavior for time comparison semantics, so adopters can make phrases such as changed, grew, last month, and year over year resolve to explicit comparable periods and calcu...
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
For Time comparison semantics, implement the semantic contract through owned, typed boundaries so adopters can make phrases such as changed, grew, last month, and year over year resolve to explicit comparable periods and calculations. The comparison contract defines period selection and arithmetic; it does not claim causality or repair incomparable data automatically. This is a reference contract: database products, numeric budgets, jurisdictions, retention, organizational defaults, and accountable owners remain explicit adoption choices.
Scope
- The Time comparison semantics actors, inputs, outputs, states, versions, and externally visible outcomes needed to make phrases such as changed, grew, last month, and year over year resolve to explicit comparable periods and calculations.
- The role-specific focus of this block: implement the semantic contract through owned, typed boundaries, including primary, cached, asynchronous, export, support, and recovery paths where applicable.
- Adoption-specific configuration, ownership, rollout, evidence retention, and review responsibilities needed to use the contract safely.
Outside this block
- The comparison contract defines period selection and arithmetic; it does not claim causality or repair incomparable data automatically.
- Choosing a universal database, model, renderer, vendor, numeric threshold, retention period, timezone, jurisdiction, or service-level objective.
- Claiming that packaged scenarios ran against a downstream implementation or that this reference grants security, privacy, accessibility, analytical, or legal approval.
Contract
- The implemented Time comparison semantics boundary enforces this rule: Natural-language periods resolve to explicit start, inclusive or exclusive end, timezone, calendar, and as-of time before any metric is queried.
- The implemented Time comparison semantics boundary enforces this rule: A comparison names its mode, such as previous equal-length period, previous calendar period, or prior-year matched period, instead of using an implicit default.
- The implemented Time comparison semantics boundary enforces this rule: Partial current periods compare only with a clearly labeled matched elapsed portion unless the user deliberately requests full-period totals.
- The implemented Time comparison semantics boundary enforces this rule: Responses include current value, comparison value, absolute delta, relative delta when mathematically valid, and the exact period labels used.
- The implemented Time comparison semantics boundary enforces this rule: Division by zero, null populations, missing buckets, late events, daylight-saving transitions, and calendar irregularities follow registered metric rules.
- The implemented Time comparison semantics boundary enforces this rule: A metric-definition change, source break, or access-scope change inside either interval marks the comparison discontinuous and blocks a simple trend claim.
- The implemented Time comparison semantics boundary enforces this rule: The agent asks one concise clarification when phrases such as recently or this season map to materially different valid periods.
- The implemented Time comparison semantics boundary enforces this rule: Visualization and narrative consume the same resolved comparison object so their dates and deltas cannot drift apart.
Implementation guidance
- Store the versioned semantic object separately from database-specific compiled artifacts and presentation-specific documents.
- Validate at ingestion, registry, query, result, and rendering boundaries and keep one normalized representation through downstream steps.
- Roll out additively, compare old and new evidence over frozen fixtures, and keep a reversible migration until consumers adopt the new version.
- Instrument success, rejection, staleness, partial results, version conflicts, and repair without recording sensitive payloads.
Failure handling and safeguards
- For Time comparison semantics, Ambiguous timezone or business-calendar input reaches a clarification state instead of silently using the model or server locale.
- For Time comparison semantics, A relative delta with a zero or unavailable baseline is returned as not applicable with an absolute change where meaningful.
- For Time comparison semantics, Insufficient freshness or incomplete ingestion labels the affected interval and prevents an unqualified improvement or decline statement.
Verification and operations
- For the implementation evidence of Time comparison semantics, replay leap day, month-end, daylight-saving, zero-baseline, partial-day, and late-arriving-event fixtures against the comparison resolver.
- For the implementation evidence of Time comparison semantics, verify that chart labels, KPI deltas, downloadable data, and narrative text use byte-equivalent resolved interval metadata.
- For the implementation evidence of Time comparison semantics, test ambiguous user phrases and confirm the resolver either chooses a documented organizational default or requests clarification.
Adoption assumptions
- The adopting product has authenticated identity, a versioned authorization policy, owned metric definitions, bounded telemetry, and a controlled path for change.
- Names and values in the example are fictional adoption fixtures, not universal defaults, production credentials, performance promises, or business targets.
- Referenced specifications constrain protocol, security, accessibility, or vendor behavior; the adopting team must confirm current applicability before promotion.
The executable-looking examples in this package are fixtures and acceptance contracts. Run the collection validator to check structure and metadata, then translate and execute the scenarios in the target repository before recording implementation evidence.