@crombolo/data 0.9.1 → 0.10.0

package/src/migrations.ts

@@ -3,7 +3,7 @@
  * version number and not a list of applied migrations: the plan is a chain of
  * transitions walked forward to its final state. That design handles concurrent
  * development branches far better than sequence numbers, so we keep it — and
- * harden it (docs/10-packaging-and-upgrades.md): a ledger of every step that
+ * harden it (docs/packaging-and-upgrades.md): a ledger of every step that
  * ran, expand/contract declared and linted, a recorded plan, and an explicit
  * refusal when the database is newer than the code.
  */
@@ -29,7 +29,24 @@ export interface Migration {
   release?: string
   /** For a contract: the name of the expand migration it removes. */
   contracts?: string
+  /** Recorded in the ledger, and compared when the plan verifies what ran. Defaults to `name`. */
+  checksum?: string
   up(db: Db): Promise<void>
+  /**
+   * Writes data once `up` has run, in the same transaction. `planUpgrade` cannot
+   * predict what it writes, so a step that has one is reported as unplannable.
+   */
+  backfill?(db: Db): Promise<void>
+}
+
+/** Where a chain keeps its state, and what it calls itself in the ledger. */
+export interface ChainOptions {
+  /** The `key_value` key holding the chain's state. */
+  stateKey?: string
+  /** The state before the first step. */
+  initialState?: string
+  /** A bundle's id, for a bundle's chain; absent for core's. */
+  bundle?: string
 }
 
 function compareRelease(a: string, b: string): number {
@@ -71,10 +88,16 @@ export function isMajorRelease(release: string): boolean {
 
 export class MigrationPlan {
   readonly migrations: readonly Migration[]
+  readonly stateKey: string
+  readonly initialState: string
+  readonly bundle: string | undefined
 
-  constructor(migrations: readonly Migration[]) {
+  constructor(migrations: readonly Migration[], options: ChainOptions = {}) {
     this.migrations = migrations
-    let expected = INITIAL_STATE
+    this.stateKey = options.stateKey ?? MIGRATION_STATE_KEY
+    this.initialState = options.initialState ?? INITIAL_STATE
+    this.bundle = options.bundle
+    let expected = this.initialState
     const seen = new Map<string, Migration>()
     for (const migration of migrations) {
       if (migration.from !== expected) {
@@ -111,7 +134,14 @@ export class MigrationPlan {
   }
 
   get finalState(): string {
-    return this.migrations.at(-1)?.to ?? INITIAL_STATE
+    return this.migrations.at(-1)?.to ?? this.initialState
+  }
+
+  /** The steps that have run when the chain is at a state; undefined when the state is not in it. */
+  appliedAt(state: string): Migration[] | undefined {
+    if (state === this.initialState) return []
+    const index = this.migrations.findIndex((m) => m.to === state)
+    return index < 0 ? undefined : this.migrations.slice(0, index + 1)
   }
 
   /** The steps still to run from a state; empty when current. Undefined when the state is not in the plan. */
@@ -123,7 +153,11 @@ export class MigrationPlan {
   }
 }
 
+/** Connections whose ledger tables are known to exist with every column. */
+const ensured = new WeakSet<Db>()
+
 async function ensureTables(db: Db): Promise<void> {
+  if (ensured.has(db)) return
   const t = db.dialect.types
   await db.exec(
     `CREATE TABLE IF NOT EXISTS key_value (
@@ -143,36 +177,62 @@ async function ensureTables(db: Db): Promise<void> {
        duration_ms ${t.integer} NOT NULL,
        checksum ${t.varchar(64)},
        applied_by ${t.varchar(255)},
-       note ${t.text}
+       note ${t.text},
+       bundle ${t.varchar(64)}
      )`,
   )
+  // A ledger from before bundles could own tables has no `bundle` column. It is
+  // added here, where the table is, rather than by a core migration: the ledger
+  // has to be able to record a bundle's step whatever state core is at.
+  if (!(await hasColumn(db, 'migration_history', 'bundle')))
+    await db.exec(`ALTER TABLE migration_history ADD COLUMN bundle ${t.varchar(64)}`)
+  ensured.add(db)
+}
+
+async function hasColumn(db: Db, table: string, column: string): Promise<boolean> {
+  const rows =
+    db.dialect.name === 'sqlite'
+      ? await db.query<{ name: string }>(`SELECT name FROM pragma_table_info('${table}')`)
+      : await db.query<{ name: string }>(
+          'SELECT column_name AS name FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = ?',
+          [table],
+        )
+  return rows.some((row) => row.name === column)
 }
 
-export async function readState(db: Db): Promise<string> {
+/** A chain's state: core's unless a plan says otherwise. */
+export async function readState(
+  db: Db,
+  chain: Pick<MigrationPlan, 'stateKey' | 'initialState'> = {
+    stateKey: MIGRATION_STATE_KEY,
+    initialState: INITIAL_STATE,
+  },
+): Promise<string> {
   await ensureTables(db)
   const rows = await db.query<{ value: string }>('SELECT value FROM key_value WHERE key = ?', [
-    MIGRATION_STATE_KEY,
+    chain.stateKey,
   ])
-  return rows[0]?.value ?? INITIAL_STATE
+  return rows[0]?.value ?? chain.initialState
 }
 
-async function writeState(db: Db, state: string): Promise<void> {
+async function writeState(db: Db, state: string, key = MIGRATION_STATE_KEY): Promise<void> {
   const now = db.dialect.now()
-  await db.query(`UPDATE key_value SET value = ?, update_date = ${now} WHERE key = ?`, [
-    state,
-    MIGRATION_STATE_KEY,
-  ])
-  const rows = await db.query<{ value: string }>('SELECT value FROM key_value WHERE key = ?', [
-    MIGRATION_STATE_KEY,
-  ])
+  await db.query(`UPDATE key_value SET value = ?, update_date = ${now} WHERE key = ?`, [state, key])
+  const rows = await db.query<{ value: string }>('SELECT value FROM key_value WHERE key = ?', [key])
   if (rows.length === 0) {
     await db.exec(
       `INSERT INTO key_value (key, value, update_date) VALUES (${db.dialect.placeholder(1)}, ${db.dialect.placeholder(2)}, ${now})`,
-      [MIGRATION_STATE_KEY, state],
+      [key, state],
     )
   }
 }
 
+/** Forgets a setting entirely, as a purged bundle's state is forgotten. */
+export async function deleteKeyValue(db: Db, key: string): Promise<void> {
+  await ensureTables(db)
+  await db.exec('DELETE FROM key_value WHERE key = ?', [key])
+}
+
 export interface LedgerEntry {
   name: string
   /** 'expand' | 'contract' for framework steps; 'value' for a value migration; 'upgrade' for a cut-over. */
@@ -183,6 +243,8 @@ export interface LedgerEntry {
   checksum?: string | null
   appliedBy?: string | null
   note?: string | null
+  /** The bundle whose chain this step belongs to; null for core. */
+  bundle?: string | null
 }
 
 /**
@@ -226,8 +288,8 @@ export async function ensureKeyValue(db: Db, key: string, create: () => string):
 export async function recordInLedger(db: Db, entry: LedgerEntry): Promise<void> {
   await ensureTables(db)
   await db.exec(
-    `INSERT INTO migration_history (name, kind, from_state, to_state, applied_at, duration_ms, checksum, applied_by, note)
-     VALUES (?, ?, ?, ?, ${db.dialect.now()}, ?, ?, ?, ?)`,
+    `INSERT INTO migration_history (name, kind, from_state, to_state, applied_at, duration_ms, checksum, applied_by, note, bundle)
+     VALUES (?, ?, ?, ?, ${db.dialect.now()}, ?, ?, ?, ?, ?)`,
     [
       entry.name,
       entry.kind,
@@ -237,6 +299,7 @@ export async function recordInLedger(db: Db, entry: LedgerEntry): Promise<void>
       entry.checksum ?? null,
       entry.appliedBy ?? null,
       entry.note ?? null,
+      entry.bundle ?? null,
     ],
   )
 }
@@ -248,10 +311,14 @@ export async function latestLedgerId(db: Db): Promise<number> {
   return Number(rows[0]?.n ?? 0)
 }
 
-/** How many contract steps — framework contracts and site purges — were ledgered after a row id. */
+/**
+ * How many contract steps — framework contracts and site purges — were ledgered
+ * after a row id. A bundle's contract is not counted: it removes only the
+ * bundle's own tables, which no read of core's depends on.
+ */
 export async function contractsLedgeredAfter(db: Db, afterId: number): Promise<number> {
   const rows = await db.query<{ n: number }>(
-    "SELECT COUNT(*) AS n FROM migration_history WHERE id > ? AND kind = 'contract'",
+    "SELECT COUNT(*) AS n FROM migration_history WHERE id > ? AND kind = 'contract' AND bundle IS NULL",
     [afterId],
   )
   return Number(rows[0]?.n ?? 0)
@@ -265,7 +332,7 @@ export interface LedgerRow extends LedgerEntry {
 export async function readLedger(db: Db): Promise<LedgerRow[]> {
   await ensureTables(db)
   const rows = await db.query(
-    'SELECT id, name, kind, from_state, to_state, applied_at, duration_ms, checksum, applied_by, note FROM migration_history ORDER BY id',
+    'SELECT id, name, kind, from_state, to_state, applied_at, duration_ms, checksum, applied_by, note, bundle FROM migration_history ORDER BY id',
   )
   return rows.map((row) => ({
     id: Number(row.id),
@@ -278,6 +345,7 @@ export async function readLedger(db: Db): Promise<LedgerRow[]> {
     checksum: (row.checksum as string | null) ?? null,
     appliedBy: (row.applied_by as string | null) ?? null,
     note: (row.note as string | null) ?? null,
+    bundle: (row.bundle as string | null) ?? null,
   }))
 }
 
@@ -286,22 +354,66 @@ export class UpgradeStateError extends Error {
   constructor(
     readonly databaseState: string,
     readonly codeState: string,
+    /** The bundle whose chain it is, when it is not core's. */
+    readonly bundle?: string,
+  ) {
+    super(
+      bundle
+        ? `The database holds the bundle "${bundle}"'s tables at state ${databaseState}, which this version of the bundle (its steps end at ${codeState}) does not know. ` +
+            'A newer release of the bundle wrote them; install that release, or restore the backup taken before the upgrade.'
+        : `The database is at migration state ${databaseState}, which this version of crombolo (plan ends at ${codeState}) does not know. ` +
+            'It was upgraded by a newer version; run that version, or restore the backup taken before the upgrade.',
+    )
+  }
+}
+
+/** A bundle step changed after it ran here: what is in the database is not what the code says made it. */
+export class BundleStepEditedError extends Error {
+  constructor(
+    readonly bundle: string,
+    readonly step: string,
   ) {
     super(
-      `The database is at migration state ${databaseState}, which this version of crombolo (plan ends at ${codeState}) does not know. ` +
-        'It was upgraded by a newer version; run that version, or restore the backup taken before the upgrade.',
+      `The bundle "${bundle}"'s step "${step}" is not the step that ran on this database: it was edited after it shipped. ` +
+        'A shipped step is never changed; put the change in a new step.',
     )
   }
 }
 
 /** Steps pending on this database, in order. Throws when the database is ahead of the code. */
 export async function pendingMigrations(db: Db, plan: MigrationPlan): Promise<Migration[]> {
-  const state = await readState(db)
+  const state = await readState(db, plan)
   const pending = plan.pendingFrom(state)
-  if (!pending) throw new UpgradeStateError(state, plan.finalState)
+  if (!pending) throw new UpgradeStateError(state, plan.finalState, plan.bundle)
   return pending
 }
 
+/**
+ * Refuses a bundle chain whose applied steps no longer match the code. Only the
+ * rows since the bundle was last purged count: a purge starts its chain again.
+ */
+async function verifyApplied(db: Db, plan: MigrationPlan, state: string): Promise<void> {
+  if (!plan.bundle) return
+  const applied = plan.appliedAt(state) ?? []
+  if (applied.length === 0) return
+  const rows = await db.query<{ name: string; kind: string; checksum: string | null }>(
+    'SELECT name, kind, checksum FROM migration_history WHERE bundle = ? ORDER BY id',
+    [plan.bundle],
+  )
+  const purged = rows.map((row) => row.kind).lastIndexOf('purge')
+  const ran = new Map(
+    rows
+      .slice(purged + 1)
+      .filter((row) => row.kind === 'expand' || row.kind === 'contract')
+      .map((row) => [row.name, row.checksum]),
+  )
+  for (const step of applied) {
+    const recorded = ran.get(step.name)
+    if (recorded !== undefined && recorded !== (step.checksum ?? step.name))
+      throw new BundleStepEditedError(plan.bundle, step.name)
+  }
+}
+
 export interface MigrateResult {
   from: string
   to: string
@@ -320,27 +432,30 @@ export async function migrate(
   options: MigrateOptions = {},
 ): Promise<MigrateResult> {
   return db.locks.withLock(Locks.KeyValues, async () => {
-    const from = await readState(db)
+    const from = await readState(db, plan)
     let state = from
     const applied: string[] = []
     const pending = plan.pendingFrom(state)
-    if (!pending) throw new UpgradeStateError(state, plan.finalState)
+    if (!pending) throw new UpgradeStateError(state, plan.finalState, plan.bundle)
+    await verifyApplied(db, plan, state)
     for (const next of pending) {
       const started = performance.now()
       await db.transaction(async (tx) => {
         await next.up(tx)
+        await next.backfill?.(tx)
       })
       state = next.to
-      await writeState(db, state)
+      await writeState(db, state, plan.stateKey)
       await recordInLedger(db, {
         name: next.name,
         kind: next.kind ?? 'expand',
         fromState: next.from,
         toState: next.to,
         durationMs: Math.round(performance.now() - started),
-        checksum: next.name,
+        checksum: next.checksum ?? next.name,
         appliedBy: options.by ?? null,
         note: next.release ? `release ${next.release}` : null,
+        bundle: plan.bundle ?? null,
       })
       applied.push(next.name)
     }
@@ -351,7 +466,7 @@ export async function migrate(
 /** A fresh install stamps the final state so no migrations then run. */
 export async function stampFinalState(db: Db, plan: MigrationPlan): Promise<void> {
   await ensureTables(db)
-  await writeState(db, plan.finalState)
+  await writeState(db, plan.finalState, plan.stateKey)
 }
 
 // ---------------------------------------------------------------- the plan
@@ -421,6 +536,7 @@ export async function planUpgrade(db: Db, plan: MigrationPlan): Promise<PlannedS
     try {
       await migration.up(recorder)
       step.statements = recorder.statements
+      if (migration.backfill) step.unplannable = 'backfills data, which only running it can show'
     } catch (error) {
       if (error instanceof UnplannableError) step.unplannable = error.message
       else throw error

package/src/pending.ts

@@ -1,7 +1,7 @@
 /**
  * An element is pending on a node when the deployment that created it is newer
  * than the node, or its file says `since` a version the node has not reached.
- * The one place the rule lives. docs/09-schema-as-code.md, "since".
+ * The one place the rule lives. docs/schema-as-code.md, "since".
  */
 import { compareStates, compareVersions, type NodeSchemaState } from './schema-state.ts'
 

package/src/repositories/bundles.ts

@@ -1,6 +1,6 @@
 /**
  * The bundle definitions: what a bundle would contain, not a built bundle.
- * `docs/17-bundles.md`.
+ * `docs/bundles.md`.
  *
  * The selection lists travel as JSON text in single columns. A malformed list
  * reads back as empty rather than throwing: a definition whose row was edited
@@ -26,12 +26,21 @@ export interface Bundle {
   scripts: string[]
   languages: string[]
   dictionaryItems: string[]
+  /**
+   * The npm package the bundle is built as. Not in Umbraco's definition, so the
+   * contract never writes these; null until someone sets them.
+   */
+  packageName: string | null
+  packageVersion: string | null
   createDate: Date
   updateDate: Date
 }
 
 /** A definition to store; `id` is assigned when it is new, the dates always. */
-export type BundleInput = Omit<Bundle, 'id' | 'createDate' | 'updateDate'>
+export type BundleInput = Omit<
+  Bundle,
+  'id' | 'createDate' | 'updateDate' | 'packageName' | 'packageVersion'
+>
 
 interface Row {
   id: string
@@ -49,6 +58,8 @@ interface Row {
   scripts: string
   languages: string
   dictionary_items: string
+  package_name: string | null
+  package_version: string | null
   create_date: unknown
   update_date: unknown
 }
@@ -56,7 +67,8 @@ interface Row {
 const SELECT = `SELECT id, name, content_node_id, content_load_child_nodes,
                        media_load_child_nodes, media_ids, element_ids, content_types,
                        media_types, data_types, components, stylesheets,
-                       scripts, languages, dictionary_items, create_date, update_date
+                       scripts, languages, dictionary_items, package_name, package_version,
+                       create_date, update_date
                   FROM bundle`
 
 const list = (value: string | null): string[] => {
@@ -87,6 +99,8 @@ const hydrate = (row: Row): Bundle => ({
   scripts: list(row.scripts),
   languages: list(row.languages),
   dictionaryItems: list(row.dictionary_items),
+  packageName: row.package_name ?? null,
+  packageVersion: row.package_version ?? null,
   createDate: DbDate.fromDb(row.create_date) ?? new Date(0),
   updateDate: DbDate.fromDb(row.update_date) ?? new Date(0),
 })
@@ -152,7 +166,14 @@ export class BundleRepository {
         DbDate.toDb(now),
       ],
     )
-    return { ...input, id, createDate: now, updateDate: now }
+    return {
+      ...input,
+      id,
+      packageName: null,
+      packageVersion: null,
+      createDate: now,
+      updateDate: now,
+    }
   }
 
   async update(id: string, input: BundleInput): Promise<void> {
@@ -185,6 +206,17 @@ export class BundleRepository {
     )
   }
 
+  /** The npm package a definition is built as; null clears a value back to its default. */
+  async setPackage(
+    id: string,
+    pkg: { name: string | null; version: string | null },
+  ): Promise<void> {
+    await this.#db.exec(
+      'UPDATE bundle SET package_name = ?, package_version = ?, update_date = ? WHERE id = ?',
+      [pkg.name, pkg.version, DbDate.toDb(new Date()), id],
+    )
+  }
+
   async delete(id: string): Promise<void> {
     await this.#db.exec('DELETE FROM bundle WHERE id = ?', [id])
   }

package/src/repositories/documents.ts

@@ -5,7 +5,7 @@
  * tagged with the event that wrote it and the schema state the writer was at.
  * `content_version` rows are events (save | publish | rollback | migrate).
  * Publish is an event and a pointer, not a copy; rollback appends the old
- * values under a new event. See docs/02-data-model.md.
+ * values under a new event. See docs/data-model.md.
  */
 import {
   type DocumentAggregate,

package/src/repositories/form-entries.ts

@@ -1,5 +1,5 @@
 /**
- * Form entries: what visitors submitted. `docs/18-forms.md`.
+ * Form entries: what visitors submitted. `docs/forms.md`.
  *
  * Keyed by the form's UUID rather than a foreign key, because the definition is
  * a file. An entry outlives its definition on purpose.

package/src/repositories/form-workflows.ts

@@ -1,5 +1,5 @@
 /**
- * The form workflow queue. `docs/18-forms.md`.
+ * The form workflow queue. `docs/forms.md`.
  *
  * Claimed with `UPDATE … WHERE state = 'pending' … RETURNING`, which is atomic
  * on both dialects: on a multi-node Postgres site every node polls, and exactly

package/src/repositories/transfer-runs.ts

@@ -24,6 +24,9 @@ export interface TransferRun {
   id: string
   bundleId: string
   bundleLabel: string | null
+  /** The npm package the content arrived in, and its version. */
+  packageName: string | null
+  packageVersion: string | null
   direction: TransferDirection
   revertsRunId: string | null
   schemaStateId: number
@@ -57,12 +60,14 @@ export class TransferRunRepository {
   async start(run: Omit<TransferRun, 'finishedAt' | 'status'>): Promise<void> {
     await this.#db.exec(
       `INSERT INTO content_transfer_run
-         (id, bundle_id, bundle_label, direction, reverts_run_id, schema_state_id, started_at, applied_by, node_count, status)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'applied')`,
+         (id, bundle_id, bundle_label, package_name, package_version, direction, reverts_run_id, schema_state_id, started_at, applied_by, node_count, status)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'applied')`,
       [
         run.id,
         run.bundleId,
         run.bundleLabel,
+        run.packageName,
+        run.packageVersion,
         run.direction,
         run.revertsRunId,
         run.schemaStateId,
@@ -121,6 +126,17 @@ export class TransferRunRepository {
     return rows[0] ? mapRun(rows[0]) : undefined
   }
 
+  /** The latest standing import of a package's content, whichever version brought it. */
+  async appliedForPackage(packageName: string): Promise<TransferRun | undefined> {
+    const rows = await this.#db.query(
+      `SELECT * FROM content_transfer_run
+         WHERE package_name = ? AND direction = 'import' AND status = 'applied'
+         ORDER BY started_at DESC, id DESC LIMIT 1`,
+      [packageName],
+    )
+    return rows[0] ? mapRun(rows[0]) : undefined
+  }
+
   /** Runs, newest first. */
   async recent(limit = 20): Promise<TransferRun[]> {
     const rows = await this.#db.query(
@@ -164,6 +180,8 @@ function mapRun(row: Record<string, unknown>): TransferRun {
     id: String(row.id),
     bundleId: String(row.bundle_id),
     bundleLabel: (row.bundle_label as string | null) ?? null,
+    packageName: (row.package_name as string | null) ?? null,
+    packageVersion: (row.package_version as string | null) ?? null,
     direction: String(row.direction) as TransferDirection,
     revertsRunId: (row.reverts_run_id as string | null) ?? null,
     schemaStateId: Number(row.schema_state_id),

package/src/schema/bundle-components.ts

@@ -1,7 +1,7 @@
 /**
  * Migration 028 — a bundle's `templates` and `partial_views` become `components`.
  *
- * There is one root and one kind of file on disk now (`docs/05-rendering.md`),
+ * There is one root and one kind of file on disk now (`docs/rendering.md`),
  * so a bundle definition that still kept two lists was recording a distinction
  * the rest of the system no longer makes. The two are merged rather than one
  * dropped: both held component aliases, and which tree the backoffice picked

package/src/schema/bundle-package.ts

@@ -0,0 +1,27 @@
+/**
+ * Migration 029 — a created bundle records the npm package it is written as.
+ *
+ * Every bundle is an npm package (`docs/bundles.md`), so the Created view's
+ * download needs a package name and version. Umbraco's package definition has
+ * neither, so they live here, beside the columns the contract does name. Both
+ * are nullable: an unset name or version is derived when the bundle is built.
+ */
+import type { Db } from '../database.ts'
+import type { Migration } from '../migrations.ts'
+import { schemaOps } from '../schema-ops.ts'
+import { STATE_BUNDLE_COMPONENTS } from './bundle-components.ts'
+
+export const STATE_BUNDLE_PACKAGE = '{6f1d4a8e-0029-4c5e-9a17-3d8b2e6f4c29}'
+
+export const bundlePackageMigration: Migration = {
+  from: STATE_BUNDLE_COMPONENTS,
+  to: STATE_BUNDLE_PACKAGE,
+  name: 'AddBundlePackageNameAndVersion',
+  kind: 'expand',
+  release: '0.10.0',
+  async up(db: Db) {
+    const ops = schemaOps(db)
+    await ops.addColumn('bundle', 'package_name', db.dialect.types.varchar(214))
+    await ops.addColumn('bundle', 'package_version', db.dialect.types.varchar(64))
+  },
+}

package/src/schema/bundles-rename.ts

@@ -3,7 +3,7 @@
  *
  * The table was named after Umbraco's `umbracoCreatedPackageSchema`, which it
  * mirrors column for column. What it holds is a bundle definition
- * (`docs/17-bundles.md`), and the backoffice now says so, so the table does too.
+ * (`docs/bundles.md`), and the backoffice now says so, so the table does too.
  *
  * A rename rather than an edit to migration 022: 022 has already run on every
  * database that exists, and rewriting it would leave those sites with a table

package/src/schema/content.ts

@@ -2,7 +2,7 @@
  * Migration 002 — the content schema.
  *
  * `node` is the universal polymorphic tree; every other table here is a facet of
- * it. See docs/02-data-model.md for the model and why it is kept.
+ * it. See docs/data-model.md for the model and why it is kept.
  */
 import type { Db } from '../database.ts'
 import type { Migration } from '../migrations.ts'
@@ -164,7 +164,7 @@ export const contentMigration: Migration = {
        )`,
     )
 
-    // ---- documents and versions (Phase 4 uses these) ----
+    // ---- documents and versions (story 005 uses these) ----
 
     await db.exec(
       `CREATE TABLE content (

package/src/schema/created-packages.ts

@@ -2,7 +2,7 @@
  * Migration 022 — the created-package definitions the Packages section builds.
  *
  * A definition, never an artifact: the zip is built when it is downloaded
- * (`docs/17-bundles.md`), so there are no bytes here to go stale when a
+ * (`docs/bundles.md`), so there are no bytes here to go stale when a
  * content type the package carries is edited afterwards.
  *
  * The selection lists are JSON text rather than a row each. They are read and

package/src/schema/form-permissions.ts

@@ -1,6 +1,6 @@
 /**
  * Migration 025 — the form permission verbs, for databases seeded before they
- * existed. `docs/18-forms.md`.
+ * existed. `docs/forms.md`.
  *
  * The same shape as migration 007: granting what the seed now grants, so an
  * upgraded site does not have a Forms section nobody can open. Idempotent, and

package/src/schema/form-workflows.ts

@@ -1,5 +1,5 @@
 /**
- * Migration 024 — the queue a form's workflows run from. `docs/18-forms.md`.
+ * Migration 024 — the queue a form's workflows run from. `docs/forms.md`.
  *
  * A submission is stored and *then* its workflows run, so a mail server being
  * down never loses an entry. That means a row per workflow per submission,

package/src/schema/forms.ts

@@ -1,5 +1,5 @@
 /**
- * Migration 023 — form entries. `docs/18-forms.md`.
+ * Migration 023 — form entries. `docs/forms.md`.
  *
  * The definition is a file, so there is no form table and nothing to point at:
  * an entry carries `form_key`, the UUID from `schema/forms/*.toml`, and keeps

package/src/schema/identity.ts

@@ -1,7 +1,7 @@
 /**
  * Migration 001 — back-office identity.
  *
- * Table and column names follow docs/02-data-model.md: Umbraco's relational
+ * Table and column names follow docs/data-model.md: Umbraco's relational
  * model with snake_case names. `user` is reserved in Postgres, hence
  * `user_account`.
  */

package/src/schema/plan.ts

@@ -14,6 +14,7 @@
 import { MigrationPlan } from '../migrations.ts'
 import { assistantMigration } from './assistant.ts'
 import { bundleComponentsMigration } from './bundle-components.ts'
+import { bundlePackageMigration } from './bundle-package.ts'
 import { bundlesRenameMigration } from './bundles-rename.ts'
 import { changeReportMigration } from './change-report.ts'
 import { clientIdPrefixMigration } from './client-id-prefix.ts'
@@ -36,6 +37,7 @@ import { redirectsMigration } from './redirects.ts'
 import { richTextUiMigration } from './rich-text-ui.ts'
 import { serverRoleMigration } from './server-role.ts'
 import { sinceVersionMigration } from './since-version.ts'
+import { transferRunPackageMigration } from './transfer-run-package.ts'
 import { transferRunsMigration } from './transfer-runs.ts'
 import { upgradeReportMigration } from './upgrade-report.ts'
 import { usersLocalisationMigration } from './users-localisation.ts'
@@ -70,4 +72,6 @@ export const cromboloPlan = new MigrationPlan([
   formPermissionPrefixMigration,
   bundlesRenameMigration,
   bundleComponentsMigration,
+  bundlePackageMigration,
+  transferRunPackageMigration,
 ])