@flow-industries/id 0.21.2 → 0.22.1

package/README.md

@@ -82,3 +82,55 @@ pointer lock before opening, then use `onClose` to restore their input state.
 ## License
 
 MIT
+
+
+### Migration compatibility checks
+
+`bun run db:check` regenerates into a temporary directory and refuses schema drift or edits
+to previously committed SQL. CI compares against the PR base or previous main commit.
+`bun run test:migrations` exercises the committed chain, the supported previous schema,
+current projections, older writes after upgrade, and deliberate missing-migration failures.
+`MIGRATION_TEST_DATABASE_URL=postgres://... bun scripts/postgres-acceptance.ts` additionally
+creates a unique disposable database on a test PostgreSQL server, runs the real migration
+entrypoint, rejects a changed applied hash, and proves a failing final migration rolls back
+both its schema changes and ledger entry. The test deletes only its own generated database.
+
+The initial compatibility baseline is source `1bda372b69e2f66a3dc0cbb244bcbe7cb858f493` (schema through `0035`).
+The tests freeze representative older SQL reads/writes; they do not boot every historical
+application version. Advance this baseline deliberately when retiring support, and extend
+the fixtures when changing a persisted contract. Migration failures block the image build;
+production's PreSync job also refuses an applied ledger that is not an exact committed prefix.
+
+Application rollback keeps the expanded schema. Pin the latest verified migration image via
+Mesh's `migrate.image` while restoring the previous compatible application image. Do not run
+down migrations or point an older migration image at a newer ledger: that is refused. A
+destructive contract migration needs an explicit support-boundary change after older writers
+and browser clients have drained.
+
+## Versioned consumer contracts
+
+`bun run contracts:generate` produces the published
+`@flow-industries/id/contracts/v1/reports.json` and `openapi.json` artifacts from
+the same schemas used by the XP, action, presence and position handlers.
+`bun run contracts:check` rejects stale output and incompatible changes to the
+existing v1 request schema against `CONTRACT_BASE_REF` (default `origin/main`).
+Keep existing v1 fields compatible; a breaking boundary needs a new version and
+an overlap plan for deployed consumers.
+
+Trusted service consumers can call `createReportsApi(host, serviceToken)` from
+`@flow-industries/id`. The returned function accepts the operation name and its
+typed request, validates both the outgoing request and successful response, and
+throws `ReportRequestError` for non-success responses. Use the XP reporting
+credential for action/XP operations and the room credential for presence/position;
+never ship either service credential to a browser.
+
+`bun run test:sdk-package` builds, packs and installs the actual SDK artifact in
+a disposable consumer, checks public imports and declarations, and proves a
+removed contract export fails. Producer tests execute the typed client against
+real report handlers and validate minted guest/full session and JWT shapes.
+CI gates both container and package publication on these checks.
+
+The current OpenAPI artifact describes the service report boundary. The remaining
+account, room management, study, settings, session and passkey HTTP operations
+still need complete request/response descriptions and generated client coverage
+before the full HTTP contract work is complete.