@effected/jsonl 0.1.0

package/index.d.ts

@@ -0,0 +1,1032 @@
+import { Context, DateTime, Duration, Effect, FileSystem, Layer, Option, PlatformError, PubSub, Result, Schema, Stream, SubscriptionRef, Take } from "effect";
+//#region src/LineSlice.d.ts
+declare const LineSlice_base: Schema.Class<LineSlice, Schema.Struct<{
+  /** UTF-8 byte offset of this line's first content byte. */
+  readonly offset: Schema.Number;
+  /**
+   * UTF-8 byte offset just past this line's terminator — the offset at which
+   * the next line begins, and the resume cursor for an incremental read.
+   *
+   * Equal to `offset + length` when the line is unterminated.
+   */
+  readonly end: Schema.Number;
+  /** UTF-8 byte length of `LineSlice.text`, excluding any terminator. */
+  readonly length: Schema.Number;
+  /** The line's content, with its terminator and any paired `\r` removed. */
+  readonly text: Schema.String;
+  /**
+   * Whether a `\n` terminated this line in the source.
+   *
+   * `false` can only occur on the final line, and means the line **may be a
+   * torn tail** — a writer caught mid-append. A reader walks back over it and
+   * leaves its bytes unconsumed so the next read sees the completed line.
+   */
+  readonly terminated: Schema.Boolean;
+}>, {}>;
+/**
+ * A single candidate line: its text, and where it lives in the source **in
+ * bytes**.
+ *
+ * Every offset on this class is a UTF-8 byte offset, never a UTF-16 code-unit
+ * index, because these values are cursors into a file: they are handed to
+ * `FileSystem.stream`'s `offset` option and persisted across process restarts.
+ * A `String.length`-derived offset is correct only for ASCII journals and is
+ * the single most likely bug in this module.
+ *
+ * The terminator is **not** part of the content: `text` and `length` exclude
+ * the trailing `\n`, and exclude the `\r` of a `\r\n` pair. `end` includes it,
+ * which is why `end - offset` is not always `length`.
+ *
+ * @example
+ * ```ts
+ * import { Line } from "@effected/jsonl";
+ *
+ * const [first] = Line.split('{"a":1}\r\n{"b":2}\n');
+ * first?.text;       // '{"a":1}'
+ * first?.offset;     // 0
+ * first?.length;     // 7  — content bytes, no terminator
+ * first?.end;        // 9  — past the CR and the LF
+ * first?.terminated; // true
+ * ```
+ *
+ * @public
+ */
+declare class LineSlice extends LineSlice_base {}
+//#endregion
+//#region src/JsonlError.d.ts
+declare const MalformedLine_base: Schema.Class<MalformedLine, Schema.TaggedStruct<"MalformedLine", {
+  /** The offending line, with its byte offsets into the source. */
+  readonly line: typeof LineSlice;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A journal line that is not valid JSON.
+ *
+ * **This is the expected steady state at the tail of a live journal**, not
+ * necessarily corruption: a writer caught mid-`write` leaves a partial final
+ * line, and `LineSlice.terminated` is what distinguishes the two cases. An
+ * unterminated malformed line is a torn tail that the next append completes; a
+ * *terminated* malformed line is a hole in the history that will never heal.
+ *
+ * Malformed input always fails through this typed channel — never as a defect,
+ * and never by being silently dropped from a read.
+ *
+ * @example
+ * ```ts
+ * import { Line } from "@effected/jsonl";
+ * import { Result } from "effect";
+ *
+ * const [line] = Line.split('{"a":');
+ * const parsed = Line.parseResult(line!);
+ * if (Result.isFailure(parsed)) {
+ *   parsed.failure.line.terminated; // false — a torn tail, not a hole
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class MalformedLine extends MalformedLine_base {
+  get message(): string;
+}
+declare const UnknownEvent_base: Schema.Class<UnknownEvent, Schema.TaggedStruct<"UnknownEvent", {
+  /** The offending line, with its byte offsets into the source. */
+  readonly line: typeof LineSlice;
+  /** The unrecognized tag as it appeared on the envelope. */
+  readonly event: Schema.String;
+  /** The tags this journal's registry does define. */
+  readonly known: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A line whose `event` tag is not in the registry.
+ *
+ * Typed rather than a defect on purpose: a journal written by an older or newer
+ * version of the same application is hostile input in the technical sense, and
+ * a reader that crashed on an unrecognized tag would be unable to skip forward
+ * past one. The known tags travel with the error so a caller can report the
+ * mismatch without reaching back for the registry.
+ *
+ * @public
+ */
+declare class UnknownEvent extends UnknownEvent_base {
+  get message(): string;
+}
+declare const InvalidData_base: Schema.Class<InvalidData, Schema.TaggedStruct<"InvalidData", {
+  /** The offending line, with its byte offsets into the source. */
+  readonly line: typeof LineSlice;
+  /**
+   * The event tag whose payload schema rejected the data, or `none` when it
+   * was the envelope frame itself that failed.
+   */
+  readonly event: Schema.Option<Schema.String>;
+  /** The schema failure, carried structurally — `issue` is the full tree. */
+  readonly error: Schema.declare<Schema.SchemaError, Schema.SchemaError>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A line whose envelope or payload failed schema validation.
+ *
+ * Covers both stages of the two-stage decode, distinguished by `event`: the
+ * frame itself (`Option.none()` — the line is JSON but not an envelope) and a
+ * registered payload (`Option.some(tag)` — the envelope is well-formed but its
+ * `data` does not match the schema registered for that tag).
+ *
+ * The `SchemaError` is carried **whole**, so `error.issue` is the full issue
+ * tree with its paths and expected types intact. Nothing here is stringified;
+ * `message` renders lazily and only when something asks for it.
+ *
+ * @public
+ */
+declare class InvalidData extends InvalidData_base {
+  get message(): string;
+}
+declare const TerminalViolation_base: Schema.Class<TerminalViolation, Schema.TaggedStruct<"TerminalViolation", {
+  /** The tag of the event whose append was refused. */
+  readonly event: Schema.String;
+  /** The terminal event currently at the tail of the journal. */
+  readonly terminal: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An append attempted after a terminal event, by an event not marked `reopen`.
+ *
+ * A journal whose tail is terminal is quiescent: it is finished, and appending
+ * to it would silently resurrect a closed loop. Reopening is legal but must be
+ * declared, which is what `reopen` marks.
+ *
+ * @public
+ */
+declare class TerminalViolation extends TerminalViolation_base {
+  get message(): string;
+}
+declare const JournalNotFound_base: Schema.Class<JournalNotFound, Schema.TaggedStruct<"JournalNotFound", {
+  /** The path that does not exist. */
+  readonly path: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An operation against a journal file that does not exist.
+ *
+ * A missing journal is a **legal state** — building the layer over a path that
+ * does not exist yet succeeds, and the watcher activates once the file appears.
+ * What is not legal is materializing it implicitly: `append`, `query` and
+ * `latest` fail with this rather than creating the file, so a typo in a path
+ * cannot quietly produce a second, empty journal that looks like a working
+ * system with no history. Creation is always explicit, via `create`.
+ *
+ * @public
+ */
+declare class JournalNotFound extends JournalNotFound_base {
+  get message(): string;
+}
+declare const UnserializableData_base: Schema.Class<UnserializableData, Schema.TaggedStruct<"UnserializableData", {
+  /** The event tag whose payload could not be serialized. */
+  readonly event: Schema.String;
+  /** The value `JSON.stringify` threw, carried structurally. */
+  readonly cause: Schema.Unknown;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A payload that validated against its schema but cannot be serialized to JSON.
+ *
+ * The two reachable causes are a `bigint` anywhere in the encoded value and a
+ * reference cycle; `JSON.stringify` throws a `TypeError` for both. A payload
+ * schema is free to permit either — `Schema.Unknown` permits everything — so
+ * schema validity does not imply serializability and the encode path has to
+ * treat them as separate questions.
+ *
+ * This is its own tag rather than a flavour of {@link InvalidData} because the
+ * recovery differs: `InvalidData` means the value is wrong and the caller
+ * should fix the value, while this means the value is fine but unrepresentable
+ * in this format and the caller must change the *shape* they are journaling.
+ *
+ * The thrown value is carried as-is under `cause` — never stringified, and
+ * never re-thrown. A raw `TypeError` escaping the encode path would be
+ * especially bad here: `Effect.fromResult` evaluates its argument eagerly, so
+ * an unguarded throw happens at **construction** of the `Effect`, before any
+ * fiber exists, where not even `Effect.runSyncExit` can catch it.
+ *
+ * @public
+ */
+declare class UnserializableData extends UnserializableData_base {
+  get message(): string;
+}
+declare const JournalClosed_base: Schema.Class<JournalClosed, Schema.TaggedStruct<"JournalClosed", {
+  /** The tag of the event whose append was refused. */
+  readonly event: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An append refused because the journal's scope has closed.
+ *
+ * Its own tag rather than a flavour of {@link TerminalViolation}, because the
+ * recoveries have nothing in common: a terminal journal is a *state* the
+ * consumer can reason about and reopen from with a `reopen` event, while a
+ * closed one is a *lifecycle* fact — this service is gone, and the only moves
+ * are to build a new layer or stop.
+ *
+ * Refusal is deliberately a typed failure rather than a wait. A `Latch` would
+ * suspend the late append with no failure channel, turning "the journal is
+ * closing" into a hang; failing fast is what lets a caller react.
+ *
+ * @public
+ */
+declare class JournalClosed extends JournalClosed_base {
+  get message(): string;
+}
+declare const JournalResync_base: Schema.Class<JournalResync, Schema.TaggedStruct<"JournalResync", {
+  /** The journal path whose file changed identity or shrank. */
+  readonly path: Schema.String;
+  /** Which contract breach was detected. Diagnostic; the recovery is the same. */
+  readonly reason: Schema.Literals<readonly ["truncated", "replaced"]>;
+  /** The logical offset the reader had consumed to. */
+  readonly expected: Schema.Number;
+  /** The file's logical size when the breach was noticed. */
+  readonly actual: Schema.Number;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The journal file was truncated or replaced beneath a reader.
+ *
+ * The cooperative-writer contract is append-only: a journal only ever grows,
+ * and every cursor this package hands out depends on that. When the file shrinks
+ * below a tracked offset, or the path comes to name a different file entirely,
+ * the contract has been broken by something outside the package and every
+ * offset-derived belief is now meaningless.
+ *
+ * Surfaced rather than repaired, deliberately. Silently re-reading from zero
+ * would paper over a real operational fault — a rotating log shipper, a
+ * `>` where `>>` was meant — and leave projections quietly inconsistent with
+ * the file. The recovery is the consumer's: discard cursor-derived state,
+ * re-read, and tell somebody.
+ *
+ * One tag rather than two, though `reason` distinguishes the causes: truncation
+ * and replacement have the **same** recovery, and a tag per cause would split
+ * one recovery across two tags.
+ *
+ * @remarks
+ * Detection is as complete as the platform allows and no more. Truncation is
+ * caught by size; replacement is caught by inode identity, which
+ * `FileSystem.File.Info` exposes as an **`Option`** — on a platform that does
+ * not report it, a replacement at equal or greater size is undetectable and
+ * only truncation is caught.
+ *
+ * @public
+ */
+declare class JournalResync extends JournalResync_base {
+  get message(): string;
+}
+/**
+ * Every error this package raises from the pure core and the journal service.
+ *
+ * Core's `PlatformError` is deliberately **not** a member: IO failures pass
+ * through untranslated rather than being wrapped in a taxonomy that would add
+ * no recovery information.
+ *
+ * @public
+ */
+type JsonlError = MalformedLine | UnknownEvent | InvalidData | UnserializableData | TerminalViolation | JournalClosed | JournalNotFound | JournalResync;
+//#endregion
+//#region src/JsonlEvent.d.ts
+/**
+ * The bound every registered payload schema must satisfy: a codec requiring
+ * **no services** in either direction.
+ *
+ * This is a contract, not an implementation detail. The pure core decodes with
+ * `Schema.decodeUnknownResult` and encodes with `Schema.encodeUnknownResult`,
+ * both of which demand `never` in both service slots — so a payload schema that
+ * needed a service would make the synchronous, runtime-free read path
+ * impossible. Bounding it here fails such a schema at **registration**, where
+ * the mistake is, instead of at some consumer's call site later.
+ *
+ * `Schema.Top` is deliberately not the bound: its service parameters are
+ * `unknown`, so it does not satisfy the sync codecs and the constraint would
+ * silently fail to bind. The value slots are `unknown` rather than `any`
+ * because `Codec`'s type and encoded parameters are covariant, so `unknown`
+ * admits every concrete payload schema while still rejecting a
+ * service-requiring one — the precision costs nothing here.
+ *
+ * @public
+ */
+type DataSchema = Schema.Codec<unknown, unknown, never, never>;
+/**
+ * Unique type identifier marking a JSONL event definition.
+ *
+ * @public
+ */
+type JsonlEventTypeId = "~effected/jsonl/JsonlEvent";
+/**
+ * Runtime type identifier marking a JSONL event definition.
+ *
+ * @public
+ */
+declare const JsonlEventTypeId: JsonlEventTypeId;
+/**
+ * One event definition: a tag, the schema its `data` must satisfy, and the two
+ * lifecycle markings.
+ *
+ * The type parameters are what make a registry more than a runtime list — the
+ * literal `Tag`, the payload schema and the `terminal`/`reopen` flags all
+ * survive into the derived envelope union, so `append` narrows on the tag and a
+ * projection over a slice is exhaustively checkable.
+ *
+ * @public
+ */
+interface JsonlEvent<out Tag extends string, in out Data extends DataSchema = Schema.Codec<void, void, never, never>, out Terminal extends boolean = false, out Reopen extends boolean = false> {
+  readonly [JsonlEventTypeId]: JsonlEventTypeId;
+  /** The string tag: the envelope discriminant and the primary filter key. */
+  readonly tag: Tag;
+  /** The schema the envelope's `data` is validated against. */
+  readonly data: Data;
+  /**
+   * Whether this event makes the journal quiescent.
+   *
+   * After a terminal event is the tail, appending fails with
+   * `TerminalViolation` unless the appended event is marked `reopen`.
+   */
+  readonly terminal: Terminal;
+  /** Whether this event may follow a terminal one, reopening the journal. */
+  readonly reopen: Reopen;
+}
+/**
+ * Helper types for working with event definitions and registries.
+ *
+ * @public
+ */
+declare namespace JsonlEvent {
+  /**
+   * A type-erased event definition.
+   *
+   * Note `data` is bounded by {@link DataSchema} rather than widened to
+   * `Schema.Top`: erasing to `Top` would lose the no-services guarantee that
+   * the sync codecs depend on.
+   *
+   * @public
+   */
+  interface Any {
+    readonly [JsonlEventTypeId]: JsonlEventTypeId;
+    readonly tag: string;
+    readonly data: DataSchema;
+    readonly terminal: boolean;
+    readonly reopen: boolean;
+  }
+  /** A registry: the set of events one journal may carry. */
+  type Registry = ReadonlyArray<Any>;
+  /** The union of every event definition in a registry. */
+  type Events<R extends Registry> = R[number];
+  /** The union of every tag in a registry — the envelope discriminant. */
+  type Tag<R extends Registry> = Events<R>["tag"];
+  /** The event definition in a registry carrying a given tag. */
+  type WithTag<R extends Registry, T extends string> = Extract<Events<R>, {
+    readonly tag: T;
+  }>;
+  /** The decoded payload type registered for a given tag. */
+  type Data<R extends Registry, T extends string> = WithTag<R, T>["data"]["Type"];
+  /** The tags marked `terminal` in a registry. */
+  type TerminalTags<R extends Registry> = Extract<Events<R>, {
+    readonly terminal: true;
+  }>["tag"];
+  /** The tags marked `reopen` in a registry. */
+  type ReopenTags<R extends Registry> = Extract<Events<R>, {
+    readonly reopen: true;
+  }>["tag"];
+}
+/**
+ * Defines an event.
+ *
+ * The `const` type parameters are load-bearing: they keep `"unlinked"` a
+ * literal rather than widening it to `string`, and keep `terminal: true` a
+ * literal `true`, so both survive into the derived envelope union where the
+ * narrowing and the terminal/reopen state machine depend on them.
+ *
+ * `data` is required rather than defaulted. A payload-less event says so
+ * explicitly with `Schema.Void`, because a silent default would make a typo in
+ * the options object look like a deliberate void payload.
+ *
+ * @example
+ * ```ts
+ * import { JsonlEvent } from "@effected/jsonl";
+ * import { Schema } from "effect";
+ *
+ * const MailReceived = JsonlEvent.make("mail-received", {
+ *   data: Schema.Struct({ round: Schema.Number }),
+ * });
+ * const Unlinked = JsonlEvent.make("unlinked", { data: Schema.Void, terminal: true });
+ * const Relinked = JsonlEvent.make("relinked", { data: Schema.Void, reopen: true });
+ *
+ * const registry = [MailReceived, Unlinked, Relinked] as const;
+ * ```
+ *
+ * @public
+ */
+declare const JsonlEvent: {
+  readonly make: <const Tag extends string, Data extends DataSchema, const Terminal extends boolean = false, const Reopen extends boolean = false>(tag: Tag, options: {
+    readonly data: Data;
+    readonly terminal?: Terminal | undefined;
+    readonly reopen?: Reopen | undefined;
+  }) => JsonlEvent<Tag, Data, Terminal, Reopen>;
+};
+//#endregion
+//#region src/Envelope.d.ts
+/**
+ * Stage one of the read path: the envelope with its payload left undecoded.
+ *
+ * A `Schema.Struct` rather than a `Schema.Class` deliberately. This is the hot
+ * path — it runs for every line of every read, including the lines a `Slice` is
+ * about to discard — and it is a transient the caller never holds, so there is
+ * nothing to gain from wrapping each one in a class instance.
+ *
+ * `data` is `Schema.Unknown`, which passes the payload through without
+ * traversing it. That is what keeps frame decoding independent of payload
+ * depth, and what lets filtering happen before any payload schema runs.
+ *
+ * @public
+ */
+declare const EnvelopeFrame: Schema.Struct<{
+  readonly at: Schema.DateTimeUtcFromString;
+  readonly event: Schema.String;
+  readonly scope: Schema.optionalKey<Schema.String>;
+  readonly data: Schema.Unknown;
+}>;
+/**
+ * A decoded envelope: the frame, its validated payload, and where it sits in
+ * the source.
+ *
+ * This interface is what the "derived discriminated union" derives *into*.
+ * A registry of event definitions produces a union of these discriminated on
+ * `event`, so narrowing on the tag recovers the payload type registered for it.
+ *
+ * @public
+ */
+interface Envelope<out Tag extends string, out Data> {
+  /** UTC timestamp, assigned by the service at append time from the `Clock`. */
+  readonly at: DateTime.Utc;
+  /** The event tag: the union discriminant and the primary filter key. */
+  readonly event: Tag;
+  /** The partition key, with no further semantics. */
+  readonly scope?: string | undefined;
+  /** The payload, validated against the schema registered for `event`. */
+  readonly data: Data;
+  /** Where this envelope's line sits in the source, in bytes. */
+  readonly line: LineSlice;
+}
+/**
+ * The envelope type derived from one event definition. Distributes over a union
+ * of definitions, which is what turns a registry into a discriminated union.
+ *
+ * @public
+ */
+type EnvelopeOf<E extends JsonlEvent.Any> = E extends JsonlEvent<infer Tag, infer Data extends DataSchema, boolean, boolean> ? Envelope<Tag, Data["Type"]> : never;
+/**
+ * The discriminated union of every envelope a registry can carry.
+ *
+ * @public
+ */
+type EnvelopeUnion<R extends JsonlEvent.Registry> = EnvelopeOf<JsonlEvent.Events<R>>;
+/**
+ * The envelope variant carrying a given tag — the type a slice narrows to.
+ *
+ * @public
+ */
+type EnvelopeWithTag<R extends JsonlEvent.Registry, T extends string> = Extract<EnvelopeUnion<R>, {
+  readonly event: T;
+}>;
+/**
+ * Decoding, encoding and the envelope-level walk-back.
+ *
+ * Every operation here is synchronous and `Result`-based; the `Effect` forms are
+ * defined **in terms of** the sync ones via `Effect.fromResult`, so the two can
+ * never drift into two implementations of the same rule.
+ *
+ * @public
+ */
+declare const Envelope: {
+  /**
+   * Stage one only: decode the frame, leaving `data` untouched.
+   *
+   * This is what filtering reads. It never runs a payload schema, so its cost
+   * is independent of payload size and depth, and a line destined to be
+   * filtered out never pays for its payload at all.
+   *
+   * @param line - A slice from `Line.split`.
+   */
+  readonly frameResult: (line: LineSlice) => Result.Result<typeof EnvelopeFrame.Type & {
+    readonly line: LineSlice;
+  }, MalformedLine | InvalidData>;
+  /**
+   * Decode one line into a fully validated envelope, running both stages.
+   *
+   * @param events - The registry defining which tags are legal and what their
+   *   payloads must look like.
+   * @param line - A slice from `Line.split`.
+   * @returns The envelope, or the typed reason it is not one: not JSON
+   *   (`MalformedLine`), not an envelope or a bad payload (`InvalidData`), or
+   *   a tag this registry does not define (`UnknownEvent`).
+   */
+  readonly decodeResult: <const R extends JsonlEvent.Registry>(events: R, line: LineSlice) => Result.Result<EnvelopeUnion<R>, MalformedLine | InvalidData | UnknownEvent>;
+  /**
+   * Decode a line only if its **frame** is selected, running the payload schema
+   * for selected lines only.
+   *
+   * This is the structural form of the filter-before-decode guarantee: when
+   * `select` rejects the frame, the registered `data` schema is never reached,
+   * so a consumer reading a journal it shares with a noisy neighbour pays
+   * nothing for the neighbour's payloads. Writing the filter *after* a full
+   * decode would produce identical output while charging for every line — which
+   * is why this exists as its own operation rather than as advice.
+   *
+   * @param events - The registry to validate against.
+   * @param line - A slice from `Line.split`.
+   * @param select - Predicate over the decoded frame — `at`, `event`, `scope`
+   *   and the raw undecoded `data`.
+   * @returns `Option.none()` when the frame is not selected; otherwise the
+   *   fully decoded envelope, or the typed reason it is not one.
+   */
+  readonly decodeSelectedResult: <const R extends JsonlEvent.Registry>(events: R, line: LineSlice, select: (frame: typeof EnvelopeFrame.Type) => boolean) => Option.Option<Result.Result<EnvelopeUnion<R>, MalformedLine | InvalidData | UnknownEvent>>;
+  /**
+   * Decode every non-blank line, reporting failures rather than dropping them.
+   *
+   * Same contract as `Line.parseAll` one layer down: a line that is not a
+   * legal envelope is a `Result` in the array, never a gap in it.
+   */
+  readonly decodeAllResult: <const R extends JsonlEvent.Registry>(events: R, text: string) => ReadonlyArray<Result.Result<EnvelopeUnion<R>, MalformedLine | InvalidData | UnknownEvent>>;
+  /**
+   * Walk back from the end to the last valid **envelope**.
+   *
+   * This is the binding definition of "the last valid line", and the envelope
+   * layer is where it has to live. `Line.lastValid` stops at JSON validity,
+   * which is not enough: a torn scalar tail (`42` cut mid-write leaves `4`)
+   * parses cleanly as a different value, so a JSON-level walk-back would hand
+   * back corruption as the current state. An envelope is always an object,
+   * every strict prefix of an object text is invalid JSON, and a bare `4` is
+   * not an envelope — so this walk-back detects the torn tail that the one
+   * below it structurally cannot.
+   *
+   * Decoding stops at the first success, so the cost tracks the damage at the
+   * tail rather than the age of the file.
+   *
+   * @param events - The registry to validate against.
+   * @param text - JSONL source text.
+   * @returns The last valid envelope, or `Option.none()` if there is none.
+   */
+  readonly lastValidResult: <const R extends JsonlEvent.Registry>(events: R, text: string) => Option.Option<EnvelopeUnion<R>>;
+  /**
+   * Encode one envelope into a complete JSONL line, terminator included.
+   *
+   * The trailing `\n` is part of the returned string on purpose: the
+   * cooperative-writer contract is one `writeAll` of a *complete line*, and an
+   * API that returned the text without its terminator would invite a caller to
+   * write the two separately — which is exactly the interleaving the contract
+   * exists to prevent.
+   *
+   * No `Schema.Union` is involved. The tag is known, so the payload schema is
+   * a direct registry lookup; a union would buy nothing and decode eagerly.
+   *
+   * @param events - The registry to validate against.
+   * @param envelope - The event tag, its payload, the service-assigned
+   *   timestamp, and an optional scope.
+   */
+  readonly encodeResult: <const R extends JsonlEvent.Registry, const T extends JsonlEvent.Tag<R>>(events: R, envelope: {
+    readonly event: T;
+    readonly data: JsonlEvent.Data<R, T>;
+    readonly at: DateTime.Utc;
+    readonly scope?: string | undefined;
+  }) => Result.Result<string, UnknownEvent | InvalidData | UnserializableData>;
+  /**
+   * {@link (Envelope:variable).decodeResult} in the `Effect` channel.
+   *
+   * Prefer the sync form in a hook or any caller that has no runtime; this
+   * exists for programs that already are one.
+   */
+  readonly decode: <const R extends JsonlEvent.Registry>(events: R, line: LineSlice) => Effect.Effect<EnvelopeUnion<R>, MalformedLine | InvalidData | UnknownEvent>;
+  /**
+   * {@link (Envelope:variable).encodeResult} in the `Effect` channel.
+   */
+  readonly encode: <const R extends JsonlEvent.Registry, const T extends JsonlEvent.Tag<R>>(events: R, envelope: {
+    readonly event: T;
+    readonly data: JsonlEvent.Data<R, T>;
+    readonly at: DateTime.Utc;
+    readonly scope?: string | undefined;
+  }) => Effect.Effect<string, UnknownEvent | InvalidData | UnserializableData>;
+};
+//#endregion
+//#region src/Slice.d.ts
+/**
+ * A filter over envelope fields.
+ *
+ * Every field is optional and they combine with AND. An omitted field does not
+ * filter; an empty `events: []` or `scopes: []` matches nothing, which is the
+ * honest reading of "restrict to this empty set" and is tested.
+ *
+ * @public
+ */
+interface Slice<R extends JsonlEvent.Registry, T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>> {
+  /**
+   * Restrict to these event tags.
+   *
+   * Passing a literal array narrows the element type of the surface's stream to
+   * exactly those variants, so a projection over a slice is exhaustively
+   * checkable.
+   */
+  readonly events?: ReadonlyArray<T> | undefined;
+  /** Restrict to these partition keys. An envelope with no `scope` matches none of them. */
+  readonly scopes?: ReadonlyArray<string> | undefined;
+  /** Lower bound on `at`, **inclusive**. */
+  readonly from?: DateTime.Utc | undefined;
+  /**
+   * Upper bound on `at`, **exclusive**.
+   *
+   * Half-open so adjacent windows tile without double-delivering an envelope on
+   * the seam — which matters because `at` collisions are ordinary at
+   * millisecond resolution and universal under `TestClock`.
+   */
+  readonly to?: DateTime.Utc | undefined;
+}
+/**
+ * A {@link Slice} plus a resume point.
+ *
+ * @public
+ */
+interface CursoredSlice<R extends JsonlEvent.Registry, T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>> extends Slice<R, T> {
+  /**
+   * Resume from this logical byte offset, **inclusive**.
+   *
+   * Offsets are post-BOM, matching every offset this package emits. Persist a
+   * processed envelope's `line.end` and pass it back to replay exactly the
+   * remainder: `end` is the start of the next line, so nothing is redelivered
+   * and nothing is skipped.
+   */
+  readonly cursor?: number | undefined;
+}
+//#endregion
+//#region src/Journal.d.ts
+/**
+ * The failure channel of a write operation.
+ *
+ * `PlatformError` rides through untranslated per the taxonomy's rule. **Any
+ * `PlatformError` out of an append must be treated as a possibly-torn tail**:
+ * `writeAll` reports no byte count, so a failure cannot be read as "nothing was
+ * written". The next reader walks back over whatever fragment survived.
+ *
+ * @public
+ */
+type JournalWriteError = JournalClosed | JournalNotFound | TerminalViolation | UnknownEvent | MalformedLine | InvalidData | UnserializableData | PlatformError.PlatformError;
+/**
+ * The failure channel of a read operation.
+ *
+ * @public
+ */
+type JournalReadError = JournalNotFound | PlatformError.PlatformError;
+/**
+ * Options for one append.
+ *
+ * @public
+ */
+interface AppendOptions {
+  /** The partition key to stamp on the envelope. */
+  readonly scope?: string | undefined;
+}
+/**
+ * The shape of a `Journal`, typed by its registry.
+ *
+ * @public
+ */
+interface JournalShape<R extends JsonlEvent.Registry> {
+  /**
+   * Validate, encode and append one envelope.
+   *
+   * `at` is stamped here from the Effect `Clock` — never by the caller — so
+   * ordering does not depend on two writers agreeing about the time, and
+   * `TestClock` controls it exactly in tests.
+   */
+  readonly append: <T extends JsonlEvent.Tag<R>>(event: T, data: JsonlEvent.Data<R, T>, options?: AppendOptions | undefined) => Effect.Effect<EnvelopeWithTag<R, T>, JournalWriteError>;
+  /**
+   * Inherit-and-patch: read the last valid envelope, shallow-merge `patch`
+   * over its `data`, validate the result and append it.
+   *
+   * This is the snapshot-journal primitive — each line is a complete state and
+   * most transitions change one field. The merge is **shallow** by decision: a
+   * nested object in the patch replaces the one beneath it.
+   */
+  readonly appendPatch: <T extends JsonlEvent.Tag<R>>(event: T, patch: Partial<JsonlEvent.Data<R, T>>, options?: AppendOptions | undefined) => Effect.Effect<EnvelopeWithTag<R, T>, JournalWriteError>;
+  /**
+   * The current last valid **envelope**, as an observable `Option`.
+   *
+   * "Last valid" always means the last valid envelope, never merely the last
+   * valid JSON — a torn scalar tail parses as a different value and only the
+   * envelope contract detects it.
+   */
+  readonly latest: SubscriptionRef.SubscriptionRef<Option.Option<EnvelopeUnion<R>>>;
+  /**
+   * Whether the journal is quiescent — its tail is an event marked `terminal`.
+   *
+   * Derived from {@link JournalShape.latest} rather than tracked separately, so
+   * the two cannot disagree.
+   */
+  readonly quiescent: Effect.Effect<boolean>;
+  /**
+   * Historical read: a finite `Stream` of the envelopes matching `slice`.
+   *
+   * Every element carries its logical byte offsets on `line`, so iteration is
+   * resumable across process restarts by persisting `line.end` and passing it
+   * back as `cursor`.
+   *
+   * Filtering happens on the envelope **frame**, strictly before the payload
+   * schema runs, so a non-matching line's `data` is never decoded.
+   *
+   * @remarks
+   * **Cost, stated rather than implied.** As built, the requested region —
+   * `cursor` to the end of the file — is read in ONE allocation bounded by the
+   * file's size, and the matching envelopes are buffered before the first is
+   * emitted. An unsliced `query()` over a large journal therefore does hold
+   * that journal in memory; a `cursor` is what bounds the read, which is
+   * precisely what a resuming consumer already persists. The window-bounded
+   * reads are `latest` and the `lastValid`-backed paths. Emitting per window,
+   * so an unsliced query costs a window rather than a file, is tracked as
+   * spencerbeggs/effected#233.
+   */
+  readonly query: <T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>>(slice?: CursoredSlice<R, T> | undefined) => Stream.Stream<EnvelopeWithTag<R, T>, JournalReadError | JsonlError>;
+  /**
+   * Live read: a `Stream` of matching envelopes as they are appended.
+   *
+   * With a `cursor`, replay-from-cursor and the live tail are **one seam**: the
+   * replayed history and the live tail are the same stream, filtered the same
+   * way, so a consumer cannot observe a gap or a duplicate at the join.
+   *
+   * The stream **ends** — it never hangs — when the journal becomes quiescent
+   * (a `terminal` event reaches the tail) or its scope closes. Subscribing to
+   * an already-quiescent journal ends immediately.
+   *
+   * @remarks
+   * Two properties are worth knowing before relying on them.
+   *
+   * The **delivered-before-end guarantee is scoped to consuming subscribers**:
+   * every append that completed is delivered before the stream ends, provided
+   * the subscriber keeps taking. One that stops taking cannot observe
+   * completion by definition, and shutdown will not wait on it past its bound.
+   *
+   * The **filter-before-decode guarantee is structural on the historical half
+   * only**. Replayed lines are filtered on the frame before their payload is
+   * decoded. Live envelopes arrive already decoded — the appender decoded its
+   * own payload in order to return it — so a filtered-out live envelope was
+   * decoded once, by the writer, not by each subscriber.
+   */
+  readonly changes: <T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>>(slice?: CursoredSlice<R, T> | undefined) => Stream.Stream<EnvelopeWithTag<R, T>, JournalReadError | JsonlError>;
+  /**
+   * A running fold over a slice, emitted as it advances.
+   *
+   * The fold only ever sees its own slice, so a per-scope state machine over a
+   * shared journal is exhaustively checkable against just that scope's events.
+   */
+  readonly projection: <S, T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>>(initial: S, fold: (state: S, envelope: EnvelopeWithTag<R, T>) => S, slice?: CursoredSlice<R, T> | undefined) => Stream.Stream<S, JournalReadError | JsonlError>;
+  /** Create the journal file if it does not exist. Always explicit. */
+  readonly create: Effect.Effect<void, PlatformError.PlatformError>;
+  /** Remove the journal file. Always explicit. */
+  readonly remove: Effect.Effect<void, PlatformError.PlatformError>;
+  /**
+   * The internal hub, exposed for the read surfaces built over it.
+   *
+   * Elements are `Take` chunks and end-of-stream is a published `Exit`, which
+   * is what lets quiescence and graceful shutdown arrive at a subscriber as a
+   * normal stream end. Never shut this down to signal completion —
+   * `PubSub.shutdown` *interrupts* subscribers, which is the tear the design
+   * forbids.
+   *
+   * @internal
+   */
+  readonly hub: PubSub.PubSub<Take.Take<EnvelopeUnion<R>, JsonlError>>;
+}
+/**
+ * Configuration for one journal layer.
+ *
+ * @public
+ */
+interface JournalConfig {
+  /** Path to the journal file. It need not exist yet. */
+  readonly path: string;
+  /**
+   * The directory to watch while the journal does not exist yet.
+   *
+   * Defaults to `path`'s parent, derived by taking everything before its last
+   * `/` or `\`. That derivation is the one piece of path arithmetic this
+   * package performs, and it is here so the common case needs no second field;
+   * name the directory explicitly when your path convention does not survive
+   * it — a drive-relative Windows path, or a path whose parent is not a plain
+   * prefix of it.
+   *
+   * It is used for exactly one thing: `FileSystem.watch` on a journal that has
+   * not been created yet. Once the journal exists the watch moves to the file
+   * itself and this value is not consulted again.
+   */
+  readonly directory?: string | undefined;
+  /**
+   * Capacity of the internal subscriber hub. Bounded with backpressure: the
+   * journal never drops an envelope for a slow subscriber, so slowness shows
+   * up at the producer where it is visible rather than as a silent gap in
+   * somebody's subscription.
+   */
+  readonly capacity?: number | undefined;
+  /**
+   * How long scope close waits for the terminal `Exit` to be accepted.
+   *
+   * Defaults to five seconds. Bounded rather than indefinite because a
+   * subscriber that never consumes cannot observe completion by definition,
+   * and must not be able to hold shutdown hostage.
+   */
+  readonly shutdownPublishTimeout?: Duration.Input | undefined;
+}
+/**
+ * A per-registry `Journal` service class.
+ *
+ * @public
+ */
+interface JournalClass<Self, Id extends string, R extends JsonlEvent.Registry> extends Context.ServiceClass<Self, Id, JournalShape<R>> {
+  /** The registry this journal was defined over. */
+  readonly events: R;
+  /**
+   * Build the layer for this journal.
+   *
+   * @remarks
+   * **Construction can fail with a `PlatformError`, and that is deliberate.** A
+   * journal file that does not exist yet is a legal state and constructs
+   * cleanly — but a file that exists and cannot be read (`EACCES`, a bad
+   * handle) is a real failure, and typing this channel `never` would have made
+   * it arrive as an untypeable defect that no caller could catch.
+   *
+   * **Bind the result to a const and provide that const.** Layers are memoized
+   * by reference, so calling this twice mints **two independent journals over
+   * one file** — two semaphores, two hubs, two `latest` refs — and their
+   * appends are not serialized against each other. That is the in-process form
+   * of exactly the interleaving the cooperative-writer rules exist to prevent,
+   * and it typechecks perfectly.
+   *
+   * ```ts
+   * // correct
+   * export const layer = MailJournal.layer({ path });
+   *
+   * // WRONG — a second, unserialized journal over the same file
+   * Effect.provide(program, MailJournal.layer({ path }));
+   * ```
+   */
+  readonly layer: (config: JournalConfig) => Layer.Layer<Self, PlatformError.PlatformError, FileSystem.FileSystem>;
+}
+/**
+ * Define a `Journal` service class over a registry.
+ *
+ * A `Context.Service` cannot itself be generic over the registry — the shape
+ * binds at declaration and a Key cannot be parameterized at retrieval — so each
+ * registry gets its own uniquely-keyed class, and several journals coexist in
+ * one layer graph with each one's operations typed by *its* registry. This
+ * mirrors `ConfigFile.Service<Self, A>()(id)`.
+ *
+ * @example
+ * ```ts
+ * import { Journal, JsonlEvent } from "@effected/jsonl";
+ * import { Schema } from "effect";
+ *
+ * const events = [JsonlEvent.make("started", { data: Schema.Void })] as const;
+ *
+ * class MailJournal extends Journal.Service<MailJournal>()("dogfood/MailJournal", { events }) {}
+ *
+ * export const layer = MailJournal.layer({ path: ".claude/dogfood/silk.jsonl" });
+ * ```
+ *
+ * @public
+ */
+declare const Journal: {
+  readonly Service: <Self>() => <const Id extends string, const R extends JsonlEvent.Registry>(id: Id, options: {
+    readonly events: R;
+  }) => JournalClass<Self, Id, R>;
+};
+//#endregion
+//#region src/Line.d.ts
+declare const ParsedLine_base: Schema.Class<ParsedLine, Schema.Struct<{
+  /** Where this line lives in the source. */
+  readonly line: typeof LineSlice;
+  /** The parsed JSON value — any JSON value, not necessarily an object. */
+  readonly value: Schema.Unknown;
+}>, {}>;
+/**
+ * A line that parsed as JSON, paired with the slice it came from.
+ *
+ * `value` is deliberately `unknown`: this layer knows JSON, not envelopes.
+ * Validating `event`, `at`, `scope` and the registered payload schema is the
+ * envelope layer's job, and keeping the split means a malformed *envelope* and
+ * a malformed *line* stay distinguishable failures.
+ *
+ * @public
+ */
+declare class ParsedLine extends ParsedLine_base {}
+/**
+ * Splitting, parsing and corrupt-tail walk-back over JSONL text.
+ *
+ * Every operation is total and synchronous: it returns a value for every
+ * input, including empty text, torn tails, and text that is not JSONL at all.
+ * Nothing here throws — a `JSON.parse` failure becomes a {@link MalformedLine}
+ * in the returned `Result`, because a journal is untrusted input and untrusted
+ * input fails typed.
+ *
+ * @public
+ */
+declare class Line {
+  /**
+   * The UTF-8 byte length of a string.
+   *
+   * Exposed because callers doing their own offset arithmetic must measure
+   * the same way this module does. `String.length` is a different number for
+   * any non-ASCII line.
+   *
+   * An unpaired surrogate counts as the 3 bytes of U+FFFD, matching what a
+   * UTF-8 write actually emits. The offsets therefore stay true to the file
+   * even though the character itself cannot survive the round trip — text
+   * read back from a UTF-8 journal never contains one.
+   *
+   * @example
+   * ```ts
+   * import { Line } from "@effected/jsonl";
+   *
+   * Line.byteLength("\u{1F600}"); // 4
+   * "\u{1F600}".length;           // 2 — the trap
+   * ```
+   */
+  static byteLength(text: string): number;
+  /**
+   * Split text into candidate lines with byte-exact offsets.
+   *
+   * Lines are separated by `\n`; a `\r` immediately preceding it is treated as
+   * part of the terminator, so CRLF journals split identically to LF ones. A
+   * bare `\r` is ordinary content, because only `\n` terminates.
+   *
+   * A trailing terminator does **not** produce a phantom empty final line, so
+   * a well-formed journal yields exactly as many slices as it has entries.
+   * Interior blank lines *are* returned — they are real bytes at real offsets,
+   * and hiding them would make the offsets lie.
+   *
+   * Only the final slice can have `terminated: false`.
+   *
+   * @param text - JSONL source text.
+   * @returns One {@link LineSlice} per candidate line, in source order.
+   */
+  static split(text: string): ReadonlyArray<LineSlice>;
+  /**
+   * The byte offset up to which this text has been fully consumed.
+   *
+   * This is the offset past the last **terminated** line. An unterminated
+   * final line is left unconsumed on purpose: it may be a writer caught
+   * mid-append, and re-reading from this offset once the file grows sees the
+   * completed line rather than gluing a stale fragment to fresh bytes.
+   *
+   * @param text - JSONL source text.
+   * @returns The resume cursor, in UTF-8 bytes.
+   */
+  static consumedOffset(text: string): number;
+  /**
+   * Parse one candidate line's JSON.
+   *
+   * Any JSON value succeeds — objects, arrays and scalars alike. This layer
+   * does not know what an envelope is.
+   *
+   * @param line - A slice from {@link Line.split}.
+   * @returns The {@link ParsedLine}, or a {@link MalformedLine} carrying the
+   *   slice so the caller can locate the damage and decide whether an
+   *   unterminated line is a torn tail worth waiting for.
+   */
+  static parseResult(line: LineSlice): Result.Result<ParsedLine, MalformedLine>;
+  /**
+   * Parse every non-blank line, reporting failures rather than dropping them.
+   *
+   * There is deliberately no "valid lines only" variant. A hole in the middle
+   * of a journal is information — it means a line was written that no reader
+   * can interpret — and whether that is tolerable is the caller's decision,
+   * not this module's. Filter the `Result`s yourself and the choice stays
+   * visible at the call site.
+   *
+   * Whitespace-only lines are skipped rather than reported: they carry no
+   * information to lose, and reporting them would make a hand-edited journal
+   * look corrupt.
+   *
+   * @param text - JSONL source text.
+   * @returns One `Result` per non-blank line, in source order.
+   */
+  static parseAll(text: string): ReadonlyArray<Result.Result<ParsedLine, MalformedLine>>;
+  /**
+   * Walk back from the end to the last line that parses.
+   *
+   * This is the whole read path for a snapshot-style journal, where the
+   * current state *is* the last valid line: a session killed mid-append leaves
+   * a partial final line, and the walk-back steps over it — and over any
+   * number of malformed or blank trailing lines — to the last line that means
+   * something.
+   *
+   * Parsing stops at the first success, so the cost is proportional to the
+   * damage at the tail rather than to the age of the file.
+   *
+   * **A torn tail is only detectable when its fragment fails to parse.**
+   * Every strict prefix of a JSON *object* is invalid JSON, so a truncated
+   * `{"event":"unlinked"}` is always caught. A truncated *scalar* is not:
+   * `42` cut mid-write leaves `4`, which parses cleanly as a different value.
+   * The JSON layer cannot close that hole — the envelope layer can, because
+   * `4` is not an envelope, which is one more reason the envelope is the
+   * package's contract rather than an option. Check `LineSlice.terminated` on
+   * the result when it matters.
+   *
+   * @param text - JSONL source text.
+   * @returns The last parseable line, or `Option.none()` if none parses.
+   */
+  static lastValid(text: string): Option.Option<ParsedLine>;
+}
+//#endregion
+export { type AppendOptions, type CursoredSlice, type DataSchema, Envelope, EnvelopeFrame, type EnvelopeOf, type EnvelopeUnion, type EnvelopeWithTag, InvalidData, Journal, type JournalClass, JournalClosed, type JournalConfig, JournalNotFound, type JournalReadError, JournalResync, type JournalShape, type JournalWriteError, type JsonlError, JsonlEvent, JsonlEventTypeId, Line, LineSlice, MalformedLine, ParsedLine, type Slice, TerminalViolation, UnknownEvent, UnserializableData };
+//# sourceMappingURL=index.d.ts.map