@byok-sdk/server 0.24.0 → 0.25.0-rc.1

package/README.md

@@ -15,7 +15,6 @@ const task = await server.dispatch({
   deviceId,
   instruction: 'Find five qualified prospects and draft follow-ups.',
   runtime: 'claude',
-  policy: { mode: 'auto' },
   requiredToolsets: ['salesko.prospecting'],
 });
 ```
@@ -59,6 +58,16 @@ explicit adoption. An already-open old writer is not stopped by the version fenc
 Preserve rejected databases for separate reconciliation; do not delete history,
 reset cursors or edit version markers to make adoption pass.
 
+Every refusal at open is a `SqliteSchemaError` with `foundVersion` and
+`requiredVersion`, so a host can check the file at startup and branch on `code`:
+
+- `SQLITE_SCHEMA_UNSUPPORTED`: the file needs an explicit `migration` selector
+  (older version) or a newer build (newer version).
+- `SQLITE_MIGRATION_REFUSED`: the selected migration would lose history;
+  preserve the file.
+- `SQLITE_SCHEMA_INVALID`: the file contradicts its declared schema or is not a
+  BYOK database.
+
 ```ts
 const server = createByokServer({
   productId,

package/dist/index.d.ts

@@ -35,7 +35,8 @@ export type { AccessTokenClaims, DeviceRecord, PairingCodeInfo, TenantId, TokenS
 export { createHmacTokenSigner } from '@byok-sdk/cloud';
 /** Cutoffs and result of {@link ByokServer.mailbox.collectRetired}, owned by `@byok-sdk/core`. */
 export type { MailboxRetentionInput, MailboxRetentionResult } from '@byok-sdk/core';
-export { SqliteUnavailableError } from './sqlite-support';
+export { SqliteSchemaError, SqliteUnavailableError } from './sqlite-support';
+export type { SqliteSchemaErrorCode } from './sqlite-support';
 export type { RateLimiterOptions } from './rate-limiter';
 export { DEFAULT_TASK_EVENT_BUFFER_LIMIT, DEFAULT_TASK_EVENT_RETENTION_MS } from './relay';
 /** Page size `tasks.list()` uses when the caller names none. */

package/dist/index.js

@@ -654,6 +654,20 @@ var SqliteUnavailableError = class extends Error {
     this.cause = cause;
   }
 };
+var SqliteSchemaError = class extends Error {
+  code;
+  /** The stored `schema_version`; `undefined` when the file has none. */
+  foundVersion;
+  /** The schema version this build writes. */
+  requiredVersion;
+  constructor(code, message, foundVersion, requiredVersion, options) {
+    super(message, options);
+    this.name = "SqliteSchemaError";
+    this.code = code;
+    this.foundVersion = foundVersion;
+    this.requiredVersion = requiredVersion;
+  }
+};
 var MIN_NODE_MAJOR = 22;
 var MIN_NODE_MINOR = 5;
 function isSqliteCapableNodeVersion(nodeVersion) {
@@ -982,14 +996,24 @@ var SqliteCoordinator = class {
   #closePromise;
   constructor(path, migration) {
     this.db = openSqliteDatabase(path);
+    let foundVersion;
+    const schemaError = (code, message, options) => new SqliteSchemaError(code, message, foundVersion, SQLITE_SCHEMA_VERSION, options);
+    const assertProjection = (projection) => {
+      try {
+        this.db.prepare(`SELECT ${projection} LIMIT 0`);
+      } catch (error) {
+        throw schemaError("SQLITE_SCHEMA_INVALID", `Missing BYOK SQLite durable authority: SELECT ${projection}`, { cause: error });
+      }
+    };
     try {
       this.db.exec("BEGIN IMMEDIATE");
       try {
         const hasMetadata = this.db.prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = 'byok_sqlite_meta'").get();
         if (hasMetadata !== void 0) {
           const version = this.db.prepare("SELECT value FROM byok_sqlite_meta WHERE key = 'schema_version'").get();
+          foundVersion = version?.value;
           if (version?.value !== SQLITE_SCHEMA_VERSION && !(version?.value === "1" && migration === "v1-to-v4" || version?.value === "2" && migration === "v2-to-v4" || version?.value === "3" && migration === "v3-to-v4")) {
-            throw new Error(`Unsupported BYOK SQLite schema version ${JSON.stringify(version?.value)}; this build requires ${SQLITE_SCHEMA_VERSION}. Stop all writers, back up the database and explicitly select migration: 'v1-to-v4' or 'v2-to-v4' for a receipt-free legacy database without task history, or 'v3-to-v4' for a database without ambiguous claimed identity. Target-v3 migration selectors are no longer supported.`);
+            throw schemaError("SQLITE_SCHEMA_UNSUPPORTED", `Unsupported BYOK SQLite schema version ${JSON.stringify(version?.value)}; this build requires ${SQLITE_SCHEMA_VERSION}. Stop all writers, back up the database and explicitly select migration: 'v1-to-v4' or 'v2-to-v4' for a receipt-free legacy database without task history, or 'v3-to-v4' for a database without ambiguous claimed identity. Target-v3 migration selectors are no longer supported.`);
           }
           for (const projection of [
             "tenant_id, device_id, next_seq, delivered_seq, acked_seq, updated_at FROM mailbox_cursor",
@@ -1000,48 +1024,48 @@ var SqliteCoordinator = class {
             "tenant_id, hash, ref_kind, ref_id, created_at FROM object_reference",
             "blob_id, tenant_id, reservation_id, content_hash, byte_size, content_type, uploaded, data FROM blob"
           ]) {
-            this.db.prepare(`SELECT ${projection} LIMIT 0`);
+            assertProjection(projection);
           }
           if (version?.value === "1" || version?.value === "2") {
             for (const table of ["task_attempt", "mailbox_message", "agent_message_admission"]) {
               if (this.db.prepare(`SELECT 1 FROM ${table} LIMIT 1`).get() !== void 0) {
-                throw new Error("Cannot migrate BYOK SQLite database with task history: historical receipts are unavailable; preserve this database for reconciliation");
+                throw schemaError("SQLITE_MIGRATION_REFUSED", "Cannot migrate BYOK SQLite database with task history: historical receipts are unavailable; preserve this database for reconciliation");
               }
             }
             if (this.db.prepare("SELECT 1 FROM mailbox_cursor WHERE next_seq <> 1 OR delivered_seq <> 0 OR acked_seq <> 0 LIMIT 1").get() !== void 0) {
-              throw new Error("Cannot migrate BYOK SQLite database with delivery history: historical receipts are unavailable; preserve this database for reconciliation");
+              throw schemaError("SQLITE_MIGRATION_REFUSED", "Cannot migrate BYOK SQLite database with delivery history: historical receipts are unavailable; preserve this database for reconciliation");
             }
             if (this.db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'request_receipt'").get() !== void 0) {
-              throw new Error("Unexpected request receipt authority in legacy BYOK SQLite schema");
+              throw schemaError("SQLITE_SCHEMA_INVALID", "Unexpected request receipt authority in legacy BYOK SQLite schema");
             }
             this.db.exec(RECEIPT_SCHEMA);
           }
           if (version?.value === "1") {
             const unexpected = this.db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'device_directory'").get();
-            if (unexpected !== void 0) throw new Error("Unexpected device directory in BYOK SQLite schema v1");
+            if (unexpected !== void 0) throw schemaError("SQLITE_SCHEMA_INVALID", "Unexpected device directory in BYOK SQLite schema v1");
             this.db.exec(DEVICE_SCHEMA);
           }
           if (version?.value !== SQLITE_SCHEMA_VERSION) {
             if (this.db.prepare("SELECT 1 FROM task_attempt WHERE owner_device_id IS NOT NULL AND claimed_runtime IS NULL LIMIT 1").get() !== void 0) {
-              throw new Error("Cannot migrate BYOK SQLite database with ambiguous claimed identity: historical harness identities are unavailable; preserve this database for reconciliation");
+              throw schemaError("SQLITE_MIGRATION_REFUSED", "Cannot migrate BYOK SQLite database with ambiguous claimed identity: historical harness identities are unavailable; preserve this database for reconciliation");
             }
             this.db.exec("ALTER TABLE task_attempt ADD COLUMN claimed_harness_id TEXT");
             this.db.prepare("UPDATE byok_sqlite_meta SET value = ? WHERE key = 'schema_version'").run(SQLITE_SCHEMA_VERSION);
           }
         } else {
           const existing = this.db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").get();
-          if (existing !== void 0) throw new Error("Existing SQLite database has no BYOK schema metadata");
+          if (existing !== void 0) throw schemaError("SQLITE_SCHEMA_INVALID", "Existing SQLite database has no BYOK schema metadata");
           this.db.exec(SCHEMA);
           this.db.exec(RECEIPT_SCHEMA);
           this.db.exec(DEVICE_SCHEMA);
           this.db.prepare("INSERT INTO byok_sqlite_meta (key, value) VALUES ('schema_version', ?)").run(SQLITE_SCHEMA_VERSION);
         }
-        this.db.prepare("SELECT claimed_harness_id FROM task_attempt LIMIT 0");
-        this.db.prepare("SELECT tenant_id, device_id, product_id, machine_id, device_name, device_public_key, proof_key_id, proof_key_epoch, capabilities_json, harnesses_json FROM device_directory LIMIT 0");
+        assertProjection("claimed_harness_id FROM task_attempt");
+        assertProjection("tenant_id, device_id, product_id, machine_id, device_name, device_public_key, proof_key_id, proof_key_epoch, capabilities_json, harnesses_json FROM device_directory");
         const receiptColumns = this.db.prepare("PRAGMA table_info(request_receipt)").all();
         const expectedColumns = ["tenant_id", "key", "body", "recorded_at"];
         if (receiptColumns.length !== expectedColumns.length || receiptColumns.some((column, index) => column.name !== expectedColumns[index] || column.type !== "TEXT" || column.notnull !== 1 || column.pk !== (index < 2 ? index + 1 : 0))) {
-          throw new Error("Invalid BYOK SQLite request receipt schema");
+          throw schemaError("SQLITE_SCHEMA_INVALID", "Invalid BYOK SQLite request receipt schema");
         }
         this.db.exec("COMMIT");
       } catch (error) {
@@ -2180,12 +2204,10 @@ function createByokServer(opts) {
         `device ${deviceId} advertises strict-agent-only; legacy task dispatch is refused before enqueue`
       );
     }
-    const policy = input.policy ?? { mode: "confirm" };
     const runtime = dispatchSelection?.runtimeId ?? input.runtime;
     const common = {
       ...input.harnessId === void 0 ? {} : { harnessId: input.harnessId },
       instruction: input.instruction,
-      policy,
       ...runtime === void 0 ? {} : { runtime },
       ...dispatchSelection === void 0 ? {} : { dispatchSelection }
     };
@@ -2453,6 +2475,6 @@ function longPollInterval(holdMs) {
   return Math.max(MIN_LONG_POLL_INTERVAL_MS, Math.min(MAX_LONG_POLL_INTERVAL_MS, derived));
 }
 
-export { DEFAULT_TASK_EVENT_BUFFER_LIMIT, DEFAULT_TASK_EVENT_RETENTION_MS, DEFAULT_TASK_PAGE_LIMIT, SqliteUnavailableError, SteerRejectedError, createByokServer };
+export { DEFAULT_TASK_EVENT_BUFFER_LIMIT, DEFAULT_TASK_EVENT_RETENTION_MS, DEFAULT_TASK_PAGE_LIMIT, SqliteSchemaError, SqliteUnavailableError, SteerRejectedError, createByokServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map