migrate-code

Migrate Code

Phase 4 of the migration pipeline: add a real SpiceDB client to the project, then rewrite every OpenFGA call site into the SpiceDB equivalent -- construct by construct, per code-mapping.md -- so the conversion ends with working SpiceDB client code, not a converted schema and data set the application still checks against the old system.

It is not the last thing the plugin automates. Phase 5 (/spicedb-dev:migrate-tests) has no ordering dependency on this command and may run before or after it, and /spicedb-dev:migrate-verify automates cutover-strategies.md step 4's differential harness once phase 3 has passed verification. Step 7 of this command's own report (below) is where that routing is stated to the user; keep the two consistent.

This command does two things the earlier phases didn't need to: it changes the project's dependencies, and it edits files a human wrote. /spicedb-dev:migrate-schema, /spicedb-dev:migrate-data, and /spicedb-dev:migrate-tests all produce new, standalone artifacts (schema.zed, a migration script, validation YAML) that a human reviews before anything downstream depends on them. This command instead vendors a client into the project's own dependency manifest and rewrites existing application source files in place. Five traps are common enough to name up front, because each produces code that compiles clean and then fails or answers wrong at runtime:

• A split relation is two names, and the write path and the check path need different ones. Phase 1 turned every source define that fused a [...] type list with an operator into a generated relation (viewer__direct) plus a same-named permission (viewer), and recorded the pair in migration-map.json's relation_splits. A rewrite that carries the source name through unchanged writes to a permission -- which SpiceDB rejects outright, on every write, at runtime -- and reads relationships through a filter that errors the same way; a rewrite that carries the generated name onto a check gets a narrower answer with no error at all. See code-mapping.md's "The relation-split obligation," and step 6 rule 3.
• Check code cannot be ported across languages mechanically. Python's check_permission has no permission parameter at all -- it reads Relationship.resource_relation -- and Rust's check_permission (singular) returns a CheckResult wrapper, not a bare bool. Converting a Go call site's CheckOne(ctx, cs, "viewer", rel) shape into Python or Rust by find-and-replace produces code that either doesn't compile or discards a wrapper silently. See code-mapping.md's "Per-language check-signature divergence."
• The identifier obligation fails closed, not at build time. Data written under base64url(email) by /spicedb-dev:migrate-data while a call site still checks user:[email protected] is a silent half-migration: the raw form fails SpiceDB's own object-id grammar on every single check, discovered in production traffic, not by a type checker or zed validate. Every call site that builds or reads an id of an encoded type must go through the codec phase 3 emitted -- see code-mapping.md's "The identifier obligation."
• batchCheck ordering silently corrupts results, not just names. OpenFGA's response is a map keyed by correlation_id, with no order guarantee. The SpiceDB client returns a plain, positionally-ordered array. Code that still pairs responses back to requests by correlation_id after a rename-only conversion pairs the wrong answer to the wrong request whenever the two happen to reorder -- see code-mapping.md's "batchCheck ordering."
• A sync OpenFGA source converting to Python's async-only client can turn a denial into a silent allow. Python is the one language of the seven where this actually happens: openfga_sdk.sync.OpenFgaClient is a real, documented sync client, but the prototype spicedb-python client has no sync form at all -- every method is async def, so the rewrite necessarily adds an await that was not in the source. A call site that misses it gets back a bare coroutine object, not a bool; a coroutine is truthy in Python's own if, so a check that would answer False takes the allowed branch instead, and the object compiles and runs without error. Confirmed live, and confirmed invisible to pyright and mypy --strict alike -- this is not a symptom of an untyped codebase, no Python type checker currently flags it. The other six languages do not share this shape: Go/Java/Ruby's SpiceDB targets are synchronous (no await to omit), and C#/Rust reject a missing await/.await at compile time; TypeScript's Promise is truthy the same way a coroutine is, but @openfga/sdk has no sync client for a rewrite to carry the habit over from, and tsc itself flags the bare case (TS2801) under a real type-check build. Review every Python call site converted from a sync OpenFGA client for a missing await by inspection -- see code-mapping.md's "Async-only target vs. sync source: the un-awaited-coroutine fail-open."