@sincpro/client-framework 1.1.0 → 1.2.0

package/AGENTS.md

@@ -33,7 +33,7 @@ module has only the layers it needs, and says what it offers in its own `index.t
 | `src/client/`        | `Transport`, `entity()`, the contract (domain); REST, memory, Parquet; discovery, propagation   |
 | `src/model/`         | Model definitions: `defineMeta`, from a JSON Schema, the store of known ones                    |
 | `src/core/`          | DTOs and events, bus, services, handlers, extension points; pipeline; `BoundedContext`; process |
-| `src/event_driven/`  | `Envelope`, `EventQueue`/`Subscribes` ports; `syncQueue`; `Publisher`, `Subscriber`             |
+| `src/event_driven/`  | `Envelope`, `EventQueue`/`Subscribes` ports; queues; `Publisher`, `Subscriber`, `Subscriptions` |
 | `src/codegen/`       | The generator and its CLI (`sincpro-client generate`) — the only place Node is allowed          |
 | `src/testing/`       | The public entry of the in-memory observability adapters                                        |
 | `tests/`             | vitest in Node, one folder per module; `tests/support/` holds fakes and forge's contracts       |
@@ -78,18 +78,35 @@ module has only the layers it needs, and says what it offers in its own `index.t
   unless `Service` is registered now for `dto`; its spans carry `sincpro.replaces`. A service
   meant to be subclassed declares `static readonly serviceName: string = "…"`, or the literal
   type stops a subclass from renaming itself.
-- **How events are carried is here; where they are kept is the platform's.** One subscriber
-  per bounded context; a `Subscriber` executes an event in each. `storedQueue` holds the rules —
-  store first, deliver in order, retry what may succeed, set aside what never will, never run a
-  context twice — over an `EventStore` the platform plugs (SQLite, IndexedDB, memory). A store
-  only keeps records; it never decides.
+- **How events are carried is here; where they are kept is the platform's.** One use case of an
+  event per bounded context, one `EventSubscriber` per event per `Subscriptions`; a `Subscriber`
+  executes an event in each. `storedQueue` holds the rules — store first, deliver in order,
+  retry what may succeed, set aside what never will, never run one who heard it twice — over an
+  `EventStore` the platform plugs (SQLite, IndexedDB, memory). A store only keeps records; it
+  never decides.
+- **A subscriber is an entrypoint, not a use case.** An `EventSubscriber` reads the event and
+  executes Commands on a bounded context it was given, as a cron does on a tick; what to decide,
+  and a workflow of several use cases, is a Feature or an ApplicationService it executes. Its run
+  is layer `entrypoint`: no interceptor wraps it, no listener hears it, no error handler answers
+  it. An event may instead be the input of a use case (`feature(Event)(Service)`) when the use
+  case exists because of it. A `Subscriptions` is named apart from every bounded context: the
+  queue keeps who heard an event by name, and `Subscriber` refuses two of one name.
+- **A bounded context injected into a run is bound to it** (`BIND`): what it executes is a child
+  of the caller — span, flow, cause, signal, one report — with its own dependencies, context and
+  handlers. A failure keeps the outcome where it first failed, so a caller does not report what
+  the callee expected.
+- **A bounded context is named for what it is.** `salesBoundedContext`, never `sales` (an
+  entity?) and never `ctx` or `bc`: `context` is already the run's. The scaffold writes it so.
 - **A circuit belongs where the dependency is.** `CircuitBreaker` (in the process's memory, the
   backend's semantics: `COUNTED_KINDS`, half-open with one probe) guards a transport
   (`guardedTransport`) or an adapter; its `CircuitOpen` declares `unavailable` and a wait, so
   nothing else needs to know a circuit exists.
-- **Delivery is at least once.** A stored event may run twice in a context after a crash; a
-  subscriber keys its effect by `this.execution.causationId` (the envelope's id). `maxAttempts`
-  sets aside what keeps failing. One process drains a store. `execution` is reserved.
+- **Delivery is at least once.** A stored event may run twice after a crash. A use case of the
+  event keys its effect by `this.execution.causationId` (the envelope's id); an `EventSubscriber`
+  finds the same id in its own run and hands it in the Command it executes — the use case's
+  `causationId` is the subscriber's run —, or the effect is keyed by the entity the event names.
+  `maxAttempts` sets aside what keeps failing. One process drains a store. `execution` is
+  reserved.
 - **A failure says its kind, whatever the wire.** `failureOf` reads a declared `failureKind`, the
   `Problem` (the same over REST, JSON-RPC and gRPC), then a REST status. A transport of another
   wire, or another backend's adapter, declares the kind with `kindOfGrpcCode` /
@@ -153,7 +170,7 @@ options)`: no route, no verb, no RPC method. The contract's bindings (`rest`, `r
 - **An error handler answers; it does not observe.** The failure is recorded where it happened —
   span, log line, report — before the layer's handlers run, as in sincpro_framework. A handler
   returns the answer or throws to the next; the global chain wraps only `execute` and `scoped`.
-- **The application layer imports no logger.** A bounded context has `project.logger`; a run
+- **The application layer imports no logger.** A bounded context has `projectBoundedContext.logger`; a run
   hands `this.logger`, bound to its execution. Only `logger` (infrastructure, the global one) and
   `loggerAdapter` are predefined; injected as a dependency they bind to the run (`BIND`), imported
   at module level they do not. No logger is predefined for an application layer. Console is the

package/MANIFESTO.md

@@ -48,7 +48,7 @@ server-side render, in a script and in a test, unchanged.**
    in a global stack: two calls at once never mix their parents.
 5. **Bounded contexts.** Set up like the backend's — its dependencies (`addDependency`), its
    Features and ApplicationServices, registered for class DTOs — and called as
-   `project.execute(new Command(...))`. The bounded context is the bus. An application is the set
+   `projectBoundedContext.execute(new Command(...))`. The bounded context is the bus. An application is the set
    of bounded contexts it loads; they never import each other's insides.
 6. **The client.** The `OperationTransport` port — an operation called by who it is, over any
    wire — with its REST and JSON-RPC adapters (a platform adds gRPC or its own); the `Transport`
@@ -67,16 +67,18 @@ server-side render, in a script and in a test, unchanged.**
 10. **The command core (`./core`).** The single model matching the backend's application
     abstractions: class DTOs and Responses, a bounded context that is a bus, Features and
     ApplicationServices registered for DTO classes, attribute-injected dependencies and a
-    feature bus for composition, domain events executed by their subscribers, replacements,
+    feature bus for composition, domain events as the input of a use case, replacements,
     and the backend's error handlers — global, feature and application service — with the
     errors a bounded context expects. The internal engine uses
     the injected process ports. Remote clients and mapping remain distinct.
 11. **Event-driven, as ports (`event_driven`).** How every platform publishes domain events and
     subscribes to them the same way: the envelope that travels beside an event (its flow and
-    its cause), the `EventQueue` and `Subscribes` ports, a `Publisher` a Feature holds, a
-    `Subscriber` over the bounded contexts that hear, the queue that delivers in the call, and
-    the stored queue's rules over an `EventStore` the platform plugs. The guidelines, the rules
-    and the contracts are here; where events are kept is the platform's.
+    its cause), the `EventQueue` and `Subscribes` ports, a `Publisher` a Feature holds, the
+    `EventSubscriber` — the entrypoint that hears an event and calls use cases, as a cron does on
+    a tick — and its `Subscriptions`, a `Subscriber` over everyone who hears, the queue that
+    delivers in the call, and the stored queue's rules over an `EventStore` the platform plugs.
+    The guidelines, the rules and the contracts are here; where events are kept is the
+    platform's.
 12. **Resilience.** What a failure is (`failureOf`, the backend's kinds on every wire) and the
     backend's circuit breaker, guarding any transport or adapter.
 

package/README.md

@@ -65,12 +65,12 @@ class Quote extends ApplicationService<CommandQuote, ResponseTotal> {
   }
 }
 
-const sales = new BoundedContext<{ unitPrice: number }>("sales");
-sales.addDependency("unitPrice", 10);
-sales.feature(CommandTotal)(Total);
-sales.appService(CommandQuote)(Quote);
+const salesBoundedContext = new BoundedContext<{ unitPrice: number }>("sales");
+salesBoundedContext.addDependency("unitPrice", 10);
+salesBoundedContext.feature(CommandTotal)(Total);
+salesBoundedContext.appService(CommandQuote)(Quote);
 
-const answer = await sales.execute(new CommandQuote(3)); // ResponseTotal — total 30
+const answer = await salesBoundedContext.execute(new CommandQuote(3)); // ResponseTotal — total 30
 ```
 
 A Command names, by its type, the Response it answers: `execute` infers it, with no second
@@ -96,12 +96,12 @@ only). A Response may be a class, a plain object, a page, a primitive or `void`.
 ### Decorators, when the project has them
 
 ```ts
-@sales.feature(CommandTotal)
+@salesBoundedContext.feature(CommandTotal)
 class Total extends Feature<CommandTotal, ResponseTotal> { … }
 ```
 
 The same functions work as standard decorators and as legacy ones (`experimentalDecorators`);
-without a decorator transform, call them: `sales.feature(CommandTotal)(Total)`. No DI library
+without a decorator transform, call them: `salesBoundedContext.feature(CommandTotal)(Total)`. No DI library
 and no `reflect-metadata`. The tests compile both decorator forms with TypeScript; a bundler's
 transform (Vite, Metro/Babel) is each application's to configure and test.
 
@@ -114,8 +114,8 @@ class PrintOnBixolon extends Print {
   static override readonly serviceName = "PrintOnBixolon";
   override execute(command: CommandPrint) { … }
 }
-printing.feature(CommandPrint, { replaces: Print })(PrintOnBixolon);
-printing.handlerOf(CommandPrint); // PrintOnBixolon
+printingBoundedContext.feature(CommandPrint, { replaces: Print })(PrintOnBixolon);
+printingBoundedContext.handlerOf(CommandPrint); // PrintOnBixolon
 ```
 
 `replaces` names the service registered now for that class, or the registration is refused. The
@@ -126,9 +126,22 @@ dependency is replaced the same way: `addDependency(name, next, { replaces: prev
 
 ## Domain events
 
-A fact that already happened — `OrderPaid` — is executed as a Command is: by the Feature or
-ApplicationService registered for its class, its subscriber in this bounded context, through
-the same pipeline (span, log lines, error handlers, report):
+A fact that already happened — `OrderPaid` — is heard in one of two ways:
+
+| What hears it                                                                                 | When                                                                                       |
+| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **A use case of the event**: a Feature or ApplicationService whose input _is_ the event       | the use case exists because of the event, and nothing else calls it                        |
+| **An `EventSubscriber`**: an entrypoint that reads the event and executes Commands on the bus | the event starts use cases that have their own Command — a screen or a cron calls them too |
+
+A subscriber is not a use case — it is a door, as a cron or a screen is: it decides nothing. Work
+of several steps is an ApplicationService (the workflow) that the subscriber executes, never
+logic in the subscriber.
+
+### A use case of the event
+
+The event is executed as a Command is: by the Feature or ApplicationService registered for its
+class in this bounded context, through the same pipeline (span, log lines, error handlers,
+report):
 
 ```ts
 class OrderPaid extends DomainEvent {
@@ -143,25 +156,67 @@ class ThankCustomer extends Feature<OrderPaid, void> {
   async execute(event: OrderPaid) { … }
 }
 
-shop.feature(OrderPaid)(ThankCustomer);
-await shop.execute(new OrderPaid("o-1")); // span shop/ThankCustomer, sincpro.event = its name
+shopBoundedContext.feature(OrderPaid)(ThankCustomer);
+await shopBoundedContext.execute(new OrderPaid("o-1")); // span shop/ThankCustomer, sincpro.event = its name
 ```
 
 - **`eventName` is declared**, as `serviceName` is: a minifier renames classes. `event.name`
   reads it; `name` is reserved, and a subclass cannot make it a field.
-- **One subscriber per bounded context.** Another context that hears the event registers its
-  own; a `Subscriber` executes it in each.
-- An ApplicationService can subscribe too, and compose Features — of Commands or of events —
-  through `featureBus`. `execute(event)` answers whatever the subscriber returns (`unknown`).
+- **One use case per event in a bounded context.** Another context that hears the event
+  registers its own; the queue's `Subscriber` executes it in each.
+- An ApplicationService can take the event too, and compose Features — of Commands or of events
+  — through `featureBus`. `execute(event)` answers whatever its use case returns (`unknown`).
+
+### An `EventSubscriber`: the entrypoint that hears an event
+
+```ts
+// entrypoints/queue/logged-successfully.subscriber.ts — reads the event, executes the Command
+export class LoggedSuccessfully extends EventSubscriber<OdooLoggedIn> {
+  static readonly subscriberName = "LoggedSuccessfully";
+  declare readonly ticketsBoundedContext: BoundedContext<TicketsDependencies>;
+
+  async handle(event: OdooLoggedIn) {
+    await this.ticketsBoundedContext.execute(new CommandStartDay(event.uid)); // an ApplicationService
+  }
+}
+
+// entrypoints/queue/index.ts — who hears what, and what they call
+export const ticketsSubscriptions = new Subscriptions<TicketsEntrypoints>(
+  "tickets-subscriptions",
+);
+ticketsSubscriptions.addDependency("ticketsBoundedContext", ticketsBoundedContext);
+ticketsSubscriptions.subscribe(OdooLoggedIn)(LoggedSuccessfully);
+```
+
+- **Each delivery is a run of its own**, `tickets-subscriptions/LoggedSuccessfully` in the layer
+  `entrypoint`: its span, its log lines, `this.logger`, `this.execution`. It continues the
+  envelope's flow, and the use cases it executes are its children.
+- **A bounded context it was given is bound to it** (`BIND`), as a transport is: what it executes
+  runs under the subscriber's span, in the same flow, caused by it, cancelled with it — and still
+  with its own dependencies, context, interceptors and handlers. A Feature that calls another
+  bounded context injected into it gets the same.
+- **One subscriber per event in a `Subscriptions`**; a second is refused, a replacement names the
+  one it replaces (`subscribe(Event, { replaces: Old })`). Several reactions to one event are one
+  ApplicationService, or subscribers of different registries.
+- **It is not a use case**: interceptors and listeners see the use cases it calls, not it. A
+  failure is reported once along the flow, where it happened, with the outcome its bounded
+  context gave it (`expectErrors` holds).
+- **Its name is its identity** in spans, logs and the stored queue's record of who already
+  heard an event, so it differs from every bounded context's (`<context>-subscriptions`).
 
 ### Publishing and subscribing
 
 ```ts
 import { Publisher, Subscriber, syncQueue } from "@sincpro/client-framework";
 
-const subscriber = new Subscriber(mail, stock); // every bounded context that hears
+// the queue's door: every bounded context with a use case of the event, every Subscriptions
+const subscriber = new Subscriber(
+  mailBoundedContext,
+  stockBoundedContext,
+  ticketsSubscriptions,
+);
 const queue = syncQueue(subscriber); // in the call, in memory — or a platform's
-shop.addDependency("publisher", new Publisher(queue));
+shopBoundedContext.addDependency("publisher", new Publisher(queue));
 
 class Pay extends Feature<CommandPay, string> {
   declare readonly publisher: Publisher;
@@ -174,37 +229,43 @@ class Pay extends Feature<CommandPay, string> {
 
 The `Publisher` is bound to the run that holds it, so the event joins that run's flow: its
 envelope carries the run's `correlationId` and names the run as its cause. The `Subscriber`
-executes it in `mail` and in `stock` — `context.execute(event, envelope)` —, so their runs
-continue the same flow; one that fails does not stop the others.
+executes it in `mail`, in `stock` and in `tickets-subscriptions` — `execute(event, envelope)`
+—, so their runs continue the same flow; one that fails does not stop the others. Two of them
+never share a name.
 
 What is defined here, and what each platform plugs behind the ports:
 
-| Piece                     | Here                                                           | The platform's                         |
-| ------------------------- | -------------------------------------------------------------- | -------------------------------------- |
-| `DomainEvent`, subscriber | the class, its `eventName`, its execution                      | —                                      |
-| `Envelope`                | `name`, `id`, `correlationId`, `causationId`, `publishedAt`    | storing it beside the event            |
-| `EventQueue` port         | `syncQueue` (in the call); `storedQueue` (store, then deliver) | a broker's queue, `BroadcastChannel`   |
-| `EventStore` port         | `memoryEventStore()`                                           | mobile: a SQLite table; web: IndexedDB |
-| `Subscribes` port         | `Subscriber(...contexts)`, `eventTypeOf(name)`                 | —                                      |
+| Piece             | Here                                                           | The platform's                         |
+| ----------------- | -------------------------------------------------------------- | -------------------------------------- |
+| `DomainEvent`     | the class, its `eventName`, its execution                      | —                                      |
+| `EventSubscriber` | the entrypoint, its run, `Subscriptions`                       | —                                      |
+| `Envelope`        | `name`, `id`, `correlationId`, `causationId`, `publishedAt`    | storing it beside the event            |
+| `EventQueue` port | `syncQueue` (in the call); `storedQueue` (store, then deliver) | a broker's queue, `BroadcastChannel`   |
+| `EventStore` port | `memoryEventStore()`                                           | mobile: a SQLite table; web: IndexedDB |
+| `Subscribes` port | `Subscriber(...hearing)`, `eventTypeOf(name)`                  | —                                      |
 
 ### Stored events: one way to carry them, any store
 
 ```ts
 const queue = storedQueue({
   store: sqliteEventStore(db), // the platform's EventStore; memoryEventStore() in a tab or a test
-  subscriber: new Subscriber(sales, stock, printing),
+  subscriber: new Subscriber(
+    salesBoundedContext,
+    stockBoundedContext,
+    printingBoundedContext,
+  ),
   ready: (stored) => connectivity.online || !needsNetwork(stored.envelope.name),
   onSettled: (stored) => activity.show(stored.envelope.name, stored.state),
 });
-shop.addDependency("publisher", new Publisher(queue));
+shopBoundedContext.addDependency("publisher", new Publisher(queue));
 connectivity.onBack(() => queue.drain()); // and on coming back to the foreground
 ```
 
 `publish` returns once the event is stored. Then the queue delivers what waits, one at a time,
 in the order stored — the backend's store-and-forward, over whatever store the platform plugs:
 
-- It is rebuilt as its class — `static fromJSON` when it has one — and executed in every
-  bounded context that hears it and does not have it yet: a retry never runs one twice.
+- It is rebuilt as its class — `static fromJSON` when it has one — and executed by everyone who
+  hears it and does not have it yet: a retry never runs one twice.
 - A failure a retry may fix (`failureOf`: unavailable, no answer, a conflict…) is tried again
   after the backoff or the wait it asks for, and what follows waits, so the order holds.
 - A failure every attempt would repeat (`PERMANENT_KINDS`: a refusal, invalid, not found) sets
@@ -219,8 +280,9 @@ memory carry events the same way, with the same rules.
 Three things a platform keeps in mind:
 
 - **At least once.** A process that stops after a context executed an event and before the store
-  saved it runs it there again. A subscriber that must not act twice keys what it does by the
-  envelope's id, `this.execution.causationId` in its run.
+  saved it runs it there again. What must not act twice keys what it does by the envelope's id —
+  `this.execution.causationId` in a use case of the event, or in an `EventSubscriber`, which hands
+  it to the Command it executes — or by what the event names (the entity's own id).
 - **One drainer per store.** Two tabs over one IndexedDB claim it first (the Web Locks API).
 - **Values come back as JSON.** An event that carries a `Money`, a `Decimal` or a date declares
   `static fromJSON` to read them back as such.
@@ -236,19 +298,24 @@ and an application changes or hears it from outside, as the backend's `bus_pipel
 
 ```ts
 // control: around the service — look, veto (throw), adjust (same class), or answer
-shop.interceptor(CommandPay)(async (command, next, run) => {
+shopBoundedContext.interceptor(CommandPay)(async (command, next, run) => {
   if (!credit.allows(command.customer_id)) throw new NoCredit();
   return next(command);
 });
-shop.interceptor()((executable, next, run) => next(executable)); // every class
+shopBoundedContext.interceptor()((executable, next, run) => next(executable)); // every class
 
 // observation: never changes the answer
-shop.onStart((started) => activity.running(started.execution.useCase));
-shop.onCompletion((done) => activity.succeeded(done.execution.useCase), CommandPay);
-shop.onFailure((failed) => activity.failed(failed.execution?.useCase, failed.outcome));
+shopBoundedContext.onStart((started) => activity.running(started.execution.useCase));
+shopBoundedContext.onCompletion(
+  (done) => activity.succeeded(done.execution.useCase),
+  CommandPay,
+);
+shopBoundedContext.onFailure((failed) =>
+  activity.failed(failed.execution?.useCase, failed.outcome),
+);
 
 // composition: a module or plugin wires its pieces in one place
-shop.extend(auditing);
+shopBoundedContext.extend(auditing);
 ```
 
 - **Interceptors** run inside the run, outermost first in the order registered: a veto is the
@@ -270,14 +337,14 @@ first-registered-first. A handler returns the answer, or throws to hand the erro
 one's throw reaches the caller:
 
 ```ts
-sales.addFeatureErrorHandler((error) => {
+salesBoundedContext.addFeatureErrorHandler((error) => {
   if (error instanceof PriceNotFound) return new ResponseTotal(0); // the answer
   throw error; // the next handler, or the caller
 });
-sales.addAppServiceErrorHandler(toBusinessError);
-sales.addGlobalErrorHandler(toProblem); // what reaches sales.execute or a scope
+salesBoundedContext.addAppServiceErrorHandler(toBusinessError);
+salesBoundedContext.addGlobalErrorHandler(toProblem); // what reaches salesBoundedContext.execute or a scope
 
-sales.expectErrors(QuoteExpired); // the business answering: `refused`, never reported
+salesBoundedContext.expectErrors(QuoteExpired); // the business answering: `refused`, never reported
 ```
 
 A failure is observed where it happened, before any handler runs: its span closes with its
@@ -338,7 +405,7 @@ reports what fails outside a use case — a view, a worker —, with the same ru
 
 ```ts
 const screen = new AbortController();
-const answer = sales.execute(new CommandQuote(3), { signal: screen.signal });
+const answer = salesBoundedContext.execute(new CommandQuote(3), { signal: screen.signal });
 screen.abort(); // the run ends `aborted` at once; nothing is reported
 ```
 
@@ -399,21 +466,21 @@ import { logger, loggerAdapter } from "@sincpro/client-framework";
 
 logger.info("Database opened"); // infrastructure — the global logger
 loggerAdapter.warn("Printer is slow", { ms: 900 }); // an adapter
-sales.logger.info("Catalog preloaded"); // a bounded context, outside a use case
+salesBoundedContext.logger.info("Catalog preloaded"); // a bounded context, outside a use case
 this.logger.info("Totalling"); // inside a Feature or ApplicationService
 ```
 
-| Logger                    | Layer                 | Each line carries                              |
-| ------------------------- | --------------------- | ---------------------------------------------- |
-| `logger`                  | `infrastructure`      | —                                              |
-| `loggerAdapter`           | `adapter`             | the run, when injected as a dependency         |
-| `sales.logger`            | `bounded_context`     | its bounded context                            |
-| `this.logger`, Feature    | `feature`             | bounded context, use case, execution and trace |
-| `this.logger`, AppService | `application_service` | the same                                       |
+| Logger                       | Layer                 | Each line carries                              |
+| ---------------------------- | --------------------- | ---------------------------------------------- |
+| `logger`                     | `infrastructure`      | —                                              |
+| `loggerAdapter`              | `adapter`             | the run, when injected as a dependency         |
+| `salesBoundedContext.logger` | `bounded_context`     | its bounded context                            |
+| `this.logger`, Feature       | `feature`             | bounded context, use case, execution and trace |
+| `this.logger`, AppService    | `application_service` | the same                                       |
 
 `this.logger` keeps its run across awaits and concurrent calls, without a global stack. An
 adapter that imports `loggerAdapter` at module level writes without the run; inject it
-(`sales.addDependency("log", loggerAdapter)`) or pass `this.logger` when a line must carry it.
+(`salesBoundedContext.addDependency("log", loggerAdapter)`) or pass `this.logger` when a line must carry it.
 
 One configuration, two doors — `configureProcess({ logger })` replaces every process port,
 `configureLogger(...)` only logging (an in-app debug switch):
@@ -441,8 +508,8 @@ snapshot, and what travels goes to the server in `sincpro-context`.
 
 ```ts
 processContext.set({ tenant_id: "acme" });
-sales.context.set({ warehouse_id: 4 });
-await sales.scoped({ company_id: 2 }).execute(new CommandQuote(1));
+salesBoundedContext.context.set({ warehouse_id: 4 });
+await salesBoundedContext.scoped({ company_id: 2 }).execute(new CommandQuote(1));
 ```
 
 Where the values live is a port (`ContextStore`): synchronous reads, a version per change and an
@@ -612,6 +679,44 @@ never a `Date`. `valuesOf`/`pack` write; `readValues` reads tagged values back;
 use a reader given explicitly. Cycles, functions and non-finite numbers are refused. How a value
 is shown, typed or stored is the platform's.
 
+## An application's layout
+
+An application is laid out as a sincpro_framework service is — the entrypoints call the bus, the
+bus runs the use cases, the use cases use the adapters:
+
+```text
+src/
+  entrypoints/main.ts(x)               configureProcess, the stored queue and its Subscriber
+  domains/
+    common/infrastructure/operations.ts  export const operations — the wire every client uses
+    <bounded context>/
+      generated/                       sincpro-client generate — never edited
+      domain/                          local Commands, Responses, DomainEvents, value rules
+      adapters/                        repositories, printers, other systems
+      services/                        the use cases, one folder per aggregate or entity
+        <aggregate>/                     sale_order/: its Features and ApplicationServices
+          confirm-quotation.feature.ts
+          <entity of the aggregate>/     payments/: a related entity with use cases of its own
+            register-payment.feature.ts
+            reconcile-payments.app-service.ts
+        index.ts                         registerServices: each Command with its service
+      infrastructure/                  dependencies.ts, bounded_context.ts (service bases)
+      entrypoints/                     the doors: they translate, they decide nothing
+        queue/                           EventSubscribers: event → Command → bus; index.ts: Subscriptions
+        cron/                            the platform's scheduler: tick → Command → bus
+      index.ts                         export const <context>BoundedContext — ready to execute
+```
+
+- **Services by aggregate.** A simple entity is one folder with its Features (a CRUD). When an
+  aggregate holds related entities with use cases of their own — the payments of a sale order —,
+  they get a folder inside it, and its Features and ApplicationServices live there, grouped by
+  what they are about.
+- **Entrypoints translate.** A subscriber, a cron and a screen build a Command and execute it;
+  a workflow of several use cases is an ApplicationService they execute. `sincpro-client check`
+  refuses a service that imports an entrypoint.
+- **A bounded context is named for what it is**: `salesBoundedContext`, never `sales` (an
+  entity?) or `ctx` — `context` is already the run's (`this.context`).
+
 ## Package layout
 
 Each module is laid out as sincpro_framework's are, and says what it offers in its `index.ts`:
@@ -646,7 +751,7 @@ src/
   event_driven/
     domain/          Envelope, the EventQueue, Subscribes and EventStore ports
     adapters/        syncQueue, storedQueue, memoryEventStore
-    entrypoint/      Publisher, Subscriber
+    entrypoint/      Publisher, Subscriber (the queue's door), Subscriptions, EventSubscriber
   codegen/         the generator and its CLI — the only place Node is allowed
   testing/         memoryTracer, memoryReporter, memoryLogger
 ```

package/dist/client/services/guarded.d.ts

@@ -6,7 +6,7 @@ import type { Transport } from "../domain/transport.js";
  * `Transport`:
  *
  *     const operations = guardedTransport(jsonRpcOperations({ endpoint }), new CircuitBreaker("forge"));
- *     project.addDependency("client", clientOf(operations));
+ *     projectBoundedContext.addDependency("client", clientOf(operations));
  *
  * Context: the circuit belongs where the dependency is — the transport —, not in each Feature. A
  * run binds it as it binds any transport, so the trace and the context still travel; an open

package/dist/codegen/services/scaffold.d.ts

@@ -8,7 +8,7 @@ import type { Metamodel } from "../domain/metamodel.js";
  *       infrastructure/dependencies.ts     what the services can count on: the generated client
  *       infrastructure/bounded_context.ts  its Feature and ApplicationService, and how it is made
  *       services/index.ts                  registers command classes and their services
- *       index.ts                           `export const project` — ready to use
+ *       index.ts                           `export const projectBoundedContext` — ready to use
  *
  * Context: the layout sincpro_framework gives a service (`dependencies.py`, `framework.py`,
  * `services/`, `__init__.py`), so a bounded context starts the way every other does and nobody

package/dist/codegen/services/scaffold.js

@@ -1,10 +1,4 @@
 import { aliasOf, FRAMEWORK } from "../domain/names.js";
-/** Names the skeleton's `index.ts` cannot give its constant. */
-const TAKEN = new Set([
-    "operations",
-    "registerServices",
-    ..."break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(" "),
-]);
 /** `sales-orders` → `SalesOrders`. */
 function pascalOf(alias) {
     const joined = alias
@@ -20,10 +14,9 @@ const HEADER = (what) => `// ${what} — written once by \`sincpro-client scaffo
 export function scaffoldFilesOf(metamodel, options = {}) {
     const alias = aliasOf(metamodel);
     const Name = pascalOf(alias);
-    const bare = `${Name.charAt(0).toLowerCase()}${Name.slice(1)}`;
-    // A word the language keeps (`import`, `default`) or a name `index.ts` already imports cannot
-    // be the constant's: it takes the bounded context's word instead.
-    const name = TAKEN.has(bare) ? `${bare}BoundedContext` : bare;
+    // Named for what it is — `projectBoundedContext`, never `project` (an entity?) or `ctx` —:
+    // nobody misreads it, and no word of the language or name `index.ts` imports can take it.
+    const name = `${Name.charAt(0).toLowerCase()}${Name.slice(1)}BoundedContext`;
     const Dependencies = `${Name}Dependencies`;
     const client = metamodel.bindings !== undefined;
     const operations = options.operations ?? at("..", "common", "infrastructure", "operations");
@@ -44,11 +37,11 @@ export function scaffoldFilesOf(metamodel, options = {}) {
         "}",
         "",
         "export function registerDependencies(",
-        `  bc: BoundedContext<${Dependencies}>,`,
+        `  boundedContext: BoundedContext<${Dependencies}>,`,
         `  ${client ? "operations" : "_operations"}: OperationTransport,`,
         ") {",
-        ...(client ? [`  bc.addDependency("client", clientOf(operations));`] : []),
-        "  return bc;",
+        ...(client ? [`  boundedContext.addDependency("client", clientOf(operations));`] : []),
+        "  return boundedContext;",
         "}",
         "",
     ].join("\n");
@@ -66,7 +59,7 @@ export function scaffoldFilesOf(metamodel, options = {}) {
         "",
         `import { type ${Dependencies}, registerDependencies } from "${at(".", "dependencies")}";`,
         "",
-        `/** A Feature of «${alias}» — of a Command, or a subscriber of an event: its dependencies typed on \`this\`, and \`this.context\`. */`,
+        `/** A Feature of «${alias}» — of a Command, or a use case of an event: its dependencies typed on \`this\`, and \`this.context\`. */`,
         "export abstract class Feature<C extends Command<R> | DomainEvent, R> extends BaseFeature<C, R> {",
         ...(client ? [`  declare readonly client: ${Dependencies}["client"];`] : []),
         "}",
@@ -91,10 +84,12 @@ export function scaffoldFilesOf(metamodel, options = {}) {
         " * Generated DTO types are remote contracts, not runtime command constructors: import",
         ` * them under their own name — \`import type * as remote from "${at("..", "generated", "domain")}"\` —`,
         " * and let a local Command implement one (`implements remote.CommandCancelIssue`).",
-        " * Register with context.feature(CommandClass)(FeatureClass) or",
-        " * context.appService(CommandClass)(ApplicationServiceClass).",
+        " * Register with boundedContext.feature(CommandClass)(FeatureClass) or",
+        " * boundedContext.appService(CommandClass)(ApplicationServiceClass); the services live in",
+        " * one folder per aggregate (`services/<aggregate>/`), and an entity of that aggregate with",
+        " * use cases of its own in a folder inside it (`services/<aggregate>/<entity>/`).",
         " */",
-        `export function registerServices(_context: BoundedContext<${Dependencies}>): void {}`,
+        `export function registerServices(_boundedContext: BoundedContext<${Dependencies}>): void {}`,
         "",
     ].join("\n");
     const index = [

package/dist/context/entrypoint/context.d.ts

@@ -1,18 +1,19 @@
 import type { ContextStore, ContextValues } from "../domain/store.js";
 /**
  * One level of the context: the process's (`processContext`) or a bounded context's
- * (`project.context`), read and written the same way on every platform.
+ * (`projectBoundedContext.context`), read and written the same way on every platform.
  *
  *     processContext.set({ tenant_id: "acme" });      the company changed — every screen hears it
  *     processContext.get("tenant_id")                  →  "acme"
- *     project.context.set({ warehouse_id: 4 });        only what `project` runs
+ *     projectBoundedContext.context.set({ warehouse_id: 4 });   only what it runs
  *     const stop = processContext.watch(() => redraw());
  *
  * Context: sincpro_framework reads its context from a tree — the process, the bounded context,
  * the scope, the execution — and the nearest wins. A client has the same levels: a use case runs
  * with the process's values, under them its bounded context's, under them a scope's
- * (`project.scoped({...})`), read once where the gesture starts and inherited by every Feature
- * it runs. That snapshot is `this.context` and what travels to the server in `sincpro-context`.
+ * (`projectBoundedContext.scoped({...})`), read once where the gesture starts and inherited by
+ * every Feature it runs. That snapshot is `this.context` and what travels to the server in
+ * `sincpro-context`.
  *
  * Where the values live is the platform's (`ContextStore`): this is only the door. `values` is
  * the same object until something changes it, so a screen can hand it straight to React's

package/dist/core/domain/dto.d.ts

@@ -5,7 +5,7 @@
  *     class CommandCancelIssue extends Command<ResponseCancelIssue> {
  *       constructor(readonly issue_id: string) { super(); }
  *     }
- *     const answer = await project.execute(new CommandCancelIssue("x"));   // ResponseCancelIssue
+ *     const answer = await projectBoundedContext.execute(new CommandCancelIssue("x"));   // ResponseCancelIssue
  *
  * Context: the backend asks `bus(dto, ResponseType)` for the type; here the Command carries it, so
  * `execute` infers it with no second argument. The association is type-only: absent from a
@@ -31,8 +31,8 @@ export declare abstract class Command<R> extends DataTransferObject {
  *       static readonly eventName = "shop.order.v1.paid";
  *       constructor(readonly order_id: string) { super(); }
  *     }
- *     project.feature(OrderPaid)(NotifyCustomer);
- *     await project.execute(new OrderPaid("o-1"));
+ *     projectBoundedContext.feature(OrderPaid)(NotifyCustomer);
+ *     await projectBoundedContext.execute(new OrderPaid("o-1"));
  *
  * Context: the backend names an event on the wire by `name`, `<context>.<aggregate>.vN.<fact>`,
  * and defaults it to the class's name; a client is minified, so the name is declared, as

package/dist/core/domain/dto.js

@@ -5,7 +5,7 @@
  *     class CommandCancelIssue extends Command<ResponseCancelIssue> {
  *       constructor(readonly issue_id: string) { super(); }
  *     }
- *     const answer = await project.execute(new CommandCancelIssue("x"));   // ResponseCancelIssue
+ *     const answer = await projectBoundedContext.execute(new CommandCancelIssue("x"));   // ResponseCancelIssue
  *
  * Context: the backend asks `bus(dto, ResponseType)` for the type; here the Command carries it, so
  * `execute` infers it with no second argument. The association is type-only: absent from a
@@ -27,8 +27,8 @@ export class Command extends DataTransferObject {
  *       static readonly eventName = "shop.order.v1.paid";
  *       constructor(readonly order_id: string) { super(); }
  *     }
- *     project.feature(OrderPaid)(NotifyCustomer);
- *     await project.execute(new OrderPaid("o-1"));
+ *     projectBoundedContext.feature(OrderPaid)(NotifyCustomer);
+ *     await projectBoundedContext.execute(new OrderPaid("o-1"));
  *
  * Context: the backend names an event on the wire by `name`, `<context>.<aggregate>.vN.<fact>`,
  * and defaults it to the class's name; a client is minified, so the name is declared, as