CapsuleDB persistence

Provide PostgreSQL authorization persistence while retaining host ownership of clients, credentials, tenancy, and policy.

@domainkit/capsuledb is an optional PostgreSQL implementation of ManagedDnsConnections.Service. The package owns lifecycle migrations and concurrency semantics; your application owns the SQL client, credentials, tenant/domain bindings, startup, and policy.

Runtime composition

Construct one Effect PgClient from your existing pool. Provide that exact instance to Effect Drizzle, CapsuleDB’s registry preparation, and the capsule layer:

import { PgClient } from "@effect/sql-pg";
import { CredentialCustody, HostBindings, capsule } from "@domainkit/capsuledb";
import { Pg, makeRegistry, prepare } from "capsuledb";
import { Effect } from "effect";

const initialize = Effect.gen(function* () {
  const authorizationCapsule = yield* capsule;
  const registry = yield* makeRegistry({
    capsules: [authorizationCapsule],
    provider: Pg.profile,
  });

  yield* prepare(registry);
  return authorizationCapsule.layer;
});

Run preparation once per execution-environment startup before accepting API or workflow traffic. Do not prepare per request. If preparation fails, keep the entrypoint unready.

CredentialCustody.Service seals and opens StoredCredential values. It must preserve your current ciphertext and rotation/recovery behavior; never give the package keys or plaintext persistence.

HostBindings.Service resolves opaque owner and domain foreign-key references. Its methods execute inside the repository’s active transaction, so implementations can query host tables through Effect Drizzle over the same PgClient. The service must remain stateless and must not capture a request’s organization identity.

Ownership boundary

DomainKit package owns	Host application owns
Authorization aggregate schema and migrations	`PgClient`, pool, and connection lifetime
Atomic connect, attach, detach, rotate, and evidence updates	Identity, tenancy, authorization, and consent
Durable revocation preparation and recovery	Credential encryption, KMS keys, and audit policy
Semantic `ManagedDnsConnections.Service`	Organization/domain tables and foreign-key policy

The package exports no tables, storage rows, Drizzle schema, or query handles. Promise consumers continue through domainkit/promise; persistence remains Effect-first.

Current provider scope

The first tracer supports PostgreSQL only. Transactional Bun SQLite and libSQL support may follow after the PostgreSQL contract is proven. D1 is deferred because bounded AtomicBatch execution cannot yet express the lifecycle’s locking and multi-phase revocation requirements.