platform-profiles — unified deployment profiles

@demystify/platform-profiles (TS) · demystify-platform-profiles (Py) · v0.2.0 · MIT

What it is / when to use it

One typed source for the cloud / onprem / demo deployment shapes that all six modules used to duplicate (DB driver + tenancy, Redis, provider aliases, residency, feature flags). Modules load a profile instead of re-deriving config from scattered env vars, and copy the canonical tenancy migration SQL from here instead of shipping their own. Leaf package (dep: zod / pydantic only). Keyless, offline, deterministic.

The Profile shape

type Profile = {
  name: "cloud" | "onprem" | "demo";
  db: { driver: "pglite"|"postgres"|"supabase"; tenancyProfile: "vanilla"|"supabase"; urlEnv: string; poolMax: number };
  redis: { enabled: boolean; driver: "memory"|"redis"; urlEnv: string };
  providers: { mode: "mock"|"gateway"|"direct"; aliases: Record<string, string> };  // alias -> "provider:model"
  residency: "standard" | "strict";
  features: Record<string, boolean>;
};

| profile | db | redis | providers | residency | offline | |---|---|---|---|---|---| | cloud | postgres · supabase tenancy · pool 20 | redis | gateway · openai/anthropic/deepgram/elevenlabs | standard | no | | onprem | postgres · vanilla tenancy · pool 10 | redis | gateway · all local:* models | strict | no | | demo | pglite · vanilla tenancy · pool 1 | memory (disabled) | mock · all mock:* | standard | yes |

SDK usage

import { loadProfile, tenancySqlFor } from "@demystify/platform-profiles";
const profile = loadProfile("onprem", process.env);      // env overlays defaults
const sqlFile = tenancySqlFor(profile);                  // "profiles/vanilla.sql"

from demystify_platform_profiles import load_profile, tenancy_sql_for
import os
profile = load_profile("onprem", os.environ)
sql_file = tenancy_sql_for(profile)                      # "profiles/vanilla.sql"

Env overlay (precedence: explicit env > profile default)

| env var | overlays | |---|---| | DMSTFY_RESIDENCY | residency (standard|strict) | | DMSTFY_DB_DRIVER | db.driver | | DMSTFY_DB_POOL_MAX | db.poolMax (int > 0) | | DMSTFY_PROVIDERS_MODE | providers.mode | | DMSTFY_REDIS_ENABLED | redis.enabled; else REDIS_URL present ⇒ enabled + driver=redis | | DMSTFY_FEATURE_INTROSPECTION_CACHE | features.introspectionCache | | DMSTFY_FEATURE_SPAN_EXPORTER | features.spanExporter | | DMSTFY_FEATURE_DASHBOARD | features.dashboardEnabled | | DMSTFY_FEATURE_OFFLINE | features.offline |

After overlay, strict residency strips every cloud-only provider alias (openai, anthropic, deepgram, elevenlabs, cartesia, google) so a strict deployment physically cannot egress to a cloud provider.

Per-module env mapping (what each profile field sets)

Each module maps profile fields onto its existing env vars at boot (module-side glue, not done here):

| Profile field | module env it sets | |---|---| | db.urlEnv (+ driver) | DATABASE_URL (pglite path in demo) | | db.tenancyProfile | migration --profile (vanilla|supabase) | | redis.enabled/urlEnv | REDIS_URL / DMSTFY_<MODULE>_<SEAM>_DRIVER=redis\|memory | | providers.mode | DMSTFY_AUTH_MODE + gateway data-plane driver (mock|gateway) | | providers.aliases | model-alias → concrete resolution the gateway/router uses | | residency | disables cloud-only providers; toggles egress allowlists | | features.* | INTROSPECTION_CACHE_*, span-exporter wiring, dashboard mount |

Migrations & platform profiles (canonical tenancy SQL)

This package ships the single canonical pair (CONVENTIONS.md §3): profiles/supabase.sql (defines app.current_tenant_id() via auth.jwt()) and profiles/vanilla.sql (via current_setting('app.tenant_id')). A profile binds to one via db.tenancyProfile; tenancySqlFor(profile) returns the file path. Modules copy/symlink these instead of duplicating them; keep the pair in sync when either changes. auth.jwt( lives only in supabase.sql — the §7 boundary grep is satisfied.

Testing

make -C packages/platform-profiles setup lint test build. Unit only (offline). Parity: TS and Py serialize PROFILES and must equal fixtures/profiles.json, and both replay fixtures/overlay-cases.json through the loader identically.

v1 scope

Three profiles, env overlay, residency egress rule, tenancy SQL binding. No secret resolution (only env var names are stored, never values) and no per-module env emission (module glue owns that).