@kairos-es/codec 1.0.0-alpha.0 → 1.0.0-alpha.2

package/src/decider.ts

@@ -52,20 +52,36 @@
  * boundary, and decode may fail with `CodecError`. All surface on the error
  * channel, so a caller handles all three the same way — and
  * `@kairos-es/testing`'s `.thenError(tag)` can assert any of them.
+ *
+ * `decide` may also answer `Unchanged` — "already done, nothing to append" — but
+ * only where its type says so: `Decider`'s fifth type parameter `O` defaults to
+ * the non-empty batch, and `runDecider` returns `DecisionResult<O>`, which is
+ * plain `Position` unless `O` admits `Unchanged`. So a decider that cannot say
+ * "already done" keeps exactly the result type it always had — an untyped one
+ * and one built in a wrapper generic in its success type included — and one
+ * that can makes its caller handle `Position | Unchanged`. `runDecider` returns an
+ * `Unchanged` without calling `append`, so `append`'s refusal of an empty batch
+ * is untouched and never met. `decision.ts` owns why it is a success rather than
+ * an error or an empty batch, and why it is recognised by a type id.
  */
 
 import type {
   AppendConditionFailed,
   CompositeState,
   DcbEvent,
-  Position,
 } from '@kairos-es/core'
 import { DcbEventStore } from '@kairos-es/core'
 import type { Array as Arr } from 'effect'
 import { Effect } from 'effect'
+import {
+  type DecisionOutput,
+  type DecisionResult,
+  isUnchanged,
+} from './decision'
 import { buildDecisionModel, type RequirementOf } from './decisionModel'
 import type { CodecError } from './errors'
 import type { SliceProjection } from './projection'
+import type { TaglessSliceInLedger } from './readLedger'
 import type { Serializer } from './Serializer'
 import type { Uuid } from './Uuid'
 
@@ -83,22 +99,26 @@ import type { Uuid } from './Uuid'
  * schema-backed, state-erased bound for a heterogeneous record); the
  * precise per-key state is recovered by core's shared `CompositeState`. The
  * requirement `R` is the union carried by the record's slices' schemas.
+ *
+ * `O` is what `decide` may succeed with. It defaults to the non-empty batch, and
+ * a decider that can answer "already done" widens it to `DecisionOutput`
+ * (`NonEmptyReadonlyArray<DcbEvent> | Unchanged`). It is LAST and DEFAULTED so
+ * that every `Decider<P, Command, E, R>` already written means exactly what it
+ * meant. Its bound is `DecisionOutput`, which still excludes a possibly-empty
+ * array — the widening adds an answer and removes no guarantee.
  */
 export interface Decider<
   P extends Record<string, SliceProjection>,
   Command,
   E = never,
   R = never,
+  O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>,
 > {
   readonly projections: (command: Command) => P
   readonly decide: (
     state: CompositeState<P>,
     command: Command,
-  ) => Effect.Effect<
-    Arr.NonEmptyReadonlyArray<DcbEvent>,
-    E,
-    Serializer | Uuid | R
-  >
+  ) => Effect.Effect<O, E, Serializer | Uuid | R>
 }
 
 /**
@@ -148,6 +168,22 @@ export interface Decider<
  * Effect.Error<Eff>, …>`. The value is the two functions it was handed, so
  * there is nothing for the cast to be wrong about.
  *
+ * The success channel is how a decider opts into `Unchanged` without writing a
+ * fifth type argument, and it is why this function is declared TWICE. The first
+ * declaration bounds `Eff` by the non-empty batch and returns a `Decider` with
+ * the DEFAULT `O`; the second bounds it by `DecisionOutput` and returns one whose
+ * `O` is `DecisionOutput`. A `decide` with a branch returning
+ * `Decision.unchanged(…)` fails the first bound and lands on the second, and one
+ * with no such branch keeps the default. Either way `O` is one of the two a
+ * caller ever writes, never the inferred success type passed through: inference
+ * is more precise than anyone writes — the produce path's one-element tuple, say
+ * — and a `Decider<…, readonly [DcbEvent]>` would not be the
+ * `Decider<P, Command, E, R>` its caller spells, though it behaves identically.
+ * Asking by ASSIGNABILITY rather than by a conditional over `Eff`'s success is
+ * what keeps an untyped (`any`) success, and a success that is a type variable
+ * bounded by the batch, on the default; `decision.ts` owns that argument, and
+ * the one type query the pair cannot answer as before.
+ *
  * `R` excludes `Serializer | Uuid` because that is what `R` MEANS on `Decider`:
  * the interface writes decide's requirement as `Serializer | Uuid | R`, so `R`
  * is what the produce side needs BEYOND the codec's own two services. Leaving
@@ -159,7 +195,7 @@ export interface Decider<
  * `@kairos-es/codec/Serializer` matches — and a tag under that key IS that
  * service, context being keyed by the same string at runtime.
  */
-export const decider = <
+export function decider<
   P extends Record<string, SliceProjection>,
   Command,
   Eff extends Effect.Effect<
@@ -175,38 +211,74 @@ export const decider = <
   Command,
   Effect.Effect.Error<Eff>,
   Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>
-> =>
-  ({ projections, decide }) as Decider<
+>
+export function decider<
+  P extends Record<string, SliceProjection>,
+  Command,
+  Eff extends Effect.Effect<DecisionOutput, unknown, unknown>,
+>(
+  projections: (command: Command) => P,
+  decide: (state: CompositeState<P>, command: Command) => Eff,
+): Decider<
+  P,
+  Command,
+  Effect.Effect.Error<Eff>,
+  Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>,
+  DecisionOutput
+>
+export function decider<P extends Record<string, SliceProjection>, Command>(
+  projections: (command: Command) => P,
+  decide: (
+    state: CompositeState<P>,
+    command: Command,
+  ) => Effect.Effect<DecisionOutput, unknown, unknown>,
+): Decider<P, Command, unknown, unknown, DecisionOutput> {
+  return { projections, decide } as Decider<
     P,
     Command,
-    Effect.Effect.Error<Eff>,
-    Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>
+    unknown,
+    unknown,
+    DecisionOutput
   >
+}
 
 /**
  * Run the full DCB command cycle for a decider against the ambient
  * `DcbEventStore`: build the decision model (real read + decode + fold), decide,
- * and append under the read's append condition. Returns the last new position.
+ * and append under the read's append condition. Returns the last new position —
+ * or, when `decide` answered `Unchanged`, that `Unchanged`, having appended
+ * nothing. The result type is `DecisionResult<O>`, so it is plain `Position` for
+ * every decider that cannot answer `Unchanged`, including one whose `O` is still
+ * a type variable bounded by the batch. ONE signature, deliberately:
+ * `decision.ts` says why that alias, and not an overload, is what carries it.
  *
  * The requirement is `DcbEventStore | Serializer | Uuid | R |
  * RequirementOf<P>`: `Serializer` enters through both the decode
  * (`buildDecisionModel`) and produce (`toEvent`) sides, `Uuid` through produce,
  * the slices' `RequirementOf<P>` through decode, and `R` through produce. (For a
  * def whose `Schema` carries a requirement, `RequirementOf<P>` and `R` are the
- * same tag.) Any `decide` failure, a decode `CodecError`, or an
- * `AppendConditionFailed` propagates on the error channel unchanged.
+ * same tag.) Any `decide` failure, a decode `CodecError`, an
+ * `AppendConditionFailed`, or the read's own `TaglessSliceInLedger` propagates on
+ * the error channel unchanged.
+ *
+ * ⚠ INSIDE a bracket this function is REFUSED, as a defect, at the store's shared
+ * append decorator, and `decideOnly` is what a body reaches for instead.
+ * `index.ts` states that pair, why each refuses exactly where the other is the
+ * answer, and why neither can be expressed over the other. Read it before
+ * changing either signature; this file does not restate the argument.
  */
 export const runDecider = <
   P extends Record<string, SliceProjection>,
   Command,
   E,
   R,
+  O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>,
 >(
-  decider: Decider<P, Command, E, R>,
+  decider: Decider<P, Command, E, R, O>,
   command: Command,
 ): Effect.Effect<
-  Position,
-  E | CodecError | AppendConditionFailed,
+  DecisionResult<O>,
+  E | CodecError | AppendConditionFailed | TaglessSliceInLedger,
   DcbEventStore | Serializer | Uuid | R | RequirementOf<P>
 > =>
   Effect.gen(function* () {
@@ -214,6 +286,13 @@ export const runDecider = <
     const { state, appendCondition } = yield* buildDecisionModel(
       decider.projections(command),
     )
-    const newEvents = yield* decider.decide(state, command)
-    return yield* store.append(newEvents, appendCondition)
+    const output: DecisionOutput = yield* decider.decide(state, command)
+    // "Already done" never reaches `append`: an empty batch stays a defect there,
+    // and this is not one. The two casts restate `DecisionResult<O>`, which the
+    // checker cannot relate to either branch while `O` is still a type variable;
+    // the branch taken is exactly the one the conditional selects.
+    if (isUnchanged(output)) {
+      return output as DecisionResult<O>
+    }
+    return (yield* store.append(output, appendCondition)) as DecisionResult<O>
   })

package/src/decision.ts

@@ -0,0 +1,174 @@
+/**
+ * `Unchanged`: a decision's answer when there is nothing to do because the work
+ * is already done, and the two types that let a decision say so without costing
+ * any existing caller its `Position`.
+ *
+ * ## Why a decision needs a third answer
+ *
+ * A decision had two answers: a non-empty batch of events to append, or a
+ * failure. The idempotent case fitted neither. A webhook redelivered after its
+ * first delivery was recorded, or a recorder re-running after a conflict whose
+ * winning write already closed the item, has nothing to append — and nothing
+ * WRONG has happened, so a failure is the wrong channel: a caller would have to
+ * tell "already done" from a genuine refusal by matching a tag, and a retry
+ * policy keyed on the error channel would retry a success. An empty batch is not
+ * the answer either. `append` refuses one as a defect, and the `Decider`'s
+ * `NonEmptyReadonlyArray` bound is what makes that refusal unreachable from a
+ * decision, a guarantee `decider.ts` calls load-bearing. So "already done" gets a
+ * value of its own, and it is a SUCCESS: an idempotent skip is never retried.
+ *
+ * ## Why it is recognised by a type id, and never by `instanceof` or a `_tag`
+ *
+ * This package ships dual ESM/CJS, so one consumer's graph can hold two copies of
+ * this module and therefore two distinct `Unchanged` classes. Under `instanceof`,
+ * a value built by one copy fails the other's check, and the runner would treat
+ * "already done" as a batch and hand it to `append` — the same single point of
+ * silent failure `@kairos-es/core` argues against, in its contract store, for
+ * `AppendConditionFailed`. That error falls back on its `_tag`, and a tag is
+ * enough there because the error channel is the library's own. A DECISION's
+ * success channel is not: an application's own union may well carry a member
+ * tagged `'Unchanged'`, and a runner that skipped on the bare tag would swallow
+ * that value and append nothing, silently. `Symbol.for` gives an identity that is
+ * shared across both builds (the global symbol registry is per runtime, not per
+ * module copy) and that no application value carries by accident. `isUnchanged`
+ * is the one test, and every runner in this package uses it.
+ *
+ * ## Why the widening is a defaulted type parameter, not a second entry point
+ *
+ * `Decider` gains a fifth type parameter `O`, defaulting to the non-empty batch.
+ * A second entry point would have meant a second `Decider`, a second runner, a
+ * second `transact` and a second `decideOnly` — against a surface whose whole
+ * argument is that `runDecider` and `decideOnly` are ONE pair.
+ *
+ * ## Why `DecisionResult` is shaped as it is, and why `decider` is overloaded
+ *
+ * The promise is that a decider or body that cannot answer `Unchanged` keeps
+ * exactly the `Position` result it had. Two kinds of success make that harder
+ * than it looks, and both were measured against call shapes that compiled
+ * before the widening.
+ *
+ * - An UNTYPED success. `any` satisfies every question a conditional can ask of
+ *   it: `Unchanged extends any` holds, and `any extends Unchanged` takes BOTH
+ *   branches. So a decision nobody typed would read as one that can answer
+ *   `Unchanged`, and its caller's `(position: Position) => …` would stop
+ *   compiling. `DecisionResult` therefore checks for `any` FIRST, and answers
+ *   `Position`.
+ * - A GENERIC success. In a wrapper generic in the success type
+ *   (`<A extends NonEmptyReadonlyArray<DcbEvent>, …>`), a conditional over `A`
+ *   stays DEFERRED, and a deferred conditional is `Position` only if the checker
+ *   can see that it must be. It can for one shape and not for the other:
+ *   `Unchanged extends O ? …` is related through the union of its two branches,
+ *   which admits `Unchanged`; `O extends Unchanged ? …`, DISTRIBUTIVE over `O`,
+ *   is related through itself instantiated at `O`'s bound — and at a bound of
+ *   the non-empty batch that is `Position`. So `DecisionResult` is written the
+ *   second way, and `runDecider` and `transact` keep ONE signature each, which
+ *   is what lets `body.pipe(transact(p))` still infer its error and requirement
+ *   channels; an overloaded step would lose both to `unknown`.
+ *
+ * `decider(…)` cannot be served by a conditional at all. Its `O` is derived from
+ * the SUCCESS of an effect type variable, and `Effect.Effect.Success` of a type
+ * variable is itself deferred, so a wrapper that copies `decider`'s own generics
+ * would get a `Decider` whose `O` nothing can resolve, and a runner result that
+ * is not `Position`. So `decider` is declared TWICE, which asks the question by
+ * ASSIGNABILITY instead: FIRST for an effect whose success is the non-empty
+ * batch, returning a `Decider` with the default `O`, and only then for any
+ * `DecisionOutput`, returning one whose `O` is `DecisionOutput`. A type
+ * variable bounded by the batch fits the first, and so does `any`; a `decide`
+ * with a branch answering `Unchanged` does not, and falls through to the second.
+ * Keep that ORDER: the checker takes the first declaration that fits, so
+ * swapped, every decider would be widened.
+ *
+ * Neither reaches a type QUERY. `ReturnType<typeof runDecider>` reads `O` at its
+ * bound, which admits `Unchanged`, so its success is widened; instantiated
+ * (`typeof runDecider<P, Command, E, R>`), `O` takes its default and the answer
+ * is `Position` again. `ReturnType<typeof decider<…>>` reads the LAST
+ * declaration, so it is the widened `Decider` whatever effect type it is given;
+ * a decider VALUE is typed by the declaration that fitted it.
+ *
+ * `DecisionOutput` still refuses a possibly-empty array — a `DcbEvent[]` from a
+ * `filter`, say — at compile time, because a plain array is neither non-empty nor
+ * `Unchanged`. The widening adds an answer; it removes no guarantee.
+ */
+import type { DcbEvent, Position } from '@kairos-es/core'
+import { type Array as Arr, Data, Predicate } from 'effect'
+
+/**
+ * The type id `isUnchanged` recognises. `Symbol.for`, so both halves of the dual
+ * build — and any two copies of this package in one graph — agree on it.
+ */
+export const UnchangedTypeId: unique symbol = Symbol.for(
+  '@kairos-es/codec/Unchanged',
+)
+
+/** The type of `UnchangedTypeId`. */
+export type UnchangedTypeId = typeof UnchangedTypeId
+
+/**
+ * "Nothing to do: this work is already done." A runner that receives it appends
+ * nothing and returns it in place of a `Position`.
+ *
+ * `reason` is for a human reading a trace or a test failure, and nothing in the
+ * library reads it. A `Data.TaggedClass`, so two values with the same reason are
+ * `Equal` and a test can compare them structurally.
+ *
+ * ⚠ Test for it with `isUnchanged`, never with `instanceof` or `_tag` — the
+ * module documentation says why each of those is wrong.
+ */
+export class Unchanged extends Data.TaggedClass('Unchanged')<{
+  readonly reason?: string
+}> {
+  readonly [UnchangedTypeId]: UnchangedTypeId = UnchangedTypeId
+}
+
+/**
+ * Whether `u` is an `Unchanged`, by its type id. Total over `unknown`, and
+ * realm-safe across the dual ESM/CJS build. An application value that merely
+ * carries `_tag: 'Unchanged'` answers `false`, deliberately.
+ */
+export const isUnchanged = (u: unknown): u is Unchanged =>
+  Predicate.hasProperty(u, UnchangedTypeId)
+
+/**
+ * The constructors a `decide` step reaches for. One member today; it is a
+ * namespace object rather than a bare function so the call site reads as what it
+ * is, `Decision.unchanged('already dispatched')`.
+ */
+export const Decision: {
+  readonly unchanged: (reason?: string) => Unchanged
+} = {
+  unchanged: (reason) => new Unchanged(reason === undefined ? {} : { reason }),
+}
+
+/**
+ * Everything a decision may succeed with: a non-empty batch of events to
+ * append, or `Unchanged`. A plain, possibly-empty array is NOT a member, which is
+ * what keeps an empty batch unreachable from a decision.
+ */
+export type DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent> | Unchanged
+
+/**
+ * What a runner returns for a decision that succeeds with `O`: `Position` unless
+ * `O` admits `Unchanged`, and `Position | Unchanged` when it does.
+ *
+ * Asked of each member of `O` — DISTRIBUTIVE — so a union `O` answers
+ * `Position | Unchanged` exactly when one of its members is `Unchanged`, a batch
+ * answers `Position` with no `| never` residue, and an `O` that is a type
+ * variable bounded by the batch is seen to be `Position`, which is what a
+ * wrapper generic in its success type needs. `O` that can ONLY be `Unchanged`
+ * answers `Unchanged`, the precise result and assignable wherever
+ * `Position | Unchanged` is expected.
+ *
+ * Two members are checked BEFORE the distribution, and both answer `Position`,
+ * the result each had before `Unchanged` existed. `any`, because a distributive
+ * conditional over `any` takes both branches and would widen every untyped
+ * decision. And `never` — a body that only ever fails — because distributing
+ * over `never` answers `never`, which a variable once typed with a `Position`
+ * result would no longer accept. The module documentation owns the rest.
+ */
+export type DecisionResult<O> = 0 extends 1 & O
+  ? Position
+  : [O] extends [never]
+    ? Position
+    : O extends Unchanged
+      ? Unchanged
+      : Position

package/src/decisionModel.ts

@@ -7,11 +7,18 @@
  * `modelAtHead` stops where the fold does, at `{ state, head }` — a
  * materialisation of the record with no table, no checkpoint and no runner.
  * `buildDecisionModel` adds the only part that is genuinely decision-specific:
- * the `AppendCondition` derived from the same query and that same head (the DCB
- * optimistic-concurrency contract). It is core's old
- * `buildDecisionModel(Record<string, AnyProjection>)` surface, moved here
+ * the `AppendCondition` (the DCB optimistic-concurrency contract). It is core's
+ * old `buildDecisionModel(Record<string, AnyProjection>)` surface, moved here
  * because decode needs `Schema` + the `Serializer`.
  *
+ * BOTH exports also record into the ambient read ledger when one is in context,
+ * which is what makes a decision that walks a chain of identifiers guard on every
+ * hop rather than on its last. Recording is `modelAtHead`'s, so it happens
+ * whatever symbol performed the read; outside a bracket there is no ledger,
+ * nothing is recorded and no behaviour changes. `readLedger.ts` owns the whole
+ * argument, including why the recorder is this module rather than a
+ * layered-only entry point of its own.
+ *
  * The fold stays pure and in core; only the decode stage is effectful, and that
  * stage lives in `decode.ts` — `decodeSlices` — so the read side folds a live
  * `subscribe` stream through the *same* decode this module folds a bounded
@@ -32,10 +39,16 @@ import {
   DcbEventStore,
   type Position,
 } from '@kairos-es/core'
-import { Effect, Stream } from 'effect'
+import { Effect, Option, Stream } from 'effect'
 import { decodeSlices } from './decode'
 import type { CodecError } from './errors'
 import type { SliceProjection } from './projection'
+import {
+  ambientLayeredCondition,
+  assertServableAddition,
+  recordQuery,
+  type TaglessSliceInLedger,
+} from './readLedger'
 import type { Serializer } from './Serializer'
 
 /** The union of requirements `R` carried by a record of `SliceProjection`s. */
@@ -66,6 +79,16 @@ export type RequirementOf<T extends Record<string, SliceProjection>> =
  * single fold cannot serve — across many identities, ordered, joined, paginated
  * — and never because it is fresher, because it is not.
  *
+ * ⚠ AND INSIDE A BRACKET IT IS NOT THE FLOOR THE APPEND WILL USE. Everything
+ * above is a statement about THIS read, and it stays true; what changes is that a
+ * bracket guards on the EARLIEST head across every hop it walked, which on any hop
+ * after the first is a strictly lower number than the one returned here. So a
+ * caller who reads `head` inside a bracket and reasons about what the append will
+ * refuse is reasoning from the wrong figure — the guard is wider than this head
+ * says. Nothing here is wrong; the trap is assuming the two are the same number,
+ * and it is named because it is exactly the assumption that holds outside a
+ * bracket and quietly stops holding inside one. `readLedger.ts` owns the floor.
+ *
  * `head` is LOG-GLOBAL: it is the head the store's `read` returned, so it moves
  * for an event no slice here selects. `test/decisionModel.test.ts` pins that
  * behaviour EXPLICITLY, over four appended events one of which the composed query
@@ -93,7 +116,7 @@ export const modelAtHead = <T extends Record<string, SliceProjection>>(
   projections: T,
 ): Effect.Effect<
   { readonly state: CompositeState<T>; readonly head: Position },
-  CodecError,
+  CodecError | TaglessSliceInLedger,
   DcbEventStore | Serializer | RequirementOf<T>
 > =>
   Effect.gen(function* () {
@@ -108,6 +131,21 @@ export const modelAtHead = <T extends Record<string, SliceProjection>>(
     const composite = composeProjections(
       projections as Record<string, AnyProjection>,
     )
+
+    // Both ledger calls below are no-ops outside a bracket and neither touches
+    // the requirement channel; `readLedger.ts` owns why recording happens HERE
+    // rather than at a layered-only entry point of its own.
+    //
+    // Refuse an unservable union BEFORE the read is paid for: the question is
+    // answerable from the queries alone, so a hop that would kill the append two
+    // layers away fails at the read that caused it instead.
+    yield* assertServableAddition(projections as Record<string, AnyProjection>)
+
+    // EAGER: the query is filed before a single event is streamed, so a read that
+    // opens and never completes still widens the guard. What comes back is the
+    // effect that completes the hop; outside a bracket it does nothing.
+    const closeHop = yield* recordQuery(composite.query)
+
     const { events, head } = yield* store.read(composite.query)
 
     const decoded = decode(events)
@@ -118,6 +156,11 @@ export const modelAtHead = <T extends Record<string, SliceProjection>>(
       (acc, event) => composite.evolve(acc, event),
     )) as CompositeState<T>
 
+    // LAZY: only once the fold has run to completion. A read that failed
+    // part-way folded a PREFIX, and a head recorded for it is a claim it did not
+    // earn — so the line below is unreachable on that path, deliberately.
+    yield* closeHop(head)
+
     return { state, head }
   })
 
@@ -134,17 +177,19 @@ export const modelAtHead = <T extends Record<string, SliceProjection>>(
  * of a near-duplicate: `modelAtHead` is the shared part, this function is the
  * condition and nothing else, and each is shorter than the one function was.
  *
- * `composeProjections` therefore runs TWICE for one command — once inside
- * `modelAtHead` for the read, once here for `failIfEventsMatch` — and that is
- * deliberate rather than waste. It is a pure derivation of the record, so the two
- * queries cannot disagree however either call site changes. The alternative,
- * returning the query from `modelAtHead`, would put a third field on a READ-TIME
- * API that no read-time caller wants, to save one pure merge over a handful of
- * slices; a surface paying for a body's convenience is the worse trade.
+ * Outside a bracket `composeProjections` therefore runs twice for one command —
+ * once inside `modelAtHead` for the read, once here for `failIfEventsMatch` — and
+ * that is deliberate rather than waste. It is a pure derivation of the record, so
+ * the two queries cannot disagree however either call site changes. The
+ * alternative, returning the query from `modelAtHead`, would put a third field on
+ * a READ-TIME API that no read-time caller wants, to save one pure merge over a
+ * handful of slices; a surface paying for a body's convenience is the worse
+ * trade. Inside a bracket the second merge is not reached at all: the ledger's
+ * own derivation composes every recorded hop instead.
  *
  * ## How to attribute the read, the decode and the fold — the rule, stated once
  *
- * Because this function is `Effect.map` over `modelAtHead`, prose about the codec
+ * Because this function is expressed OVER `modelAtHead`, prose about the codec
  * splits into two kinds and only one of them may name this symbol:
  *
  * - Naming this function as the ENTRY POINT a caller invokes, or as the path
@@ -168,15 +213,34 @@ export const buildDecisionModel = <T extends Record<string, SliceProjection>>(
     readonly state: CompositeState<T>
     readonly appendCondition: AppendCondition
   },
-  CodecError,
+  CodecError | TaglessSliceInLedger,
   DcbEventStore | Serializer | RequirementOf<T>
 > =>
-  Effect.map(modelAtHead(projections), ({ state, head }) => ({
-    state,
-    appendCondition: {
-      failIfEventsMatch: composeProjections(
-        projections as Record<string, AnyProjection>,
-      ).query,
-      after: head,
-    },
-  }))
+  Effect.gen(function* () {
+    const { state, head } = yield* modelAtHead(projections)
+
+    // INSIDE A BRACKET the condition comes from the ledger — every query the
+    // bracket walked, at the earliest head observed — and not from this one read.
+    // That is the change's whole ergonomic claim: the call whose current
+    // behaviour is the hazard becomes CORRECT inside a bracket, with nothing at
+    // the call site changing beyond entering one. The cost is that one expression
+    // means two things depending on ambient context, and that is the trade taken.
+    //
+    // `modelAtHead` has just recorded a hop, so inside a bracket the derivation
+    // cannot be empty; `None` here means there is no ledger at all.
+    const ambient = yield* ambientLayeredCondition
+    if (Option.isSome(ambient)) {
+      return { state, appendCondition: ambient.value }
+    }
+
+    // OUTSIDE a bracket this is byte-for-byte what shipped.
+    return {
+      state,
+      appendCondition: {
+        failIfEventsMatch: composeProjections(
+          projections as Record<string, AnyProjection>,
+        ).query,
+        after: head,
+      },
+    }
+  })

package/src/index.ts

@@ -34,6 +34,72 @@
  * error union are written once, in the two function bodies, rather than restated
  * as an annotation above them.
  *
+ * A decision may also answer `Unchanged` — "already done, nothing to append" —
+ * built with `Decision.unchanged(reason?)` and recognised ONLY by
+ * `isUnchanged`, by its `UnchangedTypeId`. It is a success, not an error and not
+ * an empty batch: every runner returns it in place of a `Position` and appends
+ * nothing. `Decider`'s fifth type parameter carries the widening and defaults to
+ * the non-empty batch, and each runner's result is `DecisionResult<O>`, so a
+ * decider or body that cannot answer `Unchanged` keeps a plain `Position` — an
+ * untyped one and one generic in its success type included — and its caller is
+ * never asked to handle it. `decision.ts` owns the argument, and the one type
+ * query that does read differently.
+ *
+ * `transact(precondition)(body)` is the layered write path, for a decision whose
+ * second query cannot be written until an earlier read has been folded. It opens
+ * an ambient read ledger, evaluates the precondition inside it, hands that
+ * precondition's output to the body as a service, and appends what the body
+ * returned under the union of every query either of them read, at the earliest
+ * head observed. No condition reaches the caller. `unsafeAppend(events, reason)`
+ * is the one sanctioned way out. `precondition.ts` owns the argument for the
+ * bracket and everything on it, and `readLedger.ts` for the ledger the seam rests
+ * on — including why the derivation itself is deliberately not on this surface.
+ *
+ * ## ⚠ `runDecider` and `decideOnly` are TWO DISPOSITIONS OF ONE CYCLE
+ *
+ * They are read as a pair or not at all, because each refuses exactly where the
+ * other is the answer:
+ *
+ * |              | outside a bracket                        | inside a bracket                    |
+ * | ------------ | ---------------------------------------- | ----------------------------------- |
+ * | `runDecider` | ✅ the ordinary single-hop case           | ⛔ a DEFECT, refused at the store    |
+ * | `decideOnly` | ⛔ unrunnable, and `tsc` says so          | ✅ the layered case                  |
+ *
+ * Both carry `Unchanged` the same way, which is what keeps them one pair:
+ * `runDecider` returns it having appended nothing, and `decideOnly` passes it to
+ * the body unaltered, where `transact` returns it having appended nothing —
+ * and, having no write to guard, without refusing an empty bracket as
+ * `NoReadsRecorded`.
+ *
+ * ⚠ *Unrunnable* rather than *unwritable*, and the difference is measured. A bare
+ * `decideOnly(d, cmd)` outside a bracket COMPILES, and so does an exported helper
+ * over it: its `ReadLedger` requirement simply propagates, as any unmet requirement
+ * does. The refusal lands where the context is DISCHARGED — an `Effect.provide`, a
+ * `runPromise`, an annotation asking for `R = never` — which may be another file.
+ * So `pnpm check` catches it without anything running, which is the whole gain over
+ * the runtime defect this replaced; what it does not do is underline the call.
+ *
+ * Neither is expressed over the other, and that is forced rather than chosen: a
+ * definition of `runDecider` as *"`decideOnly`, then append"* would have to call
+ * `decideOnly` outside a bracket, which does not typecheck, and the append it then
+ * made inside one would be refused. The two refusals are the same fact seen from
+ * either side — an append inside a bracket belongs to the bracket — so any
+ * expression of one over the other has to defeat one of them.
+ *
+ * ⚠ The two refusals arrive at DIFFERENT MOMENTS, which is the part a caller acts
+ * on. `runDecider` inside a bracket is refused when it RUNS, at core's shared append
+ * decorator — so the same refusal also meets a raw `store.append` and a runner one
+ * call away in a helper. `decideOnly` outside a bracket is refused by `tsc`, at the
+ * discharge point above, by naming `ReadLedger` in its requirement channel. Why each
+ * was given the instrument it was is a DECISION and belongs to the record that took
+ * it: ADR-0014's `Status`. A lint rule reaches the first case earlier still, while it
+ * is being written; `biome-plugins/README.md` in the source repository owns what a
+ * rule there can and cannot see.
+ *
+ * The remedy is one identifier away in each direction, which is the whole reason a
+ * refusal is affordable at all. `decider.ts` and `precondition.ts` carry the two
+ * halves.
+ *
  * `modelAtHead(slices)` is that same read-decode-fold WITHOUT the
  * `AppendCondition`: `{ state, head }`, one slice record materialised at read
  * time with no table, no checkpoint and no runner, current as of the `head` its
@@ -52,6 +118,14 @@
  */
 
 export { type Decider, decider, runDecider } from './decider'
+export {
+  Decision,
+  type DecisionOutput,
+  type DecisionResult,
+  isUnchanged,
+  Unchanged,
+  UnchangedTypeId,
+} from './decision'
 export {
   buildDecisionModel,
   modelAtHead,
@@ -60,11 +134,24 @@ export {
 export { decodeSlices } from './decode'
 export { CodecError, UnknownEventType } from './errors'
 export { type EventDef, type EventDefAny, event, type TagsFor } from './event'
+export {
+  decideOnly,
+  type Precondition,
+  transact,
+  unsafeAppend,
+} from './precondition'
 export {
   type ProjectionBuilder,
   projection,
   type SliceProjection,
 } from './projection'
+export {
+  type CloseHop,
+  type Hop,
+  NoReadsRecorded,
+  ReadLedger,
+  TaglessSliceInLedger,
+} from './readLedger'
 export { makeRegistry, type Registry } from './registry'
 export { Serializer, SerializerDefault } from './Serializer'
 export { toEvent } from './toEvent'