docs(gateway): separate shared edge transport from Orgmetra product composition

[seonghobae]

Scope

Advances #432 with a Proposed ADR before protected runtime adoption. Documentation-only: no gateway runtime, route configuration, identity adapter, owner API, database registry, activation/recovery, serving snapshot, request router, HTTP host, or Orgmetra release becomes production-authoritative from this PR.

Protected base remains develop@eb9757f8649aaad026a9865508d9aad50c1a7a4f. Current source head remains 6fc85e4d8bb273adb0d5866d87554067c749179d, open · Draft · mergeable=true, 51 commits / exactly three changed documentation files. ADR 0432 remains Proposed.

Live implementation authority

#434 exact 68bdf2d984ca7686219c335a85a6574195675cbe owns process-local owner-route-generation admission. #436 exact 30d89fa8f4ba95d7ddb84dde8e3b7e5faebf0343 owns durable normalized generation/configuration authority. #437 exact 8a67b5cef24332619b3a4466e3787a851c299215 owns durable activation/rollback/recovery through 0025, external evidence, checked-as-used capability integrity, recovery-bound snapshots and database-bound serving currentness. #438 exact d642eb71c05ae3990349a26facf30593a5703914 is ordinary-forward 7 ahead / 0 behind #437 with #437 exact as merge base and owns declared-request selection before durable currentness/availability; it adds no migration bytes.

Required routes require complete operation coverage; optional routes permit zero observations but require whole-route completeness once any operation is observed. Application and final PostgreSQL validators also agree that activation/recovery authority cannot remain valid longer than an owner-operation observation that makes the route serviceable.

Fresh #437 PostgreSQL RED 0e4d0b2e481db169108222fba374f89f74ba1ce4 demonstrates activation and recovery cases where a longer-lived bundle could previously be persisted over a shorter-lived required-route observation. Repair 2311c0deaf8688f26d55da12b03fe11d293ba015 requires evidence_valid_until_unix_ms <= observation.valid_until_unix_ms in both final 0025 validators and restores activation-side observed_at <= wall_clock parity. Source contract 127388c... pins those validators and 8a67b5c... preserves executable mode for the PostgreSQL root. Migration lineage remains 0018→0025.

#438 keeps configuration selection and availability separate. Concrete Path Item precedence is resolved over the complete declared generation before availability is checked, so an unavailable optional concrete route cannot disappear and widen a broader template's authority. Fresh RED ef991ff83a301aacf38a3157a1ad9bb995699ca8 additionally proves unknown declared paths and undeclared methods must be rejected before the PostgreSQL currentness boundary is crossed; repair d642eb71c05ae3990349a26facf30593a5703914 performs path/method preselection first, pins the selected route ID, then invokes #437's current activation/recovery check only for a routable request.

Architecture source status

ADR 0432, TRACEABILITY and doctoring at source head 6fc85e4... remain stale relative to current implementation. PR-body currentization is not source currentization. Before Accepted/Ready, all three architecture source files must ordinary-forward adopt final admissible heads and distinguish declared generation membership, canonical evidence-only projection, recovery-bound snapshot projection, detached/pinned structural and serving coordinates, database-owned recovery time, exact clock ordering, owner-observation lifetime dominance, latest-recovery supersession, durable-attestation/current-activation read linearization, selection-before-currentness/availability request routing, supported restore/failover provenance, and the still-missing deployable HTTP lifecycle/invalidation/performance evidence.

Migration-time owner equality still does not prove production runtime/migrator least privilege. Migration 0026 remains occupied by active Employment-absence work and must not be stolen.

Verification boundary

Exact #433 has its own historical hosted checks but still lacks independent architecture approval; those checks do not authorize stale architecture source. Current implementation RED→repair contracts are not canonical package/PostgreSQL GREEN.

Canonical package and PostgreSQL acceptance must use one unchanged exact #438 d642eb71... candidate. #260 handoff covers request-routing currentness, the new preselection-before-DB regressions, inherited #437 package tests and 100% owned statement/branch/docstring/edge coverage. #311 handoff covers complete 0018→0025 PostgreSQL inventory including the evidence-lifetime root, DB-owned recovery time, optional-route, hostile namespace, upgrade, recovery, serialization and provenance roots. Predecessor GREEN does not transfer.

#340 remains the inherited Foundation prerequisite. API-01 remains Planned under #100 because there is still no protected deployable buyer path; package routing is not an HTTP host and does not justify changing docs/product-technical-gap-baseline.md from this lane.

Remaining order: canonical exact-tree execution → architecture source currentization → fresh checks + independent architecture admission → Foundation/protected reconciliation → immutable external evidence → DB-role/security/fault/recovery acceptance → deployable HTTP host → full buyer-path k6/E2E p95≤20 ms → #51/#100 reconciliation → immutable release.

No force-push, destructive rebase, self-approval, gate weakening, mutable sibling source, cross-service SQL, synthetic status, blind/no-op rerun, routine administrator bypass, predecessor-GREEN transfer, migration-number theft, or premature Accepted/Ready/protected/release claim is authorized.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Executable-feedback currentization only; no architecture-source write. #434 is now exact be4895e9e86eae1e9f07cd80338e91a05fe148e9 (112 commits / 17 files). The two new commits are test-only stale-oracle repairs after the already-source-current route-construction snapshot strengthening: 73e5181b... fixes route-mutation and generation-retarget fixtures, and be4895e9... fixes live receipt source-revalidation expectation.

This does not change ADR 0432 topology, bounded-context ownership, OpenAPI/path authority, or the process-local-vs-durable provenance distinction. Keep #433 Proposed/Draft; do not create an ADR/TRACEABILITY churn commit merely to mirror a test-oracle repair. Normal architecture admission still requires unchanged-head terminal governance plus qualifying independent review.

[seonghobae]

Architecture handoff after fresh executable review: no topology/ADR decision change is required. #434 is now exact 68bdf2d984ca7686219c335a85a6574195675cbe; its newest delta only binds the already-existing canonical lexical HTTP-method representation in regression coverage, with no production admission change.

The previously documented process-local-versus-durable distinction now has an explicit implementation owner: #435, with Draft child #436 exact 80932c808ef873b268217ef1b79b0d14fd8884f7 stacked on #434. #436 only establishes a 3NF-ready reconstructable generation record contract; it does not yet persist to PostgreSQL or authorize activation. This is consistent with ADR 0432's existing decision that durable composition state is limited to immutable configuration/admission/activation/audit coordinates and that rollback revalidates durable generation/config/deployment authority rather than process-local receipts.

Keep ADR 0432 Proposed. Do not currentize canonical protected docs from #436 implementation churn; source change becomes warranted only if durable implementation evidence contradicts the selected architecture or normal architecture admission requires a substantive repair.

[seonghobae]

2026-09-22 architecture handoff currentization; no ADR source rewrite.

ADR 0432 already distinguishes process-local construction integrity from durable configuration/deployment authority, so the new executable delta does not change the selected topology. Dependent Draft #436 is now exact 04705a05f8e4fd58a39527f56dcb993fd4bb40cb and has advanced beyond the earlier persistence-neutral record projection to Draft-source PostgreSQL durable configuration authority: normalized append-only records, exact-material-only idempotent registration, restart reconstruction, and canonical digest recomputation.

Keep the evidence layers separate in later protected reconciliation: process-local construction snapshots -> reconstructable normalized material -> durable non-reassignable generation/configuration persistence -> still-missing append-only deployment activation/rollback/recovery. #436 has zero PR-triggered workflow runs and no submitted review/thread evidence at this exact head, so this is implementation evidence only, not architecture acceptance or protected truth. ADR 0432 remains Proposed.

[seonghobae]

Architecture handoff only; no source rewrite warranted. #436 is exact 98b4b129073a2afc70f8a533e34c31fdcc15ab07 with durable generation/configuration persistence plus explicit TRUNCATE resistance. Draft #437 is exact 692d679a2d4b7234003cd25111f0b4078214e397, directly stacked on #436, and adds structural durable activation/rollback/recovery. Fresh review also identified the remaining authority boundary: reconstruction alone is not re-admission. Before ADR 0432 can be reconciled as protected activation truth, positive activation/recovery must bind fresh released Keyverse/Orgmetra ACL evidence and fresh observed owner API/operation evidence without remote I/O under the per-deployment DB lock. ADR remains Proposed; no Accepted/Ready claim.

[seonghobae]

Architecture-currentization handoff from #437: implementation exact head advanced from 2f3592ab... to 03eb4b0861a4f1de07c9b66c20f71ab28d378559 via 7d4ef88e... RED + 03eb4b08... repair. New finding is migration-publication atomicity, not a topology/bounded-context change: 0022 previously exposed product_composition_recovery_attestation after CREATE TABLE but before its validation and append-only triggers were installed because DDL statements autocommitted separately. 0022 now wraps table/function/trigger creation in one explicit BEGIN/COMMIT. ADR 0432 should remain Proposed, but its next source currentization should pin #437 03eb4b08... and record atomic 0022 schema publication as a separate durable-upgrade invariant. Predecessor hosted GREEN does not transfer after that material source edit.

[seonghobae]

Architecture-owner handoff after #437 advanced to fb362d554ab5c0cb2b3c2611aa0d4fa7314e1b32: ADR/TRACEABILITY already state the general rule that migration publication is durable authority, but current source still pins #437 c8886e6... and does not record the newly explicit 0020 predecessor-writer fence. RED cc8486c... -> fix fb362d5... makes 0019→0020 promotion one transaction with SHARE ROW EXCLUSIVE before NULL-evidence preflight and SET NOT NULL. Keep ADR 0432 Proposed/Draft; either ordinary-forward currentize the exact implementation evidence in source or record why this is covered by the existing decision before Accepted/Ready. Current ee98b339... hosted checks are still queued and there is no submitted independent review.

[seonghobae]

Architecture currentization handoff: executable child #437 advanced to exact 035826c9ddb1534290d8ed7957da3c5a45b80da4 (99 commits / 34 files) and migration order 0018→0023. New finding is architectural evidence, not a boundary change: application activation/recovery already shared a deployment FOR UPDATE, but DB direct-DML triggers did not. Migration 0023 now makes both INSERT paths acquire the same deployment row before lineage/evidence validation, with writer-fenced publication and a database-state-synchronized PostgreSQL contract. ADR 0432 can remain Proposed and the composition/application-adapter decision is unchanged, but ADR/TRACEABILITY source should ordinary-forward pin this exact evidence and record database-level activation/recovery serialization before Accepted/Ready. Predecessor GREEN does not transfer.

[seonghobae]

Architecture-owner handoff refresh: #436 remains exact 5fd0087179f2e6f23f2bb3853ad1de397fc53b0e; #437 has advanced ordinary-forward to exact 1f63bb2bb97215a6f3e688582fe187734588b534, 124 ahead / 0 behind #436. The child now carries an executable full-chain hostile caller-search-path contract and repairs 0019/0021/0022/0023 so migration-owned activation/recovery relations/functions are pinned and explicitly qualified in trusted public before final 0024 provenance rebinding.

The current #433 conversation/body still names predecessor #437 468dab6...; the three documentation files remain older still. Do not promote ADR 0432 from Proposed or mark Ready based on conversation metadata. Before architecture admission, ordinary-forward ADR/TRACEABILITY source must point to #437 1f63bb2... and preserve a distinct invariant for full migration-chain schema provenance: running 0018→0024 under hostile caller search_path must not redirect authority relations/functions outside public. This is separate from 0018 generation provenance and from 0024 final trigger-OID provenance. Fresh checks/review are required after that source write.

[seonghobae]

Architecture evidence handoff only; no source-status promotion: Draft #438 now advances the post-#437 request-routing layer at exact f3a0ba727a11505d4246dadfa79a170225f6da50, stacked exactly on #437 947517547e5a05a43635631650d0bf5594a3a577.

The new invariant is that declared Path Item selection precedes availability. In particular, an unavailable optional concrete route must fail closed and must not disappear early so that a broader available template captures the request. #438 returns only the stable current route_id after canonical request validation + #437 DB-bound currentness + concrete/template + explicit-method selection + final availability check. It intentionally does not assign HTTP statuses, perform auth/owner I/O/retries, or claim the deployable host.

ADR 0432 / TRACEABILITY / doctoring source remains at this PR's existing exact head and Proposed/Draft status. When source is next currentized after admissible exact-tree execution, record this declared-selection-before-availability boundary separately from the still-missing raw HTTP transport normalization, authenticated principal/ACL projection, owner transport, lifecycle invalidation/fault handling and measured buyer path.

[seonghobae]

Architecture evidence handoff: executable descendant stack now extends through Draft #439 exact 2256112d09a7130cd361264eda8303b12d7ad027, 5 ahead / 0 behind #438 exact d642eb71c05ae3990349a26facf30593a5703914 with #438 as merge base. #439 adds no SQL; it binds raw ASGI transport evidence to the already-decoded request-routing contract before route selection/currentness.

When this Proposed source is ordinary-forward currentized after canonical execution, keep the layers explicit: declared generation/configuration -> recovery-bound/current durable availability -> request path/method preselection -> raw ASGI request-target normalization -> later host/auth/owner execution. The transport layer currently requires exact HTTP scope, mandatory raw path, empty query/root path, admitted ASCII bytes and raw/decoded path identity. It is not a receive/send application and does not establish Keyverse auth, owner HTTP execution, lifecycle/fault handling, deployment or p95 evidence. PR metadata is only a handoff; ADR/TRACEABILITY/doctoring source at this PR's current head remains Proposed until separately updated.

[seonghobae]

Architecture evidence handoff currentization only; this is not source currentization and ADR 0432 remains Proposed/Draft.

Current executable descendant path now extends through #439 exact 2256112d09a7130cd361264eda8303b12d7ad027 (raw ASGI request-target normalization) and new Draft #440 exact 1776dee439aa6747b23c65c5cf742bb49697b9ed (stable error→HTTP problem projection, including declared-method Allow authority for 405). #440 is ordinary-forward 8 ahead / 0 behind #439 and changes no SQL/migrations.

When the ADR/TRACEABILITY/doctoring source ordinary-forward currentizes, keep these layers distinct: admitted generation/configuration; durable activation/recovery/currentness; declared path/method selection before availability; raw ASGI transport evidence before decoded routing; and RFC-conformant non-disclosing HTTP error projection. Do not describe #440 as a complete deployable composition host: Keyverse/Orgmetra auth context, owner HTTP execution, receive/body/disconnect/cancellation lifecycle, snapshot reload/invalidation, deployment/runtime role separation and full buyer-path acceptance remain absent.

Primary standards added by the descendant evidence are RFC 9110 405/Allow semantics and RFC 9457 problem details / about:blank status-phrase title / disclosure guidance. Embedded implementation SHAs remain evidence, not Accepted architecture, until the source itself and independent review currentize.