@openlup/platform 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -8,6 +8,90 @@ SemVer promise.
 
 ## [Unreleased]
 
+## [0.17.0]
+
+- Publishable on the npm `latest` dist-tag as `0.17.0`, from tag
+  `openlup-platform-v0.17.0`.
+
+- Add experimental `./communications` and browser-safe
+  `./communications/contracts`, plus generic capped raw-body, hex-HMAC and
+  constant-time comparison helpers in the existing `./http` entry. Compose neutral
+  transport/results/capture, rendering/content, independent Auth verification,
+  receipt/observation, polling/reconciliation, consent and membership sync engines.
+  Provider clients, protocol/key mapping, copy and activation remain host-owned.
+- Require explicit egress admission for supported injected network senders.
+  Guarded transports validate fresh host decisions, redirect sink sends and
+  suppress drops before network entry; provider names grant no admission.
+  Capture remains local acceptance. Preserve the maintained reference transport
+  through its trusted composition bridge and keep Auth/provider verification separate.
+- Add Polish/English invoice, role, opt-out and inquiry default-content factories
+  with whole-copy injection. Preserve implicit Polish invoice and existing role
+  expectations; EN invoice is construction-time opt-in. Reference opt-out page
+  copy, EN legacy/error text, document language and escaping change deliberately.
+  Pure inquiry rendering activates no sender. See the
+  [B1/B2 expectation inventory](../../docs/platform/plans/oss-m04-communications-triggers.md#b1-egress-boundary).
+- Add an opt-in immutable composition-time purpose registry with mandatory
+  classification and finite legacy defaults. Registration grants no consent,
+  provider activation or managed schema permission; custom-purpose persistence
+  stays with the host. Add neutral newsletter processing and marketing ports
+  without a runner or a new public purpose.
+- Add four bounded native store groups: delivery observation/readback, existing-rail
+  membership sync, operator notification recipients and durable consent decisions.
+  Append CREATE-only direct catalogue position 70,
+  `20261019200000_communications_native_operations.sql`, and its exact sparse
+  projection. Standard factory lanes refuse unsafe effective privileges.
+  Sync uses `public.outbox_events`; the sidecar is not another executor.
+- Compose selected native readback and atomic signed-token preferences with Core
+  readiness, explicit provider/binding identities and host-supplied clocks and
+  schedules. Add distinct opt-in operator evidence and installed substitute-provider
+  proof. Captured, network-accepted and membership-synced are not delivered.
+  Native consent excludes managed 16-hour / 2-day / 4-week caps and legacy
+  contact-touching, and is not a send-time fence. No default cadence, deployment
+  activation, full native general sender or UI package capability is added.
+  [T07 destinations](../../docs/platform/plans/oss-m04-communications-triggers.md#t07-destination-matrix)
+  remain explicitly open with their owning modules.
+- @openlup/platform size growth: added the reviewed neutral communications runtime and browser content contracts, bounded native stores and SQL projection, and their API/adoption documentation.
+
+Migration: `0.16.0` did not export communications. Upgrade the complete package
+set to `0.17.0` for the exact core peers, then explicitly select and bind the new
+experimental capability. Existing non-communications entries retain their contracts.
+The host retains renderer/copy, environment, origin, egress, provider protocol,
+credentials and schedule ownership. The generic HTTP helpers do not replace the
+independent Auth Standard Webhooks or provider-specific verification protocols.
+
+Install the complete selected direct canonical catalogue through position 70
+before selecting native stores. `COMMUNICATIONS_MIGRATIONS` projects positions
+2, 9, 20 and 70; never reapply these sparse files over an existing canonical
+history or treat them as a standalone chain. Preserve managed/private lineage
+and custom-purpose persistence: registering a purpose does not expand managed
+CHECKs. Thread the same registered purpose union and registry through selected
+policy, token, newsletter and store bindings; omitted arguments retain finite
+legacy defaults and existing signing bytes.
+
+`registerNativeSyncWorkInTransaction` is a trusted host transaction seam. Its
+caller-owned executor must already hold the lane's safe effective privileges;
+this function does not check those privileges. The caller owns the transaction
+and must commit or roll back permission, sidecar and existing-rail effects
+atomically. Use a safely admitted lane; the helper grants no provider or claim
+authority. Standard native sync factory transactions check
+`public.communication_native_sync_state`, `public.outbox_events` and
+`public.communication_recipient_consents`.
+
+Custom native stores must provide binding-scoped `findByMessageId`, bounded
+`listEvidence` (1–100) and atomic `registerPreference` as declared by the new
+surface. Supply explicit provider/binding identities and full catalogue admission.
+Hosts preserving older opt-out page bytes retain their own presentation binding;
+token purposes, verification and existing HTTP status/header semantics remain.
+See the [package composition guidance](README.md#communications-import).
+
+Growth reading: +61.4% against the retained initial `0.16.0` baseline (256,973
+packed bytes), measured before S1 notes at 414,808 bytes; final S1 measurements
+are recorded in the programme evidence. No cap is changed. Baseline evidence
+(2026-10-20): the published `0.16.0` tarball is 257,434 packed bytes, SHA256
+`030756175d61279aab0ae7b26b27783e08467ec93673f5623d19d0b7fc436463`.
+S1 option B retains the initial release-gates baseline rather than replacing it
+with this observed registry identity.
+
 ## [0.16.0]
 
 - Publishable on the npm `latest` dist-tag as `0.16.0`, from tag

package/README.md

@@ -6,11 +6,11 @@ It holds the runnable server substrate an OpenLup application composes: the Node
 
 ## Package surface
 
-`release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its eleven experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
+`release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its thirteen experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
 
 | Export | Contents |
 | --- | --- |
-| `./http` | Node request adaptation, deadlines, security headers and static documents, and `createNodeHttpRuntime` with its fixed request order |
+| `./http` | Generic capped raw-body reader, hex HMAC and constant-time token comparison; Node request adaptation, deadlines, security headers and static documents, and `createNodeHttpRuntime` with its fixed request order |
 | `./bff` | `createBffDispatcher`, `lazyBffRoute`, the hosted router URL rewrite, the response envelope (`createBffResponder`), the observed request context and the health route |
 | `./scheduler` | Transport-neutral scheduled jobs (`ScheduledJob`, the job registry, the lease-aware runner and the authenticated HTTP cron entry), path-declared jobs from configuration, the node-cron scheduler with per-job advisory locks, hosted cron verification, the cron entrypoint guard (it compares the presented bearer token with `CRON_SECRET` in constant time) and direct job bindings |
 | `./blob` | Filesystem, S3-compatible, Supabase Storage and Vercel Blob adapters, and `bindBlobPort` |
@@ -21,6 +21,8 @@ It holds the runnable server substrate an OpenLup application composes: the Node
 | `./composition` | `createBundleComposer`, the Node HTTP binding helpers and `createNodeHost` |
 | `./identity` | Experimental capability: identity engine, authorization, profile readers, session adapters and BFF factories |
 | `./identity/contracts` | Experimental capability: browser-safe customer auth port, value types and provider parser |
+| `./communications` | Experimental existing public consent/status, newsletter sync, Auth email hook, transport contracts/capture, observation/polling orchestration, standard webhook verification and delivery receipts; host-selected rendering, egress, protocol mapping and control policy |
+| `./communications/contracts` | Pure renderer, block builders, copy-injected commerce/subscription factories and email/newsletter/Auth/intake/receipt types; no Zod, Node or provider runtime imports |
 
 ## Scheduled jobs
 
@@ -83,7 +85,7 @@ failed HEAD; use an upload or list operation to observe an S3 loading refusal.
 
 ## Verification
 
-This package's tests are part of the repository's required test selection; from this directory, `npm test` runs them alone. The tests rewrite the originating application's characterization with neutral names and synthetic data, and a boundary test refuses any environment read or provider import in the package source.
+This package's tests are part of the repository's required test selection; from this directory, `npm test` runs them alone. The tests rewrite the originating application's characterization with neutral names and synthetic data, and a boundary test refuses environment reads and provider imports outside its explicit `pg` adapter and `@aws-sdk/client-s3` blob-client allowlist. Follow [repository testing](../../CONTRIBUTING.md#test-scope-and-diagnostics) for placement, setup and speed rules.
 
 The module-boundary proof permits one optional `./<module>/contracts` export
 only when that module declares `contracts: true` in `PLATFORM_MODULE_GRAPH` in
@@ -110,7 +112,7 @@ The job-run ledger SQL asset test verifies a readable, nonempty file within the
 package SQL directory. Its SQL parity tests bind the actual adapter calls to the
 shipped routine signatures; the asset's explanatory header may be edited freely.
 
-`npm run api:check` compares each of the eleven declaration entry graphs with the
+`npm run api:check` compares every declared entry graph with the
 committed `api/*.api.md` reports. After building, deliberately regenerate them
 with `node --experimental-strip-types ./scripts/api-contract.ts --update` from
 this package, and review the declaration changes.
@@ -425,7 +427,8 @@ operator/customer batches. See [identity privacy](../../docs/platform/IDENTITY.m
 for refusals, token limits and retained obligations.
 
 The complete direct conformance is included in
-`ai-resource-gate run --wait openlup:coverage -- npx vitest run tests/postgres/operatorIdentityUpgrade.test.ts`.
+`npm test -- tests/postgres/operatorIdentityUpgrade.test.ts` from the repository
+root after normal setup. A maintainer host resource broker is optional.
 For managed conformance, supply the same three `OPENLUP_MANAGED_CONFORMANCE_*`
 local disposable-stack settings described for operator invitations, with
 `OPENLUP_MANAGED_CONFORMANCE_DATABASE_URL` set to the database owner
@@ -471,3 +474,280 @@ panel. Its explicit runtime must supply actual routes and readiness admission;
 the shell refuses a missing composition. See the
 [identity reference guide](../../docs/platform/IDENTITY.md#disposable-identity-reference)
 for both-bundle commands, the committed managed grants and installation limits.
+
+## Communications import
+
+For adoption from `0.16.0`, follow the [0.17.0 Migration guidance](CHANGELOG.md#0170)
+for the complete package set, canonical SQL installation and host-owned bindings.
+
+M04 P1 relocates the existing public implementation without changing its reference
+outputs. The reference shims bind the existing renderer, egress resolver, origin
+defaults, delivery-shaping policy and receipt transaction lane. The package does
+not select a deployment, mount a route or schedule another executor.
+`createCommunicationsContribution` requires the host's version and schema
+inventory; supplied handlers, schedules, routes and ports describe only that
+host's selection.
+
+`COMMUNICATIONS_MIGRATIONS` projects three existing canonical units byte for byte:
+comms outbox (position 2), transactional receipts (9) and communications control
+plane (20). This sparse list is not a standalone migration chain. Apply the full
+selected canonical prefix through its existing runner; importing the module does
+not apply SQL or advertise missing managed/direct capabilities.
+
+Browser previews retain their reference renderer, content defaults and template
+policy. The Auth hook receives that same renderer through its reference shim.
+The standard Auth webhook and the maintained HTTP mail provider verifiers keep their separate signature
+formats and clocks; the generic helper added to `./http` replaces neither.
+E2 is applied: the payment webhook module delegates these five generic helpers.
+`readRawBody` is the same package function object with its original declared
+`(req: VercelRequest) => Promise<string>` signature; the other four exports are
+plain re-exports. The payment provider verification and its replay tolerance stay local.
+The maintained mail transport, credentials, callback verification/mapping,
+poll read/mapping, timeline and send-ledger adapters remain in reference source.
+B1 changes only the four raw-injection guard sites in the reference delivery
+adapters and the approved invoice test fixture; the concrete client and all
+other vendor-directory files retain the comparison-base bytes. The package exposes
+transport/result contracts and capture without a concrete mail factory.
+The type-only `CommunicationProvider<Provider>` and `EmailMessageReadModel<Provider>`
+accept host vocabulary; reference types retain their original literal.
+
+`createGuardedEmailTransport({ providerKind, policy, send })` is the network
+adapter constructor. At each send it awaits a fresh host policy, validates the
+whole decision and enters the sender only for a coherent `production`,
+`sandbox_direct` or `sandbox_sink` decision. The sender receives the effective
+recipient and a frozen context with intended recipient, host-selected credential,
+mode, reason and environment tag. It must consume that context when selecting
+credentials and emitting provider metadata. The package reads no environment and
+contains no provider client. Missing/throwing policy, unknown modes, mismatched
+recipients/tags, blank credentials or unsupported fields fail with status zero,
+no identifier and bounded error codes. Reasons are lower-case token codes up to
+80 characters. One unadorned `local@domain.example` recipient mailbox is required;
+whitespace, lists, display names and local-only domains are refused on this new
+alternate-transport policy boundary.
+
+`blocked` returns failure; explicit `drop` returns terminal suppression with no
+send, no identifier and an ineligible sent timestamp. Arbitrary injected objects
+are refused by `guardEmailTransport`; a provider name or copied capture shape
+cannot establish admission. Package-created capture retains its ordered envelopes
+and synthetic identifiers with no network effect. Capture acceptance remains
+local acceptance, never evidence of external delivery.
+
+`admitPolicyEnforcedEmailTransport` is the trusted host bridge for a transport
+that already enforces egress internally, as the maintained reference client does.
+The package registry owns its identity; this bridge performs no second routing
+or credential decision. It is a composition trust boundary, not a sandbox for
+host code: callers must not admit an unguarded network sender. New adapters should
+use the validating constructor above. The reference default retains its original
+sink/drop policy, key selection, optional payload fields, headers, signal and
+result/error semantics. `createAuthEmailTransport` preserves the Auth envelope
+mapping and admission; raw Auth closures are refused before their send method.
+Admin/control and required-audit ordering stay at their existing callers.
+No egress result authorizes a subscription-state or delivery-cycle mutation.
+
+`processEmailObservation` accepts already authenticated, decoded and environment-admitted
+input. It looks up a local send, constructs evidence only when found, applies one
+observation and records best-effort telemetry. Lookup and apply failures propagate.
+`runDeliveryReconciliation` polls candidates sequentially, rotates every non-404
+read, and delegates consecutive failed-404 abandonment at threshold three to the
+store. Rotation failure is counted without dropping delivery truth; apply failure
+continues the batch. Candidate-query, read and not-found-store throws propagate.
+The host classifies protocol snapshots after rotation and passes recipient/evidence
+through unchanged. The existing reference domain entry points use both engines;
+routes and schedules remain the same.
+
+Neither engine writes suppression or subscription state. Both callback and poll
+composition retain `communication_update_email_delivery_from_provider` as the
+single durable convergence/suppression writer. These ports add no in-memory
+replay authority, database store or second executor. Legacy transport identifier
+fields remain compatibility residue; new ports use `messageId`.
+
+`createCommunicationPurposeRegistry` composes immutable exact identifiers with a
+mandatory `marketing` or `non-marketing` classification. Its built-ins cannot be
+redeclared. Existing policy, token and newsletter schema calls keep their finite
+defaults. Passing a registry to policy evaluation, token verification or
+`createNewsletterIntegrationSchemas` recognizes its identifiers without granting
+permission. Custom marketing purposes still require a grant and respect
+suppression; built-in tester pause and permission rules stay in force.
+
+`createRegisteredPublicPreferenceTokenPort` requires an explicit host persistence
+function and passes the exact purpose and frozen classification to it. It creates
+no sync event. Stock managed permission and newsletter-sync tables retain their
+finite CHECKs; registering a purpose does not expand those stores. Additional
+persistence and schema requirements belong to the adopter. No new purpose, table,
+migration, preference UI, URL or default fan-out is installed.
+
+`processNewsletterWebhookEvent` supplies the existing event → permission →
+settlement sequence behind neutral ports. Reference HTTP admission and signature
+mapping stay local. Explicit registered purposes survive permission writes;
+purpose-less feedback still targets exactly the two existing marketing purposes.
+Verified opt-in, suppression and replay rules are unchanged. Registered dispatch
+checks the batch's purposes before provider effects and retains claim tokens,
+echo and capability skips, retry behavior and counters. Sync-settled and accepted
+receipts are distinct from delivered evidence. Existing job admission, binding,
+leases, finish-run linkage and operator readback retain their host composition.
+No shared sender pipeline is added: required audit and best-effort send paths
+keep their distinct ordering and failure semantics.
+
+`MarketingAutomationProviderPort` and `MarketingAutomationStorePort` describe
+explicit scope, claim/generation fences, admission/deadlines, idempotency,
+observations/history and ambiguity/backoff. The synthetic substitute-provider
+conformance suite is an executable contract, not an installed worker or a remote
+provider certification. Evidence carries opaque references; remote feedback does
+not grant local consent. No trigger catalogue, schedule or provider activation
+is supplied.
+
+The required selection retains the moved-code witnesses and neutral package
+characterization tests. The package W1 hook reader witnesses the Auth composition;
+provider-specific reference test paths remain in the complete suite. The
+[M04 ledger](../../docs/platform/plans/oss-m04-communications-triggers.md#verification-ledger)
+records counted cases, separate boundary iterations and local timing provenance.
+The clean-commit artifact gate enforces all merged caps, including the owner-read, measured limit on the complete contracts entry. Artifact admission still needs a
+clean supervisor commit.
+See the [M04 plan](../../docs/platform/plans/oss-m04-communications-triggers.md)
+for scope, later waves and verification limits.
+
+## Package artifact limits
+
+The monorepo's package artifact checker enforces this package's
+`release-gates.json` caps and packed content allowlist. Only
+`--release-set <version>` checks compressed growth against the last released
+baseline, with explanations in the new set's changelog section and release body. Its browser-safe `./identity/contracts` export also has a minified+gzip cap. See the
+[package artifact policy](https://github.com/openlup/openlup/blob/main/.github/VERSIONING_AND_EOL.md#package-artifact-limits)
+for measured sizes, current caps, the S1 baseline refresh and refusal remedies.
+Artifact checks require a clean package directory; `--manifest-only` supplies no
+artifact evidence.
+
+### Pure email content and browser rendering
+
+`./communications/contracts` now exports `renderEmail`, the nine existing block
+constructors, `guideCardBlock` and per-template content factories.
+Each `create*ContentFactory` binds host-selected copy plus only the pure helpers
+it uses: order-reference formatting, payment-cause wording or marketing footer.
+Localized review routes remain in the reference helper.
+In P3 no copy pack, brand, locale choice, environment reader, provider client or
+sending policy moved into this entry. B2 adds the explicit neutral defaults below. The existing email DTOs remain its canonical types.
+Reference `petName` compatibility inputs are translated to neutral `contextName`
+by their existing facades. Complete subjects, preheaders, ordered blocks and
+HTML/text remain byte-identical, including omitted and explicit optional fields.
+
+Browser previews continue through those facades to contracts values only. Auth
+uses its existing server hook factory with the same host renderer injection;
+its inactive public content binding still refuses with 503. Standard Auth,
+mail callback, integration-event and generic HTTP verification remain separate
+policies with their existing raw-byte and replay behavior. No crypto refactor,
+new entry, dependency or graph edge is part of P3.
+
+The contracts conformance test compiles the complete entry with no Node types
+and checks its value inventory and import closure. The cold consumer repeats the
+exact inventory and renders with fetch forbidden and optional peers absent,
+retaining all other consumer checks. Browser size measures every runtime export
+of the built entry through `browserEntryBytes`; it never measures a tree-shaken
+consumer subset. See the M04 ledger for the measured size, owner-read cap and
+working-tree versus signed-candidate evidence limits.
+
+P3's complete built contracts entry measures **5,992 B minified+gzip**;
+the owner-read cap is **11,776 B**, rounded to the nearest 512 B at about
+twice that measurement. Only this browser limit changes. Existing pack classes,
+other browser limits and clean-candidate artifact checks remain binding.
+
+
+M04 B2 adds four default factories in this same pure contracts entry:
+`createInvoiceDocumentContentFactory`, `createRoleNotificationContentFactory`,
+`createInquiryContentFactory` and `createOptOutContentFactory`. Each accepts an
+optional complete bilingual copy replacement; each content call takes an explicit
+`pl`/`en` locale. Invoice takes resolved order/document references, kind and account
+URL; role takes role, operator URL and optional pending expiry. Inquiry builds
+receipt/notice blocks from caller details, signoff and URL without sending or
+promising a response time. Opt-out returns display strings for seven outcomes;
+it verifies no token and writes no consent. Hosts own brand, locale selection,
+URLs, policy and delivery.
+
+The reference invoice adapter defaults to its byte-identical Polish output; explicit
+construction locale EN maps to `/account?sekcja=orders`, while the production
+composition still omits locale. All existing role outputs remain identical.
+The reference opt-out page now selects Polish/EN throughout, escapes display values,
+and uses neutral selected-communications/service-message wording. Its methods,
+verification, purpose allowlist, durable RPC, headers and statuses are unchanged.
+Generic inquiry is only a pure binding; the existing private-label sender stays
+unchanged. Invoice/role gain Polish canon previews; no sender/registry activation.
+See the [complete B2 expectation ledger](../../docs/platform/plans/oss-m04-communications-triggers.md#b2-changed-expectations-and-preservation)
+and [default conformance tests](test/communications/contentDefaults.test.ts).
+The measured B2 contracts entry is 8,210 B minified+gzip under the unchanged
+11,776 B cap; this is a local built-entry measurement, not release admission.
+
+### Native communications operations (development preview)
+
+The server entry `@openlup/platform/communications` additionally exports
+`createPostgresDeliveryReconciliationPort`, `createPostgresCommunicationSyncStore`,
+`createPostgresNotificationRecipientsPort` and `createPostgresConsentEvaluator`.
+Install the complete canonical manifest through position 70 before selecting
+these factories. `COMMUNICATIONS_MIGRATIONS` now projects positions 2, 9, 20 and
+70; it remains a sparse inventory, not an installer. Missing schema/configuration
+is an error, never an empty queue or an allow decision.
+
+Each factory owns a capability-local, role-free transaction lane and lazy `pg`
+pool, with `close()` for host cleanup. Only a trusted host may hold these owner
+credentials. Effective PUBLIC/browser table, column and inherited privileges
+cause refusal; the CREATE-only forward intentionally changes no old ACL or role.
+Do not expose a factory or its database lane to browser callers. The directory
+requires a verified active human operator, live communications authorization and
+absence of machine authority in the same transaction as each operation.
+
+A host registers `evidence: "network_accepted"` only after actual network
+acceptance, with a unique source key and binding. Capture is never registered as
+a network target. Polls and admitted callbacks call the same `applyObservation`
+writer; observation-key replay must preserve the immutable fact. Readback keeps
+acceptance, observed state, attempt/404 counts and abandonment separate. Only
+three consecutive 404s abandon a candidate; abandonment is not failed/delivered.
+Bounce/complaint writes the authoritative fingerprint's suppression atomically.
+No subscription or renewal state is changed.
+
+For newsletter sync, inject `rail: db => createPostgresOutboxStore(db)` from
+`@openlup/outbox/postgres` in host composition. `db` is the current transaction,
+so claim commits before I/O and rail ack and sidecar settlement commit together.
+`registerWork` creates one existing-outbox identity for a source and target
+binding. Successive preferences for one contact/target share the rail aggregate,
+so newer work cannot overtake older unprocessed work. Configure a distinct
+binding per target/provider, and exclude
+`nativeSyncEventType(binding)` from generic dispatch registries. Invoke only
+`runCommunicationSyncDispatch` with an explicit neutral membership provider.
+The sidecar cannot claim work and has no lease or drainer. A membership settlement
+records sync progress, never email delivery; remote exactly-once effects are not
+promised across a process crash. There is no automatic backfill or activation.
+
+Native consent evaluates registered P4 policy against the authoritative native
+permission and persists the decision before returning its id. Admin notices need
+an active source-bound notification recipient. Optional `testerPaused` reads
+host-owned authoritative pause state inside that transaction; omitted means no
+pause policy. The capability explicitly declares `managedFrequencyCaps: false`,
+`legacyContactTouching: false`, `sendTimeFence: false`: managed 16-hour / 2-day /
+4-week caps and legacy contact-touching are excluded. Evaluation does not fence a
+later send against changed consent. Custom-purpose persistence remains host-owned.
+
+The [callable reference binding](../../server/runtime/communications/communicationsLifecycleBinding.ts)
+selects only `PLATFORM_BUNDLE=node-postgres` with `DATABASE_URL`; it closes pools
+on success/failure and supplies no network/provider default. Existing managed
+HTTP cron/UI routes retain their existing composition. See the
+[B3 expectation inventory](../../docs/platform/plans/oss-m04-communications-triggers.md#b3-native-stores)
+and [real-PG witnesses](../../tests/postgres/communicationsNative.test.ts).
+
+C-compose extends the native delivery store with binding-scoped `findByMessageId`
+and bounded `listEvidence({limit})` (1–100). Existing observation/replay and polling
+methods retain their behavior. `registerPreference` on the native sync store
+commits an authoritative denied/suppressed permission and default-purpose sync
+work together; tester permission adds no marketing work. The trusted
+`registerNativeSyncWorkInTransaction` helper contains the same registration SQL
+used by `registerWork`; standalone input validation still precedes database entry.
+This helper is a trusted host transaction seam: its caller-owned executor must
+already hold the lane's safe effective privileges; the function does not check
+them. Standard native sync factory transactions check
+`public.communication_native_sync_state`, `public.outbox_events` and
+`public.communication_recipient_consents`. The caller owns the transaction and
+must commit or roll back permission, sidecar and existing-rail effects atomically.
+Use a safely admitted lane; the helper grants no claim token or provider authority.
+
+Reference composition remains outside the package: actual installed factories,
+Core readiness, explicit provider ports and host-supplied schedules. Native
+readback and signed-token bridges do not promise managed frequency caps, legacy
+tester-source parity, a send-time fence or a full native network sender. The
+opt-in browser profile adds no npm entry or UI package export.

package/dist/communications/accountingDocumentDelivery.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The sealed transport boundary for handing an accounting document to its recipient.
+ *
+ * The kernel exercises the whole capability up to this line: a document is owed, registered with
+ * whatever authority the market has, queued, claimed and settled against a receipt. What crosses
+ * the line is one opaque hand-off, and this adapter is the deliberately inert implementation of
+ * it -- deterministic, and leaving the installation by no route at all.
+ *
+ * It is FAIL CLOSED, and that is the whole design. An installation that has declared no delivery
+ * channel gets a refusal, never a silent success: a boundary whose default answer is "fine" is
+ * how a deployment discovers months later that nothing was ever handed to anyone.
+ */
+export type CapturedDocumentDeliveryCommand = {
+    readonly deliveryId: string;
+    readonly recipientReference: string;
+};
+export type CapturedDocumentDeliveryPort = {
+    deliver(command: CapturedDocumentDeliveryCommand): Promise<{
+        readonly receiptReference: string;
+    }>;
+};
+export type CapturedDocumentDeliveryResolution = {
+    readonly port: CapturedDocumentDeliveryPort;
+    readonly refused?: undefined;
+} | {
+    readonly port?: undefined;
+    readonly refused: string;
+};
+/** The one marker that opens the boundary. Anything else, including its absence, is a refusal. */
+export declare const CAPTURED_DOCUMENT_DELIVERY_CHANNEL = "captured";
+/**
+ * Resolve the boundary for one installation. The environment is the only input, and every path
+ * that is not an explicit declaration of the captured channel ends in a named refusal.
+ */
+export declare function resolveCapturedDocumentDelivery(env: Record<string, string | undefined>): CapturedDocumentDeliveryResolution;

package/dist/communications/accountingDocumentDelivery.js

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+/** The one marker that opens the boundary. Anything else, including its absence, is a refusal. */
+export const CAPTURED_DOCUMENT_DELIVERY_CHANNEL = "captured";
+const CHANNEL_KEY = "PLATFORM_DOCUMENT_DELIVERY_CHANNEL";
+const reference = (command) => `captured:${createHash("sha256")
+    .update(`${command.deliveryId}::${command.recipientReference}`)
+    .digest("hex")
+    .slice(0, 32)}`;
+/**
+ * Resolve the boundary for one installation. The environment is the only input, and every path
+ * that is not an explicit declaration of the captured channel ends in a named refusal.
+ */
+export function resolveCapturedDocumentDelivery(env) {
+    const declared = env[CHANNEL_KEY]?.trim().toLowerCase() ?? "";
+    if (declared === "")
+        return { refused: "document_delivery_channel_undeclared" };
+    if (declared !== CAPTURED_DOCUMENT_DELIVERY_CHANNEL) {
+        return { refused: "document_delivery_channel_unsupported" };
+    }
+    return {
+        port: {
+            async deliver(command) {
+                if (typeof command.deliveryId !== "string" || command.deliveryId.trim() === "") {
+                    throw new Error("document_delivery_command_invalid");
+                }
+                if (typeof command.recipientReference !== "string" || command.recipientReference.trim() === "") {
+                    throw new Error("document_delivery_recipient_missing");
+                }
+                return { receiptReference: reference(command) };
+            },
+        },
+    };
+}

package/dist/communications/authEmailError.d.ts

@@ -0,0 +1,5 @@
+/** Typed refusal used by public/default composition when product copy is absent. */
+export declare class AuthEmailContentUnavailableError extends Error {
+    readonly code = "auth_email_content_unavailable";
+    constructor();
+}

package/dist/communications/authEmailError.js

@@ -0,0 +1,8 @@
+/** Typed refusal used by public/default composition when product copy is absent. */
+export class AuthEmailContentUnavailableError extends Error {
+    code = "auth_email_content_unavailable";
+    constructor() {
+        super("Auth email content unavailable");
+        this.name = "AuthEmailContentUnavailableError";
+    }
+}

package/dist/communications/authEmailPorts.d.ts

@@ -0,0 +1,2 @@
+export type * from "./contracts/authEmail.js";
+export { AuthEmailContentUnavailableError } from "./authEmailError.js";

package/dist/communications/authEmailPorts.js

@@ -0,0 +1 @@
+export { AuthEmailContentUnavailableError } from "./authEmailError.js";

package/dist/communications/authSendEmailHook.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The Auth Send Email hook. Live, not a candidate.
+ *
+ * Supabase Auth targets `/api/auth-send-email` in staging and production - the
+ * hooks were repointed here on 2026-09-04 and the hosted Edge Functions were
+ * undeployed the same day, so this owns the raw-stream, signature, render/send
+ * and ledger contract for every magic link, recovery and confirmation the
+ * product sends. Rotating its signing secret is a human-only control-plane act.
+ */
+import type { HttpRequest as VercelRequest, HttpResponse as VercelResponse } from "../http/index.js";
+import type { EmailBrand, EmailRenderer } from "./contracts/email.js";
+import { type AuthEmailContentPort, type AuthEmailPersistencePort, type AuthEmailTransportPort } from "./authEmailPorts.js";
+export interface AuthSendEmailHookDeps {
+    transport: AuthEmailTransportPort;
+    persistence: AuthEmailPersistencePort;
+    content: AuthEmailContentPort;
+    fromEmail: string;
+    hookSecret: string;
+    authServiceUrl: string;
+    /** App-layer defaults injected at composition; no brand/env ownership lives here. */
+    defaultOrigin: string;
+    productionEmailHosts: string[];
+    legacyBaseUrl?: string | null;
+    emailBrandForOrigin: (origin: string) => EmailBrand;
+    defaultSandboxRecipient: string;
+    defaultRedirectTo?: string;
+    env: Record<string, string | undefined>;
+    now?: () => number;
+}
+export interface AuthEmailHookHost {
+    renderEmail: EmailRenderer;
+    readObservedEnvironment: (env: Record<string, string | undefined>) => string;
+    readHiddenPreviewEnabled: (env: Record<string, string | undefined>) => boolean;
+}
+export declare function createAuthSendEmailHookCandidate(deps: AuthSendEmailHookDeps, host: AuthEmailHookHost): (req: VercelRequest, res: VercelResponse) => Promise<void>;