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

package/README.md

@@ -30,6 +30,42 @@ because it touches none of that package's machinery, and it is deliberately not
 a decider calls: `runDecider` already folds to head through `buildDecisionModel`,
 under the condition that read produces.
 
+`transact(precondition)(body)` is the LAYERED write path, for a decision whose second
+query cannot be written until an earlier read has been folded — the identifier it needs
+is data that fold produced, and better tagging cannot remove the hop. Outside a bracket
+nothing changes and no signature moves. Inside one, every read is recorded wherever and
+by whatever symbol it happened, and the bracket appends what the body returned under the
+union of every query walked, at the EARLIEST head observed. No append condition reaches
+you, so there is none to assemble wrongly — and the familiar `buildDecisionModel`, which
+guards only its own hop outside a bracket, derives from the whole walk inside one.
+
+The bracket takes ONE precondition, a `{ tag, evaluate }` pair it evaluates INSIDE the
+ledger so the guard's own reads are part of what guards the write; its result reaches the
+body as a service, so a body that consumes it cannot be run without one. `decideOnly`
+returns a decider's events for the bracket to append. `unsafeAppend(events, reason)` is
+the one sanctioned append under no condition, and the reason is required.
+
+⚠ Three things to know before you use it. **Wrap conflict retry around the whole
+bracket**, never inside it: a retry within one re-records into the ledger already
+open and its floor cannot advance. **`modelAtHead`'s error channel carries
+`TaglessSliceInLedger`**, raised when a slice built without tags would be unioned
+with another — build every slice a layered decision reads with
+`build({ tags: [...] })`.
+
+And ⚠⚠ **inside a bracket, read through `modelAtHead` and nothing else.** A read
+that consults a projection, a materialised view or raw SQL contributes no hop, so
+its query is absent from the derived union and its head is absent from the floor:
+the decision rests on data the append is not guarded on, and the bracket LOOKS
+guarded. Nothing will tell you — not the types, not `NoReadsRecorded`, which fires
+only on a bracket that read nothing at all, and no lint rule, which could not see a
+read one call away in a helper and would not run in your tree in any case. If a
+read must consult a view, do it outside the bracket, where its answer is not part
+of what the append is guarded on.
+
+The reasoning for all of this is in
+[ADR-0014](../../docs/adr/0014-layered-decision-models-an-ambient-read-ledger-and-a-bracket-that-owns-the-append.md).
+The root README says why a repo-relative link does not resolve for you yet.
+
 `decodeSlices(slices)` is the decode stage `modelAtHead` folds through, and so in turn
 the one `buildDecisionModel` gets by building on `modelAtHead` — exported so the read
 side's `ProjectionRunner` shares one implementation over a live `subscribe` stream
@@ -37,9 +73,45 @@ rather than reimplementing it. `makeRegistry(defs)` is the minimal general
 path, decoding an arbitrary wire event by its runtime type string with an unknown
 type as a typed `UnknownEventType` (ADR-0005).
 
-`Decider` and `runDecider(decider, command)` close the write side's whole command
-cycle over that fold: build the decision model, decide, append under the read's
-own condition. `decider(projections, decide)` builds one with its slice record,
+`Decider` and `runDecider(decider, command)` close a SINGLE-HOP command cycle over
+that fold: build the decision model, decide, append under the read's own condition.
+
+A decision may also answer **`Unchanged`** — "already done, nothing to append" —
+with `Decision.unchanged(reason?)`. It is a success, not an error and not an empty
+batch: `runDecider` returns it in place of a `Position` and appends nothing, and
+`transact` does the same for a body that returns it (without refusing an empty
+bracket as `NoReadsRecorded`, since there is no write to guard). Test for it with
+`isUnchanged`, never with `instanceof` or its `_tag`: the first breaks across the
+dual ESM/CJS build, and the second would match your own union's member of the same
+name. A decider that cannot answer `Unchanged` keeps a plain `Position` result —
+an untyped (`any`) one, and one built in a wrapper generic in its success type,
+included — so no call site changes for code that never uses it. The one thing that
+does is a type query over a signature whose `O` is still open, such as
+`ReturnType<typeof runDecider>`: it now reads `Position | Unchanged`, and
+`typeof runDecider<P, Command, E, R>` gives `Position` back. `decider(...)` infers
+the widening from a branch returning `Decision.unchanged(...)`, and a hand-written
+`Decider` opts in with its fifth type argument, `DecisionOutput`.
+
+⚠ **`runDecider` and `decideOnly` are two dispositions of one cycle**, and each
+refuses exactly where the other is the answer:
+
+|              | outside a bracket              | inside a bracket                    |
+| ------------ | ------------------------------ | ----------------------------------- |
+| `runDecider` | ✅ the ordinary single-hop case | ⛔ refused as a defect when it runs  |
+| `decideOnly` | ⛔ unrunnable, and `tsc` says so | ✅ the layered case                 |
+
+So the remedy is always one identifier away and you never have to guess which you
+wanted. Neither is expressed over the other — each would have to defeat the other's
+refusal to be.
+
+⚠ *Unrunnable* rather than *unwritable*: a bare `decideOnly(...)` outside a bracket
+compiles, and so does a helper you export over it, because its `ReadLedger`
+requirement propagates like any other unmet one. The error lands where you DISCHARGE
+the context — `Effect.provide`, `runPromise`, or an annotation asking for
+`R = never` — which may be a different file. You are told by the type checker rather
+than by a failing run, which is the point; you are not told at the call.
+
+`decider(projections, decide)` builds one with its slice record,
 its error union and its extra requirement all inferred — the command type, on the
 `projections` parameter, is the only annotation a caller writes. They live here,
 beside the `buildDecisionModel` they drive, rather

package/dist/cjs/decider.js

@@ -3,9 +3,11 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.runDecider = exports.decider = void 0;
+exports.decider = decider;
+exports.runDecider = void 0;
 var _core = require("@kairos-es/core");
 var _effect = require("effect");
+var _decision = require("./decision.js");
 var _decisionModel = require("./decisionModel.js");
 /**
  * A `Decider`: the write side's unit of decision. It pairs the projections a
@@ -61,92 +63,65 @@ var _decisionModel = require("./decisionModel.js");
  * 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.
- */
-
-/**
- * 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.
+ * `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.
  */
-const decider = (projections, decide) => ({
-  projections,
-  decide
-});
+
+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.
  */
-exports.decider = decider;
 const runDecider = (decider, command) => _effect.Effect.gen(function* () {
   const store = yield* _core.DcbEventStore;
   const {
     state,
     appendCondition
   } = yield* (0, _decisionModel.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 ((0, _decision.isUnchanged)(output)) {
+    return output;
+  }
+  return yield* store.append(output, appendCondition);
 });
 exports.runDecider = runDecider;
 //# sourceMappingURL=decider.js.map

package/dist/cjs/decider.js.map

@@ -1 +1 @@
-{"version":3,"file":"decider.js","names":["_core","require","_effect","_decisionModel","decider","projections","decide","exports","runDecider","command","Effect","gen","store","DcbEventStore","state","appendCondition","buildDecisionModel","newEvents","append"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":";;;;;;AA8DA,IAAAA,KAAA,GAAAC,OAAA;AAEA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,cAAA,GAAAF,OAAA;AAjEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DO,MAAMG,OAAO,GAAGA,CASrBC,WAAoC,EACpCC,MAA2D,MAO1D;EAAED,WAAW;EAAEC;AAAM,CAAE,CAKvB;AAEH;;;;;;;;;;;;;AAAAC,OAAA,CAAAH,OAAA,GAAAA,OAAA;AAaO,MAAMI,UAAU,GAAGA,CAMxBJ,OAAkC,EAClCK,OAAgB,KAMhBC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOC,mBAAa;EAClC,MAAM;IAAEC,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAO,IAAAC,iCAAkB,EAC1DZ,OAAO,CAACC,WAAW,CAACI,OAAO,CAAC,CAC7B;EACD,MAAMQ,SAAS,GAAG,OAAOb,OAAO,CAACE,MAAM,CAACQ,KAAK,EAAEL,OAAO,CAAC;EACvD,OAAO,OAAOG,KAAK,CAACM,MAAM,CAACD,SAAS,EAAEF,eAAe,CAAC;AACxD,CAAC,CAAC;AAAAR,OAAA,CAAAC,UAAA,GAAAA,UAAA","ignoreList":[]}
+{"version":3,"file":"decider.js","names":["_core","require","_effect","_decision","_decisionModel","decider","projections","decide","runDecider","command","Effect","gen","store","DcbEventStore","state","appendCondition","buildDecisionModel","output","isUnchanged","append","exports"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":";;;;;;;AAwEA,IAAAA,KAAA,GAAAC,OAAA;AAEA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,SAAA,GAAAF,OAAA;AAKA,IAAAG,cAAA,GAAAH,OAAA;AAhFA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoOM,SAAUI,OAAOA,CACrBC,WAAoC,EACpCC,MAGoD;EAEpD,OAAO;IAAED,WAAW;IAAEC;EAAM,CAM3B;AACH;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBO,MAAMC,UAAU,GAAGA,CAOxBH,OAAqC,EACrCI,OAAgB,KAMhBC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOC,mBAAa;EAClC,MAAM;IAAEC,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAO,IAAAC,iCAAkB,EAC1DX,OAAO,CAACC,WAAW,CAACG,OAAO,CAAC,CAC7B;EACD,MAAMQ,MAAM,GAAmB,OAAOZ,OAAO,CAACE,MAAM,CAACO,KAAK,EAAEL,OAAO,CAAC;EACpE;EACA;EACA;EACA;EACA,IAAI,IAAAS,qBAAW,EAACD,MAAM,CAAC,EAAE;IACvB,OAAOA,MAA2B;EACpC;EACA,OAAQ,OAAOL,KAAK,CAACO,MAAM,CAACF,MAAM,EAAEF,eAAe,CAAC;AACtD,CAAC,CAAC;AAAAK,OAAA,CAAAZ,UAAA,GAAAA,UAAA","ignoreList":[]}

package/dist/cjs/decision.js

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isUnchanged = exports.UnchangedTypeId = exports.Unchanged = exports.Decision = void 0;
+var _effect = require("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.
+ */
+const UnchangedTypeId = exports.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.
+ */
+class Unchanged extends /*#__PURE__*/_effect.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.
+ */
+exports.Unchanged = Unchanged;
+const isUnchanged = u => _effect.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')`.
+ */
+exports.isUnchanged = isUnchanged;
+const Decision = exports.Decision = {
+  unchanged: reason => new Unchanged(reason === undefined ? {} : {
+    reason
+  })
+};
+//# sourceMappingURL=decision.js.map

package/dist/cjs/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","names":["_effect","require","UnchangedTypeId","exports","Symbol","for","Unchanged","Data","TaggedClass","isUnchanged","u","Predicate","hasProperty","Decision","unchanged","reason","undefined"],"sources":["../../src/decision.ts"],"sourcesContent":[null],"mappings":";;;;;;AA4FA,IAAAA,OAAA,GAAAC,OAAA;AAEA;;;;AAIO,MAAMC,eAAe,GAAAC,OAAA,CAAAD,eAAA,gBAAkBE,MAAM,CAACC,GAAG,CACtD,4BAA4B,CAC7B;AAKD;;;;;;;;;;;AAWM,MAAOC,SAAU,sBAAQC,YAAI,CAACC,WAAW,CAAC,WAAW,CAEzD;EACS,CAACN,eAAe,IAAqBA,eAAe;;AAG/D;;;;;AAAAC,OAAA,CAAAG,SAAA,GAAAA,SAAA;AAKO,MAAMG,WAAW,GAAIC,CAAU,IACpCC,iBAAS,CAACC,WAAW,CAACF,CAAC,EAAER,eAAe,CAAC;AAE3C;;;;;AAAAC,OAAA,CAAAM,WAAA,GAAAA,WAAA;AAKO,MAAMI,QAAQ,GAAAV,OAAA,CAAAU,QAAA,GAEjB;EACFC,SAAS,EAAGC,MAAM,IAAK,IAAIT,SAAS,CAACS,MAAM,KAAKC,SAAS,GAAG,EAAE,GAAG;IAAED;EAAM,CAAE;CAC5E","ignoreList":[]}

package/dist/cjs/decisionModel.js

@@ -7,6 +7,7 @@ exports.modelAtHead = exports.buildDecisionModel = void 0;
 var _core = require("@kairos-es/core");
 var _effect = require("effect");
 var _decode = require("./decode.js");
+var _readLedger = require("./readLedger.js");
 /**
  * Read-and-fold over a slice record: read the composed query, decode each event
  * through the matching def's `Schema` in an effectful `Stream.mapEffect` stage,
@@ -16,11 +17,18 @@ var _decode = require("./decode.js");
  * `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
@@ -58,6 +66,16 @@ var _decode = require("./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
@@ -89,12 +107,28 @@ const modelAtHead = projections => _effect.Effect.gen(function* () {
   const decode = (0, _decode.decodeSlices)(projections);
   // The pure fold: core composes the record (slices are AnyProjections).
   const composite = (0, _core.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* (0, _readLedger.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* (0, _readLedger.recordQuery)(composite.query);
   const {
     events,
     head
   } = yield* store.read(composite.query);
   const decoded = decode(events);
   const state = yield* _effect.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
@@ -113,17 +147,19 @@ const modelAtHead = projections => _effect.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
@@ -141,15 +177,35 @@ const modelAtHead = projections => _effect.Effect.gen(function* () {
  * soften the sentence.
  */
 exports.modelAtHead = modelAtHead;
-const buildDecisionModel = projections => _effect.Effect.map(modelAtHead(projections), ({
-  state,
-  head
-}) => ({
-  state,
-  appendCondition: {
-    failIfEventsMatch: (0, _core.composeProjections)(projections).query,
-    after: head
+const buildDecisionModel = projections => _effect.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* _readLedger.ambientLayeredCondition;
+  if (_effect.Option.isSome(ambient)) {
+    return {
+      state,
+      appendCondition: ambient.value
+    };
   }
-}));
+  // OUTSIDE a bracket this is byte-for-byte what shipped.
+  return {
+    state,
+    appendCondition: {
+      failIfEventsMatch: (0, _core.composeProjections)(projections).query,
+      after: head
+    }
+  };
+});
 exports.buildDecisionModel = buildDecisionModel;
 //# sourceMappingURL=decisionModel.js.map

package/dist/cjs/decisionModel.js.map

@@ -1 +1 @@
-{"version":3,"file":"decisionModel.js","names":["_core","require","_effect","_decode","modelAtHead","projections","Effect","gen","store","DcbEventStore","decode","decodeSlices","composite","composeProjections","events","head","read","query","decoded","state","Stream","runFold","initialState","acc","event","evolve","exports","buildDecisionModel","map","appendCondition","failIfEventsMatch","after"],"sources":["../../src/decisionModel.ts"],"sourcesContent":[null],"mappings":";;;;;;AA0BA,IAAAA,KAAA,GAAAC,OAAA;AAQA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AAnCA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CO,MAAMG,WAAW,GACtBC,WAAc,IAMdC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOC,mBAAa;EAElC;EACA;EACA;EACA,MAAMC,MAAM,GAAG,IAAAC,oBAAY,EAACN,WAAW,CAAC;EAExC;EACA,MAAMO,SAAS,GAAG,IAAAC,wBAAkB,EAClCR,WAA4C,CAC7C;EACD,MAAM;IAAES,MAAM;IAAEC;EAAI,CAAE,GAAG,OAAOP,KAAK,CAACQ,IAAI,CAACJ,SAAS,CAACK,KAAK,CAAC;EAE3D,MAAMC,OAAO,GAAGR,MAAM,CAACI,MAAM,CAAC;EAE9B,MAAMK,KAAK,GAAI,OAAOC,cAAM,CAACC,OAAO,CAClCH,OAAO,EACPN,SAAS,CAACU,YAAY,EACtB,CAACC,GAAG,EAAEC,KAAK,KAAKZ,SAAS,CAACa,MAAM,CAACF,GAAG,EAAEC,KAAK,CAAC,CACvB;EAEvB,OAAO;IAAEL,KAAK;IAAEJ;EAAI,CAAE;AACxB,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAAW,OAAA,CAAAtB,WAAA,GAAAA,WAAA;AAwCO,MAAMuB,kBAAkB,GAC7BtB,WAAc,IASdC,cAAM,CAACsB,GAAG,CAACxB,WAAW,CAACC,WAAW,CAAC,EAAE,CAAC;EAAEc,KAAK;EAAEJ;AAAI,CAAE,MAAM;EACzDI,KAAK;EACLU,eAAe,EAAE;IACfC,iBAAiB,EAAE,IAAAjB,wBAAkB,EACnCR,WAA4C,CAC7C,CAACY,KAAK;IACPc,KAAK,EAAEhB;;CAEV,CAAC,CAAC;AAAAW,OAAA,CAAAC,kBAAA,GAAAA,kBAAA","ignoreList":[]}
+{"version":3,"file":"decisionModel.js","names":["_core","require","_effect","_decode","_readLedger","modelAtHead","projections","Effect","gen","store","DcbEventStore","decode","decodeSlices","composite","composeProjections","assertServableAddition","closeHop","recordQuery","query","events","head","read","decoded","state","Stream","runFold","initialState","acc","event","evolve","exports","buildDecisionModel","ambient","ambientLayeredCondition","Option","isSome","appendCondition","value","failIfEventsMatch","after"],"sources":["../../src/decisionModel.ts"],"sourcesContent":[null],"mappings":";;;;;;AAiCA,IAAAA,KAAA,GAAAC,OAAA;AAQA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AAGA,IAAAG,WAAA,GAAAH,OAAA;AA7CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDO,MAAMI,WAAW,GACtBC,WAAc,IAMdC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOC,mBAAa;EAElC;EACA;EACA;EACA,MAAMC,MAAM,GAAG,IAAAC,oBAAY,EAACN,WAAW,CAAC;EAExC;EACA,MAAMO,SAAS,GAAG,IAAAC,wBAAkB,EAClCR,WAA4C,CAC7C;EAED;EACA;EACA;EACA;EACA;EACA;EACA;EACA,OAAO,IAAAS,kCAAsB,EAACT,WAA4C,CAAC;EAE3E;EACA;EACA;EACA,MAAMU,QAAQ,GAAG,OAAO,IAAAC,uBAAW,EAACJ,SAAS,CAACK,KAAK,CAAC;EAEpD,MAAM;IAAEC,MAAM;IAAEC;EAAI,CAAE,GAAG,OAAOX,KAAK,CAACY,IAAI,CAACR,SAAS,CAACK,KAAK,CAAC;EAE3D,MAAMI,OAAO,GAAGX,MAAM,CAACQ,MAAM,CAAC;EAE9B,MAAMI,KAAK,GAAI,OAAOC,cAAM,CAACC,OAAO,CAClCH,OAAO,EACPT,SAAS,CAACa,YAAY,EACtB,CAACC,GAAG,EAAEC,KAAK,KAAKf,SAAS,CAACgB,MAAM,CAACF,GAAG,EAAEC,KAAK,CAAC,CACvB;EAEvB;EACA;EACA;EACA,OAAOZ,QAAQ,CAACI,IAAI,CAAC;EAErB,OAAO;IAAEG,KAAK;IAAEH;EAAI,CAAE;AACxB,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAAU,OAAA,CAAAzB,WAAA,GAAAA,WAAA;AA0CO,MAAM0B,kBAAkB,GAC7BzB,WAAc,IASdC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAM;IAAEe,KAAK;IAAEH;EAAI,CAAE,GAAG,OAAOf,WAAW,CAACC,WAAW,CAAC;EAEvD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAM0B,OAAO,GAAG,OAAOC,mCAAuB;EAC9C,IAAIC,cAAM,CAACC,MAAM,CAACH,OAAO,CAAC,EAAE;IAC1B,OAAO;MAAET,KAAK;MAAEa,eAAe,EAAEJ,OAAO,CAACK;IAAK,CAAE;EAClD;EAEA;EACA,OAAO;IACLd,KAAK;IACLa,eAAe,EAAE;MACfE,iBAAiB,EAAE,IAAAxB,wBAAkB,EACnCR,WAA4C,CAC7C,CAACY,KAAK;MACPqB,KAAK,EAAEnB;;GAEV;AACH,CAAC,CAAC;AAAAU,OAAA,CAAAC,kBAAA,GAAAA,kBAAA","ignoreList":[]}

package/dist/cjs/index.js

@@ -9,6 +9,24 @@ Object.defineProperty(exports, "CodecError", {
     return _errors.CodecError;
   }
 });
+Object.defineProperty(exports, "Decision", {
+  enumerable: true,
+  get: function () {
+    return _decision.Decision;
+  }
+});
+Object.defineProperty(exports, "NoReadsRecorded", {
+  enumerable: true,
+  get: function () {
+    return _readLedger.NoReadsRecorded;
+  }
+});
+Object.defineProperty(exports, "ReadLedger", {
+  enumerable: true,
+  get: function () {
+    return _readLedger.ReadLedger;
+  }
+});
 Object.defineProperty(exports, "Serializer", {
   enumerable: true,
   get: function () {
@@ -21,6 +39,24 @@ Object.defineProperty(exports, "SerializerDefault", {
     return _Serializer.SerializerDefault;
   }
 });
+Object.defineProperty(exports, "TaglessSliceInLedger", {
+  enumerable: true,
+  get: function () {
+    return _readLedger.TaglessSliceInLedger;
+  }
+});
+Object.defineProperty(exports, "Unchanged", {
+  enumerable: true,
+  get: function () {
+    return _decision.Unchanged;
+  }
+});
+Object.defineProperty(exports, "UnchangedTypeId", {
+  enumerable: true,
+  get: function () {
+    return _decision.UnchangedTypeId;
+  }
+});
 Object.defineProperty(exports, "UnknownEventType", {
   enumerable: true,
   get: function () {
@@ -51,6 +87,12 @@ Object.defineProperty(exports, "buildDecisionModel", {
     return _decisionModel.buildDecisionModel;
   }
 });
+Object.defineProperty(exports, "decideOnly", {
+  enumerable: true,
+  get: function () {
+    return _precondition.decideOnly;
+  }
+});
 Object.defineProperty(exports, "decider", {
   enumerable: true,
   get: function () {
@@ -69,6 +111,12 @@ Object.defineProperty(exports, "event", {
     return _event.event;
   }
 });
+Object.defineProperty(exports, "isUnchanged", {
+  enumerable: true,
+  get: function () {
+    return _decision.isUnchanged;
+  }
+});
 Object.defineProperty(exports, "makeRegistry", {
   enumerable: true,
   get: function () {
@@ -99,12 +147,27 @@ Object.defineProperty(exports, "toEvent", {
     return _toEvent.toEvent;
   }
 });
+Object.defineProperty(exports, "transact", {
+  enumerable: true,
+  get: function () {
+    return _precondition.transact;
+  }
+});
+Object.defineProperty(exports, "unsafeAppend", {
+  enumerable: true,
+  get: function () {
+    return _precondition.unsafeAppend;
+  }
+});
 var _decider = require("./decider.js");
+var _decision = require("./decision.js");
 var _decisionModel = require("./decisionModel.js");
 var _decode = require("./decode.js");
 var _errors = require("./errors.js");
 var _event = require("./event.js");
+var _precondition = require("./precondition.js");
 var _projection = require("./projection.js");
+var _readLedger = require("./readLedger.js");
 var _registry = require("./registry.js");
 var _Serializer = require("./Serializer.js");
 var _toEvent = require("./toEvent.js");

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["_decider","require","_decisionModel","_decode","_errors","_event","_projection","_registry","_Serializer","_toEvent","_Uuid"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,IAAAA,QAAA,GAAAC,OAAA;AACA,IAAAC,cAAA,GAAAD,OAAA;AAKA,IAAAE,OAAA,GAAAF,OAAA;AACA,IAAAG,OAAA,GAAAH,OAAA;AACA,IAAAI,MAAA,GAAAJ,OAAA;AACA,IAAAK,WAAA,GAAAL,OAAA;AAKA,IAAAM,SAAA,GAAAN,OAAA;AACA,IAAAO,WAAA,GAAAP,OAAA;AACA,IAAAQ,QAAA,GAAAR,OAAA;AACA,IAAAS,KAAA,GAAAT,OAAA","ignoreList":[]}
+{"version":3,"file":"index.js","names":["_decider","require","_decision","_decisionModel","_decode","_errors","_event","_precondition","_projection","_readLedger","_registry","_Serializer","_toEvent","_Uuid"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuHA,IAAAA,QAAA,GAAAC,OAAA;AACA,IAAAC,SAAA,GAAAD,OAAA;AAQA,IAAAE,cAAA,GAAAF,OAAA;AAKA,IAAAG,OAAA,GAAAH,OAAA;AACA,IAAAI,OAAA,GAAAJ,OAAA;AACA,IAAAK,MAAA,GAAAL,OAAA;AACA,IAAAM,aAAA,GAAAN,OAAA;AAMA,IAAAO,WAAA,GAAAP,OAAA;AAKA,IAAAQ,WAAA,GAAAR,OAAA;AAOA,IAAAS,SAAA,GAAAT,OAAA;AACA,IAAAU,WAAA,GAAAV,OAAA;AACA,IAAAW,QAAA,GAAAX,OAAA;AACA,IAAAY,KAAA,GAAAZ,OAAA","ignoreList":[]}