payment-kit 1.29.1 → 1.29.3

package/api/src/store/models/tax-rate.ts

@@ -1,7 +1,8 @@
 /* eslint-disable @typescript-eslint/lines-between-class-members */
-import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model } from 'sequelize';
-
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes } from 'sequelize';
 import { BN } from '@ocap/util';
+import { TenantModel } from '../tenant-model';
+import { getInstanceDid } from '../../libs/context';
 
 import { createIdGenerator } from '../../libs/util';
 import logger from '../../libs/logger';
@@ -9,9 +10,10 @@ import logger from '../../libs/logger';
 const nextTaxRateId = createIdGenerator('txr', 16);
 
 // eslint-disable-next-line prettier/prettier
-export class TaxRate extends Model<InferAttributes<TaxRate>, InferCreationAttributes<TaxRate>> {
+export class TaxRate extends TenantModel<InferAttributes<TaxRate>, InferCreationAttributes<TaxRate>> {
   declare id: CreationOptional<string>;
   declare livemode: boolean;
+  declare instance_did?: string; // tenant column (Phase 1, W1-1a), nullable until Phase 2 backfill; scoped queries land in Phase 3
   declare active: boolean;
 
   declare country: string; // ISO 3166-1 alpha-2 country code
@@ -89,24 +91,30 @@ export class TaxRate extends Model<InferAttributes<TaxRate>, InferCreationAttrib
   };
 
   public static initialize(sequelize: any) {
-    this.init(TaxRate.GENESIS_ATTRIBUTES, {
-      sequelize,
-      modelName: 'TaxRate',
-      tableName: 'tax_rates',
-      createdAt: 'created_at',
-      updatedAt: 'updated_at',
-      indexes: [
-        {
-          fields: ['country'],
-        },
-        {
-          fields: ['country', 'state'],
-        },
-        {
-          fields: ['country', 'state', 'postal_code'],
-        },
-      ],
-    });
+    this.init(
+      {
+        ...TaxRate.GENESIS_ATTRIBUTES,
+        instance_did: { type: DataTypes.STRING(64), allowNull: true, defaultValue: () => getInstanceDid() },
+      },
+      {
+        sequelize,
+        modelName: 'TaxRate',
+        tableName: 'tax_rates',
+        createdAt: 'created_at',
+        updatedAt: 'updated_at',
+        indexes: [
+          {
+            fields: ['country'],
+          },
+          {
+            fields: ['country', 'state'],
+          },
+          {
+            fields: ['country', 'state', 'postal_code'],
+          },
+        ],
+      }
+    );
   }
 
   public static associate() {}

package/api/src/store/models/usage-record.ts

@@ -1,15 +1,18 @@
-import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model, Op } from 'sequelize';
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Op } from 'sequelize';
 import type { LiteralUnion } from 'type-fest';
+import { TenantModel } from '../tenant-model';
+import { getInstanceDid } from '../../libs/context';
 
 import { createIdGenerator } from '../../libs/util';
 
 const nextId = createIdGenerator('mbur', 24);
 
 // eslint-disable-next-line prettier/prettier
-export class UsageRecord extends Model<InferAttributes<UsageRecord>, InferCreationAttributes<UsageRecord>> {
+export class UsageRecord extends TenantModel<InferAttributes<UsageRecord>, InferCreationAttributes<UsageRecord>> {
   declare id: CreationOptional<string>;
 
   declare livemode: boolean;
+  declare instance_did?: string; // tenant column (Phase 1, W1-1a), nullable until Phase 2 backfill; scoped queries land in Phase 3
   declare billed: boolean;
 
   // The timestamp when this usage occurred.
@@ -72,6 +75,12 @@ export class UsageRecord extends Model<InferAttributes<UsageRecord>, InferCreati
     this.init(
       {
         ...UsageRecord.GENESIS_ATTRIBUTES,
+        instance_did: {
+          type: DataTypes.STRING(64),
+          allowNull: true,
+          // bare creates must still land in the active tenant (single mode = app DID)
+          defaultValue: () => getInstanceDid(),
+        },
         billed: {
           type: DataTypes.BOOLEAN,
           defaultValue: false,

package/api/src/store/models/webhook-attempt.ts

@@ -1,14 +1,17 @@
-import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model } from 'sequelize';
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes } from 'sequelize';
 import type { LiteralUnion } from 'type-fest';
+import { TenantModel } from '../tenant-model';
+import { getInstanceDid } from '../../libs/context';
 
 import { createIdGenerator } from '../../libs/util';
 
 const nextId = createIdGenerator('wa', 24);
 
 // eslint-disable-next-line prettier/prettier
-export class WebhookAttempt extends Model<InferAttributes<WebhookAttempt>, InferCreationAttributes<WebhookAttempt>> {
+export class WebhookAttempt extends TenantModel<InferAttributes<WebhookAttempt>, InferCreationAttributes<WebhookAttempt>> {
   declare id: CreationOptional<string>;
   declare livemode: boolean;
+  declare instance_did?: string; // tenant column (Phase 1, W1-1a), nullable until Phase 2 backfill; scoped queries land in Phase 3
 
   declare event_id: string;
   declare webhook_endpoint_id: string;
@@ -70,13 +73,19 @@ export class WebhookAttempt extends Model<InferAttributes<WebhookAttempt>, Infer
   };
 
   public static initialize(sequelize: any) {
-    this.init(WebhookAttempt.GENESIS_ATTRIBUTES, {
-      sequelize,
-      modelName: 'WebhookAttempt',
-      tableName: 'webhook_attempts',
-      createdAt: 'created_at',
-      updatedAt: 'updated_at',
-    });
+    this.init(
+      {
+        ...WebhookAttempt.GENESIS_ATTRIBUTES,
+        instance_did: { type: DataTypes.STRING(64), allowNull: true, defaultValue: () => getInstanceDid() },
+      },
+      {
+        sequelize,
+        modelName: 'WebhookAttempt',
+        tableName: 'webhook_attempts',
+        createdAt: 'created_at',
+        updatedAt: 'updated_at',
+      }
+    );
   }
 
   public static associate(models: any) {

package/api/src/store/models/webhook-endpoint.ts

@@ -1,5 +1,7 @@
-import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes, Model } from 'sequelize';
+import { CreationOptional, DataTypes, InferAttributes, InferCreationAttributes } from 'sequelize';
 import type { LiteralUnion } from 'type-fest';
+import { TenantModel } from '../tenant-model';
+import { getInstanceDid } from '../../libs/context';
 
 import { createIdGenerator } from '../../libs/util';
 import type { EventType } from './types';
@@ -7,9 +9,10 @@ import type { EventType } from './types';
 const nextId = createIdGenerator('we', 24);
 
 // eslint-disable-next-line prettier/prettier
-export class WebhookEndpoint extends Model<InferAttributes<WebhookEndpoint>, InferCreationAttributes<WebhookEndpoint>> {
+export class WebhookEndpoint extends TenantModel<InferAttributes<WebhookEndpoint>, InferCreationAttributes<WebhookEndpoint>> {
   declare id: CreationOptional<string>;
   declare livemode: boolean;
+  declare instance_did?: string; // tenant column (Phase 1, W1-1a), nullable until Phase 2 backfill; scoped queries land in Phase 3
   declare api_version: string;
 
   declare url: string;
@@ -75,13 +78,19 @@ export class WebhookEndpoint extends Model<InferAttributes<WebhookEndpoint>, Inf
   };
 
   public static initialize(sequelize: any) {
-    this.init(WebhookEndpoint.GENESIS_ATTRIBUTES, {
-      sequelize,
-      modelName: 'WebhookEndpoint',
-      tableName: 'webhook_endpoints',
-      createdAt: 'created_at',
-      updatedAt: 'updated_at',
-    });
+    this.init(
+      {
+        ...WebhookEndpoint.GENESIS_ATTRIBUTES,
+        instance_did: { type: DataTypes.STRING(64), allowNull: true, defaultValue: () => getInstanceDid() },
+      },
+      {
+        sequelize,
+        modelName: 'WebhookEndpoint',
+        tableName: 'webhook_endpoints',
+        createdAt: 'created_at',
+        updatedAt: 'updated_at',
+      }
+    );
   }
 
   public static associate(models: any) {

package/api/src/store/scoped-core.ts

@@ -0,0 +1,55 @@
+// Tenant scope primitives — the single source for tenant-scoping logic shared
+// by:
+//   - scoped.ts        (the opt-in scoped*/system* helper functions)
+//   - tenant-model.ts  (the TenantModel base class)
+//
+// Before this module each of those carried its own inline copy of scopeWhere /
+// stampTenant / the tenant-table check (W1′ task 3 de-dup). The semantics are
+// identical and load-bearing, so they live in exactly one place now.
+//
+// IMPORTANT: this module must stay free of Node-only / workerd-only imports so
+// the worker shim engine can import it too (Phase 3 cross-engine assertion).
+// Its only ambient dependency is the request-context ALS in libs/context,
+// which is async_hooks on Node and nodejs_compat on the worker — the same ALS
+// the whole isolation design rides on.
+import { getInstanceDid } from '../libs/context';
+import { TENANT_MISMATCH, TenantError } from '../libs/tenant';
+import { TENANT_TABLES } from './tenant-tables';
+
+const TENANT_TABLE_SET: ReadonlySet<string> = new Set(TENANT_TABLES);
+
+/** Is this table one of the 38 tenant-scoped tables? */
+export function isTenantTable(tableName: string): boolean {
+  return TENANT_TABLE_SET.has(tableName);
+}
+
+/**
+ * Merge the active tenant into a where clause.
+ *
+ * - fail-closed: an explicit caller-provided `where.instance_did` that disagrees
+ *   with the active tenant throws TENANT_MISMATCH — never silently overridden.
+ * - idempotent: an equal `instance_did` is a no-op, so the double injection from
+ *   internal delegation (findByPk -> findOne -> findAll) is absorbed cleanly.
+ */
+export function scopeWhere(where: Record<string, any> | undefined): Record<string, any> {
+  const instanceDid = getInstanceDid();
+  if (where && 'instance_did' in where && where.instance_did !== instanceDid) {
+    throw new TenantError(
+      TENANT_MISMATCH,
+      `explicit where.instance_did (${JSON.stringify(where.instance_did)}) conflicts with the active tenant`
+    );
+  }
+  return { ...where, instance_did: instanceDid };
+}
+
+/**
+ * Stamp the active tenant onto create values. An explicit mismatched tenant is
+ * refused (writes never cross tenants); an equal one is a no-op.
+ */
+export function stampTenant(values: Record<string, any>): Record<string, any> {
+  const instanceDid = getInstanceDid();
+  if (values && 'instance_did' in values && values.instance_did !== instanceDid) {
+    throw new TenantError(TENANT_MISMATCH, 'explicit instance_did conflicts with the active tenant');
+  }
+  return { ...values, instance_did: instanceDid };
+}

package/api/src/store/scoped.ts

@@ -0,0 +1,247 @@
+/* eslint-disable max-classes-per-file */
+import type {
+  Attributes,
+  CountOptions,
+  CreateOptions,
+  DestroyOptions,
+  FindOptions,
+  Model,
+  ModelStatic,
+  Sequelize,
+  UpdateOptions,
+} from 'sequelize';
+
+import { context } from '../libs/context';
+import { INVALID_TENANT_TABLE, TENANT_MISMATCH, TenantError } from '../libs/tenant';
+import { isTenantTable, scopeWhere } from './scoped-core';
+
+// Phase 3 (W1-2): tenant-scoped query wrappers.
+//
+// Explicit wrapper functions (no global sequelize hooks) so every scoped call
+// is visible and auditable at the call site. The CI scanner
+// (scripts/scan-tenant-queries.js) rejects bare findByPk/findOne/findAll/
+// findAndCountAll/sequelize.query on tenant models outside this module;
+// the 38-table list is shared via ./tenant-tables (single source).
+
+export { TENANT_TABLES } from './tenant-tables';
+
+// scopeWhere / isTenantTable now live in ./scoped-core (shared with the
+// TenantModel base class — one copy of the tenant-scoping logic).
+
+function assertTenantModel(model: ModelStatic<any>) {
+  if (!isTenantTable(model.tableName)) {
+    throw new TenantError(
+      INVALID_TENANT_TABLE,
+      `${model.tableName} is not a tenant table — use the model API directly (exempt: jobs/locks/archive/exchange_rate_providers)`
+    );
+  }
+}
+
+// validation errors must surface as rejections (callers use .catch / await),
+// even though the checks themselves are synchronous
+function asAsync<T>(fn: () => Promise<T> | T): Promise<T> {
+  try {
+    return Promise.resolve(fn());
+  } catch (err) {
+    return Promise.reject(err);
+  }
+}
+
+export function scopedFindAll<M extends Model>(
+  model: ModelStatic<M>,
+  options: FindOptions<Attributes<M>> = {}
+): Promise<M[]> {
+  return asAsync(() => {
+    assertTenantModel(model);
+    return model.findAll({ ...options, where: scopeWhere(options.where as any) as any });
+  });
+}
+
+export function scopedFindOne<M extends Model>(
+  model: ModelStatic<M>,
+  options: FindOptions<Attributes<M>> = {}
+): Promise<M | null> {
+  return asAsync(() => {
+    assertTenantModel(model);
+    return model.findOne({ ...options, where: scopeWhere(options.where as any) as any });
+  });
+}
+
+export function scopedFindAndCountAll<M extends Model>(
+  model: ModelStatic<M>,
+  options: FindOptions<Attributes<M>> = {}
+): Promise<{ rows: M[]; count: number }> {
+  return asAsync(() => {
+    assertTenantModel(model);
+    return (model as any).findAndCountAll({ ...options, where: scopeWhere(options.where as any) });
+  });
+}
+
+/**
+ * Primary keys are globally unique, so a bare findByPk could load another
+ * tenant's row. The row is loaded first, then its tenant is enforced:
+ * mismatch -> TENANT_MISMATCH (no data returned, nothing written).
+ */
+export async function scopedFindByPk<M extends Model>(
+  model: ModelStatic<M>,
+  pk: string | number | undefined | null,
+  options: Omit<FindOptions<Attributes<M>>, 'where'> = {}
+): Promise<M | null> {
+  assertTenantModel(model);
+  if (pk === undefined || pk === null) return null;
+  const instanceDid = context.getInstanceDid();
+  const row: any = await model.findByPk(pk as any, options as any);
+  if (!row) return null;
+  if (row.instance_did !== instanceDid) {
+    throw new TenantError(TENANT_MISMATCH, `${model.tableName}#${String(pk)} belongs to another tenant`);
+  }
+  return row;
+}
+
+export function scopedCount<M extends Model>(
+  model: ModelStatic<M>,
+  options: CountOptions<Attributes<M>> = {}
+): Promise<number> {
+  return asAsync(() => {
+    assertTenantModel(model);
+    return model.count({ ...options, where: scopeWhere(options.where as any) as any });
+  });
+}
+
+export function scopedSum<M extends Model>(
+  model: ModelStatic<M>,
+  field: keyof Attributes<M>,
+  options: { where?: Record<string, any> } = {}
+): Promise<number> {
+  return asAsync(() => {
+    assertTenantModel(model);
+    return (model as any).sum(field, { ...options, where: scopeWhere(options.where) });
+  });
+}
+
+export function scopedAggregate<M extends Model>(
+  model: ModelStatic<M>,
+  field: keyof Attributes<M> | '*',
+  aggregateFunction: string,
+  options: { where?: Record<string, any> } = {}
+): Promise<unknown> {
+  return asAsync(() => {
+    assertTenantModel(model);
+    return (model as any).aggregate(field, aggregateFunction, { ...options, where: scopeWhere(options.where) });
+  });
+}
+
+/** Create with the active tenant; an explicit mismatched tenant is refused. */
+export function scopedCreate<M extends Model>(
+  model: ModelStatic<M>,
+  values: Record<string, any>,
+  options?: CreateOptions<Attributes<M>>
+): Promise<M> {
+  return asAsync(() => {
+    assertTenantModel(model);
+    const instanceDid = context.getInstanceDid();
+    if ('instance_did' in values && values.instance_did !== instanceDid) {
+      throw new TenantError(TENANT_MISMATCH, 'explicit instance_did conflicts with the active tenant');
+    }
+    return model.create({ ...values, instance_did: instanceDid } as any, options) as Promise<M>;
+  });
+}
+
+export function scopedUpdate<M extends Model>(
+  model: ModelStatic<M>,
+  values: Record<string, any>,
+  options: UpdateOptions<Attributes<M>>
+): Promise<[affectedCount: number]> {
+  return asAsync(() => {
+    assertTenantModel(model);
+    if ('instance_did' in values) {
+      throw new TenantError(TENANT_MISMATCH, 'instance_did is immutable — rows never change tenant');
+    }
+    return model.update(values as any, { ...options, where: scopeWhere(options.where as any) as any });
+  });
+}
+
+export function scopedDestroy<M extends Model>(
+  model: ModelStatic<M>,
+  options: DestroyOptions<Attributes<M>> = {}
+): Promise<number> {
+  return asAsync(() => {
+    assertTenantModel(model);
+    return model.destroy({ ...options, where: scopeWhere(options.where as any) as any });
+  });
+}
+
+/**
+ * Raw SQL with mandatory tenant binding: the statement must reference
+ * $instance_did (or :instance_did) and the bind value is supplied here from
+ * the context — callers cannot forget or override it.
+ */
+export function scopedQuery(sequelize: Sequelize, sql: string, options: { bind?: Record<string, any> } = {}) {
+  if (!/[$:]instance_did\b/.test(sql)) {
+    throw new TenantError(
+      TENANT_MISMATCH,
+      'raw SQL on tenant tables must bind $instance_did — add it to the WHERE clause or use scopedQuery on a scoped view'
+    );
+  }
+  const instanceDid = context.getInstanceDid();
+  const bind = { ...options.bind, instance_did: instanceDid };
+  return sequelize.query(sql, { ...options, bind });
+}
+
+// ---------------------------------------------------------------------------
+// system* family — EXPLICIT cross-tenant reads for system paths.
+//
+// Queue handlers load rows by globally-unique primary key from a
+// tenant-stamped payload and then enforce row tenant via
+// assertJobObjectTenant (libs/queue); dispatch/recovery sweeps and
+// fanout-by-row-tenant (queues/event.ts) legitimately read across tenants.
+// Naming these calls system* keeps every query auditable: anything not
+// scoped* or system* is a scanner violation.
+// ---------------------------------------------------------------------------
+
+// Each system* call runs inside context.runAsSystem so the TenantModel base
+// class bypasses scoping for the read — otherwise the model's overridden
+// findByPk/findAll/... would re-scope to the active tenant and a legitimate
+// cross-tenant read (queue dispatch, IAP reverse-lookup, fan-out) would resolve
+// to null. The caller still enforces the row's tenant afterwards.
+
+export function systemFindByPk<M extends Model>(
+  model: ModelStatic<M>,
+  pk: string | number | undefined | null,
+  options?: Omit<FindOptions<Attributes<M>>, 'where'>
+): Promise<M | null> {
+  if (pk === undefined || pk === null) return Promise.resolve(null);
+  // forward options only when provided — keeps call shapes identical for
+  // existing spies/assertions on model.findByPk
+  return context.runAsSystem(() =>
+    options ? model.findByPk(pk as any, options as any) : model.findByPk(pk as any)
+  ) as Promise<M | null>;
+}
+
+export function systemFindAll<M extends Model>(
+  model: ModelStatic<M>,
+  options: FindOptions<Attributes<M>> = {}
+): Promise<M[]> {
+  return context.runAsSystem(() => model.findAll(options));
+}
+
+export function systemFindOne<M extends Model>(
+  model: ModelStatic<M>,
+  options: FindOptions<Attributes<M>> = {}
+): Promise<M | null> {
+  return context.runAsSystem(() => model.findOne(options));
+}
+
+export function systemFindAndCountAll<M extends Model>(
+  model: ModelStatic<M>,
+  options: FindOptions<Attributes<M>> = {}
+): Promise<{ rows: M[]; count: number }> {
+  return context.runAsSystem(() => (model as any).findAndCountAll(options));
+}
+
+export function systemCount<M extends Model>(
+  model: ModelStatic<M>,
+  options: CountOptions<Attributes<M>> = {}
+): Promise<number> {
+  return context.runAsSystem(() => model.count(options));
+}

package/api/src/store/sequelize.ts

@@ -6,31 +6,90 @@ import { join } from 'path';
 
 import CLS from 'cls-hooked';
 import { Sequelize } from 'sequelize';
-
-import env, { sequelizeOptionsPoolIdle, sequelizeOptionsPoolMax, sequelizeOptionsPoolMin } from '../libs/env';
+import env, {
+  sqlLog,
+  sqlBenchmark,
+  sequelizeOptionsPoolIdle,
+  sequelizeOptionsPoolMax,
+  sequelizeOptionsPoolMin,
+} from '../libs/env';
 
 const namespace = CLS.createNamespace('payment-kit');
 
 Sequelize.useCLS(namespace);
 
-// eslint-disable-next-line import/prefer-default-export
-export const sequelize = new Sequelize({
-  dialect: 'sqlite',
-  logging: process.env.SQL_LOG === '1',
-  benchmark: process.env.SQL_LOG === '1' && process.env.SQL_BENCHMARK === '1',
-  storage: join(env.dataDir, 'payment-kit.db'),
-  pool: {
-    min: sequelizeOptionsPoolMin,
-    max: sequelizeOptionsPoolMax,
-    idle: sequelizeOptionsPoolIdle,
-  },
-});
-
-// SQLite PRAGMAs — run once at startup on the single reused connection.
-// Note: SQLite in Sequelize reuses a cached connection (connection-manager.js:43-44),
-// so these fire-and-forget calls reliably apply to all subsequent queries.
-sequelize.query('PRAGMA journal_mode = WAL');
-sequelize.query('PRAGMA synchronous = NORMAL');
-sequelize.query('PRAGMA journal_size_limit = 67108864');
-sequelize.query('PRAGMA busy_timeout = 5000');
-sequelize.query('PRAGMA cache_size = -16000'); // 16MB page cache (default ~2MB)
+// Phase 13b: the blocklet-server's default sqlite instance is built from
+// `env.dataDir`, which is absent in a bare host (arc embedding before its blocklet
+// runtime is wired). In that mode the host injects its OWN sequelize via the db
+// slot and this default is never used — so importing the models must not eagerly
+// construct it (it would crash on join(undefined, …)). Construct EAGERLY when a
+// data dir is present (blocklet server: BLOCKLET_DATA_DIR; CF worker: shim '/tmp')
+// so their behavior and hot path are byte-for-byte unchanged — no proxy on the
+// query path, CLS/transaction identity preserved. Otherwise defer behind a proxy
+// that builds on first access (only ever hit by code that uses this default).
+function buildSequelize(): Sequelize {
+  const seq = new Sequelize({
+    dialect: 'sqlite',
+    logging: sqlLog(),
+    benchmark: sqlLog() && sqlBenchmark(),
+    storage: join(env.dataDir, 'payment-kit.db'),
+    pool: {
+      min: sequelizeOptionsPoolMin(),
+      max: sequelizeOptionsPoolMax(),
+      idle: sequelizeOptionsPoolIdle(),
+    },
+  });
+
+  // SQLite PRAGMAs — run once at startup on the single reused connection.
+  // Note: SQLite in Sequelize reuses a cached connection (connection-manager.js:43-44),
+  // so these fire-and-forget calls reliably apply to all subsequent queries.
+  // Failures are non-fatal (pragmas are perf tuning) and must not crash the
+  // process via unhandledRejection, e.g. when jest teardown removes the data dir.
+  const pragma = (sql: string) => seq.query(sql).catch(() => {});
+  pragma('PRAGMA journal_mode = WAL');
+  pragma('PRAGMA synchronous = NORMAL');
+  pragma('PRAGMA journal_size_limit = 67108864');
+  pragma('PRAGMA busy_timeout = 5000');
+  pragma('PRAGMA cache_size = -16000'); // 16MB page cache (default ~2MB)
+
+  return seq;
+}
+
+let instance: Sequelize | undefined;
+const getSequelize = (): Sequelize => {
+  instance ??= buildSequelize();
+  return instance;
+};
+
+/**
+ * Point the default-export `sequelize` at the host-injected instance. In a bare
+ * host (arc embedding, no BLOCKLET_DATA_DIR) the default export is a deferred
+ * Proxy whose `buildSequelize()` would crash on `join(undefined, …)`; the host
+ * binds every model to ITS OWN sequelize via `initialize(slots.db.sequelize)`.
+ * Code that imports this default directly (e.g. `sequelize.models.Product` in
+ * Price.expand) must therefore resolve to that SAME instance — otherwise it
+ * builds the broken default. The factory calls this at the single bind point so
+ * the imported default and the model-bound instance are always one object.
+ * Equivalent to a no-op for blocklet-server/CF, where the default is already the
+ * bind target.
+ */
+export function setDefaultSequelize(seq: Sequelize): void {
+  instance = seq;
+}
+
+export const sequelize: Sequelize = env.dataDir
+  ? getSequelize()
+  : new Proxy({} as Sequelize, {
+      get(_t, prop) {
+        const seq = getSequelize();
+        const value: any = (seq as any)[prop];
+        return typeof value === 'function' ? value.bind(seq) : value;
+      },
+      set(_t, prop, value) {
+        (getSequelize() as any)[prop] = value;
+        return true;
+      },
+      has(_t, prop) {
+        return prop in (getSequelize() as any);
+      },
+    });