@structure-ai/eventsourcing-nisshi 0.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ligerian Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @structure-ai/eventsourcing-nisshi
+
+[Nisshi](https://github.com/nisshi-io/nisshi) (Kafka-API compatible broker) as the event store, with a small SQL sidecar (SQLite or PostgreSQL via `@effect/sql`) for everything a log cannot do on its own: optimistic concurrency, snapshots, checkpoints, and inbox dedupe.
+
+Implements **four** ports: `EventStore`, `SnapshotStore`, `CheckpointStore`, `Inbox`. There is **no `Outbox`** by design — see [ADR-0015](../../docs/decisions/0015-nisshi-event-store.md): the event topic itself is the publication; cross-context consumers read it directly and dedupe via `Inbox`.
+
+## How it works
+
+- **Events** live in one single-partition topic (default `events`), key = stream name, value = a JSON envelope `{type, schemaVersion, version, payload, metadata}`. Infinite retention, no compaction — the topic *is* the raw history.
+- **Positions** are Kafka offsets + 1 — a true global total order (single partition).
+- **Optimistic concurrency** via the sidecar ledger: `append(stream, expectedVersion, events)` reserves `expectedVersion+1..n` in one SQL transaction (conditional UPDATE / unique INSERT), produces with `acks=all`, then confirms. A lost race fails with `ConcurrencyConflict` before anything is written. A crash between reservation and produce leaves pending rows that `drainPending` re-produces (at-least-once; readers dedupe by `(stream, version)`).
+- **Snapshots / checkpoints / inbox** are sidecar tables (pure cache and dedupe state; losing them costs performance, never correctness).
+- **Protocol**: an in-package minimal Kafka wire client (no runtime dependencies) pinned to non-flexible API versions — `Produce` v3, `Fetch` v4, `Metadata` v0, `CreateTopics` v4 — negotiated and verified at connect. No consumer groups, no transactions: reads are positioned fetches, progress tracking is the sidecar checkpoint.
+
+## Usage
+
+SQLite sidecar:
+
+```ts
+import { layer, runPendingRelay } from "@structure-ai/eventsourcing-nisshi";
+
+const durable = layer({
+  brokerUrl: "tcp://127.0.0.1:9092", // must equal the broker's advertised listener
+  filename: "./sidecar.db",           // ":memory:" for tests
+  topic: "events",                    // single partition, created when missing
+});
+```
+
+PostgreSQL sidecar:
+
+```ts
+import { layerPg } from "@structure-ai/eventsourcing-nisshi";
+
+const durable = layerPg({
+  brokerUrl: "tcp://127.0.0.1:9092",
+  url: "postgres://app:secret@db:5432/app", // defaults to DATABASE_URL
+  applicationName: "orders",
+  maxConnections: 10,
+  topic: "events",
+});
+```
+
+On an existing SQLite or PostgreSQL `SqlClient` plus `NisshiClient`, use `storesLayer(options)` and run `migrate(options)` first.
+
+Run the orphan relay in a worker (or every app instance, it is idempotent):
+
+```ts
+Effect.runFork(runPendingRelay({ pollInterval: 500 }));
+```
+
+## Options
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `brokerUrl` | — | Broker listener; must match `--kafka-advertised-listener-url`. |
+| `filename` (`layer`) | — | Sidecar SQLite file (`":memory:"` works). |
+| `url` (`layerPg`) | `DATABASE_URL` / libpq defaults | Sidecar PostgreSQL connection URL. |
+| `applicationName` / `maxConnections` (`layerPg`) | driver defaults | PostgreSQL pool options. |
+| `topic` | `"events"` | Must have exactly one partition (verified; ADR-0015). |
+| `createTopic` | `true` | Create the topic at layer start when missing. |
+| `schemaValidation` | `true` | Validate envelopes client-side before produce. |
+| `tablePrefix` | — | Namespace sidecar tables. |
+
+## Schema files (broker-side validation, forward path)
+
+`writeSchemaFiles(dir, topics)` writes one JSON Schema (`<topic>.json`) per topic describing the envelope. Mount the directory with the broker's `--schema-registry file://./<dir>` (relative paths only — Nisshi collapses leading slashes). Note: broker-side enforcement did **not** engage on Nisshi v0.7.0-pre.2 (its own CLI accepts records violating its own sample schemas); client-side validation is the effective guard until a Nisshi release enforces it.
+
+## Production topologies
+
+The **sidecar** may be SQLite (`layer`) or PostgreSQL (`layerPg`). Use PostgreSQL when multiple app instances can command the same aggregate: the concurrency ledger must be shared. A process-local SQLite sidecar is only safe for a single writer instance.
+
+Separately, Nisshi backs the broker with pluggable storage:
+
+- **PostgreSQL** — `nisshi --storage-engine postgres://user:pass@host:5432/db`
+- **S3-compatible** — `nisshi --storage-engine s3://bucket/prefix` (11-nines durability class)
+- **libSQL/SQLite** — `nisshi --storage-engine sqlite://nisshi.db` (single host)
+
+The sidecar and broker storage may share one PostgreSQL server, but use separate schemas/credentials and backup policies. Run one broker process per availability need — brokers are stateless, all are leaders; durability comes from the storage engine, not broker replication. Set `--kafka-advertised-listener-url` to the address clients dial.
+
+## Tests
+
+`bun test` skips broker suites unless `NISSHI_URL` is set; PostgreSQL-sidecar scenarios additionally require `DATABASE_URL`. CI installs a pinned Nisshi release, starts PostgreSQL, and runs both sidecar suites. The wire quirks this client encodes (trailing `throttle_time_ms` in Produce, metadata-triggered topic auto-creation, empty-topic high watermark of 1, whole-batch fetch granularity) are pinned by tests in `test/protocol.test.ts`.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@structure-ai/eventsourcing-nisshi",
+  "version": "0.0.10",
+  "description": "Nisshi (Kafka-API broker) event store with a SQL sidecar for optimistic concurrency, snapshots, checkpoints, and inbox dedupe.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ligerian-labs/structure.git",
+    "directory": "packages/eventsourcing-nisshi"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "effect": "^3.22.1",
+    "@effect/sql": "^0.52.1",
+    "@effect/sql-sqlite-bun": "^0.53.0",
+    "@effect/sql-pg": "^0.53.0",
+    "@structure-ai/domain": "0.0.10",
+    "@structure-ai/eventsourcing": "0.0.10"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2",
+    "@types/bun": "^1.3.14"
+  }
+}

package/src/EventStore.ts

@@ -0,0 +1,337 @@
+import * as SqlClient from "@effect/sql/SqlClient";
+import type { SqlError } from "@effect/sql/SqlError";
+import { ConcurrencyConflict } from "@structure-ai/domain";
+import {
+  type AppendEvent,
+  type AppendResult,
+  EventStore,
+  type EventStoreService,
+  type StoredEvent,
+  type StoredEventMetadata,
+} from "@structure-ai/eventsourcing";
+import { Effect, Layer, Stream } from "effect";
+import { decodeWireEvent, encodeWireEvent, validateWireEvent } from "./envelope.js";
+import { NisshiClient } from "./protocol/client.js";
+import { NisshiProduceError } from "./protocol/errors.js";
+import { type SidecarOptions, type SidecarTables, sidecarTables } from "./sidecar.js";
+
+/** Options for the Nisshi event-store adapter. */
+export interface EventStoreOptions extends SidecarOptions {
+  /** Topic holding all streams' events (single partition; default `events`). */
+  readonly topic?: string;
+  /** Validate the envelope client-side before produce (default: true). */
+  readonly schemaValidation?: boolean;
+}
+
+/** Whether a `SqlError` is a unique-constraint violation (both dialects). */
+const isUniqueViolation = (error: unknown): boolean => {
+  if (typeof error !== "object" || error === null || !("cause" in error)) {
+    return false;
+  }
+  const cause: unknown = error.cause;
+  if (typeof cause !== "object" || cause === null || !("message" in cause)) {
+    return false;
+  }
+  const message = cause.message;
+  return (
+    typeof message === "string" &&
+    (message.includes("UNIQUE constraint failed") || message.includes("duplicate key value"))
+  );
+};
+
+const toNumber = (value: number | bigint | string | null | undefined): number =>
+  value === null || value === undefined ? 0 : Number(value);
+
+/** Splits a stream name into the conflict's entity/id at the first `-`. */
+const conflictIdentity = (streamName: string): { entity: string; id: string } => {
+  const separator = streamName.indexOf("-");
+  return separator === -1
+    ? { entity: streamName, id: streamName }
+    : { entity: streamName.slice(0, separator), id: streamName.slice(separator + 1) };
+};
+
+const conflict = (
+  streamName: string,
+  expectedVersion: number,
+  actualVersion: number,
+): ConcurrencyConflict => {
+  const { entity, id } = conflictIdentity(streamName);
+  return new ConcurrencyConflict({ entity, id, expectedVersion, actualVersion });
+};
+
+const storedEvent = (
+  offset: bigint,
+  streamName: string,
+  envelope: {
+    readonly type: string;
+    readonly schemaVersion: number;
+    readonly version: number;
+    readonly payload: unknown;
+    readonly metadata: StoredEventMetadata;
+  },
+): StoredEvent => ({
+  position: offset + 1n,
+  streamName,
+  version: envelope.version,
+  type: envelope.type,
+  schemaVersion: envelope.schemaVersion,
+  payload: envelope.payload,
+  metadata: envelope.metadata,
+});
+
+const make = (
+  options: EventStoreOptions,
+): Effect.Effect<EventStoreService, never, SqlClient.SqlClient | NisshiClient> =>
+  Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const client = yield* NisshiClient;
+    const tables: SidecarTables = sidecarTables(options);
+    const topic = options.topic ?? "events";
+    const validate = options.schemaValidation ?? true;
+    const maxBytes = 4 * 1024 * 1024;
+
+    const currentVersion = (streamName: string): Effect.Effect<number, SqlError> =>
+      Effect.map(
+        sql<{ readonly last_version: number | bigint | string | null }>`
+          SELECT last_version FROM ${sql(tables.streams)} WHERE stream_name = ${streamName}
+        `,
+        (rows) => toNumber(rows[0]?.last_version),
+      );
+
+    /**
+     * Reserves `expectedVersion + 1 .. + n` for the stream and stages the
+     * wire events as pending rows — one transaction. The unique PK on
+     * `(stream_name, version)` plus the conditional UPDATE make double
+     * reservations impossible; both surface as `ConcurrencyConflict`.
+     */
+    const reserve = (
+      streamName: string,
+      expectedVersion: number,
+      events: ReadonlyArray<AppendEvent>,
+    ): Effect.Effect<AppendResult, ConcurrencyConflict | SqlError> =>
+      sql
+        .withTransaction(
+          Effect.gen(function* () {
+            if (events.length === 0) {
+              const actual = yield* currentVersion(streamName);
+              if (actual !== expectedVersion) {
+                return yield* Effect.fail(conflict(streamName, expectedVersion, actual));
+              }
+              return { firstVersion: expectedVersion, lastVersion: expectedVersion };
+            }
+            if (expectedVersion === 0) {
+              yield* sql`
+              INSERT INTO ${sql(tables.streams)} (stream_name, last_version)
+              VALUES (${streamName}, ${events.length})
+            `;
+            } else {
+              // Conditional CAS: bumps only when the observed version matches.
+              yield* sql`
+              UPDATE ${sql(tables.streams)}
+              SET last_version = last_version + ${events.length}
+              WHERE stream_name = ${streamName} AND last_version = ${expectedVersion}
+            `;
+            }
+            // Authoritative CAS check: re-read after the write attempt.
+            const actual = yield* currentVersion(streamName);
+            const intended = expectedVersion + events.length;
+            if (actual !== intended) {
+              return yield* Effect.fail(conflict(streamName, expectedVersion, actual));
+            }
+            yield* Effect.forEach(
+              events,
+              (event, index) => {
+                const wire = {
+                  type: event.type,
+                  schemaVersion: event.schemaVersion,
+                  version: expectedVersion + index + 1,
+                  payload: event.payload,
+                  metadata: event.metadata,
+                };
+                if (validate) {
+                  validateWireEvent(wire, streamName);
+                }
+                return sql`
+                INSERT INTO ${sql(tables.pending)} (stream_name, version, topic, record_value)
+                VALUES (${streamName}, ${expectedVersion + index + 1}, ${topic}, ${JSON.stringify(wire)})
+              `;
+              },
+              { discard: true },
+            );
+            return {
+              firstVersion: expectedVersion + 1,
+              lastVersion: expectedVersion + events.length,
+            };
+          }),
+        )
+        .pipe(
+          Effect.catchIf(
+            (error): error is SqlError => isUniqueViolation(error),
+            () =>
+              Effect.flatMap(Effect.orDie(currentVersion(streamName)), (actual) =>
+                Effect.fail(conflict(streamName, expectedVersion, actual)),
+              ),
+          ),
+        );
+
+    /** Best-effort reservation rollback: only succeeds if nobody built on top. Never masks the original failure. */
+    const rollback = (
+      streamName: string,
+      expectedVersion: number,
+      count: number,
+    ): Effect.Effect<void> =>
+      sql
+        .withTransaction(
+          Effect.gen(function* () {
+            yield* sql`
+              UPDATE ${sql(tables.streams)}
+              SET last_version = ${expectedVersion}
+              WHERE stream_name = ${streamName} AND last_version = ${expectedVersion + count}
+            `;
+            yield* sql`
+              DELETE FROM ${sql(tables.pending)}
+              WHERE stream_name = ${streamName}
+                AND version > ${expectedVersion} AND version <= ${expectedVersion + count}
+            `;
+          }),
+        )
+        .pipe(
+          Effect.ignore,
+          Effect.catchAllDefect(() => Effect.void),
+        );
+
+    const append: EventStoreService["append"] = (streamName, expectedVersion, events) =>
+      Effect.gen(function* () {
+        const result = yield* reserve(streamName, expectedVersion, events).pipe(
+          Effect.catchTag("SqlError", (error) => Effect.die(error)),
+        );
+        if (events.length === 0) {
+          return result;
+        }
+        const records = events.map((event, index) => ({
+          key: new TextEncoder().encode(streamName),
+          value: encodeWireEvent({
+            type: event.type,
+            schemaVersion: event.schemaVersion,
+            version: expectedVersion + index + 1,
+            payload: event.payload,
+            metadata: event.metadata,
+          }),
+        }));
+        yield* client.produce(topic, records).pipe(
+          Effect.catchAllCause((cause) =>
+            Effect.gen(function* () {
+              yield* rollback(streamName, expectedVersion, events.length);
+              return yield* Effect.die(new NisshiProduceError({ topic, cause }));
+            }),
+          ),
+        );
+        // Confirm: events are durable in the topic. A failure here leaves the
+        // pending rows for the relay; a re-produce duplicates are tolerated
+        // downstream (readers dedupe by version).
+        yield* sql`
+          DELETE FROM ${sql(tables.pending)}
+          WHERE stream_name = ${streamName}
+            AND version > ${expectedVersion} AND version <= ${expectedVersion + events.length}
+        `.pipe(
+          Effect.catchTag("SqlError", (error) =>
+            Effect.logWarning(`pending confirm failed: ${error.message}`),
+          ),
+        );
+        return result;
+      });
+
+    /** Reads every committed record of the topic from `offset` on. */
+    interface TopicRecords {
+      readonly records: ReadonlyArray<{
+        readonly offset: bigint;
+        readonly streamName: string;
+        readonly value: Uint8Array;
+      }>;
+    }
+    const readTopic = (fromOffset: bigint): Effect.Effect<TopicRecords> =>
+      Effect.gen(function* () {
+        const out: { offset: bigint; streamName: string; value: Uint8Array }[] = [];
+        let offset = fromOffset;
+        for (;;) {
+          const page = yield* client.fetch(topic, offset, maxBytes).pipe(Effect.orDie);
+          if (page.records.length === 0) {
+            return { records: out };
+          }
+          for (const record of page.records) {
+            out.push({
+              offset: record.offset,
+              streamName: record.key === null ? "" : new TextDecoder().decode(record.key),
+              value: record.value,
+            });
+          }
+          const last = page.records[page.records.length - 1];
+          if (last === undefined || last.offset + 1n >= page.highWatermark) {
+            return { records: out };
+          }
+          offset = last.offset + 1n;
+        }
+      });
+
+    const service: EventStoreService = {
+      append,
+      read: (streamName, readOptions) =>
+        Stream.unwrap(
+          Effect.map(readTopic(0n), ({ records }) => {
+            const fromVersion = readOptions?.fromVersion ?? 1;
+            const seen = new Set<number>();
+            const events: StoredEvent[] = [];
+            for (const record of records) {
+              if (record.streamName !== streamName) {
+                continue;
+              }
+              const envelope = decodeWireEvent(record.value, streamName);
+              if (envelope.version < fromVersion || seen.has(envelope.version)) {
+                continue;
+              }
+              seen.add(envelope.version);
+              events.push(storedEvent(record.offset, streamName, envelope));
+            }
+            events.sort((a, b) => a.version - b.version);
+            return Stream.fromIterable(events);
+          }),
+        ),
+      readAll: (readOptions) =>
+        Stream.unwrap(
+          Effect.gen(function* () {
+            const events: StoredEvent[] = [];
+            let offset = (readOptions?.fromPosition ?? 1n) - 1n;
+            const limit = readOptions?.batchSize;
+            for (;;) {
+              if (limit !== undefined && events.length >= limit) {
+                break;
+              }
+              const page = yield* client.fetch(topic, offset, maxBytes).pipe(Effect.orDie);
+              if (page.records.length === 0) {
+                break;
+              }
+              for (const record of page.records) {
+                const streamName = record.key === null ? "" : new TextDecoder().decode(record.key);
+                events.push(
+                  storedEvent(record.offset, streamName, decodeWireEvent(record.value, streamName)),
+                );
+              }
+              const last = page.records[page.records.length - 1];
+              if (last === undefined || last.offset + 1n >= page.highWatermark) {
+                break;
+              }
+              offset = last.offset + 1n;
+            }
+            const bounded = limit === undefined ? events : events.slice(0, limit);
+            return Stream.fromIterable(bounded);
+          }),
+        ),
+    };
+    return service;
+  });
+
+/** `EventStore` over Nisshi + the sidecar ledger. */
+export const eventStoreLayer = (
+  options?: EventStoreOptions,
+): Layer.Layer<EventStore, never, SqlClient.SqlClient | NisshiClient> =>
+  Layer.effect(EventStore, make(options ?? {}));

package/src/Stores.ts

@@ -0,0 +1,115 @@
+import * as SqlClient from "@effect/sql/SqlClient";
+import {
+  CheckpointStore,
+  type CheckpointStoreService,
+  Inbox,
+  type InboxService,
+  SnapshotStore,
+  type SnapshotStoreService,
+} from "@structure-ai/eventsourcing";
+import { Effect, Layer, Option } from "effect";
+import { type SidecarOptions, sidecarTables } from "./sidecar.js";
+
+const toBigInt = (value: number | bigint | string | null | undefined): bigint =>
+  value === null || value === undefined ? 0n : BigInt(value);
+
+interface SnapshotRow {
+  readonly state: string;
+  readonly version: number | bigint | string;
+}
+
+/** `SnapshotStore` over the sidecar table: latest state per stream, replacing on save. */
+export const snapshotStoreLayer = (
+  options?: SidecarOptions,
+): Layer.Layer<SnapshotStore, never, SqlClient.SqlClient> => {
+  const tables = sidecarTables(options);
+  return Layer.effect(
+    SnapshotStore,
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+      const service: SnapshotStoreService = {
+        load: (streamName) =>
+          Effect.map(
+            sql<SnapshotRow>`
+              SELECT state, version FROM ${sql(tables.snapshots)} WHERE stream_name = ${streamName}
+            `.pipe(Effect.orDie),
+            (rows): Option.Option<{ state: unknown; version: number }> => {
+              const row = rows[0];
+              return row === undefined
+                ? Option.none()
+                : Option.some({
+                    state: JSON.parse(row.state) as unknown,
+                    version: Number(row.version),
+                  });
+            },
+          ),
+        save: (streamName, snapshot) =>
+          Effect.asVoid(sql`
+            INSERT INTO ${sql(tables.snapshots)} (stream_name, state, version)
+            VALUES (${streamName}, ${JSON.stringify(snapshot.state ?? null)}, ${snapshot.version})
+            ON CONFLICT (stream_name) DO UPDATE SET state = excluded.state, version = excluded.version
+          `).pipe(Effect.orDie),
+      };
+      return SnapshotStore.of(service);
+    }),
+  );
+};
+
+/** `CheckpointStore` over the sidecar table: one bigint position per consumer name. */
+export const checkpointStoreLayer = (
+  options?: SidecarOptions,
+): Layer.Layer<CheckpointStore, never, SqlClient.SqlClient> => {
+  const tables = sidecarTables(options);
+  return Layer.effect(
+    CheckpointStore,
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+      const service: CheckpointStoreService = {
+        load: (name) =>
+          Effect.map(
+            sql<{ readonly position: number | bigint | string | null }>`
+              SELECT position FROM ${sql(tables.checkpoints)} WHERE name = ${name}
+            `.pipe(Effect.orDie),
+            (rows) => toBigInt(rows[0]?.position),
+          ),
+        save: (name, position) =>
+          Effect.asVoid(sql`
+            INSERT INTO ${sql(tables.checkpoints)} (name, position)
+            VALUES (${name}, ${position})
+            ON CONFLICT (name) DO UPDATE SET position = excluded.position
+          `).pipe(Effect.orDie),
+      };
+      return CheckpointStore.of(service);
+    }),
+  );
+};
+
+/** `Inbox` over the sidecar table: processed `(consumer, message)` pairs. */
+export const inboxLayer = (
+  options?: SidecarOptions,
+): Layer.Layer<Inbox, never, SqlClient.SqlClient> => {
+  const tables = sidecarTables(options);
+  return Layer.effect(
+    Inbox,
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+      const service: InboxService = {
+        seen: (consumerId, messageId) =>
+          Effect.map(
+            sql<{ readonly one: number }>`
+              SELECT 1 AS one FROM ${sql(tables.inbox)}
+              WHERE consumer_id = ${consumerId} AND message_id = ${messageId}
+            `.pipe(Effect.orDie),
+            (rows) => rows.length > 0,
+          ),
+        markProcessed: (consumerId, messageId) =>
+          Effect.asVoid(sql`
+            INSERT INTO ${sql(tables.inbox)} (consumer_id, message_id)
+            VALUES (${consumerId}, ${messageId})
+            ON CONFLICT DO NOTHING
+          `).pipe(Effect.orDie),
+      };
+      return Inbox.of(service);
+    }),
+  );
+};

package/src/envelope.ts

@@ -0,0 +1,86 @@
+import type { StoredEventMetadata } from "@structure-ai/eventsourcing";
+import { NisshiProtocolError } from "./protocol/errors.js";
+
+/**
+ * The JSON envelope persisted as the record value; the stream name is the
+ * record key. `version` travels inside the envelope because offsets are
+ * global per topic while versions number one stream's events.
+ */
+export interface WireEvent {
+  readonly type: string;
+  readonly schemaVersion: number;
+  readonly version: number;
+  readonly payload: unknown;
+  readonly metadata: StoredEventMetadata;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** Serializes the envelope; `undefined` payload collapses to `null`. */
+export const encodeWireEvent = (event: WireEvent): Uint8Array =>
+  encoder.encode(JSON.stringify({ ...event, payload: event.payload ?? null }));
+
+/** Parses a record value into an envelope, failing on malformed JSON. */
+export const decodeWireEvent = (value: Uint8Array, streamName: string): WireEvent => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoder.decode(value));
+  } catch (cause) {
+    throw new NisshiProtocolError({
+      reason: `malformed event envelope for ${streamName}: ${String(cause)}`,
+    });
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new NisshiProtocolError({ reason: `event envelope for ${streamName} is not an object` });
+  }
+  const record = parsed as Record<string, unknown>;
+  const { type, schemaVersion, version, payload, metadata } = record;
+  if (
+    typeof type !== "string" ||
+    typeof schemaVersion !== "number" ||
+    typeof version !== "number"
+  ) {
+    throw new NisshiProtocolError({
+      reason: `event envelope for ${streamName} misses typed fields`,
+    });
+  }
+  if (typeof metadata !== "object" || metadata === null) {
+    throw new NisshiProtocolError({
+      reason: `event envelope for ${streamName} has no metadata object`,
+    });
+  }
+  return {
+    type,
+    schemaVersion,
+    version,
+    payload: payload ?? null,
+    metadata: metadata as StoredEventMetadata,
+  };
+};
+
+/**
+ * Minimal client-side envelope validation (defense in depth before produce).
+ * Broker-side validation is stronger and optional — see `writeSchemaFiles`.
+ */
+export const validateWireEvent = (event: WireEvent, streamName: string): void => {
+  if (event.type.length === 0) {
+    throw new NisshiProtocolError({ reason: `event for ${streamName} has an empty type` });
+  }
+  if (!Number.isSafeInteger(event.schemaVersion) || event.schemaVersion < 1) {
+    throw new NisshiProtocolError({
+      reason: `event ${event.type} for ${streamName} has schemaVersion ${event.schemaVersion}`,
+    });
+  }
+  if (!Number.isSafeInteger(event.version) || event.version < 1) {
+    throw new NisshiProtocolError({
+      reason: `event ${event.type} for ${streamName} has version ${event.version}`,
+    });
+  }
+  const occurredAt = (event.metadata as Record<string, unknown>).occurredAt;
+  if (typeof occurredAt !== "string" || occurredAt.length === 0) {
+    throw new NisshiProtocolError({
+      reason: `event ${event.type} for ${streamName} misses metadata.occurredAt`,
+    });
+  }
+};