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

package/dist/dts/readLedger.d.ts

@@ -0,0 +1,263 @@
+/**
+ * The ambient read ledger: the hops a bracket walked, and the single derivation
+ * that turns them into one `AppendCondition`.
+ *
+ * ## The gap this closes, and why the fix has to be ambient
+ *
+ * A decision model whose second query cannot be written until an earlier read has
+ * been folded — the identifier it needs is data that fold produced — guards its
+ * append on only the LAST read if it reaches for `buildDecisionModel` there. The
+ * append then succeeds on a premise that is no longer true, and nothing warns: it
+ * compiles, it runs, and it is silent. Two things must both change for the
+ * condition to be sound, and fixing either alone still lets the stale write
+ * through. Keeping the union of queries but taking the last head misses, because
+ * the invalidating event lands in the window between the two heads. Keeping the
+ * earliest head but taking the last query misses, because the invalidating event
+ * fails that query's TYPE arm before its tag arm is reached — which is why adding
+ * a tag to the last query cannot recover it.
+ *
+ * The ledger is an OPTIONAL AMBIENT SERVICE rather than a scope object a caller
+ * threads, and that is the whole design. A scope object's guarantee is "every read
+ * through this object", which is not "every read": `modelAtHead` stays exported
+ * and stays in scope inside the bracket, so a read that reached for the familiar
+ * name — or that happened inside a helper the body merely called — drops a hop
+ * silently. Here `modelAtHead` ITSELF records, so a read is recorded whatever
+ * symbol performed it and at whatever call depth. `Effect.serviceOption` is what
+ * makes that additive: it reads the service if present and adds NOTHING to the
+ * requirement channel, so `modelAtHead`'s published signature is untouched and no
+ * existing caller provides anything.
+ *
+ * ## Why the query is recorded eagerly and the head only on completion
+ *
+ * A `Hop` is `{ query, head? }` and the two halves are recorded at different
+ * moments: the query before a single event is streamed, the head once the fold has
+ * run to completion. So a read that opened and never finished widens the guard
+ * without contributing a floor, and both halves fail safe.
+ *
+ * The laziness is deliberate protection rather than an accident of where the line
+ * sits. Recording the head at read-return is available and MUST NOT be done: a
+ * read that failed part-way folded only a PREFIX, and a head recorded for it is a
+ * claim the hop did not earn — the floor would sit above events that read never
+ * folded, and nothing would refuse an append those events invalidate.
+ *
+ * ## An invalidated ledger must REFUSE to derive, never derive narrowly
+ *
+ * Nothing here evicts a hop, so there is no eviction policy to specify — but the
+ * rule is stated now because the moment a bound is added, and an unbounded walk on
+ * a large log will want one, the tempting implementation is to drop the oldest hop
+ * and carry on. A ledger that has lost hops must become a poison value and refuse
+ * to produce a condition at all. Deriving from a PARTIAL set is worse than
+ * refusing, because it looks like it worked: an emptied ledger produces a NARROWER
+ * condition and a silent success, which is the original hazard wearing a fix's
+ * name. The valve is coarsen, then poison. Never forget.
+ *
+ * ## What is deliberately NOT exported from the package
+ *
+ * `deriveLayeredCondition` is PACKAGE-internal and reaches no entry point. Two
+ * traps stay reachable for a caller who assembles a condition by hand, both
+ * demonstrated: concatenating query items drops a wildcard hop, an empty item list
+ * being absorbing under OR while an empty concatenation contributes nothing; and a
+ * MAXIMUM over heads reads as naturally as a minimum, two reducers of identical
+ * signature where "the position I read at" argues just as fluently for the later
+ * one. Offering the derivation as a public step would put both back within reach
+ * of the callers the bracket exists to protect.
+ */
+import type { AnyProjection, AppendCondition, Position, Query } from '@kairos-es/core';
+import { Context, Effect, Layer, Option } from 'effect';
+/**
+ * One recorded read: the query it rode, and the head it observed.
+ *
+ * `head` is a genuinely OPTIONAL key and not `Position | undefined`, because
+ * `exactOptionalPropertyTypes` is on and the absent case must be an absent key.
+ * Absent means the read did not complete, which the derivation below treats as
+ * the widest possible floor.
+ */
+export interface Hop {
+    readonly query: Query;
+    readonly head?: Position;
+}
+declare const ReadLedger_base: Context.TagClass<ReadLedger, "@kairos-es/codec/ReadLedger", {
+    /**
+     * File a query, and hand back the effect that will fill in its head.
+     *
+     * Two phases and not one `record(hop)`, which is what the eager/lazy split
+     * above needs: a one-shot recorder cannot express a hop whose head never
+     * arrives, and that is the case the whole fail-safe direction turns on.
+     *
+     * The second phase comes back as a CLOSURE rather than as a slot number the
+     * caller carries to a second method. The closure holds its own slot, so
+     * nothing threads an index through the reader, nothing looks the service up a
+     * second time to spend it, and there is no slot value for a caller to hold
+     * wrongly.
+     */
+    readonly record: (query: Query) => Effect.Effect<CloseHop>;
+    readonly hops: Effect.Effect<ReadonlyArray<Hop>>;
+}>;
+/**
+ * The ambient ledger, present only inside a bracket.
+ *
+ * ⚠ A RECORDING path reads it with `Effect.serviceOption` and never
+ * `yield* ReadLedger`: its absence is the normal case there, and costing the
+ * requirement channel nothing is exactly what makes this change additive.
+ * `modelAtHead` is that path and is why the rule exists.
+ *
+ * A BRACKET-ONLY function is the opposite case and yields the tag deliberately.
+ * `decideOnly` does, and naming the requirement is what turns *"call me inside a
+ * bracket"* from a runtime defect into a compile error — presence being the one
+ * direction the type system can decide here. So the test is what the function
+ * means outside a bracket: nothing (record ambiently), or nothing sensible
+ * (require it).
+ *
+ * Recording is two-phase, and `record`'s own doc below owns why and what shape the
+ * second phase takes.
+ */
+export declare class ReadLedger extends ReadLedger_base {
+}
+/**
+ * Fill in a recorded hop's head. Never called if the read does not complete.
+ *
+ * On the package's public surface because it is already ON it: `record` returns
+ * one, `ReadLedger` is exported, so a consumer holding the tag holds this type and
+ * could not name it. `Hop` was exported and this was not — the same interface, two
+ * treatments.
+ */
+export type CloseHop = (head: Position) => Effect.Effect<void>;
+declare const NoReadsRecorded_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NoReadsRecorded";
+} & Readonly<A>;
+/**
+ * Raised when a bracket closes having recorded no read at all.
+ *
+ * On the ERROR channel and deliberately split from the nested-append DEFECT,
+ * because the two are different mistakes. An empty bracket can arise from a
+ * data-dependent branch that produces events without reading — a genuinely
+ * unconditional creation, written inside a bracket by mistake — where a nested
+ * append is always a wiring fault. An error-channel value lets a caller decide
+ * which it is.
+ *
+ * Its job is narrower than it looks, and the narrowing is worth stating because
+ * the wider reading is the tempting one. Once a bracket's guard is itself a fold,
+ * a body that reads nothing still has a hop, so this cannot fire — it is the guard
+ * against an unguarded UNCONDITIONAL bracket, not against an unguarded bracket. A
+ * bracket that looks guarded and is not is NOT what this catches and never was,
+ * and nothing else catches it either — `precondition.ts` owns that gap and the
+ * rule a reader has to keep in its place. A refusal taken BEFORE reading is not
+ * this case either: it short-circuits and surfaces as the refusal.
+ */
+export declare class NoReadsRecorded extends NoReadsRecorded_base<Record<never, never>> {
+    /**
+     * The sentence, as the `Error` field that says why — so the fault renders
+     * ITSELF, exactly as this package's other two errors do (`errors.ts` owns the
+     * argument for the mechanism and it is not restated here).
+     *
+     * A getter over a constant rather than a constructor field, because there is no
+     * datum to vary: every raise of this error means one thing.
+     */
+    get message(): string;
+}
+declare const TaglessSliceInLedger_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "TaglessSliceInLedger";
+} & Readonly<A>;
+/**
+ * Raised when recording a hop would leave the bracket's accumulated union
+ * unservable.
+ *
+ * The store refuses a multi-item query in which any item is tagless, and it
+ * refuses it by THROWING inside the append decorator, which becomes a defect:
+ * uncatchable, one call and one layer away from the `build()` that chose no tags.
+ * A slice built without tags defaults to none, so it is perfectly servable alone
+ * and kills the append the moment it is unioned. This moves that failure onto the
+ * error channel, to the read that caused it, naming the record entry to fix.
+ *
+ * It refuses an unservable UNION and not every tagless hop, which is the easy
+ * mistake to make in the other direction: one tagless slice read on its own is
+ * servable and must keep working. Two cases reach it — a tagless hop unioned with
+ * another, and a single hop whose own RECORD holds two tagless slices, which
+ * composes to a multi-item query with no second hop needed.
+ */
+export declare class TaglessSliceInLedger extends TaglessSliceInLedger_base<{
+    readonly sliceKey: string;
+}> {
+    /** The offending slice and the remedy, in one sentence. */
+    get message(): string;
+}
+/**
+ * The ONE derivation: the union of every query walked, at the earliest head
+ * observed. Package-internal, for the reason the module doc gives.
+ *
+ * The union goes through core's own `unionQueries` — the merge
+ * `composeProjections` folds a record through, reached without one — and never a
+ * spread of `items`, because a wildcard hop (`items: []`) is ABSORBING under OR
+ * while a spread of an empty list contributes nothing, so hand-rolling the union
+ * narrows a match-everything hop to its sibling, silently and in the unsafe
+ * direction. A
+ * repeated or overlapping hop is harmless because this derives ONCE from a merged
+ * set and matching is idempotent over an OR; that property belongs to deriving
+ * once and would be lost by a refactor to per-hop evaluation.
+ *
+ * ## When any hop is headless the floor is `ORIGIN`, and the alternative is unsound
+ *
+ * The earliest head that actually ARRIVED is refused, and is named here as refused
+ * rather than merely not chosen, because it is what a reader writes by accident
+ * when told to take the earliest head. With one headless hop among completed hops
+ * the union looks right and the floor betrays it, sitting already above the
+ * invalidating event.
+ *
+ * `ORIGIN`'s cost is measured rather than described: it refuses every append to
+ * any identity that already has history, so it is not a conservative default but a
+ * hard stop. It is affordable only because conflict retry wraps the bracket from
+ * OUTSIDE and re-reads, which is the rule the whole shape depends on.
+ */
+export declare const deriveLayeredCondition: (hops: ReadonlyArray<Hop>) => AppendCondition | undefined;
+/**
+ * A fresh ledger and the `Layer` providing it: a `Ref` of hops behind the two-phase
+ * `record` the service declares.
+ *
+ * The hops effect is handed back beside the layer because the bracket reads them
+ * AFTER the body has run and the layer is out of scope, which is the same moment it
+ * stops being able to reach the service.
+ */
+export declare const makeReadLedger: Effect.Effect<{
+    readonly layer: Layer.Layer<ReadLedger>;
+    readonly hops: Effect.Effect<ReadonlyArray<Hop>>;
+}>;
+/**
+ * File a query into the ambient ledger if there is one, and hand back the effect
+ * that completes it. Outside a bracket the whole thing is a no-op, and the caller
+ * still writes one line rather than a conditional.
+ */
+export declare const recordQuery: (query: Query) => Effect.Effect<CloseHop>;
+/**
+ * Refuse a read that would leave the bracket's accumulated union unservable,
+ * BEFORE the read is paid for.
+ *
+ * Servability is answerable from the queries alone, so the check runs when a hop is
+ * recorded rather than at append time — the eager half of the eager/lazy split doing
+ * one more job. Outside a bracket nothing is unioned and nothing is unservable, so
+ * the ordinary single-hop caller is untaxed.
+ *
+ * It judges the PROSPECTIVE UNION and asks core for the verdict, which is what makes
+ * both failing shapes one case rather than two. An earlier version tested each
+ * recorded query separately and treated a FIRST hop as unconditionally fine — but a
+ * hop is a RECORD, and a record of two tagless slices composes to a multi-item query
+ * that is unservable on its own. That read died at the store, uncatchably, on the
+ * exact path this error exists to keep off the defect channel. A grammar with two
+ * homes drifts at the shapes neither author had in mind, so there is one home and it
+ * is `servableQueryFault`'s.
+ *
+ * Where the OFFENDING slice is THIS record's the ledger can name its key; where it
+ * belongs to an earlier hop it can only say so, a recorded hop keeping its query
+ * rather than the key it was composed from. That asymmetry is diagnostic-only and is
+ * why the message is built from a key that may be a placeholder.
+ */
+export declare const assertServableAddition: (projections: Record<string, AnyProjection>) => Effect.Effect<void, TaglessSliceInLedger>;
+/**
+ * The condition the ambient ledger derives right now, or `None` outside a bracket.
+ *
+ * This is what makes `buildDecisionModel` correct inside a bracket: the call whose
+ * current behaviour is the hazard derives from every hop the bracket walked rather
+ * than from its own single read.
+ */
+export declare const ambientLayeredCondition: Effect.Effect<Option.Option<AppendCondition>>;
+export {};
+//# sourceMappingURL=readLedger.d.ts.map

package/dist/dts/readLedger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readLedger.d.ts","sourceRoot":"","sources":["../../src/readLedger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,QAAQ,EACR,KAAK,EACN,MAAM,iBAAiB,CAAA;AAOxB,OAAO,EAAE,OAAO,EAAQ,MAAM,EAAE,KAAK,EAAE,MAAM,EAAO,MAAM,QAAQ,CAAA;AAElE;;;;;;;GAOG;AACH,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAA;CACzB;;IAuBG;;;;;;;;;;;;OAYG;qBACc,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;mBAC3C,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;;AAnCpD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAW,SAAQ,eAmB7B;CAAG;AAEN;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,QAAQ,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;;;;AAE9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,SAAQ,qBACnC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CACrB;IACC;;;;;;;OAOG;IACH,IAAa,OAAO,IAAI,MAAM,CAM7B;CACF;;;;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oBAAqB,SAAQ,0BAExC;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;IAC9B,2DAA2D;IAC3D,IAAa,OAAO,IAAI,MAAM,CAO7B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,sBAAsB,GACjC,MAAM,aAAa,CAAC,GAAG,CAAC,KACvB,eAAe,GAAG,SAiBpB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAA;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAA;CACjD,CAsBC,CAAA;AAsBF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CACT,CAAA;AAqBxD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,sBAAsB,GACjC,aAAa,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,KACzC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,oBAAoB,CAaxC,CAAA;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,CACjD,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAK/B,CAAA"}

package/dist/esm/decider.js

@@ -52,84 +52,52 @@
  * 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 { DcbEventStore } from '@kairos-es/core';
 import { Effect } from 'effect';
+import { isUnchanged } from "./decision.js";
 import { buildDecisionModel } from "./decisionModel.js";
-/**
- * Build a `Decider` with all four of its type arguments INFERRED: the slice
- * record `P` from what `projections` returns, the error union `E` and the extra
- * requirement `R` from what `decide` returns. The command type is the one thing
- * a caller still writes, once, as the annotation on the `projections` parameter
- * — `Command` occurs only in parameter positions, so nothing else could supply
- * it, and it is domain information (the command this decision is parametrised
- * by) rather than plumbing.
- *
- * It adds no capability: the interface stays directly inhabitable and this
- * returns exactly the object literal a caller would have written. What it
- * changes is what an author must SPELL. An object literal annotated
- * `Decider<P, Command, E>` has to state the whole slice record — a
- * `ReturnType<typeof someProjection>` per key, a slice's state type being
- * inferred by `projection().on().build()` and so having no name to write — plus
- * the union of every error its decide branches can fail with. Dropping the
- * annotation instead is not open to the author: without it `decide`'s `state`
- * and `command` parameters have no contextual type and are implicitly `any`. So
- * the cost landed hardest on the worked example, where some thirty lines of type
- * plumbing sat between the reader and the three decisions that file exists to
- * teach.
- *
- * `Eff` captures decide's WHOLE return type as one type parameter instead of
- * inferring `E` and `R` from an `Effect<…, E, Serializer | Uuid | R>` shaped
- * target, and that is the part that had to be got right rather than merely
- * written down. A real `decide` returns a UNION of effects — one `Effect.fail`
- * per rule it enforces, plus the produce path — and TypeScript infers a type
- * parameter from a union source by choosing one constituent's candidate, not by
- * unioning them. Against the shaped target `E` therefore came out as whichever
- * branch won, and every other branch was then rejected against it. Inference to
- * a NAKED type variable takes the union whole, which is why `Eff` is the
- * parameter and `Effect.Effect.Error` / `Effect.Effect.Context` recover the two
- * channels afterwards: those do distribute across a union of effects.
- *
- * The constraint on `Eff` is load-bearing twice over. It is what still refuses a
- * `decide` that could produce an EMPTY batch, the one guarantee the shaped
- * target used to give and the one `append` relies on. It is also what
- * contextually types the produce path's `(event) => [event]` as a one-element
- * TUPLE; unconstrained, that widens to `DcbEvent[]`, which is not a
- * `NonEmptyReadonlyArray` and would fail at the call site.
- *
- * The single `as` is narrow and unavoidable: the declared return is a
- * conditional over an unresolved `Eff`, so while `Eff` is still a type variable
- * the checker cannot relate `(…) => Eff` to `(…) => Effect<…,
- * Effect.Error<Eff>, …>`. The value is the two functions it was handed, so
- * there is nothing for the cast to be wrong about.
- *
- * `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
- * them in would state the same requirement twice and make an ordinary decider
- * read as though it carried an extra one, though the set `runDecider` ends up
- * asking for is identical either way. The exclusion cannot swallow a caller's
- * own service by accident: a `Context.Tag`'s requirement type carries its key as
- * a literal `Id` field, so only a tag declared under `@kairos-es/codec/Uuid` or
- * `@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 = (projections, decide) => ({
-  projections,
-  decide
-});
+export function decider(projections, decide) {
+  return {
+    projections,
+    decide
+  };
+}
 /**
  * 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 = (decider, command) => Effect.gen(function* () {
   const store = yield* DcbEventStore;
@@ -137,7 +105,14 @@ export const runDecider = (decider, command) => Effect.gen(function* () {
     state,
     appendCondition
   } = yield* buildDecisionModel(decider.projections(command));
-  const newEvents = yield* decider.decide(state, command);
-  return yield* store.append(newEvents, appendCondition);
+  const output = 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;
+  }
+  return yield* store.append(output, appendCondition);
 });
 //# sourceMappingURL=decider.js.map

package/dist/esm/decider.js.map

@@ -1 +1 @@
-{"version":3,"file":"decider.js","names":["DcbEventStore","Effect","buildDecisionModel","decider","projections","decide","runDecider","command","gen","store","state","appendCondition","newEvents","append"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,SAASA,aAAa,QAAQ,iBAAiB;AAE/C,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAASC,kBAAkB,QAA4B,oBAAiB;AAsCxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,OAAO,MAAMC,OAAO,GAAGA,CASrBC,WAAoC,EACpCC,MAA2D,MAO1D;EAAED,WAAW;EAAEC;AAAM,CAAE,CAKvB;AAEH;;;;;;;;;;;;;AAaA,OAAO,MAAMC,UAAU,GAAGA,CAMxBH,OAAkC,EAClCI,OAAgB,KAMhBN,MAAM,CAACO,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOT,aAAa;EAClC,MAAM;IAAEU,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAOT,kBAAkB,CAC1DC,OAAO,CAACC,WAAW,CAACG,OAAO,CAAC,CAC7B;EACD,MAAMK,SAAS,GAAG,OAAOT,OAAO,CAACE,MAAM,CAACK,KAAK,EAAEH,OAAO,CAAC;EACvD,OAAO,OAAOE,KAAK,CAACI,MAAM,CAACD,SAAS,EAAED,eAAe,CAAC;AACxD,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"decider.js","names":["DcbEventStore","Effect","isUnchanged","buildDecisionModel","decider","projections","decide","runDecider","command","gen","store","state","appendCondition","output","append"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwEA,SAASA,aAAa,QAAQ,iBAAiB;AAE/C,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAGEC,WAAW,QACN,eAAY;AACnB,SAASC,kBAAkB,QAA4B,oBAAiB;AAoJxE,OAAM,SAAUC,OAAOA,CACrBC,WAAoC,EACpCC,MAGoD;EAEpD,OAAO;IAAED,WAAW;IAAEC;EAAM,CAM3B;AACH;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,OAAO,MAAMC,UAAU,GAAGA,CAOxBH,OAAqC,EACrCI,OAAgB,KAMhBP,MAAM,CAACQ,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOV,aAAa;EAClC,MAAM;IAAEW,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAOT,kBAAkB,CAC1DC,OAAO,CAACC,WAAW,CAACG,OAAO,CAAC,CAC7B;EACD,MAAMK,MAAM,GAAmB,OAAOT,OAAO,CAACE,MAAM,CAACK,KAAK,EAAEH,OAAO,CAAC;EACpE;EACA;EACA;EACA;EACA,IAAIN,WAAW,CAACW,MAAM,CAAC,EAAE;IACvB,OAAOA,MAA2B;EACpC;EACA,OAAQ,OAAOH,KAAK,CAACI,MAAM,CAACD,MAAM,EAAED,eAAe,CAAC;AACtD,CAAC,CAAC","ignoreList":[]}

package/dist/esm/decision.js

@@ -0,0 +1,37 @@
+import { 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 = /*#__PURE__*/Symbol.for('@kairos-es/codec/Unchanged');
+/**
+ * "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 /*#__PURE__*/Data.TaggedClass('Unchanged') {
+  [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 => 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 = {
+  unchanged: reason => new Unchanged(reason === undefined ? {} : {
+    reason
+  })
+};
+//# sourceMappingURL=decision.js.map

package/dist/esm/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","names":["Data","Predicate","UnchangedTypeId","Symbol","for","Unchanged","TaggedClass","isUnchanged","u","hasProperty","Decision","unchanged","reason","undefined"],"sources":["../../src/decision.ts"],"sourcesContent":[null],"mappings":"AA4FA,SAA4BA,IAAI,EAAEC,SAAS,QAAQ,QAAQ;AAE3D;;;;AAIA,OAAO,MAAMC,eAAe,gBAAkBC,MAAM,CAACC,GAAG,CACtD,4BAA4B,CAC7B;AAKD;;;;;;;;;;;AAWA,OAAM,MAAOC,SAAU,sBAAQL,IAAI,CAACM,WAAW,CAAC,WAAW,CAEzD;EACS,CAACJ,eAAe,IAAqBA,eAAe;;AAG/D;;;;;AAKA,OAAO,MAAMK,WAAW,GAAIC,CAAU,IACpCP,SAAS,CAACQ,WAAW,CAACD,CAAC,EAAEN,eAAe,CAAC;AAE3C;;;;;AAKA,OAAO,MAAMQ,QAAQ,GAEjB;EACFC,SAAS,EAAGC,MAAM,IAAK,IAAIP,SAAS,CAACO,MAAM,KAAKC,SAAS,GAAG,EAAE,GAAG;IAAED;EAAM,CAAE;CAC5E","ignoreList":[]}

package/dist/esm/decisionModel.js

@@ -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
@@ -25,8 +32,9 @@
  * binding this module owns (see `decode.ts` for why).
  */
 import { composeProjections, DcbEventStore } from '@kairos-es/core';
-import { Effect, Stream } from 'effect';
+import { Effect, Option, Stream } from 'effect';
 import { decodeSlices } from "./decode.js";
+import { ambientLayeredCondition, assertServableAddition, recordQuery } from "./readLedger.js";
 /**
  * Read the events for the composed slices' query, decode each through its def's
  * `Schema`, fold into per-key state, and return `{ state, head }`: one slice
@@ -51,6 +59,16 @@ import { decodeSlices } from "./decode.js";
  * 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
@@ -82,12 +100,28 @@ export const modelAtHead = projections => Effect.gen(function* () {
   const decode = decodeSlices(projections);
   // The pure fold: core composes the record (slices are AnyProjections).
   const composite = composeProjections(projections);
+  // 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);
+  // 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);
   const state = yield* Stream.runFold(decoded, composite.initialState, (acc, event) => composite.evolve(acc, event));
+  // 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
@@ -106,17 +140,19 @@ export const modelAtHead = projections => Effect.gen(function* () {
  * 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
@@ -133,14 +169,34 @@ export const modelAtHead = projections => Effect.gen(function* () {
  * reads perfectly and is wrong. The correction is to name `modelAtHead`, never to
  * soften the sentence.
  */
-export const buildDecisionModel = projections => Effect.map(modelAtHead(projections), ({
-  state,
-  head
-}) => ({
-  state,
-  appendCondition: {
-    failIfEventsMatch: composeProjections(projections).query,
-    after: head
+export const buildDecisionModel = projections => 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).query,
+      after: head
+    }
+  };
+});
 //# sourceMappingURL=decisionModel.js.map

package/dist/esm/decisionModel.js.map

@@ -1 +1 @@
-{"version":3,"file":"decisionModel.js","names":["composeProjections","DcbEventStore","Effect","Stream","decodeSlices","modelAtHead","projections","gen","store","decode","composite","events","head","read","query","decoded","state","runFold","initialState","acc","event","evolve","buildDecisionModel","map","appendCondition","failIfEventsMatch","after"],"sources":["../../src/decisionModel.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,SAIEA,kBAAkB,EAClBC,aAAa,QAER,iBAAiB;AACxB,SAASC,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AACvC,SAASC,YAAY,QAAQ,aAAU;AASvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,OAAO,MAAMC,WAAW,GACtBC,WAAc,IAMdJ,MAAM,CAACK,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOP,aAAa;EAElC;EACA;EACA;EACA,MAAMQ,MAAM,GAAGL,YAAY,CAACE,WAAW,CAAC;EAExC;EACA,MAAMI,SAAS,GAAGV,kBAAkB,CAClCM,WAA4C,CAC7C;EACD,MAAM;IAAEK,MAAM;IAAEC;EAAI,CAAE,GAAG,OAAOJ,KAAK,CAACK,IAAI,CAACH,SAAS,CAACI,KAAK,CAAC;EAE3D,MAAMC,OAAO,GAAGN,MAAM,CAACE,MAAM,CAAC;EAE9B,MAAMK,KAAK,GAAI,OAAOb,MAAM,CAACc,OAAO,CAClCF,OAAO,EACPL,SAAS,CAACQ,YAAY,EACtB,CAACC,GAAG,EAAEC,KAAK,KAAKV,SAAS,CAACW,MAAM,CAACF,GAAG,EAAEC,KAAK,CAAC,CACvB;EAEvB,OAAO;IAAEJ,KAAK;IAAEJ;EAAI,CAAE;AACxB,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,OAAO,MAAMU,kBAAkB,GAC7BhB,WAAc,IASdJ,MAAM,CAACqB,GAAG,CAAClB,WAAW,CAACC,WAAW,CAAC,EAAE,CAAC;EAAEU,KAAK;EAAEJ;AAAI,CAAE,MAAM;EACzDI,KAAK;EACLQ,eAAe,EAAE;IACfC,iBAAiB,EAAEzB,kBAAkB,CACnCM,WAA4C,CAC7C,CAACQ,KAAK;IACPY,KAAK,EAAEd;;CAEV,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"decisionModel.js","names":["composeProjections","DcbEventStore","Effect","Option","Stream","decodeSlices","ambientLayeredCondition","assertServableAddition","recordQuery","modelAtHead","projections","gen","store","decode","composite","closeHop","query","events","head","read","decoded","state","runFold","initialState","acc","event","evolve","buildDecisionModel","ambient","isSome","appendCondition","value","failIfEventsMatch","after"],"sources":["../../src/decisionModel.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAIEA,kBAAkB,EAClBC,aAAa,QAER,iBAAiB;AACxB,SAASC,MAAM,EAAEC,MAAM,EAAEC,MAAM,QAAQ,QAAQ;AAC/C,SAASC,YAAY,QAAQ,aAAU;AAGvC,SACEC,uBAAuB,EACvBC,sBAAsB,EACtBC,WAAW,QAEN,iBAAc;AAOrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,OAAO,MAAMC,WAAW,GACtBC,WAAc,IAMdR,MAAM,CAACS,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOX,aAAa;EAElC;EACA;EACA;EACA,MAAMY,MAAM,GAAGR,YAAY,CAACK,WAAW,CAAC;EAExC;EACA,MAAMI,SAAS,GAAGd,kBAAkB,CAClCU,WAA4C,CAC7C;EAED;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAOH,sBAAsB,CAACG,WAA4C,CAAC;EAE3E;EACA;EACA;EACA,MAAMK,QAAQ,GAAG,OAAOP,WAAW,CAACM,SAAS,CAACE,KAAK,CAAC;EAEpD,MAAM;IAAEC,MAAM;IAAEC;EAAI,CAAE,GAAG,OAAON,KAAK,CAACO,IAAI,CAACL,SAAS,CAACE,KAAK,CAAC;EAE3D,MAAMI,OAAO,GAAGP,MAAM,CAACI,MAAM,CAAC;EAE9B,MAAMI,KAAK,GAAI,OAAOjB,MAAM,CAACkB,OAAO,CAClCF,OAAO,EACPN,SAAS,CAACS,YAAY,EACtB,CAACC,GAAG,EAAEC,KAAK,KAAKX,SAAS,CAACY,MAAM,CAACF,GAAG,EAAEC,KAAK,CAAC,CACvB;EAEvB;EACA;EACA;EACA,OAAOV,QAAQ,CAACG,IAAI,CAAC;EAErB,OAAO;IAAEG,KAAK;IAAEH;EAAI,CAAE;AACxB,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,OAAO,MAAMS,kBAAkB,GAC7BjB,WAAc,IASdR,MAAM,CAACS,GAAG,CAAC,aAAS;EAClB,MAAM;IAAEU,KAAK;IAAEH;EAAI,CAAE,GAAG,OAAOT,WAAW,CAACC,WAAW,CAAC;EAEvD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMkB,OAAO,GAAG,OAAOtB,uBAAuB;EAC9C,IAAIH,MAAM,CAAC0B,MAAM,CAACD,OAAO,CAAC,EAAE;IAC1B,OAAO;MAAEP,KAAK;MAAES,eAAe,EAAEF,OAAO,CAACG;IAAK,CAAE;EAClD;EAEA;EACA,OAAO;IACLV,KAAK;IACLS,eAAe,EAAE;MACfE,iBAAiB,EAAEhC,kBAAkB,CACnCU,WAA4C,CAC7C,CAACM,KAAK;MACPiB,KAAK,EAAEf;;GAEV;AACH,CAAC,CAAC","ignoreList":[]}