@effected/jsonl 0.9.0 → 0.11.0

package/index.d.ts

@@ -1,62 +1,14 @@
-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
- */
-export declare class LineSlice extends LineSlice_base {}
-//#endregion
+import { Context, DateTime, Duration, Effect, FileSystem, Layer, Option, PlatformError, Result, Schema, Scope, Stream } from "effect";
 //#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;
+  readonly line: Schema.Struct<{
+    readonly offset: Schema.Number;
+    readonly end: Schema.Number;
+    readonly length: Schema.Number;
+    readonly text: Schema.String;
+    readonly terminated: Schema.Boolean;
+  }>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * A journal line that is not valid JSON.
@@ -88,8 +40,14 @@ export 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 offending line, with its byte offsets into the source. Absent on the encode path. */
+  readonly line: Schema.optionalKey<Schema.Struct<{
+    readonly offset: Schema.Number;
+    readonly end: Schema.Number;
+    readonly length: Schema.Number;
+    readonly text: Schema.String;
+    readonly terminated: Schema.Boolean;
+  }>>;
   /** The unrecognized tag as it appeared on the envelope. */
   readonly event: Schema.String;
   /** The tags this journal's registry does define. */
@@ -110,8 +68,17 @@ export 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 offending line, with its byte offsets into the source. Absent when the
+   * failure came from encoding a payload for append, which has no line yet.
+   */
+  readonly line: Schema.optionalKey<Schema.Struct<{
+    readonly offset: Schema.Number;
+    readonly end: Schema.Number;
+    readonly length: Schema.Number;
+    readonly text: Schema.String;
+    readonly terminated: Schema.Boolean;
+  }>>;
   /**
    * The event tag whose payload schema rejected the data, or `none` when it
    * was the envelope frame itself that failed.
@@ -164,8 +131,8 @@ declare const JournalNotFound_base: Schema.Class<JournalNotFound, Schema.TaggedS
  *
  * 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
+ * What is not legal is materializing it implicitly: `append` and `query` fail
+ * with this (and `latest` reads as empty) 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`.
  *
@@ -178,7 +145,7 @@ declare const UnserializableData_base: Schema.Class<UnserializableData, Schema.T
   /** The event tag whose payload could not be serialized. */
   readonly event: Schema.String;
   /** The value `JSON.stringify` threw, carried structurally. */
-  readonly cause: Schema.Unknown;
+  readonly cause: Schema.Defect;
 }>, import("effect/Cause").YieldableError>;
 /**
  * A payload that validated against its schema but cannot be serialized to JSON.
@@ -268,6 +235,13 @@ declare const JournalResync_base: Schema.Class<JournalResync, Schema.TaggedStruc
 export declare class JournalResync extends JournalResync_base {
   get message(): string;
 }
+/**
+ * Why one line could not be decoded into an envelope: not JSON, not an
+ * envelope (or a bad payload), or a tag the registry does not define.
+ *
+ * @public
+ */
+type DecodeError = MalformedLine | InvalidData | UnknownEvent;
 /**
  * Every error this package raises from the pure core and the journal service.
  *
@@ -301,18 +275,6 @@ type JsonlError = MalformedLine | UnknownEvent | InvalidData | UnserializableDat
  * @public
  */
 type DataSchema = Schema.Codec<unknown, unknown, never, never>;
-/**
- * Unique type identifier marking a JSONL event definition.
- *
- * @public
- */
-export type JsonlEventTypeId = "~effected/jsonl/JsonlEvent";
-/**
- * Runtime type identifier marking a JSONL event definition.
- *
- * @public
- */
-export declare const JsonlEventTypeId: JsonlEventTypeId;
 /**
  * One event definition: a tag, the schema its `data` must satisfy, and the two
  * lifecycle markings.
@@ -325,7 +287,6 @@ export declare const JsonlEventTypeId: JsonlEventTypeId;
  * @public
  */
 export 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. */
@@ -356,7 +317,6 @@ export declare namespace JsonlEvent {
    * @public
    */
   interface Any {
-    readonly [JsonlEventTypeId]: JsonlEventTypeId;
     readonly tag: string;
     readonly data: DataSchema;
     readonly terminal: boolean;
@@ -374,14 +334,6 @@ export declare namespace JsonlEvent {
   }>;
   /** 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.
@@ -419,33 +371,92 @@ export declare const JsonlEvent: {
   }) => JsonlEvent<Tag, Data, Terminal, Reopen>;
 };
 //#endregion
-//#region src/Envelope.d.ts
+//#region src/LineSlice.d.ts
 /**
- * Stage one of the read path: the envelope with its payload left undecoded.
+ * A single candidate line: its text, and where it lives in the source **in
+ * bytes**.
+ *
+ * Every offset here is a UTF-8 byte offset, never a UTF-16 code-unit index,
+ * because these values are cursors into a file that persist 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`.
  *
- * 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.
+ * A plain record rather than a class: `Line.split` produces one per line of
+ * every read, and a class instance costs some forty times a plain object on
+ * that path. The schema exists so errors can carry the line structurally.
  *
- * `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.
+ * @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
  */
-export declare const EnvelopeFrame: Schema.Struct<{
-  readonly at: Schema.DateTimeUtcFromString;
-  readonly event: Schema.String;
-  readonly scope: Schema.optionalKey<Schema.String>;
-  readonly data: Schema.Unknown;
+export declare const 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 `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.
+   */
+  readonly terminated: Schema.Boolean;
 }>;
 /**
- * A decoded envelope: the frame, its validated payload, and where it sits in
- * the source.
+ * A single candidate line: its text, and where it lives in the source in bytes.
  *
- * This interface is what the "derived discriminated union" derives *into*.
- * A registry of event definitions produces a union of these discriminated on
+ * @public
+ */
+export type LineSlice = typeof LineSlice.Type;
+/**
+ * Where an envelope's line sits in the journal, in UTF-8 bytes.
+ *
+ * All an envelope keeps of its source line: enough to resume from (`end`) or
+ * to go back and read the line again (`offset`). The line's text is not kept —
+ * the envelope already holds its decoded payload, and a second copy of every
+ * payload as raw JSON would double what a buffered stream holds. Errors keep
+ * the full {@link (LineSlice:type)}, because there the text is the evidence.
+ *
+ * @public
+ */
+interface LinePosition {
+  /** Byte offset of the line's first content byte. */
+  readonly offset: number;
+  /**
+   * Byte offset just past the line's terminator — where the next line begins.
+   * Persist this and pass it back as a slice's `cursor` to resume.
+   */
+  readonly end: number;
+}
+//#endregion
+//#region src/Envelope.d.ts
+/**
+ * A decoded envelope: the frame, its validated payload, and where its line sits.
+ *
+ * A registry of event definitions derives a union of these discriminated on
  * `event`, so narrowing on the tag recovers the payload type registered for it.
  *
  * @public
@@ -459,8 +470,8 @@ export interface Envelope<out Tag extends string, out Data> {
   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;
+  /** Where this envelope's line sits in the journal. `position.end` is the resume cursor. */
+  readonly position: LinePosition;
 }
 /**
  * The envelope type derived from one event definition. Distributes over a union
@@ -486,24 +497,23 @@ type EnvelopeWithTag<R extends JsonlEvent.Registry, T extends string> = Extract<
 /**
  * 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.
+ * Every operation is synchronous and `Result`-based, so a hook script can read
+ * a journal with no Effect runtime. Lift one into an `Effect` with
+ * `Effect.fromResult` where a program needs it.
  *
  * @example
  * ```ts
- * import { Envelope, JsonlEvent, Line } from "@effected/jsonl";
- * import { Result, Schema } from "effect";
+ * import { Envelope, JsonlEvent } from "@effected/jsonl";
+ * import { Option, Schema } from "effect";
  *
- * const events = [JsonlEvent.make("started", { data: Schema.Struct({ id: Schema.String }) })] as const;
+ * const events = [JsonlEvent.make("state", { data: Schema.Struct({ round: Schema.Number }) })] as const;
  *
  * declare const sourceText: string;
  *
- * for (const line of Line.split(sourceText)) {
- *   const decoded = Envelope.decodeResult(events, line);
- *   if (Result.isSuccess(decoded) && decoded.success.event === "started") {
- *     decoded.success.data.id; // typed from the registered payload schema
- *   }
+ * // The whole read path for a snapshot journal, with no runtime.
+ * const current = Envelope.lastValid(events, sourceText);
+ * if (Option.isSome(current)) {
+ *   current.value.data.round; // typed from the registered payload schema
  * }
  * ```
  *
@@ -511,100 +521,58 @@ type EnvelopeWithTag<R extends JsonlEvent.Registry, T extends string> = Extract<
  */
 export 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`.
-   * @returns The frame with its source `line` attached, or `MalformedLine`
-   *   when the line is not JSON, or `InvalidData` when it is JSON that is not
-   *   an envelope frame.
-   */
-  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.
+   * Decode one line into a fully validated envelope.
    *
    * @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.
+   * @returns The envelope, or why the line 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>>;
+  readonly decodeResult: <const R extends JsonlEvent.Registry>(events: R, line: LineSlice) => Result.Result<EnvelopeUnion<R>, DecodeError>;
   /**
    * 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.
+   * A line that is not a legal envelope is a `Result` in the array, never a gap
+   * in it: whether a hole is tolerable is the caller's decision.
    *
    * @param events - The registry to validate against.
    * @param text - JSONL source text.
+   * @param base - The byte offset `text` starts at in its file.
    * @returns One `Result` per non-blank line, in file order.
    */
-  readonly decodeAllResult: <const R extends JsonlEvent.Registry>(events: R, text: string) => ReadonlyArray<Result.Result<EnvelopeUnion<R>, MalformedLine | InvalidData | UnknownEvent>>;
+  readonly decodeAllResult: <const R extends JsonlEvent.Registry>(events: R, text: string, base?: number) => ReadonlyArray<Result.Result<EnvelopeUnion<R>, DecodeError>>;
   /**
-   * Walk back from the end to the last valid **envelope**.
+   * Walk back from the end to the last valid **envelope** — the journal's
+   * current state.
    *
-   * 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.
+   * A torn tail is stepped over, and so is any number of malformed, foreign or
+   * blank trailing lines. Validity is judged at the envelope, not merely as
+   * JSON: a torn *scalar* (`42` cut mid-write leaves `4`) parses cleanly as a
+   * different value, but is not an envelope. Decoding stops at the first
+   * success, so the cost tracks the damage at the tail, not the file's age.
    *
    * @param events - The registry to validate against.
-   * @param text - JSONL source text.
+   * @param text - JSONL source text — the whole file, or a tail of it that
+   *   begins at a line boundary.
+   * @param base - The byte offset `text` starts at in its file.
    * @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>>;
+  readonly lastValid: <const R extends JsonlEvent.Registry>(events: R, text: string, base?: number) => 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.
+   * cooperative-writer contract is one write of a *complete line*, and an API
+   * returning the text without its terminator would invite writing the two
+   * separately.
    *
    * @param events - The registry to validate against.
-   * @param envelope - The event tag, its payload, the service-assigned
-   *   timestamp, and an optional scope.
-   * @returns The encoded line, or `UnknownEvent` for a tag the registry does
-   *   not define, `InvalidData` when the payload does not satisfy its schema,
-   *   or `UnserializableData` when the encoded payload cannot be turned into
-   *   JSON (a bigint or a reference cycle).
+   * @param envelope - The event tag, its payload, the timestamp, and an
+   *   optional scope.
+   * @returns The encoded line, or `InvalidData` when the payload does not
+   *   satisfy its schema, `UnserializableData` when the encoded payload is not
+   *   JSON (a bigint or a reference cycle), or `UnknownEvent` for a tag the
+   *   registry does not define.
    */
   readonly encodeResult: <const R extends JsonlEvent.Registry, const T extends JsonlEvent.Tag<R>>(events: R, envelope: {
     readonly event: T;
@@ -612,35 +580,67 @@ export declare const Envelope: {
     readonly at: DateTime.Utc;
     readonly scope?: string | undefined;
   }) => Result.Result<string, UnknownEvent | InvalidData | UnserializableData>;
+};
+//#endregion
+//#region src/JournalWatcher.d.ts
+/**
+ * The service shape behind {@link JournalWatcher}.
+ *
+ * @public
+ */
+interface JournalWatcherShape {
   /**
-   * `Envelope.decodeResult` in the `Effect` channel.
+   * Watch `path`, a journal file or the directory it will be created in.
    *
-   * Prefer the sync form in a hook or any caller that has no runtime; this
-   * exists for programs that already are one. Fails with `MalformedLine`,
-   * `InvalidData` or `UnknownEvent`; requires nothing.
-   */
-  readonly decode: <const R extends JsonlEvent.Registry>(events: R, line: LineSlice) => Effect.Effect<EnvelopeUnion<R>, MalformedLine | InvalidData | UnknownEvent>;
-  /**
-   * `Envelope.encodeResult` in the `Effect` channel.
+   * The effect succeeds only once the watch is **registered**: every change
+   * to `path` after it succeeds is delivered on the returned stream. That
+   * ordering is the whole contract — the journal arms a watch, then reads
+   * what it missed, then follows the stream, and a change landing between a
+   * watch that was merely requested and one that was registered would be
+   * lost. The watch lives until the enclosing scope closes. Watching a file,
+   * the stream ends once the path is removed or names a different file (a
+   * rename over it), because a platform watch follows the inode it was armed
+   * on and would otherwise go blind; the journal then re-arms on whatever the
+   * path names now. Watching a directory, it does not end for a child
+   * appearing or vanishing.
    *
-   * Fails with `UnknownEvent`, `InvalidData` or `UnserializableData`; requires
-   * nothing.
+   * Each element is the name the platform reports for the change, which may
+   * be a bare basename and may be absent. The journal treats every element as
+   * an untyped poke — "re-stat the file" — and never opens what it names.
+   *
+   * A path that does not exist fails with a `PlatformError` whose reason is
+   * `NotFound`.
    */
-  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>;
-};
+  readonly watch: (path: string) => Effect.Effect<Stream.Stream<string | undefined, PlatformError.PlatformError>, PlatformError.PlatformError, Scope.Scope>;
+}
+declare const JournalWatcher_base: Context.ServiceClass<JournalWatcher, "@effected/jsonl/JournalWatcher", JournalWatcherShape>;
+/**
+ * How a journal is told its file changed underneath it: a watch that reports
+ * when it is armed.
+ *
+ * Core's `FileSystem.watch` cannot serve here. Its stream registers the
+ * platform watch in a fiber it forks, after an asynchronous `stat`, and gives
+ * no signal when that has happened — so a journal reading what it missed
+ * before the watch was live cannot know whether a concurrent append landed
+ * before registration (and is lost for good) or after (and will be reported).
+ * Under load that window is real. This service closes it by construction:
+ * {@link JournalWatcherShape.watch} succeeds only once registration is done.
+ *
+ * The library owns no backend. On Node, provide `NodeJournalWatcher.layer`
+ * from `@effected/jsonl/node`; elsewhere, implement the shape over the
+ * platform's own watch primitive, honouring the arm-before-success contract.
+ *
+ * @public
+ */
+export declare class JournalWatcher extends JournalWatcher_base {}
 //#endregion
 //#region src/Slice.d.ts
 /**
- * A filter over envelope fields.
+ * A filter over envelope fields, plus where to resume and what to do with a
+ * line that cannot be decoded.
  *
- * 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.
+ * Every field is optional and the filters combine with AND. An omitted field
+ * does not filter; an empty `events: []` or `scopes: []` matches nothing.
  *
  * @public
  */
@@ -658,58 +658,98 @@ interface Slice<R extends JsonlEvent.Registry, T extends JsonlEvent.Tag<R> = Jso
   /** 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`.
+   * Upper bound on `at`, **exclusive**, so adjacent windows tile without
+   * double-delivering an envelope on the seam.
    */
   readonly to?: DateTime.Utc | undefined;
+  /**
+   * Resume from this logical byte offset, **inclusive**.
+   *
+   * Persist a processed envelope's `position.end` and pass it back to replay
+   * exactly the remainder. A cursor pointing into a line skips that line whole.
+   */
+  readonly cursor?: number | undefined;
+  /**
+   * What to do with a line that cannot be decoded — not JSON, not an envelope,
+   * an unknown tag, or a payload its schema rejects.
+   *
+   * - `"skip"` (the default): leave it out and keep reading. A journal shared
+   *   with another writer, or with an older or newer version of this one, stays
+   *   readable past lines this registry does not understand.
+   * - `"fail"`: end the stream with the typed error.
+   *
+   * A line whose frame decodes but does not match the slice is never decoded
+   * further, so it cannot fail a stream that would not have delivered it. One
+   * that cannot be framed at all counts against every slice.
+   */
+  readonly onInvalid?: "skip" | "fail" | undefined;
+}
+//#endregion
+//#region src/internal/engine.d.ts
+/**
+ * Options for one append.
+ *
+ * @public
+ */
+interface AppendOptions {
+  /** The partition key to stamp on the envelope. */
+  readonly scope?: string | undefined;
 }
 /**
- * A {@link Slice} plus a resume point.
+ * Configuration for one journal.
  *
  * @public
  */
-interface CursoredSlice<R extends JsonlEvent.Registry, T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>> extends Slice<R, T> {
+interface JournalConfig {
+  /** Path to the journal file. It need not exist yet. */
+  readonly path: string;
   /**
-   * Resume from this logical byte offset, **inclusive**.
+   * The directory to watch while the journal does not exist yet.
    *
-   * 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.
+   * Defaults to `path`'s parent — everything before its last `/` or `\`, the
+   * one piece of path arithmetic this package performs. Name it explicitly when
+   * your path convention does not survive that, such as a drive-relative
+   * Windows path. Used only until the journal exists.
    */
-  readonly cursor?: number | undefined;
+  readonly directory?: string | undefined;
+  /**
+   * Capacity of the internal subscriber hub. Bounded with backpressure: a slow
+   * subscriber slows appends rather than silently missing envelopes.
+   */
+  readonly capacity?: number | undefined;
+  /**
+   * How long scope close waits for subscribers to accept the end of the
+   * journal. Defaults to five seconds; a subscriber that never consumes must
+   * not be able to hold shutdown hostage.
+   */
+  readonly shutdownPublishTimeout?: Duration.Input | undefined;
 }
-//#endregion
-//#region src/Journal.d.ts
 /**
- * The failure channel of a write operation.
+ * Why an append failed.
  *
- * `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.
+ * `PlatformError` passes through untranslated. **Treat any `PlatformError` from
+ * an append as a possibly-torn tail**: a failed write cannot be read as
+ * "nothing was written". The next reader walks back over the fragment.
  *
  * @public
  */
-type JournalWriteError = JournalClosed | JournalNotFound | TerminalViolation | UnknownEvent | MalformedLine | InvalidData | UnserializableData | PlatformError.PlatformError;
+type AppendError = JournalClosed | JournalNotFound | TerminalViolation | InvalidData | UnserializableData | PlatformError.PlatformError;
 /**
- * The failure channel of a read operation.
+ * Why a historical read failed. A {@link DecodeError} only arrives when the
+ * slice asks for it with `onInvalid: "fail"`.
  *
  * @public
  */
-type JournalReadError = JournalNotFound | PlatformError.PlatformError;
+type QueryError = JournalNotFound | DecodeError | PlatformError.PlatformError;
 /**
- * Options for one append.
+ * Why a live read failed: anything a query can fail with, plus the file being
+ * truncated or replaced beneath the subscriber.
  *
  * @public
  */
-interface AppendOptions {
-  /** The partition key to stamp on the envelope. */
-  readonly scope?: string | undefined;
-}
+type ChangesError = QueryError | JournalResync;
+//#endregion
+//#region src/Journal.d.ts
 /**
  * The shape of a `Journal`, typed by its registry.
  *
@@ -723,250 +763,162 @@ interface JournalShape<R extends JsonlEvent.Registry> {
    * 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>;
+  readonly append: <T extends JsonlEvent.Tag<R>>(event: T, data: JsonlEvent.Data<R, T>, options?: AppendOptions | undefined) => Effect.Effect<EnvelopeWithTag<R, T>, AppendError>;
   /**
-   * Inherit-and-patch: read the last valid envelope, shallow-merge `patch`
-   * over its `data`, validate the result and append it.
+   * Inherit-and-patch: shallow-merge `patch` over the current state's `data`,
+   * validate the result and append it — read and write under one lock.
    *
-   * 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.
+   * The snapshot-journal primitive: each line is a complete state and most
+   * transitions change one field. The merge is **shallow**: 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>;
+  readonly appendPatch: <T extends JsonlEvent.Tag<R>>(event: T, patch: Partial<JsonlEvent.Data<R, T>>, options?: AppendOptions | undefined) => Effect.Effect<EnvelopeWithTag<R, T>, AppendError>;
   /**
-   * The current last valid **envelope**, as an observable `Option`.
+   * The journal's current state: its last valid **envelope**.
    *
-   * "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.
+   * "Last valid" means the last valid envelope, never merely the last valid
+   * JSON. Kept current by local appends and by the watcher.
    */
-  readonly latest: SubscriptionRef.SubscriptionRef<Option.Option<EnvelopeUnion<R>>>;
+  readonly latest: Effect.Effect<Option.Option<EnvelopeUnion<R>>>;
+  /** {@link JournalShape.latest} as a stream: the current value, then every change. */
+  readonly latestChanges: Stream.Stream<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.
+   * Derived from {@link JournalShape.latest}, 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.
+   * Resumable across restarts: persist a processed envelope's `position.end`
+   * and pass it back as `cursor`. Filtering happens on the envelope frame
+   * 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.
+   * The read is paged: the region from `cursor` to the end of the file as of
+   * the call is read a bounded page at a time, each page's matches emitted
+   * before the next is read. Memory is a page plus the longest line, and a
+   * consumer that stops early stops the reading. A line is read once its `\n`
+   * lands: an unterminated tail may be a writer mid-append, so it is left out
+   * rather than rejected.
    */
-  readonly query: <T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>>(slice?: CursoredSlice<R, T> | undefined) => Stream.Stream<EnvelopeWithTag<R, T>, JournalReadError | JsonlError>;
+  readonly query: <T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>>(slice?: Slice<R, T> | undefined) => Stream.Stream<EnvelopeWithTag<R, T>, QueryError>;
   /**
-   * Live read: a `Stream` of matching envelopes as they are appended.
+   * Live read: matching envelopes as they are appended, by this process or any
+   * other writer.
    *
-   * 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.
+   * With a `cursor`, replay and live tail are **one seam**: no gap and no
+   * duplicate at the join. The stream **ends** — it never hangs — when the
+   * journal becomes quiescent or its scope closes, and fails with
+   * `JournalResync` if the file is truncated or replaced beneath it.
    *
    * @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.
+   * Every append that completed is delivered before the stream ends, provided
+   * the subscriber keeps taking; shutdown will not wait past its bound for one
+   * that does not.
    */
-  readonly changes: <T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>>(slice?: CursoredSlice<R, T> | undefined) => Stream.Stream<EnvelopeWithTag<R, T>, JournalReadError | JsonlError>;
+  readonly changes: <T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>>(slice?: Slice<R, T> | undefined) => Stream.Stream<EnvelopeWithTag<R, T>, ChangesError>;
   /**
-   * 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.
+   * A running fold over {@link JournalShape.changes}, emitted as it advances.
+   * The fold only sees its own slice, so a per-scope state machine is
+   * exhaustively checkable against that scope's events alone.
    */
-  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 projection: <S, T extends JsonlEvent.Tag<R> = JsonlEvent.Tag<R>>(initial: S, fold: (state: S, envelope: EnvelopeWithTag<R, T>) => S, slice?: Slice<R, T> | undefined) => Stream.Stream<S, ChangesError>;
+  /** Create the journal file if it does not exist. Creation is always explicit. */
   readonly create: Effect.Effect<void, PlatformError.PlatformError>;
-  /** Remove the journal file. Always explicit. */
+  /** Remove the journal file. */
   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 tears an in-flight
-   * stream instead of ending it.
-   *
-   * @internal
-   */
-  readonly hub: PubSub.PubSub<Take.Take<EnvelopeUnion<R>, JsonlError>>;
 }
 /**
- * Configuration for one journal layer.
+ * A per-registry `Journal` service class.
  *
  * @public
  */
-interface JournalConfig {
-  /** Path to the journal file. It need not exist yet. */
-  readonly path: string;
+interface JournalClass<Self, Id extends string, R extends JsonlEvent.Registry, E, RC> extends Context.ServiceClass<Self, Id, JournalShape<R>> {
+  /** The registry this journal was defined over. */
+  readonly events: R;
   /**
-   * The directory to watch while the journal does not exist yet.
+   * The layer for this journal, built from the definition's `config`.
    *
-   * 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.
+   * One value per class, so providing it twice provides one journal twice —
+   * never two unsynchronized journals over the same file.
    *
-   * 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.
+   * @remarks
+   * A journal file that does not exist yet is legal and constructs cleanly; one
+   * that exists and cannot be read fails with `PlatformError`.
    */
-  readonly capacity?: number | undefined;
+  readonly layer: Layer.Layer<Self, PlatformError.PlatformError | E, FileSystem.FileSystem | JournalWatcher | RC>;
   /**
-   * 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.
+   * Build a journal over an explicit config, for a path only known at run
+   * time. Wrap it in `Layer.effect(Class, Class.make(config))` and bind that
+   * layer once: every build is an independent journal.
    */
-  readonly shutdownPublishTimeout?: Duration.Input | undefined;
+  readonly make: (config: JournalConfig) => Effect.Effect<JournalShape<R>, PlatformError.PlatformError, FileSystem.FileSystem | JournalWatcher | Scope.Scope>;
 }
 /**
- * A per-registry `Journal` service class.
+ * Defines journal services.
  *
  * @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;
+export declare class Journal {
+  private constructor();
   /**
-   * 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.
+   * Define a `Journal` service class over a registry.
    *
-   * **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.
+   * Each registry gets its own uniquely-keyed class, so several journals
+   * coexist in one layer graph, each typed by its own registry. `config` is a
+   * plain record or an `Effect` producing one — so a path can come from
+   * `Config` or another service, resolved when the layer builds.
    *
+   * @example
    * ```ts
-   * // correct
-   * export const layer = MailJournal.layer({ path });
-   *
-   * // WRONG — a second, unserialized journal over the same file
-   * Effect.provide(program, MailJournal.layer({ path }));
+   * import { Journal, JsonlEvent } from "@effected/jsonl";
+   * import { NodeJournalWatcher } from "@effected/jsonl/node";
+   * import { NodeFileSystem } from "@effect/platform-node";
+   * import { Effect, Schema } from "effect";
+   *
+   * const events = [JsonlEvent.make("mail", { data: Schema.Struct({ round: Schema.Number }) })] as const;
+   *
+   * class Mail extends Journal.Service<Mail>()("app/Mail", {
+   *   events,
+   *   config: { path: ".app/mail.jsonl" },
+   * }) {}
+   *
+   * const program = Effect.gen(function* () {
+   *   const mail = yield* Mail;
+   *   yield* mail.append("mail", { round: 1 });
+   * }).pipe(
+   *   Effect.provide(Mail.layer),
+   *   Effect.provide([NodeFileSystem.layer, NodeJournalWatcher.layer]),
+   * );
    * ```
    */
-  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)`.
- *
- * Pass the registry as `options.events`; the returned class exposes it as
- * `events` and builds the scoped layer with `.layer(config)`.
- *
- * @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>()("app/MailJournal", { events }) {}
- *
- * export const layer = MailJournal.layer({ path: ".app/mail.jsonl" });
- * ```
- *
- * @public
- */
-export declare const Journal: {
-  readonly Service: <Self>() => <const Id extends string, const R extends JsonlEvent.Registry>(id: Id, options: {
+  static Service<Self>(): <const Id extends string, const R extends JsonlEvent.Registry, E = never, RC = never>(id: Id, options: {
     readonly events: R;
-  }) => JournalClass<Self, Id, R>;
-};
+    readonly config: JournalConfig | Effect.Effect<JournalConfig, E, RC>;
+  }) => JournalClass<Self, Id, R, E, RC>;
+}
 //#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.
+ * Splitting and parsing JSONL text.
  *
- * `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
- */
-export 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.
+ * Every operation is total and synchronous: nothing here throws. A `JSON.parse`
+ * failure becomes a {@link MalformedLine}, because a journal is untrusted input
+ * and untrusted input fails typed.
  *
  * @public
  */
 export declare class Line {
+  private constructor();
   /**
    * 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.
+   * 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 emits.
    *
    * @example
    * ```ts
@@ -980,88 +932,31 @@ export declare class Line {
   /**
    * 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`.
+   * Lines are separated by `\n`; a `\r` immediately preceding it is part of the
+   * terminator, so CRLF journals split identically to LF ones. A bare `\r` is
+   * ordinary content. A trailing terminator does **not** produce a phantom
+   * empty final line; interior blank lines *are* returned, because they are
+   * real bytes at real offsets. Only the final slice can be unterminated.
    *
    * @param text - JSONL source text.
-   * @returns One {@link LineSlice} per candidate line, in source order.
+   * @param base - The byte offset `text` starts at in its file. Every offset
+   *   returned is shifted by it, so text read from the middle of a journal
+   *   yields offsets into the journal rather than into the text.
+   * @returns One {@link (LineSlice:type)} 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;
+  static split(text: string, base?: number): ReadonlyArray<LineSlice>;
   /**
    * Parse one candidate line's JSON.
    *
-   * Any JSON value succeeds — objects, arrays and scalars alike. This layer
-   * does not know what an envelope is.
+   * Any JSON value succeeds — objects, arrays and scalars alike.
    *
    * @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.
+   * @returns The parsed value, or a {@link MalformedLine} carrying the slice so
+   *   the caller can locate the damage. An unterminated malformed line is a
+   *   torn tail; a terminated one is a hole that will never heal.
    */
-  static lastValid(text: string): Option.Option<ParsedLine>;
+  static parseResult(line: LineSlice): Result.Result<unknown, MalformedLine>;
 }
 //#endregion
-export type { AppendOptions, CursoredSlice, DataSchema, EnvelopeOf, EnvelopeUnion, EnvelopeWithTag, JournalClass, JournalConfig, JournalReadError, JournalShape, JournalWriteError, JsonlError, Slice };
+export type { AppendError, AppendOptions, ChangesError, DataSchema, DecodeError, EnvelopeOf, EnvelopeUnion, EnvelopeWithTag, JournalClass, JournalConfig, JournalShape, JournalWatcherShape, JsonlError, LinePosition, QueryError, Slice };
 //# sourceMappingURL=index.d.ts.map