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

package/dist/esm/index.js

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

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["decider","runDecider","buildDecisionModel","modelAtHead","decodeSlices","CodecError","UnknownEventType","event","projection","makeRegistry","Serializer","SerializerDefault","toEvent","Uuid","UuidLive","UuidTest"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAuBA,OAAO,EAAEC,UAAU,QAAQ,cAAW;AAC7D,SACEC,kBAAkB,EAClBC,WAAW,QAEN,oBAAiB;AACxB,SAASC,YAAY,QAAQ,aAAU;AACvC,SAASC,UAAU,EAAEC,gBAAgB,QAAQ,aAAU;AACvD,SAA0CC,KAAK,QAAsB,YAAS;AAC9E,SAEEC,UAAU,QAEL,iBAAc;AACrB,SAASC,YAAY,QAAuB,eAAY;AACxD,SAASC,UAAU,EAAEC,iBAAiB,QAAQ,iBAAc;AAC5D,SAASC,OAAO,QAAQ,cAAW;AACnC,SAASC,IAAI,EAAEC,QAAQ,EAAEC,QAAQ,QAAQ,WAAQ","ignoreList":[]}
+{"version":3,"file":"index.js","names":["decider","runDecider","Decision","isUnchanged","Unchanged","UnchangedTypeId","buildDecisionModel","modelAtHead","decodeSlices","CodecError","UnknownEventType","event","decideOnly","transact","unsafeAppend","projection","NoReadsRecorded","ReadLedger","TaglessSliceInLedger","makeRegistry","Serializer","SerializerDefault","toEvent","Uuid","UuidLive","UuidTest"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuHA,SAAuBA,OAAO,EAAEC,UAAU,QAAQ,cAAW;AAC7D,SACEC,QAAQ,EAGRC,WAAW,EACXC,SAAS,EACTC,eAAe,QACV,eAAY;AACnB,SACEC,kBAAkB,EAClBC,WAAW,QAEN,oBAAiB;AACxB,SAASC,YAAY,QAAQ,aAAU;AACvC,SAASC,UAAU,EAAEC,gBAAgB,QAAQ,aAAU;AACvD,SAA0CC,KAAK,QAAsB,YAAS;AAC9E,SACEC,UAAU,EAEVC,QAAQ,EACRC,YAAY,QACP,mBAAgB;AACvB,SAEEC,UAAU,QAEL,iBAAc;AACrB,SAGEC,eAAe,EACfC,UAAU,EACVC,oBAAoB,QACf,iBAAc;AACrB,SAASC,YAAY,QAAuB,eAAY;AACxD,SAASC,UAAU,EAAEC,iBAAiB,QAAQ,iBAAc;AAC5D,SAASC,OAAO,QAAQ,cAAW;AACnC,SAASC,IAAI,EAAEC,QAAQ,EAAEC,QAAQ,QAAQ,WAAQ","ignoreList":[]}

package/dist/esm/precondition.js

@@ -0,0 +1,182 @@
+import { AppendIsOwned, DcbEventStore } from '@kairos-es/core';
+import { Context, Effect, Layer } from 'effect';
+import { isUnchanged } from "./decision.js";
+import { modelAtHead } from "./decisionModel.js";
+import { deriveLayeredCondition, makeReadLedger, NoReadsRecorded, ReadLedger } from "./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 — 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
+ * 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.
+ */
+export const decideOnly = (decider, command) => Effect.gen(function* () {
+  yield* ReadLedger;
+  const {
+    state
+  } = yield* 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.
+ */
+export 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.flatMap(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.mapInputContext(store.append(events), context => Context.omit(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.
+ *
+ * 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.
+ */
+export const transact = precondition => body => Effect.gen(function* () {
+  const store = yield* DcbEventStore;
+  const ledger = yield* makeReadLedger;
+  const output = yield* 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.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.provide(Layer.merge(ledger.layer, Layer.succeed(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 (isUnchanged(output)) {
+    return output;
+  }
+  const condition = deriveLayeredCondition(yield* ledger.hops);
+  if (condition === undefined) {
+    return yield* new NoReadsRecorded();
+  }
+  return yield* store.append(output, condition);
+});
+//# sourceMappingURL=precondition.js.map

package/dist/esm/precondition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"precondition.js","names":["AppendIsOwned","DcbEventStore","Context","Effect","Layer","isUnchanged","modelAtHead","deriveLayeredCondition","makeReadLedger","NoReadsRecorded","ReadLedger","decideOnly","decider","command","gen","state","projections","decide","unsafeAppend","events","reason","flatMap","store","mapInputContext","append","context","omit","transact","precondition","body","ledger","output","proof","evaluate","pipe","provideService","tag","provide","merge","layer","succeed","by","condition","hops","undefined"],"sources":["../../src/precondition.ts"],"sourcesContent":[null],"mappings":"AAwGA,SAASA,aAAa,EAAEC,aAAa,QAAQ,iBAAiB;AAE9D,SAASC,OAAO,EAAEC,MAAM,EAAEC,KAAK,QAAQ,QAAQ;AAE/C,SAGEC,WAAW,QACN,eAAY;AACnB,SAASC,WAAW,QAA4B,oBAAiB;AAGjE,SACEC,sBAAsB,EACtBC,cAAc,EACdC,eAAe,EACfC,UAAU,QAEL,iBAAc;AAgCrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,OAAO,MAAMC,UAAU,GAAGA,CAOxBC,OAAqC,EACrCC,OAAgB,KAMhBV,MAAM,CAACW,GAAG,CAAC,aAAS;EAClB,OAAOJ,UAAU;EAEjB,MAAM;IAAEK;EAAK,CAAE,GAAG,OAAOT,WAAW,CAACM,OAAO,CAACI,WAAW,CAACH,OAAO,CAAC,CAAC;EAClE,OAAO,OAAOD,OAAO,CAACK,MAAM,CAACF,KAAK,EAAEF,OAAO,CAAC;AAC9C,CAAC,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;AAsBA,OAAO,MAAMK,YAAY,GAAGA,CAC1BC,MAA2C;AAC3C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACAC,MAAc,KAEdjB,MAAM,CAACkB,OAAO,CAACpB,aAAa,EAAGqB,KAAK;AAClC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACAnB,MAAM,CAACoB,eAAe,CACpBD,KAAK,CAACE,MAAM,CAACL,MAAM,CAAC,EACnBM,OAA+B,IAAKvB,OAAO,CAACwB,IAAI,CAAC1B,aAAa,CAAC,CAACyB,OAAO,CAAC,CAC1E,CACF;AAEH;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,MAAME,QAAQ,GACGC,YAA+C,IAEnEC,IAA4B,IAQ5B1B,MAAM,CAACW,GAAG,CAAC,aAAS;EAClB,MAAMQ,KAAK,GAAG,OAAOrB,aAAa;EAClC,MAAM6B,MAAM,GAAG,OAAOtB,cAAc;EAEpC,MAAMuB,MAAM,GAAmB,OAAO5B,MAAM,CAACW,GAAG,CAAC,aAAS;IACxD;IACA;IACA;IACA,MAAMkB,KAAK,GAAG,OAAOJ,YAAY,CAACK,QAAQ;IAC1C,OAAO,OAAOJ,IAAI,CAACK,IAAI,CAAC/B,MAAM,CAACgC,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;EACA/B,MAAM,CAACkC,OAAO,CACZjC,KAAK,CAACkC,KAAK,CACTR,MAAM,CAACS,KAAK,EACZnC,KAAK,CAACoC,OAAO,CAACxC,aAAa,EAAE;IAAEyC,EAAE,EAAE;EAAU,CAAE,CAAC,CACjD,CACF,CACF;EAED;EACA;EACA;EACA;EACA;EACA;EACA,IAAIpC,WAAW,CAAC0B,MAAM,CAAC,EAAE;IACvB,OAAOA,MAA2B;EACpC;EAEA,MAAMW,SAAS,GAAGnC,sBAAsB,CAAC,OAAOuB,MAAM,CAACa,IAAI,CAAC;EAC5D,IAAID,SAAS,KAAKE,SAAS,EAAE;IAC3B,OAAO,OAAO,IAAInC,eAAe,EAAE;EACrC;EAEA,OAAQ,OAAOa,KAAK,CAACE,MAAM,CAACO,MAAM,EAAEW,SAAS,CAAC;AAChD,CAAC,CAAC","ignoreList":[]}

package/dist/esm/readLedger.js

@@ -0,0 +1,212 @@
+import { composeProjections, ORIGIN, servableQueryFault, unionQueries } from '@kairos-es/core';
+import { Context, Data, Effect, Layer, Option, Ref } from 'effect';
+/**
+ * The ambient ledger, present only inside a bracket.
+ *
+ * ⚠ A RECORDING path reads it with `Effect.serviceOption` and never
+ * `yield* ReadLedger`: its absence is the normal case there, and costing the
+ * requirement channel nothing is exactly what makes this change additive.
+ * `modelAtHead` is that path and is why the rule exists.
+ *
+ * A BRACKET-ONLY function is the opposite case and yields the tag deliberately.
+ * `decideOnly` does, and naming the requirement is what turns *"call me inside a
+ * bracket"* from a runtime defect into a compile error — presence being the one
+ * direction the type system can decide here. So the test is what the function
+ * means outside a bracket: nothing (record ambiently), or nothing sensible
+ * (require it).
+ *
+ * Recording is two-phase, and `record`'s own doc below owns why and what shape the
+ * second phase takes.
+ */
+export class ReadLedger extends /*#__PURE__*/Context.Tag('@kairos-es/codec/ReadLedger')() {}
+/**
+ * Raised when a bracket closes having recorded no read at all.
+ *
+ * On the ERROR channel and deliberately split from the nested-append DEFECT,
+ * because the two are different mistakes. An empty bracket can arise from a
+ * data-dependent branch that produces events without reading — a genuinely
+ * unconditional creation, written inside a bracket by mistake — where a nested
+ * append is always a wiring fault. An error-channel value lets a caller decide
+ * which it is.
+ *
+ * Its job is narrower than it looks, and the narrowing is worth stating because
+ * the wider reading is the tempting one. Once a bracket's guard is itself a fold,
+ * a body that reads nothing still has a hop, so this cannot fire — it is the guard
+ * against an unguarded UNCONDITIONAL bracket, not against an unguarded bracket. A
+ * bracket that looks guarded and is not is NOT what this catches and never was,
+ * and nothing else catches it either — `precondition.ts` owns that gap and the
+ * rule a reader has to keep in its place. A refusal taken BEFORE reading is not
+ * this case either: it short-circuits and surfaces as the refusal.
+ */
+export class NoReadsRecorded extends /*#__PURE__*/Data.TaggedError('NoReadsRecorded') {
+  /**
+   * The sentence, as the `Error` field that says why — so the fault renders
+   * ITSELF, exactly as this package's other two errors do (`errors.ts` owns the
+   * argument for the mechanism and it is not restated here).
+   *
+   * A getter over a constant rather than a constructor field, because there is no
+   * datum to vary: every raise of this error means one thing.
+   */
+  get message() {
+    return 'the bracket closed having recorded no read, so there is no append condition ' + 'to derive. A decision that reads nothing is unconditional — say so with the ' + 'escape hatch, which takes a reason, rather than by opening a bracket.';
+  }
+}
+/**
+ * Raised when recording a hop would leave the bracket's accumulated union
+ * unservable.
+ *
+ * The store refuses a multi-item query in which any item is tagless, and it
+ * refuses it by THROWING inside the append decorator, which becomes a defect:
+ * uncatchable, one call and one layer away from the `build()` that chose no tags.
+ * A slice built without tags defaults to none, so it is perfectly servable alone
+ * and kills the append the moment it is unioned. This moves that failure onto the
+ * error channel, to the read that caused it, naming the record entry to fix.
+ *
+ * It refuses an unservable UNION and not every tagless hop, which is the easy
+ * mistake to make in the other direction: one tagless slice read on its own is
+ * servable and must keep working. Two cases reach it — a tagless hop unioned with
+ * another, and a single hop whose own RECORD holds two tagless slices, which
+ * composes to a multi-item query with no second hop needed.
+ */
+export class TaglessSliceInLedger extends /*#__PURE__*/Data.TaggedError('TaglessSliceInLedger') {
+  /** The offending slice and the remedy, in one sentence. */
+  get message() {
+    return `slice '${this.sliceKey}' was built with no tags, and this bracket now reads ` + 'more than one slice. A layered append condition unions every query it ' + 'recorded, and the store refuses a multi-item query if any item is tagless. ' + 'Pass `build({ tags: [...] })` for this slice.';
+  }
+}
+/**
+ * The ONE derivation: the union of every query walked, at the earliest head
+ * observed. Package-internal, for the reason the module doc gives.
+ *
+ * The union goes through core's own `unionQueries` — the merge
+ * `composeProjections` folds a record through, reached without one — and never a
+ * spread of `items`, because a wildcard hop (`items: []`) is ABSORBING under OR
+ * while a spread of an empty list contributes nothing, so hand-rolling the union
+ * narrows a match-everything hop to its sibling, silently and in the unsafe
+ * direction. A
+ * repeated or overlapping hop is harmless because this derives ONCE from a merged
+ * set and matching is idempotent over an OR; that property belongs to deriving
+ * once and would be lost by a refactor to per-hop evaluation.
+ *
+ * ## When any hop is headless the floor is `ORIGIN`, and the alternative is unsound
+ *
+ * The earliest head that actually ARRIVED is refused, and is named here as refused
+ * rather than merely not chosen, because it is what a reader writes by accident
+ * when told to take the earliest head. With one headless hop among completed hops
+ * the union looks right and the floor betrays it, sitting already above the
+ * invalidating event.
+ *
+ * `ORIGIN`'s cost is measured rather than described: it refuses every append to
+ * any identity that already has history, so it is not a conservative default but a
+ * hard stop. It is affordable only because conflict retry wraps the bracket from
+ * OUTSIDE and re-reads, which is the rule the whole shape depends on.
+ */
+export const deriveLayeredCondition = hops => {
+  if (hops.length === 0) {
+    return undefined;
+  }
+  const merged = unionQueries(hops.map(hop => hop.query));
+  const arrived = hops.flatMap(hop => hop.head === undefined ? [] : [hop.head]);
+  // A headless hop widens the guard to the whole log. Unioning its query is the
+  // half that is not in dispute; the floor is where the two readings diverge.
+  const after = arrived.length === hops.length ? arrived.reduce((a, b) => b < a ? b : a) : ORIGIN;
+  return {
+    failIfEventsMatch: merged,
+    after
+  };
+};
+/**
+ * A fresh ledger and the `Layer` providing it: a `Ref` of hops behind the two-phase
+ * `record` the service declares.
+ *
+ * The hops effect is handed back beside the layer because the bracket reads them
+ * AFTER the body has run and the layer is out of scope, which is the same moment it
+ * stops being able to reach the service.
+ */
+export const makeReadLedger = /*#__PURE__*/Effect.gen(function* () {
+  const ref = yield* Ref.make([]);
+  return {
+    layer: Layer.succeed(ReadLedger, {
+      record: query => Ref.modify(ref, hops => [
+      // The close effect closes over the slot this hop just took, so the slot
+      // never becomes a value anything else has to carry or interpret.
+      head => Ref.update(ref, current => current.map((hop, index) => index === hops.length ? {
+        query: hop.query,
+        head
+      } : hop)), [...hops, {
+        query
+      }]]),
+      hops: Ref.get(ref)
+    }),
+    // The same effect the service exposes, reachable AFTER the layer is out of
+    // scope — which is exactly when the bracket derives.
+    hops: Ref.get(ref)
+  };
+});
+/**
+ * Run `f` against the ambient ledger, or answer `absent` when there is none.
+ *
+ * "Outside a bracket this is a no-op" is ONE fact stated once, rather than one
+ * per consumer free to drift from the others. Every ambient lookup in this module
+ * goes through here, which is also what keeps `Effect.serviceOption` — the reason
+ * nothing enters the requirement channel — from being a detail each caller has to
+ * remember.
+ */
+const withLedger = (absent, f) => Effect.flatMap(Effect.serviceOption(ReadLedger), ledger => Option.isNone(ledger) ? Effect.succeed(absent) : f(ledger.value));
+/** A close effect that does nothing: what a read outside a bracket gets back. */
+const NO_CLOSE = () => Effect.void;
+/**
+ * File a query into the ambient ledger if there is one, and hand back the effect
+ * that completes it. Outside a bracket the whole thing is a no-op, and the caller
+ * still writes one line rather than a conditional.
+ */
+export const recordQuery = query => withLedger(NO_CLOSE, ledger => ledger.record(query));
+/** The tagless slice keys in a record, in declaration order. */
+const taglessKeys = projections => Object.entries(projections).filter(([, projection]) => projection.query.items.some(item => item.tags.length === 0)).map(([key]) => key);
+/** Would recording this record's query leave the accumulated union unservable? */
+const unionWouldBeUnservable = (existing, incoming) => servableQueryFault(unionQueries([...existing.map(h => h.query), incoming])) !== undefined;
+/**
+ * Refuse a read that would leave the bracket's accumulated union unservable,
+ * BEFORE the read is paid for.
+ *
+ * Servability is answerable from the queries alone, so the check runs when a hop is
+ * recorded rather than at append time — the eager half of the eager/lazy split doing
+ * one more job. Outside a bracket nothing is unioned and nothing is unservable, so
+ * the ordinary single-hop caller is untaxed.
+ *
+ * It judges the PROSPECTIVE UNION and asks core for the verdict, which is what makes
+ * both failing shapes one case rather than two. An earlier version tested each
+ * recorded query separately and treated a FIRST hop as unconditionally fine — but a
+ * hop is a RECORD, and a record of two tagless slices composes to a multi-item query
+ * that is unservable on its own. That read died at the store, uncatchably, on the
+ * exact path this error exists to keep off the defect channel. A grammar with two
+ * homes drifts at the shapes neither author had in mind, so there is one home and it
+ * is `servableQueryFault`'s.
+ *
+ * Where the OFFENDING slice is THIS record's the ledger can name its key; where it
+ * belongs to an earlier hop it can only say so, a recorded hop keeping its query
+ * rather than the key it was composed from. That asymmetry is diagnostic-only and is
+ * why the message is built from a key that may be a placeholder.
+ */
+export const assertServableAddition = projections => withLedger(undefined, ledger => Effect.flatMap(ledger.hops, existing => {
+  const incoming = composeProjections(projections).query;
+  if (!unionWouldBeUnservable(existing, incoming)) {
+    return Effect.void;
+  }
+  // The offending key where the tagless slice is THIS record's, and a
+  // placeholder where it belongs to an earlier hop — a recorded hop keeps its
+  // query rather than the key it was composed from.
+  const offending = taglessKeys(projections)[0] ?? '<an earlier hop>';
+  return new TaglessSliceInLedger({
+    sliceKey: offending
+  });
+}));
+/**
+ * The condition the ambient ledger derives right now, or `None` outside a bracket.
+ *
+ * This is what makes `buildDecisionModel` correct inside a bracket: the call whose
+ * current behaviour is the hazard derives from every hop the bracket walked rather
+ * than from its own single read.
+ */
+export const ambientLayeredCondition = /*#__PURE__*/withLedger(/*#__PURE__*/Option.none(), ledger => Effect.map(ledger.hops, hops => Option.fromNullable(deriveLayeredCondition(hops))));
+//# sourceMappingURL=readLedger.js.map

package/dist/esm/readLedger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readLedger.js","names":["composeProjections","ORIGIN","servableQueryFault","unionQueries","Context","Data","Effect","Layer","Option","Ref","ReadLedger","Tag","NoReadsRecorded","TaggedError","message","TaglessSliceInLedger","sliceKey","deriveLayeredCondition","hops","length","undefined","merged","map","hop","query","arrived","flatMap","head","after","reduce","a","b","failIfEventsMatch","makeReadLedger","gen","ref","make","layer","succeed","record","modify","update","current","index","get","withLedger","absent","f","serviceOption","ledger","isNone","value","NO_CLOSE","void","recordQuery","taglessKeys","projections","Object","entries","filter","projection","items","some","item","tags","key","unionWouldBeUnservable","existing","incoming","h","assertServableAddition","offending","ambientLayeredCondition","none","fromNullable"],"sources":["../../src/readLedger.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kairos-es/codec",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "Schema-first codec with encryption seam for kairos-es",
   "license": "BSD-3-Clause",
   "repository": {
@@ -12,7 +12,7 @@
   "homepage": "https://github.com/neverbland/kairos-es",
   "peerDependencies": {
     "effect": "^3.22.0",
-    "@kairos-es/core": "^1.0.0-alpha.0"
+    "@kairos-es/core": "^1.0.0-alpha.2"
   },
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",