@kairos-es/codec 0.0.0 → 1.0.0-alpha.1

package/README.md

@@ -2,6 +2,15 @@
 
 Schema-first codec with an encryption seam for kairos-es (ADR-0004).
 
+## Installation
+
+`@kairos-es/core` and `effect` are peer dependencies, so the application owns the
+single shared Effect instance (per [ADR-0003](../../docs/adr)):
+
+```sh
+pnpm add @kairos-es/codec@alpha @kairos-es/core@alpha effect
+```
+
 The typed-payload to opaque-bytes seam: `event(type, fields, tagsFor)` defines a
 tagged `Schema` together with the mapper that derives an event's tags from its own
 payload (ADR-0006); `projection(init).on(def, fold)…build()` builds the slices a
@@ -21,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
@@ -28,9 +73,29 @@ 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.
+
+⚠ **`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

@@ -135,8 +135,15 @@ const decider = (projections, decide) => ({
  * (`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* () {

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","_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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DO,MAAMG,OAAO,GAAGA,CASrBC,WAAoC,EACpCC,MAA2D,MAO1D;EAAED,WAAW;EAAEC;AAAM,CAAE,CAKvB;AAEH;;;;;;;;;;;;;;;;;;;;AAAAC,OAAA,CAAAH,OAAA,GAAAA,OAAA;AAoBO,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":[]}

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,18 @@ Object.defineProperty(exports, "CodecError", {
     return _errors.CodecError;
   }
 });
+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 +33,12 @@ Object.defineProperty(exports, "SerializerDefault", {
     return _Serializer.SerializerDefault;
   }
 });
+Object.defineProperty(exports, "TaglessSliceInLedger", {
+  enumerable: true,
+  get: function () {
+    return _readLedger.TaglessSliceInLedger;
+  }
+});
 Object.defineProperty(exports, "UnknownEventType", {
   enumerable: true,
   get: function () {
@@ -51,6 +69,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 () {
@@ -99,12 +123,26 @@ 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 _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","_decisionModel","_decode","_errors","_event","_precondition","_projection","_readLedger","_registry","_Serializer","_toEvent","_Uuid"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA,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,aAAA,GAAAL,OAAA;AAMA,IAAAM,WAAA,GAAAN,OAAA;AAKA,IAAAO,WAAA,GAAAP,OAAA;AAOA,IAAAQ,SAAA,GAAAR,OAAA;AACA,IAAAS,WAAA,GAAAT,OAAA;AACA,IAAAU,QAAA,GAAAV,OAAA;AACA,IAAAW,KAAA,GAAAX,OAAA","ignoreList":[]}

package/dist/cjs/precondition.js

@@ -0,0 +1,174 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.unsafeAppend = exports.transact = exports.decideOnly = void 0;
+var _core = require("@kairos-es/core");
+var _effect = require("effect");
+var _decisionModel = require("./decisionModel.js");
+var _readLedger = require("./readLedger.js");
+/**
+ * The DCB command cycle MINUS the append: read the decision model, decode, fold,
+ * decide, and RETURN the events for the bracket to append.
+ *
+ * Bracket-only, and the refusal is STATIC — see the section below for the mechanism
+ * and, more importantly, for where the error actually lands, which is not where a
+ * reader first expects. Forced through anyway, being outside a bracket is a DEFECT
+ * rather than an error-channel value: it is not a data-dependent outcome a caller
+ * could handle, and the events produced would be dropped with nothing to append them.
+ *
+ * It is also what makes the nesting refusal liveable. A command runner inside a
+ * bracket is refused at the store, and this is the function a builder reaches for
+ * instead — one identifier away. A refusal is only affordable when the fix is that
+ * close.
+ *
+ * `modelAtHead` and NOT `buildDecisionModel`: this function must not derive a
+ * condition at all. The bracket owns that, and owning it in ONE place is what
+ * stops a caller appending under the last hop's condition alone.
+ *
+ * ## Bracket-only is a REQUIREMENT, so `tsc` refuses it rather than a run
+ *
+ * `ReadLedger` is named in the requirement channel and `transact` is the only thing
+ * that provides it, so a program that calls this outside a bracket cannot be RUN,
+ * and `tsc` is what says so — nothing has to execute for a caller to be told.
+ *
+ * ⚠ Measured, because the obvious stronger reading is wrong: the call site itself
+ * COMPILES. A bare `decideOnly(d, cmd)` outside a bracket is fine, and so is an
+ * exported helper over it; the requirement just propagates, as any unmet requirement
+ * does. What fails is the DISCHARGE — `Effect.provide`, `runPromise`, an annotation
+ * asking for `R = never` — possibly in another file. That is still a static refusal
+ * and it is the whole gain over the runtime defect this replaced. It is not a
+ * squiggle under the mistake.
+ *
+ * That is a PRESENCE check, and presence is the direction the type system can
+ * decide here — the same direction `transact`'s `Exclude<R, Id>` already spends on
+ * the precondition's output. ADR-0014's 2026-08-29 amendment carries the rule that
+ * follows: look for a presence check before reaching for a defect. This function
+ * shipped a defect first, and the check was available all along.
+ *
+ * ⚠ Two lines carry it and their JOBS differ. The RETURN ANNOTATION is the surface a
+ * consumer is judged against, and what the discharge above meets. The
+ * `yield* ReadLedger` keeps the requirement in the INFERRED type, so it survives the
+ * annotation being edited, and it dies at run time for the audience no type reaches
+ * — a JavaScript consumer runs no compile step — rather than handing back events
+ * with no bracket to append them. Nothing here READS the ledger; `modelAtHead` does
+ * the recording, ambiently, through `Effect.serviceOption`.
+ *
+ * ⚠ Do not try to write down which check catches which deletion. It was tried twice
+ * and was wrong twice, and `test/appendOwnership.test.ts` in the source repository
+ * says why the second failure means there should be no third attempt. Plant the
+ * mutation instead.
+ */
+const decideOnly = (decider, command) => _effect.Effect.gen(function* () {
+  yield* _readLedger.ReadLedger;
+  const {
+    state
+  } = yield* (0, _decisionModel.modelAtHead)(decider.projections(command));
+  return yield* decider.decide(state, command);
+});
+/**
+ * The sanctioned exception to the nesting refusal: append these events under NO
+ * condition, and say in the identifier and in a required `reason` why that is
+ * deliberate.
+ *
+ * It covers three cases and no others: deliberate narrowing, a genuinely
+ * unconditional creation, and a second append inside one bracket. The `reason` is
+ * ceremony on purpose, and ADR-0014 decision 6 owns why a hatch has to cost more
+ * than the safe path — that argument is a DECISION and belongs to the record that
+ * took it, so it is not restated here. How biome turns a required argument into a
+ * review signal is the source repository's `biome-plugins/unsafeAppendReported.grit`.
+ *
+ * ⚠ It BYPASSES the derived condition rather than composing with it. A caller who
+ * genuinely needs *the union, minus one event type* must restate the whole
+ * condition here. If that turns up in practice, a composing override is the
+ * additive answer and this hatch is not it.
+ *
+ * `Effect.mapInputContext` over
+ * `Context.omit(AppendIsOwned)` is what lets it through the store's ownership
+ * refusal — the one route, and `AppendIsOwned.ts` owns why removing the marker is
+ * the shape rather than a second tag or a sanctioning flag.
+ */
+exports.decideOnly = decideOnly;
+const unsafeAppend = (events,
+// Required by the signature and never read, which IS the mechanism: the value a
+// caller has to write is what a reviewer sees in the diff, and `tsc` refuses the
+// call that omits it. A lint rule asserting the same arity existed and was
+// deleted, on the ground that the type already refuses it — which made that
+// ground load-bearing, so `test/appendOwnership.test.ts` in the source repository
+// pins it. Reading the value here would give it a second job and a second place to
+// be wrong.
+//
+// NOT `_reason`, though it is unused. This name SHIPS — it is what a consumer's
+// editor offers and what the published `.d.ts` carries — and a leading underscore
+// is this ecosystem's way of saying "ignore me", which is the opposite of what a
+// required argument whose whole purpose is to be read by a human should say.
+// biome-ignore lint/correctness/noUnusedFunctionParameters: unread on purpose; this name ships in the .d.ts and an underscore would tell a consumer to ignore it
+reason) => _effect.Effect.flatMap(_core.DcbEventStore, store =>
+// ⛔ DO NOT SIMPLIFY THIS. The annotation reads as "map an empty context to an
+// empty context", and the types say nothing else — but `Context.omit` runs
+// against the RUNTIME context, which inside a bracket holds `AppendIsOwned`,
+// and removing it is the entire reason this function can append at all. That
+// marker is deliberately absent from every signature (it is read through
+// `Effect.serviceOption`, which is what keeps it out of `append`'s requirement
+// channel), so nothing here will fail to compile if this is deleted — what
+// catches it is `test/appendOwnership.test.ts` in the source repository, not the
+// type checker.
+_effect.Effect.mapInputContext(store.append(events), context => _effect.Context.omit(_core.AppendIsOwned)(context)));
+/**
+ * Open a bracket over ONE decision: evaluate the precondition inside it, hand its
+ * output to the body under the precondition's tag, and append what the body
+ * produced under the union of every read either of them performed.
+ *
+ * Curried so the precondition reads as the thing the command DECLARES and the body
+ * reads as the thing it DOES.
+ *
+ * The ownership marker is provided ALONGSIDE the ledger and to the body only, so
+ * any append inside the body — a nested bracket, a command runner, a raw
+ * `store.append` — is refused at the store as a defect, while the bracket's own
+ * closing append below runs outside that scope and is unaffected. That is why the
+ * refusal is on APPENDING rather than on opening a bracket: a command runner
+ * appends without opening one, and its events usually match the union the bracket
+ * is about to guard on, so the bracket's own close would be refused by a condition
+ * its own body invalidated.
+ */
+exports.unsafeAppend = unsafeAppend;
+const transact = precondition => body => _effect.Effect.gen(function* () {
+  const store = yield* _core.DcbEventStore;
+  const ledger = yield* _readLedger.makeReadLedger;
+  const events = yield* _effect.Effect.gen(function* () {
+    // ORDER IS THE DESIGN. The precondition runs first and runs HERE, with the
+    // ledger already in context, so its reads are hops in the very condition
+    // that will guard the body's write.
+    const proof = yield* precondition.evaluate;
+    return yield* body.pipe(_effect.Effect.provideService(precondition.tag, proof));
+  }).pipe(
+  // ONE layer, not two provisions, and it is the ANNOTATION above that makes
+  // that mandatory rather than tidy.
+  //
+  // TypeScript does not simplify a deferred conditional over an unresolved
+  // type variable, so `Exclude<Exclude<X, A>, B>` and
+  // `Exclude<X, A | B>` are unrelated types while `X` is still a parameter,
+  // and every provision here adds one level of nesting the annotation has to
+  // mirror EXACTLY. Both halves measured, each as a `TS2719` at the return
+  // annotation: two chained provisions refuse the flat
+  // `Exclude<PR, ReadLedger | AppendIsOwned>`, and even with this merge the
+  // flat `Exclude<R, Id | ReadLedger | AppendIsOwned>` is refused too,
+  // because the precondition's own tag is provided separately and further in.
+  // So `PR` is flat and `R` is one deep, and that asymmetry is the pipeline
+  // showing through rather than a slip.
+  //
+  // Merging says what is true anyway, which is why it is the fix rather than
+  // a cast: the ledger and the ownership marker have one lifetime and one
+  // meaning between them, and that meaning is *you are inside a bracket*.
+  _effect.Effect.provide(_effect.Layer.merge(ledger.layer, _effect.Layer.succeed(_core.AppendIsOwned, {
+    by: 'transact'
+  }))));
+  const condition = (0, _readLedger.deriveLayeredCondition)(yield* ledger.hops);
+  if (condition === undefined) {
+    return yield* new _readLedger.NoReadsRecorded();
+  }
+  return yield* store.append(events, condition);
+});
+exports.transact = transact;
+//# sourceMappingURL=precondition.js.map

package/dist/cjs/precondition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"precondition.js","names":["_core","require","_effect","_decisionModel","_readLedger","decideOnly","decider","command","Effect","gen","ReadLedger","state","modelAtHead","projections","decide","exports","unsafeAppend","events","reason","flatMap","DcbEventStore","store","mapInputContext","append","context","Context","omit","AppendIsOwned","transact","precondition","body","ledger","makeReadLedger","proof","evaluate","pipe","provideService","tag","provide","Layer","merge","layer","succeed","by","condition","deriveLayeredCondition","hops","undefined","NoReadsRecorded"],"sources":["../../src/precondition.ts"],"sourcesContent":[null],"mappings":";;;;;;AAyFA,IAAAA,KAAA,GAAAC,OAAA;AAEA,IAAAC,OAAA,GAAAD,OAAA;AAEA,IAAAE,cAAA,GAAAF,OAAA;AAGA,IAAAG,WAAA,GAAAH,OAAA;AAsCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDO,MAAMI,UAAU,GAAGA,CAMxBC,OAAkC,EAClCC,OAAgB,KAMhBC,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,OAAOC,sBAAU;EAEjB,MAAM;IAAEC;EAAK,CAAE,GAAG,OAAO,IAAAC,0BAAW,EAACN,OAAO,CAACO,WAAW,CAACN,OAAO,CAAC,CAAC;EAClE,OAAO,OAAOD,OAAO,CAACQ,MAAM,CAACH,KAAK,EAAEJ,OAAO,CAAC;AAC9C,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;AAAAQ,OAAA,CAAAV,UAAA,GAAAA,UAAA;AAsBO,MAAMW,YAAY,GAAGA,CAC1BC,MAA2C;AAC3C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACAC,MAAc,KAEdV,cAAM,CAACW,OAAO,CAACC,mBAAa,EAAGC,KAAK;AAClC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACAb,cAAM,CAACc,eAAe,CACpBD,KAAK,CAACE,MAAM,CAACN,MAAM,CAAC,EACnBO,OAA+B,IAAKC,eAAO,CAACC,IAAI,CAACC,mBAAa,CAAC,CAACH,OAAO,CAAC,CAC1E,CACF;AAEH;;;;;;;;;;;;;;;;;AAAAT,OAAA,CAAAC,YAAA,GAAAA,YAAA;AAiBO,MAAMY,QAAQ,GACGC,YAA+C,IAEnEC,IAA8D,IAQ9DtB,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMY,KAAK,GAAG,OAAOD,mBAAa;EAClC,MAAMW,MAAM,GAAG,OAAOC,0BAAc;EAEpC,MAAMf,MAAM,GAAG,OAAOT,cAAM,CAACC,GAAG,CAAC,aAAS;IACxC;IACA;IACA;IACA,MAAMwB,KAAK,GAAG,OAAOJ,YAAY,CAACK,QAAQ;IAC1C,OAAO,OAAOJ,IAAI,CAACK,IAAI,CAAC3B,cAAM,CAAC4B,cAAc,CAACP,YAAY,CAACQ,GAAG,EAAEJ,KAAK,CAAC,CAAC;EACzE,CAAC,CAAC,CAACE,IAAI;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA3B,cAAM,CAAC8B,OAAO,CACZC,aAAK,CAACC,KAAK,CACTT,MAAM,CAACU,KAAK,EACZF,aAAK,CAACG,OAAO,CAACf,mBAAa,EAAE;IAAEgB,EAAE,EAAE;EAAU,CAAE,CAAC,CACjD,CACF,CACF;EAED,MAAMC,SAAS,GAAG,IAAAC,kCAAsB,EAAC,OAAOd,MAAM,CAACe,IAAI,CAAC;EAC5D,IAAIF,SAAS,KAAKG,SAAS,EAAE;IAC3B,OAAO,OAAO,IAAIC,2BAAe,EAAE;EACrC;EAEA,OAAO,OAAO3B,KAAK,CAACE,MAAM,CAACN,MAAM,EAAE2B,SAAS,CAAC;AAC/C,CAAC,CAAC;AAAA7B,OAAA,CAAAa,QAAA,GAAAA,QAAA","ignoreList":[]}