@objectstack/service-datasource 10.0.0 → 10.3.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/service-datasource@10.0.0 build /home/runner/work/framework/framework/packages/services/service-datasource
+> @objectstack/service-datasource@10.3.0 build /home/runner/work/framework/framework/packages/services/service-datasource
 > tsup
 
 CLI Building entry: src/index.ts, src/contracts/index.ts
@@ -10,19 +10,31 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.js               45.58 KB
-ESM dist/contracts/index.js     33.00 B
-ESM dist/index.js.map           110.99 KB
-ESM dist/contracts/index.js.map 71.00 B
-ESM ⚡️ Build success in 1186ms
-CJS dist/index.cjs               55.09 KB
-CJS dist/contracts/index.cjs     47.00 B
-CJS dist/index.cjs.map           93.99 KB
-CJS dist/contracts/index.cjs.map 265.00 B
-CJS ⚡️ Build success in 1190ms
+ESM dist/index.js                               52.67 KB
+ESM dist/contracts/index.js                     133.00 B
+ESM dist/chunk-XLS4RP7B.js                      185.00 B
+ESM dist/sqlite-driver-fallback-BPFQYLX7.js     314.00 B
+ESM dist/chunk-JRBGOCRJ.js                      2.96 KB
+ESM dist/index.js.map                           130.13 KB
+ESM dist/contracts/index.js.map                 71.00 B
+ESM dist/chunk-XLS4RP7B.js.map                  3.10 KB
+ESM dist/sqlite-driver-fallback-BPFQYLX7.js.map 71.00 B
+ESM dist/chunk-JRBGOCRJ.js.map                  9.53 KB
+ESM ⚡️ Build success in 938ms
+CJS dist/index.cjs                               64.11 KB
+CJS dist/contracts/index.cjs                     242.00 B
+CJS dist/chunk-BI2SYWLC.cjs                      280.00 B
+CJS dist/sqlite-driver-fallback-JX4XOICD.cjs     473.00 B
+CJS dist/chunk-76HQ74MX.cjs                      4.33 KB
+CJS dist/index.cjs.map                           111.29 KB
+CJS dist/contracts/index.cjs.map                 304.00 B
+CJS dist/chunk-BI2SYWLC.cjs.map                  3.38 KB
+CJS dist/sqlite-driver-fallback-JX4XOICD.cjs.map 356.00 B
+CJS dist/chunk-76HQ74MX.cjs.map                  10.74 KB
+CJS ⚡️ Build success in 1087ms
 DTS Build start
-DTS ⚡️ Build success in 16306ms
-DTS dist/index.d.ts            20.60 KB
-DTS dist/contracts/index.d.ts  8.10 KB
-DTS dist/index.d.cts           20.60 KB
-DTS dist/contracts/index.d.cts 8.10 KB
+DTS ⚡️ Build success in 17422ms
+DTS dist/index.d.ts            33.63 KB
+DTS dist/contracts/index.d.ts  11.03 KB
+DTS dist/index.d.cts           33.63 KB
+DTS dist/contracts/index.d.cts 11.03 KB

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # @objectstack/service-external-datasource
 
+## 10.3.0
+
+### Patch Changes
+
+- f2063f3: fix(cli): extend native better-sqlite3 → wasm SQLite auto-fallback to the persistent-file / `--artifact` dev path (#2229)
+
+  The native-`better-sqlite3` → wasm SQLite → in-memory step-down previously only
+  guarded the zero-config `:memory:` dev branch of `serve`. A normal
+  `objectstack dev` run never reaches it — `dev` injects a persistent `file:` DB
+  (so AI-authored data survives restarts) and `--artifact` boots resolve sqlite
+  through the datasource factory — both of which constructed
+  `better-sqlite3` directly with no probe and no fallback. An ABI mismatch (e.g.
+  a cached prebuilt binary built for a different Node version) was therefore not
+  caught at boot and surfaced later as a runtime `Find operation failed` on the
+  first query.
+
+  The probe-by-connect + step-down is now hoisted into a shared
+  `resolveSqliteDriver` helper (`@objectstack/service-datasource`) and applied to
+  both previously-unguarded sqlite construction sites: the explicit `sqlite` /
+  `file:` branch in `serve.ts` and the sqlite branch of the default datasource
+  driver factory. better-sqlite3 loads its native addon lazily (first query), so
+  the helper forces the load with a `SELECT 1` and, **in dev only**, steps down to
+  wasm SQLite (real SQL + on-disk persistence — the same `file:` keeps working)
+  then to the in-memory driver as a last resort, emitting the existing
+  `⚠ native better-sqlite3 unavailable …` warning. In production the native driver
+  is returned unprobed so a load failure surfaces loudly (fail-closed) rather than
+  silently degrading to a different engine.
+
+  - @objectstack/spec@10.3.0
+  - @objectstack/core@10.3.0
+
+## 10.2.0
+
+### Patch Changes
+
+- Updated dependencies [b496498]
+  - @objectstack/spec@10.2.0
+  - @objectstack/core@10.2.0
+
+## 10.1.0
+
+### Minor Changes
+
+- 49da36e: feat(datasource): fail-closed credential resolution at connect (ADR-0062 Phase 2, D3)
+
+  `DatasourceConnectionService` now treats a declared `external.credentialsRef` as
+  **fail-closed**: the credential must resolve to a cleartext secret (via the
+  host's `SecretBinder` over `ICryptoProvider`) _before_ the driver is built. An
+  absent secret store, or a ref that cannot be resolved/decrypted (missing
+  `sys_secret` row, rotated key, or a throwing resolver), leaves the datasource
+  **unconnected with a clear message** — never a silent build-without-secret that
+  would connect with no/wrong auth or fail later with a confusing driver error.
+
+  The same policy as connect failures applies: a code-defined `external` datasource
+  with `validation.onMismatch: 'fail'` auto-connected at boot fails fast (bricks
+  boot); runtime-admin create/update + boot rehydration degrade-with-warning. Code-
+  and runtime-origin secrets converge on the one connection path (the same
+  `SecretBinder` is threaded through the shared service). New `failed-credentials`
+  connect status.
+
+- ac79f16: feat(datasource): auto-connect declared external datasources (ADR-0062 Phase 1, D1/D2/D5)
+
+  A declared external datasource is now connected to a live ObjectQL driver and its
+  federated objects are queryable **with zero app code** — no `onEnable` driver
+  wiring. Implements ADR-0062 Phase 1.
+
+  - **D1 — one connect path.** New `DatasourceConnectionService` in
+    `@objectstack/service-datasource` owns the single "definition → live driver"
+    path: build via the injected driver factory → resolve `external.credentialsRef`
+    via the `SecretBinder` → connect → `engine.registerDriver` under the datasource
+    name → register the datasource def → sync each bound federated object's read
+    metadata (DDL-free). Both origins converge on it: the runtime-admin
+    `registerPool` now delegates here, and `AppPlugin` auto-connects code-defined
+    datasources. Exposed as the `'datasource-connection'` kernel service.
+  - **D2 — opt-in-safe gate.** A declared datasource auto-connects only when it is
+    `external`, an object **explicitly** binds to it via `object.datasource`, or it
+    sets the new `autoConnect: true` flag. A managed datasource that nothing
+    explicitly binds (incl. ones referenced only by a `datasourceMapping` rule, e.g.
+    `examples/app-crm`'s `:memory:` datasources) stays metadata-only — existing apps
+    are byte-for-byte unchanged. See the ADR-0062 D2 implementation note.
+  - **D5 — lifecycle, ordering & policy.** Connect happens in `AppPlugin.start()`
+    (before the `kernel:ready` validation gate, relying on the kernel's
+    init-all-then-start-all ordering). Fail-fast for a declared `external` datasource
+    with `validation.onMismatch: 'fail'`; degrade-with-warning otherwise (and always
+    for runtime-admin/rehydrate, so a UI action or replica blip never bricks the
+    server). Adds a host-injectable `DatasourceConnectPolicy` (open-core default
+    allows; a multi-tenant host binds a stricter fail-closed policy for egress
+    isolation) consulted before every connect — one connect path, no cloud fork.
+
+  Adds `datasource.autoConnect` to the spec. The legacy `onEnable` +
+  `ctx.drivers.register` bridge remains supported as an escape hatch (idempotent vs.
+  auto-connect). No behavior change for managed apps.
+
+### Patch Changes
+
+- Updated dependencies [49da36e]
+- Updated dependencies [ac79f16]
+  - @objectstack/spec@10.1.0
+  - @objectstack/core@10.1.0
+
 ## 10.0.0
 
 ### Patch Changes

package/dist/chunk-76HQ74MX.cjs

@@ -0,0 +1,82 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/sqlite-driver-fallback.ts
+var NATIVE_SQLITE_WASM_FALLBACK_WARNING = "  \u26A0 native better-sqlite3 unavailable (ABI mismatch or not built) \u2014 dev using wasm SQLite (real SQL, slower).\n    Rebuild better-sqlite3 for native speed, or set OS_DATABASE_DRIVER=sqlite-wasm to silence this.";
+var NATIVE_SQLITE_MEMORY_FALLBACK_WARNING = "  \u26A0 neither native nor wasm SQLite available \u2014 dev falling back to InMemoryDriver (mingo, not real SQL).\n    Rebuild better-sqlite3, or set OS_DATABASE_URL / OS_DATABASE_DRIVER for SQL fidelity.";
+function isEphemeralFilename(filename) {
+  return filename === ":memory:" || filename.startsWith(":");
+}
+async function resolveSqliteDriver(opts) {
+  const { filename } = opts;
+  const dev = _nullishCoalesce(opts.dev, () => ( process.env.NODE_ENV === "development"));
+  const warn = _nullishCoalesce(opts.warn, () => ( ((message) => {
+    try {
+      console.warn(message);
+    } catch (e) {
+    }
+  })));
+  const { SqlDriver } = await Promise.resolve().then(() => _interopRequireWildcard(require("@objectstack/driver-sql")));
+  const buildNative = () => new SqlDriver({
+    client: "better-sqlite3",
+    connection: { filename },
+    useNullAsDefault: true,
+    ...opts.autoMigrate ? { autoMigrate: opts.autoMigrate } : {},
+    ...opts.schemaMode ? { schemaMode: opts.schemaMode } : {}
+  });
+  if (!dev) {
+    return { driver: buildNative(), engine: "better-sqlite3", label: "SqlDriver(sqlite)" };
+  }
+  let nativeDriver;
+  let nativeOk = false;
+  try {
+    nativeDriver = buildNative();
+    await nativeDriver.connect();
+    await nativeDriver.execute("SELECT 1");
+    nativeOk = true;
+  } catch (e2) {
+    nativeOk = false;
+    if (typeof _optionalChain([nativeDriver, 'optionalAccess', _ => _.disconnect]) === "function") {
+      try {
+        await nativeDriver.disconnect();
+      } catch (e3) {
+      }
+    }
+  }
+  if (nativeOk) {
+    return { driver: nativeDriver, engine: "better-sqlite3", label: "SqlDriver(sqlite)" };
+  }
+  let wasmDriver;
+  let wasmOk = false;
+  try {
+    const { SqliteWasmDriver } = await Promise.resolve().then(() => _interopRequireWildcard(require("@objectstack/driver-sqlite-wasm")));
+    wasmDriver = new SqliteWasmDriver({
+      filename,
+      // Match the existing construction sites: ephemeral DBs flush on
+      // disconnect; a persistent file flushes on every write so AI-authored
+      // data survives an unclean dev-server kill.
+      persist: isEphemeralFilename(filename) ? "on-disconnect" : "on-write"
+    });
+    await wasmDriver.connect();
+    wasmOk = true;
+  } catch (e4) {
+    wasmOk = false;
+    if (typeof _optionalChain([wasmDriver, 'optionalAccess', _2 => _2.disconnect]) === "function") {
+      try {
+        await wasmDriver.disconnect();
+      } catch (e5) {
+      }
+    }
+  }
+  if (wasmOk) {
+    warn(NATIVE_SQLITE_WASM_FALLBACK_WARNING);
+    return { driver: wasmDriver, engine: "sqlite-wasm", label: "SqliteWasmDriver" };
+  }
+  const { InMemoryDriver } = await Promise.resolve().then(() => _interopRequireWildcard(require("@objectstack/driver-memory")));
+  warn(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);
+  return { driver: new InMemoryDriver(), engine: "memory", label: "InMemoryDriver" };
+}
+
+
+
+
+
+exports.NATIVE_SQLITE_WASM_FALLBACK_WARNING = NATIVE_SQLITE_WASM_FALLBACK_WARNING; exports.NATIVE_SQLITE_MEMORY_FALLBACK_WARNING = NATIVE_SQLITE_MEMORY_FALLBACK_WARNING; exports.resolveSqliteDriver = resolveSqliteDriver;
+//# sourceMappingURL=chunk-76HQ74MX.cjs.map

package/dist/chunk-76HQ74MX.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/framework/framework/packages/services/service-datasource/dist/chunk-76HQ74MX.cjs","../src/sqlite-driver-fallback.ts"],"names":[],"mappings":"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","file":"/home/runner/work/framework/framework/packages/services/service-datasource/dist/chunk-76HQ74MX.cjs","sourcesContent":[null,"// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Shared native-`better-sqlite3` → wasm SQLite → in-memory step-down for any\n * sqlite-via-`better-sqlite3` construction (issue #2229).\n *\n * ## Why a probe is necessary\n *\n * `better-sqlite3` loads its native `.node` addon LAZILY — not at\n * `require('better-sqlite3')`, and not even at knex construction, but at the\n * first pool-connection acquire (`new Database(file)`), i.e. the first query.\n * So an ABI mismatch (a cached prebuilt binary built for a different Node\n * version — `NODE_MODULE_VERSION` mismatch) is invisible at boot and only\n * surfaces much later as a runtime `Find operation failed` on the first read.\n *\n * This helper makes the failure observable up-front by actively probing: it\n * opens a connection and runs a cheap `SELECT 1`, which forces the native addon\n * to load. (`connect()` alone is NOT a reliable probe: for SQLite it only runs\n * `mkdir` + a `PRAGMA` whose error is swallowed internally — so we additionally\n * issue a raw `SELECT 1`, which propagates the load error.) On failure it steps\n * down:\n *\n *   1. native `better-sqlite3`  — fast, real SQL\n *   2. wasm SQLite              — pure-JS, real SQL + on-disk persistence, slower   [dev only]\n *   3. in-memory (mingo)        — neither real SQL nor persistent                   [dev only, last resort]\n *\n * ## Dev vs production\n *\n * The wasm + in-memory step-down is GATED to dev. In production a native load\n * failure is NOT silently swapped for a different engine: the error is re-thrown\n * so it surfaces loudly (fail-closed) instead of an operator unknowingly running\n * on wasm/mingo. This mirrors the existing `serve.ts` default-dev fallback and\n * hoists it into one place shared by every sqlite construction site.\n */\n\n/** Which engine the resolver ultimately produced. */\nexport type SqliteFallbackEngine = 'better-sqlite3' | 'sqlite-wasm' | 'memory';\n\nexport interface ResolveSqliteDriverOptions {\n  /**\n   * SQLite filename — `:memory:` for an ephemeral database, or an absolute /\n   * relative path for a persistent file. Preserved across the wasm fallback so\n   * a persistent `file:` database keeps its on-disk persistence through wasm.\n   * Pass the raw filename (callers strip any `file:` / `sqlite:` scheme first).\n   */\n  filename: string;\n  /**\n   * Gates the wasm + in-memory step-down. When `true` (dev) a native ABI/load\n   * failure steps down the chain with a warning. When `false` (production) the\n   * native driver is returned unprobed so a failure surfaces loudly at first use\n   * (fail-closed) — we never silently degrade behind the operator's back.\n   * Defaults to `process.env.NODE_ENV === 'development'`.\n   */\n  dev?: boolean;\n  /** Forwarded to the native SqlDriver (dev loosen-only self-heal, #2186). */\n  autoMigrate?: 'off' | 'safe';\n  /** Forwarded to the SQL drivers (external schema mode, ADR-0015). */\n  schemaMode?: string;\n  /**\n   * Warning sink for the step-down messages. Defaults to `console.warn`.\n   * `serve.ts` passes a `chalk.yellow` wrapper so the banner stays consistent.\n   */\n  warn?: (message: string) => void;\n}\n\nexport interface ResolvedSqliteDriver {\n  /** The concrete engine driver to register (e.g. via `DriverPlugin`). */\n  driver: any;\n  /** Which engine actually resolved. */\n  engine: SqliteFallbackEngine;\n  /** Banner label, matching `serve.ts`'s existing strings. */\n  label: string;\n}\n\n/**\n * Warning emitted when native `better-sqlite3` is unavailable but wasm SQLite\n * loads. Kept byte-for-byte identical to the original `serve.ts` text so the\n * dev experience is the same regardless of which construction site triggers it.\n */\nexport const NATIVE_SQLITE_WASM_FALLBACK_WARNING =\n  '  ⚠ native better-sqlite3 unavailable (ABI mismatch or not built) — dev using wasm SQLite (real SQL, slower).\\n' +\n  '    Rebuild better-sqlite3 for native speed, or set OS_DATABASE_DRIVER=sqlite-wasm to silence this.';\n\n/** Warning emitted when neither native nor wasm SQLite loads (dev last resort). */\nexport const NATIVE_SQLITE_MEMORY_FALLBACK_WARNING =\n  '  ⚠ neither native nor wasm SQLite available — dev falling back to InMemoryDriver (mingo, not real SQL).\\n' +\n  '    Rebuild better-sqlite3, or set OS_DATABASE_URL / OS_DATABASE_DRIVER for SQL fidelity.';\n\n/** `:memory:` and other `:`-prefixed pseudo-filenames are never persisted. */\nfunction isEphemeralFilename(filename: string): boolean {\n  return filename === ':memory:' || filename.startsWith(':');\n}\n\n/**\n * Probe a `better-sqlite3` SQLite construction and, in dev, step down to wasm\n * SQLite (then in-memory) when the native addon cannot load.\n *\n * @see {@link ResolveSqliteDriverOptions}\n */\nexport async function resolveSqliteDriver(\n  opts: ResolveSqliteDriverOptions,\n): Promise<ResolvedSqliteDriver> {\n  const { filename } = opts;\n  const dev = opts.dev ?? process.env.NODE_ENV === 'development';\n  const warn =\n    opts.warn ??\n    ((message: string) => {\n      try {\n        // eslint-disable-next-line no-console\n        console.warn(message);\n      } catch {\n        /* ignore */\n      }\n    });\n\n  const { SqlDriver } = await import('@objectstack/driver-sql');\n\n  const buildNative = () =>\n    new SqlDriver({\n      client: 'better-sqlite3',\n      connection: { filename },\n      useNullAsDefault: true,\n      ...(opts.autoMigrate ? { autoMigrate: opts.autoMigrate } : {}),\n      ...(opts.schemaMode ? { schemaMode: opts.schemaMode } : {}),\n    } as any);\n\n  // Production: never silently swap engines. Construct the native driver and\n  // hand it back UNPROBED — exactly the historical behavior. A native load\n  // failure surfaces loudly at first use (fail-closed).\n  if (!dev) {\n    return { driver: buildNative(), engine: 'better-sqlite3', label: 'SqlDriver(sqlite)' };\n  }\n\n  // ── Dev: probe-by-connect, step down on native ABI/load failure. ──────────\n\n  // 1. Native better-sqlite3.\n  let nativeDriver: any;\n  let nativeOk = false;\n  try {\n    nativeDriver = buildNative();\n    // connect() runs mkdir (so a SELECT on a file DB whose dir is missing does\n    // not false-positive as an ABI failure) + a PRAGMA whose error it swallows;\n    // the raw SELECT 1 below is what reliably forces the native addon to load\n    // and PROPAGATES an ABI mismatch.\n    await nativeDriver.connect();\n    await nativeDriver.execute('SELECT 1');\n    nativeOk = true;\n  } catch {\n    nativeOk = false;\n    if (typeof nativeDriver?.disconnect === 'function') {\n      try {\n        await nativeDriver.disconnect();\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n  if (nativeOk) {\n    return { driver: nativeDriver, engine: 'better-sqlite3', label: 'SqlDriver(sqlite)' };\n  }\n\n  // 2. wasm SQLite — real SQL semantics + on-disk persistence, no native build.\n  let wasmDriver: any;\n  let wasmOk = false;\n  try {\n    const { SqliteWasmDriver } = await import('@objectstack/driver-sqlite-wasm');\n    wasmDriver = new SqliteWasmDriver({\n      filename,\n      // Match the existing construction sites: ephemeral DBs flush on\n      // disconnect; a persistent file flushes on every write so AI-authored\n      // data survives an unclean dev-server kill.\n      persist: isEphemeralFilename(filename) ? 'on-disconnect' : 'on-write',\n    } as any);\n    await wasmDriver.connect();\n    wasmOk = true;\n  } catch {\n    wasmOk = false;\n    if (typeof wasmDriver?.disconnect === 'function') {\n      try {\n        await wasmDriver.disconnect();\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n  if (wasmOk) {\n    warn(NATIVE_SQLITE_WASM_FALLBACK_WARNING);\n    return { driver: wasmDriver, engine: 'sqlite-wasm', label: 'SqliteWasmDriver' };\n  }\n\n  // 3. In-memory (mingo) — dev-only last resort. Not real SQL, not persistent.\n  const { InMemoryDriver } = await import('@objectstack/driver-memory');\n  warn(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);\n  return { driver: new InMemoryDriver(), engine: 'memory', label: 'InMemoryDriver' };\n}\n"]}

package/dist/chunk-BI2SYWLC.cjs

@@ -0,0 +1,9 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/contracts/connect-policy.ts
+var allowAllConnectPolicy = {
+  canConnect: () => ({ allow: true })
+};
+
+
+
+exports.allowAllConnectPolicy = allowAllConnectPolicy;
+//# sourceMappingURL=chunk-BI2SYWLC.cjs.map

package/dist/chunk-BI2SYWLC.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/framework/framework/packages/services/service-datasource/dist/chunk-BI2SYWLC.cjs","../src/contracts/connect-policy.ts"],"names":[],"mappings":"AAAA;ACkEO,IAAM,sBAAA,EAAiD;AAAA,EAC5D,UAAA,EAAY,CAAA,EAAA,GAAA,CAAO,EAAE,KAAA,EAAO,KAAK,CAAA;AACnC,CAAA;ADhEA;AACA;AACE;AACF,sDAAC","file":"/home/runner/work/framework/framework/packages/services/service-datasource/dist/chunk-BI2SYWLC.cjs","sourcesContent":[null,"// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * DatasourceConnectPolicy — host-injectable gate consulted *before*\n * {@link DatasourceConnectionService} builds and registers a live driver\n * (ADR-0062 D1/D5, and the epic #2163 \"connect-policy seam\" note).\n *\n * The framework ships a permissive default ({@link allowAllConnectPolicy}) so a\n * self-hosted single-environment runtime connects external datasources out of\n * the box (subject to the D2 auto-connect gate, which is applied separately by\n * {@link DatasourceConnectionService.connectDeclared}). A multi-tenant host\n * (shared-container cloud) binds a stricter policy that can *fail-close* on the\n * shared runtime — e.g. checking `sys_environment.plan`, an egress allow-list,\n * and per-tenant quota — to enforce SSRF / egress isolation.\n *\n * This keeps a single connect path for code- and runtime-origin datasources\n * (D1): the host injects a policy rather than forking a second connect path.\n * No plan coupling lives in the open framework.\n */\n\n/** Why a connect is being attempted — lets a policy treat origins differently. */\nexport interface DatasourceConnectContext {\n  /** Provenance of the datasource being connected. */\n  origin?: 'code' | 'runtime';\n  /**\n   * What triggered this connect:\n   *  - `declared-auto`  — code-defined datasource auto-connected at boot (D2 gate passed).\n   *  - `runtime-admin`  — UI \"Add/Update Datasource\" hot pool registration.\n   *  - `rehydrate`      — boot rehydration of a persisted runtime datasource.\n   */\n  trigger?: 'declared-auto' | 'runtime-admin' | 'rehydrate';\n}\n\n/** A policy verdict. `allow:false` leaves the datasource unconnected (metadata-only). */\nexport interface DatasourceConnectDecision {\n  allow: boolean;\n  /** Human-readable reason, surfaced in logs when a connect is denied. */\n  reason?: string;\n}\n\n/** The minimal datasource shape a policy inspects (never a secret). */\nexport interface DatasourceConnectSubject {\n  name: string;\n  driver: string;\n  schemaMode?: 'managed' | 'external' | 'validate-only';\n  external?: Record<string, unknown>;\n}\n\n/** Host-provided policy gate consulted before opening a connection. */\nexport interface DatasourceConnectPolicy {\n  /**\n   * Decide whether `ds` may be connected. Sync or async. Throwing is treated\n   * as a denial (fail-closed) by {@link DatasourceConnectionService}.\n   */\n  canConnect(\n    ds: DatasourceConnectSubject,\n    ctx?: DatasourceConnectContext,\n  ): DatasourceConnectDecision | Promise<DatasourceConnectDecision>;\n}\n\n/**\n * Open-core default: allow every connect. The D2 auto-connect gate (external /\n * explicitly-routed / `autoConnect:true`) still applies on top of this for\n * code-defined datasources, so a managed, unrouted datasource is never\n * connected even under the permissive policy.\n */\nexport const allowAllConnectPolicy: DatasourceConnectPolicy = {\n  canConnect: () => ({ allow: true }),\n};\n"]}

package/dist/chunk-JRBGOCRJ.js

@@ -0,0 +1,82 @@
+// src/sqlite-driver-fallback.ts
+var NATIVE_SQLITE_WASM_FALLBACK_WARNING = "  \u26A0 native better-sqlite3 unavailable (ABI mismatch or not built) \u2014 dev using wasm SQLite (real SQL, slower).\n    Rebuild better-sqlite3 for native speed, or set OS_DATABASE_DRIVER=sqlite-wasm to silence this.";
+var NATIVE_SQLITE_MEMORY_FALLBACK_WARNING = "  \u26A0 neither native nor wasm SQLite available \u2014 dev falling back to InMemoryDriver (mingo, not real SQL).\n    Rebuild better-sqlite3, or set OS_DATABASE_URL / OS_DATABASE_DRIVER for SQL fidelity.";
+function isEphemeralFilename(filename) {
+  return filename === ":memory:" || filename.startsWith(":");
+}
+async function resolveSqliteDriver(opts) {
+  const { filename } = opts;
+  const dev = opts.dev ?? process.env.NODE_ENV === "development";
+  const warn = opts.warn ?? ((message) => {
+    try {
+      console.warn(message);
+    } catch {
+    }
+  });
+  const { SqlDriver } = await import("@objectstack/driver-sql");
+  const buildNative = () => new SqlDriver({
+    client: "better-sqlite3",
+    connection: { filename },
+    useNullAsDefault: true,
+    ...opts.autoMigrate ? { autoMigrate: opts.autoMigrate } : {},
+    ...opts.schemaMode ? { schemaMode: opts.schemaMode } : {}
+  });
+  if (!dev) {
+    return { driver: buildNative(), engine: "better-sqlite3", label: "SqlDriver(sqlite)" };
+  }
+  let nativeDriver;
+  let nativeOk = false;
+  try {
+    nativeDriver = buildNative();
+    await nativeDriver.connect();
+    await nativeDriver.execute("SELECT 1");
+    nativeOk = true;
+  } catch {
+    nativeOk = false;
+    if (typeof nativeDriver?.disconnect === "function") {
+      try {
+        await nativeDriver.disconnect();
+      } catch {
+      }
+    }
+  }
+  if (nativeOk) {
+    return { driver: nativeDriver, engine: "better-sqlite3", label: "SqlDriver(sqlite)" };
+  }
+  let wasmDriver;
+  let wasmOk = false;
+  try {
+    const { SqliteWasmDriver } = await import("@objectstack/driver-sqlite-wasm");
+    wasmDriver = new SqliteWasmDriver({
+      filename,
+      // Match the existing construction sites: ephemeral DBs flush on
+      // disconnect; a persistent file flushes on every write so AI-authored
+      // data survives an unclean dev-server kill.
+      persist: isEphemeralFilename(filename) ? "on-disconnect" : "on-write"
+    });
+    await wasmDriver.connect();
+    wasmOk = true;
+  } catch {
+    wasmOk = false;
+    if (typeof wasmDriver?.disconnect === "function") {
+      try {
+        await wasmDriver.disconnect();
+      } catch {
+      }
+    }
+  }
+  if (wasmOk) {
+    warn(NATIVE_SQLITE_WASM_FALLBACK_WARNING);
+    return { driver: wasmDriver, engine: "sqlite-wasm", label: "SqliteWasmDriver" };
+  }
+  const { InMemoryDriver } = await import("@objectstack/driver-memory");
+  warn(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);
+  return { driver: new InMemoryDriver(), engine: "memory", label: "InMemoryDriver" };
+}
+
+export {
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+  resolveSqliteDriver
+};
+//# sourceMappingURL=chunk-JRBGOCRJ.js.map

package/dist/chunk-JRBGOCRJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sqlite-driver-fallback.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Shared native-`better-sqlite3` → wasm SQLite → in-memory step-down for any\n * sqlite-via-`better-sqlite3` construction (issue #2229).\n *\n * ## Why a probe is necessary\n *\n * `better-sqlite3` loads its native `.node` addon LAZILY — not at\n * `require('better-sqlite3')`, and not even at knex construction, but at the\n * first pool-connection acquire (`new Database(file)`), i.e. the first query.\n * So an ABI mismatch (a cached prebuilt binary built for a different Node\n * version — `NODE_MODULE_VERSION` mismatch) is invisible at boot and only\n * surfaces much later as a runtime `Find operation failed` on the first read.\n *\n * This helper makes the failure observable up-front by actively probing: it\n * opens a connection and runs a cheap `SELECT 1`, which forces the native addon\n * to load. (`connect()` alone is NOT a reliable probe: for SQLite it only runs\n * `mkdir` + a `PRAGMA` whose error is swallowed internally — so we additionally\n * issue a raw `SELECT 1`, which propagates the load error.) On failure it steps\n * down:\n *\n *   1. native `better-sqlite3`  — fast, real SQL\n *   2. wasm SQLite              — pure-JS, real SQL + on-disk persistence, slower   [dev only]\n *   3. in-memory (mingo)        — neither real SQL nor persistent                   [dev only, last resort]\n *\n * ## Dev vs production\n *\n * The wasm + in-memory step-down is GATED to dev. In production a native load\n * failure is NOT silently swapped for a different engine: the error is re-thrown\n * so it surfaces loudly (fail-closed) instead of an operator unknowingly running\n * on wasm/mingo. This mirrors the existing `serve.ts` default-dev fallback and\n * hoists it into one place shared by every sqlite construction site.\n */\n\n/** Which engine the resolver ultimately produced. */\nexport type SqliteFallbackEngine = 'better-sqlite3' | 'sqlite-wasm' | 'memory';\n\nexport interface ResolveSqliteDriverOptions {\n  /**\n   * SQLite filename — `:memory:` for an ephemeral database, or an absolute /\n   * relative path for a persistent file. Preserved across the wasm fallback so\n   * a persistent `file:` database keeps its on-disk persistence through wasm.\n   * Pass the raw filename (callers strip any `file:` / `sqlite:` scheme first).\n   */\n  filename: string;\n  /**\n   * Gates the wasm + in-memory step-down. When `true` (dev) a native ABI/load\n   * failure steps down the chain with a warning. When `false` (production) the\n   * native driver is returned unprobed so a failure surfaces loudly at first use\n   * (fail-closed) — we never silently degrade behind the operator's back.\n   * Defaults to `process.env.NODE_ENV === 'development'`.\n   */\n  dev?: boolean;\n  /** Forwarded to the native SqlDriver (dev loosen-only self-heal, #2186). */\n  autoMigrate?: 'off' | 'safe';\n  /** Forwarded to the SQL drivers (external schema mode, ADR-0015). */\n  schemaMode?: string;\n  /**\n   * Warning sink for the step-down messages. Defaults to `console.warn`.\n   * `serve.ts` passes a `chalk.yellow` wrapper so the banner stays consistent.\n   */\n  warn?: (message: string) => void;\n}\n\nexport interface ResolvedSqliteDriver {\n  /** The concrete engine driver to register (e.g. via `DriverPlugin`). */\n  driver: any;\n  /** Which engine actually resolved. */\n  engine: SqliteFallbackEngine;\n  /** Banner label, matching `serve.ts`'s existing strings. */\n  label: string;\n}\n\n/**\n * Warning emitted when native `better-sqlite3` is unavailable but wasm SQLite\n * loads. Kept byte-for-byte identical to the original `serve.ts` text so the\n * dev experience is the same regardless of which construction site triggers it.\n */\nexport const NATIVE_SQLITE_WASM_FALLBACK_WARNING =\n  '  ⚠ native better-sqlite3 unavailable (ABI mismatch or not built) — dev using wasm SQLite (real SQL, slower).\\n' +\n  '    Rebuild better-sqlite3 for native speed, or set OS_DATABASE_DRIVER=sqlite-wasm to silence this.';\n\n/** Warning emitted when neither native nor wasm SQLite loads (dev last resort). */\nexport const NATIVE_SQLITE_MEMORY_FALLBACK_WARNING =\n  '  ⚠ neither native nor wasm SQLite available — dev falling back to InMemoryDriver (mingo, not real SQL).\\n' +\n  '    Rebuild better-sqlite3, or set OS_DATABASE_URL / OS_DATABASE_DRIVER for SQL fidelity.';\n\n/** `:memory:` and other `:`-prefixed pseudo-filenames are never persisted. */\nfunction isEphemeralFilename(filename: string): boolean {\n  return filename === ':memory:' || filename.startsWith(':');\n}\n\n/**\n * Probe a `better-sqlite3` SQLite construction and, in dev, step down to wasm\n * SQLite (then in-memory) when the native addon cannot load.\n *\n * @see {@link ResolveSqliteDriverOptions}\n */\nexport async function resolveSqliteDriver(\n  opts: ResolveSqliteDriverOptions,\n): Promise<ResolvedSqliteDriver> {\n  const { filename } = opts;\n  const dev = opts.dev ?? process.env.NODE_ENV === 'development';\n  const warn =\n    opts.warn ??\n    ((message: string) => {\n      try {\n        // eslint-disable-next-line no-console\n        console.warn(message);\n      } catch {\n        /* ignore */\n      }\n    });\n\n  const { SqlDriver } = await import('@objectstack/driver-sql');\n\n  const buildNative = () =>\n    new SqlDriver({\n      client: 'better-sqlite3',\n      connection: { filename },\n      useNullAsDefault: true,\n      ...(opts.autoMigrate ? { autoMigrate: opts.autoMigrate } : {}),\n      ...(opts.schemaMode ? { schemaMode: opts.schemaMode } : {}),\n    } as any);\n\n  // Production: never silently swap engines. Construct the native driver and\n  // hand it back UNPROBED — exactly the historical behavior. A native load\n  // failure surfaces loudly at first use (fail-closed).\n  if (!dev) {\n    return { driver: buildNative(), engine: 'better-sqlite3', label: 'SqlDriver(sqlite)' };\n  }\n\n  // ── Dev: probe-by-connect, step down on native ABI/load failure. ──────────\n\n  // 1. Native better-sqlite3.\n  let nativeDriver: any;\n  let nativeOk = false;\n  try {\n    nativeDriver = buildNative();\n    // connect() runs mkdir (so a SELECT on a file DB whose dir is missing does\n    // not false-positive as an ABI failure) + a PRAGMA whose error it swallows;\n    // the raw SELECT 1 below is what reliably forces the native addon to load\n    // and PROPAGATES an ABI mismatch.\n    await nativeDriver.connect();\n    await nativeDriver.execute('SELECT 1');\n    nativeOk = true;\n  } catch {\n    nativeOk = false;\n    if (typeof nativeDriver?.disconnect === 'function') {\n      try {\n        await nativeDriver.disconnect();\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n  if (nativeOk) {\n    return { driver: nativeDriver, engine: 'better-sqlite3', label: 'SqlDriver(sqlite)' };\n  }\n\n  // 2. wasm SQLite — real SQL semantics + on-disk persistence, no native build.\n  let wasmDriver: any;\n  let wasmOk = false;\n  try {\n    const { SqliteWasmDriver } = await import('@objectstack/driver-sqlite-wasm');\n    wasmDriver = new SqliteWasmDriver({\n      filename,\n      // Match the existing construction sites: ephemeral DBs flush on\n      // disconnect; a persistent file flushes on every write so AI-authored\n      // data survives an unclean dev-server kill.\n      persist: isEphemeralFilename(filename) ? 'on-disconnect' : 'on-write',\n    } as any);\n    await wasmDriver.connect();\n    wasmOk = true;\n  } catch {\n    wasmOk = false;\n    if (typeof wasmDriver?.disconnect === 'function') {\n      try {\n        await wasmDriver.disconnect();\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n  if (wasmOk) {\n    warn(NATIVE_SQLITE_WASM_FALLBACK_WARNING);\n    return { driver: wasmDriver, engine: 'sqlite-wasm', label: 'SqliteWasmDriver' };\n  }\n\n  // 3. In-memory (mingo) — dev-only last resort. Not real SQL, not persistent.\n  const { InMemoryDriver } = await import('@objectstack/driver-memory');\n  warn(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);\n  return { driver: new InMemoryDriver(), engine: 'memory', label: 'InMemoryDriver' };\n}\n"],"mappings":";AA+EO,IAAM,sCACX;AAIK,IAAM,wCACX;AAIF,SAAS,oBAAoB,UAA2B;AACtD,SAAO,aAAa,cAAc,SAAS,WAAW,GAAG;AAC3D;AAQA,eAAsB,oBACpB,MAC+B;AAC/B,QAAM,EAAE,SAAS,IAAI;AACrB,QAAM,MAAM,KAAK,OAAO,QAAQ,IAAI,aAAa;AACjD,QAAM,OACJ,KAAK,SACJ,CAAC,YAAoB;AACpB,QAAI;AAEF,cAAQ,KAAK,OAAO;AAAA,IACtB,QAAQ;AAAA,IAER;AAAA,EACF;AAEF,QAAM,EAAE,UAAU,IAAI,MAAM,OAAO,yBAAyB;AAE5D,QAAM,cAAc,MAClB,IAAI,UAAU;AAAA,IACZ,QAAQ;AAAA,IACR,YAAY,EAAE,SAAS;AAAA,IACvB,kBAAkB;AAAA,IAClB,GAAI,KAAK,cAAc,EAAE,aAAa,KAAK,YAAY,IAAI,CAAC;AAAA,IAC5D,GAAI,KAAK,aAAa,EAAE,YAAY,KAAK,WAAW,IAAI,CAAC;AAAA,EAC3D,CAAQ;AAKV,MAAI,CAAC,KAAK;AACR,WAAO,EAAE,QAAQ,YAAY,GAAG,QAAQ,kBAAkB,OAAO,oBAAoB;AAAA,EACvF;AAKA,MAAI;AACJ,MAAI,WAAW;AACf,MAAI;AACF,mBAAe,YAAY;AAK3B,UAAM,aAAa,QAAQ;AAC3B,UAAM,aAAa,QAAQ,UAAU;AACrC,eAAW;AAAA,EACb,QAAQ;AACN,eAAW;AACX,QAAI,OAAO,cAAc,eAAe,YAAY;AAClD,UAAI;AACF,cAAM,aAAa,WAAW;AAAA,MAChC,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AACA,MAAI,UAAU;AACZ,WAAO,EAAE,QAAQ,cAAc,QAAQ,kBAAkB,OAAO,oBAAoB;AAAA,EACtF;AAGA,MAAI;AACJ,MAAI,SAAS;AACb,MAAI;AACF,UAAM,EAAE,iBAAiB,IAAI,MAAM,OAAO,iCAAiC;AAC3E,iBAAa,IAAI,iBAAiB;AAAA,MAChC;AAAA;AAAA;AAAA;AAAA,MAIA,SAAS,oBAAoB,QAAQ,IAAI,kBAAkB;AAAA,IAC7D,CAAQ;AACR,UAAM,WAAW,QAAQ;AACzB,aAAS;AAAA,EACX,QAAQ;AACN,aAAS;AACT,QAAI,OAAO,YAAY,eAAe,YAAY;AAChD,UAAI;AACF,cAAM,WAAW,WAAW;AAAA,MAC9B,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AACA,MAAI,QAAQ;AACV,SAAK,mCAAmC;AACxC,WAAO,EAAE,QAAQ,YAAY,QAAQ,eAAe,OAAO,mBAAmB;AAAA,EAChF;AAGA,QAAM,EAAE,eAAe,IAAI,MAAM,OAAO,4BAA4B;AACpE,OAAK,qCAAqC;AAC1C,SAAO,EAAE,QAAQ,IAAI,eAAe,GAAG,QAAQ,UAAU,OAAO,iBAAiB;AACnF;","names":[]}

package/dist/chunk-XLS4RP7B.js

@@ -0,0 +1,9 @@
+// src/contracts/connect-policy.ts
+var allowAllConnectPolicy = {
+  canConnect: () => ({ allow: true })
+};
+
+export {
+  allowAllConnectPolicy
+};
+//# sourceMappingURL=chunk-XLS4RP7B.js.map

package/dist/chunk-XLS4RP7B.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contracts/connect-policy.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * DatasourceConnectPolicy — host-injectable gate consulted *before*\n * {@link DatasourceConnectionService} builds and registers a live driver\n * (ADR-0062 D1/D5, and the epic #2163 \"connect-policy seam\" note).\n *\n * The framework ships a permissive default ({@link allowAllConnectPolicy}) so a\n * self-hosted single-environment runtime connects external datasources out of\n * the box (subject to the D2 auto-connect gate, which is applied separately by\n * {@link DatasourceConnectionService.connectDeclared}). A multi-tenant host\n * (shared-container cloud) binds a stricter policy that can *fail-close* on the\n * shared runtime — e.g. checking `sys_environment.plan`, an egress allow-list,\n * and per-tenant quota — to enforce SSRF / egress isolation.\n *\n * This keeps a single connect path for code- and runtime-origin datasources\n * (D1): the host injects a policy rather than forking a second connect path.\n * No plan coupling lives in the open framework.\n */\n\n/** Why a connect is being attempted — lets a policy treat origins differently. */\nexport interface DatasourceConnectContext {\n  /** Provenance of the datasource being connected. */\n  origin?: 'code' | 'runtime';\n  /**\n   * What triggered this connect:\n   *  - `declared-auto`  — code-defined datasource auto-connected at boot (D2 gate passed).\n   *  - `runtime-admin`  — UI \"Add/Update Datasource\" hot pool registration.\n   *  - `rehydrate`      — boot rehydration of a persisted runtime datasource.\n   */\n  trigger?: 'declared-auto' | 'runtime-admin' | 'rehydrate';\n}\n\n/** A policy verdict. `allow:false` leaves the datasource unconnected (metadata-only). */\nexport interface DatasourceConnectDecision {\n  allow: boolean;\n  /** Human-readable reason, surfaced in logs when a connect is denied. */\n  reason?: string;\n}\n\n/** The minimal datasource shape a policy inspects (never a secret). */\nexport interface DatasourceConnectSubject {\n  name: string;\n  driver: string;\n  schemaMode?: 'managed' | 'external' | 'validate-only';\n  external?: Record<string, unknown>;\n}\n\n/** Host-provided policy gate consulted before opening a connection. */\nexport interface DatasourceConnectPolicy {\n  /**\n   * Decide whether `ds` may be connected. Sync or async. Throwing is treated\n   * as a denial (fail-closed) by {@link DatasourceConnectionService}.\n   */\n  canConnect(\n    ds: DatasourceConnectSubject,\n    ctx?: DatasourceConnectContext,\n  ): DatasourceConnectDecision | Promise<DatasourceConnectDecision>;\n}\n\n/**\n * Open-core default: allow every connect. The D2 auto-connect gate (external /\n * explicitly-routed / `autoConnect:true`) still applies on top of this for\n * code-defined datasources, so a managed, unrouted datasource is never\n * connected even under the permissive policy.\n */\nexport const allowAllConnectPolicy: DatasourceConnectPolicy = {\n  canConnect: () => ({ allow: true }),\n};\n"],"mappings":";AAkEO,IAAM,wBAAiD;AAAA,EAC5D,YAAY,OAAO,EAAE,OAAO,KAAK;AACnC;","names":[]}

package/dist/contracts/index.cjs

@@ -1 +1,7 @@
-"use strict";//# sourceMappingURL=index.cjs.map
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkBI2SYWLCcjs = require('../chunk-BI2SYWLC.cjs');
+
+
+exports.allowAllConnectPolicy = _chunkBI2SYWLCcjs.allowAllConnectPolicy;
+//# sourceMappingURL=index.cjs.map

package/dist/contracts/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/framework/framework/packages/services/service-datasource/dist/contracts/index.cjs"],"names":[],"mappings":"AAAA","file":"/home/runner/work/framework/framework/packages/services/service-datasource/dist/contracts/index.cjs"}
+{"version":3,"sources":["/home/runner/work/framework/framework/packages/services/service-datasource/dist/contracts/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACF,yDAA8B;AAC9B;AACE;AACF,wEAAC","file":"/home/runner/work/framework/framework/packages/services/service-datasource/dist/contracts/index.cjs"}

package/dist/contracts/index.d.cts

@@ -175,4 +175,62 @@ interface IDatasourceDriverFactory {
     create(spec: DatasourceConnectionSpec): Promise<DatasourceDriverHandle> | DatasourceDriverHandle;
 }
 
-export type { DatasourceConnectionSpec, DatasourceDraft, DatasourceDriverHandle, DatasourceOrigin, DatasourceSummary, IDatasourceAdminService, IDatasourceDriverFactory, SecretInput, TestConnectionResult };
+/**
+ * DatasourceConnectPolicy — host-injectable gate consulted *before*
+ * {@link DatasourceConnectionService} builds and registers a live driver
+ * (ADR-0062 D1/D5, and the epic #2163 "connect-policy seam" note).
+ *
+ * The framework ships a permissive default ({@link allowAllConnectPolicy}) so a
+ * self-hosted single-environment runtime connects external datasources out of
+ * the box (subject to the D2 auto-connect gate, which is applied separately by
+ * {@link DatasourceConnectionService.connectDeclared}). A multi-tenant host
+ * (shared-container cloud) binds a stricter policy that can *fail-close* on the
+ * shared runtime — e.g. checking `sys_environment.plan`, an egress allow-list,
+ * and per-tenant quota — to enforce SSRF / egress isolation.
+ *
+ * This keeps a single connect path for code- and runtime-origin datasources
+ * (D1): the host injects a policy rather than forking a second connect path.
+ * No plan coupling lives in the open framework.
+ */
+/** Why a connect is being attempted — lets a policy treat origins differently. */
+interface DatasourceConnectContext {
+    /** Provenance of the datasource being connected. */
+    origin?: 'code' | 'runtime';
+    /**
+     * What triggered this connect:
+     *  - `declared-auto`  — code-defined datasource auto-connected at boot (D2 gate passed).
+     *  - `runtime-admin`  — UI "Add/Update Datasource" hot pool registration.
+     *  - `rehydrate`      — boot rehydration of a persisted runtime datasource.
+     */
+    trigger?: 'declared-auto' | 'runtime-admin' | 'rehydrate';
+}
+/** A policy verdict. `allow:false` leaves the datasource unconnected (metadata-only). */
+interface DatasourceConnectDecision {
+    allow: boolean;
+    /** Human-readable reason, surfaced in logs when a connect is denied. */
+    reason?: string;
+}
+/** The minimal datasource shape a policy inspects (never a secret). */
+interface DatasourceConnectSubject {
+    name: string;
+    driver: string;
+    schemaMode?: 'managed' | 'external' | 'validate-only';
+    external?: Record<string, unknown>;
+}
+/** Host-provided policy gate consulted before opening a connection. */
+interface DatasourceConnectPolicy {
+    /**
+     * Decide whether `ds` may be connected. Sync or async. Throwing is treated
+     * as a denial (fail-closed) by {@link DatasourceConnectionService}.
+     */
+    canConnect(ds: DatasourceConnectSubject, ctx?: DatasourceConnectContext): DatasourceConnectDecision | Promise<DatasourceConnectDecision>;
+}
+/**
+ * Open-core default: allow every connect. The D2 auto-connect gate (external /
+ * explicitly-routed / `autoConnect:true`) still applies on top of this for
+ * code-defined datasources, so a managed, unrouted datasource is never
+ * connected even under the permissive policy.
+ */
+declare const allowAllConnectPolicy: DatasourceConnectPolicy;
+
+export { type DatasourceConnectContext, type DatasourceConnectDecision, type DatasourceConnectPolicy, type DatasourceConnectSubject, type DatasourceConnectionSpec, type DatasourceDraft, type DatasourceDriverHandle, type DatasourceOrigin, type DatasourceSummary, type IDatasourceAdminService, type IDatasourceDriverFactory, type SecretInput, type TestConnectionResult, allowAllConnectPolicy };

package/dist/contracts/index.d.ts

@@ -175,4 +175,62 @@ interface IDatasourceDriverFactory {
     create(spec: DatasourceConnectionSpec): Promise<DatasourceDriverHandle> | DatasourceDriverHandle;
 }
 
-export type { DatasourceConnectionSpec, DatasourceDraft, DatasourceDriverHandle, DatasourceOrigin, DatasourceSummary, IDatasourceAdminService, IDatasourceDriverFactory, SecretInput, TestConnectionResult };
+/**
+ * DatasourceConnectPolicy — host-injectable gate consulted *before*
+ * {@link DatasourceConnectionService} builds and registers a live driver
+ * (ADR-0062 D1/D5, and the epic #2163 "connect-policy seam" note).
+ *
+ * The framework ships a permissive default ({@link allowAllConnectPolicy}) so a
+ * self-hosted single-environment runtime connects external datasources out of
+ * the box (subject to the D2 auto-connect gate, which is applied separately by
+ * {@link DatasourceConnectionService.connectDeclared}). A multi-tenant host
+ * (shared-container cloud) binds a stricter policy that can *fail-close* on the
+ * shared runtime — e.g. checking `sys_environment.plan`, an egress allow-list,
+ * and per-tenant quota — to enforce SSRF / egress isolation.
+ *
+ * This keeps a single connect path for code- and runtime-origin datasources
+ * (D1): the host injects a policy rather than forking a second connect path.
+ * No plan coupling lives in the open framework.
+ */
+/** Why a connect is being attempted — lets a policy treat origins differently. */
+interface DatasourceConnectContext {
+    /** Provenance of the datasource being connected. */
+    origin?: 'code' | 'runtime';
+    /**
+     * What triggered this connect:
+     *  - `declared-auto`  — code-defined datasource auto-connected at boot (D2 gate passed).
+     *  - `runtime-admin`  — UI "Add/Update Datasource" hot pool registration.
+     *  - `rehydrate`      — boot rehydration of a persisted runtime datasource.
+     */
+    trigger?: 'declared-auto' | 'runtime-admin' | 'rehydrate';
+}
+/** A policy verdict. `allow:false` leaves the datasource unconnected (metadata-only). */
+interface DatasourceConnectDecision {
+    allow: boolean;
+    /** Human-readable reason, surfaced in logs when a connect is denied. */
+    reason?: string;
+}
+/** The minimal datasource shape a policy inspects (never a secret). */
+interface DatasourceConnectSubject {
+    name: string;
+    driver: string;
+    schemaMode?: 'managed' | 'external' | 'validate-only';
+    external?: Record<string, unknown>;
+}
+/** Host-provided policy gate consulted before opening a connection. */
+interface DatasourceConnectPolicy {
+    /**
+     * Decide whether `ds` may be connected. Sync or async. Throwing is treated
+     * as a denial (fail-closed) by {@link DatasourceConnectionService}.
+     */
+    canConnect(ds: DatasourceConnectSubject, ctx?: DatasourceConnectContext): DatasourceConnectDecision | Promise<DatasourceConnectDecision>;
+}
+/**
+ * Open-core default: allow every connect. The D2 auto-connect gate (external /
+ * explicitly-routed / `autoConnect:true`) still applies on top of this for
+ * code-defined datasources, so a managed, unrouted datasource is never
+ * connected even under the permissive policy.
+ */
+declare const allowAllConnectPolicy: DatasourceConnectPolicy;
+
+export { type DatasourceConnectContext, type DatasourceConnectDecision, type DatasourceConnectPolicy, type DatasourceConnectSubject, type DatasourceConnectionSpec, type DatasourceDraft, type DatasourceDriverHandle, type DatasourceOrigin, type DatasourceSummary, type IDatasourceAdminService, type IDatasourceDriverFactory, type SecretInput, type TestConnectionResult, allowAllConnectPolicy };

package/dist/contracts/index.js

@@ -1 +1,7 @@
+import {
+  allowAllConnectPolicy
+} from "../chunk-XLS4RP7B.js";
+export {
+  allowAllConnectPolicy
+};
 //# sourceMappingURL=index.js.map