Local Stack and Migrations

Add a Configuration Field

1. Add the field to the schema in scripts/stack.ts.
2. Add a complete safe placeholder to config/local-stack.example.json.
3. Update config/local-stack.schema.json when the generated schema is tracked separately.
4. Map it to every required host and container environment file.
5. Update the consuming app’s environment validator.
6. Represent optional values explicitly only where the schema maps empty to undefined.
7. Add stack-generator tests.
8. Update Local Stack.

Generated environment files are outputs. Do not add another local environment contract or ask operators to edit generated files.

Add a Container Service

• Keep the Dockerfile with the owning app.
• Add a health check.
• Wait for healthy infrastructure and one-shot migrations.
• Use Compose DNS names inside containers.
• Make persistent/disposable lifecycle explicit.
• Add bounded idempotent shutdown.
• Log startup, shutdown, failures, and recovery—not every healthy tick.

Agent images use the Debian/glibc Bun base with CA certificates and required shell tooling. Do not move Codex execution to Alpine without proving binary and TLS compatibility.

Add a Migration

1. Update shared and app-local typed contracts.
2. Change schema enums, tables, and relationships in their owning modules.
3. Generate the migration and snapshot.
4. Inspect generated SQL.
5. Update repositories and lifecycle services.
6. Update endpoint validators and OpenAPI.
7. Add migration and repository tests.
8. Verify upgrade behavior against existing state.

Do not edit an already-applied migration to represent a new schema change.

Add a Pinned Vendor Binary

Install it during the owning image build with an exact version and per-architecture checksum. Keep integration binaries below their provider-owned directory and off the global path. Rebuild and verify every affected image.