@objectstack/service-datasource 7.6.0

package/src/__tests__/external-datasource-service.test.ts

@@ -0,0 +1,360 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import type { IntrospectedSchema } from '@objectstack/spec/contracts';
+import {
+  ExternalDatasourceService,
+  type DatasourceLike,
+  type ObjectLike,
+} from '../external-datasource-service.js';
+
+/** Build a fake introspected schema for the `warehouse` datasource. */
+function warehouseSchema(): IntrospectedSchema {
+  return {
+    dialect: 'postgres',
+    introspectedAt: '2026-05-30T00:00:00.000Z',
+    tables: {
+      'mart.fact_orders': {
+        name: 'mart.fact_orders',
+        indexes: [],
+        columns: [
+          { name: 'order_id', type: 'text', nullable: false, primaryKey: true },
+          { name: 'customer_id', type: 'text', nullable: false, primaryKey: false },
+          { name: 'amount', type: 'numeric(10,2)', nullable: true, primaryKey: false },
+          { name: 'ordered_at', type: 'timestamptz', nullable: true, primaryKey: false },
+          { name: 'metadata', type: 'jsonb', nullable: true, primaryKey: false },
+          { name: 'geo', type: 'geography', nullable: true, primaryKey: false },
+        ],
+      },
+      'public.dim_customer': {
+        name: 'public.dim_customer',
+        indexes: [],
+        columns: [
+          { name: 'id', type: 'text', nullable: false, primaryKey: true },
+          { name: 'name', type: 'varchar(255)', nullable: true, primaryKey: false },
+        ],
+      },
+    },
+  };
+}
+
+function makeService(overrides?: {
+  datasource?: DatasourceLike;
+  objects?: ObjectLike[];
+}) {
+  const ds: DatasourceLike = overrides?.datasource ?? {
+    name: 'warehouse',
+    schemaMode: 'external',
+    external: { allowedSchemas: ['mart', 'public'] },
+  };
+  const objects = overrides?.objects ?? [];
+  return new ExternalDatasourceService({
+    introspect: async () => warehouseSchema(),
+    getDatasource: async (n) => (n === ds.name ? ds : undefined),
+    getObject: async (n) => objects.find((o) => o.name === n),
+    listObjects: async () => objects,
+  });
+}
+
+describe('listRemoteTables', () => {
+  it('lists tables with parsed schema + column counts', async () => {
+    const svc = makeService();
+    const tables = await svc.listRemoteTables('warehouse');
+    expect(tables).toHaveLength(2);
+    const orders = tables.find((t) => t.name === 'fact_orders')!;
+    expect(orders.schema).toBe('mart');
+    expect(orders.columnCount).toBe(6);
+  });
+
+  it('filters by requested schema', async () => {
+    const svc = makeService();
+    const tables = await svc.listRemoteTables('warehouse', { schema: 'public' });
+    expect(tables.map((t) => t.name)).toEqual(['dim_customer']);
+  });
+
+  it('respects allowedSchemas', async () => {
+    const svc = makeService({
+      datasource: { name: 'warehouse', schemaMode: 'external', external: { allowedSchemas: ['mart'] } },
+    });
+    const tables = await svc.listRemoteTables('warehouse');
+    expect(tables.map((t) => t.name)).toEqual(['fact_orders']);
+  });
+});
+
+describe('generateObjectDraft', () => {
+  it('maps columns to field types and flags lossy/unknown for review', async () => {
+    const svc = makeService();
+    const draft = await svc.generateObjectDraft('warehouse', 'fact_orders');
+
+    expect(draft.name).toBe('fact_orders');
+    expect(draft.datasource).toBe('warehouse');
+    const fields = draft.definition.fields as Record<string, { type: string; primaryKey?: boolean }>;
+    expect(fields.order_id).toEqual({ type: 'text', primaryKey: true });
+    expect(fields.amount.type).toBe('number');
+    expect(fields.ordered_at.type).toBe('datetime');
+    expect(fields.metadata.type).toBe('json');
+    // geography is unknown → defaulted to text + review note.
+    expect(fields.geo.type).toBe('text');
+    expect(draft.review.some((r) => r.column === 'geo')).toBe(true);
+
+    // Source carries the external binding + a REVIEW marker.
+    expect(draft.source).toContain("remoteName: 'fact_orders'");
+    expect(draft.source).toContain("remoteSchema: 'mart'");
+    expect(draft.source).toContain('REVIEW:');
+    expect(draft.source).toContain("order_id: { type: 'text', primaryKey: true }");
+  });
+
+  it('honours include/exclude/rename/primaryKey options', async () => {
+    const svc = makeService();
+    const draft = await svc.generateObjectDraft('warehouse', 'fact_orders', {
+      includeColumns: ['order_id', 'amount'],
+      rename: { amount: 'total' },
+      primaryKey: ['order_id'],
+    });
+    const fields = draft.definition.fields as Record<string, unknown>;
+    expect(Object.keys(fields)).toEqual(['order_id', 'total']);
+  });
+
+  it('throws when the remote table is missing', async () => {
+    const svc = makeService();
+    await expect(svc.generateObjectDraft('warehouse', 'nope')).rejects.toThrow(/not found/);
+  });
+});
+
+describe('importObject', () => {
+  /** Build a service with a recording persistObject (runtime metadata store). */
+  function makeImporter(persistObject?: (name: string, def: Record<string, unknown>) => Promise<void>) {
+    const persisted: Array<{ name: string; def: Record<string, unknown> }> = [];
+    const svc = new ExternalDatasourceService({
+      introspect: async () => warehouseSchema(),
+      getDatasource: async () => ({ name: 'warehouse', schemaMode: 'external' }),
+      getObject: async () => undefined,
+      listObjects: async () => [],
+      persistObject:
+        persistObject ?? (async (name, def) => { persisted.push({ name, def }); }),
+    });
+    return { svc, persisted };
+  }
+
+  it('persists a runtime federated object and returns name/definition/review', async () => {
+    const { svc, persisted } = makeImporter();
+    const result = await svc.importObject('warehouse', 'fact_orders');
+
+    expect(result.name).toBe('fact_orders');
+    expect(persisted).toHaveLength(1);
+    expect(persisted[0].name).toBe('fact_orders');
+    const def = persisted[0].def as { datasource: string; external: { remoteName: string; writable?: boolean } };
+    expect(def.datasource).toBe('warehouse');
+    expect(def.external.remoteName).toBe('fact_orders');
+    // Read-only by default — no writable flag leaks in.
+    expect(def.external.writable).toBeUndefined();
+    // The geography column surfaced a review note (carried over from the draft).
+    expect(result.review.some((r) => r.column === 'geo')).toBe(true);
+  });
+
+  it('applies the name override and writable opt-in', async () => {
+    const { svc, persisted } = makeImporter();
+    const result = await svc.importObject('warehouse', 'fact_orders', {
+      name: 'wh_orders',
+      writable: true,
+    });
+    expect(result.name).toBe('wh_orders');
+    const def = persisted[0].def as { name: string; label: string; external: { writable?: boolean } };
+    expect(def.name).toBe('wh_orders');
+    expect(def.label).toBe('Wh Orders');
+    expect(def.external.writable).toBe(true);
+  });
+
+  it('forwards draft options (include/rename) through to the persisted fields', async () => {
+    const { svc, persisted } = makeImporter();
+    await svc.importObject('warehouse', 'fact_orders', {
+      includeColumns: ['order_id', 'amount'],
+      rename: { amount: 'total' },
+    });
+    const def = persisted[0].def as { fields: Record<string, unknown> };
+    expect(Object.keys(def.fields)).toEqual(['order_id', 'total']);
+  });
+
+  it('throws when no writable metadata store is wired', async () => {
+    const svc = new ExternalDatasourceService({
+      introspect: async () => warehouseSchema(),
+      getDatasource: async () => ({ name: 'warehouse', schemaMode: 'external' }),
+      getObject: async () => undefined,
+      listObjects: async () => [],
+      // no persistObject
+    });
+    await expect(svc.importObject('warehouse', 'fact_orders')).rejects.toThrow(
+      /writable metadata store/,
+    );
+  });
+
+  it('throws when the remote table is missing (no persistence)', async () => {
+    const { svc, persisted } = makeImporter();
+    await expect(svc.importObject('warehouse', 'ghost')).rejects.toThrow(/not found/);
+    expect(persisted).toHaveLength(0);
+  });
+});
+
+describe('validateObject', () => {
+  const baseObject: ObjectLike = {
+    name: 'wh_order',
+    datasource: 'warehouse',
+    external: { remoteName: 'fact_orders' },
+    fields: {
+      order_id: { type: 'text' },
+      customer_id: { type: 'text' },
+      amount: { type: 'number' },
+      ordered_at: { type: 'datetime' },
+    },
+  };
+
+  it('returns ok for a matching federated object', async () => {
+    const svc = makeService({ objects: [baseObject] });
+    const result = await svc.validateObject('wh_order');
+    expect(result.ok).toBe(true);
+    expect(result.diffs).toHaveLength(0);
+  });
+
+  it('reports a type_mismatch error for an incompatible field', async () => {
+    const svc = makeService({
+      objects: [{ ...baseObject, fields: { ...baseObject.fields, amount: { type: 'datetime' } } }],
+    });
+    const result = await svc.validateObject('wh_order');
+    expect(result.ok).toBe(false);
+    expect(result.diffs).toContainEqual(
+      expect.objectContaining({ kind: 'type_mismatch', column: 'amount', severity: 'error' }),
+    );
+  });
+
+  it('reports a missing_column error', async () => {
+    const svc = makeService({
+      objects: [{ ...baseObject, fields: { ...baseObject.fields, nonexistent: { type: 'text' } } }],
+    });
+    const result = await svc.validateObject('wh_order');
+    expect(result.ok).toBe(false);
+    expect(result.diffs).toContainEqual(
+      expect.objectContaining({ kind: 'missing_column', column: 'nonexistent' }),
+    );
+  });
+
+  it('reports missing_table when the remote table is absent', async () => {
+    const svc = makeService({
+      objects: [{ ...baseObject, external: { remoteName: 'ghost' } }],
+    });
+    const result = await svc.validateObject('wh_order');
+    expect(result.ok).toBe(false);
+    expect(result.diffs[0].kind).toBe('missing_table');
+  });
+
+  it('treats a managed datasource object as nothing-to-validate', async () => {
+    const svc = makeService({
+      datasource: { name: 'warehouse', schemaMode: 'managed' },
+      objects: [baseObject],
+    });
+    const result = await svc.validateObject('wh_order');
+    expect(result.ok).toBe(true);
+    expect(result.diffs).toHaveLength(0);
+  });
+
+  it('honours columnMap and ignoreColumns', async () => {
+    const svc = makeService({
+      objects: [
+        {
+          name: 'wh_order',
+          datasource: 'warehouse',
+          external: {
+            remoteName: 'fact_orders',
+            columnMap: { customer_id: 'cust' },
+            ignoreColumns: ['metadata'],
+          },
+          fields: { order_id: { type: 'text' }, cust: { type: 'text' } },
+        },
+      ],
+    });
+    const result = await svc.validateObject('wh_order');
+    expect(result.ok).toBe(true);
+  });
+
+  it('flags a lossy mapping as a warning without failing', async () => {
+    const svc = makeService({
+      objects: [
+        {
+          name: 'wh_order',
+          datasource: 'warehouse',
+          external: { remoteName: 'fact_orders' },
+          fields: { order_id: { type: 'text' }, metadata: { type: 'text' } },
+        },
+      ],
+    });
+    const result = await svc.validateObject('wh_order');
+    expect(result.ok).toBe(true);
+    expect(result.diffs).toContainEqual(
+      expect.objectContaining({ kind: 'type_mismatch', column: 'metadata', severity: 'warning' }),
+    );
+  });
+});
+
+describe('validateAll', () => {
+  it('aggregates results across federated objects only', async () => {
+    const svc = makeService({
+      objects: [
+        { name: 'local_thing', datasource: 'default', fields: { id: { type: 'text' } } },
+        {
+          name: 'wh_order',
+          datasource: 'warehouse',
+          external: { remoteName: 'fact_orders' },
+          fields: { order_id: { type: 'text' }, amount: { type: 'number' } },
+        },
+      ],
+    });
+    const report = await svc.validateAll();
+    expect(report.ok).toBe(true);
+    expect(report.results.map((r) => r.object)).toEqual(['wh_order']);
+  });
+});
+
+describe('refreshCatalog', () => {
+  it('produces a snapshot with suggested field types', async () => {
+    const svc = makeService();
+    const catalog = await svc.refreshCatalog('warehouse');
+    expect(catalog.datasource).toBe('warehouse');
+    expect(catalog.name).toBe('warehouse_catalog');
+    const orders = catalog.tables.find((t) => t.remoteName === 'fact_orders')!;
+    expect(orders.columns.find((c) => c.name === 'amount')?.suggestedFieldType).toBe('number');
+    // Canonicalised through the Zod schema: primaryKey default applied.
+    expect(orders.columns.find((c) => c.name === 'order_id')?.primaryKey).toBe(true);
+    expect(orders.columns.find((c) => c.name === 'amount')?.primaryKey).toBe(false);
+  });
+
+  it('persists the snapshot as an external_catalog record when a store is wired', async () => {
+    const persisted: unknown[] = [];
+    const svc = new ExternalDatasourceService({
+      introspect: async () => warehouseSchema(),
+      getDatasource: async () => ({ name: 'warehouse', schemaMode: 'external' }),
+      getObject: async () => undefined,
+      listObjects: async () => [],
+      persistCatalog: async (c) => {
+        persisted.push(c);
+      },
+    });
+    const catalog = await svc.refreshCatalog('warehouse');
+    expect(persisted).toHaveLength(1);
+    expect(persisted[0]).toBe(catalog);
+    expect((persisted[0] as { name: string }).name).toBe('warehouse_catalog');
+  });
+
+  it('still returns the snapshot when persistence throws (best-effort cache)', async () => {
+    const svc = new ExternalDatasourceService({
+      introspect: async () => warehouseSchema(),
+      getDatasource: async () => ({ name: 'warehouse', schemaMode: 'external' }),
+      getObject: async () => undefined,
+      listObjects: async () => [],
+      persistCatalog: async () => {
+        throw new Error('metadata store is read-only');
+      },
+      logger: { warn: () => {} },
+    });
+    const catalog = await svc.refreshCatalog('warehouse');
+    expect(catalog.name).toBe('warehouse_catalog');
+  });
+});

package/src/admin-routes.ts

@@ -0,0 +1,117 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { PluginContext } from '@objectstack/core';
+import type { IHttpServer } from '@objectstack/spec/contracts';
+
+/**
+ * Datasource lifecycle REST routes (ADR-0015 Addendum §3.5).
+ *
+ * Mounted under `/api/v1/datasources` and served by the `datasource-admin`
+ * service. Every route degrades gracefully
+ * (`503 datasource_admin_unavailable`) when the service is not wired in, and
+ * lifecycle/validation failures surface as `400` with the service's message.
+ *
+ *   GET    /datasources              → listDatasources (provenance + health)
+ *   POST   /datasources/test         → testConnection (no persistence)
+ *   POST   /datasources              → createDatasource (origin: 'runtime')
+ *   PATCH  /datasources/:name        → updateDatasource (runtime only)
+ *   DELETE /datasources/:name        → removeDatasource (runtime only)
+ *
+ * Request bodies carry the connection draft inline with an optional cleartext
+ * `secret` field; the route splits `secret` out so it never reaches the draft
+ * the service persists.
+ */
+export function registerDatasourceAdminRoutes(
+  server: IHttpServer,
+  ctx: PluginContext,
+  basePath = '/api/v1',
+): void {
+  const root = `${basePath}/datasources`;
+
+  const adminService = (): any => {
+    try {
+      return ctx.getService<any>('datasource-admin');
+    } catch {
+      return undefined;
+    }
+  };
+
+  const unavailable = (res: any) =>
+    res.status(503).json({ error: 'datasource_admin_unavailable' });
+
+  const badRequest = (res: any, err: unknown) =>
+    res.status(400).json({ error: 'datasource_admin_error', message: err instanceof Error ? err.message : String(err) });
+
+  /** Split an inline `{ secret, ...draft }` body into (draft, secret). */
+  const splitSecret = (body: any): { draft: any; secret: any } => {
+    const { secret, ...draft } = (body as Record<string, unknown>) ?? {};
+    // Accept either a bare string or a `{ value, namespace?, key? }` object.
+    const normalised =
+      secret == null
+        ? undefined
+        : typeof secret === 'string'
+          ? { value: secret }
+          : secret;
+    return { draft, secret: normalised };
+  };
+
+  // List all datasources with provenance + health.
+  server.get(root, async (_req: any, res: any) => {
+    const svc = adminService();
+    if (!svc?.listDatasources) return unavailable(res);
+    const datasources = await svc.listDatasources();
+    res.json({ datasources });
+  });
+
+  // Probe a connection without persisting anything. Registered before the
+  // `:name` routes so the literal `test` segment is never captured as a name.
+  server.post(`${root}/test`, async (req: any, res: any) => {
+    const svc = adminService();
+    if (!svc?.testConnection) return unavailable(res);
+    const { draft, secret } = splitSecret(req.body);
+    try {
+      const result = await svc.testConnection(draft, secret);
+      res.json({ result });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+
+  // Create a runtime datasource.
+  server.post(root, async (req: any, res: any) => {
+    const svc = adminService();
+    if (!svc?.createDatasource) return unavailable(res);
+    const { draft, secret } = splitSecret(req.body);
+    try {
+      const datasource = await svc.createDatasource(draft, secret);
+      res.status(201).json({ datasource });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+
+  // Patch a runtime datasource.
+  server.patch(`${root}/:name`, async (req: any, res: any) => {
+    const svc = adminService();
+    if (!svc?.updateDatasource) return unavailable(res);
+    const { draft, secret } = splitSecret(req.body);
+    try {
+      const datasource = await svc.updateDatasource(req.params.name, draft, secret);
+      res.json({ datasource });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+
+  // Remove a runtime datasource.
+  server.delete(`${root}/:name`, async (req: any, res: any) => {
+    const svc = adminService();
+    if (!svc?.removeDatasource) return unavailable(res);
+    try {
+      await svc.removeDatasource(req.params.name);
+      res.status(204).end();
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+}

package/src/contracts/datasource-admin-service.ts

@@ -0,0 +1,119 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * IDatasourceAdminService — runtime datasource lifecycle contract
+ * (ADR-0015 Addendum: Runtime UI-Created Datasources).
+ *
+ * Where {@link IExternalDatasourceService} covers *federation* (introspection,
+ * object drafting, schema validation) of datasources that already exist, this
+ * service covers their *lifecycle*: testing a connection before saving,
+ * creating / updating / removing a **runtime** datasource (`origin: 'runtime'`),
+ * and listing all datasources with their provenance + health.
+ *
+ * Code-defined datasources (`origin: 'code'`, authored as `*.datasource.ts`)
+ * are read-only here: `updateDatasource` / `removeDatasource` reject them, and
+ * a runtime datasource never shadows a code one of the same name (code wins).
+ *
+ * Credentials are never persisted in cleartext: callers pass a {@link SecretInput}
+ * separately from the connection `config`; the implementation encrypts it into
+ * the secret store (`sys_secret`) and persists only an opaque `credentialsRef`.
+ */
+
+/** Provenance of a datasource definition. */
+export type DatasourceOrigin = 'code' | 'runtime';
+
+/**
+ * A cleartext secret (password or full connection string) supplied for a
+ * create/update/test call. Never persisted as-is — encrypted into the secret
+ * store, with only the returned handle (`credentialsRef`) kept on the record.
+ */
+export interface SecretInput {
+  /** The cleartext value to encrypt (e.g. password or connection string). */
+  value: string;
+  /** Optional secret-store namespace (defaults to `'datasource'`). */
+  namespace?: string;
+  /** Optional secret-store key (defaults to the datasource name). */
+  key?: string;
+}
+
+/**
+ * The connection definition a caller supplies to test/create/update. A subset
+ * of `Datasource` — server-managed fields (`origin`) are never accepted from
+ * the client.
+ */
+export interface DatasourceDraft {
+  name: string;
+  label?: string;
+  driver: string;
+  schemaMode?: 'managed' | 'external' | 'validate-only';
+  /** Driver-specific connection config (host, port, database, …). No secrets. */
+  config?: Record<string, unknown>;
+  /** External federation settings (required when schemaMode != 'managed'). */
+  external?: Record<string, unknown>;
+  pool?: Record<string, unknown>;
+  active?: boolean;
+}
+
+/** Result of probing a connection (live driver connect + cheap round-trip). */
+export interface TestConnectionResult {
+  ok: boolean;
+  /** Round-trip latency of the probe, when the connection succeeded. */
+  latencyMs?: number;
+  /** Driver-reported server version, when available. */
+  serverVersion?: string;
+  /** Human-readable failure reason, when `ok === false`. */
+  error?: string;
+}
+
+/** A datasource with its provenance and current health (no secrets). */
+export interface DatasourceSummary {
+  name: string;
+  label?: string;
+  driver: string;
+  schemaMode: 'managed' | 'external' | 'validate-only';
+  origin: DatasourceOrigin;
+  active: boolean;
+  /** Validation health: `unvalidated` until the first validate/test runs. */
+  status: 'ok' | 'error' | 'unvalidated';
+  /** Package id that defines a code-origin datasource (omitted for runtime). */
+  definedIn?: string;
+  /** True when a runtime row is shadowed by a code definition of the same name. */
+  conflictsWithCode?: boolean;
+}
+
+/**
+ * Runtime datasource lifecycle service. Registered into the kernel as the
+ * `'datasource-admin'` service; consumed by the REST layer and Studio wizard.
+ */
+export interface IDatasourceAdminService {
+  /** List every datasource (code + runtime) with provenance and health. */
+  listDatasources(): Promise<DatasourceSummary[]>;
+
+  /**
+   * Probe a connection without persisting anything. Accepts an unsaved draft
+   * so the wizard can validate credentials before "Save".
+   */
+  testConnection(input: DatasourceDraft, secret?: SecretInput): Promise<TestConnectionResult>;
+
+  /**
+   * Persist a new runtime datasource (`origin: 'runtime'`, environment-scoped).
+   * Rejects when a code-defined datasource of the same name exists.
+   */
+  createDatasource(input: DatasourceDraft, secret?: SecretInput): Promise<DatasourceSummary>;
+
+  /**
+   * Patch an existing runtime datasource. Rejects for code-defined datasources.
+   * Passing `secret` re-wraps the stored credential.
+   */
+  updateDatasource(
+    name: string,
+    patch: Partial<DatasourceDraft>,
+    secret?: SecretInput,
+  ): Promise<DatasourceSummary>;
+
+  /**
+   * Remove a runtime datasource. Rejects for code-defined ones and while
+   * objects are still bound to it.
+   */
+  removeDatasource(name: string): Promise<void>;
+}

package/src/contracts/datasource-driver-factory.ts

@@ -0,0 +1,77 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * IDatasourceDriverFactory — host-provided capability that builds a live driver
+ * from a connection spec (ADR-0015 Addendum §3.5).
+ *
+ * The framework deliberately ships no universal "driver-by-id" registry —
+ * concrete drivers (`SqlDriver`, `MongoDBDriver`, `TursoDriver`, …) are
+ * constructed by the host stack and registered as live connections. The
+ * runtime-datasource lifecycle (`IDatasourceAdminService`) needs to build a
+ * driver from an *unsaved* draft — to probe a connection before "Save", and to
+ * hot-register a pool after create/update — so the host exposes this factory
+ * as the `'datasource-driver-factory'` service.
+ *
+ * When no factory is registered, or none `supports()` a given driver id, the
+ * admin service degrades gracefully: `testConnection` returns
+ * `{ ok: false, error }` and create/update skip hot pool registration (the
+ * driver is picked up on the next boot instead).
+ *
+ * Security: the cleartext `secret` on {@link DatasourceConnectionSpec} is used
+ * only to open the live connection. Factories MUST NOT persist or log it.
+ */
+
+/** Everything needed to construct one live driver connection. */
+export interface DatasourceConnectionSpec {
+  /** Datasource name, when building for an existing/named datasource. */
+  name?: string;
+  /** Driver id (e.g. `'postgres'`, `'sqlite'`, `'mongodb'`). */
+  driver: string;
+  /** Driver-specific connection config (host, port, database, …). No secrets. */
+  config: Record<string, unknown>;
+  /** Cleartext secret (password / DSN) injected for this connection only. */
+  secret?: string;
+  /** External federation settings (timeouts, allowed schemas, …). */
+  external?: Record<string, unknown>;
+  /** Connection pool settings. */
+  pool?: Record<string, unknown>;
+}
+
+/**
+ * A live (or lazily-connecting) driver handle. Intentionally structural and
+ * fully optional so any concrete driver satisfies it — the admin service uses
+ * whatever capabilities are present and skips the rest.
+ */
+export interface DatasourceDriverHandle {
+  /** Open the connection / pool. */
+  connect?(): Promise<void>;
+  /** Close the connection / pool. */
+  disconnect?(): Promise<void>;
+  /** Cheap liveness round-trip (preferred for probes). */
+  ping?(): Promise<unknown>;
+  /** Introspect the live schema (fallback probe when `ping` is absent). */
+  introspectSchema?(): Promise<unknown>;
+  /** Liveness check on the underlying engine driver (probe fallback). */
+  checkHealth?(): Promise<boolean>;
+  /** Driver-reported server version, when available. */
+  serverVersion?(): Promise<string | undefined>;
+  /**
+   * Escape hatch: the concrete engine driver to hand to
+   * `IDataEngine.registerDriver()` when hot-registering a pool. When present
+   * the admin service registers *this* (whose `.name` must equal the
+   * datasource name for routing) instead of the handle itself; absent ⇒ the
+   * handle is assumed to be the driver. Never serialized.
+   */
+  driver?: unknown;
+}
+
+/** Host-provided factory that builds drivers from connection specs. */
+export interface IDatasourceDriverFactory {
+  /** True if this factory can build a driver for the given driver id. */
+  supports(driverId: string): boolean;
+  /**
+   * Build a driver instance for the spec. Implementations may return a
+   * not-yet-connected handle; the caller calls `connect()` when needed.
+   */
+  create(spec: DatasourceConnectionSpec): Promise<DatasourceDriverHandle> | DatasourceDriverHandle;
+}

package/src/contracts/index.ts

@@ -0,0 +1,18 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+// Datasource lifecycle + driver-factory contracts (ADR-0015 Addendum).
+// Moved out of `@objectstack/spec` so the open framework no longer ships them.
+export type {
+  DatasourceOrigin,
+  SecretInput,
+  DatasourceDraft,
+  TestConnectionResult,
+  DatasourceSummary,
+  IDatasourceAdminService,
+} from './datasource-admin-service.js';
+
+export type {
+  DatasourceConnectionSpec,
+  DatasourceDriverHandle,
+  IDatasourceDriverFactory,
+} from './datasource-driver-factory.js';