@kairos-es/read-postgres 1.0.0-alpha.4 → 1.0.0-alpha.5

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

@@ -0,0 +1,61 @@
+/**
+ * Public configuration for the Postgres `ProjectionStore`.
+ *
+ * A read-side store is defined entirely by its `{ schema, tablePrefix }` naming
+ * pair: the checkpoint table name is DERIVED from it (see `internal/ddl.ts`), so
+ * one config value is one completely isolated checkpoint namespace, cohabiting
+ * per prefix exactly as the event store's objects do (ADR-0002).
+ *
+ * It is a `Schema`, not a bare interface, so malformed input fails LOUDLY at
+ * construction (`makeSqlProjectionStore`/`ensureCheckpointSchema` decode through
+ * it) rather than late and obscurely on the first commit — the same
+ * fail-at-the-boundary discipline core applies to `Tag`/`ReadLimit`. It rejects an
+ * empty or dotted `schema`/`tablePrefix` atom (a dot would break the
+ * qualified-name dot-split) and — via `oversizedIdentifier` — any pair whose
+ * derived table name would exceed Postgres's 63-byte identifier limit and be
+ * silently truncated.
+ *
+ * **WHY this config is DUPLICATED rather than imported from
+ * `@kairos-es/store-postgres`.** Importing it would mean peering that package,
+ * and peering an event-store BACKEND from the read side is precisely what the
+ * per-materialisation view-store design exists to avoid: a durable view must be
+ * free to sit over any log satisfying `DcbEventStore` — the in-memory oracle,
+ * Postgres, a future backend — so this package depends on the PORT
+ * (`@kairos-es/read`) and on `effect/sql`, never on a sibling backend. The
+ * duplication also keeps the two guards honestly independent: each package
+ * measures only the identifiers IT materialises, so neither inherits a byte budget
+ * from names it never creates.
+ *
+ * The shape is intentionally the event store's MINUS everything read-side wiring
+ * has no business choosing: no `lockTimeout` (the checkpoint's guarded
+ * compare-and-set takes only ordinary row locks, and a blocked writer is a
+ * competing runner whose loss is a `CheckpointSuperseded` the supervisor already
+ * handles), no `pollInterval`/`catchUpPageSize` (those belong to `subscribe`, on
+ * the log side). What remains is naming, and only naming.
+ */
+import { Schema } from 'effect';
+/**
+ * Configuration for a read-side checkpoint store.
+ *
+ * - `schema` — the Postgres schema that owns the checkpoint table (default
+ *   `public`). `ensureCheckpointSchema` creates it defensively.
+ * - `tablePrefix` — the base name the checkpoint table derives from (default
+ *   `dcb_events`, giving `dcb_events_checkpoints`). Pass the SAME pair the event
+ *   store is configured with and the checkpoint table lands beside that store's
+ *   objects, one isolated store per prefix.
+ */
+export declare const ReadPostgresConfig: Schema.Struct<{
+    readonly schema: Schema.optionalKey<Schema.String>;
+    readonly tablePrefix: Schema.optionalKey<Schema.String>;
+}>;
+export type ReadPostgresConfig = typeof ReadPostgresConfig.Type;
+/**
+ * Decode an unknown value into a validated `ReadPostgresConfig`, throwing a
+ * `SchemaError` on any violation. Used by `makeSqlProjectionStore` and
+ * `ensureCheckpointSchema` so a bad config fails at construction time.
+ */
+export declare const decodeReadPostgresConfig: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+};
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAiB/B;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB;;;EAW9B,CAAA;AACD,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAE/D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;CACS,CAAA"}

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

@@ -0,0 +1,39 @@
+/**
+ * `ensureCheckpointSchema` — the idempotent checkpoint DDL, as a building block
+ * rather than a migrator (ADR-0007, mirroring the event store's `ensureSchema`).
+ *
+ * It is a single `Effect<void, SqlError, SqlClient>` that creates (or refreshes)
+ * the one object this package owns: the checkpoint table. It requires the GENERIC
+ * `SqlClient` service — not a package-owned client service — precisely so a consumer can
+ * drop it straight into THEIR OWN migrator, e.g.:
+ *
+ * ```ts
+ * Migrator.fromRecord({
+ *   '0002_kairos_checkpoints': ensureCheckpointSchema(config),
+ * })
+ * ```
+ *
+ * or simply run it once at boot, beside `ensureSchema` from the event-store
+ * backend. We ship no `FileSystem`/`Path`/`ChildProcess` dependency and no
+ * migrator: migration ORCHESTRATION belongs to the consumer, this package only
+ * provides the idempotent PAYLOAD. That is also why schema ownership never
+ * silently moves — a read model cannot conjure its own table at runtime.
+ *
+ * Idempotence: every statement is `CREATE … IF NOT EXISTS`, so re-running against
+ * an existing checkpoint table is a no-op. Names come pre-quoted from
+ * `internal/ddl.ts`; the DDL carries no bound values (pure schema).
+ *
+ * Unlike the runtime store, this path needs no `withoutTransforms()` guard: it
+ * reads no rows and passes no identifier through `sql(identifier)`, so a
+ * consumer's name transforms have nothing here to rewrite.
+ */
+import { Effect } from 'effect';
+import { SqlClient, type SqlError } from 'effect/sql';
+import { type ReadPostgresConfig } from './config.js';
+/**
+ * Produce the checkpoint migration payload for `config`. Resolves the table name
+ * once and runs the ordered idempotent DDL against whatever `SqlClient` the
+ * caller's migrator (or boot code) provides.
+ */
+export declare const ensureCheckpointSchema: (config: ReadPostgresConfig) => Effect.Effect<void, SqlError.SqlError, SqlClient.SqlClient>;
+//# sourceMappingURL=ensureCheckpointSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ensureCheckpointSchema.d.ts","sourceRoot":"","sources":["../../src/ensureCheckpointSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrD,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAG5E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,kBAAkB,KACzB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,SAAS,CASzD,CAAA"}

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

@@ -0,0 +1,92 @@
+/**
+ * @kairos-es/read-postgres — the SQL `ProjectionStore`: a durable checkpoint
+ * table plus the guarded compare-and-set that brackets a read model's own view
+ * writes in one ordinary transaction (ADR-0007).
+ *
+ * Needs only the GENERIC `SqlClient` from `effect/sql`, deliberately not
+ * `@effect/sql-pg` and deliberately no reserved connection: the event store owns
+ * the LISTEN, so the read side needs no dedicated connection of its own, and
+ * requiring the generic client is what lets `ensureCheckpointSchema` drop into a
+ * consumer's existing migrator instead of shipping a migrator here.
+ *
+ * A store is one `{ schema, tablePrefix }` naming pair (`ReadPostgresConfig`) —
+ * the same pair the event store is configured with — so the checkpoint table
+ * cohabits PER PREFIX and ADR-0002's "each prefix is a complete, isolated store"
+ * keeps holding across the read side.
+ *
+ * Wiring, end to end:
+ *
+ * ```ts
+ * import {
+ *   checkpointKey,
+ *   DurableEventLog,
+ *   forKey,
+ *   ProjectionId,
+ *   projectionLayer,
+ * } from '@kairos-es/read'
+ * import {
+ *   ensureCheckpointSchema,
+ *   makeSqlProjectionStore,
+ * } from '@kairos-es/read-postgres'
+ *
+ * const config = { schema: 'public', tablePrefix: 'dcb_events' }
+ *
+ * // 1. Register `ensureCheckpointSchema(config)` in YOUR migrator (or run it at
+ * //    boot), beside the event-store backend's own `ensureSchema(config)`.
+ * // 2. Build the store where the read model is wired, so `commit` closes over the
+ * //    acquired client and the read model itself stays free of `SqlClient`.
+ * const courseView = Layer.unwrapEffect(
+ *   Effect.gen(function* () {
+ *     const store = yield* makeSqlProjectionStore(config)
+ *     return projectionLayer({
+ *       // One store, many read models: `forKey` binds it to THIS one's checkpoint,
+ *       // and from there no operation takes a key to get wrong.
+ *       store: forKey(store, checkpointKey(ProjectionId.make('course-subs'))),
+ *       slices,
+ *       apply,
+ *     })
+ *   }),
+ * )
+ *
+ * // 3. Declare what the LOG is worth ONCE, beside the layer that chose it —
+ * //    `DcbEventStore` exposes no durability, so the application is the only
+ * //    honest source, and R2 (a durable view needs a durable log) is checked
+ * //    against this. It is a required input of every projection layer, and one
+ * //    declaration satisfies every one of them.
+ * const main = Layer.provide(
+ *   Layer.mergeAll(courseView, studentView),
+ *   Layer.mergeAll(eventStoreLayer, DurableEventLog, SerializerDefault),
+ * )
+ * ```
+ *
+ * The resulting layer requires the `SqlClient` the checkpoint (and typically the
+ * view) is written through, the `EventLogDurability` declaration above, plus
+ * whatever the read model's own `apply` needs. The checkpoint table is assumed to
+ * already exist, exactly as the event store's `layer` assumes its objects do: this
+ * package performs no DDL at runtime.
+ *
+ * `commit` is `sql.withTransaction(viewWrites *> guardedAdvance)`. The author's own
+ * view writes join that transaction only when issued through the SAME `SqlClient`
+ * the store was built from; a write through any other `SqlClient` instance is NOT
+ * bracketed and is not rolled back on a lost guard. `withTransaction` is
+ * savepoint-aware, so a projection already inside a
+ * transaction composes without a second physical one. A guarded advance touching
+ * zero rows raises `CheckpointSuperseded`, whose FAILURE aborts the transaction and
+ * rolls the view writes back with it — the abort that makes the projection
+ * exactly-once. An infrastructure fault surfaces as `ProjectionStoreError` on the
+ * ERROR CHANNEL rather than as a defect, inverting the event store's rule
+ * (ADR-0002) because the read side has a supervisor above it that must distinguish
+ * retry-with-backoff from give-up.
+ *
+ * The config and the identifier guards are duplicated here rather than imported
+ * from `@kairos-es/store-postgres`, and that duplication is deliberate: peering
+ * the event-store backend would couple the read side to one specific event-store
+ * implementation, which is precisely what per-materialisation view-store selection
+ * exists to avoid. A durable view must be free to sit over any log satisfying
+ * `DcbEventStore`, so this package depends on the port (`@kairos-es/read`) and
+ * on `effect/sql`, never on a sibling backend.
+ */
+export type { ReadPostgresConfig } from './config.js';
+export { ensureCheckpointSchema } from './ensureCheckpointSchema.js';
+export { makeSqlProjectionStore } from './projectionStore.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/dts-esm/internal/ddl.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Internal object-naming and DDL for the Postgres `ProjectionStore`.
+ *
+ * This module is the single source of truth for the ONE object this package owns
+ * — the checkpoint table — and for the idempotent DDL that creates it. It is
+ * factored apart from the public surface for the same reason the event store's
+ * `internal/ddl.ts` is: the name is derived ONCE, from `{ schema, tablePrefix }`,
+ * and reused by both `ensureCheckpointSchema` (the migration payload) and the
+ * runtime statements in `projectionStore.ts`, so a migration and a query can
+ * never disagree about what the table is called.
+ *
+ * The checkpoint table derives from the SAME `{ schema, tablePrefix }` pair the
+ * event store uses, so a checkpoint table cohabits PER PREFIX: two prefixes are
+ * two complete, isolated stores (ADR-0002) with two independent checkpoint
+ * namespaces, and that isolation keeps holding once the read side is added rather
+ * than being punctured by one shared checkpoint table.
+ *
+ * WHY names are never string-concatenated into a query: every identifier is
+ * pre-quoted here (`quoteQualified` for the dotted table, `quoteAtom` for a bare
+ * atom) and embedded as literal text into a `sql.unsafe(text, params)` statement,
+ * exactly as the event store's read plans are; VALUES are always bound `$n`
+ * parameters and never interpolated. A hostile or merely awkward
+ * `schema`/`tablePrefix` therefore cannot inject SQL or collide with a reserved
+ * word.
+ *
+ * The runtime deliberately does NOT route these names through `sql(identifier)`.
+ * This package takes the CONSUMER's generic `SqlClient`, which may carry a
+ * query-name transform (`effect/sql` applies it to every `sql(identifier)`), so
+ * a camel-casing consumer would silently rewrite `last_position` to
+ * `lastPosition` and address a column that does not exist. Pre-quoted text inside
+ * `sql.unsafe` is transform-proof; the result side is handled by
+ * `withoutTransforms()` in `projectionStore.ts`.
+ */
+import type { SqlClient, Statement } from 'effect/sql';
+/**
+ * The one object a read-side config owns. An interface rather than a bare string
+ * so the `{ schema, tablePrefix }` atoms stay available to error messages and so
+ * a second derived object (should one ever be needed) is an additive change here
+ * rather than a new parameter at every call site.
+ */
+export interface ResolvedCheckpointNames {
+    readonly schema: string;
+    readonly tablePrefix: string;
+    /** `<schema>.<prefix>_checkpoints` — the scalar checkpoint table. */
+    readonly checkpointTable: string;
+}
+/**
+ * Default schema when the config omits one. Identical to the event store's
+ * default, on purpose: the common wiring is one `{ schema, tablePrefix }` pair
+ * used for both sides, so both defaults must agree or a caller omitting the
+ * config would silently split the log and its checkpoints across two schemas.
+ */
+export declare const DEFAULT_SCHEMA = "public";
+/** Default table prefix when the config omits one — again the event store's. */
+export declare const DEFAULT_TABLE_PREFIX = "dcb_events";
+/**
+ * The first derived identifier that exceeds 63 bytes, as a human-readable
+ * message, or `undefined` when every name fits. Shared by
+ * `resolveCheckpointNames` (which throws) and the `ReadPostgresConfig` schema
+ * filter (which fails validation), so the byte bound is enforced identically at
+ * both the name-derivation and the config-decode boundary.
+ *
+ * The bound is checked INDEPENDENTLY of the event store's: this package measures
+ * only the names IT materialises, so a prefix accepted there may be rejected here
+ * (and vice versa). Each package guards its own names, which is what lets the
+ * read side stay uncoupled from any particular event-store backend.
+ */
+export declare const oversizedIdentifier: (config: {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+}) => string | undefined;
+/**
+ * Derive the checkpoint table name from `{ schema, tablePrefix }`. The table
+ * carries its schema explicitly so `quoteQualified` dot-splits it into the two
+ * atoms Postgres expects.
+ *
+ * Throws at construction if a derived identifier would be silently truncated (see
+ * `oversizedIdentifier`) — a loud failure at the single choke point beats an
+ * invisible cross-prefix checkpoint collision later.
+ */
+export declare const resolveCheckpointNames: (config: {
+    readonly schema?: string;
+    readonly tablePrefix?: string;
+}) => ResolvedCheckpointNames;
+/**
+ * Quote a possibly-qualified identifier for embedding as literal SQL text.
+ * Splits on `.` and double-quotes each atom, mirroring what `sql(identifier)`
+ * emits, so a pre-quoted name and an `sql(identifier)` reference resolve to
+ * exactly the same object. Any embedded `"` is doubled per SQL
+ * identifier-quoting rules. (The dot-split is why `ReadPostgresConfig` bars a dot
+ * inside either atom: an embedded dot would silently re-partition the name into
+ * the wrong schema.)
+ */
+export declare const quoteQualified: (name: string) => string;
+/**
+ * The checkpoint table's columns, PRE-QUOTED, as one shared descriptor.
+ *
+ * Shared by the DDL here and by every runtime statement in `projectionStore.ts`,
+ * so a column rename cannot half-land: the table it creates and the statements
+ * that address it read the same constant. Pre-quoted because `partition` is
+ * Postgres's own partitioning vocabulary — it parses unquoted today, but quoting
+ * removes the question, and quoting all three keeps the emitted SQL uniform.
+ *
+ * These names are FIXED and owned by this package (never config-derived), which
+ * is why they are plain constants rather than something the caller can influence.
+ */
+export declare const CHECKPOINT_COLUMNS: {
+    /** The read model's `ProjectionId`. */
+    readonly projection: string;
+    /** The read model's `PartitionId` (`default` while sharding is cut). */
+    readonly partition: string;
+    /**
+     * The scalar checkpoint: `bigint`, because a `Position` is 64-bit and exceeds
+     * JS `number` safety at 2^53. The driver reads it back as a `bigint`, and it
+     * is never coerced through `number`.
+     */
+    readonly lastPosition: string;
+};
+/**
+ * The ordered, idempotent DDL that creates (or refreshes) the checkpoint table.
+ * Each entry is a `sql.unsafe` statement string; no VALUES are involved (pure
+ * DDL), and every identifier is pre-quoted to match the runtime's resolution.
+ *
+ * Notes on the shape, both load-bearing:
+ *
+ * - `PRIMARY KEY (projection, partition)` is what makes `readCheckpoint` an index
+ *   lookup AND supplies the arbiter index the first-commit upsert's
+ *   `ON CONFLICT (projection, partition)` names. Without it that upsert would not
+ *   compile, so the key is not merely hygiene.
+ * - `last_position bigint NOT NULL` with NO row for a never-committed key: a key
+ *   reads back as `ORIGIN` by ABSENCE, so "never committed" and "reset" are one
+ *   state (`resetCheckpoint` deletes the row rather than zeroing it), exactly as
+ *   the in-memory store's map deletes its entry.
+ * - No autovacuum storage parameters, unlike the event store's tables. Those are
+ *   tuned for an append-heavy, effectively-immutable log; this table is a handful
+ *   of hot-UPDATEd rows, where the stock thresholds already fire aggressively.
+ */
+export declare const checkpointDdlStatements: (names: ResolvedCheckpointNames) => ReadonlyArray<string>;
+/**
+ * Run the ordered DDL against the generic `SqlClient`. Kept here (not in the
+ * public `ensureCheckpointSchema`) so the same builder feeds both the public
+ * migration payload and any internal test setup. Each statement is a separate
+ * `sql.unsafe` call so a driver that rejects multi-statement strings still works.
+ */
+export declare const runCheckpointDdl: (sql: SqlClient.SqlClient, names: ResolvedCheckpointNames) => ReadonlyArray<Statement.Statement<unknown>>;
+//# sourceMappingURL=ddl.d.ts.map

package/dist/dts-esm/internal/ddl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.d.ts","sourceRoot":"","sources":["../../../src/internal/ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,WAAW,CAAA;AACtC,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,eAAe,CAAA;AA0ChD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,KAAG,MAAM,GAAG,SAQZ,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ;IAC7C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,KAAG,uBAYH,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,MAIhC,CAAA;AAQd;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB;IAC7B,uCAAuC;;IAEvC,wEAAwE;;IAExE;;;;OAIG;;CAEK,CAAA;AAEV;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,uBAAuB,GAClC,OAAO,uBAAuB,KAC7B,aAAa,CAAC,MAAM,CAiBtB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAC3B,KAAK,SAAS,CAAC,SAAS,EACxB,OAAO,uBAAuB,KAC7B,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,CAAC,CAC6B,CAAA"}

package/dist/dts-esm/internal/statements.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The four runtime statement texts the Postgres `ProjectionStore` issues, and the
+ * TWO parameter lists that feed them.
+ *
+ * The texts and their binding live in ONE module deliberately. `$3` and `$4` of
+ * the guarded advance are `next` and `expected` — both a `Position`, so both a
+ * `bigint` — and the whole exactly-once property of the read side rests on which
+ * of them the `SET` writes and which the `WHERE` compares. While the texts sat
+ * beside the store's Effect wiring and the binding sat inside its closure, that
+ * correspondence was asserted in prose in one place and implemented 180 lines away
+ * in another, and prose is exactly what drifted: a comment claimed a `bind` helper
+ * made a transposed argument list inexpressible, while the call site spread two
+ * interchangeable `Position`s positionally. Here the claim is checkable by reading
+ * one file, and `test/guardParameters.test.ts` pins it without a database.
+ *
+ * Everything else follows `internal/ddl.ts`: identifiers are pre-quoted literal
+ * text (`quoteQualified` / `CHECKPOINT_COLUMNS`) embedded into `sql.unsafe`, and
+ * every VALUE is a bound `$n` parameter, never interpolated.
+ */
+import type { Position } from '@kairos-es/core';
+import type { CheckpointKey } from '@kairos-es/read';
+import { type ResolvedCheckpointNames } from './ddl.js';
+/**
+ * The four statement texts a store issues, compiled ONCE per store from the
+ * resolved names — the same compile-once discipline as the event store's read
+ * plans, so a long-lived projection re-binds only its parameters rather than
+ * re-assembling SQL per batch.
+ *
+ * All four take their parameters in ONE positional order — `$1` projection,
+ * `$2` partition, `$3` next, `$4` expected — and no consumer writes that order
+ * out: `keyParams` binds the two the `select` and the `reset` take, and
+ * `advanceParams` binds all four for the two guard shapes, reading each from a
+ * NAMED field. That naming is the point rather than a nicety, because the type
+ * system cannot help here: `next` and `expected` are the same type, so a
+ * positional list makes `[..., expected, next]` typecheck, and a transposed guard
+ * would compare the stored cursor against the position it was about to write —
+ * inverting the compare-and-set that makes a projection exactly-once. Reading the
+ * fields by name does not make the mistake impossible, but it makes it
+ * unwritable without naming the wrong field, which review and a diff can see.
+ */
+export interface CheckpointStatements {
+    readonly select: string;
+    readonly upsertFromOrigin: string;
+    readonly advance: string;
+    readonly reset: string;
+}
+/**
+ * Build the statement texts for a resolved name set.
+ *
+ * **The two guard shapes, and why one cannot serve both.** The guarded advance is
+ * a compare-and-set on `last_position`, and its correct SQL depends on whether the
+ * expected value is `ORIGIN`:
+ *
+ * - `expected === ORIGIN` needs `upsertFromOrigin`. A never-committed key has NO
+ *   ROW (a key reads back as `ORIGIN` by absence, so "fresh" and "reset" are one
+ *   state), so a plain `UPDATE` would match zero rows and report
+ *   `CheckpointSuperseded` — a fresh read model could never make its FIRST commit.
+ *   The `ON CONFLICT … DO UPDATE … WHERE chk.last_position = $4` arm keeps the
+ *   upsert a real guard rather than a blind write: two racers both starting from
+ *   `ORIGIN` cannot both win, because the second one's arm blocks on the first's
+ *   uncommitted row, then re-reads it and finds a position that is no longer
+ *   `ORIGIN`, matching zero rows. That arm also makes "row present at `0`"
+ *   (an operator zeroing the column by hand instead of deleting the row) behave
+ *   identically to "row absent", so the two ways of expressing a reset are
+ *   indistinguishable to a first commit.
+ * - `expected > ORIGIN` needs `advance`, the plain `UPDATE`. The upsert would be
+ *   WRONG here: `ON CONFLICT` guards only the branch where the row exists, so an
+ *   absent row would be INSERTED unconditionally — a `resetCheckpoint` racing an
+ *   in-flight commit would be silently undone, the key resurrected at `next`, and
+ *   the entire backlog the reset existed to replay skipped with no error at all.
+ *   The `UPDATE`'s zero rows for an absent row is the CORRECT outcome: somebody
+ *   reset it, so this commit must lose and the runner must re-read.
+ *
+ * Both shapes `RETURNING` a column so the outcome is a ROW COUNT: zero rows means
+ * the guard lost. That mirrors the event store's append, where a conflict is the
+ * function's zero-row result and never a caught SQL error — no unique-violation
+ * or serialisation-failure path to classify, so a lost guard can never arrive
+ * mistagged as an infrastructure fault.
+ *
+ * The `AS chk` alias exists so the `DO UPDATE` guard can reference the EXISTING
+ * row unambiguously: the insert target is schema-qualified, and without an alias
+ * the guard would need a three-part column reference.
+ */
+export declare const compileStatements: (names: ResolvedCheckpointNames) => CheckpointStatements;
+/** The `$1`/`$2` key parameters the `select` and the `reset` take. */
+export declare const keyParams: (key: CheckpointKey) => ReadonlyArray<unknown>;
+/**
+ * The `$1`-`$4` parameters both guard shapes take, read from named fields.
+ *
+ * The argument is an object rather than three positional parameters for the reason
+ * `CheckpointStatements` gives: `next` and `expected` are interchangeable to the
+ * type checker and catastrophic to swap, so the ONE place their order is written
+ * out reads each of them by name.
+ */
+export declare const advanceParams: (args: {
+    readonly key: CheckpointKey;
+    readonly expected: Position;
+    readonly next: Position;
+}) => ReadonlyArray<unknown>;
+//# sourceMappingURL=statements.d.ts.map

package/dist/dts-esm/internal/statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.d.ts","sourceRoot":"","sources":["../../../src/internal/statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,OAAO,CAAA;AAEd;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,uBAAuB,KAC7B,oBA2BF,CAAA;AAED,sEAAsE;AACtE,eAAO,MAAM,SAAS,GAAI,KAAK,aAAa,KAAG,aAAa,CAAC,OAAO,CAGnE,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM;IAClC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CACxB,KAAG,aAAa,CAAC,OAAO,CAKxB,CAAA"}

package/dist/dts-esm/package.json

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

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

@@ -0,0 +1,77 @@
+/**
+ * The SQL `ProjectionStore`: a durable scalar checkpoint plus the guarded
+ * compare-and-set that brackets a read model's own view writes in ONE ordinary
+ * transaction (ADR-0007).
+ *
+ * This is the durable half of the parity pair. `@kairos-es/read`'s in-memory store
+ * is the oracle; this backend must produce identical OBSERVABLE behaviour, and the
+ * shared `projection-store-contract-tests` suite runs unchanged against both. The
+ * one place the two genuinely differ is HOW the abort is achieved:
+ *
+ * - in memory, the guard is checked FIRST and a loss means `viewWrites` never ran
+ *   (abort by omission — there is nothing to undo);
+ * - here, `viewWrites` runs first and a lost guard FAILS, so the transaction rolls
+ *   the view writes back with it (abort by undo).
+ *
+ * Both satisfy the port's promise that a lost guard leaves no observable view
+ * effect, which is why ordering inside the transaction is a performance choice
+ * rather than a correctness one: running the guard last keeps the checkpoint row
+ * lock held only for the advance instead of for the whole batch's worth of view
+ * writes.
+ *
+ * Two contract inversions worth naming, both deliberate:
+ *
+ * 1. A `SqlError` becomes a `ProjectionStoreError` on the ERROR CHANNEL — the
+ *    opposite of the event store, where an infrastructure fault is a DEFECT
+ *    (`Effect.die`, ADR-0002). The read side has a supervisor above it whose whole
+ *    job is telling "retry the subscription with backoff" from "give up and report
+ *    a stalled projection", and a defect carries no such distinction. On the event
+ *    store there is no supervisor: a caller cannot meaningfully retry a broken
+ *    connection, so dying is right there and wrong here.
+ * 2. A lost guard is a tagged failure (`CheckpointSuperseded`), never a returned
+ *    outcome value, and that failure is exactly what aborts the transaction. A
+ *    returned value would only roll back if the caller remembered to convert it
+ *    into a failure, and forgetting is silent double-application.
+ *
+ * The store closes over the `SqlClient` it acquired, so the returned
+ * `ProjectionStore.commit` adds NO `SqlClient` to the caller's `R` — a read model
+ * stays free of the view store's requirements, which is what lets one runner drive
+ * read models over different backends.
+ *
+ * What this module owns is the Effect wiring: the client, the transaction bracket,
+ * the error classification. The SQL itself and the parameter lists that feed it are
+ * `internal/statements.ts`, which owns the argument for why the two live together.
+ */
+import { type ProjectionStore } from '@kairos-es/read';
+import { Effect } from 'effect';
+import { SqlClient } from 'effect/sql';
+import { type ReadPostgresConfig } from './config.js';
+/**
+ * Build a durable `ProjectionStore` over the ambient `SqlClient`.
+ *
+ * A factory `Effect` rather than a `Layer`, matching the in-memory store: the view
+ * store is selected PER MATERIALISATION, so it is a value handed to a read model, not
+ * a context service one store could claim process-wide. Per materialisation rather than
+ * per read model, because one read model may be materialised several times at once —
+ * a store from here beside an in-memory one, wired by `@kairos-es/read`'s
+ * `runProjections` — which is a shape a process-wide service could not express at all. It
+ * acquires the client ONCE and closes over it, which is what keeps `commit`'s `R`
+ * down to the caller's own.
+ *
+ * **The atomic bracket covers writes issued through THIS client.** The caller's
+ * `viewWrites` join the transaction only when they are issued through the same
+ * `SqlClient` the store was built from: `effect/sql` carries the transaction's
+ * connection in the Effect CONTEXT under a key that belongs to that one client
+ * instance, so a statement run inside `commit` finds the open transaction only if
+ * its client owns that key. The store's own `withoutTransforms()` copy shares the
+ * key, which is why the guarded advance and the caller's view writes land in one
+ * transaction; a write through any OTHER `SqlClient` instance — even one over the
+ * same database — or to a different database is NOT bracketed, is not rolled back
+ * on a lost guard, and the exactly-once property does not extend to it.
+ *
+ * `ensureCheckpointSchema(config)` must have run (in the caller's migrator or at
+ * boot) before the store is used; this factory performs no DDL, so it stays a pure
+ * runtime dependency on the client alone.
+ */
+export declare const makeSqlProjectionStore: (config?: ReadPostgresConfig) => Effect.Effect<ProjectionStore, never, SqlClient.SqlClient>;
+//# sourceMappingURL=projectionStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projectionStore.d.ts","sourceRoot":"","sources":["../../src/projectionStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAGL,KAAK,eAAe,EAErB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAmF5E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAQ,kBAAuB,KAC9B,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,EAAE,SAAS,CAAC,SAAS,CA4IxD,CAAA"}

package/dist/esm/config.js

@@ -21,7 +21,7 @@
  * per-materialisation view-store design exists to avoid: a durable view must be
  * free to sit over any log satisfying `DcbEventStore` — the in-memory oracle,
  * Postgres, a future backend — so this package depends on the PORT
- * (`@kairos-es/read`) and on `@effect/sql`, never on a sibling backend. The
+ * (`@kairos-es/read`) and on `effect/sql`, never on a sibling backend. The
  * duplication also keeps the two guards honestly independent: each package
  * measures only the identifiers IT materialises, so neither inherits a byte budget
  * from names it never creates.
@@ -41,7 +41,7 @@ import { oversizedIdentifier } from "./internal/ddl.js";
  * dot-split when quoted, so an embedded dot would silently re-partition the name
  * into the wrong schema/object.
  */
-const IdentifierAtom = /*#__PURE__*/Schema.String.pipe(/*#__PURE__*/Schema.nonEmptyString(), /*#__PURE__*/Schema.pattern(/^[^.]+$/, {
+const IdentifierAtom = /*#__PURE__*/Schema.String.check(/*#__PURE__*/Schema.isNonEmpty(), /*#__PURE__*/Schema.isPattern(/^[^.]+$/, {
   identifier: 'PostgresIdentifierAtom',
   description: 'a non-empty identifier atom containing no "."'
 }));
@@ -56,24 +56,20 @@ const IdentifierAtom = /*#__PURE__*/Schema.String.pipe(/*#__PURE__*/Schema.nonEm
  *   objects, one isolated store per prefix.
  */
 export const ReadPostgresConfig = /*#__PURE__*/Schema.Struct({
-  // `exact: true` keeps the decoded type at `key?: T` (never `T | undefined`),
+  // `optionalKey` keeps the decoded type at `key?: T` (never `T | undefined`),
   // matching the repo's `exactOptionalPropertyTypes` discipline — an absent key,
   // not an explicit `undefined`.
-  schema: Schema.optionalWith(IdentifierAtom, {
-    exact: true
-  }),
-  tablePrefix: Schema.optionalWith(IdentifierAtom, {
-    exact: true
-  })
-}).pipe(
+  schema: Schema.optionalKey(IdentifierAtom),
+  tablePrefix: Schema.optionalKey(IdentifierAtom)
+}).check(
 /*#__PURE__*/
 // Cross-field guard: the derived table name must fit Postgres's 63-byte
 // identifier limit. Returning the message string fails the decode with it;
-// `undefined`/`true` passes.
-Schema.filter(config => oversizedIdentifier(config) ?? true));
+// `undefined` passes.
+Schema.makeFilter(config => oversizedIdentifier(config)));
 /**
  * Decode an unknown value into a validated `ReadPostgresConfig`, throwing a
- * `ParseError` on any violation. Used by `makeSqlProjectionStore` and
+ * `SchemaError` on any violation. Used by `makeSqlProjectionStore` and
  * `ensureCheckpointSchema` so a bad config fails at construction time.
  */
 export const decodeReadPostgresConfig = /*#__PURE__*/Schema.decodeUnknownSync(ReadPostgresConfig);

package/dist/esm/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","names":["Schema","oversizedIdentifier","IdentifierAtom","String","pipe","nonEmptyString","pattern","identifier","description","ReadPostgresConfig","Struct","schema","optionalWith","exact","tablePrefix","filter","config","decodeReadPostgresConfig","decodeUnknownSync"],"sources":["../../src/config.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAASA,MAAM,QAAQ,QAAQ;AAC/B,SAASC,mBAAmB,QAAQ,mBAAgB;AAEpD;;;;;;AAMA,MAAMC,cAAc,gBAAGF,MAAM,CAACG,MAAM,CAACC,IAAI,cACvCJ,MAAM,CAACK,cAAc,EAAE,eACvBL,MAAM,CAACM,OAAO,CAAC,SAAS,EAAE;EACxBC,UAAU,EAAE,wBAAwB;EACpCC,WAAW,EAAE;CACd,CAAC,CACH;AAED;;;;;;;;;;AAUA,OAAO,MAAMC,kBAAkB,gBAAGT,MAAM,CAACU,MAAM,CAAC;EAC9C;EACA;EACA;EACAC,MAAM,EAAEX,MAAM,CAACY,YAAY,CAACV,cAAc,EAAE;IAAEW,KAAK,EAAE;EAAI,CAAE,CAAC;EAC5DC,WAAW,EAAEd,MAAM,CAACY,YAAY,CAACV,cAAc,EAAE;IAAEW,KAAK,EAAE;EAAI,CAAE;CACjE,CAAC,CAACT,IAAI;AAAA;AACL;AACA;AACA;AACAJ,MAAM,CAACe,MAAM,CAAEC,MAAM,IAAKf,mBAAmB,CAACe,MAAM,CAAC,IAAI,IAAI,CAAC,CAC/D;AAGD;;;;;AAKA,OAAO,MAAMC,wBAAwB,gBACnCjB,MAAM,CAACkB,iBAAiB,CAACT,kBAAkB,CAAC","ignoreList":[]}
+{"version":3,"file":"config.js","names":["Schema","oversizedIdentifier","IdentifierAtom","String","check","isNonEmpty","isPattern","identifier","description","ReadPostgresConfig","Struct","schema","optionalKey","tablePrefix","makeFilter","config","decodeReadPostgresConfig","decodeUnknownSync"],"sources":["../../src/config.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAASA,MAAM,QAAQ,QAAQ;AAC/B,SAASC,mBAAmB,QAAQ,mBAAgB;AAEpD;;;;;;AAMA,MAAMC,cAAc,gBAAGF,MAAM,CAACG,MAAM,CAACC,KAAK,cACxCJ,MAAM,CAACK,UAAU,EAAE,eACnBL,MAAM,CAACM,SAAS,CAAC,SAAS,EAAE;EAC1BC,UAAU,EAAE,wBAAwB;EACpCC,WAAW,EAAE;CACd,CAAC,CACH;AAED;;;;;;;;;;AAUA,OAAO,MAAMC,kBAAkB,gBAAGT,MAAM,CAACU,MAAM,CAAC;EAC9C;EACA;EACA;EACAC,MAAM,EAAEX,MAAM,CAACY,WAAW,CAACV,cAAc,CAAC;EAC1CW,WAAW,EAAEb,MAAM,CAACY,WAAW,CAACV,cAAc;CAC/C,CAAC,CAACE,KAAK;AAAA;AACN;AACA;AACA;AACAJ,MAAM,CAACc,UAAU,CAAEC,MAAM,IAAKd,mBAAmB,CAACc,MAAM,CAAC,CAAC,CAC3D;AAGD;;;;;AAKA,OAAO,MAAMC,wBAAwB,gBACnChB,MAAM,CAACiB,iBAAiB,CAACR,kBAAkB,CAAC","ignoreList":[]}

package/dist/esm/ensureCheckpointSchema.js

@@ -4,7 +4,7 @@
  *
  * It is a single `Effect<void, SqlError, SqlClient>` that creates (or refreshes)
  * the one object this package owns: the checkpoint table. It requires the GENERIC
- * `SqlClient` tag — not a package-owned client tag — precisely so a consumer can
+ * `SqlClient` service — not a package-owned client service — precisely so a consumer can
  * drop it straight into THEIR OWN migrator, e.g.:
  *
  * ```ts
@@ -27,8 +27,8 @@
  * reads no rows and passes no identifier through `sql(identifier)`, so a
  * consumer's name transforms have nothing here to rewrite.
  */
-import { SqlClient } from '@effect/sql';
 import { Effect } from 'effect';
+import { SqlClient } from 'effect/sql';
 import { decodeReadPostgresConfig } from "./config.js";
 import { resolveCheckpointNames, runCheckpointDdl } from "./internal/ddl.js";
 /**

package/dist/esm/ensureCheckpointSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"ensureCheckpointSchema.js","names":["SqlClient","Effect","decodeReadPostgresConfig","resolveCheckpointNames","runCheckpointDdl","ensureCheckpointSchema","config","gen","sql","names","all","discard"],"sources":["../../src/ensureCheckpointSchema.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAASA,SAAS,QAAuB,aAAa;AACtD,SAASC,MAAM,QAAQ,QAAQ;AAC/B,SAASC,wBAAwB,QAAiC,aAAU;AAC5E,SAASC,sBAAsB,EAAEC,gBAAgB,QAAQ,mBAAgB;AAEzE;;;;;AAKA,OAAO,MAAMC,sBAAsB,GACjCC,MAA0B,IAE1BL,MAAM,CAACM,GAAG,CAAC,aAAS;EAClB,MAAMC,GAAG,GAAG,OAAOR,SAAS,CAACA,SAAS;EACtC;EACA;EACA;EACA,MAAMS,KAAK,GAAGN,sBAAsB,CAACD,wBAAwB,CAACI,MAAM,CAAC,CAAC;EACtE;EACA,OAAOL,MAAM,CAACS,GAAG,CAACN,gBAAgB,CAACI,GAAG,EAAEC,KAAK,CAAC,EAAE;IAAEE,OAAO,EAAE;EAAI,CAAE,CAAC;AACpE,CAAC,CAAC","ignoreList":[]}
+{"version":3,"file":"ensureCheckpointSchema.js","names":["Effect","SqlClient","decodeReadPostgresConfig","resolveCheckpointNames","runCheckpointDdl","ensureCheckpointSchema","config","gen","sql","names","all","discard"],"sources":["../../src/ensureCheckpointSchema.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAASA,MAAM,QAAQ,QAAQ;AAC/B,SAASC,SAAS,QAAuB,YAAY;AACrD,SAASC,wBAAwB,QAAiC,aAAU;AAC5E,SAASC,sBAAsB,EAAEC,gBAAgB,QAAQ,mBAAgB;AAEzE;;;;;AAKA,OAAO,MAAMC,sBAAsB,GACjCC,MAA0B,IAE1BN,MAAM,CAACO,GAAG,CAAC,aAAS;EAClB,MAAMC,GAAG,GAAG,OAAOP,SAAS,CAACA,SAAS;EACtC;EACA;EACA;EACA,MAAMQ,KAAK,GAAGN,sBAAsB,CAACD,wBAAwB,CAACI,MAAM,CAAC,CAAC;EACtE;EACA,OAAON,MAAM,CAACU,GAAG,CAACN,gBAAgB,CAACI,GAAG,EAAEC,KAAK,CAAC,EAAE;IAAEE,OAAO,EAAE;EAAI,CAAE,CAAC;AACpE,CAAC,CAAC","ignoreList":[]}

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["ensureCheckpointSchema","makeSqlProjectionStore"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAuFA,SAASA,sBAAsB,QAAQ,6BAA0B;AACjE,SAASC,sBAAsB,QAAQ,sBAAmB","ignoreList":[]}
+{"version":3,"file":"index.js","names":["ensureCheckpointSchema","makeSqlProjectionStore"],"sources":["../../src/index.ts"],"sourcesContent":[null],"mappings":"AAyFA,SAASA,sBAAsB,QAAQ,6BAA0B;AACjE,SAASC,sBAAsB,QAAQ,sBAAmB","ignoreList":[]}