@alineo-labs/sqlite 0.2.3 → 0.3.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/dist/index.d.mts CHANGED
@@ -1,4 +1,5 @@
1
- import { CheckpointInfo, EnvironmentRecord, IStorageAdapter, LedgerEntry, ListSandboxOptions, SandboxDetails } from "@alineo-labs/core";
1
+ import { Database } from "bun:sqlite";
2
+ import { CheckpointInfo, EngineLedgerEntry, EngineLedgerRow, EnvironmentRecord, IEngineLedger, IStorageAdapter, LedgerEntry, ListSandboxOptions, SandboxDetails } from "@alineo-labs/core";
2
3
  //#region src/adapter.d.ts
3
4
  export declare class SQLiteAdapter implements IStorageAdapter {
4
5
  private readonly db;
@@ -18,4 +19,91 @@ export declare class SQLiteAdapter implements IStorageAdapter {
18
19
  deleteEnvironment(name: string): Promise<void>;
19
20
  listEnvironments(): Promise<EnvironmentRecord[]>;
20
21
  }
21
- //#endregion
22
+ //#endregion
23
+ //#region src/engine-ledger.d.ts
24
+ /**
25
+ * Column names to bind this ledger onto. Defaults to its own `engine_ledger` table — but a
26
+ * consumer with a pre-existing, differently-named ledger table (alineod's `ledger`, with
27
+ * `run_id`/`agent_id` instead of `scope`/`sub_scope`) can point this at its *own* table and
28
+ * columns instead, so the physical schema never has to change. `seq`/`ts`/`event`/`payload`
29
+ * are not configurable — every known consumer's schema already spells them the same way.
30
+ */
31
+ interface SQLiteEngineLedgerSchema {
32
+ table: string;
33
+ scopeColumn: string;
34
+ subScopeColumn: string;
35
+ }
36
+ /**
37
+ * A row with `payload` left as the raw stored string, never `JSON.parse`d. Exists because
38
+ * `rowToEntry`'s eager parse turns one historically-malformed row (bad JSON written before a
39
+ * validation bug was fixed, or written directly for a test) into a hard failure for every
40
+ * other row in the same read — the caller never gets a chance to catch and skip just that one.
41
+ * alineod's `db.ts` depends on exactly this: a damaged `ledger` row must not break reading the
42
+ * rest of a run's events (`apps/alineod/test/transcript.test.ts`'s "skips a damaged row").
43
+ */
44
+ interface RawEngineLedgerRow {
45
+ seq: number;
46
+ scope: string;
47
+ subScope: string | null;
48
+ ts: number;
49
+ event: string;
50
+ payload: string | null;
51
+ }
52
+ /**
53
+ * `IEngineLedger` on `bun:sqlite` — durability-roadmap.md M3 (3.1b). alineod's own
54
+ * `apps/alineod/src/state/db.ts` is this interface's first non-sandbox-SDK consumer: it binds
55
+ * this onto its *existing* `ledger` table (`run_id`/`agent_id`, via `schema`) rather than
56
+ * migrating onto a renamed one, since 11 other files across `apps/alineod` (migrations, ops
57
+ * checks, several tests) already address that table and its columns directly in raw SQL —
58
+ * renaming it would ripple into all of them for no behavioral gain. What alineod actually
59
+ * gets from adopting this: the same query/index shape as the sandbox SDK's own ledger, from
60
+ * one shared, tested implementation, instead of two independently hand-rolled ones that can
61
+ * silently drift (e.g. the composite-index fix in `adapter.ts` otherwise has no reason to ever
62
+ * get applied to alineod's copy).
63
+ */
64
+ export declare class SQLiteEngineLedger implements IEngineLedger {
65
+ private readonly db;
66
+ private readonly ownsConnection;
67
+ private readonly insert;
68
+ private readonly selectByScope;
69
+ private readonly selectByScopeAfter;
70
+ private readonly selectBySubScope;
71
+ private readonly selectBySubScopeAndEvent;
72
+ private readonly selectAll;
73
+ /**
74
+ * `pathOrDb` accepts either a file path (opens its own connection — a standalone consumer
75
+ * like `apps/sandbox/server/registry.ts`) or an already-open `Database` (a consumer that,
76
+ * like alineod, already manages one shared connection across several tables and must not
77
+ * open a second one to the same file). Pragmas only run for a path, not a passed-in
78
+ * connection — the caller already owns those for their connection.
79
+ *
80
+ * `schema` lets a consumer with a pre-existing, differently-shaped ledger table bind onto
81
+ * its own table/columns instead of this class's default `engine_ledger` one — see
82
+ * `SQLiteEngineLedgerSchema`. When a custom `schema` is given, this class never runs
83
+ * `ENGINE_LEDGER_MIGRATION_SQL`: the caller already owns that table's DDL (its indexes,
84
+ * its migrations), and creating/indexing it here too would duplicate or conflict with that.
85
+ */
86
+ constructor(pathOrDb: string | Database, schema?: SQLiteEngineLedgerSchema);
87
+ connect(): Promise<void>;
88
+ /** A no-op when constructed from a shared connection — the owner closes it, not this. */
89
+ close(): Promise<void>;
90
+ append(entry: EngineLedgerEntry): Promise<EngineLedgerRow>;
91
+ readByScope(scope: string, opts?: {
92
+ afterSeq?: number;
93
+ }): Promise<EngineLedgerRow[]>;
94
+ readBySubScope(subScope: string, event?: string): Promise<EngineLedgerRow[]>;
95
+ readAll(): Promise<EngineLedgerRow[]>;
96
+ appendSync(entry: EngineLedgerEntry): EngineLedgerRow;
97
+ readByScopeSync(scope: string, opts?: {
98
+ afterSeq?: number;
99
+ }): EngineLedgerRow[];
100
+ readBySubScopeSync(subScope: string, event?: string): EngineLedgerRow[];
101
+ readAllSync(): EngineLedgerRow[];
102
+ readByScopeRawSync(scope: string, opts?: {
103
+ afterSeq?: number;
104
+ }): RawEngineLedgerRow[];
105
+ readBySubScopeRawSync(subScope: string, event?: string): RawEngineLedgerRow[];
106
+ readAllRawSync(): RawEngineLedgerRow[];
107
+ }
108
+ //#endregion
109
+ export type { RawEngineLedgerRow, SQLiteEngineLedgerSchema };
package/dist/index.mjs CHANGED
@@ -2,10 +2,16 @@ import { Database } from "bun:sqlite";
2
2
  import { mkdirSync } from "node:fs";
3
3
  import { dirname } from "node:path";
4
4
  import { SandboxStatus } from "@alineo-labs/core";
5
+ import { renameEventsStatement } from "@alineo-labs/ledger";
5
6
  //#region src/migrations.ts
6
7
  const MIGRATION_SQL = `
7
8
  CREATE TABLE IF NOT EXISTS alineo_events (
8
- id INTEGER PRIMARY KEY AUTOINCREMENT,
9
+ -- No AUTOINCREMENT: this is an append-only log, so rowid reuse after a delete is not a
10
+ -- concern worth paying a sqlite_sequence write on every insert for (foundation-packages.md
11
+ -- Phase 3). Only affects freshly-created databases -- SQLite can't retroactively strip
12
+ -- AUTOINCREMENT from an existing table's schema, and that's a one-time insert-cost
13
+ -- difference, not a correctness issue, so an existing database is left as-is.
14
+ id INTEGER PRIMARY KEY,
9
15
  sandbox_id TEXT NOT NULL,
10
16
  name TEXT NOT NULL,
11
17
  step_idx INTEGER NOT NULL,
@@ -16,8 +22,17 @@ CREATE TABLE IF NOT EXISTS alineo_events (
16
22
  ts INTEGER NOT NULL
17
23
  );
18
24
 
19
- CREATE INDEX IF NOT EXISTS alineo_events_sandbox_id ON alineo_events(sandbox_id);
20
- CREATE INDEX IF NOT EXISTS alineo_events_name ON alineo_events(name);
25
+ -- Replaces the two single-column indexes below (dropped in adapter.ts's connect(), for
26
+ -- existing databases) -- every hot read filters on (name, sandbox_id) and orders by ts, which
27
+ -- this one composite index now covers end to end instead of SQLite picking one single-column
28
+ -- index, filtering the rest, then sorting ts separately. 'id' is a tie-breaker only (two
29
+ -- entries can share a ts) -- the primary sort key stays 'ts', not 'id': callers can append
30
+ -- entries with an out-of-order ts (see adapter.test.ts's "returns entries in ascending
31
+ -- timestamp order", which deliberately appends ts 2000 then ts 1000 and expects ts order back),
32
+ -- so 'id' is not a safe substitute for 'ts' the way foundation-packages.md's original proposal
33
+ -- assumed -- insertion order and timestamp order are not guaranteed to agree.
34
+ CREATE INDEX IF NOT EXISTS alineo_events_name_sandbox_ts
35
+ ON alineo_events(name, sandbox_id, ts, id);
21
36
 
22
37
  CREATE TABLE IF NOT EXISTS alineo_environments (
23
38
  name TEXT PRIMARY KEY,
@@ -33,14 +48,14 @@ const AGG_SQL = (whereClause) => `
33
48
  SELECT
34
49
  name,
35
50
  sandbox_id,
36
- MIN(CASE WHEN event = 'sandbox_created' THEN ts END) AS started_at,
37
- MAX(CASE WHEN event = 'sandbox_closed' THEN ts END) AS completed_at,
38
- MAX(CASE WHEN event = 'sandbox_closed' THEN 1 ELSE 0 END) AS is_closed,
39
- CAST(COUNT(CASE WHEN event = 'exec_complete' THEN 1 END) AS INTEGER) AS exec_count,
40
- MAX(CASE WHEN event = 'sandbox_created' THEN json_extract(payload, '$.runId') END) AS run_id,
41
- MAX(CASE WHEN event = 'sandbox_created' THEN json_extract(payload, '$.resourceId') END) AS resource_id,
42
- MAX(CASE WHEN event = 'sandbox_created' THEN json_extract(payload, '$.teamId') END) AS team_id,
43
- MAX(CASE WHEN event = 'sandbox_created' THEN json_extract(payload, '$.parentSandboxId') END) AS parent_sandbox_id
51
+ MIN(CASE WHEN event = 'sandbox.created' THEN ts END) AS started_at,
52
+ MAX(CASE WHEN event = 'sandbox.closed' THEN ts END) AS completed_at,
53
+ MAX(CASE WHEN event = 'sandbox.closed' THEN 1 ELSE 0 END) AS is_closed,
54
+ CAST(COUNT(CASE WHEN event = 'exec.completed' THEN 1 END) AS INTEGER) AS exec_count,
55
+ MAX(CASE WHEN event = 'sandbox.created' THEN json_extract(payload, '$.runId') END) AS run_id,
56
+ MAX(CASE WHEN event = 'sandbox.created' THEN json_extract(payload, '$.resourceId') END) AS resource_id,
57
+ MAX(CASE WHEN event = 'sandbox.created' THEN json_extract(payload, '$.teamId') END) AS team_id,
58
+ MAX(CASE WHEN event = 'sandbox.created' THEN json_extract(payload, '$.parentSandboxId') END) AS parent_sandbox_id
44
59
  FROM alineo_events
45
60
  ${whereClause}
46
61
  GROUP BY name, sandbox_id
@@ -75,7 +90,7 @@ function applyOpts(details, opts) {
75
90
  if (opts?.limit != null) result = result.slice(0, opts.limit);
76
91
  return result;
77
92
  }
78
- function rowToEntry(row) {
93
+ function rowToEntry$1(row) {
79
94
  return {
80
95
  sandboxId: row.sandbox_id,
81
96
  name: row.name,
@@ -98,8 +113,13 @@ var SQLiteAdapter = class {
98
113
  this.db = new Database(path, { create: true });
99
114
  }
100
115
  async connect() {
116
+ this.db.run("DROP INDEX IF EXISTS alineo_events_sandbox_id;");
117
+ this.db.run("DROP INDEX IF EXISTS alineo_events_name;");
101
118
  this.db.run(MIGRATION_SQL);
119
+ const rename = renameEventsStatement();
120
+ this.db.run(rename.sql, rename.params);
102
121
  this.db.run("PRAGMA journal_mode = WAL;");
122
+ this.db.run("PRAGMA synchronous = FULL;");
103
123
  }
104
124
  async close() {
105
125
  this.db.close();
@@ -112,15 +132,15 @@ var SQLiteAdapter = class {
112
132
  return this.db.prepare(`SELECT sandbox_id, name, step_idx, branch, event, payload, error, ts
113
133
  FROM alineo_events
114
134
  WHERE name = ? AND sandbox_id = ?
115
- ORDER BY ts ASC`).all(name, sandboxId).map(rowToEntry);
135
+ ORDER BY ts ASC, id ASC`).all(name, sandboxId).map(rowToEntry$1);
116
136
  }
117
137
  async lastCheckpoint(name, sandboxId) {
118
138
  const row = this.db.prepare(`SELECT sandbox_id, name, step_idx, branch, event, payload, error, ts
119
139
  FROM alineo_events
120
- WHERE name = ? AND sandbox_id = ? AND event = 'checkpoint_created'
121
- ORDER BY ts DESC
140
+ WHERE name = ? AND sandbox_id = ? AND event = 'sandbox.checkpoint_created'
141
+ ORDER BY ts DESC, id DESC
122
142
  LIMIT 1`).get(name, sandboxId);
123
- return row ? rowToEntry(row) : null;
143
+ return row ? rowToEntry$1(row) : null;
124
144
  }
125
145
  async listSandboxDetails(name, opts) {
126
146
  return applyOpts(this.db.prepare(AGG_SQL("WHERE name = ?")).all(name).map(aggRowToDetails), opts);
@@ -138,8 +158,8 @@ var SQLiteAdapter = class {
138
158
  async listCheckpoints(name, sandboxId) {
139
159
  return this.db.prepare(`SELECT sandbox_id, name, step_idx, branch, event, payload, error, ts
140
160
  FROM alineo_events
141
- WHERE name = ? AND sandbox_id = ? AND event = 'checkpoint_created'
142
- ORDER BY ts ASC`).all(name, sandboxId).map((r) => {
161
+ WHERE name = ? AND sandbox_id = ? AND event = 'sandbox.checkpoint_created'
162
+ ORDER BY ts ASC, id ASC`).all(name, sandboxId).map((r) => {
143
163
  const p = r.payload !== null ? JSON.parse(r.payload) : { snapshotId: "" };
144
164
  return {
145
165
  snapshotId: p.snapshotId,
@@ -174,4 +194,145 @@ var SQLiteAdapter = class {
174
194
  }
175
195
  };
176
196
  //#endregion
177
- export { SQLiteAdapter };
197
+ //#region src/engine-ledger.ts
198
+ const ENGINE_LEDGER_MIGRATION_SQL = `
199
+ CREATE TABLE IF NOT EXISTS engine_ledger (
200
+ seq INTEGER PRIMARY KEY,
201
+ scope TEXT NOT NULL,
202
+ sub_scope TEXT,
203
+ ts INTEGER NOT NULL,
204
+ event TEXT NOT NULL,
205
+ payload TEXT
206
+ );
207
+ CREATE INDEX IF NOT EXISTS engine_ledger_scope ON engine_ledger (scope, seq);
208
+ CREATE INDEX IF NOT EXISTS engine_ledger_sub_scope_event ON engine_ledger (sub_scope, event, seq);
209
+ `;
210
+ const DEFAULT_SCHEMA = {
211
+ table: "engine_ledger",
212
+ scopeColumn: "scope",
213
+ subScopeColumn: "sub_scope"
214
+ };
215
+ function rowToEntry(row) {
216
+ return {
217
+ seq: row.seq,
218
+ scope: row.scope,
219
+ subScope: row.sub_scope ?? void 0,
220
+ ts: row.ts,
221
+ event: row.event,
222
+ payload: row.payload !== null ? JSON.parse(row.payload) : void 0
223
+ };
224
+ }
225
+ function rowToRawEntry(row) {
226
+ return {
227
+ seq: row.seq,
228
+ scope: row.scope,
229
+ subScope: row.sub_scope,
230
+ ts: row.ts,
231
+ event: row.event,
232
+ payload: row.payload
233
+ };
234
+ }
235
+ /**
236
+ * `IEngineLedger` on `bun:sqlite` — durability-roadmap.md M3 (3.1b). alineod's own
237
+ * `apps/alineod/src/state/db.ts` is this interface's first non-sandbox-SDK consumer: it binds
238
+ * this onto its *existing* `ledger` table (`run_id`/`agent_id`, via `schema`) rather than
239
+ * migrating onto a renamed one, since 11 other files across `apps/alineod` (migrations, ops
240
+ * checks, several tests) already address that table and its columns directly in raw SQL —
241
+ * renaming it would ripple into all of them for no behavioral gain. What alineod actually
242
+ * gets from adopting this: the same query/index shape as the sandbox SDK's own ledger, from
243
+ * one shared, tested implementation, instead of two independently hand-rolled ones that can
244
+ * silently drift (e.g. the composite-index fix in `adapter.ts` otherwise has no reason to ever
245
+ * get applied to alineod's copy).
246
+ */
247
+ var SQLiteEngineLedger = class {
248
+ db;
249
+ ownsConnection;
250
+ insert;
251
+ selectByScope;
252
+ selectByScopeAfter;
253
+ selectBySubScope;
254
+ selectBySubScopeAndEvent;
255
+ selectAll;
256
+ /**
257
+ * `pathOrDb` accepts either a file path (opens its own connection — a standalone consumer
258
+ * like `apps/sandbox/server/registry.ts`) or an already-open `Database` (a consumer that,
259
+ * like alineod, already manages one shared connection across several tables and must not
260
+ * open a second one to the same file). Pragmas only run for a path, not a passed-in
261
+ * connection — the caller already owns those for their connection.
262
+ *
263
+ * `schema` lets a consumer with a pre-existing, differently-shaped ledger table bind onto
264
+ * its own table/columns instead of this class's default `engine_ledger` one — see
265
+ * `SQLiteEngineLedgerSchema`. When a custom `schema` is given, this class never runs
266
+ * `ENGINE_LEDGER_MIGRATION_SQL`: the caller already owns that table's DDL (its indexes,
267
+ * its migrations), and creating/indexing it here too would duplicate or conflict with that.
268
+ */
269
+ constructor(pathOrDb, schema = DEFAULT_SCHEMA) {
270
+ this.ownsConnection = typeof pathOrDb === "string";
271
+ if (typeof pathOrDb === "string") {
272
+ try {
273
+ mkdirSync(dirname(pathOrDb), { recursive: true });
274
+ } catch (e) {
275
+ if (e.code !== "EEXIST") throw e;
276
+ }
277
+ this.db = new Database(pathOrDb, { create: true });
278
+ this.db.run("PRAGMA journal_mode = WAL;");
279
+ this.db.run("PRAGMA synchronous = FULL;");
280
+ } else this.db = pathOrDb;
281
+ if (schema === DEFAULT_SCHEMA) this.db.run(ENGINE_LEDGER_MIGRATION_SQL);
282
+ const { table, scopeColumn: sc, subScopeColumn: ssc } = schema;
283
+ const cols = `seq, ${sc} AS scope, ${ssc} AS sub_scope, ts, event, payload`;
284
+ this.insert = this.db.query(`INSERT INTO ${table} (${sc}, ${ssc}, ts, event, payload)
285
+ VALUES (?, ?, ?, ?, ?) RETURNING seq`);
286
+ this.selectByScope = this.db.query(`SELECT ${cols} FROM ${table} WHERE ${sc} = ? ORDER BY seq ASC`);
287
+ this.selectByScopeAfter = this.db.query(`SELECT ${cols} FROM ${table} WHERE ${sc} = ? AND seq > ? ORDER BY seq ASC`);
288
+ this.selectBySubScope = this.db.query(`SELECT ${cols} FROM ${table} WHERE ${ssc} = ? ORDER BY seq ASC`);
289
+ this.selectBySubScopeAndEvent = this.db.query(`SELECT ${cols} FROM ${table} WHERE ${ssc} = ? AND event = ? ORDER BY seq ASC`);
290
+ this.selectAll = this.db.query(`SELECT ${cols} FROM ${table} ORDER BY seq ASC`);
291
+ }
292
+ async connect() {}
293
+ /** A no-op when constructed from a shared connection — the owner closes it, not this. */
294
+ close() {
295
+ if (this.ownsConnection) this.db.close();
296
+ return Promise.resolve();
297
+ }
298
+ append(entry) {
299
+ return Promise.resolve(this.appendSync(entry));
300
+ }
301
+ readByScope(scope, opts) {
302
+ return Promise.resolve(this.readByScopeSync(scope, opts));
303
+ }
304
+ readBySubScope(subScope, event) {
305
+ return Promise.resolve(this.readBySubScopeSync(subScope, event));
306
+ }
307
+ readAll() {
308
+ return Promise.resolve(this.readAllSync());
309
+ }
310
+ appendSync(entry) {
311
+ const payloadJson = entry.payload === void 0 ? null : JSON.stringify(entry.payload);
312
+ const { seq } = this.insert.get(entry.scope, entry.subScope ?? null, entry.ts, entry.event, payloadJson);
313
+ return {
314
+ ...entry,
315
+ seq
316
+ };
317
+ }
318
+ readByScopeSync(scope, opts) {
319
+ return (opts?.afterSeq !== void 0 ? this.selectByScopeAfter.all(scope, opts.afterSeq) : this.selectByScope.all(scope)).map(rowToEntry);
320
+ }
321
+ readBySubScopeSync(subScope, event) {
322
+ return (event !== void 0 ? this.selectBySubScopeAndEvent.all(subScope, event) : this.selectBySubScope.all(subScope)).map(rowToEntry);
323
+ }
324
+ readAllSync() {
325
+ return this.selectAll.all().map(rowToEntry);
326
+ }
327
+ readByScopeRawSync(scope, opts) {
328
+ return (opts?.afterSeq !== void 0 ? this.selectByScopeAfter.all(scope, opts.afterSeq) : this.selectByScope.all(scope)).map(rowToRawEntry);
329
+ }
330
+ readBySubScopeRawSync(subScope, event) {
331
+ return (event !== void 0 ? this.selectBySubScopeAndEvent.all(subScope, event) : this.selectBySubScope.all(subScope)).map(rowToRawEntry);
332
+ }
333
+ readAllRawSync() {
334
+ return this.selectAll.all().map(rowToRawEntry);
335
+ }
336
+ };
337
+ //#endregion
338
+ export { SQLiteAdapter, SQLiteEngineLedger };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alineo-labs/sqlite",
3
- "version": "0.2.3",
3
+ "version": "0.3.0",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -28,7 +28,8 @@
28
28
  "test": "bun test"
29
29
  },
30
30
  "dependencies": {
31
- "@alineo-labs/core": "0.4.2"
31
+ "@alineo-labs/core": "0.5.0",
32
+ "@alineo-labs/ledger": "0.2.0"
32
33
  },
33
34
  "devDependencies": {
34
35
  "bun-types": "1.4.2",