core/utils/remote_schema_compiler library

Remote Schema Compiler (FEAT-81) — pure-Dart, no Flutter dependency, so tool/remote_schema_compiler.dart can run as a genuine headless dart run CLI (same constraint as tool/accessibility_audit.dart, tool/dependency_sbom.dart).

Turns a declarative RemoteSchemaDef (a remote content pack's field shape across its version history) into:

  • generateModelSource: an immutable, value-equal Dart model class with fromJson/toJson — the generated file has zero import, not even on this package, so upgrading roy_casual_kit can never break a previously-generated file (the compatibility policy this feature is graded on).
  • buildMigrationRegistry: wires the schema's version list into the existing SaveMigrationRegistry (FEAT-37) — this compiler never invents its own migration-chain validation, it only supplies the version pairs; SaveMigrationRegistry's own constructor still throws SaveMigrationException on a broken/missing hop.
  • verifySignedFixture: gates a "real" remote content fixture through the exact same signature+version checks RemoteContentPack applies at runtime (save_integrity.dart's verifyAndStrip, reject-future-version) — a compiler run never bakes a forged or too-new fixture into generated migration-fixture data.

Safety-first construction: RemoteSchemaDef's factory constructor IS the validation gate — an invalid schema (duplicate/out-of-order version, duplicate or non-identifier field name, empty field list) never produces an instance, so no downstream step (codegen, migration wiring, fixture verification) can ever run against a broken schema.

Classes

RemoteSchemaDef
Validated, immutable definition of one remote content pack's schema across its version history. See library doc for the safety guarantee its factory constructor provides.
RemoteSchemaField
One field in one RemoteSchemaVersion's shape.
RemoteSchemaVersion
One version's full field shape.

Functions

buildMigrationRegistry(RemoteSchemaDef schema, {required Map<int, Map<String, Object?> Function(Map<String, Object?> input)> stepMigrations}) → SaveMigrationRegistry
Wires schema's version history into a SaveMigrationRegistry — one stepMigrations entry per consecutive (fromVersion, toVersion) hop is required (this compiler cannot safely synthesize field-transform logic from a declarative schema alone). Throws RemoteSchemaCompilerException if a hop's migrate function is missing; SaveMigrationRegistry's own constructor still re-validates the resulting chain.
generateModelSource(RemoteSchemaDef schema) → String
Generates a self-contained (zero-import) immutable Dart model class for schema's RemoteSchemaDef.current version — value-equal (==/ hashCode), fromJson/toJson, never-throwing field readers (a wrong-typed field falls back to a type-appropriate default, same tolerant-parsing contract lib/core/utils/safe_json.dart follows, re-implemented inline here instead of imported so the output has no dependency on this package at all).
verifySignedFixture(RemoteSchemaDef schema, Map<String, Object?> signedEnvelope, String secret) → SdkResult<Map<String, Object?>>
Verifies a fetched/authored signedEnvelope the same way RemoteContentPack does at runtime: HMAC signature via save_integrity.dart's verifyAndStrip, then rejects a schemaVersion newer than schema's RemoteSchemaDef.current — a downgraded compiler run must never bake content shaped for a future schema into generated fixtures. Returns SdkFailure (never throws) on any problem so a CLI caller can report it and refuse to generate anything from it.

Exceptions / Errors

RemoteSchemaCompilerException