日本語 · English

Kairos Language Specification — Appendix A. Firing Layer Profile (the contract for conformant implementations)

Translated from the canonical Japanese appendix spec/60-firing-layer-profile.md. The source_sha above records the source revision; a consistency check flags this page when the Japanese original changes.

This document is an appendix placed in the specification tree; it is not part of the normative text (§1–7). It is a contract, in prose only, that defines what a Kairos-conformant firing layer satisfies.

The language has only definition and evaluation (§1.4); execution and state are the firing layer’s responsibility (§7.8). This document makes that boundary concrete with what was learned from the feedback reports (2026-07 to 2026-10) of a supply-side runtime that put the reference implementation into production.

A.0 What this document is

The language returns a sequence of instants. The firing layer executes that sequence and holds state. This document lets neither side cross that boundary. Conformance has three levels.

The stance of this document.

Reading order: §1.4 Scope → §7.7–7.8 the general form of the division of labor → §4.10 evaluation annotations and the coverage summary → this document.

A.1 The evaluation contract

The boundary with the language is the shape of CliReport. The evaluator may be called through the CLI or embedded, but the vessel handed across is this shape.

The vessel

tz and the evaluation range

Version

The identity key (1.0.9)

When the firing layer has its own evaluator

A.2 Re-evaluation (rolling horizon)

Evaluate a bounded near-future window and re-evaluate it periodically, replacing the result. The language’s determinism is what supports this operation.

The bounded window and determinism

The watermark and missed-fires

Timers and wake-ups

A.3 Firing and idempotency

Firing is at-least-once; duplicates are absorbed by idempotency on the job side. No persistence of the plan is needed.

At-least-once and claim

The idempotency key

Matching instants

No persistence of the plan is required

A.4 Wiring the operational signals

The language returns danger as annotations, the coverage summary, and warnings. The firing layer wires them to monitoring and does not silence them.

Runway → monitoring

Interval annotations → warnings

Supply failure → degraded operation

Warnings

The signal ledger

A.5 Supply

Expressions are static; data is resolved at run time. Supply is fixed once per evaluation.

The static bundle and one resolution per evaluation

asof and covering

The supply path

A.6 Reconciliation (plan vs. actual)

Reconciliation is needed only for side effects that carry meaning. No table on the plan side.

A.7 Observed examples

The language side’s prototype measurements, and values recorded in the feedback reports from the supply side’s runtime (its own evaluator, external supply, delivery of notifications). The supply side’s proper names are withheld, and its values are cited in the frame “according to the supply side’s records”.

The language side’s prototype measurements (2026-07-09)

The supply side’s production values (the conditions: the production environment, one firing per event, not a benchmark)

A.8 Self-declaration of conformance (checklist)

The list to attach when a firing layer calls itself “Kairos-conformant”. Tick every MUST, and for each SHOULD you skip, write which and why.

MUST

  1. Evaluation results are received in the CliReport shape, with points as the identity of instants (A.1)
  2. Errors are received as JSON too, and error.kind decides what happens at boot (A.1)
  3. tz is declared on the definition side and does not depend on the runtime’s default tz (A.1)
  4. The evaluation range is a half-open interval in whole dates (to excluded) (A.1)
  5. Cutting at a time-of-day origin is not done with the evaluation range (A.1)
  6. version is recorded, and sequences are compared before and after a version update (A.1)
  7. uid is not used as a persistent ID (A.1)
  8. An embedded evaluator satisfies verdict identity (including diagnostic wording) and the doctest check (A.1, where applicable)
  9. A bounded window is re-evaluated periodically and replaced, and agreement on the overlapping interval is tested (A.2)
  10. A watermark is kept, unfired instants are enumerated, and none is dropped silently (A.2)
  11. Firing is at-least-once, a claim precedes the side effect, and the ledger has one row per key (event × destination) (A.3)
  12. A missed-fire goes through the same delivery path and the same idempotency key as a normal firing (A.3)
  13. The idempotency key’s components include the identity of the definition (the firing layer’s own record id), the instant (the civil day or the instant itself, by granularity), and asof (and the destination with multiple destinations) (A.3)
  14. The runway is wired to threshold monitoring (A.4)
  15. Intersections of fired instants with annotation intervals are handled (A.4)
  16. The only error.kind that does not stop boot is supply (degraded operation); static and usage stop it (A.4)
  17. “Nothing yet” and “resolution failed” are distinguished by type (A.4)
  18. Supply is a static bundle, one resolution per evaluation, and asof is used for identity comparison only (A.5)
  19. A premise that carries data declares covering and tz (A.5)
  20. Plan-vs-actual reconciliation is deterministic re-evaluation × the idempotency ledger (A.6)
  21. The three times — firing, reservation, completion of sending — are recorded apart (A.6)

The minimal set of conformance tests (SHOULD)

The report template (SHOULD)

A.9 Terms

Term Definition See
firing layer The implementation that interprets the language’s sequence of instants and actually launches, executes, and manages. Outside the language’s scope §1.4, §7.8
rolling horizon The execution model that evaluates a bounded near-future window [today, today+H) and periodically re-materializes and replaces it A.2
materialization Evaluating the definition over the evaluation window and settling the firing plan (missed and next). Runs at boot, daily, and on recovery A.2
watermark The record of how far firing has progressed. Implemented as the previous execution position or a lookback window A.2
missed-fire A firing instant that passed during downtime. Obtained by enumerating from the watermark to now. Goes through the same delivery path as a normal firing A.2, A.3
determinism The same definition, the same range, and the same supply yield the same sequence. next does not change across environments §7.8
at-least-once The guarantee that nothing is dropped. Duplicates are absorbed by idempotency on the job side A.3
idempotent claim Taking a ledger row with the idempotency key before a side effect. Expressed as counts of claimed / delivered. One row per key (event × destination) A.3
idempotency key The key built from the identity of the definition (the firing layer’s own record id), the instant (the civil day or the instant itself, by granularity), and asof (and the destination with multiple destinations) A.3
uid The expression’s fingerprint, computed from position, text, and tz. Not a persistent ID A.1
runway For each source in the coverage summary, the number of days from the evaluation’s to to the end of covering §4.10
interval annotation An annotation interval of out-of-coverage origin. Runs alongside the result and attaches to non-empty results too §4.10
coverage summary For each source referenced: covering, asof, the completion claim, the runway. Not clipped to the evaluation range §4.10
degraded operation The state of booting with an empty plan on a supply resolution failure and retrying at every wake-up A.4
supply error A resolution failure of external; with the CLI --supply, a malformed bundle counts too. A machine-readable subclass (error.kind is supply) ADR-46
legitimate empty An empty table + covering. Materialization succeeds, zero instants, and the runway warning is raised ADR-45
CAP / TTL / H The wake-up period / the supply cache’s expiry / the evaluation horizon. Where a failed refresh still advances the TTL, CAP > TTL is the condition for recovery A.2, A.4
horizon-clip / window-clip The warning for crossing the implementation horizon / the warning for an instant inside the evaluation range moved outside by a stage §7.8, ADR-37
one resolution per evaluation Resolving supply exactly once per evaluation and fixing asof A.5
static bundle The bundle that passes external’s resolved values in the shape dates/instants, covering, asof, labels A.5
reconciliation Matching deterministic re-evaluation against the idempotency ledger. Needed only for side effects that carry meaning A.6
the three times Firing, reservation (claim), and completion of sending. Say which one an observed value is A.6
transcription / following Moving the reference implementation into an evaluator of your own, and tracking the published versions A.1
verdict identity Returning the same verdict (acceptance or rejection), sequence, and diagnostic wording as the reference implementation. No guards of your own A.1
signal ledger The record that keeps operational signals, one record per firing A.4