@frontera-sdk/cli 1.53.5 → 1.53.7

package/src/commands/app/shared.ts

@@ -1,5 +1,7 @@
 import { AppsApi } from '../../api/apps-api'
+import { PlatformApi } from '../../api/platform-api'
 import { UsageError } from '../../errors'
+import { appBinding, appTarget, bindApp } from '../../project'
 import type { AppProject } from '../../context'
 import type { CommandContext } from '../types'
 
@@ -13,6 +15,16 @@ export function requireProjectFrom(ctx: CommandContext): AppProject {
   return ctx.project
 }
 
+/**
+ * The target this credential reaches (`appTarget`): its workspace as `whoami`
+ * answers, asked the way `AppsApi` asks, so it is the workspace the App calls
+ * land in. Null when it cannot say; the folder's bindings are then left alone.
+ */
+export async function credentialTarget(ctx: CommandContext): Promise<string | null> {
+  const me = await new PlatformApi(ctx.apiUrl, ctx.token).whoami().catch(() => null)
+  return me?.workspaceId ? appTarget(ctx.apiUrl, me.workspaceId) : null
+}
+
 /**
  * The app this project belongs to, without creating one.
  *
@@ -20,6 +32,51 @@ export function requireProjectFrom(ctx: CommandContext): AppProject {
  * that ensured instead would turn a typo, or a slug the platform had since
  * renamed, into a brand new empty app.
  */
-export function projectApp(client: AppsApi, project: AppProject) {
-  return client.resolveApp(project.appId ?? project.slug)
+export async function projectApp(ctx: CommandContext, client: AppsApi, project: AppProject) {
+  const bound = appBinding(project.root, await credentialTarget(ctx)).id
+  return client.resolveApp(bound ?? project.fallbackAppId ?? project.slug)
+}
+
+/**
+ * The folder's App where the credential acts, created when it has none there
+ * (`save`, `deploy`, `app dev`), and bound to the folder for that target. A
+ * creation is said: a person who renamed the folder or moved it to another
+ * workspace must not learn of a second App from the gallery. `app` names an
+ * existing App to deploy to instead, which never creates one.
+ */
+export async function ensureProjectApp(
+  ctx: CommandContext,
+  client: AppsApi,
+  project: AppProject,
+  app?: string,
+): Promise<{ id: string; slug: string; created: string | null; target: string | null }> {
+  const target = await credentialTarget(ctx)
+  const known = appBinding(project.root, target)
+  const named = app ? await client.resolveApp(app) : null
+  // Refused before the folder is bound to it: every later deploy would send its id, and fail the same way.
+  if (named?.kind && named.kind !== 'code') {
+    throw new UsageError(`${named.slug} is a Chat App, and a folder deploys to a Custom App`, '`frontera app list` names the Apps; pass a Custom App\'s slug to `--app`, or leave `--app` out to deploy to the folder\'s own')
+  }
+  const ensured = named
+    ? { ...named, created: false }
+    : await client.ensureApp(project.slug, project.displayName, known.id ?? project.fallbackAppId, { icon: project.icon })
+  bindApp(project.root, target, ensured.id)
+  const created = ensured.created ? createdApp(ensured.slug, known.id ? 'gone' : known.elsewhere || project.fallbackAppId ? 'elsewhere' : 'first') : null
+  if (created) ctx.output.note(`  ${created}`)
+  // The platform owns the name once the App exists (App settings renames it); the folder's name only creates one.
+  else if (ensured.slug !== project.slug) ctx.output.note(`  bound to the App ${ensured.slug} here: this folder's own name, ${project.slug}, names an App only on its first deploy to a workspace and never renames one (rename it in Apps, App settings)`)
+  return { id: ensured.id, slug: ensured.slug, created, target }
+}
+
+/**
+ * What a creation says: plain for a folder's first deploy anywhere. A folder
+ * that has an App elsewhere, or had one here, gets the way back too, since
+ * this workspace may hold its App under another name.
+ */
+function createdApp(slug: string, before: 'first' | 'gone' | 'elsewhere'): string {
+  if (before === 'first') return `created the App ${slug} in this workspace`
+  const why = before === 'gone' ? ': the App this folder deployed to here is gone' : ', this folder\'s first deploy here (it has deployed to other workspaces)'
+  return `created a new App ${slug} in this workspace${why}. `
+    + 'If this workspace already had the App under another name, deploy to that one instead with `frontera app deploy --app <slug>` (`frontera app list` names them) '
+    + `and archive ${slug} in Apps. A deploy never renames an App: rename one in Apps, App settings.`
 }

package/src/commands/app/unpin.ts

@@ -20,7 +20,7 @@ export const appUnpin: Command = {
     if (!reason?.trim()) throw new UsageError('unpinning needs --reason', 'frontera app unpin --reason "why production may move again"')
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     const res = await client.unpin(app.id, reason)
     return { data: { app: app.slug, appId: app.id, ...res }, text: `Unpinned ${app.slug}: production keeps serving ${res.productionLabel ?? res.production ?? 'what it serves'}, and promotion works again` }
   },

package/src/commands/app/versions.ts

@@ -17,7 +17,7 @@ export const appVersions: Command = {
   async run(ctx) {
     const project = requireProjectFrom(ctx)
     const client = new AppsApi(ctx.apiUrl, ctx.token)
-    const app = await projectApp(client, project)
+    const app = await projectApp(ctx, client, project)
     const versions = await client.listVersions(app.id)
 
     return {

package/src/commands/blueprint/authoring.ts

@@ -2,6 +2,16 @@ import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
+import { GovernedActionApi } from '../../api/governed-action-api'
+import {
+  blockerLines,
+  groupedChanges,
+  migrationInstructions,
+  newActionSteps,
+  changedActionSteps,
+  publishPlan,
+} from '../../blueprint/publish-plan'
+import { signInStep } from '../../device-login'
 import { CliError } from '../../errors'
 import type { Command, CommandContext } from '../types'
 
@@ -301,7 +311,7 @@ type ValidationReport = Awaited<ReturnType<BlueprintAuthoringApi['validate']>>
  * release to the validation that cleared it rather than to whatever the draft
  * holds later.
  */
-export function renderValidationReport(report: ValidationReport): string {
+export function renderValidationReport(report: Partial<ValidationReport>): string {
   const id = report?.id ?? report?.reportId
   const objectTypes = report?.catalogProjection?.objectTypes?.length ?? 0
   const linkTypes = report?.catalogProjection?.linkTypes?.length ?? 0
@@ -327,7 +337,16 @@ export const blueprintPublish: Command = {
     verb: 'publish',
     args: [],
     flags: { label: 'string', notes: 'string', report: 'string', instruction: 'string' },
+    flagHelp: {
+      instruction: 'how existing data and environments take the changes that need a migration instruction; sent with each of them (a new Action’s own is written for you)',
+      report: 'the draft’s latest validation report to publish against; without it, publish validates the draft first',
+    },
     summary: 'Publish the shared draft as a release',
+    details: [
+      'Validates the draft first and posts nothing that would be refused: each blocker is listed with the command that clears it.',
+      'A new governed Action with no deployment decision is recorded as shipping switched off, as `frontera action prepare` does.',
+      'A change that needs a migration instruction (other than a new Action\'s) is listed by kind and name; --instruction explains every one of them.',
+    ],
     examples: [
       'frontera blueprint publish --label v3 --notes "Adds Customer"',
       'frontera blueprint publish --label v4 --instruction "Backfilled"',
@@ -337,39 +356,106 @@ export const blueprintPublish: Command = {
     const client = api(ctx)
     const label = (ctx.flags.label as string) ?? 'cli-release'
     const notes = (ctx.flags.notes as string) ?? 'Published with the Frontera CLI.'
-
-    // Validate first when no report was given: publishing against a stale report
-    // would release something nobody checked.
-    let validationReportId = ctx.flags.report as string | undefined
-    if (!validationReportId) {
-      const report = await client.validate()
-      validationReportId = report?.id ?? report?.reportId
+    const instruction = (ctx.flags.instruction as string | undefined)?.trim() || undefined
+    const profile = typeof ctx.flags.profile === 'string' ? ctx.flags.profile : undefined
+
+    // `--report` is the validation the person read; without it, the draft is validated now.
+    let report: ValidationReport
+    const reportId = ctx.flags.report as string | undefined
+    if (reportId) {
+      const latest = (await client.lifecycle() as { latestValidation?: ValidationReport | null }).latestValidation
+      if (latest?.id !== reportId) {
+        throw new CliError(`Report ${reportId} is not the draft's latest validation, so a release from it would not be what was checked.`, {
+          code: 'VALIDATION_STALE',
+          hint: 'drop --report (publish validates the draft itself), or run `frontera blueprint validate` and pass its report',
+        })
+      }
+      report = latest
+    } else {
+      report = await client.validate()
+    }
+    const signIn = await signInStep({ profile: ctx.profile, apiUrl: ctx.apiUrl })
+    let plan = publishPlan(report, signIn, profile)
+
+    // What `action prepare` records, for each Action that has no decision yet.
+    const prepared: string[] = []
+    if (plan.autoFixable.length) {
+      const actions = new GovernedActionApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
+      for (const name of plan.autoFixable) {
+        await actions.recordDeploymentDecision(name, `Published with the Frontera CLI ("${label}"): ships switched off until a person deploys it and turns it on.`)
+        prepared.push(name)
+      }
+      plan = publishPlan(await client.validate(), signIn, profile)
+    }
+    const preparedLines = prepared.map((name) => `Recorded that Action ${name} ships switched off: a person deploys it and turns it on after publish.`)
+
+    if (plan.blockers.length) {
+      throw new CliError([
+        ...preparedLines,
+        `The draft can't be published yet, so nothing was published. ${plan.blockers.length} blocker${plan.blockers.length === 1 ? '' : 's'}:`,
+        ...blockerLines(plan.blockers),
+      ].join('\n'), {
+        code: 'RELEASE_BLOCKED',
+        hint: 'clear each blocker above, then publish again',
+        details: { prepared, plan },
+      })
     }
-    if (!validationReportId) {
-      throw new CliError('Validation produced no report id; cannot publish.', {
-        code: 'FAILURE',
-        hint: 'frontera blueprint validate',
+
+    if (plan.instructionsNeeded.length && !instruction) {
+      const quote = (value: string) => (/^[\w.:-]+$/.test(value) ? value : JSON.stringify(value))
+      const rerun = ['frontera blueprint publish', `--label ${quote(label)}`, ...(ctx.flags.notes ? [`--notes ${quote(notes)}`] : []), '--instruction "<how existing data and environments take these changes>"', ...(profile ? [`--profile ${profile}`] : [])].join(' ')
+      const count = plan.instructionsNeeded.length
+      throw new CliError([
+        ...preparedLines,
+        `${count} change${count === 1 ? '' : 's'} in this release need${count === 1 ? 's' : ''} a migration instruction, so nothing was published:`,
+        ...groupedChanges(plan.instructionsNeeded).map((line) => `  ${line}`),
+      ].join('\n'), {
+        code: 'MIGRATION_INSTRUCTION_REQUIRED',
+        hint: `say how existing data and environments take these changes; the instruction is kept with each change in the release:\n    ${rerun}`,
+        details: { prepared, plan },
       })
     }
 
+    // Refused by the service, and kept as a failed attempt, if posted.
+    if (plan.unchanged) {
+      return { data: { release: null, prepared, newActions: [] }, text: [...preparedLines, 'The draft has no unpublished changes, so nothing was published.'].join('\n') }
+    }
+
     const released = await client.publish({
-      expectedRevision: await client.revision(),
-      validationReportId,
+      expectedRevision: plan.draftRevision,
+      validationReportId: plan.reportId,
       releaseLabel: label,
       releaseNotes: notes,
-      // A release that discards changes needs an instruction per discarded change.
-      instruction: ctx.flags.instruction as string | undefined,
+      migrationInstructions: migrationInstructions(plan, instruction),
     })
     const lifecycle = released as { activeRelease?: { releaseLabel?: string }; alreadyPublished?: boolean } | null
-    if (!lifecycle?.alreadyPublished) {
-      return { data: released, text: `Published release "${label}".` }
+    if (lifecycle?.alreadyPublished) {
+      // A retry of a publish that already went through is answered with the release
+      // that is live, which carries the label it was published with, not this run's.
+      // One made after newer Draft edits is refused by the service as stale.
+      const activeReleaseLabel = lifecycle.activeRelease?.releaseLabel ?? label
+      return { data: { release: released, prepared, newActions: [] }, text: `Release "${activeReleaseLabel}" is already active; nothing was published.` }
+    }
+    const newActions = plan.newActions.map((action) => ({ ...action, nextSteps: newActionSteps(action, signIn, profile) }))
+    const changedActions = plan.changedSwitchedOff.map((action) => ({ apiName: action.apiName, nextSteps: changedActionSteps(action, signIn, profile) }))
+    const numbered = (steps: Array<{ step: string; command?: string }>) => steps.flatMap((step, index) => (step.command ? [`  ${index + 1}. ${step.step}:`, `       ${step.command}`] : [`  ${index + 1}. ${step.step}.`]))
+    return {
+      data: { release: released, prepared, newActions, changedActions },
+      text: [
+        ...preparedLines,
+        `Published release "${label}".`,
+        ...newActions.flatMap((action) => [
+          '',
+          `New Action ${action.apiName} is published switched off, with no write path. To turn it on:`,
+          ...numbered(action.nextSteps),
+        ]),
+        ...changedActions.flatMap((action) => [
+          '',
+          `Action ${action.apiName} changed and is published switched off; its old write path does not run the new version. To turn it on again:`,
+          ...numbered(action.nextSteps),
+        ]),
+      ].join('\n'),
     }
-    // A retry of a publish that already went through is answered with the release
-    // that is live, which carries the label it was published with, not this run's.
-    // One made after newer Draft edits is refused by the service as stale.
-    const activeReleaseLabel = lifecycle.activeRelease?.releaseLabel ?? label
-    const nothingPublished = `Release "${activeReleaseLabel}" is already active; nothing was published.`
-    return { data: released, text: nothingPublished }
   },
 }
 

package/src/commands/blueprint/bind.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 
 import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
-import { pickCurrentRevision } from '../../blueprint/dataset-revision'
+import { columnMappingsFrom, datasetBindingCommand, pickCurrentRevision, type MappingEntry } from '../../blueprint/dataset-revision'
 import { readTree, writeTree } from '../../blueprint/tree'
 import { CliError } from '../../errors'
 import type { Command, CommandContext } from '../types'
@@ -31,7 +31,7 @@ function api(ctx: CommandContext): BlueprintAuthoringApi {
 
 interface MappingFile {
   dataset: string
-  mapping: Record<string, string | { column: string; field?: string | null } | null>
+  mapping: Record<string, MappingEntry | null>
 }
 
 async function datasetRevision(client: BlueprintAuthoringApi, name: string) {
@@ -58,7 +58,7 @@ async function datasetRevision(client: BlueprintAuthoringApi, name: string) {
       hint: 'Publish a revision of the dataset, then bind.',
     })
   }
-  return current
+  return { ...current, id: current.id }
 }
 
 /**
@@ -150,36 +150,7 @@ export const blueprintBind: Command = {
       })
     }
     const mapping = JSON.parse(readFileSync(resolve(ctx.cwd, filePath), 'utf8')) as MappingFile
-    const idByApiName = new Map(properties.map((property) => [property.apiName, property.id]))
-
-    const columnMappings: Array<{ propertyId: string; column: string; field?: string | null }> = []
-    const missing: string[] = []
-    for (const property of properties) {
-      const name = property.apiName
-      // A calculated field (a location from latitude and longitude) reads no column.
-      if (!name || (property as { calculation?: unknown }).calculation) continue
-      const entry = mapping.mapping?.[name]
-      if (entry === undefined || entry === null) {
-        missing.push(name)
-        continue
-      }
-      const resolved = typeof entry === 'string' ? { column: entry } : entry
-      const propertyId = idByApiName.get(name)
-      if (!propertyId) {
-        // `!` sent `propertyId: undefined` and let the service answer for it. The
-        // property came from the same read as the mapping, so this means the draft
-        // moved mid-command.
-        throw new CliError(`Property "${name}" is no longer on "${apiName}".`, {
-          code: 'CONFLICT',
-          hint: 'Re-run `frontera blueprint bind … --plan` against the current draft.',
-        })
-      }
-      columnMappings.push({
-        propertyId,
-        column: resolved.column,
-        ...(resolved.field === undefined || resolved.field === null ? {} : { field: resolved.field }),
-      })
-    }
+    const { columnMappings, unmapped: missing } = columnMappingsFrom(properties, mapping.mapping ?? {})
     if (missing.length > 0) {
       // Refused here rather than at the service: the same refusal, one round trip
       // earlier, and it can name every unmapped property at once instead of the
@@ -193,20 +164,13 @@ export const blueprintBind: Command = {
       )
     }
 
-    const result = await client.draftCommand({
-      kind: 'update_source_binding',
-      objectId: detail.id,
-      binding: {
-        kind: 'dataset',
-        datasetRevisionId: revision.id,
-        columnMappings,
-        ...(ctx.flags['accept-contract-change'] === true ? { acceptContractChange: true } : {}),
-      },
-    }, await client.revision())
+    const result = await client.draftCommand(
+      datasetBindingCommand(detail.id, revision.id, columnMappings, ctx.flags['accept-contract-change'] === true),
+      await client.revision(),
+    )
 
-    // The tree is told what the draft now says. `backing` is excluded from the diff
-    // — a rebind is this command's act, not `apply`'s — so nothing else would ever
-    // reconcile the file, and it would sit stale until the next `pull`.
+    // The tree is told what the draft now says, or the next `apply` would read the
+    // file's old Dataset as a rebind back to it.
     const treeRoot = resolve(ctx.cwd, (ctx.flags.dir as string) ?? 'blueprint')
     let treeUpdated = false
     if (existsSync(join(treeRoot, 'object-types'))) {

package/src/commands/blueprint/declarative.ts

@@ -23,15 +23,19 @@ import {
 } from '../../blueprint/compile'
 import { metricRuleProblems } from '../../blueprint/metric-rules'
 import { actionRuleProblems, type ActionRuleProblems, type InheritedConflict } from '../../blueprint/action-rules'
-import { pickCurrentRevision } from '../../blueprint/dataset-revision'
+import { datasetBindingCommand, pickCurrentRevision } from '../../blueprint/dataset-revision'
 import { nameCheckWords, orgNameCheck } from '../../blueprint/org-name-check'
 import {
   assertPrunesLeaveNoDanglingReference,
   diff,
+  driftOf,
+  editableChanges,
   isEmpty,
   satisfies,
+  type DatasetIndex,
   type ModelOperation,
   type Plan,
+  type RebindChange,
 } from '../../blueprint/diff'
 import {
   API_NAME_RULE,
@@ -135,6 +139,66 @@ async function datasetNamesByRevision(
   return names
 }
 
+/**
+ * What `plan` needs from the Datasets: the name each pinned revision belongs to, and the
+ * current revision of a Dataset a file names. The Dataset list names every current
+ * revision, so revisions are read only for a pin that is not current (it may have
+ * drifted) and for a Dataset a file names that its type does not read now (it may move).
+ * When every type reads its Dataset's current revision, nothing beyond the list is read.
+ * Undefined when this credential cannot read Datasets, so nothing is planned from a guess.
+ */
+async function readDatasetIndex(
+  client: BlueprintAuthoringApi,
+  files: AuthoredFile[],
+  live: DefinitionBundle,
+): Promise<DatasetIndex | undefined> {
+  const pinOf = (apiName: string) => (live.objects.find((object) => object.apiName === apiName)
+    ?.governance.sourceMappings[0] as { datasetRevisionId?: string } | undefined)?.datasetRevisionId
+  const named = files.flatMap((file) => {
+    const dataset = file.kind === 'object-type' ? (file.document.backing as { dataset?: unknown } | undefined)?.dataset : undefined
+    return typeof dataset === 'string' && dataset && live.objects.some((object) => object.apiName === file.apiName)
+      ? [{ dataset, pin: pinOf(file.apiName) }]
+      : []
+  })
+  const pins = new Set([...named.flatMap((entry) => entry.pin ?? []), ...driftOf(live).map((pin) => pin.datasetRevisionId)])
+  if (named.length === 0 && pins.size === 0) return undefined
+  const readable = await readableDatasets(client)
+  if (!readable) return undefined
+
+  const byName = new Map(readable.flatMap((dataset) => (dataset.id && dataset.name ? [[dataset.name, { ...dataset, id: dataset.id }] as const] : [])))
+  const index: DatasetIndex = { nameByRevisionId: new Map(), current: new Map() }
+  for (const [name, dataset] of byName) {
+    if (dataset.currentRevisionId) index.nameByRevisionId.set(dataset.currentRevisionId, name)
+  }
+  const read = new Set<string>()
+  const readRevisions = async (name: string, dataset: { id: string; currentRevisionId?: string }) => {
+    if (read.has(name)) return
+    read.add(name)
+    const revisions = await client.datasetRevisions(dataset.id)
+    for (const revision of revisions) {
+      if (revision.id) index.nameByRevisionId.set(revision.id, name)
+    }
+    const current = pickCurrentRevision(dataset, revisions)
+    if (!current?.id) return
+    index.current.set(name, {
+      id: current.id,
+      ...(current.schemaDigest ? { schemaDigest: current.schemaDigest } : {}),
+      ...(current.columns ? { columns: current.columns.flatMap((column) => (column.name ? [column.name] : [])) } : {}),
+    })
+  }
+  for (const { dataset, pin } of named) {
+    const target = byName.get(dataset)
+    if (target && (!pin || target.currentRevisionId !== pin)) await readRevisions(dataset, target)
+  }
+  for (const pin of pins) {
+    for (const [name, dataset] of byName) {
+      if (index.nameByRevisionId.has(pin)) break
+      await readRevisions(name, dataset)
+    }
+  }
+  return index
+}
+
 async function resolveRevision(
   client: BlueprintAuthoringApi,
   name: string,
@@ -308,34 +372,18 @@ async function computePlan(ctx: CommandContext): Promise<{
     })
   }
   const { definition, revision } = await client.draft()
-  const plan = withheldPrunes(diff(files, definition, revision), directory)
+  const datasets = await readDatasetIndex(client, files, definition)
+  const plan = withheldPrunes(diff(files, definition, revision, datasets), directory)
 
-  // Per DISTINCT dataset, which is what the design promised and what the previous
-  // loop did not do: it called `datasetRevisions` once per BOUND TYPE, after
-  // `datasetNamesByRevision` had already read every dataset's revisions. A hundred
-  // types on one dataset cost a hundred redundant round trips.
+  // A type moving to another Dataset is no longer held to the old one's contract.
+  const rebound = new Set(plan.rebind.map((change) => change.objectApiName))
   const drift: Array<{ objectApiName: string; datasetName: string; currentDigest: string }> = []
-  if (plan.drift.length > 0) {
-    // One pass over the datasets, not two: the revisions are read once and both the
-    // revision→name map and the current-revision map are built from the same reads.
-    const names = new Map<string, string>()
-    const currentByDataset = new Map<string, { id: string; schemaDigest?: string }>()
-    for (const dataset of await readableDatasets(client) ?? []) {
-      if (!dataset.id || !dataset.name) continue
-      const revisions = await client.datasetRevisions(dataset.id)
-      for (const revision of revisions) {
-        if (revision.id) names.set(revision.id, dataset.name)
-      }
-      const current = pickCurrentRevision(dataset, revisions)
-      if (current?.id) currentByDataset.set(dataset.name, { id: current.id, schemaDigest: current.schemaDigest })
-    }
-    for (const pin of plan.drift) {
-      const datasetName = names.get(pin.datasetRevisionId)
-      if (!datasetName) continue
-      const current = currentByDataset.get(datasetName)
-      if (!current?.schemaDigest || current.schemaDigest === pin.pinnedDigest) continue
-      drift.push({ objectApiName: pin.objectApiName, datasetName, currentDigest: current.schemaDigest })
-    }
+  for (const pin of plan.drift) {
+    const datasetName = datasets?.nameByRevisionId.get(pin.datasetRevisionId)
+    if (!datasetName || rebound.has(pin.objectApiName)) continue
+    const current = datasets?.current.get(datasetName)
+    if (!current?.schemaDigest || current.schemaDigest === pin.pinnedDigest) continue
+    drift.push({ objectApiName: pin.objectApiName, datasetName, currentDigest: current.schemaDigest })
   }
   const inherits = inheritance(ctx)
   const actionProblems = actionRuleProblems(files, inherits.conflict)
@@ -1341,8 +1389,8 @@ export const blueprintApply: Command = {
 
     // Drift is REPORTED, and blocks only the artifacts it is about. It used to throw
     // before the plan was even shown, so a colleague's type reading a moved dataset
-    // refused an unrelated creation and hid what the run would have done. A rebind is
-    // `bind`'s act either way — the plan says so on the line.
+    // refused an unrelated creation and hid what the run would have done. Re-binding to
+    // the same Dataset's new revision is `bind`'s act; the plan says so on the line.
     const driftingNames = new Set(drift.map((entry) => entry.objectApiName))
     const blocked = plan.operations.filter((operation) =>
       operation.kind === 'object-type' && driftingNames.has(operation.apiName))
@@ -1354,6 +1402,16 @@ export const blueprintApply: Command = {
       )
     }
 
+    // A rebind that cannot be sent stops the run before any write, with what to run instead.
+    const refused = plan.rebind.filter((change): change is Extract<RebindChange, { refused: string }> => 'refused' in change)
+    if (refused.length > 0) {
+      throw new CliError(
+        refused.map((change) => `${change.objectApiName} cannot move to Dataset "${change.to}": ${change.refused}.`).join('\n')
+        + '\nNothing was applied.',
+        { code: 'CONFLICT', hint: refused.map((change) => change.next).join('\n') },
+      )
+    }
+
     // BOTH orderings resolved before the confirmation, not inside the write loop.
     // Each refuses a mutual `compensationAction` pair, and a refusal that arrives
     // after the creates have committed leaves the draft half-applied — which is what
@@ -1367,9 +1425,10 @@ export const blueprintApply: Command = {
     const ordered = orderForApply(plan.operations)
     const orderedPrunes = prune ? orderForPrune(plan.prunes, liveCompensations(definition)) : []
 
+    const changeCount = plan.operations.length + plan.editable.length + plan.rebind.length
     if (ctx.flags.yes !== true) {
       throw new CliError(
-        `This would apply ${plan.operations.length} change${plan.operations.length === 1 ? '' : 's'}.\n`
+        `This would apply ${changeCount} change${changeCount === 1 ? '' : 's'}.\n`
         + `${renderPlan(plan, { prune })}\n\nRe-run with --yes to apply.`,
         { code: 'USAGE', hint: 'frontera blueprint apply --yes' },
       )
@@ -1398,6 +1457,23 @@ export const blueprintApply: Command = {
           }),
         ),
       }
+      // First, so a property this run adds can read a column only the new Dataset publishes.
+      // The file naming the Dataset is the decision `--accept-contract-change` stands for in `bind`.
+      for (const change of plan.rebind) {
+        if ('refused' in change) continue
+        current = `update object-type ${change.objectApiName} dataset: ${change.from ?? '(none)'} → ${change.to}`
+        try {
+          revision = (await client.draftCommand(datasetBindingCommand(change.objectId, change.datasetRevisionId, change.columnMappings, true), revision)).revision
+        } catch (err) {
+          if (!(err instanceof CliError)) throw err
+          throw new CliError(`backing.dataset (${change.to}) was refused: ${err.message}`, {
+            code: err.code,
+            hint: `frontera blueprint bind ${change.objectApiName} --dataset ${change.to} --plan ./map.json`,
+            cause: err,
+          })
+        }
+        applied.push(current)
+      }
       for (const operation of ordered) {
         const file = byKey.get(`${operation.kind}:${operation.apiName}`)!
         current = `${operation.operation} ${operation.kind} ${operation.apiName}`
@@ -1411,6 +1487,24 @@ export const blueprintApply: Command = {
           applied.push(current)
         }
       }
+      // Last, against the draft as these writes left it: a type created above has its
+      // id, and a property added above can be named.
+      if (plan.editable.length) {
+        const after = await client.draft()
+        revision = after.revision
+        for (const change of editableChanges(files, after.definition)) {
+          current = `update object-type ${change.objectApiName}`
+          const objectId = after.definition.objects.find((object) => object.apiName === change.objectApiName)?.id
+          if (!objectId) throw new CliError(`No object type "${change.objectApiName}" on the draft to declare editable fields on.`, { code: 'NOT_FOUND', hint: 'frontera blueprint plan — re-plan against the current draft, then re-apply.' })
+          try {
+            revision = (await client.draftCommand({ kind: 'set_editable_properties', objectId, editableProperties: change.to }, revision)).revision
+          } catch (err) {
+            if (!(err instanceof CliError)) throw err
+            throw new CliError(`backing.editable (${change.to.join(', ') || 'none'}) was refused: ${err.message}`, { code: err.code, ...(err.hint ? { hint: err.hint } : {}), cause: err })
+          }
+          applied.push(`${current} editable: ${change.to.join(', ') || '(none)'}`)
+        }
+      }
       current = null
     } catch (err) {
       // What landed is as important as what failed: the draft is shared, and a

package/src/commands/blueprint/editable.ts

@@ -5,11 +5,9 @@ import type { Command, CommandContext } from '../types'
 /**
  * Declare which properties a governed Action may write.
  *
- * The `set_editable_properties` draft command has existed since the edit
- * overlay landed, and until now nothing called it: `apply` excludes backings
- * from its diff (`bind` owns them) and `bind` sends only the column mapping.
- * So the one declaration standing between a published ontology and an Action
- * that can change it was reachable by raw HTTP alone.
+ * The `set_editable_properties` draft command, for one object type at a time.
+ * `apply` sends the same command for every file whose `backing.editable`
+ * differs from the draft; this verb reads or changes the set without a file.
  *
  * It is its own verb rather than a flag on `bind` because narrowing the set is
  * a governed act with its own consequence — an edit already stored against a

package/src/commands/knowledge/index-commands.ts

@@ -26,6 +26,19 @@ interface KnowledgeRow {
 }
 
 
+/**
+ * These commands manage the knowledge bases Agents attach. The Knowledge app's
+ * bases (organization and workspace) are another thing with no command or
+ * project file, and no local runtime runs the app. Said only where the
+ * platform runs the app: elsewhere there is no such base to mistake for one.
+ */
+async function knowledgeAppNote(api: PlatformApi): Promise<string> {
+  return (await api.knowledgeAppRuns())
+    ? ' A knowledge base from the Knowledge app is not one of these: it runs on the platform only, not on a local runtime. '
+      + 'Choose it for an Agent on the platform, under the Agent\'s Knowledge page, and test that Agent there.'
+    : ''
+}
+
 /** Accept a base by name or id — `knowledge list` shows both. */
 async function resolveKnowledgeRef(client: PlatformApi, ref: string): Promise<string> {
   const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
@@ -38,7 +51,7 @@ async function resolveKnowledgeRef(client: PlatformApi, ref: string): Promise<st
 
   throw new CliError(`no knowledge base named "${ref}"`, {
     code: 'NOT_FOUND',
-    hint: `known bases: ${rows.map((k) => k.name).filter(Boolean).join(', ') || '(none)'}`,
+    hint: `known bases: ${rows.map((k) => k.name).filter(Boolean).join(', ') || '(none)'}.${await knowledgeAppNote(client)}`,
   })
 }
 
@@ -61,7 +74,7 @@ const list: Command = {
       data: rows,
       text:
         rows.length === 0
-          ? 'No knowledge bases in this workspace.'
+          ? `No knowledge bases in this workspace.${await knowledgeAppNote(api)}`
           : // NAME first: it is the value `knowledge sources` takes, not the id.
             // No `displayName` on these rows, so a column for it was always
             // blank and shifted the description out of alignment.