feat(schema): provision schema externally; drop runtime DDL and defaults seed

CHANGELOG.md

@@ -1,5 +1,49 @@
 # Lib-systemplane Changelog
 
+## [Unreleased]
+
+### Changed
+
+- **lib-systemplane no longer creates its schema or seeds defaults at
+  runtime.** The Postgres store and the multi-tenant `Manager` previously ran
+  `CREATE TABLE` / `CREATE FUNCTION` / `CREATE TRIGGER` and an
+  `INSERT ... ON CONFLICT DO NOTHING` defaults seed on first use
+  (`Store.Start` / `OnTenantActivated`). Those runtime DDL/seed paths are
+  removed. Consumers provision `systemplane_entries` (plus
+  `systemplane_notify_v3()` and the INSERT/DELETE and UPDATE NOTIFY triggers)
+  and any default values externally — e.g. via their migration pipeline —
+  using the DDL published by `SchemaSQL()` / `DefaultSeedSQL()`. The runtime
+  database role needs only DML (`SELECT`/`INSERT`/`UPDATE`/`DELETE`) +
+  `LISTEN`; it no longer needs `CREATE` on the schema. This aligns with the
+  least-privilege per-tenant roles handed back by the tenant-manager (which
+  reject runtime DDL with `permission denied for schema ... (42501)`). No
+  current consumers depend on the removed runtime bootstrap, so this is a
+  behavior change with no expected real-world breakage.
+- Warm-load (`OnTenantActivated`) now tolerates a not-yet-provisioned table:
+  if `systemplane_entries` does not exist yet (SQLSTATE `42P01`) it logs at
+  WARN and proceeds with an empty cache instead of failing activation;
+  LISTEN/poll refreshes the cache once the consumer's migration creates the
+  table. Reads return not-found / zero-value as before.
+
+### Removed
+
+- Postgres store: `runSchema` and the `CREATE ...` DDL builders, the
+  `ensureSchema` / `schemaOnce` / `schemaErr` lazy-bootstrap machinery, and
+  the `Start`/`resolveDB` calls into them.
+- Manager: `runSchemaAndSeed`, `runSchema`, and the runtime `seedDefaults`
+  defaults seed.
+
+### Unchanged
+
+- `SchemaSQL()` and `DefaultSeedSQL()` are intact and are now the ONLY way the
+  schema and defaults are expressed, for consumers to vendor into migrations.
+
+> Recommended version: **v1.7.0** (next beta `v1.7.0-beta.1`) — minor bump
+> continuing the v1.6.x line that introduced `SchemaSQL()` / `DefaultSeedSQL()`.
+> Tag owned by the maintainer; not tagged here.
+
+---
+
 ## [1.5.0](https://github.com/LerianStudio/lib-systemplane/releases/tag/v1.5.0)
 
 - **Features**
@@ -35,8 +79,9 @@ Contributors: @bedatty, @fredcamaral, @jeffersonrodrigues92
   identical v1.4.0 behaviour.
 - Schema bootstrap + defaults seed via `INSERT ... ON CONFLICT DO NOTHING`
   happen at `OnTenantActivated` time. Operator-set values are never
-  overwritten. This removes the need for hand-rolled plugin-side migrations
-  that seeded systemplane defaults.
+  overwritten. (Superseded by the Unreleased change above: runtime schema
+  creation and the defaults seed were removed — provision the schema and
+  defaults externally via `SchemaSQL()` / `DefaultSeedSQL()`.)
 - Six new OpenTelemetry metrics: `systemplane.manager.tenants_active`,
   `cache_entries`, `notify_received_total`, `listen_disconnects_total`,
   `warmload_latency_seconds`, `get_cache_hits_total`. Tenant-id cardinality

CLAUDE.md

@@ -58,7 +58,7 @@ These are external module imports. Do not rewrite them to in-repo paths. Do not
 The Client runs in one of two modes selected at construction:
 
 - **Single-tenant** (default). The constructor receives a non-nil `*sql.DB` / `*mongo.Client`. Reads serve from an in-process cache; writes upsert through the store and update the cache. The backend's changefeed (LISTEN/NOTIFY on Postgres, change stream on MongoDB) drives invalidation and fires `OnChange` subscribers.
-- **Multi-tenant** (opt-in via `WithMultiTenantEnabled()`). DB/client may be nil. Every read/write resolves the tenant database from `ctx` via `tmcore.GetPGContext(ctx, module)` / `tmcore.GetMBContext(ctx, module)` (`lib-commons/v5/commons/tenant-manager/core`). The lib lazily runs `CREATE TABLE IF NOT EXISTS` (Postgres) / index/collection bootstrap (MongoDB) once per resolved tenant database via a `sync.Map`-backed `sync.Once` cache. No in-process cache. No LISTEN/NOTIFY. `OnChange` returns `ErrNotSupportedInMultiTenant`. Callers wire `tenant-manager/middleware.TenantMiddleware` (with `WithPG(...)` or `WithMB(...)` and a matching module name) before the lib's handlers.
+- **Multi-tenant** (opt-in via `WithMultiTenantEnabled()`). DB/client may be nil. Every read/write resolves the tenant database from `ctx` via `tmcore.GetPGContext(ctx, module)` / `tmcore.GetMBContext(ctx, module)` (`lib-commons/v5/commons/tenant-manager/core`). For Postgres the lib performs NO runtime schema provisioning — `systemplane_entries` plus its NOTIFY trigger function/triggers must be created externally via `SchemaSQL()` / `DefaultSeedSQL()` (e.g. the consumer's migration pipeline); the runtime role only needs DML + `LISTEN`. (MongoDB still bootstraps its collection/indexes lazily once per resolved tenant database via a `sync.Map`-backed `sync.Once` cache.) No in-process cache. No LISTEN/NOTIFY. `OnChange` returns `ErrNotSupportedInMultiTenant`. Callers wire `tenant-manager/middleware.TenantMiddleware` (with `WithPG(...)` or `WithMB(...)` and a matching module name) before the lib's handlers.
 
 ### Storage shape
 

README.md

@@ -26,7 +26,28 @@ The library supports two modes; pick at construction time:
 | Single-tenant | `db *sql.DB` / `*mongo.Client` | In-process cache | Through cache + store | LISTEN/NOTIFY (Postgres) or change stream (MongoDB) |
 | Multi-tenant  | May be nil | Resolved per-call via tenant-manager ctx | Same | Disabled — `OnChange` returns `ErrNotSupportedInMultiTenant` |
 
-In multi-tenant mode the library does NOT hold an in-process cache. Every `Get` reads through the resolved tenant database. The lib expects the caller to wire `lib-commons/v5/commons/tenant-manager/middleware.TenantMiddleware` with `WithPG(pgManager, "<module>")` (Postgres) or `WithMB(mongoManager, "<module>")` (MongoDB) where `<module>` matches the lib's `WithModule(...)` option (default `"systemplane"`). The middleware populates the request context; the lib calls `tmcore.GetPGContext` / `tmcore.GetMBContext` to resolve the tenant database, lazily ensures the schema on first use per database, and runs the read/write against that handle.
+In multi-tenant mode the library does NOT hold an in-process cache. Every `Get` reads through the resolved tenant database. The lib expects the caller to wire `lib-commons/v5/commons/tenant-manager/middleware.TenantMiddleware` with `WithPG(pgManager, "<module>")` (Postgres) or `WithMB(mongoManager, "<module>")` (MongoDB) where `<module>` matches the lib's `WithModule(...)` option (default `"systemplane"`). The middleware populates the request context; the lib calls `tmcore.GetPGContext` / `tmcore.GetMBContext` to resolve the tenant database and runs the read/write against that handle.
+
+> **Provisioning (Postgres).** The library no longer creates its schema or seeds defaults at runtime. Provision `systemplane_entries` (plus the `systemplane_notify_v3()` trigger function and the NOTIFY triggers) and any defaults externally — e.g. via your migration pipeline — using the DDL published by [`SchemaSQL()` / `DefaultSeedSQL()`](#schema-provisioning). The runtime database role only needs DML (`SELECT`/`INSERT`/`UPDATE`/`DELETE`) + `LISTEN`; it does NOT need `CREATE` on the schema.
+
+## Schema provisioning
+
+`lib-systemplane` does not run any DDL or defaults seed at runtime (single- or multi-tenant). The Postgres schema and defaults are published as importable artifacts so consumers can fold them into their own migration pipeline:
+
+```go
+// systemplane.SchemaSQL() returns the full idempotent DDL:
+//   - CREATE TABLE IF NOT EXISTS systemplane_entries (...)
+//   - CREATE OR REPLACE FUNCTION systemplane_notify_v3() ...
+//   - the INSERT/DELETE and UPDATE NOTIFY triggers on the
+//     systemplane_changes channel
+ddl := systemplane.SchemaSQL()
+
+// systemplane.DefaultSeedSQL() returns neutral runtime_config defaults
+// inserted with ON CONFLICT (namespace, "key") DO NOTHING.
+seed := systemplane.DefaultSeedSQL()
+```
+
+Run both through a privileged role during provisioning (e.g. as a migration executed by your migrate-up step or by the tenant-manager during per-tenant database provisioning). At runtime the library only reads, writes values (DML), and — in single-tenant mode — runs `LISTEN`, so the runtime role can be least-privilege with no `CREATE` on the schema. If the table has not been provisioned yet when a multi-tenant `Manager` activates a tenant, warm-load logs a warning and proceeds with an empty cache rather than failing; the cache refreshes via LISTEN/poll once the migration creates the table.
 
 ## Single-tenant Quickstart — PostgreSQL
 
@@ -275,7 +296,7 @@ func run() error {
 }
 ```
 
-In multi-tenant mode the lib lazily runs `CREATE TABLE IF NOT EXISTS` (Postgres) or its MongoDB equivalent once per tenant database, the first time a request touches that database. Calling `OnChange` returns `ErrNotSupportedInMultiTenant`.
+In multi-tenant mode the lib does NOT provision schema at runtime for Postgres — the `systemplane_entries` table and its NOTIFY triggers must be created externally (see [Schema provisioning](#schema-provisioning)) before the lib reads or writes. Calling `OnChange` returns `ErrNotSupportedInMultiTenant`.
 
 ## Admin HTTP routes
 

examples/manager/main.go

@@ -64,8 +64,11 @@ func main() {
 
 	defer func() { _ = client.Close() }()
 
-	// 2. Register every runtime configuration key. Defaults are seeded
-	//    per tenant by the Manager on OnTenantActivated.
+	// 2. Register every runtime configuration key. The Manager does NOT seed
+	//    defaults at runtime — provision the schema and any defaults externally
+	//    via systemplane.SchemaSQL() / DefaultSeedSQL() (e.g. your migration
+	//    pipeline). OnTenantActivated warm-loads existing values and opens
+	//    LISTEN; a not-yet-provisioned table is tolerated (empty cache).
 	if err := client.Register("ledger", "retries", 3, systemplane.WithDescription("retry count")); err != nil {
 		fail("Register retries", err)
 	}

internal/manager/connector.go

@@ -18,7 +18,8 @@ import (
 // substitute a fake implementation.
 type Connector interface {
 	// ResolveDB returns the tenant's primary database handle. Used for
-	// schema bootstrap, defaults seed, warm-load and NOTIFY refresh reads.
+	// warm-load and NOTIFY refresh reads. The schema is provisioned
+	// externally; the Manager never issues DDL through this handle.
 	ResolveDB(ctx context.Context, tenantID string) (dbresolver.DB, error)
 
 	// ResolveDSN returns the connection string used by pgx.Connect to open

internal/manager/lifecycle.go

@@ -14,11 +14,13 @@ import (
 
 // OnTenantActivated bootstraps systemplane state for tenantID.
 //
-// Slice 3+: ensures the systemplane schema exists, seeds defaults via
-// INSERT ON CONFLICT DO NOTHING, opens the LISTEN goroutine, and warm-loads
-// every registered key into the cache. Slice 1 records the tenant in
-// perTenant so subsequent Get calls observe an empty cache for it (which
-// still falls through to the DB).
+// It warm-loads every registered key into the per-tenant cache and opens the
+// LISTEN goroutine. It does NOT create the schema or seed defaults — those are
+// provisioned externally by the consumer's migration pipeline (see
+// internal/manager/schema.go and the root package's SchemaSQL() /
+// DefaultSeedSQL()). Warm-load tolerates a not-yet-provisioned table: it logs
+// and proceeds with an empty cache so a provisioning race never wedges
+// activation; LISTEN/poll refreshes the cache once the table exists.
 func (m *Manager) OnTenantActivated(ctx context.Context, tenantID string) error {
 	if m == nil || m.IsClosed() || tenantID == "" {
 		return nil
@@ -49,15 +51,6 @@ func (m *Manager) OnTenantActivated(ctx context.Context, tenantID string) error
 	ts := m.tenantStateFor(tenantID)
 	registered := m.hooks.RegisteredKeys()
 
-	if err := m.runSchemaAndSeed(ctx, db, registered); err != nil {
-		m.logWarn(ctx, "OnTenantActivated: schema/seed failed",
-			log.String("tenant_id", tenantID),
-			log.Err(err),
-		)
-
-		return err
-	}
-
 	if err := m.warmLoad(ctx, db, ts, registered); err != nil {
 		m.logWarn(ctx, "OnTenantActivated: warm-load failed",
 			log.String("tenant_id", tenantID),

internal/manager/listen_integration_test.go

@@ -187,10 +187,7 @@ func TestListen_ReadSingle_NoRows(t *testing.T) {
 	db, raw, _, cleanup := freshTenantDB(t, baseDSN)
 	t.Cleanup(cleanup)
 
-	m := New(nil)
-	if err := m.runSchema(context.Background(), db); err != nil {
-		t.Fatalf("runSchema: %v", err)
-	}
+	provisionTestSchema(t, db)
 	_ = raw
 
 	v, found, err := readSingle(context.Background(), db, "ns", "missing")
@@ -210,10 +207,7 @@ func TestListen_ReadSingle_DecodeError(t *testing.T) {
 	db, raw, _, cleanup := freshTenantDB(t, baseDSN)
 	t.Cleanup(cleanup)
 
-	m := New(nil)
-	if err := m.runSchema(context.Background(), db); err != nil {
-		t.Fatalf("runSchema: %v", err)
-	}
+	provisionTestSchema(t, db)
 
 	// JSONB enforces JSON well-formedness, but our column's bytes path will
 	// still decode any valid JSON. To force a Unmarshal failure we have to
@@ -363,9 +357,7 @@ func TestListen_ApplyEvent_UpsertRowMissing_DeletesEntry(t *testing.T) {
 	tel, _ := newTestTelemetry(t)
 	m.metrics = newMetrics(tel, log.NewNop(), DefaultAggregateTenantThreshold)
 
-	if err := m.runSchema(context.Background(), db); err != nil {
-		t.Fatalf("runSchema: %v", err)
-	}
+	provisionTestSchema(t, db)
 
 	fc := newFakeConnectorInternal()
 	fc.setTenant("t", "", db)
@@ -400,9 +392,7 @@ func TestListen_ApplyEvent_UpsertSuccess_UpdatesCacheAndDispatches(t *testing.T)
 	tel, _ := newTestTelemetry(t)
 	m.metrics = newMetrics(tel, log.NewNop(), DefaultAggregateTenantThreshold)
 
-	if err := m.runSchema(context.Background(), db); err != nil {
-		t.Fatalf("runSchema: %v", err)
-	}
+	provisionTestSchema(t, db)
 
 	if _, err := raw.Exec(`INSERT INTO ` + defaultTable +
 		` (namespace, key, value, updated_by) VALUES ('a', 'k', '"fresh"'::jsonb, 'op')`); err != nil {
@@ -448,9 +438,7 @@ func TestListen_ConsumeAndReconnect_RealNotify(t *testing.T) {
 	tel, _ := newTestTelemetry(t)
 	m.metrics = newMetrics(tel, log.NewNop(), DefaultAggregateTenantThreshold)
 
-	if err := m.runSchema(context.Background(), db); err != nil {
-		t.Fatalf("runSchema: %v", err)
-	}
+	provisionTestSchema(t, db)
 
 	fc := newFakeConnectorInternal()
 	fc.setTenant("t", tDSN, db)
@@ -505,9 +493,7 @@ func TestListen_Reconnect_RecoversAfterDrop(t *testing.T) {
 	tel, _ := newTestTelemetry(t)
 	m.metrics = newMetrics(tel, log.NewNop(), DefaultAggregateTenantThreshold)
 
-	if err := m.runSchema(context.Background(), db); err != nil {
-		t.Fatalf("runSchema: %v", err)
-	}
+	provisionTestSchema(t, db)
 
 	fc := newFakeConnectorInternal()
 	fc.setTenant("t", tDSN, db)