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

package/dist/dts/precondition.d.ts

@@ -0,0 +1,221 @@
+/**
+ * The bracket that owns the append, the precondition value it takes, and the two
+ * functions that make a decision inside it writable.
+ *
+ * ## What the bracket is for, and why no condition reaches the caller
+ *
+ * `transact(precondition)(body)` evaluates a guard, hands its output to the body
+ * as a service, and appends whatever the body produced under the union of every
+ * read EITHER of them performed. A caller writes no condition, no union, no floor
+ * and no `min`.
+ *
+ * That is not an ergonomic preference. Owning the append does not make a wrong
+ * condition a type error — it makes one UNWRITABLE, which is the stronger
+ * guarantee: a returned condition is a condition a caller can decline to use, and
+ * a decision that looks guarded and is not is the exact failure this seam exists
+ * to close. It is what Axon Framework 5 does, where the condition is married to
+ * the events at prepare-commit and the caller never holds one.
+ *
+ * One thing is deliberately NOT borrowed from that prior art. There, an append
+ * with no prior read leaves the condition unset and the append unguarded, so the
+ * method name reads as unconditional while the behaviour is not. `NoReadsRecorded`
+ * closes that door here and must not be lost.
+ *
+ * ⚠ The name says *declare, then do*. It is NOT a database transaction: an append
+ * under a condition is not two-phase, and nothing rolls back.
+ *
+ * ## Order is the design, and it is the one line here that must not move
+ *
+ * The precondition is evaluated INSIDE the bracket and never before it. Evaluated
+ * before, its reads are not part of what it protects — the ledger does not exist
+ * yet, so its hops are lost and the write is guarded only by the business read.
+ * The check would look exactly as it does now and would guard nothing.
+ *
+ * ## Why the precondition's output crosses as a SERVICE
+ *
+ * A body that needs authorisation names the tag in its requirement channel, so
+ * `transact` must provide it, so the body CANNOT BE RUN without a precondition.
+ * That is a PRESENCE check, and presence is the one direction the type system can
+ * decide here — `Exclude<R, Id>` in the return type is where it is spent. The
+ * alternative, a curried parameter, buys nothing equivalent: a body is free to
+ * ignore a parameter.
+ *
+ * ## Composition is a combinator, not a list
+ *
+ * `transact` takes exactly ONE precondition. A variadic argument asserts
+ * INDEPENDENCE, and the interesting case is DEPENDENT — *may act for this
+ * organisation*, then *may sign in that organisation* — which a flat list cannot
+ * express and which is the very shape this change exists for. A dependent pair
+ * needs nothing anyway: a precondition is an ordinary `Effect` evaluated inside
+ * the open ledger, so two compose with `Effect.gen` and both sets of reads land in
+ * the same condition. An INDEPENDENT set wants a combinator over a RECORD,
+ * evaluated SEQUENTIALLY — fail-fast is the point, and concurrent reads are
+ * precisely the case where the earliest-head reduction stops being redundant. That
+ * combinator is purely additive and is not shipped here.
+ *
+ * ## Conflict retry goes OUTSIDE the bracket, never inside
+ *
+ * `retryOnConflict(transact(p)(body))`, never a retry within the body. The bracket
+ * takes an opaque `Effect`, so no type can express that rule and the lint gate is
+ * what enforces it: in the source repository, `biome-plugins/noRetryInBracket.grit`
+ * owns why and `test/retryInBracket.test.ts` executes it.
+ *
+ * ## ⚠⚠ THE ONE MISTAKE NOTHING CATCHES: a view read inside a bracket
+ *
+ * **A projection read, a raw SQL read, or any read that does not fold through
+ * `modelAtHead`, performed inside a bracket, contributes NO HOP.** Its query is
+ * absent from the derived union and its head is absent from the floor, so the
+ * decision rests on data the condition does not guard — and the bracket looks
+ * guarded, which is the exact failure this seam exists to close, wearing the fix's
+ * own name.
+ *
+ * **Nothing will tell you — not here and not in your own tree.** Not the type
+ * system: a requirement channel is ADDITIVE, so it can demand a capability's
+ * presence and never its absence. Not `NoReadsRecorded`: that fires on an EMPTY
+ * bracket and never on an under-populated one, so a bracket holding one genuine fold
+ * beside a view read passes it. And not a lint rule — one was written for exactly
+ * this, kept for a while and deleted, because a syntactic gate has no call graph and
+ * no types, so it could only name a receiver by convention, and because a lint
+ * plugin runs only where its own config is and so never travels with the library.
+ * `biome-plugins/README.md` in the source repository records the test that rule
+ * failed.
+ *
+ * So this is a rule a reader keeps, and knowing it is the guarantee: **inside a
+ * bracket, read through `modelAtHead`. If a read must
+ * consult a materialised view, do it OUTSIDE the bracket** — where it is ordinary
+ * code, because its answer is then not part of what the append is guarded on.
+ * ADR-0014's *decision read* rule is the test for which one a given read is.
+ */
+import type { AppendConditionFailed, DcbEvent, Position } from '@kairos-es/core';
+import { AppendIsOwned, DcbEventStore } from '@kairos-es/core';
+import type { Array as Arr } from 'effect';
+import { Context, Effect } from 'effect';
+import type { Decider } from './decider.js';
+import { type RequirementOf } from './decisionModel.js';
+import type { CodecError } from './errors.js';
+import type { SliceProjection } from './projection.js';
+import { NoReadsRecorded, ReadLedger, type TaglessSliceInLedger } from './readLedger.js';
+import type { Serializer } from './Serializer.js';
+import type { Uuid } from './Uuid.js';
+/**
+ * A named, reusable guard plus the tag its output is handed across.
+ *
+ * A VALUE and not a function of the command, deliberately: the point of the seam
+ * is that a guard is written once, centrally, and referenced by however many
+ * commands need it. A command supplies its own arguments when it BUILDS the value
+ * (`mayActFor(userId, orgId, verb)`), and what `transact` receives is the built
+ * thing.
+ *
+ * `Service` is fully generic and the library never reads it. Every consumer-side
+ * authorisation shape — a plain resolved identifier, a branded proof, a gate with
+ * a private minting closure — is application code this genericity accommodates
+ * without the library knowing anything about it. That is a requirement rather than
+ * an incidental property: hard-coding it would foreclose a consumer's later
+ * choice, and it costs nothing to keep.
+ *
+ * ⚠ `evaluate` is an `Effect`, so it is a FIELD OF AN OBJECT LITERAL and its
+ * expression is evaluated when the `Precondition` VALUE is built — before the
+ * bracket opens and before any cheap check inside it runs. Anything a builder does
+ * eagerly there (parsing an argument, resolving an identifier) happens outside the
+ * ordering guarantee above, and a throw there is an uncatchable defect on the very
+ * path meant to deny the input cheaply. Wrap such work in `Effect.suspend`.
+ */
+export interface Precondition<Id, Service, E, R> {
+    readonly tag: Context.Tag<Id, Service>;
+    readonly evaluate: Effect.Effect<Service, E, R>;
+}
+/**
+ * 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.
+ */
+export declare const decideOnly: <P extends Record<string, SliceProjection>, Command, E, R>(decider: Decider<P, Command, E, R>, command: Command) => Effect.Effect<Arr.NonEmptyReadonlyArray<DcbEvent>, E | CodecError | TaglessSliceInLedger, ReadLedger | DcbEventStore | Serializer | Uuid | R | RequirementOf<P>>;
+/**
+ * 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 declare const unsafeAppend: (events: Arr.NonEmptyReadonlyArray<DcbEvent>, reason: string) => Effect.Effect<Position, AppendConditionFailed, DcbEventStore>;
+/**
+ * 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.
+ */
+export declare const transact: <Id, Service, PE, PR>(precondition: Precondition<Id, Service, PE, PR>) => <E, R>(body: Effect.Effect<Arr.NonEmptyReadonlyArray<DcbEvent>, E, R>) => Effect.Effect<Position, E | PE | NoReadsRecorded | AppendConditionFailed, Exclude<Exclude<R, Id>, ReadLedger | AppendIsOwned> | Exclude<PR, ReadLedger | AppendIsOwned> | DcbEventStore>;
+//# sourceMappingURL=precondition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"precondition.d.ts","sourceRoot":"","sources":["../../src/precondition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAChF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC9D,OAAO,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,EAAS,MAAM,QAAQ,CAAA;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACxC,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAGL,eAAe,EACf,UAAU,EACV,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAElC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC7C,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;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,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EACnC,CAAC,GAAG,UAAU,GAAG,oBAAoB,EACrC,UAAU,GAAG,aAAa,GAAG,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAOnE,CAAA;AAEJ;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EAc3C,QAAQ,MAAM,KACb,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,qBAAqB,EAAE,aAAa,CAe5D,CAAA;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ,GAClB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,EAAE,cAAc,YAAY,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,CAAC,MACpE,CAAC,EAAE,CAAC,EACH,MAAM,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAC7D,MAAM,CAAC,MAAM,CACd,QAAQ,EACR,CAAC,GAAG,EAAE,GAAG,eAAe,GAAG,qBAAqB,EAC9C,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC,GACnD,OAAO,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,CAAC,GACvC,aAAa,CA6Cb,CAAA"}

package/dist/dts/readLedger.d.ts

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

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

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

package/dist/esm/decider.js

@@ -128,8 +128,15 @@ export 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.
  */
 export const runDecider = (decider, command) => Effect.gen(function* () {
   const store = yield* DcbEventStore;

package/dist/esm/decider.js.map

@@ -1 +1 @@
-{"version":3,"file":"decider.js","names":["DcbEventStore","Effect","buildDecisionModel","decider","projections","decide","runDecider","command","gen","store","state","appendCondition","newEvents","append"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,SAASA,aAAa,QAAQ,iBAAiB;AAE/C,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAASC,kBAAkB,QAA4B,oBAAiB;AAsCxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,OAAO,MAAMC,OAAO,GAAGA,CASrBC,WAAoC,EACpCC,MAA2D,MAO1D;EAAED,WAAW;EAAEC;AAAM,CAAE,CAKvB;AAEH;;;;;;;;;;;;;AAaA,OAAO,MAAMC,UAAU,GAAGA,CAMxBH,OAAkC,EAClCI,OAAgB,KAMhBN,MAAM,CAACO,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOT,aAAa;EAClC,MAAM;IAAEU,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAOT,kBAAkB,CAC1DC,OAAO,CAACC,WAAW,CAACG,OAAO,CAAC,CAC7B;EACD,MAAMK,SAAS,GAAG,OAAOT,OAAO,CAACE,MAAM,CAACK,KAAK,EAAEH,OAAO,CAAC;EACvD,OAAO,OAAOE,KAAK,CAACI,MAAM,CAACD,SAAS,EAAED,eAAe,CAAC;AACxD,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"decider.js","names":["DcbEventStore","Effect","buildDecisionModel","decider","projections","decide","runDecider","command","gen","store","state","appendCondition","newEvents","append"],"sources":["../../src/decider.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8DA,SAASA,aAAa,QAAQ,iBAAiB;AAE/C,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAASC,kBAAkB,QAA4B,oBAAiB;AAuCxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,OAAO,MAAMC,OAAO,GAAGA,CASrBC,WAAoC,EACpCC,MAA2D,MAO1D;EAAED,WAAW;EAAEC;AAAM,CAAE,CAKvB;AAEH;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,MAAMC,UAAU,GAAGA,CAMxBH,OAAkC,EAClCI,OAAgB,KAMhBN,MAAM,CAACO,GAAG,CAAC,aAAS;EAClB,MAAMC,KAAK,GAAG,OAAOT,aAAa;EAClC,MAAM;IAAEU,KAAK;IAAEC;EAAe,CAAE,GAAG,OAAOT,kBAAkB,CAC1DC,OAAO,CAACC,WAAW,CAACG,OAAO,CAAC,CAC7B;EACD,MAAMK,SAAS,GAAG,OAAOT,OAAO,CAACE,MAAM,CAACK,KAAK,EAAEH,OAAO,CAAC;EACvD,OAAO,OAAOE,KAAK,CAACI,MAAM,CAACD,SAAS,EAAED,eAAe,CAAC;AACxD,CAAC,CAAC","ignoreList":[]}