@starci/hfs 4.2.17 → 4.3.0

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

@@ -12,7 +12,7 @@ appliesTo:
 family: be
 # The slot ids this topic teaches (knowledge/hfs/slots.yaml); scripts/gates/read-digest.mjs inverts these
 # into the READ-step slot -> pattern-topic map (knowledge/op-gate.yaml kinds), each slot's topics in index.yaml order.
-slots: [be.feature, be.feature.application]
+slots: [be.feature, be.feature.application, be.app.api]
 provenance:
   reviewedAt: 2026-10-02
   sources:
@@ -21,6 +21,7 @@ provenance:
     - knowledge/hfs/rules.yaml
     - owner-locked BE convention 2026-09-30
     - owner decision 2026-10-02 (features grouped by trigger kind; synchronous inside a context)
+    - owner ruling 2026-10-14 (app composition standard: options, compose/<area>.ts groups, budgets)
     - https://docs.nestjs.com/recipes/cqrs
   limitations: |-
     Static checks prove the shape of a feature, a message, its handler and the dispatch, and that SQL touches only tables its
@@ -245,6 +246,68 @@ rules:
       manual:
         - Confirm the spec asserts the error code of each refusal, not only a status.
     relatedExamples: [api]
+  - id: BE-API-4
+    title: An api app parses env separately and composes in area groups; its options hold values and port bindings only
+    kind: mandatory
+    hfsRules: [R245, R246, R32, R45, R43]
+    requirement: |-
+      An app's `src/` (slot `be.app.api`, and alike `be.app.worker` and `be.app.cli`) holds five app roles, each within the
+      line budget its slot names (owner ruling 2026-10-14):
+      - `main.ts` (80 lines) builds `EnvSource` once, imports and calls `read<App>Env` from `<app>.env.ts`, builds the options
+        and boots the app.
+      - `<app>.env.ts` (150) exports an explicit typed `<App>Env` interface and `read<App>Env(env: EnvSource): <App>Env`
+        (for example `ApiEnv` and `readApiEnv`). It holds fail-fast environment parsing only, via the app's `EnvSource` and
+        unchanged capability `parse<C>Config` helpers, with no localhost or default host fallback. Secrets use `env.secret`:
+        `EnvSource` resolves `<NAME>_FILE` first for `.starcistacks` custody, then plain `<NAME>` when the file key is absent.
+        It holds no logic, module composition, business code or feature imports. Only this app file and `main.ts` may read
+        `process.env` or `EnvSource`; `platform/config` owns the standard `EnvSource` reader. The role name stays
+        `<app>.env.ts`, never `env.ts`; its interface declares its own readonly parsed members, such as
+        `readonly server: ReturnType<typeof parseServerConfig>`, structurally compatible with the app's options.
+      - `<app>.options.ts` (200) holds the env-derived values plus its port bindings: provider maps such as
+        `{ approvalGate: ApprovalGateAdapter }`, with no environment parsing or reads of `process.env` or `EnvSource`.
+        Neither it nor `<app>.env.ts` holds an array
+        listing `*Module` classes, module or queue registrations (`register`, `forRoot`, `registerQueue`) or scheduler entries,
+        or an `imports`, `modules`, `schedulers` or `processors` list. The env file also refuses standalone module or queue
+        registration calls (`BE_APP_OPTIONS_COMPOSITION`).
+      - `compose/<area>.ts` (120) is a composition group: it exports the module list of one area of the app (the platform, the
+        background mechanisms with their message and queue doors, a product area), as a function of the options when it needs
+        them, and the providers of the area's global ports when it has any. It is composition only: no business logic, no
+        environment read (no `parse<C>Config`, `process.env` or `EnvSource` reads), and its `X.register({ isGlobal: true, ...options.x })` calls
+        count as the app root's registrations (R45).
+      - `app.module.ts` (250) imports the groups and spreads them into its `imports` (`...platformModules(options)`), registers
+        what is left, and binds the app-wide guards and filter.
+      A file over its budget is `BE_APP_COMPOSITION_BUDGET`; the budget is absolute, so an app root that outgrows 250 lines
+      moves an area into a new group, never into the env or options file. An entrypoint over 80 moves its parsing into the env file.
+    rationale: |-
+      A long app root invites moving its module lists into the options file, which then mixes configuration with composition
+      and grows without a bound. One group per area keeps each composition reviewable, the options pure data, and the root a
+      table of contents. The env file keeps typed, fail-fast parsing visible while the entrypoint stays within 80 lines.
+    cases:
+      - id: case-1
+        when: A new api app is scaffolded
+        write: 'apps/api/src/compose/platform.ts exports platformModules(options) (clock, logging, i18n, errors, cqrs, http security, database), and app.module.ts spreads ...platformModules(options) before the domain modules and the guards.'
+      - id: case-2
+        when: The app root passes 250 lines because every module is listed in it
+        write: 'Move one area into apps/<app>/src/compose/<area>.ts (for example compose/background.ts with the event bus, the queue and its schedulers, the jobs and the message and queue doors) and spread it in app.module.ts.'
+      - id: case-3
+        when: 'api.options.ts exports `modules: [...]`, a `BullModule.registerQueue(...)` list or `schedulers: [orderExpirySchedulerOf(...)]`'
+        write: 'Refused (BE_APP_OPTIONS_COMPOSITION): keep only the parsed values (orderExpiry: { everyMs, olderThanMs }) and the port map in the options; the list goes into compose/<area>.ts.'
+      - id: case-4
+        when: An api app reads capability configuration
+        write: 'api.env.ts exports interface ApiEnv and readApiEnv(env: EnvSource): ApiEnv (at most 150 lines); main.ts passes its EnvSource to that reader and builds AppOptions from the parsed values and port bindings within 80 lines. No module list or feature import goes into api.env.ts.'
+    verification:
+      automated:
+        - BE_APP_OPTIONS_COMPOSITION
+        - BE_APP_COMPOSITION_BUDGET
+        - BE_APP_COMPOSITION_ONLY
+        - BE_APP_BUSINESS_ROLE
+        - BE_MODULE_SHAPE
+        - BE_MODULE_HANDLER_REGISTRATION
+        - BE_MODULE_PROVIDER_REREGISTRATION
+        - BE_CONFIG_OWNER
+      manual:
+        - Confirm each group is one area of the app and holds no decision a capability should own.
+    relatedExamples: [api]
   - id: BE-OPERATIONS-1
     title: A versioned operation is declared once in the app's typed operation table
     kind: mandatory

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

@@ -41,8 +41,16 @@ rules:
       nest-commander and never serves: no `NestFactory.create*`, no `.listen()`, no microservice connection, no
       `@nestjs/platform-*` adapter and no `@nestjs/microservices`. `apps/cli/src/app.module.ts` composes the platform modules
       the commands need (the database capability over every connection with its entities and migrations, like an api app) and
-      the static cli feature root module `CliModule`; `apps/cli/src/cli.options.ts` carries what the cli reads from the
-      environment, the connections it migrates among them.
+      the static cli feature root module `CliModule`. `apps/cli/src/cli.env.ts` (at most 150 lines) exports an explicit typed
+      `CliEnv` interface and `readCliEnv(env: EnvSource): CliEnv` using `EnvSource` and unchanged capability parse helpers.
+      The interface declares its own readonly parsed members with types matching those helpers; the options factory binds
+      these values to its connection list.
+      It holds fail-fast parsing only, with no localhost or default host fallback, logic, module composition, business code
+      or feature imports. Secrets use `env.secret`, with `<NAME>_FILE` first for `.starcistacks` custody, then plain `<NAME>`
+      when the file key is absent. `main.ts` (at most 80 lines) builds `EnvSource` once and imports and calls `readCliEnv`.
+      Only these two app files may read the environment; the role name stays `cli.env.ts`, never `env.ts`.
+      `apps/cli/src/cli.options.ts` carries the env-derived values and port bindings, the connections it migrates among them,
+      with no parsing or reads of `process.env` or `EnvSource`; compose groups never read the environment either.
     rationale: |-
       One image for every operator action gives one place to find, deploy and audit them, and a process that never listens
       cannot become a second, unguarded door into the application.
@@ -52,7 +60,9 @@ rules:
         write: |-
           // be/apps/cli/src/main.ts
           async function bootstrap(): Promise<void> {
-              await CommandFactory.run(AppModule.register(parseCliOptions(EnvSource.fromProcess())), new JsonLinesLogger())
+              const env = EnvSource.fromProcess()
+              const options = createCliAppOptions(readCliEnv(env))
+              await CommandFactory.run(AppModule.register(options), new JsonLinesLogger())
           }
           void bootstrap()
       - id: case-2
@@ -60,7 +70,7 @@ rules:
         write: 'Refused (BE_CLI_BOOTSTRAP): the cli app boots only through CommandFactory.run.'
       - id: case-3
         when: A back end declares a connection and has no apps/cli
-        write: 'Refused (BE_CLI_REQUIRED): add be/apps/cli with main.ts, app.module.ts, cli.options.ts and its Dockerfile, declared as { "name": "cli", "kind": "cli" } in hfs.json sides.be.apps.'
+        write: 'Refused (BE_CLI_REQUIRED): add be/apps/cli with main.ts, app.module.ts, cli.env.ts, cli.options.ts and its Dockerfile, declared as { "name": "cli", "kind": "cli" } in hfs.json sides.be.apps.'
     verification:
       automated:
         - BE_CLI_REQUIRED
@@ -196,10 +206,18 @@ files:
   - path: apps/cli/src/cli.options.ts
     slot: be.app.cli
     optional: true
-    role: what the cli reads from the environment, the connection list it migrates among them
+    role: env-derived values and port bindings without parsing, the connection list it migrates among them
     rules:
       - BE_CLI_REQUIRED
       - BE_SCHEMA_AUTHORITY
+  - path: apps/cli/src/cli.env.ts
+    slot: be.app.cli
+    optional: true
+    role: 'exports interface CliEnv and readCliEnv(env: EnvSource): CliEnv; fail-fast parsing only, no localhost fallback, logic, composition, business code or feature imports; secrets use env.secret with _FILE first'
+    rules:
+      - BE_CONFIG_OWNER
+      - BE_APP_OPTIONS_COMPOSITION
+      - BE_APP_COMPOSITION_BUDGET
   - path: src/features/cli/index.ts
     slot: be.cli
     optional: true

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

@@ -3,25 +3,34 @@ id: be.feature.webhooks
 title: Provider webhooks
 purpose: |-
   Given a delivery a payment, identity or shipping provider POSTs to us, how is it received? A webhook is a feature KIND:
-  `be/src/features/webhooks/<provider>/` holds one signed door that proves the delivery came from the provider (signature and
-  replay window), then hands it to exactly ONE domain intake method. That method records the delivery (deduplicated through the
-  inbox) and publishes the domain event with `eventBus.publish(event, tx)` inside its own transaction, because publishing is
-  allowed only from `modules/domain`. The door writes nothing and decides nothing; everything after the proof is an event.
+  `be/src/features/webhooks/<provider>/` holds one signed door whose first call proves the delivery came from the provider
+  (signature and replay window), either separately or inside its ONE domain method that combines verification and intake. The
+  intake records the delivery (deduplicated through the inbox) and publishes a typed receipt event with
+  `eventBus.publish(event, tx)` inside its own transaction, because publishing is allowed only from `modules/domain`.
+  A reactor or job consumes the durable receipt and dispatches the processing command. Neither the door, its HTTP module,
+  nor its called domain intake dispatches on a command/query bus or feature handler. A provider may receive a declared fixed `PROVIDER_ACK` body;
+  a subscription provider may also use one GET verifier that echoes its challenge result.
 appliesTo:
   - backend
 family: be
 provenance:
-  reviewedAt: 2026-10-02
+  reviewedAt: 2026-10-14
   sources:
     - knowledge/hfs/README.md
     - knowledge/hfs/slots.yaml
     - knowledge/hfs/rules.yaml
     - knowledge/patterns/be/api-auth.yaml
     - knowledge/patterns/be/idempotency.yaml
+    - knowledge/patterns/be/event-bus.yaml
+    - knowledge/patterns/be/reactors.yaml
+    - knowledge/patterns/be/jobs.yaml
     - owner decision 2026-10-02 (feature kinds: webhooks, realtime, reactors, saga, jobs, cli; no kind imports another)
+    - owner decision 2026-10-14 (literal provider ACK, one optional GET challenge, durable inbox handoff before reactor/job command dispatch)
   limitations: |-
-    Static checks prove the door's shape, that the proof is its first statement and that the only thing it can call after it is
-    one domain service method. They do not prove the HMAC scheme matches the provider's documentation, that the replay window
+    Static checks prove the door's shape, that an unconditional verification call is its first statement and that it makes
+    one intake call, either after a separate proof or combined with it. They resolve direct command/query-bus and feature-handler receivers in the called
+    domain intake; helper calls, dynamic receivers and unavailable method bodies need semantic review. They do not prove that a domain verifier completes proof
+    before intake, that the signature scheme matches the provider's documentation, that the replay window
     is the right length or that the intake is idempotent; the provider fake of the test world and the three
     `webhooks/*` scenarios prove those against the real stack.
 rules:
@@ -33,7 +42,8 @@ rules:
       A provider webhook lives in `be/src/features/webhooks/<provider>/` (slot `be.feature.webhooks`), enabled by declaring the pattern
       `webhooks` in `hfs.json` `sides.be.patterns`. The folder holds `index.ts` (the module class an app composes), `transport/http/<provider>-http.module.ts`, `transport/http/<provider>.webhook.ts` (the
       door), `<provider>.webhook.spec.ts` (its spec — the kind's door has no service of its own, so the door carries it) and an optional `transport/http/dto/` of typed
-      payload classes (`<event>.request.ts`). Nothing else exists there: no application layer, no handler, no consumer. The kind
+      payload classes (`<event>.request.ts`). `PROVIDER_ACK`, when needed, is an exported typed literal constant in the door or
+      its own HTTP module. Nothing else exists there: no application layer, no handler, no consumer. The kind
       imports only `modules/*`, never another kind, and only an api-kind app composes `<provider>-http.module.ts`.
     rationale: |-
       A webhook is an external caller we do not control, so its door is kept apart from the api features a client uses. One place
@@ -76,24 +86,128 @@ rules:
         - Confirm the provider endpoint is one door and that a second endpoint of the same provider is a second door only when it has a different proof.
     relatedExamples: [webhooks]
   - id: BE-WEBHOOK-2
-    title: The door verifies first, then makes one domain call
+    title: The door verifies first and hands the delivery to one domain intake
     kind: mandatory
     hfsRules: [R182, R183, R41, R42, R203]
     requirement: |-
-      `<provider>.webhook.ts` is one `@Controller` with one `@Post` handler declared
-      `@Public({ reason: PublicReason.SignedWebhook })`, thin (R203 `BE_FEATURE_THIN`). The handler's FIRST statement is the unconditional
-      `this.<signature>.verify({ provider, rawBody, signature, timestamp })` of the `WebhookSignatureService` of `platform/http-security`
-      (HMAC-SHA256 over `<timestamp>.<raw body>` with the provider's secret, a constant-time comparison and a replay window on the signed timestamp; it throws before anything else runs). The provider key and its secret and tolerance are options of `platform/http-security` (`options.webhooks[provider]`). The
-      second and last call is one method of a domain service, the intake. The door injects only that service and the signature
-      service (injected with `@InjectWebhookSignature()`), holds no branch, loop or `try`, calls nothing else (no parsing, mapping or publishing) and returns nothing: the
-      provider gets its status code and an empty body. `@RateLimit(RateTier.Strict)` is required by the signed-webhook reason.
+      `<provider>.webhook.ts` is one `@Controller` with exactly one `@Post` handler and optionally one `@Get` subscription
+      challenge handler. Each handler is declared
+      `@Public({ reason: PublicReason.SignedWebhook })`, thin (R203 `BE_FEATURE_THIN`). The handler's FIRST statement is an unconditional
+      direct verification call, awaited when async: either `this.<signature>.verify({ provider, rawBody, signature, timestamp })`
+      of the `WebhookSignatureService` of `platform/http-security` or a domain verifier. No data access, nested call or other work
+      may run in the door before that proof call. The shared service uses HMAC-SHA256 over `<timestamp>.<raw body>`, a constant-time
+      comparison and a replay window on the signed timestamp; its provider key, secret and tolerance are `platform/http-security`
+      options (`options.webhooks[provider]`). A domain verifier owns the provider's proof when secrets belong to individual
+      connections, as for the billing payment webhooks; it refuses an invalid delivery before intake.
+      A domain verifier is a method on a service declared in a domain `<name>.service.ts` whose declared class name ends in
+      `Verifier` or `verify`, or an exact domain service method declared by the adjacent `<provider>-http.module.ts` as
+      `export const webhookVerifiers = [BillingService.prototype.receiveCassoWebhook] as const`. The array names TypeScript
+      method symbols, never strings; a local alias or a class from the platform, integrations or a package grants no domain proof.
+      A separate verification call is followed by exactly one domain intake call. A domain method that verifies and then performs
+      intake may be the first and only call; a separate domain verification call does not count as intake. The door injects only
+      domain services and, when used, the signature service (injected with `@InjectWebhookSignature()`), holds no branch, loop or
+      `try`, and calls nothing else (no parsing, mapping or publishing). Neither the door nor its HTTP module imports or injects
+      `CommandBus`, `QueryBus` from `@nestjs/cqrs`, or a feature command handler. The called domain intake must not dispatch on
+      a command or query bus or feature handler either; it records the inbox receipt and outbox event so a reactor or job can dispatch after commit.
+      The POST handler returns nothing (an empty body) or exactly `return PROVIDER_ACK`. That exported constant belongs to the
+      same webhook feature, is declared with `as const` or a readonly literal type, and contains only literal object values or
+      a literal string. Calls, interpolated templates, spreads, input-derived values, inline returned objects and constants of
+      another feature are refused. A provider acknowledgement does not weaken the first-statement proof requirement.
+      The optional GET starts with a declared domain verifier's challenge call, awaited when async, and returns exactly that
+      call's result: `const challenge = this.verifier.challenge(query); return challenge`, or directly returns that call.
+      It makes no intake call and computes no other response. `@RateLimit(RateTier.Strict)` is required on both signed-webhook handlers.
     rationale: |-
-      The signature is the authentication of a public door. Making the proof the first statement removes every path to the intake
-      that skips it, and a door with one call and no decision has nothing left to test except the proof and the hand-over.
+      The signature is the authentication of a public door. Making verification the first statement removes every door path that
+      skips it; a combined domain method must finish that proof before intake. Keeping one intake and no decision leaves the door
+      with only the proof and the hand-over to test.
     cases:
       - id: case-1
         when: A delivery whose raw body must be hashed
         write: 'enable the raw body for the app (`NestFactory.create(..., { rawBody: true })` in the api app) and read `request.rawBody`; never hash a re-serialized `body`.'
+      - id: case-2
+        when: A payment provider uses a different secret for each billing connection
+        write: 'declare BillingService.prototype.receiveCassoWebhook in the adjacent HTTP module webhookVerifiers array; the first and only handler statement awaits that method, which resolves the connection secret, verifies the provider proof and delegates to the intake. The door never reads the connection or payment data itself.'
+      - id: case-3
+        when: 'A provider requires exactly {"success": true} instead of an empty acknowledgement'
+        write: |-
+          In the webhook door's own file declare `export const PROVIDER_ACK = { success: true } as const`.
+          After the first verification call and the one domain intake call, return `PROVIDER_ACK` with the provider's required
+          status code. `return { success: true }`, `return { success: delivery.accepted }`, a spread, a computed constant,
+          and an ACK imported from another feature remain findings.
+      - id: case-4
+        when: A Meta-style provider uses GET subscription verification and POST deliveries
+        write: |-
+          Worked tree (the webhook and reactor are separate kinds; the app composes their modules):
+          be/src/features/webhooks/meta/index.ts
+          be/src/features/webhooks/meta/transport/http/meta-http.module.ts
+          be/src/features/webhooks/meta/transport/http/meta.webhook.ts
+          be/src/features/webhooks/meta/transport/http/meta.webhook.spec.ts
+          be/src/features/webhooks/meta/transport/http/dto/meta-challenge.request.ts
+          be/src/features/webhooks/meta/transport/http/dto/meta-event.request.ts
+          be/src/modules/domain/meta/index.ts
+          be/src/modules/domain/meta/meta-verifier.service.ts
+          be/src/modules/domain/meta/meta.service.ts
+          be/src/modules/events/core/meta-delivery-recorded.event.ts
+          be/src/features/reactors/meta-intake/index.ts
+          be/src/features/reactors/meta-intake/meta-intake.module.ts
+          be/src/features/reactors/meta-intake/application/process-meta-delivery.command.ts
+          be/src/features/reactors/meta-intake/application/process-meta-delivery.handler.ts
+          be/src/features/reactors/meta-intake/application/process-meta-delivery.contracts.ts
+          be/src/features/reactors/meta-intake/transport/message/meta-delivery-recorded.consumer.ts
+          be/src/features/reactors/meta-intake/transport/message/meta-intake-message.module.ts
+
+          meta.webhook.ts:
+          import { Body, Controller, Get, Headers, HttpCode, HttpStatus, Post, Query, Req } from "@nestjs/common"
+          import type { RawBodyRequest } from "@nestjs/common"
+          import type { Request } from "express"
+          import { Public, PublicReason } from "@modules/domain/identity"
+          import { MetaService, MetaVerifier } from "@modules/domain/meta"
+          import { RateLimit, RateTier } from "@modules/platform/http-security"
+          import { MetaChallengeRequest } from "./dto/meta-challenge.request"
+          import { MetaEventRequest } from "./dto/meta-event.request"
+
+          export const PROVIDER_ACK = "EVENT_RECEIVED" as const
+
+          @Controller("webhooks/meta")
+          export class MetaWebhook {
+              constructor(private readonly verifier: MetaVerifier, private readonly deliveries: MetaService) {}
+
+              @Get()
+              @Public({ reason: PublicReason.SignedWebhook })
+              @RateLimit(RateTier.Strict)
+              challenge(@Query() query: MetaChallengeRequest): string {
+                  const challenge = this.verifier.challenge(query)
+                  return challenge
+              }
+
+              @Post()
+              @HttpCode(HttpStatus.OK)
+              @Public({ reason: PublicReason.SignedWebhook })
+              @RateLimit(RateTier.Strict)
+              async receive(
+                  @Req() request: RawBodyRequest<Request>,
+                  @Headers("x-hub-signature-256") signature: string | undefined,
+                  @Body() delivery: MetaEventRequest,
+              ): Promise<typeof PROVIDER_ACK> {
+                  await this.verifier.verify({ rawBody: request.rawBody, signature })
+                  await this.deliveries.recordMetaDelivery(delivery)
+                  return PROVIDER_ACK
+              }
+          }
+
+          meta-http.module.ts:
+          import { Module } from "@nestjs/common"
+          import { MetaWebhook } from "./meta.webhook"
+
+          @Module({ controllers: [MetaWebhook] })
+          export class MetaHttpModule {}
+
+          MetaVerifier is declared in meta-verifier.service.ts. Its challenge method proves the subscription mode and verify
+          token before returning the challenge field unchanged; its verify method owns Meta's signature proof and delivery
+          freshness policy. MetaService.recordMetaDelivery only records the delivery and its outbox receipt in one transaction
+          (case-1 of BE-WEBHOOK-3). The reactor consumes that receipt and dispatches ProcessMetaDeliveryCommand after commit.
+          The provider's real GET and POST proof schemes belong in the verifier, rather than being assumed to match the shared
+          timestamp/HMAC convention. The api app composes MetaHttpModule; an api or worker app composes MetaIntakeMessageModule.
     verification:
       automated:
         - BE_WEBHOOK_SHAPE
@@ -102,33 +216,58 @@ rules:
         - BE_INPUT_BOUNDED
         - BE_FEATURE_THIN
       manual:
-        - Review that the raw body, not a re-serialized one, is verified, and that the replay window matches the provider's tolerance.
+        - Review that the raw body, not a re-serialized one, is verified, that the replay window matches the provider's tolerance, and that a domain verifier refuses the delivery before intake or business data access.
+        - Trace intake helpers and dynamic dispatch that static resolution cannot inspect; none may dispatch a command before the receipt is durable.
     relatedExamples: [webhooks]
   - id: BE-WEBHOOK-3
-    title: The intake publishes the event inside its own transaction
+    title: The intake records the inbox receipt; a reactor or job dispatches after commit
     kind: mandatory
     hfsRules: [R80, R152, R151]
     requirement: |-
-      The domain intake method (`PaymentService.acceptNotification`) is the delivery method of R80: its first awaited expression
+      The sanctioned path is `verify -> inbox.record -> reactor/job dispatches the command`. `inbox.record` describes the
+      domain intake's durable recording responsibility, not a new method on the shared `Inbox` port: the real port has `claim`.
+      The domain intake method (`PaymentService.recordPaymentDelivery`) is the delivery method of R80: its first awaited expression
       claims `(source, eventId)` in the `Inbox` and it returns when the claim answers false, so a redelivery is a no-op. It then
-      records the delivery and calls `this.eventBus.publish(PaymentConfirmedEvent.create({...}), manager)` inside the same
+      records the provider payload or a durable receipt reference and calls
+      `this.eventBus.publish(PaymentDeliveryRecordedEvent.create({...}), manager)` inside the same
       transaction (`entityManager.transaction`). The events are typed classes in `modules/events/<service>/<event>.event.ts` that
-      equal their `be/contracts/<service>/events.json` entry (`payment.confirmed`, `payment.failed`). The webhook door never
-      imports `modules/events` or the event bus.
+      equal their `be/contracts/<service>/events.json` entry (`payment.delivery-recorded`). The webhook door never imports
+      `modules/events` or the event bus. The door, HTTP module and called intake do not reach a command or query bus or feature
+      handler. A reactor consumes the receipt event and dispatches its own command, forwarding the delivered `eventId` and
+      receipt reference; its domain service claims that separate consumer delivery before processing the receipt. A job may
+      instead consume a transactionally enqueued receipt reference under the queue and fenced-job patterns.
     rationale: |-
       Recording the delivery and writing the outbox row in one transaction means a crash cannot lose or duplicate the event, and
       keeping the publish in `modules/domain` keeps one place that owns the transaction boundary.
     cases:
       - id: case-1
-        when: A confirmed payment arrives
-        write: 'acceptNotification claims the inbox row, updates the payment row and publishes PaymentConfirmedEvent in one transaction; a second delivery of the same eventId changes nothing.'
+        when: A payment provider retries a delivery whose processing belongs in a reactor
+        write: |-
+          The POST handler verifies first, then calls PaymentService.recordPaymentDelivery(delivery) once. That domain method
+          runs entityManager.transaction(async (manager) => { ... }): its first awaited statement claims
+          this.inbox.claim(PAYMENT_SOURCE, delivery.eventId, manager), and a false answer returns. With the same manager it
+          saves the durable receipt and publishes PaymentDeliveryRecordedEvent carrying that receipt's id. Its method never
+          dispatches CommandBus.execute. The outbox relay delivers the committed event to
+          features/reactors/payment-intake/transport/message/payment-delivery-recorded.consumer.ts:
+
+          async handle(delivery: EventDelivery<PaymentDeliveryRecordedEvent>): Promise<void> {
+              await this.commandBus.execute(new ProcessPaymentDeliveryCommand({
+                  request: { eventId: delivery.eventId, receiptId: delivery.event.payload.receiptId },
+              }))
+          }
+
+          The command's handler delegates to its domain service; that service claims the reactor delivery id and processes the
+          saved receipt in its transaction. A duplicate provider POST records nothing more, and a duplicate relay delivery
+          processes nothing twice. The command, handler and consumer live in the reactor's own kind; no feature imports the
+          webhook kind. The equivalent job path enqueues a receipt reference in the recording transaction and processes it
+          through the job's platform claim and fencing, never synchronously in the POST handler.
     verification:
       automated:
         - BE_INBOX_DEDUPE_MISSING
         - BE_OUTBOX_WRITE_TX
         - BE_EVENT_CLASS_CONTRACT
       manual:
-        - Confirm each provider event kind maps to exactly one published event and that an unknown kind is acknowledged and ignored, not published.
+        - Confirm each accepted provider delivery records at most one receipt and outbox event, and the reactor or job alone dispatches processing commands.
     relatedExamples: [webhooks]
   - id: BE-WEBHOOK-4
     title: Three behaviours are proven on the test world
@@ -140,8 +279,9 @@ rules:
       refused and nothing is published) and `accepted-delivery-publishes-once` (a valid delivery publishes the event once and a
       redelivery publishes nothing more). The provider is the network-edge fake of the test world (`world.fake.<provider>`), which
       signs with the test secret; a real provider is never called. The unit spec `<provider>.webhook.spec.ts` covers the door
-      itself with the Nest testing module, a real `WebhookSignatureService` configured with a test secret and a double of the
-      domain service.
+      itself with the Nest testing module and the verifier it uses: a real `WebhookSignatureService` configured with a test secret
+      or a real domain verifier configured with the connection's test secret, plus a double of a separate intake service. A method
+      that combines verification and intake has its domain service spec proving refusal before intake and the door spec proving delegation.
     rationale: |-
       The door has no logic of its own, so the risk is in the wiring: the raw body, the headers, the real signature scheme and the
       transaction behind the intake. Only a signed request through the real app proves it.
@@ -167,7 +307,7 @@ files:
   - path: src/features/webhooks/<provider>/transport/http/<provider>.webhook.ts
     slot: be.feature.webhooks.http
     template: webhooks/webhook.door.ts.tpl
-    role: The signed door, one controller with one POST handler.
+    role: The signed door, one controller with one POST handler and optionally one GET challenge verifier; an own-feature PROVIDER_ACK is a fixed literal.
     rules: [BE_WEBHOOK_SHAPE, BE_WEBHOOK_UNVERIFIED, BE_DEFAULT_DENY, BE_INPUT_BOUNDED]
     spec: src/features/webhooks/<provider>/transport/http/<provider>.webhook.spec.ts
   - path: src/features/webhooks/<provider>/transport/http/<provider>.webhook.spec.ts
@@ -181,12 +321,12 @@ files:
     template: webhooks/webhook.request.ts.tpl
   - path: src/modules/platform/http-security/webhook-signature.service.ts
     slot: be.platform
-    role: WebhookSignatureService, the one owner of the signature and replay proof.
+    role: WebhookSignatureService, the shared signature and replay proof when provider secrets are platform options.
     spec: src/modules/platform/http-security/webhook-signature.service.spec.ts
     optional: true
   - path: src/modules/domain/<capability>/<capability>.service.ts
     slot: be.domain
-    role: The intake method, which claims the inbox and publishes the event in its transaction.
+    role: The domain verifier or intake method, which may combine per-connection proof with inbox claim, durable receipt recording and outbox publishing in its transaction; no command/query-bus or feature-handler dispatch.
     rules: [BE_INBOX_DEDUPE_MISSING, BE_OUTBOX_WRITE_TX]
     optional: true
   - path: src/modules/events/<service>/<event>.event.ts
@@ -194,9 +334,24 @@ files:
     role: The typed event the intake publishes.
     rules: [BE_EVENT_CLASS_CONTRACT]
     optional: true
+  - path: src/features/reactors/<reactor>/transport/message/<event>.consumer.ts
+    slot: be.transport.message
+    role: Optional reactor consumer of the durable receipt event; forwards its eventId and receipt reference in one command after commit.
+    rules: [BE_EVENT_CONSUMER_SHAPE, BE_FEATURE_THIN]
+    optional: true
   - path: src/tests/e2e/<area>/<provider>-webhook.e2e-spec.ts
     slot: be.tests.e2e
     role: "Titles webhooks/<scenario>: ... prove the pattern against the provider fake."
     spec: webhooks/bad-signature-is-refused, webhooks/replay-is-refused, webhooks/accepted-delivery-publishes-once
     rules: [BE_PATTERN_SPEC_MISSING]
     optional: true
+sourceMaintenance: >-
+  The add webhook verb keeps the default empty acknowledgement and does not add a consumer. In full, the generated POST
+  verifies first and calls the supplied domain service's record<Provider>Delivery once. Implement that method as the
+  transactional inbox receipt/outbox recording intake above, then add its reactor or job separately.
+  In lite, the generated POST verifies first and calls <Provider>InboxService.record<Provider>Delivery. This record-only
+  domain intake uses recordWebhookDelivery to insert a pending provider inbox row atomically in Supabase Postgres, unique on
+  (provider, delivery_id), without processing it or marking it complete. Add a reactor or job separately to consume the
+  committed pending row and dispatch the processing command (reactors.yaml, jobs.yaml). The --service option validates the
+  future domain processing owner; the webhook writer does not import or call that owner synchronously and does not
+  synthesize a consumer.

package/runtime/knowledge/patterns/fe/folder.yaml

@@ -174,6 +174,9 @@ rules:
       component.tsx. Pure blocks, composites, branches and leaves use index.tsx only and never gain an
       empty twin. classNames.ts is present only when the unit owns class strings. Budgets: component.tsx 300 lines,
       connected index.tsx 200 lines, at most 6 data hooks and 6 useState per connected unit.
+      A composition-only feature may render an existing public pure component owner directly instead of creating a
+      forwarding component.tsx. The route-state overlay host of FE-BOUNDARY-5 renders components/branches/OverlayHost;
+      a connected block still requires its exact private Base twin.
     rationale: |
       Stable basenames make class names and the connected and presentational split discoverable without forwarding
       twins, and budgets keep a unit reviewable.

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

@@ -245,7 +245,7 @@ BE_APP_BUSINESS_ROLE:
 BE_APP_COMPOSITION_ONLY:
   title: "Composition root has stray source"
   title_vi: "Gốc ghép nối có tệp lạc chỗ"
-  meaning_vi: "Mã trong ứng dụng gốc không phải tệp mà slot ứng dụng cho phép (main.ts, app.module.ts, <app>.options.ts; operations.ts ở ứng dụng API)."
+  meaning_vi: "Mã trong ứng dụng gốc không phải tệp mà slot ứng dụng cho phép (main.ts, app.module.ts, <app>.env.ts, <app>.options.ts, compose/<area>.ts; operations.ts ở ứng dụng API)."
   causes_vi:
     - "Thêm tệp không đúng tên vào thư mục ứng dụng gốc"
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
@@ -802,11 +802,11 @@ DB_DYNAMIC_DDL:
   kind: check-finding
 
 DB_MIGRATION_SHAPE:
-  title: "A migration is named `<ts14>_<kebab>.sql`, stamped in valid past UTC, ordered after the base's migrations, and immutable once on the base"
+  title: "A migration is named `<ts14>_<kebab>.sql`, stamped in valid UTC, appended after HEAD's active migrations, and immutable once on the base"
   title_vi: "Migration sai hình dạng hoặc bị sửa"
-  meaning_vi: "`<path>` vi phạm luật migration: tên phải là `<ts14>_<kebab>.sql`, stamp là thời điểm UTC thật không ở tương lai, migration mới xếp sau mọi migration trên base, và migration đã lên base là bất biến (sửa hay xoá đều là finding)."
+  meaning_vi: "`<path>` vi phạm luật migration: tên phải là `<ts14>_<kebab>.sql`, stamp là thời điểm UTC thật và không trùng giữa các migration đang hoạt động; migration mới xếp sau chuỗi đang hoạt động đã commit trên HEAD. Archive ghi nhận migration đã nghỉ khỏi chuỗi, nên baseline thay thế có thể mang stamp trước archive. Migration đã lên base là bất biến (sửa hay xoá mà không archive đều là finding)."
   causes_vi:
-    - "Vi phạm luật L02: `supabase/migrations/<ts14>_<kebab>.sql`; stamp tăng nghiêm ngặt so với base; file đã lên base không được đổi."
+    - "Vi phạm luật L02: `supabase/migrations/<ts14>_<kebab>.sql`; stamp mới tăng nghiêm ngặt so với chuỗi đang hoạt động đã commit trên HEAD, không so với đồng hồ, thời gian commit hay stamp trên remote; file đã lên base không được đổi."
   nextStep_vi: "Tạo migration mới bằng the Supabase CLI new-migration command, không sửa/đổi tên/xoá migration đã lên base; nếu cần đổi nội dung, viết migration mới."
   owner: op-retry
   kind: check-finding
@@ -2055,6 +2055,17 @@ HFS_STACKS_SHAPE:
   owner: op-retry
   kind: check-finding
 
+HFS_STARCIWORK_LITE_FORBIDDEN:
+  title: "lite .starciwork holds only workspace.yaml and brand/"
+  title_vi: "Work của lite"
+  meaning_vi: "Trong ứng dụng edition lite, .starciwork chỉ được giữ workspace.yaml, .gitignore và brand/** (bản ghi bản vẽ, tham chiếu và tài sản thương hiệu). Cây này không bắt buộc khi ứng dụng chưa có bản ghi thương hiệu."
+  causes_vi:
+    - "Ứng dụng lite còn index.yaml, shell/, features/, _resources/, uat hoặc br trong .starciwork"
+    - "Có tệp khác nằm ngoài workspace.yaml, brand/ và .gitignore trong Work của lite"
+  nextStep_vi: "Giữ nguyên workspace.yaml, brand/** và .gitignore, chuyển nội dung khác ra khỏi .starciwork hoặc nâng ứng dụng lên edition full nếu cần các bản ghi đó, rồi chạy lại kiểm tra."
+  owner: op-retry
+  kind: check-finding
+
 HFS_TOOL_CONFIG_LOCAL:
   title: "Configs only call the factories; no local rules"
   title_vi: "Kho tự đặt luật cục bộ"

package/runtime/scripts/api/git/cat-file.mjs

@@ -0,0 +1,5 @@
+// cat-file.mjs — `git cat-file <args>`: the type, size or content of repository objects (-e, -p, --batch).
+import { runGit } from './lib.mjs';
+
+/** The spawn result {status, stdout, stderr, error} of `git cat-file ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
+export const catFile = (args = [], options = {}) => runGit(['cat-file', ...args], options);

package/runtime/scripts/api/sops/resolve-sops.mjs

@@ -0,0 +1,7 @@
+// resolve-sops.mjs — find the sops executable: PATH, and on Windows the WinGet links and packages.
+import { resolveSops as resolve } from './lib.mjs';
+
+/** The absolute sops path, or null. `options`: platform, pathext (PATHEXT names), wingetPackageTree (the full package tree), filesystem (a probe). */
+export function resolveSops(env = process.env, options = {}) {
+  return resolve(env, options);
+}

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

@@ -1,4 +1,4 @@
-// seal.mjs - one `sops encrypt` of a plaintext document held in memory: the canon command `starci app secret set` and `starci app secret gen`
+// seal.mjs - one `sops encrypt` of a plaintext document held in memory: `starci app secret set` (including --generate)
 // (scripts/hfs/secret.mjs). The plaintext travels on the child's stdin and never on its argument list, so it is not visible in a
 // process listing; the ciphertext comes back on stdout.
 import { spawnSync } from 'node:child_process';