@effected/jsonl 0.9.0 → 0.11.0

package/Journal.js

@@ -1,478 +1,58 @@
-import { LineSlice } from "./LineSlice.js";
-import { JournalClosed, JournalNotFound, JournalResync, TerminalViolation } from "./JsonlError.js";
-import { Line } from "./Line.js";
-import { Envelope } from "./Envelope.js";
-import { canMerge, shallowMerge } from "./internal/merge.js";
-import { DEFAULT_WINDOW, probeBomBytes, readRangeText, readTail, readTailUntil } from "./internal/tail.js";
-import { matchesFrame } from "./Slice.js";
-import { Channel, Context, DateTime, Deferred, Duration, Effect, Exit, Fiber, FileSystem, Layer, Option, PubSub, Result, Semaphore, Stream, SubscriptionRef } from "effect";
+import { makeEngine } from "./internal/engine.js";
+import { Context, Effect, Layer } from "effect";
 
 //#region src/Journal.ts
 /**
-* How long scope close waits for the terminal `Exit` to be accepted by the hub.
+* Defines journal services.
 *
-* Bounded rather than indefinite: a subscriber that never consumes cannot
-* observe completion, so waiting on it forever only converts "one stuck
-* subscriber" into "the process cannot shut down".
-*/
-const SHUTDOWN_PUBLISH_TIMEOUT = Duration.seconds(5);
-/**
-* How many times the watcher re-arms a watch that ends without observing
-* anything before it gives up.
-*
-* A watch that completes instantly — an unsupported backend, a path that keeps
-* vanishing — would otherwise spin the supervisor at full speed, and no timer
-* is permitted here to back it off. Giving up is the honest failure: local
-* appends keep working, live observation does not.
-*/
-const MAX_IMMEDIATE_REARMS = 8;
-/**
-* Scheduler turns yielded to a freshly-forked watch consumer before the
-* catch-up read runs.
-*
-* See the arming comment in `supervise`: this orders arming ahead of catch-up
-* by scheduling rather than by synchronisation, because `fs.watch` offers no
-* registration signal.
-*/
-const ARM_YIELDS = 3;
-/**
-* Index of the last path separator, on either convention.
-*
-* Both are checked because a Windows path contains no `/` at all: matching only
-* on `/` returns `-1` there, which makes the whole path its own basename and
-* points the activation watch at the process working directory — a journal
-* created after its layer was built is then never observed.
-*/
-const lastSeparator = (path) => Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
-/**
-* The last segment of a path.
-*
-* Used for **comparison only** — matching a watch event's basename against the
-* journal's filename. `event.path` is never opened or read, on any watch.
-*/
-const basenameOf = (path) => path.slice(lastSeparator(path) + 1);
-/**
-* The directory a path sits in — the single derived path this package ever
-* hands to the filesystem, and only as {@link JournalConfig.directory}'s
-* default.
-*
-* Path arithmetic is otherwise forbidden here: paths are opaque strings handed
-* straight to `FileSystem`. This one derivation exists because the activation
-* watch has to name a directory and the layer takes only a file path; a caller
-* whose path convention this does not fit (a drive-relative Windows path, say)
-* names the directory explicitly instead.
-*/
-const parentOf = (path) => {
-	const separator = lastSeparator(path);
-	if (separator < 0) return ".";
-	return separator === 0 ? path.slice(0, 1) : path.slice(0, separator);
-};
-/**
-* The last valid envelope in a tail window, with its offsets rebased onto the
-* journal.
-*
-* The walk-back itself is **not** reimplemented here: `Envelope.lastValidResult`
-* is the binding definition of "the journal's current state" — which lines
-* count as blank, which failures are walked over, where it stops — and a second
-* copy of those rules would only be a place for them to drift apart. All this
-* adds is the one thing the pure core cannot know: the window's text begins at
-* `window.start`, so every offset inside it is relative to that.
+* @public
 */
-const decodeWindow = (events, window) => Option.map(Envelope.lastValidResult(events, window.text), (envelope) => ({
-	...envelope,
-	line: new LineSlice({
-		offset: envelope.line.offset + window.start,
-		end: envelope.line.end + window.start,
-		length: envelope.line.length,
-		text: envelope.line.text,
-		terminated: envelope.line.terminated
-	})
-}));
-const makeEngine = (events, config, fs) => Effect.gen(function* () {
-	const terminalTags = new Set(events.filter((event) => event.terminal).map((event) => event.tag));
-	const reopenTags = new Set(events.filter((event) => event.reopen).map((event) => event.tag));
-	/** Guards the WRITE critical section only: file write plus ref updates. */
-	const writePermit = Semaphore.makeUnsafe(1);
-	/**
-	* The publish baton.
-	*
-	* Each append links a fresh Deferred onto this chain **while holding the
-	* write permit**, so publish order is fixed to write order; it then awaits
-	* its predecessor and publishes OUTSIDE the write permit. That is what lets
-	* a stalled subscriber block publishers without wedging writers or
-	* deadlocking scope close, while still making an append complete only once
-	* the hub has accepted its envelope.
-	*/
-	let publishBaton = Deferred.makeUnsafe();
-	Deferred.doneUnsafe(publishBaton, Exit.void);
-	/** Bytes of leading BOM, probed from the file — never inferred from a window. */
-	let bomBytes = 0;
+var Journal = class {
+	constructor() {}
 	/**
-	* The watched file's identity, for detecting replacement.
-	*
-	* Size alone cannot see a same-size replace; inode identity can. `ino` is
-	* an `Option` in core's `File.Info`, so on a platform that does not report
-	* it this degrades to truncation-only detection — stated rather than
-	* pretended away.
+	* Define a `Journal` service class over a registry.
+	*
+	* 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
+	* 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]),
+	* );
+	* ```
 	*/
-	let identity = Option.none();
-	const hub = yield* PubSub.bounded(config.capacity ?? 64);
-	const latest = yield* SubscriptionRef.make(Option.none());
-	/** Refusal state. Read before the permit so a late append fails fast. */
-	let closed = false;
-	/** Logical bytes decoded so far — the resume cursor the watcher advances. */
-	let consumed = 0;
-	const exists = () => fs.exists(config.path);
-	const requireFile = Effect.gen(function* () {
-		if (!(yield* exists())) return yield* new JournalNotFound({ path: config.path });
-	});
-	const readLatest = Effect.gen(function* () {
-		yield* requireFile;
-		return yield* readTailUntil(fs, config.path, bomBytes, (window) => decodeWindow(events, window), DEFAULT_WINDOW);
-	});
-	const refresh = Effect.gen(function* () {
-		const found = yield* readLatest;
-		yield* SubscriptionRef.set(latest, found);
-		return found;
-	});
-	const isTerminalTail = Effect.gen(function* () {
-		const current = yield* SubscriptionRef.get(latest);
-		return Option.isSome(current) && terminalTags.has(current.value.event);
-	});
-	/**
-	* Read `[from, to)` and decode the complete lines in it, in file order.
-	*
-	* The one decode loop the external-growth paths share. Both the watcher's
-	* catch-up ingest and an append whose bytes landed past another writer's
-	* need the same thing — "decode this gap" — and two copies of a loop that
-	* rebases offsets and tolerates a torn tail is exactly the drift that
-	* produces a cursor bug on one path only.
-	*
-	* `advanced` is where the last COMPLETE line ended: an unterminated final
-	* line is not consumed, so a torn tail holds the offset until its writer
-	* finishes it. A line that fails to decode is skipped rather than fatal —
-	* a foreign writer's unknown tag must not blind this reader to the lines
-	* after it.
-	*/
-	const decodeRange = (from, to) => Effect.gen(function* () {
-		const text = yield* readRangeText(fs, config.path, from + bomBytes, to - from);
-		const lines = Line.split(text);
-		const decoded = [];
-		let advanced = from;
-		for (const line of lines) {
-			if (!line.terminated) break;
-			advanced = line.end + from;
-			if (line.text.trim() === "") continue;
-			const rebased = new LineSlice({
-				offset: line.offset + from,
-				end: line.end + from,
-				length: line.length,
-				text: line.text,
-				terminated: true
-			});
-			const envelope = Envelope.decodeResult(events, rebased);
-			if (Result.isSuccess(envelope)) decoded.push(envelope.success);
-		}
-		return {
-			decoded,
-			advanced
+	static Service() {
+		return (id, options) => {
+			const make = (config) => Effect.map(makeEngine(id, options.events, config), (engine) => engine.journal);
+			const config = Effect.isEffect(options.config) ? options.config : Effect.succeed(options.config);
+			class JournalService extends Context.Service()(id) {
+				static events = options.events;
+				static make = make;
+				static layer = Layer.effect(JournalService, Effect.flatMap(config, make));
+			}
+			return JournalService;
 		};
-	});
-	/**
-	* The one write path.
-	*
-	* `build` runs **inside the write permit**, so an inherit-and-patch reads
-	* the current state under the same lock that serializes the write. Reading
-	* outside it was a lost-update race: two concurrent patches to different
-	* fields both read the same base and the second silently reverted the
-	* first.
-	*/
-	const appendWith = (event, build, scope) => Effect.gen(function* () {
-		if (closed) return yield* new JournalClosed({ event });
-		const { envelope, external, predecessor, baton } = yield* writePermit.withPermits(1)(Effect.gen(function* () {
-			if (closed) return yield* new JournalClosed({ event });
-			yield* requireFile;
-			const current = yield* SubscriptionRef.get(latest);
-			if (Option.isSome(current) && terminalTags.has(current.value.event) && !reopenTags.has(event)) return yield* new TerminalViolation({
-				event,
-				terminal: current.value.event
-			});
-			const data = build(current);
-			const at = yield* DateTime.now;
-			const encoded = Envelope.encodeResult(events, {
-				event,
-				data,
-				at,
-				...scope === void 0 ? {} : { scope }
-			});
-			if (Result.isFailure(encoded)) return yield* encoded.failure;
-			const bytes = new TextEncoder().encode(encoded.success);
-			const end = yield* Effect.scoped(Effect.gen(function* () {
-				const file = yield* fs.open(config.path, { flag: "a" });
-				yield* file.writeAll(bytes);
-				const info = yield* file.stat;
-				return Number(info.size) - bomBytes;
-			}));
-			const offset = end - bytes.length;
-			const external = offset > consumed ? (yield* decodeRange(consumed, offset)).decoded : [];
-			consumed = end;
-			const line = new LineSlice({
-				offset,
-				end,
-				length: bytes.length - 1,
-				text: encoded.success.slice(0, -1),
-				terminated: true
-			});
-			const decoded = Envelope.decodeResult(events, line);
-			if (Result.isFailure(decoded)) return yield* decoded.failure;
-			yield* SubscriptionRef.set(latest, Option.some(decoded.success));
-			const previous = publishBaton;
-			const mine = Deferred.makeUnsafe();
-			publishBaton = mine;
-			return {
-				envelope: decoded.success,
-				external,
-				predecessor: previous,
-				baton: mine
-			};
-		}));
-		yield* Effect.uninterruptibleMask((restore) => restore(Effect.gen(function* () {
-			yield* Deferred.await(predecessor);
-			for (const preceding of external) yield* PubSub.publish(hub, [preceding]);
-			yield* PubSub.publish(hub, [envelope]);
-		})).pipe(Effect.ensuring(Deferred.done(baton, Exit.void))));
-		return envelope;
-	});
-	const appendEncoded = (event, data, scope) => appendWith(event, () => data, scope);
-	/**
-	* Read the file from `cursor`, frame-filtered before payload decode.
-	*
-	* **What this actually does, as built**: ONE read of the requested region
-	* — `cursor` to the end of the file, bounded by the file's size — whose
-	* matching envelopes are buffered and then emitted. It is bounded by the
-	* cursor, not by a window, so an unsliced read over a large journal holds
-	* that journal in memory. The frame filter still runs per line before any
-	* payload schema, so the filter-before-decode guarantee is untouched;
-	* what is not true here is the "never held in memory" half.
-	*
-	* Paging this — read one window, emit its envelopes, carry the
-	* unterminated tail into the next read — is spencerbeggs/effected#233,
-	* rather than something attempted alongside the correctness fixes around
-	* it.
-	*/
-	const readFrom = (slice) => Stream.unwrap(Effect.gen(function* () {
-		yield* requireFile;
-		const from = slice?.cursor ?? 0;
-		const info = yield* fs.stat(config.path);
-		const logicalSize = Number(info.size) - bomBytes;
-		if (from >= logicalSize) return Stream.empty;
-		const window = yield* readTail(fs, config.path, logicalSize - from + 1, bomBytes);
-		const lines = Line.split(window.text);
-		const selected = [];
-		for (const line of lines) {
-			if (line.text.trim() === "") continue;
-			const rebased = new LineSlice({
-				offset: line.offset + window.start,
-				end: line.end + window.start,
-				length: line.length,
-				text: line.text,
-				terminated: line.terminated
-			});
-			if (rebased.offset < from) continue;
-			const decoded = Envelope.decodeSelectedResult(events, rebased, (frame) => matchesFrame(frame, slice));
-			if (Option.isNone(decoded)) continue;
-			if (Result.isFailure(decoded.value)) return Stream.concat(Stream.fromIterable(selected), Stream.fail(decoded.value.failure));
-			selected.push(decoded.value.success);
-		}
-		return Stream.fromIterable(selected);
-	}));
-	/**
-	* Envelope-level matching, for the live path.
-	*
-	* The frame-level {@link matchesFrame} is the one that carries the
-	* filter-before-decode guarantee; this is its counterpart for envelopes
-	* that arrived already decoded from the hub, where there is no decode left
-	* to avoid.
-	*/
-	const matchesEnvelope = (envelope, slice) => matchesFrame({
-		at: envelope.at,
-		event: envelope.event,
-		...envelope.scope === void 0 ? {} : { scope: envelope.scope },
-		data: envelope.data
-	}, slice);
-	const isTerminalEnvelope = (envelope) => terminalTags.has(envelope.event);
-	const changesStream = (slice) => Stream.unwrap(Effect.gen(function* () {
-		const alreadyQuiescent = yield* isTerminalTail;
-		const replay = slice?.cursor === void 0 ? Stream.empty : readFrom(slice);
-		if (alreadyQuiescent || closed) return replay;
-		const subscription = yield* PubSub.subscribe(hub);
-		let replayedThrough = slice?.cursor ?? 0;
-		const history = replay.pipe(Stream.tap((envelope) => Effect.sync(() => {
-			replayedThrough = Math.max(replayedThrough, envelope.line.end);
-		})));
-		const live = Stream.fromChannel(Channel.fromEffectTake(PubSub.take(subscription))).pipe(Stream.takeUntil(isTerminalEnvelope), Stream.filter((envelope) => envelope.line.offset >= replayedThrough));
-		return Stream.concat(history, live);
-	}));
-	const identityOf = (info) => Option.map(info.ino, (ino) => `${info.dev}:${ino}`);
-	const ingest = Semaphore.makeUnsafe(1).withPermits(1)(Effect.gen(function* () {
-		if (!(yield* exists())) return;
-		const info = yield* fs.stat(config.path);
-		const currentIdentity = identityOf(info);
-		const logicalSize = Number(info.size) - bomBytes;
-		const replaced = Option.isSome(identity) && Option.isSome(currentIdentity) && identity.value !== currentIdentity.value;
-		if (replaced || logicalSize < consumed) {
-			const failure = new JournalResync({
-				path: config.path,
-				reason: replaced ? "replaced" : "truncated",
-				expected: consumed,
-				actual: logicalSize
-			});
-			identity = currentIdentity;
-			bomBytes = yield* probeBomBytes(fs, config.path);
-			consumed = 0;
-			yield* SubscriptionRef.set(latest, Option.none());
-			yield* PubSub.publish(hub, Exit.fail(failure));
-			return;
-		}
-		identity = currentIdentity;
-		if (logicalSize <= consumed) return;
-		const { envelopes, predecessor, baton } = yield* writePermit.withPermits(1)(Effect.gen(function* () {
-			const { decoded, advanced } = yield* decodeRange(consumed, logicalSize);
-			consumed = advanced;
-			if (decoded.length > 0) yield* SubscriptionRef.set(latest, Option.some(decoded[decoded.length - 1]));
-			const previous = publishBaton;
-			const mine = Deferred.makeUnsafe();
-			publishBaton = mine;
-			return {
-				envelopes: decoded,
-				predecessor: previous,
-				baton: mine
-			};
-		}));
-		yield* Effect.uninterruptibleMask((restore) => restore(Effect.gen(function* () {
-			yield* Deferred.await(predecessor);
-			for (const envelope of envelopes) yield* PubSub.publish(hub, [envelope]);
-		})).pipe(Effect.ensuring(Deferred.done(baton, Exit.void))));
-	}));
-	const shape = {
-		append: (event, data, options) => appendEncoded(event, data, options?.scope),
-		appendPatch: (event, patch, options) => appendWith(event, (current) => {
-			const base = Option.isSome(current) ? current.value.data : void 0;
-			if (!canMerge(base, patch)) return patch;
-			return shallowMerge(base, patch);
-		}, options?.scope),
-		latest,
-		quiescent: isTerminalTail,
-		query: ((slice) => readFrom(slice).pipe(Stream.filter((envelope) => matchesEnvelope(envelope, slice)))),
-		changes: ((slice) => changesStream(slice).pipe(Stream.filter((envelope) => matchesEnvelope(envelope, slice)))),
-		projection: ((initial, fold, slice) => changesStream(slice).pipe(Stream.filter((envelope) => matchesEnvelope(envelope, slice)), Stream.scan(() => initial, fold))),
-		create: Effect.gen(function* () {
-			if (!(yield* exists())) yield* Effect.scoped(fs.open(config.path, { flag: "a" }));
-		}),
-		remove: fs.remove(config.path, { force: true }),
-		hub
-	};
-	if (yield* exists()) {
-		bomBytes = yield* probeBomBytes(fs, config.path);
-		yield* refresh.pipe(Effect.catchTag("JournalNotFound", () => Effect.succeed(Option.none())));
-		const info = yield* fs.stat(config.path);
-		consumed = Number(info.size) - bomBytes;
-	}
-	/**
-	* Watch for the life of the layer scope.
-	*
-	* Two watches, and the distinction matters:
-	*
-	* - **The journal itself**, once it exists. Steady state, one `Update` per
-	*   append, and the tags are trustworthy here.
-	* - **The parent directory**, while the journal does not exist yet. The
-	*   tags are NOT trustworthy at this edge — on the installed node backend a
-	*   creation and an append both arrive as `Remove`, with a bare relative
-	*   `path` — so this watch **never branches on `WatchEvent._tag`**. Any
-	*   event whose path BASENAME matches the journal filename is an untyped
-	*   poke meaning "re-stat the journal yourself".
-	*
-	* The directory watch is an **activation** watch and nothing more: it ends
-	* as soon as the journal exists, and the supervisor then arms the file
-	* watch. Staying on it would be silently wrong rather than merely
-	* redundant — a non-recursive directory watch reports creation, not a
-	* child's later content appends, so a journal that never handed off would
-	* observe its own appends and no external ones.
-	*
-	* `event.path` is **never** used to open or read anything, on either watch.
-	* It can be a bare basename that resolves against the process CWD; the
-	* journal's own configured path is the only path this service touches. The
-	* symptom of violating that is a phantom `JournalNotFound` on a healthy
-	* journal.
-	*
-	* No timer anywhere. Activation is event-driven.
-	*/
-	const basename = basenameOf(config.path);
-	const directory = config.directory ?? parentOf(config.path);
-	const watchJournal = fs.watch(config.path).pipe(Stream.runForEach(() => ingest), Effect.ignore);
-	const watchForCreation = fs.watch(directory).pipe(Stream.filter((event) => basenameOf(event.path) === basename), Stream.takeUntilEffect(() => exists()), Stream.runForEach(() => ingest), Effect.ignore);
-	const supervise = Effect.gen(function* () {
-		let immediateCompletions = 0;
-		for (;;) {
-			const startedAt = consumed;
-			if (yield* exists()) {
-				const armed = yield* Effect.forkChild(watchJournal);
-				for (let turn = 0; turn < ARM_YIELDS; turn++) yield* Effect.yieldNow;
-				yield* ingest;
-				yield* Fiber.join(armed);
-				yield* ingest;
-			} else yield* watchForCreation;
-			immediateCompletions = consumed === startedAt ? immediateCompletions + 1 : 0;
-			if (immediateCompletions > MAX_IMMEDIATE_REARMS) return;
-		}
-	});
-	yield* Effect.forkScoped(supervise.pipe(Effect.ignore));
-	yield* Effect.addFinalizer(() => Effect.gen(function* () {
-		closed = true;
-		const pending = yield* writePermit.withPermits(1)(Effect.sync(() => publishBaton));
-		yield* Effect.interruptible(Effect.gen(function* () {
-			yield* Deferred.await(pending);
-			yield* PubSub.publish(hub, Exit.void);
-		})).pipe(Effect.timeout(config.shutdownPublishTimeout ?? SHUTDOWN_PUBLISH_TIMEOUT), Effect.ignore);
-	}));
-	return shape;
-});
-/**
-* 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
-*/
-const Journal = { Service: () => (id, options) => {
-	class JournalService extends Context.Service()(id) {
-		static events = options.events;
-		static layer = (config) => Layer.effect(JournalService, Effect.gen(function* () {
-			const fs = yield* FileSystem.FileSystem;
-			return yield* makeEngine(options.events, config, fs);
-		}));
 	}
-	return JournalService;
-} };
+};
 
 //#endregion
 export { Journal };

package/JournalWatcher.js

@@ -0,0 +1,25 @@
+import { Context } from "effect";
+
+//#region src/JournalWatcher.ts
+/**
+* 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
+*/
+var JournalWatcher = class extends Context.Service()("@effected/jsonl/JournalWatcher") {};
+
+//#endregion
+export { JournalWatcher };

package/JsonlError.js

@@ -12,6 +12,8 @@ import { Option, Schema } from "effect";
 * and expected types — instead of flattening it to a string at the boundary.
 */
 const SchemaErrorFromSelf = Schema.declare(Schema.isSchemaError);
+/** The ` at byte offset N` suffix, when there is a line to locate. */
+const at = (line) => line === void 0 ? "" : ` at byte offset ${line.offset}`;
 /**
 * A journal line that is not valid JSON.
 *
@@ -57,15 +59,15 @@ line: LineSlice }) {
 * @public
 */
 var UnknownEvent = class extends Schema.TaggedError()("UnknownEvent", {
-	/** The offending line, with its byte offsets into the source. */
-	line: LineSlice,
+	/** The offending line, with its byte offsets into the source. Absent on the encode path. */
+	line: Schema.optionalKey(LineSlice),
 	/** The unrecognized tag as it appeared on the envelope. */
 	event: Schema.String,
 	/** The tags this journal's registry does define. */
 	known: Schema.Array(Schema.String)
 }) {
 	get message() {
-		return `unknown JSONL event ${JSON.stringify(this.event)} at byte offset ${this.line.offset}`;
+		return `unknown JSONL event ${JSON.stringify(this.event)}${at(this.line)}`;
 	}
 };
 /**
@@ -83,8 +85,11 @@ var UnknownEvent = class extends Schema.TaggedError()("UnknownEvent", {
 * @public
 */
 var InvalidData = class extends Schema.TaggedError()("InvalidData", {
-	/** The offending line, with its byte offsets into the source. */
-	line: 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.
+	*/
+	line: Schema.optionalKey(LineSlice),
 	/**
 	* The event tag whose payload schema rejected the data, or `none` when it
 	* was the envelope frame itself that failed.
@@ -94,7 +99,7 @@ var InvalidData = class extends Schema.TaggedError()("InvalidData", {
 	error: SchemaErrorFromSelf
 }) {
 	get message() {
-		return `invalid JSONL ${Option.isSome(this.event) ? `payload for event ${JSON.stringify(this.event.value)}` : "envelope"} at byte offset ${this.line.offset}: ${this.error.message}`;
+		return `invalid JSONL ${Option.isSome(this.event) ? `payload for event ${JSON.stringify(this.event.value)}` : "envelope"}${at(this.line)}: ${this.error.message}`;
 	}
 };
 /**
@@ -121,8 +126,8 @@ var TerminalViolation = class extends Schema.TaggedError()("TerminalViolation",
 *
 * 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`.
 *
@@ -161,7 +166,7 @@ var UnserializableData = class extends Schema.TaggedError()("UnserializableData"
 	/** The event tag whose payload could not be serialized. */
 	event: Schema.String,
 	/** The value `JSON.stringify` threw, carried structurally. */
-	cause: Schema.Unknown
+	cause: Schema.Defect()
 }) {
 	get message() {
 		const detail = this.cause instanceof Error ? this.cause.message : "value is not JSON-serializable";

package/JsonlEvent.js

@@ -1,11 +1,5 @@
 //#region src/JsonlEvent.ts
 /**
-* Runtime type identifier marking a JSONL event definition.
-*
-* @public
-*/
-const JsonlEventTypeId = "~effected/jsonl/JsonlEvent";
-/**
 * Defines an event.
 *
 * The `const` type parameters are load-bearing: they keep `"unlinked"` a
@@ -34,7 +28,6 @@ const JsonlEventTypeId = "~effected/jsonl/JsonlEvent";
 * @public
 */
 const JsonlEvent = { make: (tag, options) => ({
-	[JsonlEventTypeId]: JsonlEventTypeId,
 	tag,
 	data: options.data,
 	terminal: options.terminal ?? false,
@@ -42,4 +35,4 @@ const JsonlEvent = { make: (tag, options) => ({
 }) };
 
 //#endregion
-export { JsonlEvent, JsonlEventTypeId };
+export { JsonlEvent };