0101: Let semantic expression cues yield to V3 evidence

Status: accepted (2026-08-22); activation policy superseded by ADR 0102
Scope: product tier (core/semantic, Codec)

Context

Codec can derive operational expressions from Event Ledger V3 facts. A fresh error produces alert, an open input wait produces waiting, and a blocked lifecycle produces blocked. These states are authoritative enough for a deterministic precedence ladder.

The semantic read model from ADR 0097 can distinguish work postures that do not have a single authoritative event. Its phase field already maps planning, verification, and wrapping up onto portrait expressions, but phase should not become an art vocabulary. For example, weighing can describe a choice inside the planning phase without changing the phase itself.

Harnery also supports optional expression files with a required base fallback. This lets a new cue render safely before every portrait pack has matching art.

Alternatives

Expand the phase vocabulary for every pose. Rejected because work stage and visual posture answer different questions. It would make the semantic phase contract depend on Codec’s current artwork.

Let the model choose any Codec expression. Rejected because several expressions represent facts already proven by V3, including blocked lifecycle, typed waits, errors, recovery, compaction, image observation, context pressure, and open subagents. Model synthesis must not compete with those projections.

Send raw prompts, transcripts, commands, and tool output to improve the choice. Rejected because a controlled expression enum does not need private prose. The extra input would widen secret and prompt-injection exposure without proving better classification.

Keep mapping phase directly to expressions. Rejected as the complete solution because it cannot represent a posture such as weighing. It remains a fallback when the model abstains from the dedicated cue.

Decision

The semantic read-model schema moves to version 2, and the request-bound prompt contract moves to version 3. SemanticMeaningV2 adds an optional expression_cue field whose value is one of these controlled presentation states:

focused, curious, deliberating, investigating, building, coordinating, planning, verifying, weighing, or wrapping-up.

The field must use basis=model-synthesis, confidence medium or low, and at least one supplied evidence event ID. Omission means abstention. The enum does not include neutral or any expression that asserts an authoritative wait, blocker, error, recovery, compaction, observation, context, or subagent state.

Codec uses the cue only when the semantic document is accepted and current and the deterministic expression is still neutral. The cue takes precedence over the old phase-to-expression fallback. It carries inferred provenance, the model’s confidence, citations, and the same expiry as the semantic document.

The privacy boundary from ADR 0097 remains. The evidence builder refuses raw prompts, transcripts, command and tool bodies, paths, URLs, environment assignments, and secret-shaped text. Model-produced prose passes the same outbound validation before persistence. The expression cue itself is a closed enum, so it cannot carry private text.

Harnery cuts rebuildable state over to .harnery/semantic/v2/. It does not read or migrate V1 agent documents and caches. The service remains explicit-start.

Result

The V2 contract, prompt, validator, cache identity, storage path, Codec merge, and evidence receipt shipped together. Contract tests reject unknown cues, high confidence, missing citations, and authoritative expressions. Codec tests prove that weighing fills a neutral panel, phase remains the fallback when the reader abstains, event-backed expressions retain precedence, and a stale cue cannot change the portrait.

The focused semantic suite passes 27 tests, and the full Codec library suite passes 128 tests. TypeScript typecheck passes. Controlled requests through the three production adapters all returned an accepted planning cue at medium confidence. The probe also found two gaps before dogfood: field basis rules had to be expressed in the response schema, and replies had to be bound to the request’s exact generation ID and evidence digest. Both constraints now apply before persistence. The service stayed explicit-start during the measured expression cohort.

Cohort and activation result

A fixed 30-state cohort replayed the same bounded V3 evidence through all three production adapters. The 90 first-read outcomes were 78 accepted, 7 invalid, and 5 unavailable. Accepted readers proposed 41 expression cues. Thirty-two repeated the expression already supplied by semantic phase, three were masked by deterministic evidence, and six changed one core expression to another. No cue added an extended expression beyond the phase fallback.

Cue transitions affected 28.6% to 40.0% of comparable consecutive readings. Median adapter latency ranged from 15.20 to 34.89 seconds, and p95 ranged from 19.02 to 45.94 seconds. Raw model replies were not retained; the evidence packet kept only validated meaning, typed failures, measurements, and reply digests.

The service therefore remains explicit-start. Harnery does not start it with Codec, normal startup, or a checked-in opt-in. Broader activation requires a later cohort with nonzero incremental extended cues, less churn, and an operator A/B that shows better task comprehension.

ADR 0102 supersedes this explicit-start policy after the operator chose to run the reader continuously and improve it from live evidence. The cue precedence, privacy filter, validation, and failure fallbacks in this ADR do not change.

Semantic phase still creates useful extended-expression demand when the cue abstains. verifying appeared 12 times and wrapping-up 4 times in the cohort’s upper-bound semantic expression mix. They are the first and second semantic art priorities after the required portrait tier. planning and weighing remain on their declared base fallbacks until later evidence supports a wider commission.