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

package/README.md

@@ -76,6 +76,22 @@ type as a typed `UnknownEventType` (ADR-0005).
 `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:
 

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,74 +63,34 @@ 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
@@ -145,15 +107,21 @@ const decider = (projections, decide) => ({
  * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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":[]}
+{"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/index.js

@@ -9,6 +9,12 @@ 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 () {
@@ -39,6 +45,18 @@ Object.defineProperty(exports, "TaglessSliceInLedger", {
     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 () {
@@ -93,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 () {
@@ -136,6 +160,7 @@ Object.defineProperty(exports, "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");

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"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":[]}
+{"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":[]}

package/dist/cjs/precondition.js

@@ -6,11 +6,13 @@ Object.defineProperty(exports, "__esModule", {
 exports.unsafeAppend = exports.transact = exports.decideOnly = void 0;
 var _core = require("@kairos-es/core");
 var _effect = require("effect");
+var _decision = require("./decision.js");
 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.
+ * decide, and RETURN the events for the bracket to append — or the decider's
+ * `Unchanged`, passed through as it came, for the bracket to append nothing.
  *
  * 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
@@ -131,12 +133,18 @@ _effect.Effect.mapInputContext(store.append(events), context => _effect.Context.
  * 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.
+ *
+ * The body may succeed with `Unchanged` (see the module documentation), and the
+ * result is then `DecisionResult<O>`: `Position` for a body that cannot answer
+ * it, `Position | Unchanged` for one that can. `O` is last and defaulted, so an
+ * explicit `<E, R>` written against the narrower signature still means what it
+ * did.
  */
 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* () {
+  const output = 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.
@@ -164,11 +172,20 @@ const transact = precondition => body => _effect.Effect.gen(function* () {
   _effect.Effect.provide(_effect.Layer.merge(ledger.layer, _effect.Layer.succeed(_core.AppendIsOwned, {
     by: 'transact'
   }))));
+  // "Already done": nothing to append, so no condition to derive and nothing
+  // for `NoReadsRecorded` to protect — that refusal guards a WRITE that would
+  // go out unguarded, and there is none. It must stay BEFORE the derivation,
+  // or an empty bracket answering `Unchanged` would be refused for a write it
+  // never asked for. The casts restate `DecisionResult<O>`, which the checker
+  // cannot relate to either branch while `O` is still a type variable.
+  if ((0, _decision.isUnchanged)(output)) {
+    return output;
+  }
   const condition = (0, _readLedger.deriveLayeredCondition)(yield* ledger.hops);
   if (condition === undefined) {
     return yield* new _readLedger.NoReadsRecorded();
   }
-  return yield* store.append(events, condition);
+  return yield* store.append(output, condition);
 });
 exports.transact = transact;
 //# sourceMappingURL=precondition.js.map

package/dist/cjs/precondition.js.map

@@ -1 +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":[]}
+{"version":3,"file":"precondition.js","names":["_core","require","_effect","_decision","_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","output","proof","evaluate","pipe","provideService","tag","provide","Layer","merge","layer","succeed","by","isUnchanged","condition","deriveLayeredCondition","hops","undefined","NoReadsRecorded"],"sources":["../../src/precondition.ts"],"sourcesContent":[null],"mappings":";;;;;;AAwGA,IAAAA,KAAA,GAAAC,OAAA;AAEA,IAAAC,OAAA,GAAAD,OAAA;AAEA,IAAAE,SAAA,GAAAF,OAAA;AAKA,IAAAG,cAAA,GAAAH,OAAA;AAGA,IAAAI,WAAA,GAAAJ,OAAA;AAsCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDO,MAAMK,UAAU,GAAGA,CAOxBC,OAAqC,EACrCC,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;AAuBO,MAAMY,QAAQ,GACGC,YAA+C,IAEnEC,IAA4B,IAQ5BtB,cAAM,CAACC,GAAG,CAAC,aAAS;EAClB,MAAMY,KAAK,GAAG,OAAOD,mBAAa;EAClC,MAAMW,MAAM,GAAG,OAAOC,0BAAc;EAEpC,MAAMC,MAAM,GAAmB,OAAOzB,cAAM,CAACC,GAAG,CAAC,aAAS;IACxD;IACA;IACA;IACA,MAAMyB,KAAK,GAAG,OAAOL,YAAY,CAACM,QAAQ;IAC1C,OAAO,OAAOL,IAAI,CAACM,IAAI,CAAC5B,cAAM,CAAC6B,cAAc,CAACR,YAAY,CAACS,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;EACA5B,cAAM,CAAC+B,OAAO,CACZC,aAAK,CAACC,KAAK,CACTV,MAAM,CAACW,KAAK,EACZF,aAAK,CAACG,OAAO,CAAChB,mBAAa,EAAE;IAAEiB,EAAE,EAAE;EAAU,CAAE,CAAC,CACjD,CACF,CACF;EAED;EACA;EACA;EACA;EACA;EACA;EACA,IAAI,IAAAC,qBAAW,EAACZ,MAAM,CAAC,EAAE;IACvB,OAAOA,MAA2B;EACpC;EAEA,MAAMa,SAAS,GAAG,IAAAC,kCAAsB,EAAC,OAAOhB,MAAM,CAACiB,IAAI,CAAC;EAC5D,IAAIF,SAAS,KAAKG,SAAS,EAAE;IAC3B,OAAO,OAAO,IAAIC,2BAAe,EAAE;EACrC;EAEA,OAAQ,OAAO7B,KAAK,CAACE,MAAM,CAACU,MAAM,EAAEa,SAAS,CAAC;AAChD,CAAC,CAAC;AAAA/B,OAAA,CAAAa,QAAA,GAAAA,QAAA","ignoreList":[]}

package/dist/dts/decider.d.ts

@@ -52,11 +52,23 @@
  * boundary, and decode may fail with `CodecError`. All surface on the error
  * channel, so a caller handles all three the same way — and
  * `@kairos-es/testing`'s `.thenError(tag)` can assert any of them.
+ *
+ * `decide` may also answer `Unchanged` — "already done, nothing to append" — but
+ * only where its type says so: `Decider`'s fifth type parameter `O` defaults to
+ * the non-empty batch, and `runDecider` returns `DecisionResult<O>`, which is
+ * plain `Position` unless `O` admits `Unchanged`. So a decider that cannot say
+ * "already done" keeps exactly the result type it always had — an untyped one
+ * and one built in a wrapper generic in its success type included — and one
+ * that can makes its caller handle `Position | Unchanged`. `runDecider` returns an
+ * `Unchanged` without calling `append`, so `append`'s refusal of an empty batch
+ * is untouched and never met. `decision.ts` owns why it is a success rather than
+ * an error or an empty batch, and why it is recognised by a type id.
  */
-import type { AppendConditionFailed, CompositeState, DcbEvent, Position } from '@kairos-es/core';
+import type { AppendConditionFailed, CompositeState, DcbEvent } from '@kairos-es/core';
 import { DcbEventStore } from '@kairos-es/core';
 import type { Array as Arr } from 'effect';
 import { Effect } from 'effect';
+import { type DecisionOutput, type DecisionResult } from './decision.js';
 import { type RequirementOf } from './decisionModel.js';
 import type { CodecError } from './errors.js';
 import type { SliceProjection } from './projection.js';
@@ -77,10 +89,17 @@ import type { Uuid } from './Uuid.js';
  * schema-backed, state-erased bound for a heterogeneous record); the
  * precise per-key state is recovered by core's shared `CompositeState`. The
  * requirement `R` is the union carried by the record's slices' schemas.
+ *
+ * `O` is what `decide` may succeed with. It defaults to the non-empty batch, and
+ * a decider that can answer "already done" widens it to `DecisionOutput`
+ * (`NonEmptyReadonlyArray<DcbEvent> | Unchanged`). It is LAST and DEFAULTED so
+ * that every `Decider<P, Command, E, R>` already written means exactly what it
+ * meant. Its bound is `DecisionOutput`, which still excludes a possibly-empty
+ * array — the widening adds an answer and removes no guarantee.
  */
-export interface Decider<P extends Record<string, SliceProjection>, Command, E = never, R = never> {
+export interface Decider<P extends Record<string, SliceProjection>, Command, E = never, R = never, O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>> {
     readonly projections: (command: Command) => P;
-    readonly decide: (state: CompositeState<P>, command: Command) => Effect.Effect<Arr.NonEmptyReadonlyArray<DcbEvent>, E, Serializer | Uuid | R>;
+    readonly decide: (state: CompositeState<P>, command: Command) => Effect.Effect<O, E, Serializer | Uuid | R>;
 }
 /**
  * Build a `Decider` with all four of its type arguments INFERRED: the slice
@@ -129,6 +148,22 @@ export interface Decider<P extends Record<string, SliceProjection>, Command, E =
  * Effect.Error<Eff>, …>`. The value is the two functions it was handed, so
  * there is nothing for the cast to be wrong about.
  *
+ * The success channel is how a decider opts into `Unchanged` without writing a
+ * fifth type argument, and it is why this function is declared TWICE. The first
+ * declaration bounds `Eff` by the non-empty batch and returns a `Decider` with
+ * the DEFAULT `O`; the second bounds it by `DecisionOutput` and returns one whose
+ * `O` is `DecisionOutput`. A `decide` with a branch returning
+ * `Decision.unchanged(…)` fails the first bound and lands on the second, and one
+ * with no such branch keeps the default. Either way `O` is one of the two a
+ * caller ever writes, never the inferred success type passed through: inference
+ * is more precise than anyone writes — the produce path's one-element tuple, say
+ * — and a `Decider<…, readonly [DcbEvent]>` would not be the
+ * `Decider<P, Command, E, R>` its caller spells, though it behaves identically.
+ * Asking by ASSIGNABILITY rather than by a conditional over `Eff`'s success is
+ * what keeps an untyped (`any`) success, and a success that is a type variable
+ * bounded by the batch, on the default; `decision.ts` owns that argument, and
+ * the one type query the pair cannot answer as before.
+ *
  * `R` excludes `Serializer | Uuid` because that is what `R` MEANS on `Decider`:
  * the interface writes decide's requirement as `Serializer | Uuid | R`, so `R`
  * is what the produce side needs BEYOND the codec's own two services. Leaving
@@ -140,11 +175,17 @@ export interface Decider<P extends Record<string, SliceProjection>, Command, E =
  * `@kairos-es/codec/Serializer` matches — and a tag under that key IS that
  * service, context being keyed by the same string at runtime.
  */
-export declare const decider: <P extends Record<string, SliceProjection>, Command, Eff extends Effect.Effect<Arr.NonEmptyReadonlyArray<DcbEvent>, unknown, unknown>>(projections: (command: Command) => P, decide: (state: CompositeState<P>, command: Command) => Eff) => Decider<P, Command, Effect.Effect.Error<Eff>, Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>>;
+export declare function decider<P extends Record<string, SliceProjection>, Command, Eff extends Effect.Effect<Arr.NonEmptyReadonlyArray<DcbEvent>, unknown, unknown>>(projections: (command: Command) => P, decide: (state: CompositeState<P>, command: Command) => Eff): Decider<P, Command, Effect.Effect.Error<Eff>, Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>>;
+export declare function decider<P extends Record<string, SliceProjection>, Command, Eff extends Effect.Effect<DecisionOutput, unknown, unknown>>(projections: (command: Command) => P, decide: (state: CompositeState<P>, command: Command) => Eff): Decider<P, Command, Effect.Effect.Error<Eff>, Exclude<Effect.Effect.Context<Eff>, Serializer | Uuid>, DecisionOutput>;
 /**
  * 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
@@ -161,5 +202,5 @@ export declare const decider: <P extends Record<string, SliceProjection>, Comman
  * answer, and why neither can be expressed over the other. Read it before
  * changing either signature; this file does not restate the argument.
  */
-export declare const runDecider: <P extends Record<string, SliceProjection>, Command, E, R>(decider: Decider<P, Command, E, R>, command: Command) => Effect.Effect<Position, E | CodecError | AppendConditionFailed | TaglessSliceInLedger, DcbEventStore | Serializer | Uuid | R | RequirementOf<P>>;
+export declare const runDecider: <P extends Record<string, SliceProjection>, Command, E, R, O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>>(decider: Decider<P, Command, E, R, O>, command: Command) => Effect.Effect<DecisionResult<O>, E | CodecError | AppendConditionFailed | TaglessSliceInLedger, DcbEventStore | Serializer | Uuid | R | RequirementOf<P>>;
 //# sourceMappingURL=decider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"decider.d.ts","sourceRoot":"","sources":["../../src/decider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,cAAc,EACd,QAAQ,EACR,QAAQ,EACT,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAElC;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,OAAO,CACtB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,OAAO,EACP,CAAC,GAAG,KAAK,EACT,CAAC,GAAG,KAAK;IAET,QAAQ,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,CAAA;IAC7C,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EACxB,OAAO,EAAE,OAAO,KACb,MAAM,CAAC,MAAM,CAChB,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EACnC,CAAC,EACD,UAAU,GAAG,IAAI,GAAG,CAAC,CACtB,CAAA;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,OAAO,GAClB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,OAAO,EACP,GAAG,SAAS,MAAM,CAAC,MAAM,CACvB,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EACnC,OAAO,EACP,OAAO,CACR,EAED,aAAa,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,EACpC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,GAAG,KAC1D,OAAO,CACR,CAAC,EACD,OAAO,EACP,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EACxB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC,CAOrD,CAAA;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,UAAU,GACrB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,OAAO,EACP,CAAC,EACD,CAAC,EAED,SAAS,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,EAClC,SAAS,OAAO,KACf,MAAM,CAAC,MAAM,CACd,QAAQ,EACR,CAAC,GAAG,UAAU,GAAG,qBAAqB,GAAG,oBAAoB,EAC7D,aAAa,GAAG,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAStD,CAAA"}
+{"version":3,"file":"decider.d.ts","sourceRoot":"","sources":["../../src/decider.ts"],"names":[],"mappings":"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"}

package/dist/dts/decision.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../../src/decision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EAAE,KAAK,KAAK,IAAI,GAAG,EAAmB,MAAM,QAAQ,CAAA;AAE3D;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,MAEpC,CAAA;AAED,qCAAqC;AACrC,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAA;;;;AAEpD;;;;;;;;;;GAUG;AACH,qBAAa,SAAU,SAAQ,eAA8B;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB,CAAC;IACA,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,eAAe,CAAkB;CAC9D;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,SACH,CAAA;AAE3C;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,SAAS,CAAA;CAGnD,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;AAE5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAC3C,QAAQ,GACR,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACjB,QAAQ,GACR,CAAC,SAAS,SAAS,GACjB,SAAS,GACT,QAAQ,CAAA"}