demystify-platform-profiles 0.2.0

Unified Demystify deployment profiles (Python mirror): typed profile models, the three canonical profiles as data, env-overlay loader, and the canonical tenancy migration profile pair.

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).