@kairos-es/codec 1.0.0-alpha.4 → 1.0.0-alpha.5

package/dist/dts-esm/event.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Event definitions: a tagged `Schema` built through `event(type, fields,
+ * tagsFor)`. Each def is a `Schema.Codec<Payload, Wire, R, R>` plus its branded versioned
+ * `type` (ADR-0005) captured *beside* the payload, and a required `tagsFor`
+ * mapper deriving the event's tags from its decoded payload (ADR-0006).
+ *
+ * The single `EventType` brand is applied once, here, so no consumer ever casts
+ * a type string: `def.type` is already assignable to core's `EventType`. The
+ * payload `A`, wire encoding `I`, and requirement `R` are inferred from the
+ * `Schema.Struct` of `fields` — including any requirement a field's `Schema`
+ * transform carries (e.g. an application `Encrypted(...)` field contributes its
+ * `CipherKey` to `R`).
+ *
+ * `tagsFor` is the only way to tag an event: `toEvent` derives the wire tags by
+ * calling it, and there is no `tags` option to override them. Its
+ * `NonEmptyReadonlyArray<Tag>` return makes "every event carries at least one
+ * tag" a compile-time guarantee (returning `[]` is a type error at the def
+ * site), and its input being only this event's payload guarantees `tag ⊆ event
+ * data` structurally. An event with no natural business identity returns an
+ * explicit app-defined `system:<name>` tag, never an empty array.
+ *
+ * A mapper must be a *pure* function of its payload and key off fields in their
+ * schema-canonical form (normalising in the mapper to match a field's schema),
+ * so the tag it derives is stable under the schema round-trip: a later retag
+ * re-derives tags from decoded history, and `tagsFor(decode(encode(p)))` must
+ * equal `tagsFor(p)` for that to be sound. Plain scalar fields satisfy this
+ * trivially; a field whose schema canonicalises on decode (trim, lowercase,
+ * normalise) needs the mapper to apply the same normalisation (ADR-0006).
+ */
+import type { EventType, Tag } from '@kairos-es/core';
+import type { Array as Arr } from 'effect';
+import { Schema } from 'effect';
+/**
+ * A tag mapper: derives an event's tags from its decoded payload, returning at
+ * least one `Tag`. Named so a standalone mapper can be typed and shared (e.g.
+ * across two versioned defs of one logical event) and so the signature is
+ * written once, not per use site.
+ */
+export type TagsFor<A> = (payload: A) => Arr.NonEmptyReadonlyArray<Tag>;
+/**
+ * An event definition: its branded `type`, the `Schema` mapping its typed
+ * payload `A` to its wire encoding `I` (requiring `R`), and the `tagsFor` mapper
+ * that derives the event's tags from a decoded payload.
+ *
+ * `R` is ONE requirement for both directions, which is why the schema is a
+ * `Schema.Codec<A, I, R, R>` rather than leaving decoding and encoding services
+ * apart. A def is decoded on the read path and encoded by `toEvent`, so a
+ * consumer providing a def's services provides them for both; an application
+ * encryption transform needs its key either way. A struct whose two directions
+ * differ still fits, the codec being covariant in both, and `R` is then their
+ * union.
+ *
+ * `tagsFor` CONSUMES an `A`, so `EventDef` is invariant in `A` whatever the
+ * schema's own variance, and is therefore not declared `out A`.
+ */
+export interface EventDef<A = unknown, I = unknown, R = never> {
+    readonly type: EventType;
+    readonly schema: Schema.Codec<A, I, R, R>;
+    readonly tagsFor: TagsFor<A>;
+}
+/**
+ * The heterogeneous bound for arrays/records of mixed defs, where the precise
+ * `A`/`I` differ per element. `tagsFor` erases to `(a: any) => …`, which is
+ * harmless: only the write path (`toEvent`) calls it, and the registry/decode
+ * path never does (stored events already carry tags).
+ */
+export type EventDefAny = EventDef<any, any, unknown>;
+/**
+ * Define an event from a versioned `type` literal, its payload `fields`, and its
+ * required `tagsFor` mapper. Builds `Schema.Struct(fields)` and brands the type
+ * literal *once* (the single sanctioned cast). The returned def is typed so
+ * `def.type` is a branded literal assignable to core's `EventType` with no
+ * consumer cast, `A`/`I`/`R` are inferred from the struct, and `tagsFor`
+ * receives the def's decoded payload type.
+ */
+export declare const event: <const Type extends string, Fields extends Schema.Struct.Fields>(type: Type, fields: Fields, tagsFor: TagsFor<Schema.Struct.Type<Fields>>) => {
+    readonly type: Type & EventType;
+    readonly schema: Schema.Struct<Fields>;
+    readonly tagsFor: TagsFor<Schema.Struct.Type<Fields>>;
+};
+//# sourceMappingURL=event.d.ts.map

package/dist/dts-esm/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../../src/event.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,KAAK,EAAE,KAAK,IAAI,GAAG,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,GAAG,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAA;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,KAAK;IAC3D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAC7B;AAED;;;;;GAKG;AAEH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAChB,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,MAAM,SAAS,MAAM,CAAC,MAAM,CAAC,MAAM,EAEnC,MAAM,IAAI,EACV,QAAQ,MAAM,EACd,SAAS,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAC3C;IACD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;CAStD,CAAA"}

package/dist/dts-esm/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @kairos-es/codec — the schema-first codec seam, mapping typed domain events
+ * to and from the store's opaque wire bytes, with an application-owned
+ * encryption seam (ADR-0004).
+ *
+ * Two entry points:
+ * - The *typed slice path* (primary): `event(type, fields, tagsFor)` defines a
+ *   tagged `Schema` plus a required mapper deriving the event's tags from its
+ *   payload (ADR-0006); `projection(init).on(def, fold)...build()` composes the
+ *   specific defs a decision model consumes, inferring its state and requirement
+ *   `R`; `modelAtHead(slices)` reads, decodes through each def's `Schema`, and folds
+ *   purely, and `buildDecisionModel(slices)` adds the `AppendCondition` to it. A handler for an un-imported event is a compile error, and
+ *   a mistyped type cannot silently match nothing.
+ * - The *general path* (minimal): `makeRegistry(defs)` decodes an arbitrary wire
+ *   event by its runtime type string; an unknown type is a typed
+ *   `UnknownEventType` (ADR-0005 decode-totality). The payload stays `unknown`
+ *   on this path: the type is discovered at runtime, so no def was named to
+ *   narrow it (see `registry.ts`).
+ *
+ * `toEvent(def, payload, { uuid?, occurredAt?, metadata? })` produces a wire
+ * event (encode -> serialise, tags derived from `def.tagsFor`, clock + uuid from
+ * services, metadata from the call or the optional ambient `MetadataSource`).
+ * Serialisation is a pluggable `Serializer` (JSON
+ * default). Encryption, when needed, is an *application*-authored `Schema`
+ * transform on a payload field; the codec only propagates its requirement and
+ * error channels — it owns no cipher and imports no `node:crypto`.
+ *
+ * `Decider` + `runDecider(decider, command)` close that path into the write
+ * side's whole command cycle: build the decision model, decide, append under the
+ * read's own condition. They live HERE, beside the `buildDecisionModel` they
+ * drive, rather than in `@kairos-es/testing` where they began — that package
+ * peers `@effect/vitest`, and a production command handler must not name it (see
+ * `decider.ts` for the full argument). `decider(projections, decide)` builds one
+ * with all four type arguments inferred, so a command's slice record and its
+ * 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
+ * read returned — which is a stronger currency claim than a maintained view's
+ * checkpoint can make. `buildDecisionModel` is expressed over it, so the write
+ * path's decision model and a read-time materialisation share one body rather
+ * than two that could drift (see `decisionModel.ts` for both arguments).
+ *
+ * `decodeSlices(slices)` is the decode stage `modelAtHead` folds through,
+ * exported because the read side needs the *same* decode over a live
+ * `subscribe` stream. Exposing it keeps that single implementation shared
+ * rather than reimplemented downstream. It is deliberately ONE symbol taking
+ * the slice record, not a merge-then-decode pair: the pair had exactly one
+ * legal composition, and its only degree of freedom was to decode against a
+ * record other than the one the query came from (see `decode.ts`).
+ */
+export { type Decider, decider, runDecider } from './decider.js';
+export { Decision, type DecisionOutput, type DecisionResult, isUnchanged, Unchanged, UnchangedTypeId, } from './decision.js';
+export { buildDecisionModel, modelAtHead, type RequirementOf, } from './decisionModel.js';
+export { decodeSlices } from './decode.js';
+export { CodecError, UnknownEventType } from './errors.js';
+export { type EventDef, type EventDefAny, event, type TagsFor } from './event.js';
+export { MetadataSource } from './MetadataSource.js';
+export { decideOnly, type Precondition, transact, unsafeAppend, } from './precondition.js';
+export { type ProjectionBuilder, projection, type SliceProjection, } from './projection.js';
+export { type CloseHop, type Hop, NoReadsRecorded, ReadLedger, TaglessSliceInLedger, } from './readLedger.js';
+export { makeRegistry, type Registry } from './registry.js';
+export { Serializer, SerializerDefault } from './Serializer.js';
+export { toEvent } from './toEvent.js';
+export { Uuid, UuidLive, UuidTest } from './Uuid.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/dts-esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsHG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC7D,OAAO,EACL,QAAQ,EACR,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,WAAW,EACX,SAAS,EACT,eAAe,GAChB,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EACL,UAAU,EACV,KAAK,YAAY,EACjB,QAAQ,EACR,YAAY,GACb,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,GAAG,EACR,eAAe,EACf,UAAU,EACV,oBAAoB,GACrB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA"}

package/dist/dts-esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/dts-esm/precondition.d.ts

@@ -0,0 +1,244 @@
+/**
+ * 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.
+ *
+ * ## A body may answer `Unchanged`, and then there is nothing to guard
+ *
+ * The body's success is a `DecisionOutput`: a non-empty batch, or `Unchanged` —
+ * "already done". On `Unchanged` the bracket appends nothing, derives no
+ * condition and returns the `Unchanged`, and the result type is
+ * `DecisionResult<O>`, so a body that cannot answer it keeps a plain `Position`.
+ * `decideOnly` passes a decider's `Unchanged` through to the body unaltered.
+ *
+ * It is NOT refused as `NoReadsRecorded`, even from a bracket that read nothing,
+ * and that is not a hole in the refusal. `NoReadsRecorded` exists because an
+ * append with no prior read would go out UNGUARDED while looking guarded. An
+ * `Unchanged` appends nothing, so there is no write for a condition to guard and
+ * nothing for the refusal to protect. The same empty bracket returning EVENTS is
+ * still refused, exactly as before. `decision.ts` owns what `Unchanged` is.
+ *
+ * ## 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 DecisionOutput, type DecisionResult } from './decision.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.Key<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 — 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 declare const decideOnly: <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<O, 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.updateContext` 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.
+ *
+ * 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 declare const transact: <Id, Service, PE, PR>(precondition: Precondition<Id, Service, PE, PR>) => <E, R, O extends DecisionOutput = Arr.NonEmptyReadonlyArray<DcbEvent>>(body: Effect.Effect<O, E, R>) => Effect.Effect<DecisionResult<O>, E | PE | NoReadsRecorded | AppendConditionFailed, Exclude<Exclude<R, Id>, ReadLedger | AppendIsOwned> | Exclude<PR, ReadLedger | AppendIsOwned> | DcbEventStore>;
+//# sourceMappingURL=precondition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"precondition.d.ts","sourceRoot":"","sources":["../../src/precondition.ts"],"names":[],"mappings":"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"}

package/dist/dts-esm/projection.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The typed slice path (primary): a schema-backed projection and the fluent
+ * builder that produces it.
+ *
+ * A `SliceProjection<S, R>` is a core `AnyProjection<S>` (directly composable —
+ * its `evolve` folds a `DecodedEvent`) enriched with the `type -> Schema` map
+ * `decodeSlices` merges and decodes through. That map's value type carries `R`
+ * covariantly (`Schema.Decoder<unknown, R>`), so the union of the defs'
+ * requirements flows to the decision model with no cast (and no phantom marker).
+ * Because `evolve` is already erased, a built slice drops straight into
+ * `composeProjections` — no `AnyProjection.of` ceremony.
+ *
+ * `projection(initialState).on(def, fold)...build()` infers the state `S` and
+ * the union `R` of the `.on`-ed defs' requirements, derives the read `Query`'s
+ * event-types from the defs' branded type literals (no `as EventType`), and
+ * hands each `fold` its decoded, typed payload. A handler for an un-imported
+ * event is therefore a compile error, and a mistyped type cannot silently match
+ * nothing.
+ */
+import { type AnyProjection, type Tag } from '@kairos-es/core';
+import type { Schema } from 'effect';
+import type { EventDef } from './event.js';
+/**
+ * A schema-backed, directly-composable projection: an `AnyProjection<S>` plus
+ * the `type -> Schema` map for decode. The map's value type carries the union
+ * `R` of its defs' requirements covariantly, so `RequirementOf` recovers `R`
+ * (and the `out R` annotation keeps union-widening sound) with no phantom marker.
+ */
+export interface SliceProjection<out S = unknown, out R = unknown> extends AnyProjection<S> {
+    readonly schemas: ReadonlyMap<string, Schema.Decoder<unknown, R>>;
+}
+/** The fluent builder: accumulate `.on(def, fold)` steps, then `.build()`. */
+export interface ProjectionBuilder<S, R = never> {
+    /**
+     * Fold events of `def`'s type: `fold` receives the decoded, typed `payload`.
+     * Adds `def`'s requirement `R2` to the accumulated `R`.
+     *
+     * Throws if this chain has already `.on`-ed that event type — see the guard in
+     * `projection` for why a repeat is always a mistake here, where across two
+     * slices it need not be.
+     */
+    on<A, I, R2>(def: EventDef<A, I, R2>, fold: (state: S, payload: A) => S): ProjectionBuilder<S, R | R2>;
+    /**
+     * Materialise the slice. The query is a single item over the `.on`-ed defs'
+     * types (branded via `EventType.make`) and `options.tags` (default none).
+     */
+    build(options?: {
+        readonly tags?: ReadonlyArray<Tag>;
+    }): SliceProjection<S, R>;
+}
+/**
+ * Start a slice for `initialState`. Returns a builder with no defs yet
+ * (`R = never`); each `.on(def, fold)` widens `R` by the def's requirement.
+ */
+export declare const projection: <S>(initialState: S) => ProjectionBuilder<S, never>;
+//# sourceMappingURL=projection.d.ts.map

package/dist/dts-esm/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,KAAK,aAAa,EAIlB,KAAK,GAAG,EACT,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,GAAG,OAAO,CAC/D,SAAQ,aAAa,CAAC,CAAC,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAA;CAClE;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK;IAC7C;;;;;;;OAOG;IACH,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EACT,GAAG,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EACvB,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,GAChC,iBAAiB,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAA;IAC/B;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC,CAAA;KAAE,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;CAC/E;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,cAAc,CAAC,KAAG,iBAAiB,CAAC,CAAC,EAAE,KAAK,CA4FzE,CAAA"}