dedalo-ts-ops-config

name

dedalo-ts-ops-config

description

Configuration discipline and running the Dédalo v7 TS/Bun server in production. Use when reading or adding a DEDALO_* config key, touching process.env / src/config/env.ts (readEnv) / src/config/config.ts / ../private/.env, wiring a COEXISTENCE flag (DEDALO_DIFFUSION_NATIVE, DEDALO_DEV_MODE, DEDALO_SESSION_DB_PATH), or doing anything ops: deploy/systemd, the unix socket + reverse proxy (SERVER_UNIX_SOCKET), graceful shutdown (SIGTERM drain), boot migrations, backups, /health, /api/v1/counters observability, or pool sizing (DB_POOL_MAX). Also for "config key isn't taking effect", config_env_tripwire or coex_tag_tripwire failures, and "how do we run this in production". Authoritative ops doc: engineering/PRODUCTION.md; validation checklist: engineering/STAGING_VALIDATION.md; PHP↔TS shared-DB rules: rewrite/COEXISTENCE.md; config precedence + key census: dedalo-config skill + ../private/sample.env.

Dédalo v7 TS — ops & config discipline

Two jobs: (1) read/add configuration the ONE correct way, (2) run and supervise the Bun server in production. This skill is orientation + the load-bearing rules. The operational detail lives in engineering/PRODUCTION.md (§1–9) — POINT there, do not re-derive it. Measured current state: rewrite/LEDGER.md.

The one config law

readEnv (src/config/env.ts:98) is the ONLY environment reader. NEVER touch process.env outside src/config/.

Why: readEnv implements the precedence chain (real process env > ../private/.env / .env.<host> overlays > catalog default). A raw process.env.KEY bypasses that chain, so a value set in ../private/.env silently does nothing, and the read is untestable (the tripwire's own docstring: it "silently drops the override"). This is exactly the "config key isn't taking effect" bug.

• Typed catalog: src/config/config.ts — every subsystem's keys resolved once at boot into a frozen object. Pool/observability/timeout/backup keys live under config.ops (config.ts:700); the socket path under config.server.unixSocketPath (SERVER_UNIX_SOCKET, config.ts:622).
• Key census: src/config/catalog/ is the single source of truth (type, default, scope, prose — one entry per key). It GENERATES install/sample.env (the copy-paste template the installer drops at ../private/sample.env) and the generated regions of docs/config/{config,config_db}.md. config_docs_tripwire re-renders and demands byte identity, so hand-editing any of the three is a red gate — change the catalog and run bun run config:gen.
• Precedence is exactly process.env > ../private/.env > default. There is no per-host .env.<host> overlay (env.ts implements none) and no dedalo-config skill — both were claimed here and neither exists.

Tripwire: test/unit/config_env_tripwire.test.ts — statically bans process.env in src/ and tools/ outside src/config/. It carries a small subprocess-passthrough allowlist (each entry cites a reason: pg_dump / media binaries / runner child get the whole env). Lowering the count is free; raising it needs a justified allowlist entry. A new key is: (1) declare it in src/config/catalog/<domain>.ts — type, default, scope and the operator prose, all in one entry; (2) read it (a config.* field if it is boot-stable — never sprinkle raw reads if a config.* field will do); (3) classify it in migration_map.ts; (4) bun run config:gen. Steps 1, 3 and 4 are NOT optional: config_docs_tripwire fails on (1) and (4), config_census_tripwire on (3). The catalog prose must be PHP-free — it renders straight into docs/config/config.md, where docs_current_engine_tripwire bans the substring.

Coexistence config (retires at cutover)

These flags exist ONLY because the TS server currently shares a DB with the live PHP oracle (transitional — see the "TS self-contained, not shared" memory). Verified readers:

• DEDALO_DIFFUSION_NATIVE (+ DEDALO_DIFFUSION_NATIVE_ELEMENTS) — routes diffusion to the native TS engine (src/core/resolve/environment.ts:124, src/core/resolve/widget_request.ts:1059, src/diffusion/api/actions.ts:244). Unset → the diffusion tool 404s get_diffusion_info (TS has no legacy route); set it in ../private/.env and restart (memory: "diffusion native flag client 404").
• DEDALO_DEV_MODE (src/core/resolve/environment.ts:35) — drives the DEVELOPMENT_SERVER/SHOW_DEBUG/SHOW_DEVELOPER posture the pre-auth login SW path reads. This posture must be available pre-auth; the S1-19 fix (engineering/WIRE_CONTRACT.md, rewrite/STATUS.md) was a login stall that made the client-test gate unrunnable — do NOT gate dev/login-path env behind isLogged.
• DEDALO_SESSION_DB_PATH (src/core/security/session_store.ts:76,304) — session store override, used for test isolation.

Tripwire: test/unit/coex_tag_tripwire.test.ts (DEC-19/DEC-12) — every source file with a bare-word COEX tag must (1) cite DEC-19 and (2) have a row in rewrite/COEXISTENCE.md. No allowlist: a new coexistence hedge adds its ledger row + DEC citation in the same change. Why: coexistence scaffolding is invisible debt; without the tag+row it never gets torn out at cutover and PHP/TS drift silently against the shared DB.

Running in production

Unix-socket only. Bun.serve listens on SERVER_UNIX_SOCKET (default /tmp/dedalo_ts.sock). A reverse proxy owns TCP/TLS, statics, and media — the app process never binds a port. Full runtime/supervision/proxy config: engineering/PRODUCTION.md §1–3.

Verified behaviors in src/server.ts — do not regress these:

• Graceful shutdown (installShutdownHandlers, ~server.ts:653): SIGTERM → stop accepting → drain in-flight requests within config.ops.shutdownGraceMs → mark undrained media jobs interrupted in their pfiles → close the DB pool → unlinkSync the socket → exit 0. Idempotent latch so a repeated SIGTERM doesn't re-drain. Diffusion RUNNERS survive by design (engineering/PRODUCTION.md §8).
• Double-start socket guard (~server.ts:619): a second startServer must NOT silently unlink the first instance's socket — the guard refuses. Why: two servers on one socket = corrupted request routing.
• Boot migrations (runBootMigrations, install/db/migrate.ts:99): run once, idempotent, a failure logs loudly and aborts boot so no request sees a half-migrated schema. Also reconciles running→interrupted pfiles from the previous process life. Authoritative: engineering/PRODUCTION.md §7 (DEC-17/DEC-19).
• /health (src/core/api/process_health.ts) is DB-checked AND poison-latched: once a boot-order/TDZ ReferenceError poisons the process, /health turns 503 so the watchdog (engineering/PRODUCTION.md §2) recycles it — a plain DB ping alone stayed green while read failed, which is the bug it fixes.
• /api/v1/counters (src/core/api/counters.ts, audit S2-37): session-gated AND global-admin-only; 404s for non-admins (no existence leak). Access log is one structured JSON line per request behind DEDALO_ACCESS_LOG.
• Pool posture (config.ops): DB_POOL_MAX (per-process; cross-process budget in engineering/PRODUCTION.md §4), DB_POOL_ACQUIRE_TIMEOUT_MS, DB_STATEMENT_TIMEOUT_MS.
• Backups (src/core/area_maintenance/backup.ts, S2-35): TS-native pg_dump -F c of the SHARED DB into the TS server's OWN ../private/backups/db (never the PHP dir). The full backup set + restore-test cadence + the other stores: engineering/PRODUCTION.md §6 — point there, do not enumerate here.

Validation (the audit's biggest coverage hole)

Ops is code-verified, not yet failover-tested. Before trusting a deploy, run the checklist in engineering/STAGING_VALIDATION.md — it proves shutdown/restart/failover/health/pool behavior through a REAL restart, which no unit test exercises.

Bun coupling

• Version is pinned: .bun-version = 1.3.9, package.json engines.bun = 1.3.9. Ops surfaces (Bun.serve unix socket, Bun.spawn for media/pg_dump, Bun.sql for postgres+mariadb) are version-sensitive — do not float the version.
• The Bun.sql jsonb/array param trap: a plain object / native array bound into a jsonb param is mis-encoded; the write path routes through encodeForJsonb (src/core/db/json_codec.ts:102, which REJECTS lossy shapes). Full write-path contract: see src/core/db/json_codec.ts + the isolation/caching skill; PHP on the same Postgres is the byte-coexistent oracle.

The meta-rule (audit's central lesson)

Every invariant enforced only by docs/memory was violated in practice; every tripwired boundary held. If you add an ops/config invariant, add its tripwire — otherwise it will rot. This skill's two live rails are config_env_tripwire (no stray process.env) and coex_tag_tripwire (every coexistence hedge is ledgered). Tripwire index: rewrite/LEDGER.md.