@alineo-labs/ledger 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,4 +1,47 @@
1
- # Temporary Holding Version
1
+ # @alineo-labs/ledger
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
4
- If no other versions are published within 30 days, this package and version will be deleted.
3
+ Behaviour for alineo's event ledger: sinks, fold helpers, and an in-memory store. The shapes
4
+ live in [`@alineo-labs/schema`](../schema); this package is what _does_ something with them.
5
+
6
+ ```bash
7
+ bun add @alineo-labs/ledger
8
+ ```
9
+
10
+ ## Sinks
11
+
12
+ A sink is where an event goes on its way out — OpenTelemetry, a warehouse, a file.
13
+
14
+ ```ts
15
+ import { composeSinks, jsonlSink, memorySink } from "@alineo-labs/ledger";
16
+
17
+ const captured = memorySink();
18
+ const sink = composeSinks([captured, jsonlSink((line) => stream.write(line))]);
19
+ ```
20
+
21
+ **A sink is synchronous and must not throw.** Both constraints come from where sinks sit: on
22
+ the write path of a sandbox operation. An async sink invites a caller to await it, and a slow
23
+ export becomes sandbox backpressure. A throwing sink fails the operation that emitted the
24
+ event — exactly backwards, since an export failing should never stop the work being exported.
25
+
26
+ `composeSinks` isolates each sink, so one broken exporter cannot break its siblings or the
27
+ operation that triggered them. A sink that genuinely needs IO buffers internally and flushes
28
+ on its own schedule.
29
+
30
+ ## Storage
31
+
32
+ `LedgerStorage` is the narrow append/read surface a durable store offers — three methods, not
33
+ fourteen. `MemoryStorage` implements it for tests. The real sqlite and postgres engines land
34
+ behind the same interface later.
35
+
36
+ The store assigns `seq`, because it is the only thing that can: a monotone sequence needs a
37
+ single writer for an aggregate.
38
+
39
+ ## Fold
40
+
41
+ ```ts
42
+ import { fold, inLedgerOrder, persistedOnly } from "@alineo-labs/ledger";
43
+ ```
44
+
45
+ Replay helpers for the fold-equivalence gate — rebuild a projection from a sink's captured
46
+ stream and deep-equal it against the one rebuilt from the store's rows. If dual-write ever
47
+ drifts, that comparison is where it surfaces.
@@ -0,0 +1,123 @@
1
+ import { LedgerEnvelope, PersistedEnvelope } from "@alineo-labs/schema/types";
2
+ //#region src/sink.d.ts
3
+ /**
4
+ * Somewhere an event goes on its way out — OpenTelemetry, a warehouse, a file.
5
+ *
6
+ * **Synchronous, and it must not throw.** Both constraints come from where sinks sit: on the
7
+ * write path of a sandbox operation. An async sink invites a caller to await it, and a slow
8
+ * export would become sandbox backpressure. A throwing sink would fail the operation that
9
+ * emitted the event, which is exactly backwards — an export failing should never stop the
10
+ * work being exported.
11
+ *
12
+ * A sink that genuinely needs IO buffers internally and flushes on its own schedule.
13
+ *
14
+ * This is the same contract `composeHooks()` already established in
15
+ * `@alineo-labs/core`'s `sandbox/hooks.ts`: one broken adapter cannot break its siblings or
16
+ * the operation that triggered them.
17
+ */
18
+ type EventSink = (envelope: LedgerEnvelope) => void;
19
+ /**
20
+ * Fan an event out to several sinks, isolating each.
21
+ *
22
+ * A throwing sink is reported through `onError` and the rest still run. `onError` itself is
23
+ * guarded, because a reporting callback that throws would defeat the whole arrangement —
24
+ * that is the failure this function exists to prevent, and it would be embarrassing to
25
+ * reintroduce it one level up.
26
+ */
27
+ export declare function composeSinks(sinks: readonly EventSink[], onError?: (error: unknown, envelope: LedgerEnvelope) => void): EventSink;
28
+ interface MemorySink {
29
+ (envelope: LedgerEnvelope): void;
30
+ /** Everything captured, in emission order. */
31
+ readonly events: readonly LedgerEnvelope[];
32
+ clear(): void;
33
+ }
34
+ /**
35
+ * Collects envelopes in an array. The fold-equivalence gate runs alineod's suite with one of
36
+ * these attached and rebuilds projections from what it captured.
37
+ */
38
+ export declare function memorySink(): MemorySink;
39
+ /**
40
+ * Serialises each envelope as one JSON line.
41
+ *
42
+ * Takes a `write` rather than a path, because opening a file is the caller's decision and
43
+ * this package does no IO of its own — which is also what keeps it testable without a
44
+ * filesystem.
45
+ */
46
+ export declare function jsonlSink(write: (line: string) => void): EventSink;
47
+ //#endregion
48
+ //#region src/storage.d.ts
49
+ /**
50
+ * The narrow read/append surface a durable store has to offer.
51
+ *
52
+ * Deliberately small. `IStorageAdapter` in `@alineo-labs/core` has fourteen methods mixing an
53
+ * event log, read models and an environment cache, and users are expected to implement it —
54
+ * which is why two of the three internal consumers hand-rolled `bun:sqlite` instead. This is
55
+ * the log, and nothing else.
56
+ *
57
+ * Phase 3 backs it with the real sqlite and postgres engines. `MemoryStorage` below is enough
58
+ * for tests and for the fold helpers.
59
+ */
60
+ interface LedgerStorage {
61
+ /**
62
+ * Append one event and return it with `durable` filled in.
63
+ *
64
+ * The store assigns `seq` — it is the only thing that can, being the single writer for an
65
+ * aggregate.
66
+ */
67
+ append(envelope: LedgerEnvelope): PersistedEnvelope;
68
+ /** Every persisted event for an aggregate, in `seq` order. */
69
+ read(aggregate: string): PersistedEnvelope[];
70
+ /** Events after `seq`, in order. What an SSE reconnect replays. */
71
+ readSince(aggregate: string, seq: number): PersistedEnvelope[];
72
+ }
73
+ /** An in-memory `LedgerStorage`. Not durable; for tests and fold helpers. */
74
+ export declare class MemoryStorage implements LedgerStorage {
75
+ #private;
76
+ append(envelope: LedgerEnvelope): PersistedEnvelope;
77
+ read(aggregate: string): PersistedEnvelope[];
78
+ readSince(aggregate: string, seq: number): PersistedEnvelope[];
79
+ /** Every aggregate this store holds. What a boot-time rebuild iterates. */
80
+ aggregates(): string[];
81
+ }
82
+ //#endregion
83
+ //#region src/fold.d.ts
84
+ /**
85
+ * Replay helpers, used by the fold-equivalence gate.
86
+ *
87
+ * The gate is the one that actually proves dual-write is honest: run a suite with a
88
+ * `memorySink()` attached, rebuild projections from what it captured, and deep-equal the
89
+ * result against the projection rebuilt from the store's own rows. If the two writes ever
90
+ * disagree, that comparison is where it surfaces — not in production, months later.
91
+ */
92
+ /** Left-fold a stream of envelopes into a projection. */
93
+ export declare function fold<S>(events: Iterable<LedgerEnvelope>, initial: S, apply: (state: S, envelope: LedgerEnvelope) => S): S;
94
+ /**
95
+ * Sort by `durable.seq` within each aggregate, then by timestamp across them.
96
+ *
97
+ * A sink sees events in emission order, which is usually persist order but is not guaranteed
98
+ * to be across two aggregates. Comparing a sink's stream against a store's rows means putting
99
+ * them in the same order first, or the comparison fails for a reason that has nothing to do
100
+ * with the thing being tested.
101
+ */
102
+ export declare function inLedgerOrder(events: readonly LedgerEnvelope[]): LedgerEnvelope[];
103
+ /** Only the events that earned a row — what a store holds and a rebuild sees. */
104
+ export declare function persistedOnly(events: readonly LedgerEnvelope[]): LedgerEnvelope[];
105
+ /** Group by aggregate, preserving order within each. */
106
+ export declare function byAggregate(events: readonly LedgerEnvelope[]): Map<string, LedgerEnvelope[]>;
107
+ //#endregion
108
+ //#region src/rename-events.d.ts
109
+ export declare function eventRenames(): [string, string][];
110
+ /**
111
+ * The single-pass UPDATE, and its parameters.
112
+ *
113
+ * Lives here rather than in either adapter because both need it and neither should depend on
114
+ * the other. It returns SQL and parameters rather than running anything — placeholders are
115
+ * `?`, which the postgres adapter renumbers to `$1`-style on its way in. No driver, no
116
+ * connection, nothing engine-specific.
117
+ */
118
+ export declare function renameEventsStatement(): {
119
+ sql: string;
120
+ params: string[];
121
+ };
122
+ //#endregion
123
+ export type { EventSink, LedgerStorage, MemorySink };
package/dist/index.mjs ADDED
@@ -0,0 +1,211 @@
1
+ import { RENAMED_EVENTS } from "@alineo-labs/schema";
2
+ //#region src/sink.ts
3
+ /**
4
+ * Fan an event out to several sinks, isolating each.
5
+ *
6
+ * A throwing sink is reported through `onError` and the rest still run. `onError` itself is
7
+ * guarded, because a reporting callback that throws would defeat the whole arrangement —
8
+ * that is the failure this function exists to prevent, and it would be embarrassing to
9
+ * reintroduce it one level up.
10
+ */
11
+ function composeSinks(sinks, onError) {
12
+ return (envelope) => {
13
+ for (const sink of sinks) try {
14
+ sink(envelope);
15
+ } catch (error) {
16
+ try {
17
+ onError?.(error, envelope);
18
+ } catch {}
19
+ }
20
+ };
21
+ }
22
+ /**
23
+ * Collects envelopes in an array. The fold-equivalence gate runs alineod's suite with one of
24
+ * these attached and rebuilds projections from what it captured.
25
+ */
26
+ function memorySink() {
27
+ const events = [];
28
+ const sink = ((envelope) => {
29
+ events.push(envelope);
30
+ });
31
+ Object.defineProperty(sink, "events", { get: () => events });
32
+ sink.clear = () => {
33
+ events.length = 0;
34
+ };
35
+ return sink;
36
+ }
37
+ /**
38
+ * Serialises each envelope as one JSON line.
39
+ *
40
+ * Takes a `write` rather than a path, because opening a file is the caller's decision and
41
+ * this package does no IO of its own — which is also what keeps it testable without a
42
+ * filesystem.
43
+ */
44
+ function jsonlSink(write) {
45
+ return (envelope) => {
46
+ write(`${JSON.stringify(envelope)}\n`);
47
+ };
48
+ }
49
+ //#endregion
50
+ //#region src/storage.ts
51
+ /** An in-memory `LedgerStorage`. Not durable; for tests and fold helpers. */
52
+ var MemoryStorage = class {
53
+ #byAggregate = /* @__PURE__ */ new Map();
54
+ append(envelope) {
55
+ const aggregate = envelope.durable?.aggregate ?? envelope.runId ?? envelope.agentId;
56
+ if (!aggregate) throw new Error(`Cannot append ${envelope.type}: no aggregate. Set durable.aggregate, or a runId or agentId to derive it from.`);
57
+ const rows = this.#byAggregate.get(aggregate) ?? [];
58
+ if (rows.length === 0) this.#byAggregate.set(aggregate, rows);
59
+ const persisted = {
60
+ ...envelope,
61
+ durable: {
62
+ aggregate,
63
+ seq: (rows.at(-1)?.durable.seq ?? 0) + 1,
64
+ version: envelope.durable?.version ?? 1
65
+ }
66
+ };
67
+ rows.push(persisted);
68
+ return persisted;
69
+ }
70
+ read(aggregate) {
71
+ return [...this.#byAggregate.get(aggregate) ?? []];
72
+ }
73
+ readSince(aggregate, seq) {
74
+ return this.read(aggregate).filter((e) => e.durable.seq > seq);
75
+ }
76
+ /** Every aggregate this store holds. What a boot-time rebuild iterates. */
77
+ aggregates() {
78
+ return [...this.#byAggregate.keys()];
79
+ }
80
+ };
81
+ //#endregion
82
+ //#region src/fold.ts
83
+ /**
84
+ * Replay helpers, used by the fold-equivalence gate.
85
+ *
86
+ * The gate is the one that actually proves dual-write is honest: run a suite with a
87
+ * `memorySink()` attached, rebuild projections from what it captured, and deep-equal the
88
+ * result against the projection rebuilt from the store's own rows. If the two writes ever
89
+ * disagree, that comparison is where it surfaces — not in production, months later.
90
+ */
91
+ /** Left-fold a stream of envelopes into a projection. */
92
+ function fold(events, initial, apply) {
93
+ let state = initial;
94
+ for (const envelope of events) state = apply(state, envelope);
95
+ return state;
96
+ }
97
+ /**
98
+ * Sort by `durable.seq` within each aggregate, then by timestamp across them.
99
+ *
100
+ * A sink sees events in emission order, which is usually persist order but is not guaranteed
101
+ * to be across two aggregates. Comparing a sink's stream against a store's rows means putting
102
+ * them in the same order first, or the comparison fails for a reason that has nothing to do
103
+ * with the thing being tested.
104
+ */
105
+ function inLedgerOrder(events) {
106
+ return [...events].sort((a, b) => {
107
+ if (a.durable && b.durable && a.durable.aggregate === b.durable.aggregate) return a.durable.seq - b.durable.seq;
108
+ return a.ts - b.ts;
109
+ });
110
+ }
111
+ /** Only the events that earned a row — what a store holds and a rebuild sees. */
112
+ function persistedOnly(events) {
113
+ return events.filter((e) => e.durable !== void 0);
114
+ }
115
+ /** Group by aggregate, preserving order within each. */
116
+ function byAggregate(events) {
117
+ const groups = /* @__PURE__ */ new Map();
118
+ for (const event of events) {
119
+ const aggregate = event.durable?.aggregate;
120
+ if (!aggregate) continue;
121
+ const group = groups.get(aggregate);
122
+ if (group) group.push(event);
123
+ else groups.set(aggregate, [event]);
124
+ }
125
+ return groups;
126
+ }
127
+ //#endregion
128
+ //#region src/rename-events.ts
129
+ /**
130
+ * One-time rename of `alineo_events.event` from the old flat names to the namespaced ones.
131
+ *
132
+ * **Idempotent by construction**, matching every other migration here — there is no
133
+ * `schema_version` table anywhere in this repo, so `WHERE event IN (…old names…)` matching
134
+ * nothing on a second run *is* the version check.
135
+ *
136
+ * **One pass, not one per name.** `event` is **unindexed** on this table (only `sandbox_id`
137
+ * and `name` are), so each separate `UPDATE` would be a full scan. A `CASE` over one scan
138
+ * replaces roughly twenty-five of them. This is a one-time boot cost either way, but there is
139
+ * no reason for it to be accidentally quadratic on a large ledger.
140
+ *
141
+ * **This is one-way.** An older SDK reading a migrated database would find event names it
142
+ * does not recognise, and `getSandboxDetails` — which aggregates on `event = 'sandbox.created'`
143
+ * and friends — would return nothing rather than fail loudly.
144
+ */
145
+ /**
146
+ * The pairs this store rewrites.
147
+ *
148
+ * `alineo_events` holds the substrate, agent and workflow layers — everything the SDK itself
149
+ * writes. It has never held alineod's swarm events or the harness stream, which live in
150
+ * alineod's own database, so those are excluded: rewriting rows that cannot exist is at best
151
+ * wasted work and at worst wrong about which store owns a name.
152
+ */
153
+ const NOT_IN_THIS_STORE = /* @__PURE__ */ new Set([
154
+ "agent_spawned",
155
+ "agent_provisioned",
156
+ "agent_state_changed",
157
+ "agent_steered",
158
+ "agent_released",
159
+ "agent_ended",
160
+ "handle_settled",
161
+ "wait_resolved",
162
+ "wait_blocked_on_paused",
163
+ "inbox_queued",
164
+ "inbox_delivered",
165
+ "inbox_dropped",
166
+ "notify_registered",
167
+ "budget_denied",
168
+ "subtree_quiescent",
169
+ "agent_start",
170
+ "agent_end",
171
+ "turn_start",
172
+ "turn_end",
173
+ "tool_start",
174
+ "tool_update",
175
+ "tool_end",
176
+ "message_start",
177
+ "message_update",
178
+ "message_end",
179
+ "text",
180
+ "compaction_start",
181
+ "compaction_end",
182
+ "auto_retry_start",
183
+ "auto_retry_end",
184
+ "queue_update",
185
+ "extension_ui",
186
+ "extension_error",
187
+ "permission_request"
188
+ ]);
189
+ function eventRenames() {
190
+ const pairs = Object.entries(RENAMED_EVENTS).filter(([old]) => !NOT_IN_THIS_STORE.has(old));
191
+ pairs.push(["run_started", "workflow.started"]);
192
+ return pairs;
193
+ }
194
+ /**
195
+ * The single-pass UPDATE, and its parameters.
196
+ *
197
+ * Lives here rather than in either adapter because both need it and neither should depend on
198
+ * the other. It returns SQL and parameters rather than running anything — placeholders are
199
+ * `?`, which the postgres adapter renumbers to `$1`-style on its way in. No driver, no
200
+ * connection, nothing engine-specific.
201
+ */
202
+ function renameEventsStatement() {
203
+ const pairs = eventRenames();
204
+ return {
205
+ sql: `UPDATE alineo_events SET event = CASE ${pairs.map(() => "WHEN event = ? THEN ?").join(" ")} ELSE event END
206
+ WHERE event IN (${pairs.map(() => "?").join(", ")})`,
207
+ params: [...pairs.flat(), ...pairs.map(([old]) => old)]
208
+ };
209
+ }
210
+ //#endregion
211
+ export { MemoryStorage, byAggregate, composeSinks, eventRenames, fold, inLedgerOrder, jsonlSink, memorySink, persistedOnly, renameEventsStatement };
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "@alineo-labs/ledger",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "Behaviour for alineo's event ledger: sinks, fold helpers and an in-memory store. Shapes live in @alineo-labs/schema.",
5
+ "license": "Apache-2.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/DrejT/alineo.git",
9
+ "directory": "packages/ledger"
10
+ },
11
+ "files": [
12
+ "dist"
13
+ ],
14
+ "type": "module",
15
+ "main": "./dist/index.mjs",
16
+ "types": "./dist/index.d.mts",
17
+ "exports": {
18
+ ".": {
19
+ "import": "./dist/index.mjs",
20
+ "types": "./dist/index.d.mts"
21
+ }
22
+ },
23
+ "publishConfig": {
24
+ "access": "public",
25
+ "provenance": true
26
+ },
27
+ "scripts": {
28
+ "build": "tsdown",
29
+ "test": "vitest run",
30
+ "test:watch": "vitest"
31
+ },
32
+ "dependencies": {
33
+ "@alineo-labs/schema": "0.2.0"
34
+ },
35
+ "devDependencies": {
36
+ "bun-types": "1.4.2",
37
+ "tsdown": "0.23.0",
38
+ "typescript": "6.0.3",
39
+ "vitest": "5.0.0"
40
+ }
41
+ }