@owlmeans/planning-postgres 0.1.18-rc.0

package/src/store/index.ts

@@ -0,0 +1,237 @@
+import { uuid } from '@owlmeans/basic-ids'
+import { CommitState, TransitionAction } from '@owlmeans/planning'
+import type { CommitStatus, Unsubscribe } from '@owlmeans/planning'
+import type { PostgresResource } from '@owlmeans/postgres-resource'
+import type { ResourceRecord } from '@owlmeans/resource'
+import { makeCommitHub } from '@owlmeans/server-planning/store'
+import type { CommitHub, CommitListener } from '@owlmeans/server-planning/store'
+import type { Pool } from 'pg'
+import {
+  DEFAULT_PLANNING_POSTGRES_LIMITS, PLANNING_POSTGRES_STORE, PLANNING_RESOURCE_FILES, RES_PLANNING_CARD,
+  RES_PLANNING_LINK, RES_PLANNING_SCHEMA, RES_PLANNING_TRANSITION,
+} from '../consts.js'
+import { PlanningPostgresError } from '../errors.js'
+import { planningIndexName } from '../resource.js'
+import { poolRunner } from '../sql.js'
+import type { PlanningTables, SqlContext } from '../sql.js'
+import type {
+  PlanningCardResource, PlanningLinkResource, PlanningPostgresAliases, PlanningPostgresLimits,
+  PlanningSchemaResource, PlanningTransitionResource, PostgresPlanningStore, PostgresPlanningStoreOptions,
+} from '../types.js'
+import { makePlanningBus } from './bus.js'
+import { makeCardPort, readCard } from './cards.js'
+import { makeFoldEngine } from './fold.js'
+import { makeLinkPort } from './links.js'
+import { makeSchemaPort } from './schemas.js'
+import { makeSpecPort } from './specs.js'
+import { makeTransitionPort, readTransition } from './transitions.js'
+
+export * from './bus.js'
+export * from './cards.js'
+export * from './fold.js'
+export * from './links.js'
+export * from './schemas.js'
+export * from './specs.js'
+export * from './transitions.js'
+
+const isoNow = (): string => new Date().toISOString()
+
+/** The aliases a store resolves, each defaulting to the package's own resource alias. */
+export const planningPostgresAliases = (aliases?: Partial<PlanningPostgresAliases>): PlanningPostgresAliases => ({
+  card: aliases?.card ?? RES_PLANNING_CARD,
+  transition: aliases?.transition ?? RES_PLANNING_TRANSITION,
+  link: aliases?.link ?? RES_PLANNING_LINK,
+  schema: aliases?.schema ?? RES_PLANNING_SCHEMA,
+})
+
+/**
+ * The Postgres `PlanningStore`: four tables, an inline fold (one transaction per card under its
+ * advisory lock), the commit hub fed by the fold and by a LISTEN/NOTIFY bus, and the data-defined
+ * schema port.
+ *
+ * Nothing is resolved at construction: the resources are looked up on the context at the first
+ * call — which also runs one `recover()` in the background — so the store can be handed to the
+ * planning service before the context initializes. A resource the context does not have is refused
+ * with the file a target adds for it.
+ */
+export const makePostgresPlanningStore = (opts: PostgresPlanningStoreOptions): PostgresPlanningStore => {
+  const aliases = planningPostgresAliases(opts.aliases)
+  const limits: PlanningPostgresLimits = { ...DEFAULT_PLANNING_POSTGRES_LIMITS, ...(opts.limits ?? {}) }
+  const ids = opts.ids ?? uuid
+  const now = opts.now ?? isoNow
+  const processId = uuid()
+  let committed: CommitListener | undefined
+  let closed = false
+
+  const resourceOf = <R extends PostgresResource<ResourceRecord>>(kind: keyof PlanningPostgresAliases) => (): R => {
+    const context = opts.context()
+    const alias = aliases[kind]
+    if (context == null) {
+      throw new PlanningPostgresError(`context-missing:${alias}`)
+    }
+    if (!context.hasResource(alias)) {
+      throw new PlanningPostgresError(`resource-missing:${alias}: add ${PLANNING_RESOURCE_FILES[kind]}`)
+    }
+    return context.resource<R>(alias)
+  }
+  const resources = {
+    card: resourceOf<PlanningCardResource>('card'),
+    transition: resourceOf<PlanningTransitionResource>('transition'),
+    link: resourceOf<PlanningLinkResource>('link'),
+    schema: resourceOf<PlanningSchemaResource>('schema'),
+  }
+
+  let ready: Promise<PlanningTables> | undefined
+  let recovered = false
+  const tables = (): Promise<PlanningTables> => {
+    ready ??= (async () => {
+      const resolved = [resources.card(), resources.transition(), resources.link(), resources.schema()]
+      // A resource registered after the context initialized is initialized here, once.
+      await Promise.all(resolved.map(async resource => { await resource.queryOne('SELECT 1') }))
+      const [card, transition, link, schema] = resolved.map(resource => resource.table)
+      return { card, transition, link, schema }
+    })()
+    const pending = ready
+    pending.then(() => {
+      if (!recovered && !closed) {
+        recovered = true
+        void engine.recover().catch(error => {
+          if (!closed) {
+            console.error('planning-postgres: recovery on first use failed:', error)
+          }
+        })
+      }
+    }, () => {
+      // A failed resolution (a missing resource) is asked again by the next call.
+      if (ready === pending) {
+        ready = undefined
+      }
+    })
+    return pending
+  }
+
+  const pool = async (): Promise<Pool> => (await resources.card().db()).pool
+  const sql = async (): Promise<SqlContext> => ({ runner: poolRunner(await pool()), tables: await tables() })
+
+  const schemaWatchers = new Set<(entityId: string) => void>()
+  const touched = (entityId: string): void => {
+    for (const watcher of [...schemaWatchers]) {
+      try {
+        watcher(entityId)
+      } catch (error) {
+        console.error('planning-postgres: schema watcher failed:', error)
+      }
+    }
+  }
+
+  const bus = makePlanningBus({
+    enabled: opts.bus !== false,
+    processId,
+    table: async () => (await tables()).transition.qualified,
+    pool,
+  })
+
+  const statusOf = async (transition: string): Promise<CommitStatus | null> => {
+    const context = await sql()
+    const row = await readTransition(context, transition)
+    if (row == null) {
+      return null
+    }
+    const status: CommitStatus = { transition, state: row.commit.state }
+    if (row.commit.at != null) {
+      status.at = row.commit.at
+    }
+    if (row.commit.error != null) {
+      status.error = row.commit.error
+    }
+    if (row.commit.state === CommitState.Pending && Date.now() - Date.parse(row.at) > limits.healAfterMs) {
+      // Every waiter is a healer: a commit left pending by a lost fold is folded again.
+      engine.heal(row.card)
+    }
+    if (row.commit.state === CommitState.Committed) {
+      status.card = row.action === TransitionAction.Delete ? null : await readCard(context, row.card, row.entityId)
+    }
+    return status
+  }
+
+  const hub = makeCommitHub({ status: statusOf })
+  bus.onCommit(async event => { await hub.publish(event) })
+  bus.onSchema(touched)
+
+  const engine = makeFoldEngine({
+    pool,
+    tables,
+    limits,
+    ids,
+    now,
+    bus,
+    hub,
+    committed: () => committed,
+    schemasTouched: touched,
+    closed: () => closed,
+  })
+
+  const commits: CommitHub = {
+    ...hub,
+    subscribe: (listener, filter) => {
+      bus.ensure()
+      return hub.subscribe(listener, filter)
+    },
+    wait: async (transition, waitOpts) => {
+      bus.ensure()
+      return await hub.wait(transition, waitOpts)
+    },
+  }
+
+  const indexes = async () => {
+    await tables()
+    return {
+      cardSeq: planningIndexName(aliases.transition, 'card_seq'),
+      entityKey: planningIndexName(aliases.transition, 'entity_key'),
+    }
+  }
+
+  const store: PostgresPlanningStore = {
+    alias: PLANNING_POSTGRES_STORE,
+    capabilities: { transitions: true, sync: true, purge: true, revisions: true },
+    newId: ids,
+    transitions: makeTransitionPort({ sql, resource: resources.transition, ids, now, indexes }),
+    cards: makeCardPort({
+      sql,
+      resource: resources.card,
+      project: async card => { await engine.fold(card) },
+      purge: engine.purge,
+    }),
+    specs: makeSpecPort({ sql, resource: resources.card }),
+    links: makeLinkPort({ sql, resource: resources.link, ids }),
+    commits,
+    schemas: makeSchemaPort({
+      sql,
+      pool,
+      tables,
+      bus,
+      ids,
+      now,
+      touched,
+      watch: listener => {
+        bus.ensure()
+        schemaWatchers.add(listener)
+        const unsubscribe: Unsubscribe = () => { schemaWatchers.delete(listener) }
+        return unsubscribe
+      },
+    }),
+
+    bind: listener => { committed = listener },
+
+    fold: async cardId => await engine.fold(cardId),
+
+    recover: async recoverOpts => await engine.recover(recoverOpts),
+
+    close: async () => {
+      closed = true
+      await bus.close()
+    },
+  }
+
+  return store
+}

package/src/store/links.ts

@@ -0,0 +1,77 @@
+import { PlanningError } from '@owlmeans/planning'
+import type { Relationship, RelationshipStore, RelationshipWhere } from '@owlmeans/planning'
+import type { Criteria, ListResult } from '@owlmeans/resource'
+import { cleanRecord, col, insertOf, recordOf, whereOf } from '../sql.js'
+import type { SqlContext } from '../sql.js'
+import type { PlanningLinkResource } from '../types.js'
+
+const clean = <T extends object>(record: T): T =>
+  Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
+
+export const linkCriteria = (where: RelationshipWhere): Criteria<Relationship> => clean({
+  entityId: where.entityId,
+  id: where.id,
+  from: where.from,
+  to: where.to,
+  type: where.type,
+  project: where.project,
+}) as Criteria<Relationship>
+
+const fixed = (where: RelationshipWhere) => ({
+  entityId: where.entityId, id: where.id, from: where.from, to: where.to, type: where.type, project: where.project,
+})
+
+/** Edges by fixed fields — this package's own statement, so it runs inside a fold's transaction. */
+export const listLinks = async (sql: SqlContext, where: RelationshipWhere): Promise<ListResult<Relationship>> => {
+  const spec = sql.tables.link
+  const condition = whereOf(spec, fixed(where))
+  const rows = await sql.runner.query(
+    `SELECT * FROM ${spec.qualified} WHERE ${condition.text} ORDER BY ${col(spec, 'createdAt')}, ${col(spec, 'id')}`, condition.params
+  )
+  const items = rows.map(row => recordOf<Relationship>(row, spec))
+  return { items, total: items.length }
+}
+
+/** One edge per `(from, to, type)`: an existing one is answered as it is. */
+export const putLink = async (sql: SqlContext, link: Relationship, id: () => string): Promise<Relationship> => {
+  const spec = sql.tables.link
+  const statement = insertOf(spec, { ...link, id: link.id ?? id() } as unknown as Record<string, unknown>, {
+    tail: `ON CONFLICT (${col(spec, 'from')}, ${col(spec, 'to')}, ${col(spec, 'type')}) DO NOTHING RETURNING *`,
+  })
+  const inserted = await sql.runner.query(statement.text, statement.params)
+  if (inserted[0] != null) {
+    return recordOf<Relationship>(inserted[0], spec)
+  }
+  const existing = await listLinks(sql, { entityId: link.entityId, from: link.from, to: link.to, type: link.type })
+  return existing.items[0] ?? link
+}
+
+/** @throws {PlanningError} `links:drop-empty` for a where naming nothing but the organization */
+export const dropLinks = async (sql: SqlContext, where: RelationshipWhere): Promise<number> => {
+  if (where.id == null && where.from == null && where.to == null && where.type == null && where.project == null) {
+    throw new PlanningError('links:drop-empty')
+  }
+  const spec = sql.tables.link
+  const condition = whereOf(spec, fixed(where))
+  return (await sql.runner.query(
+    `DELETE FROM ${spec.qualified} WHERE ${condition.text} RETURNING ${col(spec, 'id')}`, condition.params
+  )).length
+}
+
+export interface LinkPortDeps {
+  sql: () => Promise<SqlContext>
+  resource: () => PlanningLinkResource
+  ids: () => string
+}
+
+export const makeLinkPort = (deps: LinkPortDeps): RelationshipStore => ({
+  list: async (where, opts) => {
+    await deps.sql()
+    const listed = await deps.resource().list(linkCriteria(where), opts)
+    return { ...listed, items: listed.items.map(item => cleanRecord(item)) }
+  },
+
+  put: async link => await putLink(await deps.sql(), link, deps.ids),
+
+  drop: async where => await dropLinks(await deps.sql(), where),
+})

package/src/store/schemas.ts

@@ -0,0 +1,174 @@
+import { SchemaConflict } from '@owlmeans/planning'
+import type { SchemaStore, ScopedSchemaRecord, Unsubscribe } from '@owlmeans/planning'
+import type { Pool } from 'pg'
+import { SCHEMA_HEAD_KEY, SCHEMA_HEAD_KIND } from '../consts.js'
+import { clientRunner, col, insertOf, recordOf } from '../sql.js'
+import type { PlanningTables, SqlContext, SqlRunner } from '../sql.js'
+import type { PlanningBus } from './bus.js'
+
+/** The scope's uniqueness expression — the one the `…_scope` index is built on. */
+const scopeTarget = (sql: SqlContext): string => {
+  const spec = sql.tables.schema
+  return `(${col(spec, 'entityId')}, COALESCE(${col(spec, 'project')}, ''), ${col(spec, 'kind')}, ${col(spec, 'key')})`
+}
+
+/**
+ * Bump an organization's schema revision — its private `head` row, created at 1 — and answer the
+ * new value. Runs inside the write's own transaction, so the revision moves exactly when it commits.
+ */
+export const bumpRevision = async (sql: SqlContext, entityId: string, at: string, id: () => string): Promise<number> => {
+  const spec = sql.tables.schema
+  const statement = insertOf(spec, {
+    id: id(), entityId, kind: SCHEMA_HEAD_KIND, key: SCHEMA_HEAD_KEY, version: 1, rev: 1, definition: {}, createdAt: at,
+  }, {
+    as: 'existing',
+    tail: `ON CONFLICT ${scopeTarget(sql)} DO UPDATE SET ${col(spec, 'rev')} = COALESCE(existing.${col(spec, 'rev')}, 0) + 1,`
+      + ` ${col(spec, 'updatedAt')} = EXCLUDED.${col(spec, 'createdAt')} RETURNING ${col(spec, 'rev')} AS rev`,
+  })
+  const rows = await sql.runner.query<{ rev: number }>(statement.text, statement.params)
+  return Number(rows[0]?.rev ?? 0)
+}
+
+/** Remove the layers of the given projects inside a transaction; answers how many records went. */
+export const purgeSchemaLayers = async (sql: SqlContext, entityId: string, projects: readonly string[]): Promise<number> => {
+  if (projects.length === 0) {
+    return 0
+  }
+  const spec = sql.tables.schema
+  return (await sql.runner.query(
+    `DELETE FROM ${spec.qualified} WHERE ${col(spec, 'entityId')} = $1 AND ${col(spec, 'project')} = ANY($2) RETURNING ${col(spec, 'id')}`,
+    [entityId, [...projects]]
+  )).length
+}
+
+export interface SchemaPortDeps {
+  sql: () => Promise<SqlContext>
+  pool: () => Promise<Pool>
+  tables: () => Promise<PlanningTables>
+  bus: PlanningBus
+  ids: () => string
+  now: () => string
+  /** Every local watcher, told after a write of this process commits. */
+  touched: (entityId: string) => void
+  watch: (listener: (entityId: string) => void) => Unsubscribe
+}
+
+/**
+ * The data-defined schema port over `planning-schema`.
+ *
+ * `put` is one transaction: bump the organization's revision row, write the record under a
+ * compare-and-set on `version` (an INSERT that must not conflict for version 1, an UPDATE guarded
+ * on `version - 1` after), NOTIFY a schema frame. `revision` reads the head row — one primary read,
+ * so every lookup of a resolved layer sees a write committed anywhere.
+ */
+export const makeSchemaPort = (deps: SchemaPortDeps): SchemaStore => {
+  const transaction = async <R>(run: (sql: SqlContext) => Promise<R>): Promise<R> => {
+    const client = await (await deps.pool()).connect()
+    const tables = await deps.tables()
+    const runner: SqlRunner = clientRunner(client)
+    try {
+      await client.query('BEGIN')
+      const result = await run({ runner, tables })
+      await client.query('COMMIT')
+      return result
+    } catch (error) {
+      await client.query('ROLLBACK').catch(() => undefined)
+      throw error
+    } finally {
+      client.release()
+    }
+  }
+
+  return {
+    list: async where => {
+      const sql = await deps.sql()
+      const spec = sql.tables.schema
+      const clauses = [`${col(spec, 'entityId')} = $1`, `${col(spec, 'kind')} <> '${SCHEMA_HEAD_KIND}'`]
+      const params: unknown[] = [where.entityId]
+      if (where.project === null) {
+        clauses.push(`${col(spec, 'project')} IS NULL`)
+      } else if (where.project !== undefined) {
+        params.push(where.project)
+        clauses.push(`${col(spec, 'project')} = $${params.length}`)
+      }
+      if (where.kind != null) {
+        params.push(where.kind)
+        clauses.push(`${col(spec, 'kind')} = $${params.length}`)
+      }
+      if (where.key != null) {
+        params.push(Array.isArray(where.key) ? where.key : [where.key])
+        clauses.push(`${col(spec, 'key')} = ANY($${params.length})`)
+      }
+      if (where.retired != null) {
+        clauses.push(where.retired ? `${col(spec, 'retired')} IS TRUE` : `${col(spec, 'retired')} IS NOT TRUE`)
+      }
+      const rows = await sql.runner.query(
+        `SELECT * FROM ${spec.qualified} WHERE ${clauses.join(' AND ')}`
+        + ` ORDER BY ${col(spec, 'kind')}, ${col(spec, 'key')}, ${col(spec, 'project')} NULLS FIRST`, params
+      )
+      return rows.map(row => recordOf<ScopedSchemaRecord>(row, spec))
+    },
+
+    put: async record => {
+      const written = await transaction(async sql => {
+        const spec = sql.tables.schema
+        const rev = await bumpRevision(sql, record.entityId, deps.now(), deps.ids)
+        const values = { ...record, id: record.id ?? deps.ids(), rev, retired: record.retired === true ? true : undefined }
+        let rows: Record<string, unknown>[]
+        if (record.version === 1) {
+          const insert = insertOf(spec, values as unknown as Record<string, unknown>, {
+            tail: `ON CONFLICT ${scopeTarget(sql)} DO NOTHING RETURNING *`,
+          })
+          rows = await sql.runner.query(insert.text, insert.params)
+        } else {
+          rows = await sql.runner.query(
+            `UPDATE ${spec.qualified} SET ${col(spec, 'version')} = $5, ${col(spec, 'definition')} = $6::jsonb,`
+            + ` ${col(spec, 'retired')} = $7, ${col(spec, 'rev')} = $8, ${col(spec, 'updatedAt')} = $9, ${col(spec, 'by')} = $10::jsonb`
+            + ` WHERE ${col(spec, 'entityId')} = $1 AND COALESCE(${col(spec, 'project')}, '') = $2 AND ${col(spec, 'kind')} = $3`
+            + ` AND ${col(spec, 'key')} = $4 AND ${col(spec, 'version')} = $5 - 1 RETURNING *`,
+            [
+              record.entityId, record.project ?? '', record.kind, record.key, record.version,
+              JSON.stringify(record.definition), record.retired === true ? true : null, rev,
+              record.updatedAt ?? deps.now(), record.by != null ? JSON.stringify(record.by) : null,
+            ]
+          )
+        }
+        if (rows[0] == null) {
+          throw new SchemaConflict(`${record.kind}:${record.key}:version:${record.version}`)
+        }
+        await deps.bus.notify(sql.runner, { t: 's', e: record.entityId })
+        return recordOf<ScopedSchemaRecord>(rows[0], spec)
+      })
+      deps.touched(record.entityId)
+      return written
+    },
+
+    purge: async where => {
+      const count = await transaction(async sql => {
+        const purged = await purgeSchemaLayers(sql, where.entityId, [where.project])
+        if (purged > 0) {
+          await bumpRevision(sql, where.entityId, deps.now(), deps.ids)
+          await deps.bus.notify(sql.runner, { t: 's', e: where.entityId })
+        }
+        return purged
+      })
+      if (count > 0) {
+        deps.touched(where.entityId)
+      }
+      return count
+    },
+
+    revision: async entityId => {
+      const sql = await deps.sql()
+      const spec = sql.tables.schema
+      const rows = await sql.runner.query<{ rev: number | null }>(
+        `SELECT ${col(spec, 'rev')} AS rev FROM ${spec.qualified} WHERE ${col(spec, 'entityId')} = $1`
+        + ` AND ${col(spec, 'project')} IS NULL AND ${col(spec, 'kind')} = '${SCHEMA_HEAD_KIND}' AND ${col(spec, 'key')} = '${SCHEMA_HEAD_KEY}'`,
+        [entityId]
+      )
+      return Number(rows[0]?.rev ?? 0)
+    },
+
+    watch: listener => deps.watch(listener),
+  }
+}

package/src/store/specs.ts

@@ -0,0 +1,72 @@
+import { listOptionsOf, specCriteriaOf, WorkcardKind } from '@owlmeans/planning'
+import type { Specification, SpecificationStore } from '@owlmeans/planning'
+import { applyQuery } from '@owlmeans/resource'
+import type { Criteria } from '@owlmeans/resource'
+import { revisionsFromLog } from '@owlmeans/server-planning/store'
+import { cleanRecord, col, recordOf } from '../sql.js'
+import type { SqlContext } from '../sql.js'
+import type { PlanningCardRecord, PlanningCardResource } from '../types.js'
+import { CARD_PRIVATE } from './cards.js'
+import { listTransitions } from './transitions.js'
+
+/** The current document of a slot is the highest revision, then the most recently updated. */
+const currentOrder = (sql: SqlContext): string => {
+  const spec = sql.tables.card
+  return `COALESCE(${col(spec, 'revision')}, 0) DESC, COALESCE(${col(spec, 'updatedAt')}, ${col(spec, 'createdAt')}) DESC, ${col(spec, 'id')}`
+}
+
+const specOf = (row: Record<string, unknown>, sql: SqlContext): Specification =>
+  cleanRecord(recordOf<PlanningCardRecord>(row, sql.tables.card), CARD_PRIVATE) as unknown as Specification
+
+export interface SpecPortDeps {
+  sql: () => Promise<SqlContext>
+  resource: () => PlanningCardResource
+}
+
+/** Specifications are rows of the card table (`kind: 'specification'`), read per parent and slot. */
+export const makeSpecPort = (deps: SpecPortDeps): SpecificationStore => ({
+  current: async (parent, category, entityId) => {
+    const sql = await deps.sql()
+    const spec = sql.tables.card
+    const rows = await sql.runner.query(
+      `SELECT * FROM ${spec.qualified} WHERE ${col(spec, 'entityId')} = $1 AND ${col(spec, 'kind')} = $2`
+      + ` AND ${col(spec, 'parent')} = $3 AND ${col(spec, 'category')} = $4 ORDER BY ${currentOrder(sql)} LIMIT 1`,
+      [entityId, WorkcardKind.Specification, parent, category]
+    )
+    return rows[0] == null ? null : specOf(rows[0], sql)
+  },
+
+  list: async (parent, entityId, query) => {
+    const sql = await deps.sql()
+    if (query?.all === true) {
+      const listed = await deps.resource().list(
+        specCriteriaOf(parent, query, { entityId }) as unknown as Criteria<PlanningCardRecord>, listOptionsOf(query) as never
+      )
+      return { ...listed, items: listed.items.map(item => cleanRecord(item, CARD_PRIVATE) as unknown as Specification) }
+    }
+    const spec = sql.tables.card
+    const categories = query?.category == null ? undefined : Array.isArray(query.category) ? query.category : [query.category]
+    const rows = await sql.runner.query(
+      `SELECT DISTINCT ON (${col(spec, 'category')}) * FROM ${spec.qualified}`
+      + ` WHERE ${col(spec, 'entityId')} = $1 AND ${col(spec, 'kind')} = $2 AND ${col(spec, 'parent')} = $3`
+      + `${categories != null ? ` AND ${col(spec, 'category')} = ANY($4)` : ''}`
+      + ` ORDER BY ${col(spec, 'category')}, ${currentOrder(sql)}`,
+      categories != null ? [entityId, WorkcardKind.Specification, parent, categories] : [entityId, WorkcardKind.Specification, parent]
+    )
+    // One current document per category is a small set: its paging and sorting are the shared engine's.
+    return applyQuery(rows.map(row => specOf(row, sql)), undefined, listOptionsOf(query))
+  },
+
+  revisions: async (id, entityId, limit) => {
+    const sql = await deps.sql()
+    const spec = sql.tables.card
+    const found = await sql.runner.query(
+      `SELECT ${col(spec, 'id')} FROM ${spec.qualified} WHERE ${col(spec, 'id')} = $1 AND ${col(spec, 'entityId')} = $2 AND ${col(spec, 'kind')} = $3`,
+      [id, entityId, WorkcardKind.Specification]
+    )
+    if (found.length === 0) {
+      return []
+    }
+    return revisionsFromLog((await listTransitions(sql, { entityId, card: id })).items, limit)
+  },
+})