# Beto boundaries

Start with the [Project directory](../contexts/project/README.md) for its query,
read model and provider limitations. Shared adaptors contain technical mechanisms.

| Folder | Responsibility |
| --- | --- |
| `command/` | Plain handler execution with a per-invocation write repository, immutable prepared projections and explicit realtime intent. |
| `persistence/postgres/` | Database ownership, atomic state/receipt/outbox writes, projection bytes and fenced dispatch leases. |
| `messaging/amqp/` | RabbitMQ connections, confirmed publication, acknowledgements and topology declaration. |
| `messaging/requests/` | Typed request envelopes, complete command/query registration and reconnecting request workers. |
| `messaging/workers/` | Event consumption, durable private commands, committed replies and fenced outbox delivery. |
| `realtime/` | Delivery of saved projection bytes to the restricted realtime gateway. |
| `http/operational/` | Health/diagnostic responses and authentication. |

Context adaptors own wire-to-application mapping and read repositories. Project's
static repository lives under `contexts/project/adaptors/persistence/mock`.
Foundation packages retain domain/application primitives, configuration,
diagnostics and cancellation timing. Fx registrations stay in `services/beto/di`.

Project has no write commands or events. Its named query handler is registered
in the composition root through a generated response-bound registration. Its schema
owns plain input/response models, query/reply identifiers and mechanical wire mappings.
The shared registry routes plain application values through `QueryBusPort`.
Registration covers every declared request before workers start. Commands use
`services/commandregistration` to bind a plain `FeatureHandler` factory to one
`AggregateTransaction`. Handlers receive `CommandContext`, generated input and an
owner `WriteRepository.Get/Save` capability. The transaction owns locking, version
checks, durable receipts, outcomes and outgoing intent. Repository and realtime
bus capabilities expire when the invocation ends. `CommandStore`, `CommandPort`,
`Fact` and the old HTTP command/query helpers have been removed.

Saving stages private domain facts through the owner's mapper. An integration
publication subscriber commits its own receipt and encoded event, preserving the
source aggregate revision and occurrence time. A command reaction commits exact
private command bytes before a paired consumer executes them. Public commands
commit their exact reply bytes alongside their outcome; the reply relay confirms
delivery independently. Query replies retain confirmed publication before ACK.
Each owner's query queue has four consumers, each with one outstanding request
and its own reply publisher. Independent reads can progress while another waits
on a provider. Cancellation drains all consumers and leaves unfinished reads
available for redelivery. Command queues retain one consumer.

Realtime publication is explicit. Each message selects a canonical Project or
Party audience, or a principal subject for a private outcome. Command snapshots
must match committed state; rejection messages must match the recorded outcome and
use a principal target. The gateway derives channels from the target. Subscribers
have a separate receipt/outbox boundary. Saving a root alone creates no browser
publication.

## Development checks

- `pnpm check:beto`: formatting, architecture, generated drift, historical compatibility, Go vet, pinned
  Staticcheck and errcheck. This is also part of `pnpm verify`.
- `pnpm generate:beto`: regenerate Beto's contracts, copied migration baselines
  and broker catalogue. `--category requests` selects one output family.
- `python3 scripts/beto_native_integration.py`: isolated native PostgreSQL with
  restricted runtime credentials, race detection and transaction/recovery fixtures.
- `pnpm check:contracts:beto`: compare generated files in a temporary directory,
  including missing and obsolete outputs, without changing the checkout.

Generated files live under `generated/` or use `.generated.json`. Beto contains
its technical envelopes and Project query bindings; Execution Core projection
bindings belong to Metallo. Shared migration copies retain their exact SQL bytes.

The foundation follows the Storefront Go service at reference commit `a9d7bf6`
in `ddd-hexagonal-cqrs-es-eda-microservices-multilingual`. Pharos retains its UUID
salt, wire identities, broker routes and current-state storage. Frozen platform
SQL baselines remain byte-identical; Beto's checksummed `0003_delivery.sql` adds
command/reply outboxes and explicit realtime support to its persisted contexts.
Project remains storage-free, with no commands, event subscriptions or browser
publication authority. Project-specific source selection and provisioning remain
intentional.

Request annotations generate public/private inputs, required presence rules,
responses, shared `PageRequest`/`Outcome`/`Rejection` values and direct handler
registrations. Event declarations generate plain values, codecs and catalogues;
`contracts/subscriptions.json` generates the complete graph, paired command queues
and replay membership. These registries are empty for Project. Application code
imports only its owner's plain contracts and shared value types. Typed Go AST
checks reject transaction callbacks in application code, chained handlers and
mutation outside command handlers.

`check:beto` compares published Project schemas against commit `adb80196ea1c`,
independently of generated-file drift. Existing request/reply byte fixtures cover
queued bytes. API's `mappings/project.json` supplies its explicit HTTP translation;
the JSON model and mechanical Protobuf mapping are generated from that mapping
and the HTTP/Protobuf contracts.