@boxxy/store-sqlite 0.1.0 → 0.1.3

package/README.md

@@ -5,12 +5,17 @@
     <a href="https://www.npmjs.com/package/@boxxy/store-sqlite"><img src="https://img.shields.io/npm/v/@boxxy/store-sqlite" alt="npm version"></a>
     <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
   </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
 </div>
 
-boxxy's store on SQLite: the schema, the migrations and the transactions.
+boxxy's store on SQLite: the schema, the migrations and the transactions behind the `ClaimStore`
+port.
 
-This version is a placeholder that exports only its package name, as `packageName`. The
-[boxxy README](https://github.com/zgeoff/boxxy#workspace) lists the workspace's packages.
+`createSQLiteClaimStore(path)` opens one SQLite file, creates it when it's missing, runs the
+migrations the file hasn't run, and returns the store with a `close` function.
 
 ## Install
 
@@ -21,3 +26,19 @@ bun add @boxxy/store-sqlite
 ```
 
 The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- Items, levers, attempts, leases, limit seats, notes, notices and the outbox in one file, with each
+  change applied whole or not at all
+  ([one write path](../../docs/design/boxxy/slice-1.md#one-write-path)).
+- `exclusive` calls that run one at a time in a `BEGIN IMMEDIATE` transaction, and `read` calls that
+  see the last commit ([store rules](../../docs/design/boxxy/slice-1.md#store-rules)).
+- Each item's position and state derived on each read, from the rows and the loaded rules
+  ([v1](../../docs/design/boxxy/v1.md)).
+
+## Documentation
+
+The [v1 tables migration](./src/migrations/v1-tables-migration.ts) creates each table, and the store
+section of [`02-types.ts`](../../docs/design/boxxy/sketches/v1/core/02-types.ts) gives the port, the
+seat take and the seat sync.

package/dist/codecs/parse-json-text.d.ts

@@ -0,0 +1 @@
+export declare function parseJSONText(text: string): unknown;

package/dist/codecs/parse-store-row.d.ts

@@ -0,0 +1,2 @@
+import type { TableName, Tables } from '@boxxy/model';
+export declare function parseStoreRow<T extends TableName>(table: T, record: object): Tables[T];

package/dist/codecs/table-codecs.d.ts

@@ -0,0 +1,10 @@
+import type { TableName, Tables } from '@boxxy/model';
+interface TableCodec<Row> {
+    readonly fields: readonly (keyof Row & string)[];
+    readonly json: readonly (keyof Row & string)[];
+    readonly flags: readonly (keyof Row & string)[];
+}
+export declare const tableCodecs: {
+    readonly [T in TableName]: TableCodec<Tables[T]>;
+};
+export {};

package/dist/codecs/to-column-name.d.ts

@@ -0,0 +1 @@
+export declare function toColumnName(field: string): string;

package/dist/codecs/to-store-columns.d.ts

@@ -0,0 +1,3 @@
+import type { TableName } from '@boxxy/model';
+export type StoreValue = string | number | null;
+export declare function toStoreColumns(table: TableName, fields: object): [string, StoreValue][];

package/dist/constants.d.ts

@@ -0,0 +1 @@
+export declare const lockWaitLimitMs = 5000;

package/dist/create-sqlite-claim-store.d.ts

@@ -0,0 +1,5 @@
+import type { ClaimStore } from '@boxxy/model';
+export interface SQLiteClaimStore extends ClaimStore {
+    close: () => Promise<void>;
+}
+export declare function createSQLiteClaimStore(path: string): Promise<SQLiteClaimStore>;

package/dist/index.d.ts

@@ -1 +1 @@
-export { packageName } from './package-name.ts';
+export { createSQLiteClaimStore, type SQLiteClaimStore } from './create-sqlite-claim-store.ts';

package/dist/migrations/create-tables-migration.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from 'kysely/migration';
+export declare const createTablesMigration: Migration;

package/dist/migrations/rename-relations-migration.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from 'kysely/migration';
+export declare const renameRelationsMigration: Migration;

package/dist/migrations/run-store-migrations.d.ts

@@ -0,0 +1,3 @@
+import type { Kysely } from 'kysely';
+import type { StoreDatabase } from '../types.ts';
+export declare function runStoreMigrations(db: Kysely<StoreDatabase>): Promise<void>;

package/dist/migrations/v1-tables-migration.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from 'kysely/migration';
+export declare const v1TablesMigration: Migration;

package/dist/reads/build-sqlite-reader.d.ts

@@ -0,0 +1,4 @@
+import type { StoreReader } from '@boxxy/model';
+import type { Kysely } from 'kysely';
+import type { StoreDatabase } from '../types.ts';
+export declare function buildSQLiteReader(db: Kysely<StoreDatabase>): StoreReader;

package/dist/reads/is-latest-of-session.d.ts

@@ -0,0 +1,3 @@
+import type { Expression, ExpressionBuilder, SqlBool } from 'kysely';
+import type { StoreDatabase } from '../types.ts';
+export declare function isLatestOfSession(builder: ExpressionBuilder<StoreDatabase, 'attempts'>): Expression<SqlBool>;

package/dist/reads/read-item-views.d.ts

@@ -0,0 +1,5 @@
+import type { Instant, ItemRules, ItemWithLevers } from '@boxxy/model';
+import type { Expression, ExpressionBuilder, Kysely, SqlBool } from 'kysely';
+import type { StoreDatabase } from '../types.ts';
+export type ItemScope = (builder: ExpressionBuilder<StoreDatabase, 'items'>) => Expression<SqlBool>;
+export declare function readItemViews(db: Kysely<StoreDatabase>, scope: ItemScope, now: Instant, rules: ItemRules): Promise<ItemWithLevers[]>;

package/dist/reads/read-limit-fills.d.ts

@@ -0,0 +1,4 @@
+import type { LimitFill } from '@boxxy/model';
+import type { Kysely } from 'kysely';
+import type { StoreDatabase } from '../types.ts';
+export declare function readLimitFills(db: Kysely<StoreDatabase>): Promise<LimitFill[]>;

package/dist/reads/read-wakes.d.ts

@@ -0,0 +1,4 @@
+import type { Wake } from '@boxxy/model';
+import type { Kysely } from 'kysely';
+import type { StoreDatabase } from '../types.ts';
+export declare function readWakes(db: Kysely<StoreDatabase>): Promise<Wake[]>;

package/dist/test-utils/create-claim-bench.d.ts

@@ -0,0 +1,8 @@
+import type { ItemId } from '@boxxy/model';
+export interface ClaimBenchOptions {
+    readonly itemCount: number;
+}
+export interface ClaimBench extends AsyncDisposable {
+    readonly claim: () => Promise<ItemId>;
+}
+export declare function createClaimBench(options: ClaimBenchOptions): Promise<ClaimBench>;

package/dist/test-utils/create-test-claim-store.d.ts

@@ -0,0 +1,2 @@
+import type { SQLiteClaimStore } from '../create-sqlite-claim-store.ts';
+export declare function createTestClaimStore(): Promise<SQLiteClaimStore>;

package/dist/types.d.ts

@@ -0,0 +1,172 @@
+import type { Generated } from 'kysely';
+export interface StoreDatabase {
+    items: {
+        id: string;
+        kind: string;
+        repo: string;
+        title: string;
+        outcome: string;
+        acceptance: string;
+        fields: string;
+        labels: string;
+        found_in_attempt: string | null;
+        filed_by: string;
+        filed_at: number;
+        closed_at: number | null;
+        close_reason: string | null;
+        kept_session: string | null;
+    };
+    relations: {
+        source: string;
+        target: string;
+        type: string;
+        added_by: string;
+        added_at: number;
+        removed_at: number | null;
+    };
+    levers: {
+        seq: number;
+        kind: string;
+        item: string;
+        until: number | null;
+        expires_at: number | null;
+        reason: string | null;
+        phase: string | null;
+        actor: string;
+        at: number;
+    };
+    attempts: {
+        id: string;
+        item: string;
+        phase: string;
+        number: number;
+        runner: string;
+        recipe_hash: string;
+        rules_version: string;
+        pool: string;
+        lease_gen: number;
+        spawn_request: string;
+        spawn_request_hash: string;
+        state: string;
+        failure: string | null;
+        atc_session: string | null;
+        caller: string | null;
+        claimed_at: number;
+        started_at: number | null;
+        ended_at: number | null;
+        fields: string;
+        mode: string;
+        round: number;
+        input: string | null;
+        hold_gen: number;
+        close_out: string | null;
+        close_out_hash: string | null;
+        close_out_fact: string | null;
+        closing: string | null;
+        closing_at: number | null;
+        suspend_requested_at: number | null;
+        slept_at: number | null;
+        wake_requested_at: number | null;
+        woken_at: number | null;
+        outcome: string | null;
+        returned_outcome: string | null;
+        strayed_at: number | null;
+        session_stopped_at: number | null;
+        session_forgotten_at: number | null;
+    };
+    attempt_sessions: {
+        attempt: string;
+        agent_session: string;
+        atc_session: string;
+        product: string;
+        source: string;
+        seen_at: number;
+    };
+    leases: {
+        item: string;
+        phase: string;
+        attempt: string;
+        gen: number;
+        taken_at: number;
+        released_at: number | null;
+    };
+    limits: {
+        name: string;
+        max: number;
+        counts: string;
+    };
+    limit_seats: {
+        limit: string;
+        attempt: string;
+        hold_gen: number;
+        over_cap: number;
+        taken_at: number;
+        released_at: number | null;
+    };
+    decisions: {
+        id: string;
+        attempt: string;
+        item: string;
+        kind: string;
+        pool: string;
+        rules_version: string;
+        snapshot_hash: string;
+        store_version: number;
+        pepys_offsets: string;
+        faults: string;
+        limits: string;
+        at: number;
+    };
+    evidence: {
+        fact_id: string;
+        attempt: string;
+        kind: string;
+        ref: string;
+        observed: string | null;
+        source: string;
+        at: number;
+    };
+    pull_requests: {
+        repo: string;
+        number: number;
+        attempt: string;
+        github_id: number;
+        url: string;
+        state: string;
+        merged_at: number | null;
+        merge_commit: string | null;
+        checked_at: number;
+    };
+    runners: {
+        id: string;
+        heartbeat_at: number;
+        paused: number;
+    };
+    notes: {
+        item: string;
+        seq: number;
+        text: string;
+        by: string;
+        at: number;
+    };
+    notices: {
+        id: Generated<number>;
+        item: string;
+        reason: string;
+        at: number;
+        tries: number;
+        sent_at: number | null;
+    };
+    outbox: {
+        seq: Generated<number>;
+        fact_id: string;
+        type: string;
+        entity: string;
+        actor: string;
+        at: number;
+        payload: string;
+        sent_at: number | null;
+        parked_at: number | null;
+        parked_reason: string | null;
+    };
+}

package/dist/with-busy-retry.d.ts

@@ -0,0 +1 @@
+export declare function withBusyRetry(waitLimitMs: number, work: () => unknown): Promise<void>;

package/dist/with-transaction.d.ts

@@ -0,0 +1,3 @@
+import type { Kysely } from 'kysely';
+import type { StoreDatabase } from './types.ts';
+export declare function withTransaction<T>(db: Kysely<StoreDatabase>, begin: (db: Kysely<StoreDatabase>) => Promise<unknown>, work: () => Promise<T>): Promise<T>;

package/dist/writes/apply-sqlite-change.d.ts

@@ -0,0 +1,4 @@
+import type { ApplyResult, StoreChange } from '@boxxy/model';
+import type { Kysely } from 'kysely';
+import type { StoreDatabase } from '../types.ts';
+export declare function applySQLiteChange(db: Kysely<StoreDatabase>, change: StoreChange): Promise<ApplyResult>;

package/dist/writes/create-sqlite-tx.d.ts

@@ -0,0 +1,4 @@
+import type { StoreTx } from '@boxxy/model';
+import type { Kysely } from 'kysely';
+import type { StoreDatabase } from '../types.ts';
+export declare function createSQLiteTx(db: Kysely<StoreDatabase>): StoreTx;

package/dist/writes/take-write-lock.d.ts

@@ -0,0 +1,3 @@
+import type { Kysely } from 'kysely';
+import type { StoreDatabase } from '../types.ts';
+export declare function takeWriteLock(db: Kysely<StoreDatabase>, waitLimitMs: number): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxxy/store-sqlite",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "boxxy's store on SQLite",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/adapters/store-sqlite#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
@@ -26,9 +26,23 @@
     "access": "public"
   },
   "scripts": {
+    "bench": "rig bench",
     "build": "rm -rf dist && tsrs -p tsconfig.build.json",
     "typecheck": "tsrs --noEmit"
   },
+  "dependencies": {
+    "@boxxy/content-hash": "0.1.3",
+    "@boxxy/model": "0.1.3",
+    "@zgeoff/kysely-bun-sqlite": "0.3.2",
+    "kysely": "0.29.8",
+    "tiny-invariant": "1.3.3",
+    "ts-pattern": "5.9.2",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@boxxy/dispatch": "0.1.3",
+    "@zgeoff/rig": "0.2.3"
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=24"

package/src/codecs/parse-json-text.ts

@@ -0,0 +1,5 @@
+export function parseJSONText(text: string): unknown {
+  const parsed: unknown = JSON.parse(text);
+
+  return parsed;
+}

package/src/codecs/parse-store-row.ts

@@ -0,0 +1,36 @@
+import { rowSchemas } from '@boxxy/model';
+import type { TableName, Tables } from '@boxxy/model';
+import { tableCodecs } from './table-codecs.ts';
+import { toColumnName } from './to-column-name.ts';
+
+export function parseStoreRow<T extends TableName>(table: T, record: object): Tables[T] {
+  const codec = tableCodecs[table];
+
+  const columns = new Map<string, unknown>(Object.entries(record));
+  const json = new Set<string>(codec.json);
+  const flags = new Set<string>(codec.flags);
+
+  const fields = Object.fromEntries(
+    codec.fields.map((field) => {
+      const value = columns.get(toColumnName(field));
+
+      return [field, parseStoreValue(value, json.has(field), flags.has(field))];
+    }),
+  );
+
+  return rowSchemas[table].parse(fields);
+}
+
+function parseStoreValue(value: unknown, isJSON: boolean, isFlag: boolean): unknown {
+  if (isJSON && typeof value === 'string') {
+    const parsed: unknown = JSON.parse(value);
+
+    return parsed;
+  }
+
+  if (isFlag) {
+    return value === 1;
+  }
+
+  return value;
+}

package/src/codecs/table-codecs.ts

@@ -0,0 +1,148 @@
+import type { TableName, Tables } from '@boxxy/model';
+
+interface TableCodec<Row> {
+  readonly fields: readonly (keyof Row & string)[];
+
+  readonly json: readonly (keyof Row & string)[];
+
+  readonly flags: readonly (keyof Row & string)[];
+}
+
+export const tableCodecs: { readonly [T in TableName]: TableCodec<Tables[T]> } = {
+  items: {
+    fields: [
+      'id',
+      'kind',
+      'repo',
+      'title',
+      'outcome',
+      'acceptance',
+      'fields',
+      'labels',
+      'foundInAttempt',
+      'filedBy',
+      'filedAt',
+      'closedAt',
+      'closeReason',
+      'keptSession',
+    ],
+    json: ['acceptance', 'fields', 'labels', 'keptSession'],
+    flags: [],
+  },
+  relations: {
+    fields: ['source', 'target', 'type', 'addedBy', 'addedAt', 'removedAt'],
+    json: [],
+    flags: [],
+  },
+  levers: {
+    fields: ['seq', 'kind', 'item', 'until', 'expiresAt', 'reason', 'phase', 'actor', 'at'],
+    json: [],
+    flags: [],
+  },
+  attempts: {
+    fields: [
+      'id',
+      'item',
+      'phase',
+      'number',
+      'runner',
+      'recipeHash',
+      'rulesVersion',
+      'pool',
+      'leaseGen',
+      'spawnRequest',
+      'spawnRequestHash',
+      'state',
+      'failure',
+      'atcSession',
+      'caller',
+      'claimedAt',
+      'startedAt',
+      'endedAt',
+      'fields',
+      'mode',
+      'round',
+      'input',
+      'holdGen',
+      'closeOut',
+      'closeOutHash',
+      'closeOutFact',
+      'closing',
+      'closingAt',
+      'suspendRequestedAt',
+      'sleptAt',
+      'wakeRequestedAt',
+      'wokenAt',
+      'outcome',
+      'returnedOutcome',
+      'strayedAt',
+      'sessionStoppedAt',
+      'sessionForgottenAt',
+    ],
+    json: ['spawnRequest', 'caller', 'fields', 'input', 'closeOut'],
+    flags: [],
+  },
+  attempt_sessions: {
+    fields: ['attempt', 'agentSession', 'atcSession', 'product', 'source', 'seenAt'],
+    json: [],
+    flags: [],
+  },
+  leases: {
+    fields: ['item', 'phase', 'attempt', 'gen', 'takenAt', 'releasedAt'],
+    json: [],
+    flags: [],
+  },
+  decisions: {
+    fields: [
+      'id',
+      'attempt',
+      'item',
+      'kind',
+      'pool',
+      'rulesVersion',
+      'snapshotHash',
+      'storeVersion',
+      'pepysOffsets',
+      'faults',
+      'limits',
+      'at',
+    ],
+    json: ['pepysOffsets', 'faults', 'limits'],
+    flags: [],
+  },
+  evidence: {
+    fields: ['factId', 'attempt', 'kind', 'ref', 'observed', 'source', 'at'],
+    json: [],
+    flags: [],
+  },
+  pull_requests: {
+    fields: [
+      'repo',
+      'number',
+      'attempt',
+      'githubId',
+      'url',
+      'state',
+      'mergedAt',
+      'mergeCommit',
+      'checkedAt',
+    ],
+    json: [],
+    flags: [],
+  },
+  runners: {
+    fields: ['id', 'heartbeatAt', 'paused'],
+    json: [],
+    flags: ['paused'],
+  },
+  notes: {
+    fields: ['item', 'seq', 'text', 'by', 'at'],
+    json: [],
+    flags: [],
+  },
+  notices: {
+    fields: ['id', 'item', 'reason', 'at', 'tries', 'sentAt'],
+    json: [],
+    flags: [],
+  },
+};

package/src/codecs/to-column-name.ts

@@ -0,0 +1,3 @@
+export function toColumnName(field: string): string {
+  return field.replaceAll(/[A-Z]/gu, (letter) => `_${letter.toLowerCase()}`);
+}

package/src/codecs/to-store-columns.ts

@@ -0,0 +1,44 @@
+import { formatCanonicalJson } from '@boxxy/content-hash';
+import { toJSONValue } from '@boxxy/model';
+import type { TableName } from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { tableCodecs } from './table-codecs.ts';
+import { toColumnName } from './to-column-name.ts';
+
+export type StoreValue = string | number | null;
+
+// a field outside the table's codec fails, so no caller's key reaches the SQL as a column name
+export function toStoreColumns(table: TableName, fields: object): [string, StoreValue][] {
+  const codec = tableCodecs[table];
+
+  const known = new Set<string>(codec.fields);
+  const json = new Set<string>(codec.json);
+
+  return Object.entries(fields).map(([field, value]: [string, unknown]) => {
+    invariant(known.has(field), `${table} has no field ${field}`);
+
+    return [toColumnName(field), toStoreValue(value, json.has(field))];
+  });
+}
+
+function toStoreValue(value: unknown, isJSON: boolean): StoreValue {
+  if (value === null) {
+    return null;
+  }
+
+  if (isJSON) {
+    // an update compares the stored text, so two objects with their keys in another order match
+    return formatCanonicalJson(toJSONValue(value));
+  }
+
+  if (typeof value === 'boolean') {
+    return value ? 1 : 0;
+  }
+
+  invariant(
+    typeof value === 'string' || typeof value === 'number',
+    `a ${typeof value} needs a JSON column`,
+  );
+
+  return value;
+}

package/src/constants.ts

@@ -0,0 +1 @@
+export const lockWaitLimitMs = 5000;