<a id="dads-frameworkauthorization-migration"></a>

# `@dads-framework/authorization-migration`

Scaffold and apply ordered SpiceDB schema snapshots and relationship migration steps.

<a id="try-it"></a>

## Try it

The generated starter uses Postgres for authorization in [`assembly/services.ts`](https://dadsframework.dev/docs/source/apps/kit-workbench/assembly/services.ts). For the SpiceDB schema journal, see the repository's [journal runner tests](https://dadsframework.dev/docs/source/packages/server/authorization-migration/src/lib/run-authorization-migrations.test.ts), which show ordered application and a rerun that skips applied entries.

Use Node.js 22 or later. The script creates a temporary journal, previews the first migration ID, then checks that scaffolding the same schema again is a no-op. No SpiceDB instance is needed to scaffold.

```sh
npm install @dads-framework/authorization-migration
npm install -D tsx
```

Save as `scaffold-journal.mts` and run `npx tsx scaffold-journal.mts`.

```ts
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
  listShippedAuthorizationMigrationIds,
  scaffoldMigration,
} from "@dads-framework/authorization-migration";

const journalFolder = await mkdtemp(join(tmpdir(), "dads-journal-"));
try {
  const input = {
    journalFolder,
    mode: "new",
    slug: "baseline",
    composedSchema: `
definition authz/migration_version {}
definition authz/migration_journal {
  relation applied: authz/migration_version
}
definition user {}
`,
  } satisfies Parameters<typeof scaffoldMigration>[0];

  console.log((await scaffoldMigration(input)).action);
  console.log(
    (await listShippedAuthorizationMigrationIds(journalFolder)).join(),
  );
  console.log((await scaffoldMigration(input)).action);
} finally {
  await rm(journalFolder, { recursive: true, force: true });
}
```

The script prints `created`, `0001_baseline`, and `up-to-date`. To retain the generated `index.ts`, `schema.zed`, and `migration.ts` in your app, use an existing journal directory and omit the temporary directory cleanup.

<a id="use-it"></a>

## Use it

Pass the generated index's `journal`, the absolute path of its directory, an `AuthorizationMigrationStore`, and a logger with an `info` method to `runAuthorizationMigrations`. For a development run against SpiceDB, start with a dedicated datastore and construct `SpiceDbAuthorization` from `@dads-framework/authorization` with its endpoint and credentials. Pass the adapter as `store`. A successful run logs the applied ID. Rerunning the same journal reports zero newly applied entries.

For independently authored patches, use `scaffoldAuthorizationChange` and pass their directory as `changesFolder` on the same runner. Each patch records the definitions it changes and the changes it depends on. `renumberMigration` moves a snapshot entry that collided with another branch.

<a id="what-it-refuses-to-do"></a>

## What it refuses to do

The runner rejects gaps, duplicate entries, unregistered folders, and snapshots that drop the journal definition. A destructive entry after the baseline requires the relationship steps that make its schema write legal.

<a id="contract"></a>

## Contract

Each `NNNN_slug` holds a full schema snapshot. The runner calls `beforeSchemaWrite`, writes the snapshot, and then calls `afterSchemaWrite` when those steps are present. It records success as an `authz/migration_version` relationship. A failure leaves the marker unwritten. Make relationship steps safe to repeat when retrying an entry.

Canonical page: <https://dadsframework.dev/docs/package-authorization-migration>
