test(cli)+docs(tph): #208 verify --db @Unmanaged gate + TPH lane-coverage note

Two small coverage/documentation gaps:

- cli verify-db-drift: add a test that `verify --db` treats an @Unmanaged DB object
  (Flyway / a hand-migration owns its DDL) as EXTERNAL — an out-of-band
  legacy_accounts table present in the DB is excluded from the drift comparison
  (computeDrift threads it out via collectUnmanagedNames) → exit 0 + the
  "external (declared @Unmanaged …)" annotation. Without the exclusion it would
  surface as a spurious drop-table drift. The behavior existed (#208) but was
  untested at the verify --db surface.

- api-contract tph/README: document that TPH runs BOTH lanes on TS + C#
  (full-stack) but the GENERATED lane only on the seam ports (Java/Kotlin/Python)
  as ACCEPTED design — a hand-rolled reference TPH server for a controller-only
  seam port would merely re-implement the generated routing, adding no independent
  contract signal. Prevents it being mistaken for a coverage gap.

Test/docs-only; no library behavior change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGQ7oSuNcjhsMHWwZzhBwr

Author: dmealing

fixtures/api-contract-conformance/tph/README.md

@@ -88,3 +88,26 @@ The runtime persistence half (single-table insert/find/update semantics, decimal
 normalization, no-cross-subtype-update) is pinned by the `persistence-conformance`
 `tph-*` query scenarios. A port can land routes-only or runtime-only first, so the
 two corpora gate independently.
+
+## Lane coverage — TPH is generated-lane-only on the seam ports (ACCEPTED design)
+
+The base / m2m / jsonb api-contract corpora run **both** lanes (hand-rolled
+reference server + generated artifact) on all five ports. **TPH deliberately does
+NOT**: it runs both lanes on **TS and C#** (`api-contract-tph.test.ts`,
+`TphReferenceServer.cs`) — the full-stack ports whose generated output includes
+persistence, so a hand-rolled reference server is a genuinely independent
+implementation worth cross-checking — but the **generated lane ONLY** on the seam
+ports **Java / Kotlin / Python** (`TphGeneratedApiContractConformanceTest` /
+`test_api_contract_tph_generated.py`; no hand-rolled reference TPH server).
+
+This asymmetry is intentional, not a coverage gap. Those three ports generate only
+the **controller/router** behind a consumer-supplied persistence seam, so the
+generated lane already boots the EMITTED polymorphic controller over HTTP — the
+artifact under test. A hand-rolled reference TPH server for a seam port would
+merely re-implement the discriminator routing + per-subtype filtering the
+generated controller already provides, yielding no independent contract signal
+beyond what the generated lane verifies. (For the base/m2m/jsonb corpora the seam
+ports DO keep a reference lane because its single-entity / traversal semantics are
+distinct enough from the generated code to be worth pinning independently.) The
+polymorphic-CRUD contract itself is still gated byte-identically across all five
+ports; only the redundant second lane is dropped where it would add nothing.

server/typescript/packages/cli/test/integration/verify-db-drift.test.ts

@@ -129,4 +129,52 @@ describe("meta verify --db — schema-drift gate", () => {
       rmSync(repo, { recursive: true, force: true });
     }
   });
+
+  // #208 — an @unmanaged DB object (Flyway / a hand-migration owns its DDL) must be
+  // INVISIBLE to `verify --db`: its out-of-band presence in the DB is NOT drift (it is
+  // threaded out of computeDrift via collectUnmanagedNames), and verify annotates it as
+  // external. Without the exclusion the extra table surfaces as a spurious drop-table
+  // drift → exit 1. Uses an @unmanaged TABLE (the Flyway-owned-entity case).
+  test("@unmanaged DB object present out-of-band → NOT drift; exit 0 + annotated external", async () => {
+    const repo = mkdtempSync(join(tmpdir(), "metaobjects-verify-db-unmanaged-"));
+    const dbUrl = `file:${join(repo, "local.db")}`;
+    // Widget is managed; Legacy is an @unmanaged table (Flyway / a hand-migration owns it).
+    const meta = JSON.stringify({
+      "metadata.root": {
+        package: "acme::drift",
+        children: [
+          { "object.entity": { name: "Widget", children: [
+            { "field.long": { name: "id" } },
+            { "field.string": { name: "name", "@column": "name" } },
+            { "identity.primary": { name: "pk", "@fields": ["id"] } },
+          ] } },
+          { "object.entity": { name: "Legacy", children: [
+            { "source.rdb": { "@table": "legacy_accounts", "@unmanaged": true } },
+            { "field.long": { name: "id" } },
+            { "identity.primary": { name: "pk", "@fields": ["id"] } },
+          ] } },
+        ],
+      },
+    });
+    try {
+      mkdirSync(join(repo, "metaobjects"), { recursive: true });
+      writeFileSync(join(repo, "metaobjects", "meta.drift.json"), meta, "utf8");
+      // Materialize: creates `widgets`, and NEVER the @unmanaged legacy_accounts.
+      await materialize(repo, dbUrl);
+      // Flyway creates the table out-of-band — it now EXISTS in the DB but is unmodeled-as-managed.
+      const client = createClient({ url: dbUrl });
+      await client.execute(`CREATE TABLE legacy_accounts ("id" integer PRIMARY KEY)`);
+      client.close();
+
+      const exit = await run(["verify", "--cwd", repo, "--db", dbUrl, "--dialect", "sqlite"]);
+      // The @unmanaged table is excluded from the drift comparison → in sync → exit 0.
+      expect(exit).toBe(0);
+      // ...and it is annotated as external rather than vanishing silently.
+      const all = [...out, ...err].join("\n");
+      expect(all).toContain("legacy_accounts");
+      expect(all).toContain("external");
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+    }
+  });
 });