feat(api): M4.2 — full REST surface + pgx-backed Postgres store

Replaces the M5.1-skeleton handler set with the M4.2 spec from
IMPLEMENTATION_PLAN.md:

Endpoints (authoritative shape in openapi.yaml):
  POST   /v1/tenants
  GET    /v1/tenants/{id}
  GET    /v1/tenants/by-slug/{slug}
  POST   /v1/tenants/{id}/activate
  POST   /v1/tenants/{id}/cancel
  GET    /v1/entitlements?tenant_id=...
  GET    /v1/catalog
  POST   /v1/catalog/request
  POST   /v1/catalog/trial-request
  POST   /v1/api-keys                       returns plaintext ONCE
  GET    /v1/api-keys?tenant_id=...
  DELETE /v1/api-keys/{id}
  POST   /v1/internal/api-keys/verify       always 200; valid: bool
  POST   /v1/audit
  GET    /v1/audit?{tenant_id,product,actor_id,action,since,until,limit,cursor}

Architecture:
  internal/store/store.go        Store interface (CRUD + audit + ping)
  internal/store/memory.go       in-process impl, used when DATABASE_URL
                                 is empty (seed acme tenant, no migrations)
  internal/store/postgres.go     pgxpool impl against the M4.1 schema
  internal/server/server.go      router + healthz/readyz
  internal/server/{tenants,catalog,apikeys,audit}.go
                                 per-concern handlers (≤250 LoC each)
  internal/server/helpers.go     writeJSON/writeError/error mapping/log mw
  openapi.yaml                   3.1 spec; openapi_test.go is the contract gate

API keys:
  Plaintext format 'bp_<22-char base64>'. Prefix bp_<8> stored for UI.
  Hash is argon2id(salt, time=1, mem=64MB, threads=4, len=32) encoded as
  'argon2id|<salt-b64>|<hash-b64>'. Format-tagged so we can rotate
  parameters without re-keying. Verify is constant-time.

Store selection:
  cmd/server picks Postgres when DATABASE_URL is set, otherwise Memory.
  Both implementations are exercised by the same eachStore test harness —
  parity is enforced.

Audit:
  Every state-changing endpoint emits via s.emitAudit() (fire-and-forget).
  audit_log uses ON DELETE SET NULL on tenant_id so forensic history
  outlives tenant deletes (per M4.1 schema).

Routing constraint:
  Go 1.22 ServeMux can't disambiguate /v1/tenants/{id}/products from
  /v1/tenants/by-slug/{slug=products}. Per-tenant subresources moved to
  query-param top-level paths: /v1/entitlements?tenant_id=… and
  /v1/api-keys?tenant_id=….

Tests:
  Every endpoint exercised against both Memory and Postgres via the
  eachStore harness. Includes happy paths, validation errors, conflicts,
  404s, auto-audit-emit assertion. testcontainers-go for the postgres
  harness; gated by -short.

  TestOpenAPISpec is the contract gate: every documented operation must
  resolve against the router. (kin-openapi v0.138.0.)

Refs: M4.2

internal/store/store.go

@@ -0,0 +1,92 @@
+// Package store hides the persistence layer behind a Store interface.
+// Two implementations: Memory (dev convenience, used when DATABASE_URL is
+// empty) and Postgres (production via pgx). Handlers depend on the
+// interface — never on a concrete type.
+package store
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+// Sentinel errors.
+var (
+	ErrNotFound     = errors.New("not found")
+	ErrConflict     = errors.New("conflict")
+	ErrInvalidInput = errors.New("invalid input")
+)
+
+// TenantCreate is the input shape for Store.CreateTenant.
+type TenantCreate struct {
+	Slug       string
+	Name       string
+	Plan       string // optional, defaults to "starter"
+	Kind       string // optional, defaults to "customer"
+	SalesOwner string // optional
+}
+
+// TenantUpdate captures partial mutations. Nil fields are left untouched.
+type TenantUpdate struct {
+	Status        *string
+	Plan          *string
+	ErpCustomerID *string
+	StripeCustID  *string
+	TrialEndsAt   *time.Time
+	ContractStart *time.Time
+	ContractEnd   *time.Time
+	SalesOwner    *string
+}
+
+// APIKeyCreate is the input shape for Store.CreateAPIKey.
+type APIKeyCreate struct {
+	TenantID  string
+	Product   string // empty = applies to all products
+	Name      string
+	Scopes    []string
+	Prefix    string
+	Hash      string // argon2id encoded
+	CreatedBy string
+}
+
+// AuditFilter narrows /v1/audit GET results.
+type AuditFilter struct {
+	TenantID string
+	Product  string
+	ActorID  string
+	Action   string
+	Since    *time.Time
+	Until    *time.Time
+	Limit    int
+	Cursor   int64 // id > Cursor (ascending) is the next page anchor
+}
+
+// Store is the persistence contract. Implementations:
+//   - Memory  — in-process, used when DATABASE_URL is empty (dev convenience).
+//   - Postgres — pgxpool-backed, used in stage + prod.
+type Store interface {
+	// Tenants
+	CreateTenant(ctx context.Context, in TenantCreate) (*Tenant, error)
+	GetTenant(ctx context.Context, id string) (*Tenant, error)
+	GetTenantBySlug(ctx context.Context, slug string) (*Tenant, error)
+	UpdateTenant(ctx context.Context, id string, in TenantUpdate) (*Tenant, error)
+
+	// Entitlements
+	UpsertTenantProduct(ctx context.Context, tp TenantProduct) (*TenantProduct, error)
+	ListTenantProducts(ctx context.Context, tenantID string) ([]TenantProduct, error)
+
+	// API keys
+	CreateAPIKey(ctx context.Context, in APIKeyCreate) (*APIKey, error)
+	FindAPIKeyByPrefix(ctx context.Context, prefix string) (*APIKey, string, error) // returns key + hash
+	TouchAPIKeyUsed(ctx context.Context, id string) error
+	RevokeAPIKey(ctx context.Context, id string) error
+	ListAPIKeys(ctx context.Context, tenantID string) ([]APIKey, error)
+
+	// Audit
+	AppendAudit(ctx context.Context, ev AuditEvent) (*AuditEvent, error)
+	ListAudit(ctx context.Context, f AuditFilter) ([]AuditEvent, int64, error) // returns rows + next cursor (0 = none)
+
+	// Lifecycle
+	Close()
+	Ping(ctx context.Context) error
+}