Topaz alignment spike — mapping doc + green e2e example

Closes FLEX-WP-0005 T04. Validates ADR-003's commitment to shape the
standalone core for cheap Topaz adapter work.

Spike output:
- docs/topaz-mapping-spike.md — vocabulary map (subject, group, tenant,
  knowledge_base, document, plus parent / owner_team / reader / steward /
  member relations), Rego module shape, decision envelope, wire-protocol
  ranking (gRPC primary, REST fallback, embedding rejected), schema
  restatement recommendation, implications for FLEX-WP-0002 / 0004.
- examples/topaz/ — runnable docker-compose deploying Topaz with the
  flex-auth-shaped manifest. seed and probe one-shots cover three
  scenarios: alice (steward) allow, bob (group→reader) allow, eve
  (outsider) deny. End-to-end green on 2026-05-16:

    probe: steward-allow OK (check=true)
    probe: reader-allow  OK (check=true)
    probe: outsider-deny OK (check=false)
    probe: all checks passed

Key findings recorded as Implementation Notes in the spike doc:
- Rego input contract bridging (Topaz raw shape ↔ flex-auth canonical
  shape) is adapter scope, not core scope.
- Topaz identity objects are a Topaz convention; the adapter
  materializes them at directory import time.
- Directory-only permission resolution is sufficient for the common
  case; Rego is reserved for context-dependent decisions.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

examples/topaz/README.md

@@ -0,0 +1,99 @@
+# Topaz alignment example
+
+Runnable validation for the alignment commitment in ADR-003 and the
+mapping recorded in `docs/topaz-mapping-spike.md`. Boots Topaz, seeds
+a directory shaped like flex-auth's canonical vocabulary, and probes
+three permission scenarios.
+
+## Quick start
+
+```sh
+cd examples/topaz
+docker compose up --abort-on-container-exit --exit-code-from probe
+```
+
+Expected outcome (exit code 0):
+
+```
+probe-1  | probe: steward-allow OK (check=true)
+probe-1  | probe: reader-allow  OK (check=true)
+probe-1  | probe: outsider-deny OK (check=false)
+probe-1  | probe: all checks passed
+```
+
+Tear down:
+
+```sh
+docker compose down -v
+```
+
+## What the example proves
+
+- Topaz's v3 manifest can express flex-auth's canonical object types
+  (`user`, `group`, `tenant`, `knowledge_base`, `document`) and
+  relations (`member`, `parent`, `owner_team`, `reader`, `steward`).
+- The Markitect fixture data
+  (`examples/markitect/resource_manifest.yaml`, mirrored here) seeds
+  the directory without translation.
+- Group→reader edges (`reader:platform-architecture` group with a
+  `member` relation, plus a `reader` relation from the document to
+  that group with `subject_relation=member`) resolve correctly via
+  the manifest's `reader | group#member` union.
+- The `check` decision is fully derivable from directory data for the
+  read-path case; no Rego is involved.
+
+## File map
+
+```
+manifest.yaml              # Topaz v3 directory manifest
+policy/markitect.documents.rego   # Rego module showing flex-auth's
+                                  # canonical input shape (used by the
+                                  # standalone evaluator; FLEX-WP-0004
+                                  # T01 will bridge to Topaz's input)
+bundle/                    # OPA bundle loaded into Topaz
+bundle/.manifest           # OPA bundle root manifest
+bundle/policy/markitect.documents.rego   # same Rego, mounted into Topaz
+data/objects.json          # seed objects
+data/relations.json        # seed relations
+cfg/config.yaml            # Topaz config
+scripts/seed.sh            # writes manifest + objects + relations
+scripts/probe.sh           # three directory checks via REST
+docker-compose.yml         # topaz, seed (one-shot), probe (one-shot)
+```
+
+## Ports
+
+When running, Topaz exposes (on `127.0.0.1` only):
+
+| Port | Service |
+| --- | --- |
+| 8282 | authorizer gRPC |
+| 8383 | authorizer REST |
+| 9292 | directory gRPC (reader, writer, model, exporter, importer) |
+| 9393 | directory REST gateway |
+| 9494 | health |
+| 9696 | metrics |
+
+Plaintext HTTP on the gateways. Internal gRPC uses TLS with
+auto-generated self-signed certs in a `topaz-certs` named volume; the
+`remote_directory.insecure: true` flag tells the in-process clients to
+accept them.
+
+## Caveats
+
+- Plaintext gateways are for the spike only. Real deployments use
+  certs everywhere; see `docs/topaz-mapping-spike.md` §"Wire-Protocol
+  Candidates" for the production posture.
+- The probe deliberately uses the directory `check` API instead of the
+  authorizer `is` API. Bridging flex-auth's Rego input shape into
+  Topaz's raw authorizer input is the Topaz adapter's job
+  (FLEX-WP-0004 T01) and is intentionally out of scope for this
+  validation. See `docs/topaz-mapping-spike.md` §"Implementation Notes
+  Surfaced By The Spike".
+
+## Pinned Topaz version
+
+`ghcr.io/aserto-dev/topaz:latest` as resolved on 2026-05-16
+(digest `sha256:11fa7e2075870f3fe523afaadd942a6559b612f44b6bdb1296fe65299f5831fa`).
+FLEX-WP-0004 T01 will pin a specific tagged version once the adapter
+lands.