Skip to content
ContractSpec
Start here

Package manual · integrations

·Delivery, infrastructure and runtime operations

integration.runtime-managed

Managed runtime compatibility wrapper for Builder.

integrationsintegrationv2.0.5experimentalservernode
@lssm-tech/integration.runtime-managed
bun add @lssm-tech/integration.runtime-managed
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Managed runtime compatibility wrapper for Builder, plus the managed database runtime preset (./database).

createDatabaseRuntime()

createDatabaseRuntime(options) composes the governed Postgres provider, the O2 observability binding, tenant-scoped RLS access, and the pre-bound governed read / relational-read / mutation resolvers into one preset. It returns:

memberdescription
providerTenant-scoped DatabaseProvider (ambient tenant; fail-closed when none)
governedQueryPre-bound resolver factory (data-view and relational descriptors)
governedMutationPre-bound executeGovernedMutation
withTenant(id)Returns a slice bound to a fixed tenant id
close()Closes the underlying pool once
ts
import { createDatabaseRuntime } from '@lssm-tech/integration.runtime-managed/database';

const db = createDatabaseRuntime({
  connection: { connectionString: process.env.DATABASE_URL },
  pooler: 'transaction-pooler',
  instrumentation, // lib.observability Instrumentation facade (optional)
});

const tenant = db.withTenant('tenant-42');
const list = tenant.governedQuery({ descriptor }); // (envelope, ctx) => ContractResult
await tenant.governedMutation(mutationDescriptor);

Tenant scoping (RLS, Critic N6)

The raw provider is never exposed. Every read/write runs inside a transaction that first issues set_config('app.tenant_id', <id>, true), so Postgres RLS policies see the active tenant. The top-level provider resolves the tenant from resolveTenantId (or the auth seam) per call and fails closed when no tenant context is present; use withTenant(id) in server contexts that already know the tenant. TransportContext.principal is carried onto resolver ctx and never stripped (AC14); policyDecisionRef / policy.auth enforcement stays in the handlers.

Pooler modes (AC3)

pooler selects connection sizing and SSL. Prepared statements are always disabled — SupabasePostgresProvider hard-sets prepare: false, which the Supabase transaction pooler (pgBouncer transaction mode) requires.

modemaxConnectionssslModenotes
transaction-pooler1requireDefault. pgBouncer txn mode; no prepared stmts.
session-pooler10requireBackend held per connection for the session.
direct10preferDirect Postgres connection (no pooler).

Override sizing/SSL via connection.maxConnections / connection.sslMode.

Observability (O2)

Pass an instrumentation (the lib.observability Instrumentation facade) and each governed read/write emits one span plus a database.query / database.mutation duration metric. The tenant set_config statement is classified as a session statement and excluded from the data-latency histograms.

Relationships

THIS PACKAGEintegration.runtime-managed7 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

8 declarations

Declared capabilities

Integration Runtime Managed

Managed runtime compatibility wrapper for Builder.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lint:checknode ../../../scripts/biome.cjs check .
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit