@starci/hfs 4.11.0 → 4.11.11

package/runtime/knowledge/hfs/slots.yaml

@@ -7,7 +7,7 @@
 # catalog READ this file through scripts/hfs/slots.mjs; none of them hardcodes a path.
 # Shape: modules/schemas/hfs-slots.schema.yaml. The repository side is hfs.json: modules/schemas/hfs-repo.schema.yaml.
 schema: starci/hfs-slots@3
-version: 3.11.0
+version: 3.14.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -55,6 +55,11 @@ versioning:
 # 3.11.0 (ruling:lite-official-postgres-image, 2026-10-29) is, like 3.9.0, a change for lite only: it ADDS the managed app.db.image slot
 # (db/Dockerfile, written by `starci app sync --write`), narrows ruleParams.db.extensions to the extensions that image carries, and gives
 # @nestjs/schedule and cron one owner, platform/jobs (R335).
+# 3.13.0 (rulings lite-pgmq-bus-bullmq-jobs and lite-db-image-in-stacks, 2026-10-29) is a change for lite only: ruleParams.db.extensions
+# admits pgmq, the event bus, ruleParams.db.queueOutbox is retired with the pg_cron half of R258, the lite event-bus functions replace
+# event_bus_write in ruleParams.be.dbFunctions, and app.db.image moves to .starcistacks/images/db/Dockerfile (db/ keeps schema and data).
+# 3.14.0 (ruling app-secrets-one-standard, 2026-10-29) adds the optional app.ci-stack-key-restore, the managed workflow that writes the
+# deploy server's age identity back from its GitHub Environment backup.
 
 # Field meaning, per slot.
 #   id          stable name, never changes meaning inside a major.
@@ -129,8 +134,8 @@ testValues: [unit-beside, e2e, none]
 # event bus, saga, reactors, projection, realtime, webhooks, fenced job), declared in hfs.json the same way, and the same unit
 # specs (unitRoles, logicRoles, 100 per file, @starci/jest-preset doubles, builders). What differs is ADAPTERS and DELIVERY
 # (ruling:R212/case-10): schema authority in db/migrations, the queue port on BullMQ over the Redis hfs.json
-# sides.be.backing declares (as in full, fed by the Postgres outbox), event-bus ports on pgmq-backed topics or in-process
-# delivery, cache and locks on Postgres or the declared Redis, schedules as platform/jobs ticks enqueueing through the queue
+# sides.be.backing declares (as in full, fed by the Postgres outbox), event-bus ports on pgmq topics sent in the publisher's
+# transaction (ruling:lite-pgmq-bus-bullmq-jobs), cache and locks on Postgres or the declared Redis, schedules as platform/jobs ticks enqueueing through the queue
 # outbox (R335), storage on S3-compatible MinIO (integrations/object-storage) and auth through integrations/passport. Realtime uses SSE or the socket.io gateway
 # in the api process, which scales horizontally and stateless (memory hub for one replica or tests; the Redis hub and @socket.io/redis-adapter when Redis is declared, else the Postgres hub and @socket.io/postgres-adapter, for N replicas; websocket only, no sticky sessions). Integration and provider sandbox contract specs are optional;
 # declared patterns owe their integration proofs (R284). Lite has no e2e world. Production uses declared docker-swarm under
@@ -209,11 +214,9 @@ ruleParams:
   db:
     # R259: btree_gist supplies UUID equality for the booking interval exclusion constraint.
     # R259: the extensions the db image carries (ruling:lite-official-postgres-image): the official postgres image's contrib set and pgvector
-    # from PGDG; unaccent serves Vietnamese-content search functions. No pg_cron, pg_net, pgmq or supabase_vault.
-    extensions: [pgcrypto, pg_trgm, vector, uuid-ossp, unaccent, btree_gist]
-    # R258 DB_CRON_OWNED: THE queue outbox of a lite schema (the relay hands its unsent rows to BullMQ, ruling:R212/case-10). A pg_cron
-    # job enqueues only by inserting one row into this table, writing only these columns, one of which is `queue`.
-    queueOutbox: {table: public.queue, columns: [queue, payload, created_at, correlation_id]}
+    # from PGDG; unaccent serves Vietnamese-content search functions; pgmq is the event bus (ruling:lite-pgmq-bus-bullmq-jobs), installed
+    # from its pinned release. No pg_cron, pg_net or supabase_vault.
+    extensions: [pgcrypto, pg_trgm, vector, uuid-ossp, unaccent, btree_gist, pgmq]
   common:
     # HFS_SIZE_GROWTH: a file above soft may not grow against its parent commit; a new file stays within soft. Slot
     # budgets (component.tsx 300, hooks 200, modules 400) are stricter than this cap where they apply.
@@ -429,29 +432,36 @@ ruleParams:
     # logic roles and spec doubles are full's (owner ruling 2026-10-12 (owner:lite-production-swarm), with the Work boundary amended by ruling:R212/case-4). infraOwners: full's owners,
     # bullmq in platform/queue and ioredis/redis in integrations/cache and integrations/redis (ruling:R212/case-10: the queue is
     # Redis in both editions; a backing library is legal only when hfs.json sides.be.backing declares its service, which
-    # HFS_BACKING_UNDECLARED checks), except Kafka, which is owned nowhere (platform/event-bus runs pgmq queues through
+    # HFS_BACKING_UNDECLARED checks), except Kafka, which is owned nowhere (platform/event-bus runs pgmq topics through
     # the shared EntityManager); realtime is the same socket.io gateway as full, run inside the api process, scaled horizontally and stateless (hub redis when
     # Redis is declared, else hub postgres with @socket.io/postgres-adapter; no sticky sessions).
     # R334: the database functions code may call through platform/database's callDbFunction, advisoryXactLock and notify helpers,
-    # each {name, reason}; the canon lists the pg built-ins it uses itself, and an app adds its own in hfs.json sides.be.dbFunctions.
+    # each {name, reason}; a pg built-in is listed bare (called in pg_catalog), every other function schema-qualified (public.job_claim),
+    # and an app adds its own, schema-qualified, in hfs.json sides.be.dbFunctions.
     dbFunctions:
       - {name: pg_advisory_xact_lock, reason: "advisoryXactLock: a transaction-scoped lock TypeORM has no API for"}
       - {name: hashtextextended, reason: "advisoryXactLock: the 64-bit key of a text lock name"}
       - {name: pg_notify, reason: "notify: LISTEN/NOTIFY of the Postgres realtime hub"}
       - {name: to_regproc, reason: "callDbFunction: whether an optional database function exists"}
-      - {name: job_claim, reason: "platform/jobs (add job, lite): the fenced claim upsert of jobs.sql"}
-      - {name: job_advance, reason: "platform/jobs (add job, lite): the token-guarded step write of jobs.sql"}
-      - {name: job_complete, reason: "platform/jobs (add job, lite): the token-guarded completion of jobs.sql"}
-      - {name: job_fail, reason: "platform/jobs (add job, lite): the token-guarded failure of jobs.sql"}
-      - {name: job_tick_claim, reason: "platform/jobs (add job, lite): the once-per-minute claim of a scheduler tick, jobs.sql (R335)"}
-      - {name: queue_write, reason: "platform/queue (add queue, lite): the outbox insert of queue-outbox.sql"}
-      - {name: queue_waiting, reason: "platform/queue (add queue, lite): the relay read FOR UPDATE SKIP LOCKED of queue-outbox.sql"}
-      - {name: queue_mark_sent, reason: "platform/queue (add queue, lite): the relay mark of queue-outbox.sql"}
-      - {name: inbox_claim_event, reason: "platform/inbox (add webhook, lite): the conflict-safe delivery claim"}
-      - {name: inbox_claim_client, reason: "platform/inbox (add webhook, lite): the client claim upsert returning its committed outcome"}
-      - {name: inbox_save_client_outcome, reason: "platform/inbox (add webhook, lite): the saved client outcome"}
-      - {name: inbox_sweep_clients, reason: "platform/inbox (add webhook, lite): the bounded retention sweep FOR UPDATE SKIP LOCKED"}
-      - {name: event_bus_write, reason: "platform/event-bus (add webhook, lite): the typed envelope insert of the outbox"}
+      - {name: gen_random_uuid, reason: "callDbFunction: a random uuid from the database (PG13+ core, pg_catalog) where a token is minted in the transaction"}
+      - {name: public.job_claim, reason: "platform/jobs (add job, lite): the fenced claim upsert of jobs.sql"}
+      - {name: public.job_advance, reason: "platform/jobs (add job, lite): the token-guarded step write of jobs.sql"}
+      - {name: public.job_complete, reason: "platform/jobs (add job, lite): the token-guarded completion of jobs.sql"}
+      - {name: public.job_fail, reason: "platform/jobs (add job, lite): the token-guarded failure of jobs.sql"}
+      - {name: public.job_tick_claim, reason: "platform/jobs (add job, lite): the once-per-minute claim of a scheduler tick, jobs.sql (R335)"}
+      - {name: public.queue_write, reason: "platform/queue (add queue, lite): the outbox insert of queue-outbox.sql"}
+      - {name: public.queue_waiting, reason: "platform/queue (add queue, lite): the relay read FOR UPDATE SKIP LOCKED of queue-outbox.sql"}
+      - {name: public.queue_mark_sent, reason: "platform/queue (add queue, lite): the relay mark of queue-outbox.sql"}
+      - {name: public.inbox_claim_event, reason: "platform/inbox (add webhook, lite): the conflict-safe delivery claim"}
+      - {name: public.inbox_claim_client, reason: "platform/inbox (add webhook, lite): the client claim upsert returning its committed outcome"}
+      - {name: public.inbox_save_client_outcome, reason: "platform/inbox (add webhook, lite): the saved client outcome"}
+      - {name: public.inbox_sweep_clients, reason: "platform/inbox (add webhook, lite): the bounded retention sweep FOR UPDATE SKIP LOCKED"}
+      - {name: public.event_bus_send, reason: "platform/event-bus (add webhook, lite): the send of a typed envelope to its pgmq topic in the publisher's transaction"}
+      - {name: public.event_bus_read, reason: "platform/event-bus (add webhook, lite): a consumer's pgmq read with a visibility timeout"}
+      - {name: public.event_bus_archive, reason: "platform/event-bus (add webhook, lite): the archive of a handled message"}
+      - {name: public.event_bus_bury, reason: "platform/event-bus (add webhook, lite): the move of an exhausted or malformed message to its consumer's dead-letter queue"}
+      - {name: public.event_bus_dead_letters, reason: "platform/event-bus (add webhook, lite): the operator read of a consumer's dead-letter queue"}
+      - {name: public.event_bus_requeue, reason: "platform/event-bus (add webhook, lite): the operator requeue of one dead letter"}
 
     lite:
       schemaAuthority: sql
@@ -668,6 +678,19 @@ slots:
     managedBy: ci-workflows
     liteManagedBy: ci-workflows-lite
     rules: [HFS_MANAGED_FILE_DRIFT]
+  - id: app.ci-stack-key-restore
+    since: 3.14.0
+    profiles: [app]
+    editionWhy: "ruling:app-secrets-one-standard: both editions deploy to a Docker Swarm server whose own age identity the owner backs up as a protected GitHub Environment secret; this workflow writes it back."
+    # The server identity restore workflow: workflow_dispatch only (like app.ci-stack-deploy); `starci app secret server-key <env> --restore github` dispatches it, rendered by starci app sync.
+    path: ".github/workflows/stack-key-restore.yml"
+    presence: optional
+    tracked: tracked
+    tier: none
+    tests: none
+    managedBy: ci-workflows
+    liteManagedBy: ci-workflows-lite
+    rules: [HFS_MANAGED_FILE_DRIFT]
   - id: app.dockerignore
     since: 3.1.0
     profiles: [app]
@@ -870,7 +893,7 @@ slots:
     # The db service supplies the database; schedules are platform/jobs ticks (R335); production has no Compose or host cron.
     lite:
       requires: [application-stacks.yaml]
-      allows: [application-stacks.yaml, "<env>/README.md", "<env>/environment.json", "<env>/infra/swarm/**", "<env>/infra/metadata.json",
+      allows: [application-stacks.yaml, images/db/Dockerfile, "<env>/README.md", "<env>/environment.json", "<env>/infra/swarm/**", "<env>/infra/metadata.json",
                "<env>/runtime/{config,env}/**", "<env>/runtime/env/KEYS.md", "<env>/secrets/<slug>.enc", "<env>/secrets/.gitkeep", "<env>/seeds/**"]
       forbids: ["<env>/runtime/files/**", "**/*.enc outside <env>/secrets/", DESIGN.md, deployment.json, "k8s/ at root"]
     rules: [HFS_STACKS_SHAPE, HFS_STACKS_IN_SIDE, HFS_PLAINTEXT_SECRET, HFS_IDENTITY_CUSTODY]
@@ -931,7 +954,7 @@ slots:
     rules: [HFS_PLAINTEXT_SECRET]
 
   # ----- app root: the database of a lite app (ruling:lite-self-hosted-postgres-passport-minio): a self-hosted PostgreSQL in the app's
-  # stack (the `db` service, built from the managed db/Dockerfile: the official postgres image plus pgvector, ruling:lite-official-postgres-image), migrated by
+  # stack (the `db` service, built from the managed .starcistacks/images/db/Dockerfile: the official postgres image plus pgvector and pgmq, ruling:lite-db-image-in-stacks), migrated by
   # `starci app db migrate --url-env <NAME>`. A full app keeps its TypeORM migrations under be/ and has no such folder.
   - id: app.db
     profiles: [app]
@@ -984,10 +1007,11 @@ slots:
   - id: app.db.image
     profiles: [app]
     editions: [lite]
-    # The managed image of the db service (templates/app/db-image, ruling:lite-official-postgres-image): FROM the digest-pinned official
-    # postgres image plus postgresql-17-pgvector from PGDG. The stack's db service, the local db container and the scratch database
-    # of `starci app db drift` all build it.
-    path: "db/Dockerfile"
+    # The managed image of the db service (templates/app/db-image, rulings lite-official-postgres-image and lite-db-image-in-stacks): FROM
+    # the digest-pinned official postgres image plus postgresql-17-pgvector from PGDG and the sha256-verified pgmq release. It lives with
+    # the stacks; the stack's db service, the local db container, the scratch database of `starci app db drift` and the squash replay
+    # all build it.
+    path: ".starcistacks/images/db/Dockerfile"
     presence: required
     tracked: tracked
     managedBy: db-image
@@ -998,9 +1022,11 @@ slots:
   - id: app.db.bootstrap
     profiles: [app]
     editions: [lite]
-    # The managed pre-migration bootstrap (templates/app/db-bootstrap): the auth and storage schemas, auth.users with the GoTrue column
-    # set, auth.uid/role/jwt stubs and the NOLOGIN browser roles, so migrations written for a hosted Supabase apply to the db service's
-    # official postgres image (nothing else of Supabase: no supabase_admin, extensions schema or realtime publication). `starci app db migrate` applies it before the first migration of an empty database.
+    # The managed pre-migration bootstrap (templates/app/db-bootstrap): the extensions schema every allowed extension is created in, the
+    # auth and storage schemas, auth.users with the GoTrue column set, auth.uid/role/jwt stubs and the NOLOGIN browser roles, so migrations
+    # written for a hosted Supabase apply to the db service's official postgres image (nothing else of Supabase: no supabase_admin or
+    # realtime publication). `starci app db migrate` applies it before the first migration of an empty database; sync renders all of it
+    # but the one marked section `starci app db baseline --squash` writes (the source's app roles and the grants a per-database dump loses).
     path: "db/bootstrap.sql"
     presence: required
     tracked: tracked
@@ -1785,7 +1811,7 @@ slots:
   - id: be.platform.event-bus
     since: 3.1.0
     profiles: [be]
-    editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite implements the event ports with outbox and pgmq; full uses its Kafka adapter."
+    editionWhy: "ruling:R212/case-2 (owner:lite-production-swarm) (with the Work boundary amended by ruling:R212/case-4): lite implements the event ports on pgmq (ruling:lite-pgmq-bus-bullmq-jobs); full uses its Kafka adapter."
     path: "src/modules/platform/event-bus/"
     presence: opt-in
     pattern: event-bus            # the ONE durable event transport: transactional outbox, relay, Kafka, inbox, retry and dead letter (knowledge/patterns/be/event-bus.yaml)
@@ -1794,10 +1820,10 @@ slots:
     owner: true
     lite:
       why: >-
-        the same EventPublisher and EventConsumer ports on pgmq queues: the outbox relay sends each committed row to the
-        pgmq queue of every consumer group of its topic through the shared EntityManager, a consumer reads with a visibility
-        timeout, retries by letting it lapse and archives the message on dead letter (read_ct over the budget); a single api may
-        deliver in process. No Kafka (knowledge/patterns/be/event-bus.yaml liteAdapter)
+        the EventBus and EventConsumer ports on pgmq (ruling:lite-pgmq-bus-bullmq-jobs): publish sends the envelope to its
+        topic in the publisher's transaction, so no outbox or relay runs; each consumer group reads its own queue bound to the
+        event's name with a visibility timeout, archives a handled message, lets a failed one reappear and buries one past its
+        maxDeliveries in its __dead queue (BE-EVENT-BUS-6). Jobs stay on BullMQ (platform/queue). No Kafka (knowledge/patterns/be/event-bus.yaml liteAdapter)
     requires: [index.ts, event-bus.module.ts, event-bus.port.ts, event-bus.contracts.ts, event-bus.service.ts, event-bus.service.spec.ts]
     tests: unit-beside
     coverage: required

package/runtime/knowledge/patterns/be/event-bus.yaml

@@ -288,19 +288,21 @@ files:
     role: "The consumed event's e2e flow; titles event-bus/<scenario>: ... prove the pattern."
     spec: event-bus/atomic-with-transaction, event-bus/relay-only-after-commit, event-bus/redelivery-then-dead-letter, event-bus/duplicate-delivery-is-a-noop
     rules: [BE_PATTERN_SPEC_MISSING]
-# Edition lite (R212): the same ports and rules, a self-hosted Postgres adapter behind them. ruling:R212/case-10 moved the lite queue to Redis
-# because full's queue is Redis; full's event bus is Kafka, so the lite event-bus adapter below is unchanged by that ruling.
+# Edition lite (R212): the same ports and rules, a self-hosted Postgres adapter behind them. ruling:lite-pgmq-bus-bullmq-jobs makes pgmq the
+# lite event bus and keeps jobs on BullMQ (platform/queue).
 liteAdapter:
   summary: >-
-    Under lite the event bus keeps typed events, the vendored contract, publish(event, tx, correlationId) in the domain transaction, the outbox,
-    the inbox and thin consumers; Kafka is replaced by pgmq-backed topics, or by in-process delivery after commit for a back end
-    with a single api app. Each consumer group of a topic has its own pgmq queue `<service>__<event>__<group>`, created by a
-    db migration, named by a literal `<GROUP>_TOPIC_QUEUE` constant under platform/event-bus (its owner, R258) and
-    granted only to the application role, so each group keeps its own cursor and dead letter.
+    Under lite the event bus keeps typed events, the vendored contract, publish(event, tx, correlationId) in the domain transaction,
+    the inbox and thin consumers; Kafka is replaced by pgmq topics in the db service. Publish sends the envelope to its topic
+    (the event name) in the publisher's transaction, so no outbox or relay stands between them. Each consumer of an event has its
+    own pgmq queue `<topic>__<consumer>` and dead-letter queue `<topic>__<consumer>__dead`, created and bound to the event's name
+    by a db migration and named by a literal `<TOPIC>_<CONSUMER>_TOPIC_QUEUE` constant under platform/event-bus (its owner, R258);
+    every payload carries a business dedupeKey the consumer inbox claims, and subscriptions are static (R336); the application
+    role reaches pgmq only through the security-definer event_bus_* functions of the migration (contexts/code/be/event-bus.md BE-EVENT-BUS-6).
   ports:
-    - {port: EventPublisher (platform/event-bus), adapter: the same outbox row in the domain transaction}
-    - {port: relay, adapter: "fans each committed event out with pgmq.send to one queue per consumer group of its topic, marking the row in the same transaction"}
-    - {port: EventConsumer (platform/event-bus), adapter: "pgmq.read with a visibility timeout, the inbox claim on the event id, pgmq.delete on success, pgmq.archive as the dead letter"}
+    - {port: EventBus.publish (platform/event-bus), adapter: "event_bus_send: pgmq.send_topic of the envelope in the domain transaction"}
+    - {port: EventConsumer (platform/event-bus), adapter: "event_bus_read with a visibility timeout, the inbox claim on (consumer, dedupeKey) in the dispatched command, event_bus_archive on success, a failed delivery left to reappear, event_bus_bury into <queue>__dead past maxDeliveries (default 5)"}
+    - {port: EventBus.deadLetters and requeue (platform/event-bus), adapter: "event_bus_dead_letters and event_bus_requeue over a consumer's dead-letter queue"}
   forbids: [kafkajs]
   proof: >-
     Unit specs as full; declaring event-bus requires integration specs titled `event-bus/<scenario>: ...` for every declared

package/runtime/knowledge/patterns/be/queues.yaml

@@ -98,12 +98,11 @@ rules:
         write: 'order-expiry.queue.ts declares scheduler { every: 5 minutes } for the expire-orders job; the processor dispatches ExpireOrdersCommand.'
       - id: case-2
         when: A lite app sends booking reminders every fifteen minutes
-        write: "A migration declares private.booking_reminder_tick() as one insert into public.queue (queue, payload, created_at) values ('booking_reminder', jsonb_build_object('tick', true), now()) and schedules it with cron.schedule('booking_reminder_tick', '*/15 * * * *', ...); the send-reminder processor is the queue's."
+        write: "platform/jobs declares a booking_reminder tick every fifteen minutes (BE-JOBS-6): each firing claims its slot and writes one booking_reminder row through the queue outbox; the send-reminder processor is the queue's."
     verification:
       automated:
         - BE_INFRA_OWNER
         - DB_PGMQ_DECLARED
-        - DB_CRON_OWNED
       manual:
         - Confirm the cadence and the job's idempotence.
     relatedExamples: [queue]
@@ -277,7 +276,7 @@ liteAdapter:
     its append-only file (WAITAOF) and still holds it, so a job Redis loses inside the at most one second fsync window leaves
     its row waiting and is added again; that is why a lite queue does not lose a job. Without a declared Redis there is no queue
     pattern: the work is a direct call inside the request, or a declared replicated-job running a cli command. pgmq
-    is not a queue transport. `starci app add queue|job` writes this adapter in a lite app, with the outbox and job
+    is the event bus, not a queue transport (ruling:lite-pgmq-bus-bullmq-jobs). `starci app add queue|job` writes this adapter in a lite app, with the outbox and job
     tables as one db migration, the Redis declaration and the persisted Redis of every docker-swarm environment.
   ports:
     - {port: QueueOutbox (platform/queue), adapter: "the outbox row written through the caller's tx by queue_write, and the relay's queue_waiting and queue_mark_sent, functions of the queue migration in db/migrations called through callDbFunction of platform/database (R334)"}

package/runtime/knowledge/patterns/be/reactors.yaml

@@ -158,7 +158,7 @@ files:
 liteAdapter:
   summary: >-
     Under lite a reactor is unchanged: a thin consumer of another context's events that dispatches one command. Its deliveries
-    come from the lite event bus (its own pgmq queue per consumer group).
+    come from the lite event bus (its own pgmq queue per consumer group, bound to the event's topic).
   ports:
     - {port: EventConsumer delivery, adapter: "the reactor's pgmq queue (see event-bus.yaml liteAdapter)"}
   proof: >-

package/runtime/modules/kernel/failure-codes.yaml

@@ -1827,17 +1827,6 @@ DB_BASELINE_SHAPE:
 
 
 
-DB_CRON_OWNED:
-  title: "A uniquely owned migration cron job only enqueues through the queue outbox"
-  title_vi: "Lịch pg_cron thiếu chủ sở hữu hoặc thực hiện nghiệp vụ"
-  meaning_vi: "Tên lịch bị trùng, hằng hàng đợi hoặc hàm tick không tồn tại, lệnh thực hiện DML nghiệp vụ hay HTTP thay vì chỉ chèn một dòng của hằng hàng đợi vào bảng outbox của ruleParams.db.queueOutbox (chỉ các cột đã khai báo), lịch đang chạy vẫn gọi pgmq.send, hoặc cùng tick còn được lập lịch ở ứng dụng."
-  causes_vi:
-    - "Vi phạm R258: pg_cron chỉ đưa việc vào hàng đợi qua outbox, mỗi tick có đúng một nơi lập lịch và được hủy lịch khi loại bỏ."
-    - "Lịch đang chạy (hoặc tick hiện tại của nó) vẫn gửi bằng pgmq.send; pgmq.send chỉ hợp lệ trong thân gốc của lịch cũ."
-  nextStep_vi: "Đặt lịch trong migration với tên duy nhất, chèn đúng một dòng của hằng hàng đợi vào outbox hàng đợi (trực tiếp hoặc qua một hàm *_tick chỉ làm việc đó), bỏ lịch trùng và gọi cron.unschedule khi xóa tick."
-  owner: op-retry
-  kind: check-finding
-
 DB_DEFINER_REVOKE:
   title: "Exposed security definer functions revoke browser execution"
   title_vi: "Function security definer chưa thu hồi quyền trình duyệt"
@@ -1909,14 +1898,14 @@ DB_MIGRATION_SHAPE:
   kind: check-finding
 
 DB_PGMQ_DECLARED:
-  title: "A queue constant keeps a pgmq queue, a pgmq queue has no event-bus owner, or a pgmq object is declared or granted unsafely"
-  title_vi: "Hằng hàng đợi còn hàng đợi pgmq, hàng đợi pgmq không có chủ event-bus, hoặc đối tượng pgmq khai báo hay cấp quyền sai"
-  meaning_vi: "Hàng đợi là BullMQ trên Redis (ruling:R212/case-10), nhưng các migration đang hoạt động vẫn để lại một hàng đợi pgmq trùng tên một hằng hàng đợi trong modules/queues, hoặc một hàng đợi pgmq không được hằng literal *_TOPIC_QUEUE nào trong platform/event-bus đặt tên (hay một hằng như vậy không có hàng đợi pgmq); hoặc pgmq.create không có tên literal trong migration, tên hằng không phải literal, hay quyền trên đối tượng pgmq vượt vai trò ứng dụng."
+  title: "A queue constant keeps a pgmq queue, a pgmq queue has no event-bus owner, or a pgmq queue, binding or grant is declared unsafely"
+  title_vi: "Hằng hàng đợi còn hàng đợi pgmq, hàng đợi pgmq không có chủ event-bus, hoặc hàng đợi, liên kết topic hay quyền pgmq khai báo sai"
+  meaning_vi: "pgmq là event bus và job chạy trên BullMQ (ruling:lite-pgmq-bus-bullmq-jobs), nhưng các migration đang hoạt động vẫn để lại một hàng đợi pgmq trùng tên một hằng hàng đợi trong modules/queues, hoặc một hàng đợi pgmq không được hằng literal *_TOPIC_QUEUE nào trong platform/event-bus đặt tên (hay một hằng như vậy không có hàng đợi pgmq); hoặc pgmq.create hay pgmq.bind_topic không có tên literal trong migration, liên kết một hàng đợi chưa được tạo, tên hằng không phải literal, hay quyền trên đối tượng pgmq vượt vai trò ứng dụng."
   causes_vi:
-    - "Vi phạm R258: hàng đợi của app vẫn chạy trên Supabase Queues (pgmq) thay vì BullMQ trên Redis."
-    - "Một hàng đợi pgmq bị bỏ lại hoặc đổi tên mà không có chủ event-bus."
+    - "Vi phạm R258: một job của app chạy trên pgmq thay vì BullMQ trên Redis."
+    - "Một hàng đợi pgmq bị bỏ lại hoặc đổi tên mà không có chủ event-bus, hoặc một liên kết topic trỏ tới hàng đợi chưa tạo."
     - "Migration, mã nguồn hoặc quyền truy cập khai báo đối tượng pgmq ngoài migration tĩnh hoặc cho vai trò khác vai trò ứng dụng."
-  nextStep_vi: "Chuyển hàng đợi sang BullMQ trên Redis đã khai báo, rồi xóa hàng đợi pgmq bằng pgmq.drop_queue trong một migration mới; hàng đợi topic của event bus được đặt tên bằng một hằng literal *_TOPIC_QUEUE trong platform/event-bus; chỉ cấp quyền trên q_<queue>, a_<queue> cho vai trò ứng dụng."
+  nextStep_vi: "Chuyển job sang BullMQ trên Redis đã khai báo, rồi xóa hàng đợi pgmq bằng pgmq.drop_queue trong một migration mới; hàng đợi của một nhóm consumer được đặt tên bằng một hằng literal *_TOPIC_QUEUE trong platform/event-bus, tạo bằng pgmq.create rồi liên kết với tên event bằng pgmq.bind_topic trong cùng migration; vai trò ứng dụng đi qua các hàm event_bus_* thay vì nhận quyền trên schema pgmq."
   owner: op-retry
   kind: check-finding
 
@@ -5601,6 +5590,17 @@ BE_PERSISTENCE_NO_RAW_SQL:
   owner: op-retry
   kind: check-finding
 
+BE_EVENT_BUS_LITE_SHAPE:
+  title: "A lite event payload without dedupeKey, or a subscription that is not static"
+  title_vi: "Payload event của bản lite thiếu dedupeKey, hoặc đăng ký consumer không tĩnh"
+  meaning_vi: "File `<path>` khai một event (lớp kế thừa BaseEvent trong modules/events) mà kiểu payload không có `dedupeKey`, hoặc gọi `subscribe` với tên hàng đợi không phải hằng `*_TOPIC_QUEUE` import từ `@modules/platform/event-bus`, hay với options không phải object literal của giá trị literal."
+  causes_vi:
+    - "Vi phạm R336: event bus pgmq giao ít nhất một lần và không theo thứ tự, nên inbox của consumer claim (consumer, dedupeKey); thiếu dedupeKey thì không khử trùng được."
+    - "Một đăng ký tính tên hàng đợi lúc chạy, nên không ai thấy được nó trong hằng và migration (R258)."
+  nextStep_vi: "Thêm `readonly dedupeKey: string` (khoá nghiệp vụ, như id đơn hàng) vào kiểu payload hoặc kế thừa `EventPayload`; khai hằng `<TOPIC>_<CONSUMER>_TOPIC_QUEUE` trong platform/event-bus, tạo hàng đợi, hàng đợi `__dead` và bind_topic trong migration, rồi subscribe bằng hằng đó."
+  owner: op-retry
+  kind: check-finding
+
 BE_JOBS_SCHEDULER_OWNER:
   title: "A schedule outside the platform/jobs tick scheduler"
   title_vi: "Lịch chạy định kỳ nằm ngoài bộ lập lịch tick của platform/jobs"

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -85,7 +85,7 @@ properties:
         command: {type: string, minLength: 1}
   backing:
     description: >-
-      The self-hosted database of a lite app: its db component (the image its managed db/Dockerfile builds), a Docker container in
+      The self-hosted database of a lite app: its db component (the image its managed .starcistacks/images/db/Dockerfile builds), a Docker container in
       development and a Swarm service in production. Every other dependency is a Docker component too.
     type: object
     additionalProperties:
@@ -855,5 +855,7 @@ $defs:
           - {type: integer, minimum: 1}
           - {type: string, pattern: '^[1-9][0-9]*$'}
       where: {type: string, minLength: 1}
-      recipientPolicy: {type: string, minLength: 1, description: "Which age recipient the envelope is encrypted to: the one shared master recipient every project uses."}
+      member: {type: string, pattern: '^[a-z0-9][a-z0-9-]*$', description: "The provider member holding this key (`secrets/<member>`, the slug of where); with key, the entry declares one key of it."}
+      key: {type: string, pattern: '^[A-Z][A-Z0-9_]*$', description: "The one key of the member this entry declares; materialized as its own file, read by the app as <KEY>_FILE."}
+      recipientPolicy: {type: string, minLength: 1, description: "Which age recipients the envelope is encrypted to: its environment's rule of the app's managed .sops.yaml."}
       keyCustody: {type: string, minLength: 1, description: "Where the shared decrypting identity is held; docs/host-secrets.md owns host custody and its execution prerequisites."}

package/runtime/scripts/api/sops/lib.mjs

@@ -310,6 +310,36 @@ export function runSelectedSops(bin, request, { selection, invocation, env, cwd,
   }
 }
 
+/**
+ * `sops --config <config> updatekeys -y --input-type <type> <file>` under an inline selected identity: the member's data key is
+ * opened with SOPS_AGE_KEY in an isolated child environment and wrapped again to the recipients the config's rule names; no value
+ * is decrypted to stdout or disk. The tool profile is the selected one; captures are wiped.
+ */
+export function runSelectedUpdateKeys(bin, { file, config, inputType }, { selection, invocation, env, cwd, timeout } = {}) {
+  if (selection?.error?.identityRefusal !== 'inline-context-unqualified' || typeof selection.inlineName !== 'string' || !env || typeof env !== 'object') return held('selected-context-missing');
+  if (!invocation || typeof invocation.runProgram !== 'function' || typeof invocation.resolveRealTool !== 'function') return held('selected-context-missing');
+  if (!['yaml', 'dotenv', 'json'].includes(inputType) || !path.isAbsolute(file ?? '') || !path.isAbsolute(config ?? '')) return held('invalid-request');
+  const key = env[selection.inlineName];
+  if (typeof key !== 'string' || !/^AGE-SECRET-KEY-1[0-9A-Z]+$/.test(key.trim())) return held('invalid-inline');
+  const captures = [];
+  try {
+    const exe = bin ?? resolveSops(env), age = invocation.resolveRealTool('age-keygen', { env });
+    if (!nativeFile(exe) || !nativeFile(age)) return held('native-tool-unavailable');
+    if (!auditAbsent(cwd)) return held('unsupported-audit-context');
+    const publicEnv = isolatedSopsEnv(env, null);
+    const options = { cwd, shell: false, encoding: 'buffer', windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'], timeout: timeout ?? IDENTITY_TIMEOUT_MS, maxBuffer: CREDENTIAL_FILE_MAX_BYTES };
+    const run = (program, args, childEnv) => {
+      const result = invocation.runProgram(program, args, { ...options, env: childEnv });
+      captures.push(result); return result;
+    };
+    if (!toolProfileSupported(run(exe, ['--disable-version-check', '--version'], publicEnv), run(age, ['--version'], publicEnv))) return held('unsupported-tool-profile');
+    const result = run(exe, ['--disable-version-check', '--config', config, 'updatekeys', '-y', '--input-type', inputType, file], isolatedSopsEnv(env, selection.inlineName));
+    if (!captured(result)) return { status: result?.status ?? null, stdout: '', stderr: '', error: result?.error ?? null };
+    return { status: 0, stdout: '', stderr: '', error: null };
+  } catch { return held('selected-native-refused'); }
+  finally { wipeCaptures(captures); }
+}
+
 const identityRequestValid = ({ env, cwd, invocation, assertLease, consume }) =>
   env && typeof env === 'object' && path.isAbsolute(cwd ?? '') && typeof consume === 'function'
     && typeof assertLease === 'function' && typeof invocation?.runProgram === 'function'

package/runtime/scripts/api/sops/update-keys.mjs

@@ -0,0 +1,20 @@
+// update-keys.mjs — the public SOPS `updatekeys` call: a sealed member is wrapped again to the recipients its .sops.yaml rule
+// names. Only the member's data key is opened (with the caller's identity); no value is decrypted to stdout or disk.
+import { spawnSync } from 'node:child_process';
+import { sopsIdentityEnv } from '../../../engine/secrets.mjs';
+import { resolveSops, runSelectedUpdateKeys } from './lib.mjs';
+
+/**
+ * Run `<bin> --config <config> updatekeys -y --input-type <inputType> <file>` (bin null: the sops resolveSops finds). An inline
+ * SOPS_AGE_KEY goes through the selected isolation (runSelectedUpdateKeys); a SOPS_AGE_KEY_FILE runs with the selected environment.
+ * {status, stdout, stderr, error}; stdout and stderr carry public key names only.
+ */
+export function updateKeys(bin, { file, config, inputType }, { invocation = null, env = process.env, cwd = undefined, timeout = undefined } = {}) {
+  const selected = sopsIdentityEnv(env, { required: true });
+  if (selected.error?.identityRefusal === 'inline-context-unqualified') return runSelectedUpdateKeys(bin, { file, config, inputType }, { selection: selected, invocation, env, cwd, timeout });
+  if (selected.error) return { status: null, stdout: '', stderr: '', error: selected.error };
+  const exe = bin ?? resolveSops(selected.env);
+  if (!exe) return { status: null, stdout: '', stderr: '', error: Object.assign(new Error('sops is not installed (Windows: winget install Mozilla.SOPS)'), { code: 'SOPS_MISSING' }) };
+  const r = spawnSync(exe, ['--disable-version-check', '--config', config, 'updatekeys', '-y', '--input-type', inputType, file], { cwd, env: selected.env, encoding: 'utf8', windowsHide: true, timeout, stdio: ['ignore', 'pipe', 'pipe'] });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, error: r.error ?? null };
+}

package/runtime/scripts/gates/starcistacks.mjs

@@ -329,7 +329,10 @@ const checkTrackedCustody = ({ repo, root, add }) => {
     // infra/** is tracked source, but a value file inside it (.env*, *.env, *.key, *.pem, *.tfvars)
     // is plaintext custody (inc-5360513a96b3: infra/compose/.env.generated was trackable).
     const infraValue = parts.length > 3 && parts[2] === 'infra' && isInfrastructureValueFile(base) && !base.endsWith('.enc') && !base.endsWith('.example');
-    if ((custodyArea && !base.endsWith('.enc') && !['KEYS.md', '.gitkeep'].includes(base)) || infraValue)
+    // An app's sealed member is `<env>/secrets/<member>.enc.yaml` (ruling app-secrets-one-standard, scripts/lib/sealed-member.mjs);
+    // runtime custody keeps `<name>.<fmt>.enc`.
+    const appMember = parts.length === 4 && parts[2] === 'secrets' && base.endsWith('.enc.yaml');
+    if ((custodyArea && !base.endsWith('.enc') && !appMember && !['KEYS.md', '.gitkeep'].includes(base)) || infraValue)
       add('refuse', 'STACKS_PLAINTEXT_TRACKED', file, /\.enc\.(?:ya?ml|json|env)$/u.test(base)
         ? `${base} is named the wrong way round: a custody file is <name>.<fmt>.enc (rename it to ${base.replace(/\.enc\.(ya?ml|json|env)$/u, '.$1.enc')}) and every read states the format (scripts/api/sops/exec-env.mjs)`
         : 'a custody member is tracked in plaintext; untrack it (git rm --cached), rotate the value and commit only its .enc twin');
@@ -363,7 +366,8 @@ const checkIgnoreRules = ({ repo, root, add }) => {
   }
 };
 // Custody layout (modules/schemas/stacks-layout.yaml custody, the product repositories' secrets-guard).
-const envDirs = (repo, root) => fs.readdirSync(path.join(repo, root), { withFileTypes: true }).filter((entry) => entry.isDirectory());
+// The images folder holds the managed db image of a lite app (slot app.db.image), never custody or an environment.
+const envDirs = (repo, root) => fs.readdirSync(path.join(repo, root), { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name !== 'images');
 const checkCustodyLayout = ({ repo, own, add }) => {
   if (!own.rooted) return;
   const root = STACK_ROOT;

package/runtime/scripts/guards/push-scan.mjs

@@ -54,7 +54,7 @@ function diffScanner(files = [], { encText = null, keepHit = null } = {}) {
       if (raw.startsWith('+++ ')) {
         flushEnc();
         file = raw.slice(4).replace(/^b\//, '');
-        if (/\.enc$/i.test(file)) enc = { file, line: null, added: [], findings: [] };
+        if (/\.enc(?:\.yaml)?$/i.test(file)) enc = { file, line: null, added: [], findings: [] };
         return;
       }
       const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(raw);

package/runtime/scripts/hfs/ci-declaration.mjs

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { isSealedName, memberOfName } from '../lib/sealed-member.mjs';
 import { list } from '../lib/list.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
 
@@ -70,7 +71,7 @@ function entries(dir, fs) {
 export function sealedKeyNames(root, { fs }) {
   const out = [], base = path.join(root, '.starcistacks');
   for (const env of entries(base, fs).filter((entry) => entry.isDirectory())) {
-    for (const member of entries(path.join(base, env.name, 'secrets'), fs).filter((entry) => entry.isFile() && entry.name.endsWith('.enc'))) {
+    for (const member of entries(path.join(base, env.name, 'secrets'), fs).filter((entry) => entry.isFile() && isSealedName(entry.name))) {
       const file = `.starcistacks/${env.name}/secrets/${member.name}`;
       const source = fs.readFileSync(path.join(root, file), 'utf8');
       const dotenv = [...source.matchAll(/^([A-Za-z_]\w*)=ENC\[/gm)].map((match) => match[1]).filter((key) => !key.startsWith('sops_'));
@@ -79,7 +80,7 @@ export function sealedKeyNames(root, { fs }) {
         const doc = parseYaml(source);
         keys = doc && typeof doc === 'object' && !Array.isArray(doc) ? Object.keys(doc).filter((key) => key !== 'sops' && !key.startsWith('sops_')) : [];
       }
-      for (const key of keys) out.push({ env: env.name, member: member.name.slice(0, -4), key, file });
+      for (const key of keys) out.push({ env: env.name, member: memberOfName(member.name), key, file });
     }
   }
   return out;