overlay M1: the overlay layer contract - a behaviour block on /api/overlay

[lex00]

M1 of #397. The overlay layer contract: GET /api/overlay (src/server.ts:2580) gains a per-entity behaviour block sourced from the lexicon's report.

What

GET /api/overlay today carries the live drift overlay for ?env=. It needs a second, optional block per entity: cost per hour, headroom, an error-rate expectation, a resilience verdict, a right-size hint, and provenance (engine, version, stated tolerance, modeled or validated). The pattern to copy is the carve lens: a peelability score computed once by an advisor, rendered as a colour and a scored overlay, with the runbook lines as copy buttons and no execute button (src/carve-lens.ts:342,375, docs/using/carve.mdx:461-469).

Do

Add the behaviour block to the overlay payload, keyed the same way the drift overlay already keys its entities. Pin the JSON shape with a golden test the way the existing overlay fixtures are pinned. When the lexicon's report has no block for an entity, that entity's overlay carries no behaviour field at all, not a zeroed one.

Proof

A fixture overlay carrying the behaviour block renders the new fields. A fixture overlay without the block renders exactly as today, with nothing invented in its place.

Refs #397.

[lex00]

The behaviour block, proposed (behold #398 ↔ chant #2356)

One shape, pinned in both repos before either builds. behold reads it; chant's lexicon writes it. Every figure is the engine's; behold does arithmetic on engine figures (sums per box and per estate) and labels the arithmetic, and never produces a figure of its own.

Per entity — attrs._behaviour on an overlay IR node

The same channel every other live fact rides on (_status, _release, _carve, _renderDrift): chant graph --live --overlay puts it on the node, keyed by the entity id the drift overlay already keys.

{
  "at": { "traffic": "100 rps, p50" },                 // the stated level the prediction is for — a string the engine names, echoed verbatim
  "cost": { "perHour": 0.0416, "currency": "USD" },
  "headroom": { "cpu": 0.62, "latency": 0.41 },        // fraction of capacity still free, 0..1; a missing axis is absent, not 0
  "errorRate": 0.001,                                  // expected fraction of requests failing at `at`
  "resilience": { "failure": "one zone lost", "verdict": "survives" | "degrades" | "fails", "note": "…" },
  "rightSize": { "suggestion": "t3.small", "reason": "…" },   // optional
  "provenance": {
    "engine": "acme-sim", "version": "1.4.2",
    "tolerance": "±15%",                               // the engine's own stated tolerance, echoed verbatim
    "basis": "modeled" | "validated"                   // list prices vs a bill; "modeled" is the badge's default word
  }
}

Rules: every field except rightSize, resilience.note and either headroom axis is required when the block is present. An entity the engine did not price carries no _behaviour key at all — never a zeroed block. provenance is per entity, not per report, because one estate can be priced by two engines.

Per graph — meta._behaviour on the overlay IR

{
  "engine": "acme-sim", "version": "1.4.2", "at": { "traffic": "100 rps, p50" },
  "total": { "perHour": 12.31, "currency": "USD" },   // optional; when the engine states an estate total behold shows it instead of its own sum
  "refusal": { "reason": "…", "remedy": "…" }        // present INSTEAD of everything above when the engine is configured but unreachable, or not configured at all
}

A refusal drops every behaviour-derived colour and figure; the drift overlay keeps rendering. The refusal text is the lexicon's, in the house style (an env-var chain and the variable it wants), and behold prints it as it came.

The same shape as a document — behaviour.<env>.json

The lexicon's written report (chant #2358's artifact) and every test fixture: { "meta": <meta._behaviour>, "entities": { "<entity id>": <attrs._behaviour>, … } }. behold reads it from a member's root only when the member's overlay carries no _behaviour on any node — a fixture path for demos and tests, and the file a CI job would leave behind — and joins by entity id. A member with neither draws no behaviour modes and says which file or lexicon would supply them.

What behold draws from it

• colour-by cost: a sequential scale over cost.perHour across the entities that carry one; colour-by headroom: the lower of the axes present; an entity without a block draws the drift overlay's neutral, never the zero end of the scale.
• totals: per box and per estate, Σ cost.perHour over the entities with a figure, labelled n priced · m unpriced; meta.total wins when present.
• the badge: {engine} {version} · {tolerance} · {basis} on every figure, "modeled" by default.
• the refusal: the drift overlay stays, the behaviour modes are disabled, the reason and remedy are printed where the legend would be.

What is deliberately NOT here: any unit but per-hour and a fraction, any currency conversion, any default traffic level, any derived score. Those are the engine's.

[lex00]

Merged in #405 (3de03c9), released in @intentius/behold@0.18.0. The block shape it implements is the comment on #398 and chant#2356.