@starci/hfs 4.3.0 → 4.4.0

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

@@ -0,0 +1,121 @@
+# Illustrative production model. Replace all-zero application digests with verified published release digests before use.
+version: "3.8"
+services:
+  api:
+    image: "{{project}}/api:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+    environment:
+      NODE_ENV: production
+      PORT: "3001"
+      HTTP_SECURITY_ALLOWED_ORIGINS: https://{{project}}.example.invalid
+      PRIMARY_DB_URL_FILE: /run/secrets/primary-db-url
+      PRIMARY_DB_SCHEMA: public
+      SUPABASE_URL: https://{{project}}.supabase.co
+      SUPABASE_SERVICE_ROLE_KEY_FILE: /run/secrets/supabase-service-role-key
+    secrets:
+      - source: primary-db-url
+        target: primary-db-url
+      - source: supabase-service-role-key
+        target: supabase-service-role-key
+    networks: [app]
+    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
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+    deploy:
+      replicas: 1
+      placement:
+        constraints: ["node.labels.{{project}} == production"]
+      update_config:
+        parallelism: 1
+        order: start-first
+        failure_action: rollback
+        monitor: 30s
+      rollback_config:
+        parallelism: 1
+        order: stop-first
+      restart_policy:
+        condition: on-failure
+        delay: 5s
+  web:
+    image: "{{project}}/web:v0.0.0@sha256:0000000000000000000000000000000000000000000000000000000000000000"
+    environment:
+      NODE_ENV: production
+      PORT: "3000"
+      HOSTNAME: 0.0.0.0
+      NEXT_PUBLIC_SITE_URL: https://{{project}}.example.invalid
+    networks: [app]
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health/live').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      start_period: 20s
+      retries: 3
+    deploy:
+      replicas: 1
+      placement:
+        constraints: ["node.labels.{{project}} == production"]
+      update_config:
+        parallelism: 1
+        order: start-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:
+      - source: ingress-config
+        target: /etc/caddy/Caddyfile
+    ports:
+      - { target: 80, published: 80, protocol: tcp, mode: ingress }
+      - { target: 443, published: 443, protocol: tcp, mode: ingress }
+    volumes:
+      - ingress-data:/data
+      - ingress-config-data:/config
+    networks: [app]
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:2019/config/"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+    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
+networks:
+  app:
+    driver: overlay
+secrets:
+  primary-db-url:
+    external: true
+    name: "{{project}}-production-primary-db-url-v1"
+  supabase-service-role-key:
+    external: true
+    name: "{{project}}-production-supabase-service-role-key-v1"
+configs:
+  ingress-config:
+    file: ./Caddyfile
+volumes:
+  ingress-data:
+    external: true
+    name: "{{project}}-production-ingress-data"
+  ingress-config-data:
+    external: true
+    name: "{{project}}-production-ingress-config-data"

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

@@ -0,0 +1,21 @@
+# Production environment key roster
+
+This inventory declares names, consumers and mounted file paths. Scaffolding generates the two declared encrypted members with placeholder values encrypted to this app's own age recipient. Replace their values through `starci app secret set production` after owner provisioning and before creating external secrets. The runtime template tracks no ciphertext; its specs generate members with ephemeral identities in disposable copies. Scaffolding supplies no deployment credential or successful deployment.
+
+| Key | Consumer |
+| --- | --- |
+| `PORT` | API listener |
+| `HTTP_SECURITY_ALLOWED_ORIGINS` | API origin allowlist |
+| `PRIMARY_DB_URL` | API least-privilege database connection; reads `PRIMARY_DB_URL_FILE` at `/run/secrets/primary-db-url` |
+| `PRIMARY_DB_SCHEMA` | API primary database schema |
+| `SUPABASE_URL` | API Auth and Storage integration |
+| `SUPABASE_SERVICE_ROLE_KEY` | API Auth and Storage integration; reads `SUPABASE_SERVICE_ROLE_KEY_FILE` at `/run/secrets/supabase-service-role-key` |
+| `NEXT_PUBLIC_SITE_URL` | Front-end site URL |
+| `NEXT_PUBLIC_GRAPHQL_URL` | Front-end GraphQL transport |
+| `NEXT_PUBLIC_SUPABASE_URL` | Browser Auth client |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Browser Auth client public key |
+| `SUPABASE_ACCESS_TOKEN` | Production database deployment |
+| `SUPABASE_DB_PASSWORD` | Production database deployment |
+| `SUPABASE_PROJECT_ID` | Production database deployment |
+
+Public front-end configuration is supplied at build time and stays outside sealed custody. Set real values in `.starcistacks/production/secrets/primary-db-url.enc` and `.starcistacks/production/secrets/supabase-service-role-key.enc` at the declared paths. Versioned external application secrets are `{{project}}-production-primary-db-url-v1` and `{{project}}-production-supabase-service-role-key-v1`. Seal deployment-only credentials separately under `.starcistacks/production/secrets/*.enc`; they never enter an API container.

package/templates/app/skeleton-lite/.starciwork/brand/index.yaml

@@ -0,0 +1,12 @@
+schema: work/brand@1
+id: brand
+kind: brand
+state: todo
+rev: 1
+brand:
+  identity:
+    name: "{{project}}"
+review:
+  reviewer: the {{project}} owner
+  authority: "The lite scaffold seeds this record so the brand tree exists; the owner settles rev 1 of the brand before the first drawn surface."
+  reviewedAt: "2026-10-14T00:00:00Z"

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

@@ -4,7 +4,7 @@ One StarCi lite app: a Nest API in `be/`, one Next web app in `fe/`, and Supabas
 
 ## Overview
 
-The starter keeps one deployable API and one web app, with the same code structure as a full app: the web app calls the API over GraphQL (`src/modules/api`, SWR hooks under `src/hooks/swr`) and uses Supabase only for Auth in the browser (`src/modules/auth`); every data read and write goes through the API, which verifies the access token.
+The starter keeps one deployable API and one web app, with the same code structure as a full app: the web app calls the API over GraphQL (`fe/apps/web/src/modules/api`, SWR hooks under `fe/apps/web/src/hooks/swr`) and uses Supabase only for Auth in the browser (`fe/apps/web/src/modules/auth`); every data read and write goes through the API, which verifies the access token.
 
 ## Stack
 
@@ -14,9 +14,9 @@ TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, Supabas
 
 - `supabase/`: local configuration, forward-only SQL migrations, seed data, and generated database types.
 - `be/`: the API, shared platform capabilities, verified identity admission, and privileged Supabase integrations.
-- `fe/`: the web app; the only Supabase client is the Auth client of `src/modules/auth`, data goes through `src/modules/api`.
+- `fe/`: the web app; the only Supabase client is the Auth client of `fe/apps/web/src/modules/auth`, data goes through `fe/apps/web/src/modules/api`.
 - `.starcistacks/`: value-free environment metadata and encrypted-secret custody.
-- `.starciwork/`: `.gitignore`, `workspace.yaml` project metadata and repo roles, and optional `brand/` drawing records, references, and assets.
+- `.starciwork/`: `.gitignore`, `.starciwork/workspace.yaml` project metadata and repo roles, and optional brand drawing records, references, and assets.
 
 ## Development
 
@@ -34,6 +34,8 @@ The API reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS`, `PRIMARY_DB_URL`, `PRIMAR
 
 `npm test` runs the back end's unit specs with per-file coverage. Optional integration specs run with `npm run test:integration` against the local Supabase stack (`npm run db:start`); a lite app has no e2e world.
 
+The public runtime template tracks only sealed member names. Scaffolding creates this app's own age recipient and encrypts generated placeholder values into the declared `.starcistacks/<environment>/secrets/*.enc` members. Keep the matching host age identity in untracked local custody, then use `starci app secret set` to replace each placeholder with an actual value before deployment. Product apps retain sealed member custody. Runtime specs use disposable copies with ephemeral identities and remove them afterwards.
+
 ## Database changes
 
 Create a forward-only migration under `supabase/migrations`, keep each table's RLS policies and grants beside the table, and run `npm run contract:emit` to refresh `supabase/types/database.types.ts`. `starci app add table <name> --fe` adds the table with its GraphQL feature on the API and its operations and SWR hooks in the web app; `npm run codegen:graphql` regenerates the web app's wire types from `be/contracts/<app>/schema.graphql`.

package/templates/app/skeleton-lite/supabase/config.toml

@@ -3,7 +3,7 @@ project_id = "{{project}}"
 [api]
 enabled = true
 port = {{supabasePortApi}}
-schemas = ["public", "graphql_public"]
+schemas = []
 extra_search_path = ["public", "extensions"]
 max_rows = 1000
 
@@ -25,6 +25,13 @@ port = {{supabasePortInbucket}}
 [analytics]
 port = {{supabasePortAnalytics}}
 
+[edge_runtime]
+enabled = false
+
+[storage]
+enabled = true
+file_size_limit = "50MiB"
+
 [auth]
 enabled = true
 site_url = "http://127.0.0.1:3000"

package/templates/app/skeleton-lite/supabase/migrations/__timestamp___baseline.sql

@@ -1,5 +1,13 @@
-drop role if exists app_be;
-create role app_be login noinherit;
+do $$
+begin
+    if not exists (select 1 from pg_catalog.pg_roles where rolname = 'app_be') then
+        create role app_be login noinherit nosuperuser nobypassrls nocreatedb nocreaterole;
+    end if;
+end;
+$$;
+
+-- The attributes a Supabase migration role may change: SUPERUSER and BYPASSRLS stay as create role set them (the role migration owner is no superuser).
+alter role app_be login noinherit nocreatedb nocreaterole;
 
 create schema if not exists private;
 
@@ -24,6 +32,7 @@ create table public.profiles (
 );
 
 alter table public.profiles enable row level security;
+alter table public.profiles force row level security;
 
 create trigger profiles_set_updated_at
 before update on public.profiles
@@ -34,20 +43,20 @@ create policy profiles_app_be_select
 on public.profiles
 for select
 to app_be
-using (id is not null);
+using (current_user = 'app_be');
 
 create policy profiles_app_be_insert
 on public.profiles
 for insert
 to app_be
-with check (id is not null);
+with check (current_user = 'app_be');
 
 create policy profiles_app_be_update
 on public.profiles
 for update
 to app_be
-using (id is not null)
-with check (id is not null);
+using (current_user = 'app_be')
+with check (current_user = 'app_be');
 
 grant usage on schema public to app_be;
 revoke all on table public.profiles from public, anon, authenticated;

package/templates/app/upgrade-full/.starcistacks/dev/README.md

@@ -1,10 +1,16 @@
 # Development stack
 
-The full-edition development stack keeps PostgreSQL and the API in one declared Docker Compose project.
+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.
+Starter release images and external secrets must be prepared 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.
 
-- Prepare: provide `PRIMARY_DB_URL` to the API through the normal secret custody flow.
-- Up: `docker compose -f infra/compose/compose.yaml up -d`.
-- Status: `docker compose -f infra/compose/compose.yaml ps`.
-- Logs: `docker compose -f infra/compose/compose.yaml logs`.
-- Down: `docker compose -f infra/compose/compose.yaml down`.
-- Verify: call the API health endpoint and run `npm run lint`.
+| 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. 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`. |
+| logs | Run `docker service logs {{project}}-dev_api`; never print mounted credentials. |
+| down | Run `docker stack rm {{project}}-dev`. |
+| verification | Confirm the API `/health/live` and `/health/ready` endpoints, then run `npm run lint` from the app root. |
+
+Keep real sealed members under `.starcistacks/dev/secrets/*.enc`, add them to the manifest after sealing and inventory their key names in the environment record. The scaffold creates no fake secret or successful proof.

package/templates/be/image/worker/Dockerfile

@@ -32,5 +32,5 @@ RUN npm ci --omit=dev --ignore-scripts && npm cache clean --force
 COPY --from=build /app/be/dist be/dist
 
 USER node
-HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD pgrep -f "apps/{{app}}/src/main.js" > /dev/null || exit 1
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD ["node", "-e", "const fs=require('node:fs');const args=fs.readFileSync('/proc/1/cmdline','utf8').split(String.fromCharCode(0));process.exit(args.includes('be/dist/apps/{{app}}/src/main.js')?0:1)"]
 CMD ["node", "be/dist/apps/{{app}}/src/main.js"]

package/templates/be/inbox/database-client.spec.ts.tpl

@@ -1,4 +1,4 @@
-import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { mockEntityManager } from "@starci/jest-preset"
 import type { EntityManager } from "typeorm"
 import { sql } from "./database.sql"
 import { DatabaseErrorCode } from "./errors/database.error"
@@ -8,35 +8,34 @@ import { recordWebhookDelivery } from "./webhook-inbox.client"
 const INSERT = sql`SELECT id FROM record_spec_inbox($1, $2, $3::jsonb)`
 const PAYLOAD = { id: "delivery-1" }
 
-const record = (entityManager: EntityManager, deliveryId: string | undefined) =>
-    recordWebhookDelivery({ entityManager, insert: INSERT, provider: "spec", deliveryId, payload: PAYLOAD })
+const record = (manager: EntityManager, deliveryId: string | undefined) =>
+    recordWebhookDelivery({ manager, insert: INSERT, provider: "spec", deliveryId, payload: PAYLOAD })
 
 describe("recordWebhookDelivery", () => {
-    it("records a new delivery and commits before any business processing", async () => {
-        const transaction = fakeTransaction(mockEntityManager({ query: [INSERT, [{ id: "inbox-1" }]] }))
+    it("records a new delivery through the caller's transaction manager", async () => {
+        const manager = mockEntityManager({ query: [INSERT, [{ id: "inbox-1" }]] })
 
-        await record(transaction.em, "  delivery-1  ")
+        const receiptId = await record(manager, "  delivery-1  ")
 
-        expect(transaction.em.query).toHaveBeenCalledTimes(1)
-        expect(transaction.em.query).toHaveBeenCalledWith(INSERT, ["spec", "delivery-1", JSON.stringify(PAYLOAD)])
-        expect(transaction.commits).toBe(1)
+        expect(manager.query).toHaveBeenCalledTimes(1)
+        expect(manager.query).toHaveBeenCalledWith(INSERT, ["spec", "delivery-1", JSON.stringify(PAYLOAD)])
+        expect(receiptId).toBe("inbox-1")
     })
 
     it("acknowledges a duplicate without any completion or business write", async () => {
-        const transaction = fakeTransaction(mockEntityManager({ query: [INSERT, []] }))
+        const manager = mockEntityManager({ query: [INSERT, []] })
 
-        await record(transaction.em, "delivery-1")
+        const receiptId = await record(manager, "delivery-1")
 
-        expect(transaction.em.query).toHaveBeenCalledTimes(1)
-        expect(transaction.commits).toBe(1)
+        expect(manager.query).toHaveBeenCalledTimes(1)
+        expect(receiptId).toBeUndefined()
     })
 
-    it.each([["no", undefined], ["a blank", "   "]])("refuses %s delivery id before opening a transaction", async (_label, deliveryId) => {
-        const transaction = fakeTransaction(mockEntityManager())
+    it.each([["no", undefined], ["a blank", "   "]])("refuses %s delivery id before writing a receipt", async (_label, deliveryId) => {
+        const manager = mockEntityManager()
 
-        await expect(record(transaction.em, deliveryId)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+        await expect(record(manager, deliveryId)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
 
-        expect(transaction.outcomes).toEqual([])
-        expect(transaction.em.query).not.toHaveBeenCalled()
+        expect(manager.query).not.toHaveBeenCalled()
     })
 })

package/templates/be/inbox/database-client.ts.tpl

@@ -3,33 +3,34 @@ import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
 import type { SqlText } from "./database.sql"
 
 interface RecordWebhookDelivery {
-    readonly entityManager: EntityManager
+    readonly manager: EntityManager
     readonly insert: SqlText
     readonly provider: string
     readonly deliveryId: string | undefined
     readonly payload: object
 }
 
+type WebhookReceiptId = string | undefined
+
 /**
- * Records one pending delivery in one EntityManager transaction. The conflict-safe insert keeps redelivery a no-op.
+ * Records one pending delivery using the intake's transaction manager and returns its durable receipt identity.
  * Business processing and the completion marker belong to the reactor or job that consumes the committed row.
  */
 export const recordWebhookDelivery = async ({
-    entityManager,
+    manager,
     insert,
     provider,
     deliveryId,
     payload,
-}: RecordWebhookDelivery): Promise<void> => {
+}: RecordWebhookDelivery): Promise<WebhookReceiptId> => {
     const normalizedDeliveryId = deliveryId?.trim()
     if (!normalizedDeliveryId) {
         throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
     }
-    await entityManager.transaction(async (manager) => {
-        await manager.query(insert, [
-            provider,
-            normalizedDeliveryId,
-            JSON.stringify(payload),
-        ])
-    })
+    const rows: Array<{ readonly id: string }> = await manager.query(insert, [
+        provider,
+        normalizedDeliveryId,
+        JSON.stringify(payload),
+    ])
+    return rows[0]?.id
 }

package/templates/be/inbox/delivery-recorded.event.ts.tpl

@@ -0,0 +1,36 @@
+import { BaseEvent } from "@modules/platform/event-bus"
+import type { ParsedEvent } from "@modules/platform/event-bus"
+
+/** A durable receipt reference; processing reads the provider payload after the intake commits. */
+export interface @@Provider@@DeliveryRecordedPayload {
+    readonly receiptId: string
+}
+
+/** Version 1 of `@@provider@@.delivery-recorded`, published once by the provider inbox intake. */
+export class @@Provider@@DeliveryRecordedEvent extends BaseEvent {
+    static readonly eventName = "@@provider@@.delivery-recorded"
+    static readonly version = 1
+
+    readonly eventName = @@Provider@@DeliveryRecordedEvent.eventName
+
+    private constructor(
+        readonly eventId: string,
+        readonly payload: @@Provider@@DeliveryRecordedPayload,
+    ) {
+        super()
+    }
+
+    /** The receipt identity is stable across relay retries and distinct from a consumer's inbox source. */
+    static create(payload: @@Provider@@DeliveryRecordedPayload): @@Provider@@DeliveryRecordedEvent {
+        return new @@Provider@@DeliveryRecordedEvent(payload.receiptId, payload)
+    }
+
+    /** Reads an outbox envelope; malformed deliveries never reach a processing consumer. */
+    static parse(envelope: unknown): ParsedEvent<@@Provider@@DeliveryRecordedEvent> {
+        if (typeof envelope !== "object" || envelope === null || !("eventId" in envelope) || !("payload" in envelope)) return null
+        const { eventId, payload } = envelope
+        if (typeof eventId !== "string" || !eventId.trim() || typeof payload !== "object" || payload === null || !("receiptId" in payload)) return null
+        if (typeof payload.receiptId !== "string" || !payload.receiptId.trim()) return null
+        return new @@Provider@@DeliveryRecordedEvent(eventId, { receiptId: payload.receiptId })
+    }
+}

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

@@ -0,0 +1 @@
+export { @@Provider@@DeliveryRecordedEvent } from "./@@provider@@-delivery-recorded.event"

package/templates/be/inbox/events.json.tpl

@@ -0,0 +1,10 @@
+{
+  "events": {
+    "@@provider@@.delivery-recorded": {
+      "payload": { "receiptId": "string" },
+      "version": 1
+    }
+  },
+  "schema": "starci/event-contract@1",
+  "service": "@@provider@@"
+}

package/templates/be/inbox/migration.sql.tpl

@@ -9,6 +9,7 @@ create table public.@@table@@ (
 );
 
 alter table public.@@table@@ enable row level security;
+alter table public.@@table@@ force row level security;
 
 -- The dedicated app_be PostgreSQL role is the only application path. With no anon or authenticated policy,
 -- RLS denies those PostgREST roles by default; the service-role JWT is deliberately not granted here.

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

@@ -0,0 +1,42 @@
+/** The base of each typed event in modules/events: its stable identity, name and payload. */
+export abstract class BaseEvent {
+    /** A receiver uses this stable identity to deduplicate redelivery. */
+    abstract readonly eventId: string
+    /** The event name listed by the service's vendored event contract. */
+    abstract readonly eventName: string
+    /** The fact that a reactor or job processes after commit. */
+    abstract readonly payload: object
+}
+
+/** Parsing either returns the event or refuses a mismatched envelope. */
+export type ParsedEvent<Event extends BaseEvent> = Event | null
+
+/** The class side of a typed event, shared by publishers and later consumers. */
+export interface EventClass<Event extends BaseEvent> {
+    /** The contract's event name. */
+    readonly eventName: string
+    /** The contract's payload version. */
+    readonly version: number
+    /** Reads the event from its durable envelope. */
+    parse(envelope: unknown): ParsedEvent<Event>
+}
+
+/** One committed delivery received by a reactor. */
+export interface EventDelivery<Event extends BaseEvent> {
+    /** The consumer's idempotency key. */
+    readonly eventId: string
+    /** The typed event. */
+    readonly event: Event
+    /** The number of attempts, including this one. */
+    readonly attempt: number
+}
+
+/** The typed event's durable envelope, read only after the intake transaction commits. */
+export interface EventEnvelope {
+    /** The stable event id. */
+    readonly eventId: string
+    /** The contract's event name. */
+    readonly eventName: string
+    /** The data of the fact. */
+    readonly payload: object
+}

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

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { EventBus } from "./event-bus.port"
+
+/** Token of the transactional EventBus publisher. */
+export const EVENT_BUS: unique symbol = Symbol("platform.event-bus")
+
+/** Injects the EventBus port. Parameter type: EventBus. */
+export const InjectEventBus = (): TypedParameterDecorator<EventBus> => injector<EventBus>(EVENT_BUS)

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

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { EventBusOptions } from "./event-bus.options"
+
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<EventBusOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

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

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { EVENT_BUS } from "./event-bus.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./event-bus.module-definition"
+import { EventBusService } from "./event-bus.service"
+
+@Module({})
+/** Provides the transactional lite EventBus publisher, shared by domain intake services. */
+export class EventBusModule extends ConfigurableModuleClass {
+    /** Registers the publishing capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), { provide: EVENT_BUS, useClass: EventBusService }],
+            exports: [EVENT_BUS],
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+/** The lite publisher uses the caller's transaction and has no runtime options. */
+export interface EventBusOptions {}

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

@@ -0,0 +1,16 @@
+import type { EntityManager } from "typeorm"
+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>
+}
+
+/** A later message transport receives one typed event and forwards its delivery id. */
+export interface EventConsumer<Event extends BaseEvent> {
+    /** The event class the consumer reads. */
+    readonly event: EventClass<Event>
+    /** Applies one delivery after commit; a throw leaves the delivery available for retry. */
+    handle(delivery: EventDelivery<Event>): Promise<void>
+}

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

@@ -0,0 +1,45 @@
+import { Test } from "@nestjs/testing"
+import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { BaseEvent } from "./event-bus.contracts"
+import { EventBusService } from "./event-bus.service"
+import { INSERT_OUTBOX_EVENT } from "./persistence/event-bus.sql"
+
+class ReceiptRecordedEvent extends BaseEvent {
+    readonly eventId = "receipt-1"
+    readonly eventName = "spec.delivery-recorded"
+    readonly payload = { receiptId: "receipt-1" }
+}
+
+describe("EventBusService", () => {
+    const build = async () => {
+        const module = await Test.createTestingModule({ providers: [EventBusService] }).compile()
+        return module.get(EventBusService)
+    }
+
+    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))
+
+        expect(transaction.em.query).toHaveBeenCalledWith(INSERT_OUTBOX_EVENT, [
+            "receipt-1",
+            "spec.delivery-recorded",
+            JSON.stringify({ eventId: event.eventId, eventName: event.eventName, payload: event.payload }),
+        ])
+        expect(transaction.commits).toBe(1)
+    })
+
+    it("propagates an outbox failure so the receipt transaction rolls back", async () => {
+        const subject = await build()
+        const manager = mockEntityManager({ query: [INSERT_OUTBOX_EVENT, []] })
+        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")
+
+        expect(transaction.commits).toBe(0)
+        expect(transaction.rollbacks).toBe(1)
+    })
+})

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

@@ -0,0 +1,15 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import type { BaseEvent, EventEnvelope } from "./event-bus.contracts"
+import type { EventBus } from "./event-bus.port"
+import { INSERT_OUTBOX_EVENT } from "./persistence/event-bus.sql"
+
+@Injectable()
+/** 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)])
+    }
+}

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

@@ -0,0 +1,5 @@
+export { BaseEvent } from "./event-bus.contracts"
+export type { EventClass, EventDelivery, EventEnvelope, ParsedEvent } from "./event-bus.contracts"
+export { EVENT_BUS, InjectEventBus } from "./event-bus.decorators"
+export { EventBusModule } from "./event-bus.module"
+export type { EventBus, EventConsumer } from "./event-bus.port"

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

@@ -0,0 +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)`