@frontera-sdk/cli 1.53.25 → 1.53.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.53.25",
+  "version": "1.53.27",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,8 +40,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.53.25",
-    "@frontera-sdk/functions": "1.53.25",
+    "@frontera-sdk/core": "1.53.27",
+    "@frontera-sdk/functions": "1.53.27",
     "ai": "^6.0.319",
     "axe-core": "4.12.1",
     "gray-matter": "^4.0.3",
@@ -49,7 +49,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.53.25",
+    "@frontera-sdk/forge-contracts": "1.53.27",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

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

@@ -449,6 +449,180 @@ const testSource: Command = {
   },
 }
 
+type DatasetDefinition = {
+  common: { apiName: string; displayName: string; description?: string; keyColumns: string[] | null; deterministicKeyConfirmed: boolean }
+} & (
+  | { kind: 'blank'; columns: DatasetColumn[] }
+  | { kind: 'source'; source: string; schema: string; relation: string; includedColumns: string[] }
+  | { kind: 'file'; csv: string; csvPath: string; includedColumns: string[]; declared: Map<string, { nullable?: boolean; databaseType?: string }> | null }
+)
+
+/**
+ * A dataset definition as `dataset create` reads it, refused for everything
+ * that needs no service to tell. `local dev` checks a dataset the runtime
+ * holds with it too, since it loads that one's CSV without `create`.
+ */
+export function readDatasetDefinition(path: string, filePath: string): DatasetDefinition {
+  let document: DatasetFile
+  try {
+    document = JSON.parse(readFileSync(path, 'utf8')) as DatasetFile
+  } catch (e) {
+    // The likeliest way to get here is handing over the CSV itself — the
+    // summary says "from … a CSV" and this is the only flag. That used to be
+    // a raw parser crash: `INTERNAL_ERROR: JSON Parse error: Unexpected
+    // identifier "id"`, exit 1, naming the first CSV header as the fault.
+    throw new CliError(`${filePath} is not a JSON definition: ${(e as Error).message}`, {
+      code: 'USAGE',
+      hint: filePath.toLowerCase().endsWith('.csv')
+        ? '--file takes the definition document, not the CSV. To ingest a CSV, the document '
+          + 'names it: { "apiName": "…", "kind": "file", "path": "./' + basename(filePath) + '" }'
+        : 'the document is JSON: { apiName, kind: blank | source | file, … } — see `frontera dataset create --help`',
+    })
+  }
+
+  const apiName = document.apiName
+  if (typeof apiName !== 'string' || !apiName) {
+    throw new CliError(`${filePath} names no \`apiName\`.`, {
+      code: 'USAGE',
+      hint: 'apiName is how `backing.dataset` and `blueprint bind` refer to it.',
+    })
+  }
+  const displayName = typeof document.displayName === 'string' && document.displayName
+    ? document.displayName
+    : apiName
+  const description = typeof document.description === 'string'
+    ? { description: document.description }
+    : {}
+
+  const keyColumns = document.keyColumns === undefined || document.keyColumns === null
+    ? null
+    : document.keyColumns
+  if (keyColumns !== null && !Array.isArray(keyColumns)) {
+    throw new CliError(`${filePath} has \`keyColumns\` that is neither a list nor null.`, {
+      code: 'USAGE',
+      hint: 'keyColumns: ["id"] for a keyed dataset, or null when no column identifies a row.',
+    })
+  }
+  // Only ever true when the file DECLARED key columns. The flag attests that the key
+  // identifies a row uniquely, and attesting that of a key nobody named is a claim
+  // the file never made.
+  const deterministicKeyConfirmed = document.deterministicKeyConfirmed === true && keyColumns !== null
+  const common = {
+    apiName,
+    displayName,
+    ...description,
+    keyColumns: keyColumns as string[] | null,
+    deterministicKeyConfirmed,
+  }
+
+  /**
+   * `kind` defaults to blank, and blank reads NOTHING — so a document that
+   * carried `source` or `path` without saying `kind` was created as an empty
+   * schema, its row-bearing keys silently dropped. "Created" was the whole
+   * answer, and the caller found the zero rows later, somewhere else.
+   *
+   * The default stays, because a plain columns document is the common case
+   * and has always worked. What goes is the silence: keys that only mean
+   * something under another kind refuse rather than vanish.
+   */
+  const doc = document as Record<string, unknown>
+  const kind = document.kind ?? 'blank'
+
+  const KIND_KEYS: Record<string, Set<string>> = {
+    blank: new Set(['columns']),
+    source: new Set(['source', 'schema', 'relation', 'includedColumns']),
+    // `columns`: what the file declares of each column (its nullability, its type) instead of
+    // leaving both to the first CSV, whose contract every later upload must then match.
+    file: new Set(['path', 'includedColumns', 'columns']),
+  }
+  const COMMON = new Set([
+    'apiName', 'displayName', 'description', 'kind', 'keyColumns', 'deterministicKeyConfirmed',
+  ])
+  // Where a stray key probably meant to point. `csv`, `rows` and `data` are
+  // what people actually reached for when probing how rows get in.
+  const MEANT: Record<string, string> = {
+    csv: 'kind: "file" with `path`',
+    rows: 'kind: "file" with `path` (rows ride in the CSV)',
+    data: 'kind: "file" with `path`',
+    source: 'kind: "source"',
+    path: 'kind: "file"',
+    schema: 'kind: "source"',
+    relation: 'kind: "source"',
+  }
+
+  const allowed = KIND_KEYS[kind as string] ?? new Set<string>()
+  const strays = Object.keys(doc).filter((k) => !COMMON.has(k) && !allowed.has(k))
+  if (strays.length > 0) {
+    const guesses = strays
+      .map((k) => (MEANT[k] && !allowed.has(k) ? `\`${k}\` belongs to ${MEANT[k]}` : null))
+      .filter(Boolean)
+    const named = strays.map((k) => '`' + k + '`').join(', ')
+    const strayHint = guesses.length > 0
+      ? `${guesses.join('; ')} — say the kind explicitly, it does not default from the keys`
+      : `kind "${kind}" reads: ${[...COMMON, ...allowed].join(', ')}`
+    throw new CliError(`${filePath} carries ${named}, which kind "${kind}" does not read.`, {
+      code: 'USAGE',
+      hint: strayHint,
+    })
+  }
+
+  if (kind === 'blank') {
+    const columns = readColumns(document.columns, filePath)
+    const declared = new Set(columns.map((column) => column.name))
+    for (const key of (keyColumns ?? []) as string[]) {
+      if (!declared.has(key)) {
+        throw new CliError(`${filePath}: keyColumns names "${key}", which is not a declared column.`, {
+          code: 'USAGE',
+          hint: `Declared: ${[...declared].join(', ')}`,
+        })
+      }
+    }
+    return { common, kind, columns }
+  }
+  if (kind === 'source') {
+    const source = document.source
+    if (typeof source !== 'string' || !source) {
+      throw new CliError(`${filePath} names no \`source\`.`, {
+        code: 'USAGE',
+        hint: 'frontera dataset sources — the file names one by displayName, never by id.',
+      })
+    }
+    const schema = document.schema
+    const relation = document.relation
+    if (typeof schema !== 'string' || !schema || typeof relation !== 'string' || !relation) {
+      throw new CliError(`${filePath} needs both \`schema\` and \`relation\`.`, {
+        code: 'USAGE',
+        hint: 'The relation this dataset pulls, e.g. schema: public, relation: customers.',
+      })
+    }
+    return { common, kind, source, schema, relation, includedColumns: names(document.includedColumns, 'includedColumns', filePath) }
+  }
+  if (kind === 'file') {
+    const csv = document.path
+    if (typeof csv !== 'string' || !csv) {
+      throw new CliError(`${filePath} names no \`path\` to a CSV.`, {
+        code: 'USAGE',
+        hint: 'path is resolved relative to the definition file, so the pair can move together.',
+      })
+    }
+    const includedColumns = names(document.includedColumns, 'includedColumns', filePath)
+    return {
+      common,
+      kind,
+      csv,
+      // Relative to the DEFINITION, not the shell's cwd: the two travel together in a
+      // repo, and resolving against cwd broke the moment anyone ran it from elsewhere.
+      csvPath: resolve(dirname(path), csv),
+      includedColumns,
+      declared: document.columns === undefined ? null : readFileColumns(document.columns, includedColumns, filePath),
+    }
+  }
+  throw new CliError(`${filePath} has an unknown \`kind\`: ${String(kind)}.`, {
+    code: 'USAGE',
+    hint: 'One of: blank, source, file.',
+  })
+}
+
 const create: Command = {
   meta: {
     noun: 'dataset',
@@ -475,134 +649,16 @@ const create: Command = {
         hint: 'The file names a `kind`: blank, source, or file.',
       })
     }
-    const path = resolve(ctx.cwd, filePath)
-    let document: DatasetFile
-    try {
-      document = JSON.parse(readFileSync(path, 'utf8')) as DatasetFile
-    } catch (e) {
-      // The likeliest way to get here is handing over the CSV itself — the
-      // summary says "from … a CSV" and this is the only flag. That used to be
-      // a raw parser crash: `INTERNAL_ERROR: JSON Parse error: Unexpected
-      // identifier "id"`, exit 1, naming the first CSV header as the fault.
-      throw new CliError(`${filePath} is not a JSON definition: ${(e as Error).message}`, {
-        code: 'USAGE',
-        hint: filePath.toLowerCase().endsWith('.csv')
-          ? '--file takes the definition document, not the CSV. To ingest a CSV, the document '
-            + 'names it: { "apiName": "…", "kind": "file", "path": "./' + basename(filePath) + '" }'
-          : 'the document is JSON: { apiName, kind: blank | source | file, … } — see `frontera dataset create --help`',
-      })
-    }
-
-    const apiName = document.apiName
-    if (typeof apiName !== 'string' || !apiName) {
-      throw new CliError(`${filePath} names no \`apiName\`.`, {
-        code: 'USAGE',
-        hint: 'apiName is how `backing.dataset` and `blueprint bind` refer to it.',
-      })
-    }
-    const displayName = typeof document.displayName === 'string' && document.displayName
-      ? document.displayName
-      : apiName
-    const description = typeof document.description === 'string'
-      ? { description: document.description }
-      : {}
-
-    const keyColumns = document.keyColumns === undefined || document.keyColumns === null
-      ? null
-      : document.keyColumns
-    if (keyColumns !== null && !Array.isArray(keyColumns)) {
-      throw new CliError(`${filePath} has \`keyColumns\` that is neither a list nor null.`, {
-        code: 'USAGE',
-        hint: 'keyColumns: ["id"] for a keyed dataset, or null when no column identifies a row.',
-      })
-    }
-    // Only ever true when the file DECLARED key columns. The flag attests that the key
-    // identifies a row uniquely, and attesting that of a key nobody named is a claim
-    // the file never made.
-    const deterministicKeyConfirmed = document.deterministicKeyConfirmed === true && keyColumns !== null
-    const common = {
-      apiName,
-      displayName,
-      ...description,
-      keyColumns: keyColumns as string[] | null,
-      deterministicKeyConfirmed,
-    }
-
+    const definition = readDatasetDefinition(resolve(ctx.cwd, filePath), filePath)
+    const { common } = definition
+    const apiName = common.apiName
     const api = new DatasetApi(ctx.apiUrl, ctx.token)
-
-    /**
-     * `kind` defaults to blank, and blank reads NOTHING — so a document that
-     * carried `source` or `path` without saying `kind` was created as an empty
-     * schema, its row-bearing keys silently dropped. "Created" was the whole
-     * answer, and the caller found the zero rows later, somewhere else.
-     *
-     * The default stays, because a plain columns document is the common case
-     * and has always worked. What goes is the silence: keys that only mean
-     * something under another kind refuse rather than vanish.
-     */
-    const doc = document as Record<string, unknown>
-    const kind = document.kind ?? 'blank'
-
-    const KIND_KEYS: Record<string, Set<string>> = {
-      blank: new Set(['columns']),
-      source: new Set(['source', 'schema', 'relation', 'includedColumns']),
-      // `columns`: what the file declares of each column (its nullability, its type) instead of
-      // leaving both to the first CSV, whose contract every later upload must then match.
-      file: new Set(['path', 'includedColumns', 'columns']),
-    }
-    const COMMON = new Set([
-      'apiName', 'displayName', 'description', 'kind', 'keyColumns', 'deterministicKeyConfirmed',
-    ])
-    // Where a stray key probably meant to point. `csv`, `rows` and `data` are
-    // what people actually reached for when probing how rows get in.
-    const MEANT: Record<string, string> = {
-      csv: 'kind: "file" with `path`',
-      rows: 'kind: "file" with `path` (rows ride in the CSV)',
-      data: 'kind: "file" with `path`',
-      source: 'kind: "source"',
-      path: 'kind: "file"',
-      schema: 'kind: "source"',
-      relation: 'kind: "source"',
-    }
-
-    const allowed = KIND_KEYS[kind as string] ?? new Set<string>()
-    const strays = Object.keys(doc).filter((k) => !COMMON.has(k) && !allowed.has(k))
-    if (strays.length > 0) {
-      const guesses = strays
-        .map((k) => (MEANT[k] && !allowed.has(k) ? `\`${k}\` belongs to ${MEANT[k]}` : null))
-        .filter(Boolean)
-      const named = strays.map((k) => '`' + k + '`').join(', ')
-      const strayHint = guesses.length > 0
-        ? `${guesses.join('; ')} — say the kind explicitly, it does not default from the keys`
-        : `kind "${kind}" reads: ${[...COMMON, ...allowed].join(', ')}`
-      throw new CliError(`${filePath} carries ${named}, which kind "${kind}" does not read.`, {
-        code: 'USAGE',
-        hint: strayHint,
-      })
-    }
-
     let created
 
-    if (kind === 'blank') {
-      const columns = readColumns(document.columns, filePath)
-      const declared = new Set(columns.map((column) => column.name))
-      for (const key of (keyColumns ?? []) as string[]) {
-        if (!declared.has(key)) {
-          throw new CliError(`${filePath}: keyColumns names "${key}", which is not a declared column.`, {
-            code: 'USAGE',
-            hint: `Declared: ${[...declared].join(', ')}`,
-          })
-        }
-      }
-      created = await api.createBlank({ ...common, columns })
-    } else if (kind === 'source') {
-      const sourceName = document.source
-      if (typeof sourceName !== 'string' || !sourceName) {
-        throw new CliError(`${filePath} names no \`source\`.`, {
-          code: 'USAGE',
-          hint: 'frontera dataset sources — the file names one by displayName, never by id.',
-        })
-      }
+    if (definition.kind === 'blank') {
+      created = await api.createBlank({ ...common, columns: definition.columns })
+    } else if (definition.kind === 'source') {
+      const sourceName = definition.source
       // Named, not id'd: a Source id is minted per deployment, so a definition
       // carrying one would be correct here and wrong in the next organization —
       // the same reason nothing in a Blueprint tree carries a uuid.
@@ -616,34 +672,15 @@ const create: Command = {
             : `Visible: ${all.map((entry) => entry.displayName).filter(Boolean).join(', ')}`,
         })
       }
-      const schema = document.schema
-      const relation = document.relation
-      if (typeof schema !== 'string' || !schema || typeof relation !== 'string' || !relation) {
-        throw new CliError(`${filePath} needs both \`schema\` and \`relation\`.`, {
-          code: 'USAGE',
-          hint: 'The relation this dataset pulls, e.g. schema: public, relation: customers.',
-        })
-      }
       created = await api.createFromSource({
         ...common,
         sourceId: source.id,
-        schema,
-        relation,
-        includedColumns: names(document.includedColumns, 'includedColumns', filePath),
+        schema: definition.schema,
+        relation: definition.relation,
+        includedColumns: definition.includedColumns,
       })
-    } else if (kind === 'file') {
-      const csv = document.path
-      if (typeof csv !== 'string' || !csv) {
-        throw new CliError(`${filePath} names no \`path\` to a CSV.`, {
-          code: 'USAGE',
-          hint: 'path is resolved relative to the definition file, so the pair can move together.',
-        })
-      }
-      // Relative to the DEFINITION, not the shell's cwd: the two travel together in a
-      // repo, and resolving against cwd broke the moment anyone ran it from elsewhere.
-      const csvPath = resolve(dirname(path), csv)
-      const included = names(document.includedColumns, 'includedColumns', filePath)
-      const declared = document.columns === undefined ? null : readFileColumns(document.columns, included, filePath)
+    } else {
+      const { csv, csvPath, includedColumns: included, declared } = definition
       if (!declared) {
         created = await api.createFromFile(csvPath, { ...common, includedColumns: included })
       } else {
@@ -656,11 +693,6 @@ const create: Command = {
         }
         created = await api.uploadSnapshot(blank.id, csvPath)
       }
-    } else {
-      throw new CliError(`${filePath} has an unknown \`kind\`: ${String(kind)}.`, {
-        code: 'USAGE',
-        hint: 'One of: blank, source, file.',
-      })
     }
 
     return {
@@ -668,7 +700,7 @@ const create: Command = {
       // Blank is a CONTRACT with no rows, and that surprised everyone who
       // reached it by default. Said here, at creation, rather than left for
       // `dataset rows` to reveal after the binding is already built.
-      text: `Created dataset "${apiName}"${kind === 'blank'
+      text: `Created dataset "${apiName}"${definition.kind === 'blank'
         ? ` — declared columns only, no rows. Load them with \`frontera dataset upload ${apiName} ./rows.csv\`,`
           + ' or create with kind "file" (a CSV) or kind "source" instead.'
         : '.'} `

package/src/commands/local/dev.ts

@@ -8,7 +8,7 @@ import { CliError, UsageError } from '../../errors'
 import { ensureProjectBunfig } from '../../local/local-scaffold'
 import { llmParameterNotes } from '../../local/local-model-parameters'
 import { findOrphans, orphanCalls, restoreIfArchived, retireDeleted, reviveFunction, runtimeItems } from '../../local/local-orphans'
-import { adaptationOf, contentHash, refOfTarget, failureCodeAndHint, isEnvironmentNote, loadBuild, loadHashes, oneLine, promotedVersionOf, pruneBuild, recordBuild, recordSettingsDifferences, saveHashes, type BuildEntry } from '../../local/local-applied'
+import { adaptationOf, contentHash, refOfTarget, failureCodeAndHint, isEnvironmentNote, loadBuild, loadHashes, oneLine, promotedVersionOf, pruneBuild, recordBuild, recordSettingsDifferences, refusedForColumns, saveHashes, type BuildEntry } from '../../local/local-applied'
 import { INHERITED_FROM_PULL } from '../../blueprint/action-rules'
 import { actionsNotRunning, deployActions, ensureActionDraft, liveActionStates, localActionCalls, prepareActions, retireActions, staleActions, unpublishedActions, type ActionBuild } from '../../local/local-actions'
 import { agentIdentity, hasAgentDraft, syncAgentName } from '../../local/local-agent-name'
@@ -20,6 +20,7 @@ import {
   blueprintObjectTypes,
   byApplyOrder,
   commandFor,
+  datasetDocument,
   fallbackFor,
   describeTarget,
   followUpsFor,
@@ -43,6 +44,7 @@ import { applyOperatingConfig } from '../../local/local-operating'
 import { localEmbeddingsReachable } from '../../local/local-keys'
 import { mirrorOrgSettings, settingsCalls } from '../../local/local-org-settings'
 import { directoryOf, readSnapshot } from '../../local/local-sync-snapshot'
+import { syncClient } from '../../local/local-sync-client'
 import { BUNDLE_ID_MAP_ENV, bundleIdMap, functionCodeFiles, hardCodedIdLine, hardCodedObjectTypeIds, platformObjectTypeIds } from '../../local/local-function-ids'
 import { checkRunnable, functionSlugOf, mirrorFunctionState } from '../../local/local-function-state'
 import { functionSecretNames, localSecretPresence, missingSecretLines, readProjectDoc, readProjectText, workflowSecretNames } from '../../local/local-secrets'
@@ -67,6 +69,7 @@ import { canChangeRuntime, filesChangedTrigger, readApplies, recordApply } from
 import { failedForRuntime, RUNTIME_DOWN_ERROR, RUNTIME_STOPPED_LINE, runtimeAnswering } from '../../local/local-runtime-health'
 import { noticeLines, projectNotices } from '../../local/local-project-notices'
 import { refreshVendoredSdk, vendoredSdkState } from '../../local/local-vendored-sdk'
+import { readDatasetDefinition } from '../dataset/index-commands'
 import { flagBool, type Command, type CommandContext } from '../types'
 import { applyEvents } from '../../telemetry/apply-events'
 import { recordExit } from '../../telemetry/cli-telemetry'
@@ -268,7 +271,16 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
   if (target.kind === 'dataset') {
     const media = mediaCatalogDatasetReason(project.root, target.apiName)
     if (media) return { ok: true, output: `  warning: dataset ${target.apiName} is skipped here: ${media}` }
+    // Refused as `dataset create` refuses it, before anything is asked: one the runtime holds is loaded without `create`.
+    try {
+      readDatasetDefinition(join(project.root, target.file), target.file)
+    } catch (err) {
+      if (!(err instanceof CliError)) throw err
+      return withNotes({ ok: false, output: [`error [${err.code}]: ${err.message}`, ...(err.hint ? [`  ${err.hint}`] : [])].join('\n') })
+    }
   }
+  // A dataset the runtime holds already takes its rows as a snapshot (`fallbackFor`): `dataset create` would be refused, every apply.
+  const held = target.kind === 'dataset' && creds ? await datasetOnRuntime(opts.serviceUrl, creds.orgKey, datasetDocument(project.root, target)?.apiName ?? target.apiName) : false
   if (resolved.file) target = { ...target, file: resolved.file } as SyncTarget
   // A Function whose code hard-codes the workspace's object type ids (a pulled one): said, and its
   // bundle here built with this runtime's ids in their place; the files keep the workspace's.
@@ -328,7 +340,7 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
         if (draft.note) notes = [notes, `  warning: ${draft.note}`].filter(Boolean).join('\n')
       }
     }
-    result = withNotes(await runCli(project, command, opts.auth, bundleEnv))
+    result = held ? { ok: false, output: '' } : withNotes(await runCli(project, command, opts.auth, bundleEnv))
     if (blueprint && !result.ok && refused.size < MAX_REFUSED) {
       const stop = refusedArtifact(result.output)
       if (stop && !refused.has(stop.key)) {
@@ -345,7 +357,7 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
     break
   }
   const fallback = fallbackFor(target, profiles, project.root)
-  if (!result.ok && fallback?.when.test(result.output)) {
+  if (fallback && (held || (!result.ok && fallback.when.test(result.output)))) {
     // An empty fallback means there was nothing more to do.
     result = { ok: true, output: '' }
     for (const args of fallback.steps) {
@@ -359,7 +371,8 @@ async function apply(project: LocalProject, target: SyncTarget, opts: ApplyOptio
     // fits its revision, so the definition becomes the dataset's next revision.
     if (!result.ok && target.kind === 'dataset' && /requires a new revision/i.test(result.output)) {
       const revised = await runCli(project, ['dataset', 'revise', '-f', target.file, '--profile', profiles.organization], opts.auth)
-      if (!revised.ok) return { ...revised, output: [result.output.trim(), revised.output.trim()].join('\n') }
+      // The revision's refusal names the column and the way out; the upload's "requires a new revision" was answered by trying it.
+      if (!revised.ok) return withNotes(revised)
       // Each object type reading it is bound to the new revision (a binding is pinned to the revision it was made on).
       const rebound = await rebindReaders(project, target.apiName, profiles, (args) => runCli(project, args, opts.auth))
       if (!rebound.ok) return rebound
@@ -652,6 +665,22 @@ async function rebindReaders(project: LocalProject, dataset: string, profiles: S
   return { ok: true, output: lines.join('\n') }
 }
 
+/** Whether the runtime holds a dataset of this apiName; null when it could not say (then `dataset create` finds out). */
+export async function datasetOnRuntime(serviceUrl: string, orgKey: string, apiName: string): Promise<boolean | null> {
+  const org = syncClient(serviceUrl, orgKey)
+  try {
+    let cursor: string | null | undefined
+    do {
+      const page = await org.get<{ items?: Array<{ apiName?: string }>; nextCursor?: string | null }>(`/v1/data-integration/datasets?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''}`)
+      if (page.items?.some((d) => d.apiName === apiName)) return true
+      cursor = page.nextCursor
+    } while (cursor)
+    return false
+  } catch {
+    return null
+  }
+}
+
 /** The local runner's loopback address, to ask it to sync a deploy at once. */
 function runnerAt(project: LocalProject): { runnerUrl?: string } {
   const port = readState(project)?.ports.runner
@@ -842,7 +871,8 @@ async function dev(ctx: CommandContext) {
   }
 
   const organizationId = state.credentials!.organizationId
-  const applied = flagBool(ctx, 'reapply') ? new Map<string, string | null>() : loadHashes(project, organizationId)
+  const reapply = flagBool(ctx, 'reapply')
+  const applied = reapply ? new Map<string, string | null>() : loadHashes(project, organizationId)
 
   // The organization's settings as the last fetch read them: the timezone is taken, every
   // other difference is said here and in the build summary.
@@ -930,6 +960,13 @@ async function dev(ctx: CommandContext) {
     if (stopping) return
     if (target.kind !== 'blueprint' && !existsSync(join(project.root, target.file))) return
     const hash = contentHash(project, target)
+    const recorded = loadBuild(project, organizationId)[target.key]
+    // A dataset refused for its columns is refused again while its files are the same: said, not applied again.
+    if (target.kind === 'dataset' && hash && !reapply && recorded?.status === 'failed' && recorded.hash === hash && refusedForColumns(recorded.error)) {
+      failing.set(target.key, { item: describeTarget(target), error: recorded.error! })
+      ctx.output.note(`  ✕ ${describeTarget(target)}: ${recorded.error} Not applied again until its files change (--reapply tries it now).`)
+      return
+    }
     // Unchanged files, but the runtime lost the Agent's draft (it was published): the draft is
     // what its test cases and Studio's Draft chat run, so it is staged again from the files.
     const draftGone = hash && applied.get(target.key) === hash && target.kind === 'agent' && (await hasAgentDraft({ slug: target.slug, serviceUrl, creds })) === false
@@ -940,7 +977,6 @@ async function dev(ctx: CommandContext) {
     for (const a of actionsDown) ctx.output.note(`  governed Action ${a.apiName} doesn’t run on the runtime (${a.why}): applying the Blueprint again`)
     // Unchanged, but applied before the build recorded which version the file was pushed as:
     // pushed once more, so its tests run exactly that version (never a stale draft).
-    const recorded = loadBuild(project, organizationId)[target.key]
     const versionUnknown = hash && applied.get(target.key) === hash && target.kind === 'workflow' && (!recorded || (recorded.status !== 'failed' && recorded.status !== 'blocked' && recorded.version === undefined))
     if (versionUnknown) ctx.output.note(`  ${describeTarget(target)}: pushing ${target.file} again to record the version it runs as`)
     // A knowledge base's threshold follows the runtime's embeddings (`knowledgeSettings`): when they changed since
@@ -1077,7 +1113,9 @@ async function dev(ctx: CommandContext) {
       // A failed apply may have changed the runtime (an Action retired, switched off): the file is not
       // "unchanged" afterwards, even when it is restored to what last applied.
       if (applied.delete(target.key)) saveHashes(project, organizationId, applied)
-      failed.set(target.key, target)
+      // A dataset refused for its columns is refused again whatever else applies (`runOne`); any other failure is tried
+      // again after progress, as a dataset's rebind can wait on the Blueprint and a storage error can pass.
+      if (target.kind !== 'dataset' || !refusedForColumns(applyFailureReason(result.output))) failed.set(target.key, target)
       events.item(target, 'failed', round.cause, ms, { output: result.output })
       // A retry that fails the same way is not said again in the same round of changes.
       // A governed Action's checks are each a line to fix: shown whole, not cut to the first seven lines.

package/src/exit.ts

@@ -507,3 +507,25 @@ export function sessionLaneFailure(
   if (err instanceof CliError) return null
   return new CliError(failure.message, { code: failure.code, hint, cause: err })
 }
+
+/** What a fetch fails with when the platform never answered: refused, no such host, no route to it. Bun's own names too. */
+const NO_ANSWER = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH', 'ETIMEDOUT', 'ConnectionRefused', 'FailedToOpenSocket'])
+
+/**
+ * A request that never reached the platform, as one failure whichever client
+ * sent it: `UNAVAILABLE`, "<origin> did not answer: …", the origin the fetch
+ * tried (Bun names it) or else the command's. When that origin is the
+ * project's own local runtime, the hint is to start it. Null for any other failure.
+ */
+export function unreachableFailure(err: unknown, apiUrl: string, isLocalRuntime: (origin: string) => boolean = () => false): CliError | null {
+  if (!(err instanceof Error) || !NO_ANSWER.has(String((err as { code?: unknown }).code))) return null
+  const tried = (err as { path?: unknown }).path
+  let origin = 'the platform'
+  try {
+    origin = new URL(typeof tried === 'string' && tried ? tried : apiUrl).origin
+  } catch {
+    // No address to name.
+  }
+  const hint = isLocalRuntime(origin) ? 'the project’s local runtime is not running: start it with `frontera local start`, then run the command again' : 'check the address and your network, then run the command again'
+  return new CliError(`${origin} did not answer: ${err.message}`, { code: 'UNAVAILABLE', hint, cause: err })
+}

package/src/local/local-applied.ts

@@ -179,6 +179,18 @@ export const IMPORT_MISSING_FIX = 'the pull couldn’t bring the files it import
  */
 export const EMBEDDING_MISSING_FIX = 'not its file: the runtime has no embedding model that runs. `frontera local status` says why under Setting and Embeddings; a key the provider refuses is replaced with `frontera local key-set <provider>`, and `frontera local stop` then `frontera local start` sets a model (the keyless local embeddings when no key works); the next `frontera local dev` reads it again'
 
+/** What fixes a dataset whose file retypes, adds or drops a column: no revision of the runtime's copy takes that. */
+export const DATASET_COLUMNS_FIX = 'make the CSV fit the columns the dataset has here again, give it another apiName (a new dataset), or run `frontera local reset`, which creates every dataset again from its definition'
+
+/**
+ * A dataset refused for its columns (`dataset revise`: one retyped, added or
+ * dropped). Applying the same files again is refused the same way; only they
+ * change it. Read from the error's start: a long list of columns is cut.
+ */
+export function refusedForColumns(error: string | undefined): boolean {
+  return /^The file (?:changes the type of|has no|carries) /.test(error ?? '')
+}
+
 /**
  * What fixes an item whose apply failed for these very files: the hint the
  * apply gave, what a known failure needs, else fixing the file. Applying the
@@ -187,6 +199,7 @@ export const EMBEDDING_MISSING_FIX = 'not its file: the runtime has no embedding
 export function failureFix(entry: Pick<BuildEntry, 'error' | 'code' | 'hint'>, file: string): string {
   if (entry.code === 'FUNCTION_IMPORT_MISSING' || /^imports .+, which (?:isn[’']t|aren[’']t) in the project/i.test(entry.error ?? '')) return IMPORT_MISSING_FIX
   if (/set this organization['’]s embedding model|embedding model .*is not available/i.test(entry.error ?? '')) return EMBEDDING_MISSING_FIX
+  if (refusedForColumns(entry.error)) return DATASET_COLUMNS_FIX
   if (entry.hint) return entry.hint
   return `change ${file} so the runtime takes it; \`frontera local dev\` applies it once the file changes`
 }

package/src/local/local-apply-error.ts

@@ -47,7 +47,10 @@ const GENERIC = /^(invalid workflow definition|blueprint validation is blocked|v
  * that says why: a blocker, a definition error, the hint.
  */
 export function applyFailureReason(output: string): string {
-  const text = applyErrorText(output)
+  const said = applyErrorText(output)
+  // `blueprint apply` leads with what landed ("Nothing was applied.", the list's bare `error [CODE]:`) and the step it stopped at; the reason is under them.
+  const reasons = said.split('\n').filter((l) => !/^(?:|Nothing was applied\.|Stopped at: .*)$/.test(oneLine(l)))
+  const text = reasons.length ? reasons.join('\n') : said
   const head = oneLine(text)
   if (!GENERIC.test(head)) return head
   const detail = text

package/src/local/local-runtime-health.ts

@@ -55,7 +55,7 @@ export async function runtimeAnswering(project: LocalProject, deps: HealthDeps =
 export async function failedForRuntime(project: LocalProject, output: string, deps: HealthDeps = {}): Promise<boolean> {
   if (!(await runtimeAnswering(project, deps))) return true
   const first = output.split('\n').find((l) => /^error/i.test(l.trim())) ?? ''
-  return /\[INTERNAL_ERROR\]/.test(first) && isConnectionError(first)
+  return /\[(?:INTERNAL_ERROR|UNAVAILABLE)\]/.test(first) && isConnectionError(first)
 }
 
 export interface DatabaseReadyOptions {

package/src/local/local-runtime-target.ts

@@ -1,3 +1,4 @@
+import { portBlockOf } from './local-ports'
 import { localProject, type LocalProject } from './local-project'
 import { isAlive, readState, type LocalCredentials, type LocalState } from './local-state'
 
@@ -40,3 +41,14 @@ export function localRuntimeAt(cwd: string, apiUrl: string): LocalRuntimeTarget
   if (!sameService(serviceUrl, apiUrl)) return null
   return { project, state, creds: state.credentials, serviceUrl }
 }
+
+/** Whether `apiUrl` is the service of the local runtime of the project `cwd` is in, running or not: the port it keeps. */
+export function isLocalRuntimeAddress(cwd: string, apiUrl: string): boolean {
+  try {
+    const project = localProject(cwd)
+    const port = readState(project)?.ports?.service ?? portBlockOf(project.id)?.service
+    return port !== undefined && sameService(`http://127.0.0.1:${port}`, apiUrl)
+  } catch {
+    return false
+  }
+}

package/src/main.ts

@@ -5,9 +5,9 @@ import { credentialStore } from './credential-store'
 import { readDeviceSession } from './device-login'
 import { findProjectRoot } from './context'
 import { CliError, UsageError } from './errors'
-import { EXIT, sessionLaneFailure, sessionLaneRefusal, type ExitCode } from './exit'
+import { EXIT, sessionLaneFailure, sessionLaneRefusal, unreachableFailure, type ExitCode } from './exit'
 import { actAsLocalPersona, listPersonas, localPersonaHint, redact } from './local/local-personas'
-import { localRuntimeAt } from './local/local-runtime-target'
+import { isLocalRuntimeAddress, localRuntimeAt } from './local/local-runtime-target'
 import { acquireLock, lockRefusal, locksRuntime, projectStateDir, recordWrite, writeCommand } from './local/local-writers'
 import { tokenFromStdin } from './mcp/mcp-apps'
 import { resolveOrganization, setSelectedOrganization } from './organization'
@@ -16,7 +16,7 @@ import { remoteFromLocalProject, remoteWords } from './remote-guard'
 import { createOutput, type OutputMode } from './output'
 import { readProject } from './project'
 import { commandScope, unaddressedWorkspaceRefusal } from './scopes'
-import { cliTelemetry, INTERRUPTED, invocationVia, projectHashAt, severityOfExit, TERMINATED } from './telemetry/cli-telemetry'
+import { cliTelemetry, INTERRUPTED, invocationVia, projectHashAt, projectNamesAt, severityOfExit, TERMINATED } from './telemetry/cli-telemetry'
 import { isBackground } from './telemetry/enabled'
 import { errorCode, errorFields } from './telemetry/redact'
 import {
@@ -96,7 +96,7 @@ function recordCommand(exitCode: number): void {
     const telemetry = cliTelemetry()
     if (telemetry.mode.mode === 'off') return
     const { failure } = invocation
-    const error = failure === undefined ? undefined : errorFields(errorCode((failure as { code?: unknown })?.code), failure instanceof Error ? failure.message : String(failure), invocation.names)
+    const error = failure === undefined ? undefined : errorFields(errorCode((failure as { code?: unknown })?.code), failure instanceof Error ? failure.message : String(failure), [...invocation.names, ...projectNamesAt(invocation.cwd)])
     const project = projectHashAt(invocation.cwd)
     telemetry.record({
       name: 'frontera.cli.command',
@@ -494,7 +494,8 @@ async function main(): Promise<number> {
     // A key on a session-lane command: one recovery for every such noun,
     // rather than each API client rewording its own 401/403.
     const laneFailure = sessionLaneFailure(command.meta, token, err)
-    const failure = (laneFailure && (await onLocalRuntime(laneFailure, command.meta, typeof flags.dir === 'string' ? flags.dir : process.cwd(), { apiUrl: apiUrlUsed, token }).catch(() => null))) ?? laneFailure ?? err
+    const dir = typeof flags.dir === 'string' ? flags.dir : process.cwd()
+    const failure = (laneFailure && (await onLocalRuntime(laneFailure, command.meta, dir, { apiUrl: apiUrlUsed, token }).catch(() => null))) ?? laneFailure ?? unreachableFailure(err, apiUrlUsed, (origin) => isLocalRuntimeAddress(dir, origin)) ?? err
     invocation.failure = failure
     return output.fail(personaToken ? redact(failure, personaToken) : failure)
   }

package/src/mcp/mcp-protocol.ts

@@ -1,6 +1,6 @@
 import { createInterface } from 'node:readline'
 
-import { cliTelemetry, projectHashAt } from '../telemetry/cli-telemetry'
+import { cliTelemetry, projectHashAt, projectNamesAt } from '../telemetry/cli-telemetry'
 import { errorCode, errorFields, outputErrorCode } from '../telemetry/redact'
 
 /**
@@ -93,7 +93,7 @@ function recordToolCall(tool: string, input: Record<string, unknown>, result: To
     const telemetry = cliTelemetry()
     if (telemetry.mode.mode === 'off') return
     const text = result.content.find((c) => c.type === 'text')?.text ?? ''
-    const names = Object.values(input).filter((v): v is string => typeof v === 'string')
+    const names = [...Object.values(input).filter((v): v is string => typeof v === 'string'), ...projectNamesAt(process.cwd())]
     const code = thrown === undefined ? outputErrorCode(text) : errorCode((thrown as { code?: unknown })?.code)
     const project = projectHashAt(process.cwd())
     telemetry.record({

package/src/telemetry/apply-events.ts

@@ -5,7 +5,7 @@ import { writeFileAtomic } from '../fs-atomic'
 import { applyFailureReason } from '../local/local-apply-error'
 import type { SyncTarget } from '../local/local-dev-sync'
 import type { LocalProject } from '../local/local-project'
-import { cliTelemetry } from './cli-telemetry'
+import { cliTelemetry, projectNamesAt } from './cli-telemetry'
 import type { ApplyOutcome, ApplyTrigger, Severity } from './events'
 import type { Recorder } from './recorder'
 import { errorCode, errorFields, outputErrorCode } from './redact'
@@ -106,11 +106,12 @@ export function applyEvents(project: LocalProject, opts: { recorder?: Recorder;
       if (!on) return
       try {
         const { attempt, recovered } = step(target.key, outcome)
+        const names = failure ? [...targetNames(target), ...projectNamesAt(project.root)] : []
         const error = !failure
           ? undefined
           : 'output' in failure
-            ? errorFields(outputErrorCode(failure.output), applyFailureReason(failure.output), targetNames(target))
-            : errorFields(errorCode((failure.error as { code?: unknown })?.code), failure.error instanceof Error ? failure.error.message : String(failure.error), targetNames(target))
+            ? errorFields(outputErrorCode(failure.output), applyFailureReason(failure.output), names)
+            : errorFields(errorCode((failure.error as { code?: unknown })?.code), failure.error instanceof Error ? failure.error.message : String(failure.error), names)
         telemetry.record({
           name: 'frontera.cli.apply',
           severity: SEVERITY[outcome],

package/src/telemetry/cli-telemetry.ts

@@ -1,9 +1,10 @@
 import { randomUUID } from 'node:crypto'
-import { existsSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 
 import pkg from '../../package.json' with { type: 'json' }
+import { KIND_DIRECTORY } from '../blueprint/model'
 import { findSolutionRoot, localProjectAt, PROJECT_FILES } from '../local/local-project'
 import { forgeSessionOf } from '../provenance'
 import { telemetryMode } from './enabled'
@@ -71,6 +72,33 @@ export function projectHashAt(cwd: string, home: string = homedir()): string | u
   return telemetry.hash(localProjectAt(root).id)
 }
 
+/**
+ * What the project's Blueprint artifacts and datasets are named, for an error
+ * template to take out: a service's reason names them, and a one-word name
+ * (`tickets`, `Loan`) passes every redaction rule.
+ */
+export function projectNamesAt(cwd: string): string[] {
+  const root = findSolutionRoot(cwd)
+  const stems = (dir: string) => {
+    try {
+      return readdirSync(dir).flatMap((f) => /^(.+)\.(?:ya?ml|json)$/.exec(f)?.slice(1) ?? [])
+    } catch {
+      return []
+    }
+  }
+  const datasets = stems(join(root, 'datasets'))
+  // A definition's apiName is the dataset's name even when its file is named otherwise.
+  const declared = datasets.flatMap((d) => {
+    try {
+      const { apiName } = JSON.parse(readFileSync(join(root, 'datasets', `${d}.json`), 'utf8')) as { apiName?: unknown }
+      return typeof apiName === 'string' ? [apiName] : []
+    } catch {
+      return []
+    }
+  })
+  return [...Object.values(KIND_DIRECTORY).flatMap((dir) => stems(join(root, 'blueprint', dir))), ...datasets, ...declared]
+}
+
 /** The exit code of a command the person stopped with Ctrl+C (128 + SIGINT), as a shell reports it. */
 export const INTERRUPTED = 130
 

package/src/telemetry/redact.ts

@@ -48,8 +48,10 @@ const ERROR_LINE = /^error \[[A-Z][A-Z0-9_]*\]:\s*/
  */
 export function errorTemplate(message: string, names: readonly string[] = []): string {
   const lines = message.split('\n').map((l) => l.trim()).filter(Boolean)
+  // `blueprint apply` leads with what landed and the step it stopped at: its reason is the first line past them.
+  const reason = /^(?:Nothing was applied\.|Applied before failing:)$/.test(lines[0] ?? '') ? lines.find((l, i) => i > 0 && !/^(?:Stopped at: |(?:create|update|delete|publish|grant) )/.test(l)) : undefined
   // Cut first: the rules backtrack quadratically on a long run of word characters, and a template keeps 300 anyway.
-  let text = (lines.find((l) => ERROR_LINE.test(l)) ?? lines[0] ?? '').replace(ERROR_LINE, '').slice(0, MAX_INPUT)
+  let text = (reason ?? lines.find((l) => ERROR_LINE.test(l)) ?? lines[0] ?? '').replace(ERROR_LINE, '').slice(0, MAX_INPUT)
   const known = [...new Set(names.map((n) => n.trim()).filter((n) => n.length > 1))].sort((a, b) => b.length - a.length)
   if (known.length) text = text.replace(new RegExp(`(?<![\\w-])(?:${known.map(escape).join('|')})(?![\\w-])`, 'gi'), X)
   for (const rule of RULES) text = text.replace(rule, X)