@starci/hfs 4.7.31 → 4.7.33

package/templates/app/skeleton/.starcistacks/application-stacks.yaml

@@ -5,10 +5,6 @@ schema: starci/application-stacks@1
 # A GitHub package.json repository URL also enables the managed block.
 sources:
   - repository: "{{project}}"
-backing:
-  primary:
-    provider: external-postgres
-    managed: true
 components:
   core:
     role: service
@@ -27,8 +23,10 @@ components:
     purpose: The single public entry point; TLS state stays on its declared persistent volume.
   postgres:
     role: stateful
+    stateful: true
+    volumes: [postgres-data]
     image: postgres:16@sha256:1a6ab3f5345eb6dbe04a1349529caabdb0ab09293a09590fad07b2246bfa4b54
-    purpose: The full development database; production uses an owner-provisioned external PostgreSQL connection.
+    purpose: PostgreSQL in Docker Linux containers for development and Docker Swarm for production; production credentials use mounted secrets and data stays on its named volume.
 environments:
   dev:
     status: supported
@@ -51,6 +49,7 @@ environments:
       app: { port: 3000 }
       landing: { port: 3002 }
       ingress: { httpPort: 80, httpsPort: 443 }
+      postgres: { replicas: 1, port: 5432 }
     runbook: README.md
     ingress:
       component: ingress
@@ -79,8 +78,8 @@ environments:
         retention: Thirty daily snapshots
         owner: Production operator
         restoreProof: .starcistacks/production/infra/swarm/recovery/restore-proof.md
-      - component: primary
-        target: Provider recovery plus owner-provisioned encrypted off-host database exports
+      - component: postgres
+        target: Owner-provisioned encrypted off-host database exports and postgres-data volume snapshots
         retention: Thirty daily exports
         owner: Production operator
         restoreProof: .starcistacks/production/infra/swarm/recovery/restore-proof.md
@@ -92,8 +91,19 @@ environments:
         where: secrets/primary-db-url
         recipientPolicy: This app's own age recipient configured in .sops.yaml
         keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
+      - name: postgres-password
+        runtimeName: "{{project}}-production-postgres-password-v1"
+        version: 1
+        where: secrets/postgres-password
+        recipientPolicy: This app's own age recipient configured in .sops.yaml
+        keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
+      - name: primary-db-password
+        runtimeName: "{{project}}-production-primary-db-password-v1"
+        version: 1
+        where: secrets/primary-db-password
+        recipientPolicy: This app's own age recipient configured in .sops.yaml
+        keyCustody: SOPS_AGE_KEY in the host's untracked .claude/secret.env
     # What `starci app stack` deploys (verbs: prepare, doctor, deploy, verify, rollback); names and shapes only, never a value.
-    # Add secrets.grants once the real sealed members exist under .starcistacks/production/secrets, and a backup block for stateful volumes.
     deploy:
       stack: {{project}}-production
       # The image registry. The canon scaffold writes `public` (the owner's default: images cost nothing there); the value belongs to the app from now on
@@ -118,6 +128,24 @@ environments:
       volumes:
         - {{project}}-production-ingress-data
         - {{project}}-production-ingress-config-data
+        - {{project}}-production-postgres-data
+      secrets:
+        grants:
+          - service: core
+            filePointers: true
+            from: [{member: primary-db-url}]
+          - service: postgres
+            filePointers: true
+            from: [{member: postgres-password}, {member: primary-db-password}]
+      configs:
+        - name: postgres-init
+          file: infra/swarm/postgres-init.sh
+          env: POSTGRES_INIT_CONFIG
+      # Release tasks: an idempotent write the release owes the data (a catalogue sync, a seed upsert) is declared under tasks and listed in postDeploy.
+      # A deploy runs postDeploy after the stack converged and before verify, which stays read-only. Uncomment and name the real command:
+      # tasks:
+      #   sync-catalogue: {service: core, command: [node, dist/cli.js, catalogue, sync]}
+      # postDeploy: [sync-catalogue]
       verify:
         http:
           - name: core liveness

package/templates/app/skeleton/.starcistacks/dev/README.md

@@ -1,6 +1,6 @@
 # Development stack
 
-The development Docker Compose model contains the core API, the product and landing front ends, and a pinned local PostgreSQL database. Trust authentication is confined to this local, unpublished database.
+Every development dependency runs in Docker Linux containers. This starter's Docker Compose model contains the core API, the product and landing front ends, and a pinned local PostgreSQL database. Compose is an implementation detail; declared dependencies may also use managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts, and local Supabase, when declared, runs through the Supabase CLI. A declared native profile may run app processes locally while dependencies stay in Docker. Trust authentication is confined to this local, unpublished database.
 Starter release images and external secrets must be prepared before starting the container model. Local source development remains available through the app scripts.
 
 | Command | Operation |

package/templates/app/skeleton/.starcistacks/production/README.md

@@ -1,14 +1,15 @@
 # Production stack
 
-The tracked model declares Docker Swarm application services and one digest-pinned Caddy ingress.
-The production database is external PostgreSQL; the owner supplies its least-privilege connection through sealed custody.
+The app and its dependencies run on Docker Swarm; Supabase, when declared, is a hosted service. The tracked model declares the application services, one digest-pinned Caddy ingress and one digest-pinned PostgreSQL service on an internal backing network, with its data on a named persistent volume and credentials supplied through mounted secrets. On the first boot of an empty data volume, PostgreSQL runs the mounted `postgres-init.sh` config to create the `app_be` role with access to this app's database and schema, without superuser, database-creation, role-creation, replication or RLS-bypass privileges. Existing data volumes skip initialization and retain their roles and credentials.
 The model is a deployment declaration. It contains no owner credentials, real DNS receipt, completed release or restore proof. The public records under `.starcistacks/production/infra/swarm/` mark those owner-run operations as pending. Its all-zero application image digests are illustrative and must be replaced before deployment.
 
-The runtime template tracks no encrypted members. Scaffolding generates the declared database member with a placeholder value encrypted to this app's own recipient in `.sops.yaml`. Replace it with `starci app secret set production` using the matching host age identity in untracked local custody. Each Docker secret contains its corresponding key's real value; the API receives it through the declared mounted file.
+The runtime template tracks no encrypted members. Scaffolding generates the declared database connection, application password and PostgreSQL administrator password members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace them with `starci app secret set production` using the matching host age identity in untracked local custody. The sealed connection uses role `app_be`, database `{{project}}` and internal endpoint `postgres:5432`; its URI-encoded password matches the separate `primary-db-password` member. The administrator password is distinct. The API receives only its least-privilege connection; only PostgreSQL receives the two password files for initialization. The non-empty application password contains no line breaks. The service has no TTY: initialization creates the role without a password, then feeds the two `psql` `\password` prompts through stdin using Bash's builtin `printf`, so psql encrypts it before sending SQL. No password travels in an initialization command argument or a plaintext SQL statement.
+
+Bootstrap references reviewed 2026-10-25: the [official PostgreSQL image initialization and Docker secret contract](https://github.com/docker-library/docs/blob/master/postgres/README.md#initialization-scripts), [PostgreSQL 16 psql password handling and SQL interpolation](https://www.postgresql.org/docs/16/app-psql.html), and its [password command](https://github.com/postgres/postgres/blob/REL_16_STABLE/src/bin/psql/command.c) and [prompt stdin fallback](https://github.com/postgres/postgres/blob/REL_16_STABLE/src/common/sprompt.c). First-release verification must confirm fresh-volume initialization, `app_be` privileges, health-gated startup and unchanged credentials after data-volume reuse; this source template records no live verification result.
 
 | Command | Operation |
 | --- | --- |
-| prepare | Owner provisions the Swarm, node label, database, DNS and real sealed secret members, then runs `starci app stack prepare --env production --execute` to create the missing external volumes (the one-time swarm initialization stays an owner-approved step: `--init-swarm` with `--execute`, after the owner's explicit approval). Release images are built and pushed by the managed the managed stack-deploy workflow. |
+| prepare | Owner provisions the Swarm, node label and DNS, seals the matching application connection/password and distinct administrator password, then runs `starci app stack prepare --env production --execute` to create the missing external volumes (the one-time swarm initialization stays an owner-approved step: `--init-swarm` with `--execute`, after the owner's explicit approval). The single up path below starts PostgreSQL and initializes `app_be` automatically on a new empty data volume. Release images are built and pushed by the managed stack-deploy workflow. |
 | doctor | Run `starci app stack doctor --env production` (read-only): docker, swarm, volumes, services, secrets, configs and the release pointers on the intended manager. |
 | up | After preparation and review, run the manual stack-deploy workflow (Actions, deploy stack) on a release tag; it builds the images and runs `starci app stack deploy --env production --image <service>=<repository>@sha256:<digest> --source-sha <sha> --execute`. A dry run is `starci app stack render` or `deploy` without `--execute`. |
 | status | Run `starci app stack doctor --env production`, or `starci app stack converge --env production --since <ISO time>` to inspect desired and running replicas plus update state. |
@@ -22,16 +23,16 @@ Every item is pending. Swarm initialization, provider URIs, DNS changes and key
 
 | Area | Required owner action and evidence |
 | --- | --- |
-| Swarm and placement | Initialize the intended manager; label the intended stateful node `{{project}}=production`. Only that node owns the external ingress volumes. |
+| Swarm and placement | Initialize the intended manager; label the intended stateful node `{{project}}=production`. Only that node owns the external ingress and PostgreSQL data volumes. |
 | DNS | Replace the reserved `example.invalid` hosts consistently in the manifest, Caddyfile and public configuration; publish address records for the product, API and landing hosts and retain a provider receipt in `.starcistacks/production/infra/swarm/owner-actions.md`. |
 | TLS | Caddy issues certificates after real DNS resolves. Provision `{{project}}-production-ingress-data` and `{{project}}-production-ingress-config-data` on the selected node; retain an issuance and renewal receipt in `.starcistacks/production/infra/swarm/owner-actions.md`. |
-| Database | Provision external PostgreSQL and its least-privilege application role. Record the provider URI and recovery owner without copying credentials here. |
-| Secret custody | Replace the generated placeholder with the real value in the manifest's declared `.starcistacks/production/secrets/primary-db-url.enc`; record its key in `.starcistacks/production/runtime/env/KEYS.md`. The age identity stays only in the host's untracked `.claude/secret.env`. |
-| External secrets | Materialize the sealed members in owner custody and create `{{project}}-production-primary-db-url-v1`. The API reads mounted files; rotation creates new versioned names before updating the model. |
+| Database | Prepare creates `{{project}}-production-postgres-data` on the declared stateful node; the normal up path starts PostgreSQL and initializes `app_be` on its first empty-volume boot. Seal the matching role, database and password described above before up. Existing databases retain their current roles and credentials; initialization never rewrites them. Record the recovery owner without copying credentials here. |
+| Secret custody | Replace generated placeholders in `.starcistacks/production/secrets/primary-db-url.enc`, `primary-db-password.enc` and `postgres-password.enc` with the matching application connection/password and distinct administrator password; record their key names in the environment roster. The age identity stays only in the host's untracked `.claude/secret.env`. |
+| External secrets | Materialize the sealed members in owner custody and create `{{project}}-production-primary-db-url-v1`, `{{project}}-production-primary-db-password-v1` and `{{project}}-production-postgres-password-v1`. The API and PostgreSQL read their separately granted mounted files. A later credential rotation updates the actual database role under owner authority and rotates matching immutable secrets; changing a mounted file does not rerun first-boot initialization. |
 | Public build configuration | Build the front end with its declared public site and GraphQL URLs. Public browser values stay outside sealed secret custody. |
 | Immutable release | Replace the illustrative all-zero application digests in the manifest, model and `.starcistacks/production/infra/swarm/releases/images.lock.yaml` with the verified release digests. Store each rendered release under `/srv/{{project}}/releases/<digest>`. Retain the last accepted record in `.starcistacks/production/infra/swarm/releases/previous.yaml`, then move the pointer and update `.starcistacks/production/infra/swarm/releases/current.yaml` after verification. |
 | Rollback | Retain the previous model and images, redeploy that model if convergence or health fails, and record the resulting convergence receipt. Database changes follow an expand/contract sequence. |
-| Backup | Provision the manifest's thirty daily encrypted off-host database exports and ingress-volume snapshots. Record the actual destination and encryption custody in `.starcistacks/production/infra/swarm/recovery/restore-proof.md`; the production operator owns both components. |
+| Backup | Provision the manifest's thirty daily encrypted off-host database exports and PostgreSQL and ingress-volume snapshots. Record the actual destination and encryption custody in `.starcistacks/production/infra/swarm/recovery/restore-proof.md`; the production operator owns both components. |
 | Restore proof | Perform a restore into isolated infrastructure, verify the restored database and ingress state, and attach a dated receipt with artifact digests to `.starcistacks/production/infra/swarm/recovery/restore-proof.md`. Its initial record is pending; no restore has been run by scaffolding. |
 
 No host scheduler is installed. Scheduled application work belongs to the back-end scheduler or an explicitly declared replicated job.

package/templates/app/skeleton/.starcistacks/production/infra/swarm/postgres-init.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# PostgreSQL runs this config only when its data volume is empty.
+set -euo pipefail
+
+PRIMARY_DB_PASSWORD="$(cat "${PRIMARY_DB_PASSWORD_FILE:?}")"
+if [[ -z "$PRIMARY_DB_PASSWORD" || "$PRIMARY_DB_PASSWORD" == *$'\n'* || "$PRIMARY_DB_PASSWORD" == *$'\r'* ]]; then
+    builtin printf '%s\n' 'The application password must be non-empty and contain no line breaks.' >&2
+    exit 1
+fi
+psql --no-psqlrc --no-password --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" --set ON_ERROR_STOP=1 <<'SQL'
+\getenv app_database POSTGRES_DB
+CREATE ROLE app_be WITH LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS;
+REVOKE ALL ON DATABASE :"app_database" FROM PUBLIC;
+GRANT CONNECT ON DATABASE :"app_database" TO app_be;
+REVOKE CREATE ON SCHEMA public FROM PUBLIC;
+GRANT USAGE, CREATE ON SCHEMA public TO app_be;
+SQL
+# The service has no TTY; psql reads both hidden prompts from this pipe and encrypts the password before sending SQL.
+builtin printf '%s\n%s\n' "$PRIMARY_DB_PASSWORD" "$PRIMARY_DB_PASSWORD" |
+    psql --no-psqlrc --no-password --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" --set ON_ERROR_STOP=1 --command '\password app_be'
+unset PRIMARY_DB_PASSWORD

package/templates/app/skeleton/.starcistacks/production/infra/swarm/recovery/restore-proof.md

@@ -2,6 +2,6 @@
 
 Status: pending owner execution. No backup or restore has been run by scaffolding.
 
-The production operator owns recovery of the external PostgreSQL database and both external ingress volumes, `{{project}}-production-ingress-data` and `{{project}}-production-ingress-config-data`. Provision provider recovery and thirty daily encrypted off-host database exports. Retain thirty daily encrypted off-host snapshots for both ingress volumes.
+The production operator owns recovery of the PostgreSQL service's external named volume `{{project}}-production-postgres-data` and both external ingress volumes, `{{project}}-production-ingress-data` and `{{project}}-production-ingress-config-data`. Provision thirty daily encrypted off-host database exports and PostgreSQL volume snapshots. Retain thirty daily encrypted off-host snapshots for both ingress volumes.
 
 Before relying on the backup policy, restore a database backup and both volume snapshots into isolated infrastructure. Record the actual off-host destination, retention, encryption custody, backup artifact digests, restoration time and operator. Verify database connectivity and the API readiness endpoint, then verify the restored TLS and ingress configuration. Attach the dated result here without credentials.

package/templates/app/skeleton/.starcistacks/production/infra/swarm/releases/images.lock.yaml

@@ -7,3 +7,4 @@ images:
   app: "{{project}}/app:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
   landing: "{{project}}/landing:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
   ingress: caddy:2.10.2@sha256:c3d7ee5d2b11f9dc54f947f68a734c84e9c9666c92c88a7f30b9cba5da182adb
+  postgres: postgres:16@sha256:1a6ab3f5345eb6dbe04a1349529caabdb0ab09293a09590fad07b2246bfa4b54

package/templates/app/skeleton/.starcistacks/production/infra/swarm/stack.yaml

@@ -7,11 +7,7 @@ services:
       NODE_ENV: production
       PORT: "3001"
       HTTP_SECURITY_ALLOWED_ORIGINS: https://{{project}}.example.invalid
-      PRIMARY_DB_URL_FILE: /run/secrets/primary-db-url
-    secrets:
-      - source: primary-db-url
-        target: primary-db-url
-    networks: [app]
+    networks: [app, backing]
     healthcheck:
       test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3001/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
       interval: 30s
@@ -91,6 +87,37 @@ services:
       restart_policy:
         condition: on-failure
         delay: 5s
+  postgres:
+    image: postgres:16@sha256:1a6ab3f5345eb6dbe04a1349529caabdb0ab09293a09590fad07b2246bfa4b54
+    tty: false
+    environment:
+      POSTGRES_DB: "{{project}}"
+    configs:
+      - source: postgres-init
+        target: /docker-entrypoint-initdb.d/10-app-role.sh
+        mode: 0o555
+    volumes: [postgres-data:/var/lib/postgresql/data]
+    networks: [backing]
+    healthcheck:
+      test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "postgres", "-d", "{{project}}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    deploy:
+      replicas: 1
+      placement:
+        constraints: ["node.labels.{{project}} == production"]
+      update_config:
+        parallelism: 1
+        order: stop-first
+        failure_action: rollback
+        monitor: 30s
+      rollback_config:
+        parallelism: 1
+        order: stop-first
+      restart_policy:
+        condition: on-failure
+        delay: 5s
   ingress:
     image: caddy:2.10.2@sha256:c3d7ee5d2b11f9dc54f947f68a734c84e9c9666c92c88a7f30b9cba5da182adb
     configs:
@@ -126,14 +153,29 @@ services:
 networks:
   app:
     driver: overlay
+  backing:
+    driver: overlay
+    internal: true
 secrets:
   primary-db-url:
     external: true
     name: "{{project}}-production-primary-db-url-v1"
+  postgres-password:
+    external: true
+    name: "{{project}}-production-postgres-password-v1"
+  primary-db-password:
+    external: true
+    name: "{{project}}-production-primary-db-password-v1"
 configs:
   ingress-config:
     file: ./Caddyfile
+  postgres-init:
+    external: true
+    name: ${POSTGRES_INIT_CONFIG}
 volumes:
+  postgres-data:
+    external: true
+    name: "{{project}}-production-postgres-data"
   ingress-data:
     external: true
     name: "{{project}}-production-ingress-data"

package/templates/app/skeleton/.starcistacks/production/runtime/env/KEYS.md

@@ -1,14 +1,16 @@
 # Production environment key roster
 
-This inventory declares names, consumers and mounted file paths. Scaffolding seals a generated database placeholder to this app's own recipient. Replace it with the real credential before use; no successful deployment is claimed by scaffolding.
+This inventory declares names, consumers and mounted file paths. Scaffolding seals generated database connection, application password and administrator password placeholders to this app's own recipient. Replace them with real credentials before use; no successful deployment is claimed by scaffolding.
 
 | Key | Consumer |
 | --- | --- |
 | `PORT` | Core API listener |
 | `HTTP_SECURITY_ALLOWED_ORIGINS` | Core API origin allowlist |
-| `PRIMARY_DB_URL` | Core API and CLI primary database connection; the API reads `PRIMARY_DB_URL_FILE` at `/run/secrets/primary-db-url` |
+| `PRIMARY_DB_URL` | Core API and CLI primary database connection; managed deployment sets the API's `PRIMARY_DB_URL_FILE` to `/run/secrets/PRIMARY_DB_URL` from sealed `secrets/primary-db-url.enc` |
+| `POSTGRES_PASSWORD` | PostgreSQL administrator password; managed deployment sets only PostgreSQL's `POSTGRES_PASSWORD_FILE` to `/run/secrets/POSTGRES_PASSWORD` from sealed `secrets/postgres-password.enc` |
+| `PRIMARY_DB_PASSWORD` | First-boot `app_be` role password; managed deployment sets only PostgreSQL's `PRIMARY_DB_PASSWORD_FILE` to `/run/secrets/PRIMARY_DB_PASSWORD` from sealed `secrets/primary-db-password.enc`; it must match the password in the API's sealed connection URI |
 | `NEXT_PUBLIC_SITE_URL` | Product front-end site URL |
 | `NEXT_PUBLIC_GRAPHQL_URL` | Product front-end GraphQL transport |
 | `NEXT_PUBLIC_APP_URL` | Landing front-end product link |
 
-Public front-end configuration is supplied at build time and stays outside sealed custody. Replace the generated private placeholder only in `.starcistacks/production/secrets/primary-db-url.enc`, already declared by the manifest. The versioned external database secret is `{{project}}-production-primary-db-url-v1`.
+Public front-end configuration is supplied at build time and stays outside sealed custody. Replace the generated private placeholders only in the manifest's declared `.starcistacks/production/secrets/primary-db-url.enc`, `primary-db-password.enc` and `postgres-password.enc` members. Their versioned external secrets are `{{project}}-production-primary-db-url-v1`, `{{project}}-production-primary-db-password-v1` and `{{project}}-production-postgres-password-v1`; the API receives its least-privilege connection separately from PostgreSQL's administrator password.

package/templates/app/skeleton/README.md

@@ -22,6 +22,8 @@ Declare `ci.github.repository` and `ci.github.defaultBranch` in `.starcistacks/a
 
 ## Development
 
+Every development dependency runs in Docker Linux containers. Local Supabase, when declared, runs through the Supabase CLI; every other declared dependency runs through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model. This starter uses Compose to run its pinned local PostgreSQL and app services; Compose is an implementation detail. A declared native profile may run the app processes locally while dependencies stay in Docker. In production, the app and its dependencies run on Docker Swarm, except Supabase, which is a hosted service.
+
 ```sh
 npm install
 npm run typecheck

package/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml

@@ -163,6 +163,11 @@ environments:
             from:
               - member: primary-db-url
               - member: supabase-service-role-key
+      # Release tasks: an idempotent write the release owes the data (a catalogue sync, a seed upsert) is declared under tasks and listed in postDeploy.
+      # A deploy runs postDeploy after the stack converged and before verify, which stays read-only. Uncomment and name the real command:
+      # tasks:
+      #   sync-catalogue: {service: api, command: [node, dist/cli.js, catalogue, sync]}
+      # postDeploy: [sync-catalogue]
       verify:
         http:
           - name: api liveness

package/templates/app/skeleton-lite/.starcistacks/dev/README.md

@@ -1,13 +1,13 @@
 # Development stack
 
-The app services may run in a local Docker Swarm; local Supabase is started separately with its CLI and supplies the database and broker. The tracked model contains no self-hosted database.
+Every development dependency runs in Docker Linux containers. Local Supabase starts through its CLI and supplies PostgreSQL, pgvector, Auth and Storage. Every other declared dependency, such as Redis, starts through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model; Compose is an implementation detail. The app services may run in the local Docker Swarm model or through a declared native development profile while dependencies stay in Docker.
 The application image references contain illustrative all-zero digests. Replace them with verified published release digests in the manifest, model and `.starcistacks/dev/infra/swarm/releases/images.lock.yaml` before starting the container model. Replace its starter `SUPABASE_URL` with the local Supabase endpoint reachable from the Swarm node, and seal that local database connection and integration credential; a container cannot use the host's loopback address without owner-configured networking. Local source development remains available through the app scripts.
 
 The runtime template tracks no encrypted members. Scaffolding generates the two declared members with placeholder values encrypted to this app's own recipient in `.sops.yaml`. Replace those values with `starci app secret set dev` using the matching host age identity in untracked local custody. Existing generated envelopes are decryptable with that app identity and can be updated in place. Each Docker secret contains the corresponding key's real value, and the API receives it through its declared mounted file.
 
 | Command | Operation |
 | --- | --- |
-| prepare | Run `npm run db:start` at the app root; obtain the local Supabase connection and Auth configuration. An owner who chooses local Swarm initializes it, labels its node `{{project}}=dev` and provisions the ingress volumes. Replace the reserved development host consistently in the manifest, Caddyfile and public configuration; resolve it to the node and record this in `.starcistacks/dev/infra/swarm/owner-actions.md`. Create the external development secrets named in the model from real sealed members. |
+| prepare | Run `npm run db:start` at the app root; obtain the local Supabase connection and Auth configuration. For a declared Redis, run `npm run redis:create` once, then `npm run redis:start` when using the native app profile. An owner who chooses local Swarm initializes it, labels its node `{{project}}=dev` and provisions the ingress volumes; the model starts its declared Redis with the app. Replace the reserved development host consistently in the manifest, Caddyfile and public configuration; resolve it to the node and record this in `.starcistacks/dev/infra/swarm/owner-actions.md`. Create the external development secrets named in the model from real sealed members. |
 | doctor | From this directory, run `docker stack config -c infra/swarm/stack.yaml`. Confirm image, secret and local Supabase availability. |
 | up | Run `docker stack deploy -c infra/swarm/stack.yaml {{project}}-dev` from this directory after preparation. |
 | status | Run `docker stack services {{project}}-dev`. |

package/templates/app/skeleton-lite/.starcistacks/production/README.md

@@ -1,7 +1,7 @@
 # Production stack
 
 The tracked model declares Docker Swarm application services and one digest-pinned Caddy ingress.
-Supabase supplies PostgreSQL, Auth and pgmq. This stack runs no PostgreSQL, Redis or MongoDB service.
+Hosted Supabase supplies PostgreSQL, pgvector, Auth and Storage. The app and its other dependencies run on Docker Swarm. A Redis service runs only when `hfs.json` `sides.be.backing` declares it for a capability that needs it: one stateful replica with a digest-pinned image, a named volume with a backup entry and its password as a sealed member granted as a Swarm secret (Redis runs `--appendonly yes` with the volume at `/data`). The scaffold declares none; `starci app add queue|job` declares Redis and renders it here.
 The model is a deployment declaration. It contains no owner credentials, real DNS receipt, completed release or restore proof. Public records under `.starcistacks/production/infra/swarm/` explicitly mark those owner-run operations as pending.
 Its application image references contain illustrative all-zero digests; they identify no published image and must be replaced before deployment.
 

package/templates/app/skeleton-lite/README.md

@@ -24,7 +24,7 @@ Declare `ci.github.repository` and `ci.github.defaultBranch` in `.starcistacks/a
 
 ## Development
 
-Start the Docker engine, then run `npm run db:start` to start local Supabase in Docker containers through the Supabase CLI. Configure the local environment and start the API and web app separately using the package scripts for the declared development profile.
+Every development dependency runs in Docker Linux containers. Start local Supabase with `npm run db:start` through the Supabase CLI; start any other declared dependency through its managed `<dep>:create`, `<dep>:start` and `<dep>:stop` scripts or the declared container model. Compose is an implementation detail. Configure the local environment and start the API and web app using the package scripts for the declared development profile. In production, the app and its dependencies run on Docker Swarm, except Supabase, which is a hosted service; Supabase pgvector owns vector search.
 
 ```sh
 npm install

package/templates/be/inbox/platform/client-operation-outcomes.sql.tpl

@@ -0,0 +1,18 @@
+-- Extend the one shared inbox; provider and broker claims keep null client fields.
+alter table public.inbox
+    add column request_fingerprint varchar(64),
+    add column outcome jsonb;
+
+create index inbox_client_retention_idx on public.inbox (claimed_at, source, event_id)
+where source like 'client:%' and request_fingerprint is not null and outcome is not null;
+
+create policy "inbox_app_be_update"
+on public.inbox for update to app_be
+using (source like 'client:%')
+with check (source like 'client:%');
+
+create policy "inbox_app_be_delete"
+on public.inbox for delete to app_be
+using (source like 'client:%' and request_fingerprint is not null and outcome is not null);
+
+grant update, delete on table public.inbox to app_be;

package/templates/be/inbox/platform/event-bus/errors/event-bus.error.ts.tpl

@@ -0,0 +1,16 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the event-bus capability. */
+export enum EventBusErrorCode {
+    /** A publisher supplied an unsafe or unbounded request identity. */
+    CorrelationInvalid = "EVENT_BUS_CORRELATION_INVALID",
+}
+
+/** How each event-bus code travels. */
+export const EVENT_BUS_ERROR_KINDS: Record<EventBusErrorCode, ErrorKind> = {
+    [EventBusErrorCode.CorrelationInvalid]: "invalid",
+}
+
+/** The one error class of the event-bus capability. */
+export class EventBusError extends DomainError<EventBusErrorCode> {}

package/templates/be/inbox/platform/event-bus/event-bus.contracts.ts.tpl

@@ -23,6 +23,8 @@ export interface EventClass<Event extends BaseEvent> {
 
 /** One committed delivery received by a reactor. */
 export interface EventDelivery<Event extends BaseEvent> {
+    /** The request id carried explicitly from intake to delivery. */
+    readonly correlationId: string
     /** The consumer's idempotency key. */
     readonly eventId: string
     /** The typed event. */
@@ -31,8 +33,16 @@ export interface EventDelivery<Event extends BaseEvent> {
     readonly attempt: number
 }
 
+/** Explicit request context carried independently of the business payload. */
+export interface EventMetadata {
+    /** The originating request or promoted legacy event identity. */
+    readonly correlationId: string
+}
+
 /** The typed event's durable envelope, read only after the intake transaction commits. */
 export interface EventEnvelope {
+    /** The originating request context, independent of the business payload. */
+    readonly metadata: EventMetadata
     /** The stable event id. */
     readonly eventId: string
     /** The contract's event name. */

package/templates/be/inbox/platform/event-bus/event-bus.port.ts.tpl

@@ -4,7 +4,7 @@ import type { BaseEvent, EventClass, EventDelivery } from "./event-bus.contracts
 /** The publishing side of the lite event bus; the reactor or job owns delivery of committed outbox rows. */
 export interface EventBus {
     /** Writes the typed event in the caller's transaction; a rollback writes no durable event. */
-    publish(event: BaseEvent, tx: EntityManager): Promise<void>
+    publish(event: BaseEvent, tx: EntityManager, correlationId: string): Promise<void>
 }
 
 /** A later message transport receives one typed event and forwards its delivery id. */

package/templates/be/inbox/platform/event-bus/event-bus.service.spec.ts.tpl

@@ -1,5 +1,6 @@
 import { Test } from "@nestjs/testing"
 import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { EventBusErrorCode } from "./errors/event-bus.error"
 import { BaseEvent } from "./event-bus.contracts"
 import { EventBusService } from "./event-bus.service"
 import { INSERT_OUTBOX_EVENT } from "./persistence/event-bus.sql"
@@ -16,17 +17,28 @@ describe("EventBusService", () => {
         return module.get(EventBusService)
     }
 
+    it.each(["", "unsafe\nid", "x".repeat(129)])("refuses invalid correlation before SQL: %s", async (correlationId) => {
+        const subject = await build()
+        const manager = mockEntityManager({ query: [INSERT_OUTBOX_EVENT, []] })
+
+        await expect(subject.publish(new ReceiptRecordedEvent(), manager, correlationId)).rejects.toMatchObject({
+            code: EventBusErrorCode.CorrelationInvalid,
+        })
+        expect(manager.query).not.toHaveBeenCalled()
+    })
+
     it("writes the typed envelope through the receipt transaction", async () => {
         const subject = await build()
         const transaction = fakeTransaction(mockEntityManager({ query: [INSERT_OUTBOX_EVENT, []] }))
         const event = new ReceiptRecordedEvent()
 
-        await transaction.em.transaction((manager) => subject.publish(event, manager))
+        await transaction.em.transaction((manager) => subject.publish(event, manager, "request-1"))
 
         expect(transaction.em.query).toHaveBeenCalledWith(INSERT_OUTBOX_EVENT, [
             "receipt-1",
             "spec.delivery-recorded",
-            JSON.stringify({ eventId: event.eventId, eventName: event.eventName, payload: event.payload }),
+            JSON.stringify({ metadata: { correlationId: "request-1" }, eventId: event.eventId, eventName: event.eventName, payload: event.payload }),
+            "request-1",
         ])
         expect(transaction.commits).toBe(1)
     })
@@ -37,7 +49,7 @@ describe("EventBusService", () => {
         jest.spyOn(manager, "query").mockRejectedValue(new Error("outbox unavailable"))
         const transaction = fakeTransaction(manager)
 
-        await expect(transaction.em.transaction((tx) => subject.publish(new ReceiptRecordedEvent(), tx))).rejects.toThrow("outbox unavailable")
+        await expect(transaction.em.transaction((tx) => subject.publish(new ReceiptRecordedEvent(), tx, "request-1"))).rejects.toThrow("outbox unavailable")
 
         expect(transaction.commits).toBe(0)
         expect(transaction.rollbacks).toBe(1)

package/templates/be/inbox/platform/event-bus/event-bus.service.ts.tpl

@@ -1,5 +1,7 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
+import { isCorrelationId } from "@modules/platform/logging"
+import { EventBusError, EventBusErrorCode } from "./errors/event-bus.error"
 import type { BaseEvent, EventEnvelope } from "./event-bus.contracts"
 import type { EventBus } from "./event-bus.port"
 import { INSERT_OUTBOX_EVENT } from "./persistence/event-bus.sql"
@@ -8,8 +10,14 @@ import { INSERT_OUTBOX_EVENT } from "./persistence/event-bus.sql"
 /** Writes a receipt event into the same transaction as its inbox receipt, without running any consumer. */
 export class EventBusService implements EventBus {
     /** The outbox commits or rolls back with the receipt; only a later reactor or job processes it. */
-    async publish(event: BaseEvent, tx: EntityManager): Promise<void> {
-        const envelope: EventEnvelope = { eventId: event.eventId, eventName: event.eventName, payload: event.payload }
-        await tx.query(INSERT_OUTBOX_EVENT, [event.eventId, event.eventName, JSON.stringify(envelope)])
+    async publish(event: BaseEvent, tx: EntityManager, correlationId: string): Promise<void> {
+        if (!isCorrelationId(correlationId)) throw new EventBusError({ code: EventBusErrorCode.CorrelationInvalid })
+        const envelope: EventEnvelope = {
+            metadata: { correlationId },
+            eventId: event.eventId,
+            eventName: event.eventName,
+            payload: event.payload,
+        }
+        await tx.query(INSERT_OUTBOX_EVENT, [event.eventId, event.eventName, JSON.stringify(envelope), correlationId])
     }
 }

package/templates/be/inbox/platform/event-bus/index.ts.tpl

@@ -1,3 +1,5 @@
+export { EVENT_BUS_ERROR_KINDS } from "./errors/event-bus.error"
+export { EVENT_BUS_MESSAGES } from "./messages/event-bus.messages"
 export { BaseEvent } from "./event-bus.contracts"
 export type { EventClass, EventDelivery, EventEnvelope, ParsedEvent } from "./event-bus.contracts"
 export { EVENT_BUS, InjectEventBus } from "./event-bus.decorators"

package/templates/be/inbox/platform/event-bus/messages/event-bus.messages.ts.tpl

@@ -0,0 +1,7 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the event-bus codes, Vietnamese and English. */
+export const EVENT_BUS_MESSAGES: MessageBundle = {
+    vi: { "errors.EVENT_BUS_CORRELATION_INVALID": "M? t??ng quan s? ki?n kh?ng h?p l?." },
+    en: { "errors.EVENT_BUS_CORRELATION_INVALID": "The event correlation id is invalid." },
+}

package/templates/be/inbox/platform/event-bus/persistence/event-bus.sql.ts.tpl

@@ -1,5 +1,5 @@
 import { sql } from "@modules/platform/database"
 
 /** Writes only the typed envelope; a reactor or job reads the committed row afterward. */
-export const INSERT_OUTBOX_EVENT = sql`INSERT INTO public.event_bus (event_id, event_name, payload)
-VALUES ($1, $2, $3::jsonb)`
+export const INSERT_OUTBOX_EVENT = sql`INSERT INTO public.event_bus (event_id, event_name, payload, correlation_id)
+VALUES ($1, $2, $3::jsonb, $4)`

package/templates/be/inbox/platform/idempotency/errors/idempotency.error.ts.tpl

@@ -0,0 +1,19 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Stable client-operation refusals shared by transports and durable inbox adapters. */
+export enum IdempotencyErrorCode {
+    /** This principal's operation key was already used for a different request. */
+    KeyReused = "IDEMPOTENCY_KEY_REUSED",
+    /** The key, authenticated scope or JSON data cannot identify a valid operation. */
+    RequestInvalid = "IDEMPOTENCY_REQUEST_INVALID",
+}
+
+/** Transport kinds of the public idempotency refusals. */
+export const IDEMPOTENCY_ERROR_KINDS: Record<IdempotencyErrorCode, ErrorKind> = {
+    [IdempotencyErrorCode.KeyReused]: "conflict",
+    [IdempotencyErrorCode.RequestInvalid]: "invalid",
+}
+
+/** The public idempotency error family. */
+export class IdempotencyError extends DomainError<IdempotencyErrorCode> {}

package/templates/be/inbox/platform/idempotency/index.ts.tpl

@@ -0,0 +1,2 @@
+export { IdempotencyError, IdempotencyErrorCode, IDEMPOTENCY_ERROR_KINDS } from "./errors/idempotency.error"
+export { IDEMPOTENCY_MESSAGES } from "./messages/idempotency.messages"

package/templates/be/inbox/platform/idempotency/messages/idempotency.messages.ts.tpl

@@ -0,0 +1,13 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the public client-operation refusals. */
+export const IDEMPOTENCY_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.IDEMPOTENCY_KEY_REUSED": "Khóa thao tác đã được dùng cho nội dung khác.",
+        "errors.IDEMPOTENCY_REQUEST_INVALID": "Khóa, phạm vi hoặc dữ liệu thao tác không hợp lệ.",
+    },
+    en: {
+        "errors.IDEMPOTENCY_KEY_REUSED": "This operation key was already used with a different request.",
+        "errors.IDEMPOTENCY_REQUEST_INVALID": "The operation key, scope or JSON data is invalid.",
+    },
+}

package/templates/be/inbox/platform/inbox/client-operation.policy.spec.ts.tpl

@@ -0,0 +1,32 @@
+import { Test } from "@nestjs/testing"
+import { IdempotencyError, IdempotencyErrorCode } from "@modules/platform/idempotency"
+import { clientSource } from "./client-operation.policy"
+
+const CLIENT_SOURCE = Symbol("client-source")
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: CLIENT_SOURCE, useValue: clientSource }],
+    }).compile()
+    return moduleRef.get<typeof clientSource>(CLIENT_SOURCE)
+}
+
+const REQUEST = { principalId: "person-1", operation: "checkout.place", idempotencyKey: "key-1", request: {} }
+
+describe("clientSource", () => {
+    it("binds the exact authenticated principal and operation and accepts a 64-character key", async () => {
+        const sourceOf = await build()
+        expect(sourceOf({ ...REQUEST, idempotencyKey: "a".repeat(64) })).toBe("client:person-1:checkout.place")
+    })
+
+    it.each([
+        { ...REQUEST, principalId: " " },
+        { ...REQUEST, principalId: "a:b" },
+        { ...REQUEST, operation: " " },
+        { ...REQUEST, operation: "a:b" },
+        { ...REQUEST, idempotencyKey: " " },
+        { ...REQUEST, idempotencyKey: "a".repeat(65) },
+    ])("refuses ambiguous scopes and unbounded or empty keys %p", async (request) => {
+        const sourceOf = await build()
+        expect(() => sourceOf(request)).toThrow(new IdempotencyError({ code: IdempotencyErrorCode.RequestInvalid }))
+    })
+})