@frontera-sdk/cli 0.1.0 → 1.43.5

package/src/automation-template.ts

@@ -0,0 +1,224 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+// The committed payload, exactly as `template.ts` reads it. NOT
+// `../scripts/sync-sdk` — `scripts/` is build tooling, not part of the shipped
+// CLI, and importing it from `src/` would drag it into the bundle.
+import vendored from './vendor/sdk-sources.json'
+
+/**
+ * The vendored SDK files an automation project carries — a FILE list, not a
+ * directory list, and that distinction is load-bearing.
+ *
+ * Derived by tracing imports rather than assumed:
+ *
+ *     automation/index.ts    → ./define, ./manifest, ./types
+ *     automation/define.ts   → ./types
+ *     automation/manifest.ts → cron-parser
+ *     automation/types.ts    → @frontera-sdk/blueprint/types
+ *     blueprint/types.ts     → nothing
+ *
+ * So `frontera/core/` is never reached, and the REST of `frontera/blueprint/`
+ * must be excluded: `hooks.ts` and `provider.tsx` import React and
+ * `@tanstack/react-query`, which are peerDependencies an automation project has
+ * no reason to install. Vendoring the whole directory — as `APP_SDK_DIRS` does,
+ * because an app HAS React — would fail `tsc` in a freshly scaffolded project.
+ */
+export const AUTOMATION_SDK_FILES = [
+  'frontera/automation/index.ts',
+  'frontera/automation/define.ts',
+  'frontera/automation/manifest.ts',
+  'frontera/automation/types.ts',
+  // `index.ts` re-exports both, so omitting them breaks the whole package for a
+  // scaffolded project, not just the parts that use them. `testing.ts` is what
+  // lets an author unit-test a handler; `messages.ts` is the wording it refuses
+  // in, shared with the runner.
+  'frontera/automation/messages.ts',
+  'frontera/automation/testing.ts',
+  'frontera/blueprint/types.ts',
+] as const
+
+/**
+ * The files a new automation project contains.
+ *
+ * The SDK is written into `src/frontera/` rather than declared as a dependency:
+ * `@frontera-sdk/automation` is `private: true` and `workspace:*`, so it resolves
+ * nowhere outside this monorepo — which is the entire problem Phase B exists to
+ * solve. `package.json` therefore asks for nothing but public npm.
+ */
+export function automationScaffoldFiles(name: string): Record<string, string> {
+  const files = vendored.files as Record<string, string>
+  const out: Record<string, string> = {}
+  for (const rel of AUTOMATION_SDK_FILES) {
+    const content = files[rel]
+    // Fail loudly. A silently missing SDK file produces a project whose imports
+    // resolve to nothing — discovered by the author, not by us. This is the
+    // failure `cron-parser` caused in SEB-289.
+    if (content === undefined) {
+      throw new Error(
+        `vendored SDK is missing ${rel} — run \`bun run sync:sdk\` in packages/frontera-cli`,
+      )
+    }
+    out[`src/${rel}`] = content
+  }
+
+  out['package.json'] = JSON.stringify({
+    name,
+    private: true,
+    type: 'module',
+    scripts: {
+      typecheck: 'tsc --noEmit',
+      // A handler is testable without deploying — `createTestContext` is what
+      // the starter test uses — so the project ships with somewhere to run it.
+      test: 'bun test',
+      deploy: 'frontera automation deploy src/index.ts',
+    },
+    dependencies: {
+      // The vendored `frontera/automation/manifest.ts` imports it to validate
+      // cron expressions at author time. Omitting it leaves every generated
+      // project with an unresolvable import and a failing `typecheck`.
+      'cron-parser': '^5.0.6',
+    },
+    // `@types/bun` is what makes `bun:test` resolve in the starter test; the
+    // scaffold would otherwise ship a test file its own typecheck rejects.
+    devDependencies: { typescript: '^5.6.0', '@types/bun': 'latest' },
+  }, null, 2) + '\n'
+
+  out['tsconfig.json'] = JSON.stringify({
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'ESNext',
+      moduleResolution: 'bundler',
+      strict: true,
+      noEmit: true,
+      skipLibCheck: true,
+      // No DOM and no node types: an automation runs server-side under Bun and
+      // its handler touches neither. Keeping the surface empty means a scaffolded
+      // project needs no @types packages to typecheck.
+      types: ['bun'],
+      // Mirrors how the CLI resolves these when it builds the entry file. The
+      // specifier is the contract; where it resolves is an implementation
+      // detail, so publishing the packages later is deleting these lines.
+      baseUrl: '.',
+      paths: {
+        '@frontera-sdk/automation': ['./src/frontera/automation/index.ts'],
+        '@frontera-sdk/automation/*': ['./src/frontera/automation/*'],
+        '@frontera-sdk/blueprint/types': ['./src/frontera/blueprint/types.ts'],
+        '@frontera-sdk/blueprint/*': ['./src/frontera/blueprint/*'],
+      },
+    },
+    include: ['src'],
+  }, null, 2) + '\n'
+
+  out['src/index.ts'] = `import { automation } from '@frontera-sdk/automation'
+
+export default automation(
+  {
+    name: '${name}',
+    // A starter schedule — every five minutes, so you can see it run.
+    // CHANGE OR REMOVE THIS before anyone relies on the automation.
+    trigger: { cron: '*/5 * * * *' },
+    // Grants are enforced twice: the runner refuses a ctx call the manifest does
+    // not list, and Blueprint grants decide which object types are visible.
+    grants: ['blueprint:read'],
+  },
+  async (ctx) => {
+    // Wrap work in a STEP. A step runs at most once per run: if a later step
+    // fails and the run is retried, this one returns what it returned the first
+    // time instead of querying again. Steps are also what the Console draws.
+    const found = await ctx.step.run('load', async () => {
+      const result = await ctx.blueprint.query('YourObjectType', { limit: 10 })
+      await ctx.log(\`loaded \${result.rows.length} row(s)\`)
+      return { count: result.rows.length }
+    })
+
+    // A branch is a branch: each arm is its own step, so both are visible in
+    // the Console — including the one today's data did not take.
+    if (found.count === 0) {
+      return await ctx.step.run('nothing-to-do', async () => ({ handled: 0 }))
+    }
+
+    // Names must be UNIQUE within a run. The platform memoizes by name, so a
+    // repeated one would hand back the first result — inside a loop, put the
+    // index in the name.
+    for (const i of [0, 1]) {
+      await ctx.step.run(\`handle:\${i}\`, async () => {
+        await ctx.log(\`handling batch \${i}\`)
+        return { batch: i }
+      })
+    }
+
+    // Anything OUTSIDE a step re-runs each time the platform resumes the
+    // handler, which it does after every step — so keep calls that cost
+    // something inside one.
+    //
+    // Whatever you return is stored as the run's result and shown in the
+    // Console. Returning nothing is fine; returning something is how you see
+    // what happened without reading logs.
+    return { handled: found.count, checkedAt: new Date().toISOString() }
+  },
+)
+`
+
+  out['src/index.test.ts'] = `import { expect, test } from 'bun:test'
+import { createTestContext } from '@frontera-sdk/automation'
+
+import automation from './index'
+
+// A handler is just a function, so it can be tested without deploying. The
+// context refuses what the platform refuses — a grant the manifest does not
+// declare, a step name used twice — so a passing test means something.
+test('handles an empty result', async () => {
+  const { ctx, steps } = createTestContext({ grants: ['blueprint:read'] })
+
+  const result = await automation.handler(ctx)
+
+  expect(result).toEqual({ handled: 0 })
+  // The steps it took, in order — including the arm a day with no data hits.
+  expect(steps).toEqual(['load', 'nothing-to-do'])
+})
+
+test('handles rows', async () => {
+  const { ctx, steps } = createTestContext({
+    grants: ['blueprint:read'],
+    // Stub only what this test is about; an object type you do not stub returns
+    // no rows, which is a real answer.
+    blueprint: { YourObjectType: { rows: [{ id: 'a' }, { id: 'b' }], hasMore: false } },
+  })
+
+  await automation.handler(ctx)
+
+  expect(steps).toEqual(['load', 'handle:0', 'handle:1'])
+})
+`
+
+  out['.gitignore'] = 'node_modules\n.env\n.env.*\n'
+
+  out['README.md'] = `# ${name}
+
+\`\`\`bash
+bun install
+bun run typecheck
+frontera automation deploy src/index.ts
+\`\`\`
+
+The SDK is vendored into \`src/frontera/\` and resolved by the \`paths\` in
+\`tsconfig.json\`. Do not replace those imports with a package dependency — the
+packages are unpublished, and the vendored copy is what makes this project build
+on a machine that has never seen the Frontera monorepo.
+
+\`frontera automation pull ${name}\` recovers this project from any deployed
+version. A \`.env\` here is never uploaded.
+`
+
+  return out
+}
+
+/** Write a new automation project to `target`. */
+export function scaffoldAutomation(target: string, name: string): void {
+  for (const [rel, content] of Object.entries(automationScaffoldFiles(name))) {
+    const full = join(target, rel)
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, content)
+  }
+}

package/src/blueprint/compile.ts

@@ -0,0 +1,371 @@
+import { CliError } from '../errors'
+import type { ArtifactKind, AuthoredFile, RefError, Result } from './model'
+
+/**
+ * Authored document → the body its route takes.
+ *
+ * Not a reference resolver, and that is worth saying because an earlier design made
+ * it one: every per-artifact route speaks `apiName`, not UUID — `linkTypeStructureBody`
+ * takes `fromObjectType` / `fromProperty` as names, and object types are addressed by
+ * apiName in the path. So nothing here mints or looks up an id. UUIDs are needed only
+ * by the object DRAFT COMMANDS, which address an `objectId`, and those are resolved
+ * from the live draft where they are issued.
+ *
+ * What this module does is the shape mapping, which is real: the file mirrors the
+ * DEFINITION BUNDLE (`valueType`, `unique`, `pluralDisplayName`) while the create
+ * route takes an authoring shape (`dataType`, `isUnique`, `pluralName`). Keeping the
+ * file bundle-shaped is what makes `pull` lossless; keeping the translation here is
+ * what stops that choice leaking into every command.
+ */
+
+export interface DatasetResolver {
+  /** Dataset name → its current revision id and schema digest. */
+  (name: string): Promise<{ revisionId: string; schemaDigest: string }>
+}
+
+/** `backing:` as a file writes it — a dataset NAME, and one column per property. */
+export interface AuthoredBacking {
+  dataset: string
+  mapping: Record<string, string | { column: string; field?: string | null }>
+  editable?: string[]
+}
+
+function requireString(
+  document: Record<string, unknown>,
+  field: string,
+  path: string,
+): string {
+  const value = document[field]
+  if (typeof value !== 'string' || !value) {
+    throw new CliError(`${path} is missing \`${field}\`.`, {
+      code: 'USAGE',
+      hint: `Every artifact declares ${field}; \`frontera blueprint new\` writes one that validates.`,
+    })
+  }
+  return value
+}
+
+function optional<T>(value: T | undefined, key: string): Record<string, T> {
+  return value === undefined ? {} : { [key]: value } as Record<string, T>
+}
+
+export function readBacking(file: AuthoredFile): AuthoredBacking | undefined {
+  const backing = file.document.backing
+  if (backing === undefined) return undefined
+  if (!backing || typeof backing !== 'object' || Array.isArray(backing)) {
+    throw new CliError(`${file.path} has a \`backing\` that is not a mapping.`, {
+      code: 'USAGE',
+      hint: 'backing: { dataset: <name>, mapping: { <property>: <column> } }',
+    })
+  }
+  const candidate = backing as Record<string, unknown>
+  if (typeof candidate.dataset !== 'string' || !candidate.dataset) {
+    throw new CliError(`${file.path} has a \`backing\` that names no dataset.`, {
+      code: 'USAGE',
+      hint: 'backing.dataset is the dataset NAME — the revision it pins is resolved at apply time.',
+    })
+  }
+  return {
+    dataset: candidate.dataset,
+    mapping: (candidate.mapping ?? {}) as AuthoredBacking['mapping'],
+    ...(Array.isArray(candidate.editable) ? { editable: candidate.editable as string[] } : {}),
+  }
+}
+
+/**
+ * `sharedField: accountCode` → the uuid the wire takes. THREE-VALUED, because the
+ * authored key has three states and the wire has the same three:
+ *
+ * | Authored | Returned | Wire |
+ * |---|---|---|
+ * | key absent | `undefined` | omit `sharedPropertyId` — unchanged |
+ * | `sharedField: null` | `null` | `sharedPropertyId: null` — detach |
+ * | `sharedField: <name>` | the uuid | `sharedPropertyId: <uuid>` |
+ *
+ * Collapsing `null` into `undefined` looked harmless and broke detach outright: the
+ * plan saw the change, the executor then omitted the only member the patch had, and
+ * `update_field_metadata` went out as `patch: {}` — which the route refuses on
+ * `minProperties: 1`. The wire models the distinction deliberately
+ * (`sharedPropertyId: t.Optional(t.Nullable(uuid))`), so the tree can state it.
+ *
+ * The name is resolved against what the draft holds AT THE MOMENT OF THE WRITE, not
+ * at plan time: a shared field created earlier in the same `apply` has no id when
+ * the plan is computed, and the executor adds it to this map as each create answers.
+ *
+ * An unresolvable name names both halves of the reference, because either one may be
+ * the typo and an error naming only the field sends the reader to the wrong file.
+ */
+export function resolveSharedProperty(
+  file: AuthoredFile,
+  propertyApiName: string,
+  declared: unknown,
+  sharedPropertyIdByApiName: Map<string, string>,
+): string | null | undefined {
+  if (declared === undefined) return undefined
+  if (declared === null) return null
+  const name = String(declared)
+  const id = sharedPropertyIdByApiName.get(name)
+  if (!id) {
+    throw new CliError(
+      `${file.path}: field "${propertyApiName}" names shared field "${name}", `
+      + 'which is not on the draft.',
+      {
+        code: 'USAGE',
+        hint: `Add shared-fields/${name}.yaml, or correct the name. `
+          + 'A shared field is referenced by apiName — the tree carries no identifiers.',
+      },
+    )
+  }
+  return id
+}
+
+function columnOf(entry: string | { column: string; field?: string | null }): {
+  column: string
+  field?: string | null
+} {
+  return typeof entry === 'string' ? { column: entry } : entry
+}
+
+/**
+ * The create body for `POST /v1/blueprint/object-types`.
+ *
+ * `datasetRevisionId` is resolved from the backing's dataset NAME. That indirection is
+ * the whole reason the tree is portable: `customers` means the same thing in two
+ * deployments, and the revision it currently points at does not.
+ */
+export async function objectTypeCreateBody(
+  file: AuthoredFile,
+  expectedRevision: number,
+  resolveDataset: DatasetResolver,
+  sharedPropertyIdByApiName: Map<string, string>,
+): Promise<Record<string, unknown>> {
+  const document = file.document
+  const backing = readBacking(file)
+  if (!backing) {
+    throw new CliError(`${file.path} declares no \`backing\`, so it cannot be created.`, {
+      code: 'USAGE',
+      hint: 'An object type reads through a Dataset. Add backing.dataset and a column per property.',
+    })
+  }
+  // The create route builds an object type from an explicit body — apiName, display
+  // names, properties, keys, backing — and has no channel for `validations` or
+  // `lifecycle`. Sending a file that declares them would create the type WITHOUT them
+  // and report success, which is the silent-drop this design keeps having to root out.
+  const validations = document.validations
+  if (Array.isArray(validations) && validations.length > 0) {
+    throw new CliError(`${file.path} declares validations, which the create route cannot express.`, {
+      code: 'USAGE',
+      hint: 'Create the type without them and add validations in the Console, or remove them from the file.',
+    })
+  }
+  if (document.lifecycle !== undefined) {
+    throw new CliError(`${file.path} declares a lifecycle, which the create route cannot express.`, {
+      code: 'USAGE',
+      hint: 'Create the type without it and author the lifecycle in the Console.',
+    })
+  }
+
+  const { revisionId } = await resolveDataset(backing.dataset)
+  const properties = Array.isArray(document.properties) ? document.properties : []
+
+  return {
+    apiName: requireString(document, 'apiName', file.path),
+    displayName: requireString(document, 'displayName', file.path),
+    pluralName: requireString(document, 'pluralDisplayName', file.path),
+    ...optional(document.description as string | undefined, 'description'),
+    ...optional(document.icon as string | undefined, 'icon'),
+    ...optional(document.color as string | undefined, 'color'),
+    ...optional(document.groups as string[] | undefined, 'groups'),
+    ...optional(document.status as string | undefined, 'status'),
+    ...optional(document.visibility as string | undefined, 'visibility'),
+    datasetRevisionId: revisionId,
+    properties: properties.map((entry) => {
+      const property = entry as Record<string, unknown>
+      const apiName = String(property.apiName)
+      const mapped = backing.mapping[apiName]
+      if (mapped === undefined) {
+        throw new CliError(
+          `${file.path}: property "${apiName}" has no column in \`backing.mapping\`.`,
+          {
+            code: 'USAGE',
+            // The service refuses a name match deliberately (ADR 0008); saying so
+            // here stops the reader looking for the setting that turns it on.
+            hint: 'Every property names the column it reads. There is no name-match fallback.',
+          },
+        )
+      }
+      const { column, field } = columnOf(mapped)
+      // Attached AT CREATION, not by a later add-field command: a first apply against
+      // an empty organization creates the type and all its fields in one call, so a
+      // reference the create body cannot carry is unreachable on exactly that run.
+      const sharedPropertyId = resolveSharedProperty(
+        file, apiName, property.sharedField, sharedPropertyIdByApiName,
+      )
+      return {
+        apiName,
+        displayName: String(property.displayName ?? apiName),
+        ...optional(property.description as string | undefined, 'description'),
+        propertyType: (property.propertyType as string | undefined) ?? 'attribute',
+        dataType: String(property.valueType ?? 'string'),
+        column,
+        ...(field === undefined || field === null ? {} : { field }),
+        ...optional(property.formatConfig as Record<string, unknown> | undefined, 'formatConfig'),
+        ...(property.unique === undefined ? {} : { isUnique: Boolean(property.unique) }),
+        // A CREATE has nothing to detach from, so an authored `null` is simply
+        // "no shared field" — and the create body's uuid is not nullable, so
+        // sending it would be a 422 rather than a detach.
+        ...(typeof sharedPropertyId === 'string' ? { sharedPropertyId } : {}),
+      }
+    }),
+    columnMappings: Object.entries(backing.mapping).map(([propertyApiName, entry]) => {
+      const { column, field } = columnOf(entry)
+      return { propertyApiName, column, ...(field === undefined ? {} : { field }) }
+    }),
+    primaryKey: requireString(document, 'primaryKey', file.path),
+    titleKey: requireString(document, 'title', file.path),
+    expectedRevision,
+  }
+}
+
+/** `PUT /object-types/:apiName` takes metadata only — fields move by draft command. */
+export function objectTypePatchBody(
+  file: AuthoredFile,
+  expectedRevision: number,
+): Record<string, unknown> {
+  const document = file.document
+  return {
+    ...optional(document.displayName as string | undefined, 'displayName'),
+    ...optional(document.pluralDisplayName as string | undefined, 'pluralName'),
+    ...optional(document.description as string | undefined, 'description'),
+    ...optional(document.icon as string | undefined, 'icon'),
+    ...optional(document.color as string | undefined, 'color'),
+    ...optional(document.groups as string[] | undefined, 'groups'),
+    ...optional(document.status as string | undefined, 'status'),
+    ...optional(document.visibility as string | undefined, 'visibility'),
+    expectedRevision,
+  }
+}
+
+function endpoint(document: Record<string, unknown>, side: 'from' | 'to', path: string) {
+  const value = document[side]
+  if (!value || typeof value !== 'object') {
+    throw new CliError(`${path} has no \`${side}\` endpoint.`, {
+      code: 'USAGE',
+      hint: `${side}: { objectType: <ApiName>, property: <apiName>, displayName: <text> }`,
+    })
+  }
+  return value as Record<string, unknown>
+}
+
+export function linkTypeStructure(
+  file: AuthoredFile,
+  expectedRevision: number,
+): Record<string, unknown> {
+  const document = file.document
+  const from = endpoint(document, 'from', file.path)
+  const to = endpoint(document, 'to', file.path)
+  return {
+    cardinality: String(document.cardinality ?? 'one_to_many'),
+    fromObjectType: String(from.objectType),
+    toObjectType: String(to.objectType),
+    fromProperty: String(from.property),
+    toProperty: String(to.property),
+    fromDisplayName: String(from.displayName ?? to.objectType),
+    toDisplayName: String(to.displayName ?? from.objectType),
+    ...optional(from.phrase as string | undefined, 'fromPhrase'),
+    ...optional(to.phrase as string | undefined, 'toPhrase'),
+    ...optional(document.description as string | undefined, 'description'),
+    expectedRevision,
+  }
+}
+
+export function linkTypeCreateBody(
+  file: AuthoredFile,
+  expectedRevision: number,
+): Record<string, unknown> {
+  return { apiName: file.apiName, ...linkTypeStructure(file, expectedRevision) }
+}
+
+/**
+ * Metrics and actions are carried through as authored.
+ *
+ * Their routes take the same shape the bundle carries, so translating would only
+ * create a place for the two to drift.
+ */
+export function metricCreateBody(
+  file: AuthoredFile,
+  expectedRevision: number,
+): Record<string, unknown> {
+  const { objectType, ...body } = file.document as Record<string, unknown>
+  if (typeof objectType !== 'string' || !objectType) {
+    throw new CliError(`${file.path} names no \`objectType\`.`, {
+      code: 'USAGE',
+      hint: 'A metric measures one object type, named by apiName.',
+    })
+  }
+  // `objectType` in the file, `objectTypeApiName` on the wire — the route's own name
+  // for the same thing.
+  return { ...body, objectTypeApiName: objectType, expectedRevision }
+}
+
+/** The patch route takes metadata and the definition, never the subject. */
+export function metricPatchBody(
+  file: AuthoredFile,
+  expectedRevision: number,
+): Record<string, unknown> {
+  const { objectType: _objectType, apiName: _apiName, ...body } = file.document as Record<string, unknown>
+  return { ...body, expectedRevision }
+}
+
+/**
+ * A shared field is authored whole: the create route takes the same fields the
+ * bundle carries, so the file is passed through rather than translated.
+ *
+ * It names no column and no dataset, which is why there is no backing to resolve —
+ * a shared field says what a field MEANS, and nothing about where it is read.
+ */
+export function sharedPropertyCreateBody(
+  file: AuthoredFile,
+  expectedRevision: number,
+): Record<string, unknown> {
+  const document = file.document
+  return {
+    apiName: requireString(document, 'apiName', file.path),
+    displayName: requireString(document, 'displayName', file.path),
+    ...optional(document.description as string | undefined, 'description'),
+    valueType: requireString(document, 'valueType', file.path),
+    // Required like `valueType`: a shared field states how it is read, and the
+    // create route refuses a body without it. Caught here so the failure names
+    // the file instead of arriving as a 422 from the service.
+    propertyType: requireString(document, 'propertyType', file.path),
+    ...optional(document.formatConfig as Record<string, unknown> | undefined, 'formatConfig'),
+    ...optional(document.status as string | undefined, 'status'),
+    ...optional(document.visibility as string | undefined, 'visibility'),
+    expectedRevision,
+  }
+}
+
+/**
+ * The patch route treats `apiName` as a RENAME, so it is omitted here.
+ *
+ * The file's apiName is its filename (`readTree` refuses a tree where they disagree),
+ * and the route is addressed by that same name — so sending it could only ever
+ * restate what is already true, while a future edit to one of the two would make it
+ * silently rename the artifact instead.
+ */
+export function sharedPropertyPatchBody(
+  file: AuthoredFile,
+  expectedRevision: number,
+): Record<string, unknown> {
+  const { apiName: _apiName, ...body } = file.document as Record<string, unknown>
+  return { ...body, expectedRevision }
+}
+
+/** Collected rather than thrown — see `RefError`. */
+export function ok<T>(value: T): Result<T> {
+  return { ok: true, value }
+}
+
+export function failed<T>(errors: RefError[]): Result<T> {
+  return { ok: false, errors }
+}

package/src/blueprint/dataset-revision.ts

@@ -0,0 +1,33 @@
+/**
+ * Which revision of a dataset is CURRENT.
+ *
+ * The dataset says so itself, in `currentRevisionId`. Sorting its revisions and taking
+ * the highest number is a DIFFERENT answer after a rollback — the live revision is then
+ * not the newest one — and a binding pinned that way reads a revision the organization
+ * has stepped off, silently, until somebody notices the columns are stale.
+ *
+ * One implementation because there were two and they disagreed: `apply` read
+ * `currentRevisionId` while `bind` took `revisions[0]`, so the same tree pinned
+ * differently depending on which command reached the dataset first.
+ */
+
+export interface DatasetRef {
+  currentRevisionId?: string
+}
+
+/**
+ * @param revisions ordered highest revision number first, as `datasetRevisions` returns
+ * them. The order is only the FALLBACK: it answers a payload that names no current
+ * revision, and a list that does not contain the named one — which is what a truncated
+ * page looks like.
+ */
+export function pickCurrentRevision<T extends { id?: string }>(
+  dataset: DatasetRef,
+  revisions: readonly T[],
+): T | undefined {
+  if (dataset.currentRevisionId) {
+    const named = revisions.find((revision) => revision.id === dataset.currentRevisionId)
+    if (named) return named
+  }
+  return revisions[0]
+}