docs(roadmap): close Packet 7 with the record of what it got wrong

The delivery record, the status blocks in three carriers, the three
architecture rules this packet added and never registered, and the two
isolation entries that promised a request-level case without naming one.

Measured at close: 1187 tests green — counted from a run, not computed. An
earlier commit message in this packet carried a total that was eight short
because it summed two review rounds instead of applying the second on top.

The record is long for the reason Packets 5 and 6's were. Eleven steps, each
reviewed twice, and the second round repeatedly found the first round's fix: a
conflict translation that turned a 409 into a 500, a seeder idempotency check
that masked validation failures, a cache invalidation whose comment claimed a
guarantee its placement did not give. The sharpest finding was in the last step —
a test that asserted an anonymous POST failed, and therefore passed against a
deleted endpoint and against a database with every policy dropped.

It also records what the packet did not ship and who owns each: nothing is
audited until Packet 9, nothing is authorized until Phase 03, PlatformAdminScope
ships with no reachable caller, and the host-resolution cache is invalidated
before the commit rather than after.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cemililik

CLAUDE.md

@@ -36,11 +36,10 @@ repository holds only LearnStack's side of the boundary, in
 
 **Phase 01 complete.
 [Phase 02a](docs/roadmap/phase-02a-kernel-tenancy.md) in progress —
-packets 0–3, 3b, 4, 5 and 6 shipped; packets 3b–10 were re-scoped on 2026-08-08
+packets 0–3, 3b, 4, 5, 6 and 7 shipped; packets 3b–10 were re-scoped on 2026-08-08
 after a four-report audit of the corpus.
-[Packet 7](docs/roadmap/phase-02a-kernel-tenancy.md#packet-sequence) — host and
-tenant resolution, the EF query filters, the request-level isolation suite and
-the two seed tenants — is next.**
+[Packet 8](docs/roadmap/phase-02a-kernel-tenancy.md#packet-sequence) — the Tenant
+Customization foundation — is next.**
 
 **Phase 01** shipped the .NET 10 solution scaffold under `backend/`
 (core + 7 modules × 4 projects + 4 test projects including the
@@ -109,6 +108,24 @@ is long because several of its defects were introduced by the *fix* for an
 earlier one, and because three tests were caught agreeing with the code instead
 of constraining it — the packet's most repeated lesson.
 
+**Packet 7** shipped what a request does with a tenant: host classification and
+resolution, `EffectiveHost` normalization, the negative host cache, the
+four-origin `TenantContextFactory`, and `TenantContextBehavior`'s two-gate
+authority ceiling with `[AllowsUnresolvedTenantContext]` and `[PublicSurface]` as
+enumerated holes. With them: `ProvisionTenantCommand`, the one operation
+[ADR-0042](docs/decisions/0042-tenant-provisioning-cross-aggregate-transaction.md)
+sanctions to write two aggregate roots on one transaction; `CreateOrganizationCommand`
+and `MapHostToTenantCommand`, both taking their tenant from the context and never
+from the request; `LearnStack.Tools.Seeder` and the two seed tenants
+(`demo-english`, `demo-yoga`) written through those commands, so `make seed` exercises
+the request path rather than a second one; and the request-level isolation suite —
+the first fixture pairing the real middleware chain with a real database. Its record,
+[Delivery Record (Packet 7)](docs/roadmap/phase-02a-kernel-tenancy.md#delivery-record-packet-7),
+is long for the reason Packets 5 and 6's were: eleven steps, each reviewed twice,
+and the second round repeatedly found the first round's fix. The sharpest finding
+was a test that asserted an anonymous POST failed and therefore passed against a
+deleted endpoint.
+
 **Packet 6** shipped the tenancy schema: the four database roles, ten tables in
 two independent migration chains, and every one of them under `ENABLE` **and**
 `FORCE ROW LEVEL SECURITY` with the corrected

README.md

@@ -41,9 +41,12 @@ for LearnStack's side of the boundary.
 ## Status
 
 **Phase 01 complete. [Phase 02a](docs/roadmap/phase-02a-kernel-tenancy.md) in progress —
-packets 0–3, 3b, 4, 5 and 6 shipped; packets 4–10 re-scoped on 2026-08-08.
-[Packet 7](docs/roadmap/phase-02a-kernel-tenancy.md#packet-sequence) — host and tenant
-resolution, the query filters, and the two seed tenants — is next.**
+packets 0–3, 3b, 4, 5, 6 and 7 shipped; packets 4–10 re-scoped on 2026-08-08.
+Packet 7 landed host and tenant resolution, the query filters, tenant provisioning
+and the two seed tenants — `demo-english` and `demo-yoga`, which `make seed` writes
+through the same commands a request uses.
+[Packet 8](docs/roadmap/phase-02a-kernel-tenancy.md#packet-sequence) — the Tenant
+Customization foundation — is next.**
 
 Phase 01 shipped the .NET 10 solution scaffold, the `pnpm` frontend monorepo
 (`apps/web` + `packages/{config,ui,sdk}`), the local-dev `docker-compose` stack, and the

docs/roadmap/phase-02a-kernel-tenancy.md

@@ -1,7 +1,7 @@
 # Phase 02a: Platform Kernel, Multi-Tenancy, Organization, and Foundation Sockets
 
-> **Status (2026-08-28).** Phase 02a in progress. Packets 0–3, 3b, 4, 5 and 6 shipped; the
-> 2026-08-08 restructure re-scoped packets 4–10 and added packet 3b. Each packet
+> **Status (2026-09-03).** Phase 02a in progress. Packets 0–3, 3b, 4, 5, 6 and 7 shipped;
+> the 2026-08-08 restructure re-scoped packets 4–10 and added packet 3b. Each packet
 > is independently reviewable in its own commit, matching the
 > [Phase 01 cadence](phase-01-repository-tooling.md). The order is dependency-driven: a
 > later packet may consume any earlier packet's deliverables, never the reverse.
@@ -16,7 +16,7 @@
 > | 4 | API conventions | ✅ [record](#delivery-record-packet-4) |
 > | 5 | Foundation ports and default implementations | ✅ [record](#delivery-record-packet-5) |
 > | 6 | Tenancy schema and the corrected RLS template | ✅ [record](#delivery-record-packet-6) |
-> | 7 | Tenant and organization resolution, isolation, two tenants | ⏳ [scope](#packet-sequence) |
+> | 7 | Tenant and organization resolution, isolation, two tenants | ✅ [record](#delivery-record-packet-7) |
 > | 8 | Tenant Customization foundation | ⏳ [scope](#packet-sequence) |
 > | 9 | Audit infrastructure and the entitlement socket | ⏳ [scope](#packet-sequence) |
 > | 10 | Architecture tests green and phase exit | ⏳ [scope](#packet-sequence) |
@@ -30,7 +30,8 @@
 > [`## Delivery Record (Packet 3b)`](#delivery-record-packet-3b), and Packet 4 in
 > [`## Delivery Record (Packet 4)`](#delivery-record-packet-4), Packet 5 in
 > [`## Delivery Record (Packet 5)`](#delivery-record-packet-5), and Packet 6 in
-> [`## Delivery Record (Packet 6)`](#delivery-record-packet-6) — each kept separate
+> [`## Delivery Record (Packet 6)`](#delivery-record-packet-6) and Packet 7 in
+> [`## Delivery Record (Packet 7)`](#delivery-record-packet-7) — each kept separate
 > because the frozen one is scoped to packets 0–3.**
 
 ## Goal
@@ -1400,8 +1401,6 @@ The remaining exit gates (tenant + organization resolution, isolation tests runn
 conventions, two seed tenants, architecture-test catalogue green) close as Packets
 3b–10 ship.
 
-
-
 ## Delivery Record (Packets 0–3)
 
 Shipped history, kept verbatim. Packets 0–3 and the 2026-08-08 restructure annotation
@@ -2423,3 +2422,94 @@ in a record rather than in production.
 > does not mistake a green suite for proof of them: a cross-module read inside the
 > ambient transaction returning rows, and an outer failure after an inner write
 > leaving zero rows in both modules. Both need a second module `DbContext`.
+
+## Delivery Record (Packet 7)
+
+Kept separate from the records above, and long for the reason Packets 5 and 6 were:
+most of what follows is a defect this packet introduced and its own review rounds
+found. Eleven steps, each reviewed twice — once by an Opus agent, once by a Sonnet
+one — and the second round repeatedly found the first round's fix.
+
+> **Packet 7 — Tenant and organization resolution, isolation, two tenants ✅**
+>
+> **Measured at close: 1187 tests green** — 1 contract, 76 architecture, 802 unit,
+> 308 integration. Counted from a run, not computed from a plan; an earlier commit
+> message in this packet carried an arithmetic total that was eight short.
+
+### What shipped
+
+- **Host and tenant resolution.** `HostClassificationMiddleware`,
+  `TenantResolverMiddleware`, `CachedHostToTenantResolver`, `EffectiveHost`
+  normalization, the `UnknownHostCache`, and the four-origin `TenantContextFactory`
+  behind a pure, total, synchronous `Create`.
+- **The authority ceiling.** `TenantContextBehavior`'s two nested gates, with
+  `[AllowsUnresolvedTenantContext]` and `[PublicSurface]` as enumerated holes and an
+  architecture rule counting each.
+- **Provisioning.** `ProvisionTenantCommand` — the one operation
+  [ADR-0042](../decisions/0042-tenant-provisioning-cross-aggregate-transaction.md)
+  sanctions to write two aggregate roots on one transaction — with
+  `IProvisionsTenant`, the `SetProvisioningTenantContextAsync` announcement seam, and
+  `IAggregateWriteStore<TRoot, TId>`, the codebase's first persistence port.
+- **`CreateOrganizationCommand` and `MapHostToTenantCommand`,** both taking their
+  tenant from the context and never from the request, plus
+  `PlatformHostMapping.Create`, which did not exist and without which nothing could
+  write a host row at all.
+- **Two seed tenants** — `demo-english` and `demo-yoga`, two organizations each, one
+  host row each of a different live class — written by `LearnStack.Tools.Seeder`
+  through the same commands a request sends, because ADR-0042 requires the seeder not
+  to hold a second copy of the sanctioned cross-aggregate write. `make seed` runs it.
+- **The request-level isolation suite,** the first fixture pairing
+  `WebApplicationFactory<Program>` with a real Postgres container: five cases driven
+  by the host header alone, with no stubbed `ITenantContext`.
+
+### What this packet got wrong, and how it was found
+
+- **A `[Theory]` that agreed with the code.** Three separate tests were caught
+  asserting what the implementation did rather than what it owed. The sharpest was in
+  the final step: `Write_With_Foreign_TenantId_Is_Rejected_By_WithCheck` performed no
+  `INSERT` at all — it asserted that an anonymous POST failed, which a 404 satisfies,
+  so it passed against a **deleted endpoint** and against a database with every policy
+  dropped. `Org_X_cannot_read_Org_Y` read a tenant-wide table and narrowed the rows
+  with a `Where` the test's own probe handler wrote.
+- **A validator whose every message was discarded.** `ValidationBehavior` builds its
+  response from `ErrorCode ?? ErrorMessage`, and FluentValidation always fills
+  `ErrorCode` with the validator's own name — so a malformed slug and a tenant sharing
+  its organization's id both reached the caller as `lockey_predicatevalidator`, the
+  second under an empty field key.
+- **A fix that made things worse.** Translating a uniqueness conflict into four
+  module-specific error codes turned a duplicate slug from a 409 into a **500**:
+  `HttpStatusMap` is a closed table of cross-cutting codes and falls through to
+  `InternalServerError`. The shape that works is the one `ValidationBehavior` already
+  used — a canonical top-level code plus per-field details.
+- **An architecture rule with three escapes.** The cross-aggregate rule missed a fused
+  port, every `INotificationHandler`, and any non-public constructor — each proven by
+  dropping the shape into a production assembly and watching 76 cases pass. Worse, the
+  ADR amendment written alongside it *claimed* the fused case was caught.
+- **`make seed` could not run.** It read `ConnectionStrings__Default` from the process
+  environment, which nothing populates: the Makefile has no `include .env`. The error
+  it printed offered a remedy — copy `.env.example` to `.env` — that is exactly the
+  state that already fails.
+- **An idempotency check that masked failures.** The seeder treated any
+  `business_rule_violation` as "already seeded", which was safe while provisioning was
+  the only command and stopped being safe the moment `MapHostToTenantCommand` returned
+  the same code for three different conditions.
+- **Two obligations inherited without noticing.** ADR-0036 assigns the
+  `Tenancy:PlatformHosts` collision check to "whichever packet builds the host-mapping
+  writer", and `UnknownHostCache.Forget` had no caller because none existed. This
+  packet built that writer.
+- **A promise from ADR-0037 that Packet 6 did not keep.** `IIdempotencyStore` still
+  took a raw `Guid` tenant after the ADR said it and `ITenantContext.TenantId` "both
+  move together". Amendment 4 records the conversion and the divergence.
+
+### What it did not ship, and who owns each
+
+- **Nothing is audited.** `AuditLogBehavior` lights up in Packet 9; `TransactionBehavior`
+  carries the `TODO` marking the line the MUST-class write goes on.
+- **Nothing is authorized.** No permission key is registered; the three commands are
+  reachable only from the seeder and, from Phase 02c, the Hub over `/api/internal/*`.
+  Phase 03 ships the catalogue.
+- **`PlatformAdminScope` has no reachable caller.** It ships with its gate closed;
+  Packet 9's GDPR handler is the first.
+- **The host-resolution cache is invalidated before the commit, not after.** The
+  guarantee is therefore the request *after* the write, not the one racing it; closing
+  the rest needs a post-commit seam on `IUnitOfWork`, whose surface ADR-0040 governs.

docs/standards/21-architecture-tests-catalogue.md

@@ -990,13 +990,19 @@ first two rows are coverage checks; the last three are the proof.
 - **Source:** ADR-0003 Amendment 3 § Test requirement.
 - **Type:** **integration** test (Testcontainers + PostgreSQL), not an architecture
   test. **Kind:** runtime.
-- **Status:** **Implemented** (Packet 6 step 4,
-  `LearnStack.Tests.Integration`, `TenancySchemaTests`). It moved forward because
-  the schema's own assertions needed the two-tenant seed anyway: without rows for
-  both tenants, every count assertion in that class passed against dropped
-  policies. Packet 7 re-runs it through `TenantResolverMiddleware` and the EF
-  query filters rather than through `set_config`.
-- **Phase:** 02a (Packet 6 ships the schema-level case; Packet 7 the request-level one).
+- **Status:** **Implemented, twice.** The schema-level case is Packet 6 step 4
+  (`TenancySchemaTests`); the request-level one is Packet 7 step 11
+  (`Database/TenantIsolationHttpTests`), which drives it through
+  `HostClassificationMiddleware`, `TenantResolverMiddleware`, the announcement and the
+  EF query filters, with the host header as the only input and no stubbed
+  `ITenantContext`. The schema-level case moved forward because that class's own
+  assertions needed the two-tenant seed anyway: without rows for both tenants, every
+  count in it passed against dropped policies.
+- **Reads `tenant_settings`, not `platform_host_to_tenant`.** The row shape the rule
+  names is tenant-owned with `organization_id IS NULL`; the host table is
+  platform-scoped and its policy has no organization term, so reading it would name the
+  wrong mechanism. The first version of the request-level case did exactly that.
+- **Phase:** 02a (Packet 6 the schema-level case; Packet 7 the request-level one).
 
 #### `Write_With_Foreign_TenantId_Is_Rejected_By_WithCheck`
 
@@ -1008,18 +1014,71 @@ first two rows are coverage checks; the last three are the proof.
 - **Source:** ADR-0003 Amendment 3 § Test requirement;
   [05-database.md](05-database.md).
 - **Type:** **integration** test (Testcontainers + PostgreSQL). **Kind:** runtime.
-- **Status:** **Implemented** (Packet 6 step 4,
-  `LearnStack.Tests.Integration`, `TenancySchemaTests`) — as a `[Theory]` over
-  both halves, because `WITH CHECK` guards `INSERT` and `UPDATE` and a rule
-  covering one leaves the other open.
-- **Phase:** 02a (Packet 6 ships the schema-level case; Packet 7 the request-level one).
+- **Status:** **Implemented, twice.** Packet 6 step 4 (`TenancySchemaTests`) as a
+  `[Theory]` over both halves, because `WITH CHECK` guards `INSERT` and `UPDATE` and a
+  rule covering one leaves the other open. Packet 7 step 11
+  (`Database/TenantIsolationHttpTests`) issues the write through a request: raw SQL on
+  the ambient connection, so no query filter is in front of it and only `WITH CHECK` can
+  refuse. The first version of that case asserted merely that an anonymous POST failed,
+  and passed against a **deleted endpoint** and against a database with every policy
+  dropped — which is why the entry now says what the case must observe rather than what
+  it must return.
+- **Phase:** 02a (Packet 6 the schema-level case; Packet 7 the request-level one).
 
 `Tenant_A_cannot_read_Tenant_B_data`, `Org_X_cannot_read_Org_Y_within_TenantA` and
 `Unsetting_tenant_context_returns_zero_rows_through_RLS` are ordinary integration tests
-named in the phase document rather than catalogue-governed rules; all three shipped
-alongside the two rules above in Packet 6 step 4 and are listed in
-[Phase 02a Packet 7](../roadmap/phase-02a-kernel-tenancy.md), which re-runs them through
-the request path.
+named in the phase document rather than catalogue-governed rules. All three shipped
+alongside the two rules above in Packet 6 step 4, and Packet 7 step 11 re-runs them
+through the request path in `Database/TenantIsolationHttpTests`.
+
+Three things are worth recording about that second run, because each was a defect in its
+first version. `Org_X_…` must read an **organization-scoped** table — `tenant_settings`,
+whose policy carries an organization term — not `organizations`, which is tenant-wide and
+where every organization is visible to every other by design; reading the latter and
+narrowing the rows in the test's own handler tested the test.
+`Unsetting_tenant_context_…` must actually run a query under an unresolved context, which
+takes a `PlatformHost` request (a host in `Tenancy:PlatformHosts`); asserting a 404 for an
+unknown host instead exercises the resolver and never reaches a table. And the suite as a
+whole constrains the **composite** answer, not one layer: measured, deleting both EF query
+filters leaves all five green because RLS holds, disabling RLS leaves the four reads green
+because the filters hold, and removing both turns all five red.
+
+#### `Every_Scoping_Interface_Carries_Its_Marker`
+
+- **Asserts:** every entity implementing a scoping interface — `ITenantOwned`,
+  `IOrganizationScoped` — also carries the marker attribute the filter and policy
+  generators read. An entity that implements one and not the other is scoped in the type
+  system and unscoped everywhere it matters.
+- **Source:** [ADR-0003 Amendment 3](../decisions/0003-tenant-isolation-defense-in-depth.md).
+- **Type:** xUnit + reflection. **Kind:** structural.
+- **Status:** **Implemented** (Packet 7, `LearnStack.Tests.Architecture`).
+- **Phase:** 02a Packet 7.
+
+#### `The_Request_Filter_Sees_Every_Shape_MediatR_Dispatches`
+
+- **Asserts:** the predicate that enumerates request types covers every shape MediatR
+  dispatches, so a rule written over "all requests" is not silently blind to one of them.
+  Measured facts behind it: `IStreamRequest<T>.GetInterfaces()` is empty and
+  `IBaseRequest.IsAssignableFrom(IStreamRequest<>)` is false, so a filter written the
+  obvious way misses streamed requests entirely.
+- **Source:** [04-api-design.md](04-api-design.md).
+- **Type:** xUnit + reflection. **Kind:** structural.
+- **Status:** **Implemented** (Packet 7, `LearnStack.Tests.Architecture`).
+- **Phase:** 02a Packet 7.
+
+#### `The_Sweep_Covers_Every_Production_Assembly`
+
+- **Asserts:** every `LearnStack.*` project under `backend/src` is loadable by the rules
+  that sweep production assemblies. A project the sweep cannot load is a project every
+  reflection rule silently skips, which is worse than a rule that fails: it reports green
+  over code it never read.
+- **Note:** it is why adding a project — `LearnStack.Tools.Seeder` in Packet 7 step 10 —
+  requires a `ProjectReference` from the architecture test project. The rule names the
+  remedy in its own failure message.
+- **Source:** [21-architecture-tests-catalogue.md § What a structural test proves](#what-a-structural-test-proves--and-what-it-does-not).
+- **Type:** xUnit + reflection. **Kind:** structural.
+- **Status:** **Implemented** (Packet 7, `LearnStack.Tests.Architecture`).
+- **Phase:** 02a Packet 7.
 
 #### `Tenant_Context_Guard_Fires_Only_On_An_Unmarked_Transaction`