@frontera-sdk/cli 1.43.5 → 1.43.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.43.5",
+  "version": "1.43.7",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -37,8 +37,8 @@
     "build:release": "bun run scripts/build-release.ts"
   },
   "dependencies": {
-    "@frontera-sdk/automation": "0.1.0",
-    "@frontera-sdk/core": "0.1.0",
+    "@frontera-sdk/automation": "1.43.6",
+    "@frontera-sdk/core": "1.43.6",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0"
   },

package/src/api/automation-api.ts

@@ -134,10 +134,75 @@ export class AutomationApi {
    * kill switch, not a lock, so an operator can test a fix without re-arming the
    * cron.
    */
-  run(slug: string): Promise<{ slug: string; version: number; queued: boolean }> {
-    return this.client.request<{ slug: string; version: number; queued: boolean }>(
-      `/v1/automations/${encodeURIComponent(slug)}/run`,
-      { method: 'POST' },
+  /** `version` omitted runs the live one — the behaviour every caller had before
+   *  the parameter existed, and the one the service still defaults to. */
+  run(
+    slug: string,
+    version?: number,
+    dev?: boolean,
+  ): Promise<{ slug: string; version: number | null; queued: boolean; dev?: boolean }> {
+    const body = dev ? { dev: true } : version === undefined ? undefined : { version }
+    return this.client.request(`/v1/automations/${encodeURIComponent(slug)}/run`, {
+      method: 'POST',
+      body,
+    })
+  }
+
+  /** Open or take over this automation's dev session. Creates the automation
+   *  row when absent — an author develops before the first deploy. */
+  devSessionOpen(
+    slug: string,
+    entryFile: string,
+    holderId: string,
+  ): Promise<{
+    sessionId: string
+    slug: string
+    liveVersionId: string | null
+    created: boolean
+    leaseExpiresAt: string
+    leaseMs: number
+  }> {
+    return this.client.request(
+      `/v1/automations/${encodeURIComponent(slug)}/dev/session`,
+      { method: 'POST', body: { entryFile, holderId } },
+    )
+  }
+
+  /** Heartbeat and claim in one call: a lost lease invalidates a claim, so
+   *  asking separately would let a taken-over worker execute one more run. */
+  /**
+   * Heartbeat, claim, and hand over the manifest — one call.
+   *
+   * The manifest rides here because this is the only message that comes from
+   * the machine holding the file. It is what the claimed run's grants are set
+   * from, so a grant added while iterating takes effect on the very next run
+   * with no redeploy and no session restart.
+   */
+  devPoll(
+    slug: string,
+    sessionId: string,
+    holderId: string,
+    manifest: Record<string, unknown>,
+  ): Promise<{
+    held: boolean
+    run: { runId: string; runToken: string; grants: string[]; workspaceId: string } | null
+  }> {
+    const q = `sessionId=${encodeURIComponent(sessionId)}&holderId=${encodeURIComponent(holderId)}`
+    return this.client.request(
+      `/v1/automations/${encodeURIComponent(slug)}/dev/poll?${q}`,
+      { method: 'POST', body: { manifest } },
+    )
+  }
+
+  devSessionClose(
+    slug: string,
+    sessionId: string,
+    holderId: string,
+  ): Promise<{ closed: boolean }> {
+    const q = `sessionId=${encodeURIComponent(sessionId)}&holderId=${encodeURIComponent(holderId)}`
+    return this.client.request(
+      `/v1/automations/${encodeURIComponent(slug)}/dev/session?${q}`,
+      { method: 'DELETE' },
     )
   }
 
@@ -145,8 +210,23 @@ export class AutomationApi {
     return this.client.request<RegistryStatus>('/v1/automations/registry-status')
   }
 
-  runs(slug: string, limit?: number): Promise<AutomationRunSummary[]> {
-    const query = limit === undefined ? '' : `?limit=${limit}`
+  /**
+   * Run history. `mode` is NOT optional in effect, only in the signature.
+   *
+   * The route defaults to `live` when it is absent, so a caller that omits it
+   * on a dev path reads the wrong history in silence — `automation run --dev`
+   * waited out its whole timeout for a run it had already finished, and would
+   * report a cron fire that happened during the wait as if it were the dev run.
+   */
+  runs(
+    slug: string,
+    limit?: number,
+    mode: 'live' | 'dev' = 'live',
+  ): Promise<AutomationRunSummary[]> {
+    const params = new URLSearchParams()
+    if (limit !== undefined) params.set('limit', String(limit))
+    if (mode === 'dev') params.set('mode', 'dev')
+    const query = params.size > 0 ? `?${params}` : ''
     return this.client.request<AutomationRunSummary[]>(
       `/v1/automations/${encodeURIComponent(slug)}/runs${query}`,
     )

package/src/api/blueprint-authoring-api.ts

@@ -266,6 +266,44 @@ export class BlueprintAuthoringApi {
     })
   }
 
+  // ── semantic types ─────────────────────────────────────────────────────
+
+  listSemanticTypes(): Promise<
+    Array<{ id?: string; apiName?: string; displayName?: string; dataType?: string }>
+  > {
+    return this.call('/v1/blueprint/semantic-types?view=draft')
+  }
+
+  /**
+   * Create, and read the minted id back — the same contract the shared-field create
+   * has, and needed by BOTH carrier kinds: a tree that introduces a semantic type
+   * alongside the shared field or the property carrying it has no id at plan time.
+   */
+  createSemanticType(
+    body: Record<string, unknown>,
+    expectedRevision: number,
+  ): Promise<{ semanticType?: { id?: string; apiName?: string }; draftRevision?: number }> {
+    return this.call('/v1/blueprint/semantic-types', {
+      method: 'POST',
+      body: { ...body, expectedRevision },
+    })
+  }
+
+  updateSemanticType(apiName: string, body: Record<string, unknown>, expectedRevision: number) {
+    return this.call(`/v1/blueprint/semantic-types/${encodeURIComponent(apiName)}`, {
+      method: 'PUT',
+      body: { ...body, expectedRevision },
+    })
+  }
+
+  /** Succeeds with carriers: each reverts to an unconstrained field. */
+  deleteSemanticType(apiName: string, expectedRevision: number) {
+    return this.call(`/v1/blueprint/semantic-types/${encodeURIComponent(apiName)}`, {
+      method: 'DELETE',
+      body: { expectedRevision },
+    })
+  }
+
   /**
    * Removing an object type is a STRUCTURAL change, so it goes through preview and
    * apply rather than a plain DELETE: the service refuses an apply whose digest does

package/src/automation-template.ts

@@ -112,6 +112,16 @@ export function automationScaffoldFiles(name: string): Record<string, string> {
 
   out['src/index.ts'] = `import { automation } from '@frontera-sdk/automation'
 
+/**
+ * The object type this reads. CHANGE THIS to one of yours —
+ * \`frontera blueprint list\` shows what this workspace can read.
+ *
+ * Exported, and the starter test imports it, so changing it here changes both.
+ * The test used to hard-code the same literal, and every author's first edit
+ * broke it with a bare array diff naming neither the cause nor the fix.
+ */
+export const OBJECT_TYPE = 'YourObjectType'
+
 export default automation(
   {
     name: '${name}',
@@ -127,7 +137,7 @@ export default automation(
     // 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 })
+      const result = await ctx.blueprint.query(OBJECT_TYPE, { limit: 10 })
       await ctx.log(\`loaded \${result.rows.length} row(s)\`)
       return { count: result.rows.length }
     })
@@ -163,7 +173,7 @@ export default automation(
   out['src/index.test.ts'] = `import { expect, test } from 'bun:test'
 import { createTestContext } from '@frontera-sdk/automation'
 
-import automation from './index'
+import automation, { OBJECT_TYPE } 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
@@ -183,7 +193,7 @@ test('handles rows', async () => {
     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 } },
+    blueprint: { [OBJECT_TYPE]: { rows: [{ id: 'a' }, { id: 'b' }], hasMore: false } },
   })
 
   await automation.handler(ctx)

package/src/blueprint/compile.ts

@@ -119,6 +119,50 @@ export function resolveSharedProperty(
   return id
 }
 
+/**
+ * `semanticType: percentage` → the uuid the wire takes. THREE-VALUED, exactly like
+ * `resolveSharedProperty` above and for the same reasons — omission preserves, `null`
+ * detaches, a name attaches or replaces — and resolved at the moment of the write so
+ * a semantic type created earlier in the same `apply` is already in the map.
+ *
+ * Its own function rather than a parameterisation of the shared-field resolver: the
+ * two namespaces are independent (a shared field and a semantic type may share an
+ * apiName), the messages name different files, and collapsing them would make the
+ * one map serve two references — which is how a typo in one resolves to the other.
+ *
+ * `carrier` is what the reference is written ON, and it is a free string because both
+ * carrier kinds resolve through here: a field on an object type, and a shared field
+ * standing alone.
+ */
+export function resolveSemanticType(
+  file: AuthoredFile,
+  carrier: string,
+  declared: unknown,
+  semanticTypeIdByApiName: Map<string, string>,
+): string | null | undefined {
+  if (declared === undefined) return undefined
+  if (declared === null) return null
+  const name = String(declared)
+  const id = semanticTypeIdByApiName.get(name)
+  if (!id) {
+    throw new CliError(
+      `${file.path}: ${carrier} names semantic type "${name}", which is not on the draft.`,
+      {
+        code: 'USAGE',
+        hint: `Add semantic-types/${name}.yaml, or correct the name. `
+          + 'A semantic type is referenced by apiName — the tree carries no identifiers.',
+      },
+    )
+  }
+  return id
+}
+
+/** Both id maps a write may need to resolve, threaded together so neither is forgotten. */
+export interface AuthoringIds {
+  sharedPropertyIdByApiName: Map<string, string>
+  semanticTypeIdByApiName: Map<string, string>
+}
+
 function columnOf(entry: string | { column: string; field?: string | null }): {
   column: string
   field?: string | null
@@ -137,7 +181,7 @@ export async function objectTypeCreateBody(
   file: AuthoredFile,
   expectedRevision: number,
   resolveDataset: DatasetResolver,
-  sharedPropertyIdByApiName: Map<string, string>,
+  ids: AuthoringIds,
 ): Promise<Record<string, unknown>> {
   const document = file.document
   const backing = readBacking(file)
@@ -199,7 +243,10 @@ export async function objectTypeCreateBody(
       // 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,
+        file, apiName, property.sharedField, ids.sharedPropertyIdByApiName,
+      )
+      const semanticTypeId = resolveSemanticType(
+        file, `field "${apiName}"`, property.semanticType, ids.semanticTypeIdByApiName,
       )
       return {
         apiName,
@@ -215,6 +262,9 @@ export async function objectTypeCreateBody(
         // "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 } : {}),
+        // Same three-state collapse as the shared field beside it: a CREATE has
+        // nothing to detach from, and the create body's uuid is not nullable.
+        ...(typeof semanticTypeId === 'string' ? { semanticTypeId } : {}),
       }
     }),
     columnMappings: Object.entries(backing.mapping).map(([propertyApiName, entry]) => {
@@ -308,6 +358,56 @@ export function metricCreateBody(
   return { ...body, objectTypeApiName: objectType, expectedRevision }
 }
 
+/**
+ * `POST /v1/blueprint/actions` and its PUT.
+ *
+ * Carried through as authored, name references and all. The service resolves them
+ * against the draft and mints the ids the contract owns — see
+ * `action-reference-resolution` and `action-identity` — so translating anything here
+ * would put a second resolver on the wire's other end, which is the arrangement
+ * `linkTypeStructure`'s neighbours exist to avoid.
+ */
+/**
+ * An action file with every id the SERVICE mints removed — the action's own and each
+ * child's.
+ *
+ * Exported because two callers must agree exactly: `actionBody` sends this, and the
+ * differ compares against it. Stripping only the top-level id made a pasted Console
+ * export plan an `~ action` update on EVERY run — the projection strips child ids too,
+ * so the raw file never matched the live side, and the apply then sent a body identical
+ * to what was already stored. `replaceBlueprintDraft` has no no-op guard, so each run
+ * bumped the revision and changed nothing.
+ *
+ * Forwarding a pasted id was wrong on its own terms as well: `assignActionIdentity`
+ * honours a pinned id, so an export from another organization created an action here
+ * carrying THAT deployment's uuid — accepted, because the duplicate check is per-org,
+ * and invisible afterwards, because the next `pull` strips it again while contract
+ * digests and binding rows keep keying off it.
+ */
+export function actionWithoutMintedIds(document: Record<string, unknown>): Record<string, unknown> {
+  const drop = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(drop)
+    if (!value || typeof value !== 'object') return value
+    const out: Record<string, unknown> = {}
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      // `id` only. A REFERENCE ending in `Id` is the service's own resolution of a name
+      // and never appears in a projected file, so it is left alone rather than guessed
+      // at — the projection is the authority on what a file may carry.
+      if (key === 'id') continue
+      out[key] = drop(entry)
+    }
+    return out
+  }
+  return drop(document) as Record<string, unknown>
+}
+
+export function actionBody(file: AuthoredFile): Record<string, unknown> {
+  // `apiName` from the PATH, not the document: the tree's filename is the identity,
+  // and a file whose body disagreed with its name would create one artifact and be
+  // pruned as another on the next run.
+  return { ...actionWithoutMintedIds(file.document), apiName: file.apiName }
+}
+
 /** The patch route takes metadata and the definition, never the subject. */
 export function metricPatchBody(
   file: AuthoredFile,
@@ -327,8 +427,12 @@ export function metricPatchBody(
 export function sharedPropertyCreateBody(
   file: AuthoredFile,
   expectedRevision: number,
+  semanticTypeIdByApiName: Map<string, string>,
 ): Record<string, unknown> {
   const document = file.document
+  const semanticTypeId = resolveSemanticType(
+    file, `shared field "${file.apiName}"`, document.semanticType, semanticTypeIdByApiName,
+  )
   return {
     apiName: requireString(document, 'apiName', file.path),
     displayName: requireString(document, 'displayName', file.path),
@@ -339,6 +443,11 @@ export function sharedPropertyCreateBody(
     // 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'),
+    // A shared field created with nothing carrying it yet still states what its
+    // implementers will mean, so the reference travels the CREATE rather than a
+    // follow-up patch: on a first apply against an empty organization there is no
+    // second call to make.
+    ...(typeof semanticTypeId === 'string' ? { semanticTypeId } : {}),
     ...optional(document.status as string | undefined, 'status'),
     ...optional(document.visibility as string | undefined, 'visibility'),
     expectedRevision,
@@ -356,6 +465,63 @@ export function sharedPropertyCreateBody(
 export function sharedPropertyPatchBody(
   file: AuthoredFile,
   expectedRevision: number,
+  semanticTypeIdByApiName: Map<string, string>,
+): Record<string, unknown> {
+  const {
+    apiName: _apiName,
+    // TRANSLATED, never passed through. The file says `semanticType: <name>` and the
+    // route takes `semanticTypeId: <uuid> | null`; sending the authored key would
+    // leave the route's own key absent, so the patch would report success having
+    // changed nothing — the silent no-op this projection exists to prevent.
+    semanticType,
+    ...body
+  } = file.document as Record<string, unknown>
+  const semanticTypeId = resolveSemanticType(
+    file, `shared field "${file.apiName}"`, semanticType, semanticTypeIdByApiName,
+  )
+  return {
+    ...body,
+    ...(semanticTypeId === undefined ? {} : { semanticTypeId }),
+    expectedRevision,
+  }
+}
+
+/**
+ * A semantic type is authored whole: metadata plus one rule, and the create route
+ * takes the same fields the bundle carries.
+ *
+ * The rule is passed through UNVALIDATED. Its grammar is four discriminated schemas
+ * the service owns, and restating them here would be a second copy that drifts —
+ * the route answers a 400 carrying the path into the rule, which is a better error
+ * than any this package could invent.
+ */
+export function semanticTypeCreateBody(
+  file: AuthoredFile,
+  expectedRevision: number,
+): Record<string, unknown> {
+  const document = file.document
+  if (document.rule === undefined) {
+    throw new CliError(`${file.path} declares no \`rule\`.`, {
+      code: 'USAGE',
+      hint: 'A semantic type is a rule. `frontera blueprint new semantic-type <name>` writes one that validates.',
+    })
+  }
+  return {
+    apiName: requireString(document, 'apiName', file.path),
+    displayName: requireString(document, 'displayName', file.path),
+    ...optional(document.description as string | undefined, 'description'),
+    dataType: requireString(document, 'dataType', file.path),
+    rule: document.rule,
+    ...optional(document.status as string | undefined, 'status'),
+    ...optional(document.visibility as string | undefined, 'visibility'),
+    expectedRevision,
+  }
+}
+
+/** `apiName` is omitted for the same reason a shared field's is: it means RENAME. */
+export function semanticTypePatchBody(
+  file: AuthoredFile,
+  expectedRevision: number,
 ): Record<string, unknown> {
   const { apiName: _apiName, ...body } = file.document as Record<string, unknown>
   return { ...body, expectedRevision }

package/src/blueprint/diff.ts

@@ -1,3 +1,4 @@
+import { actionWithoutMintedIds } from './compile'
 import { toFiles } from './projection'
 import {
   ARTIFACT_KINDS,
@@ -5,6 +6,7 @@ import {
   type AuthoredFile,
   type DefinitionBundle,
 } from './model'
+import { CliError } from '../errors'
 
 /**
  * The plan: what the files say that the live draft does not, expressed as typed
@@ -48,6 +50,16 @@ export interface Plan {
   operations: ModelOperation[]
   /** Artifacts in the draft but absent from the tree. Applied only with `--prune`. */
   prunes: ModelOperation[]
+  /**
+   * Prunes NOT offered, because the tree has no directory for that kind at all.
+   *
+   * Reported rather than dropped. Git cannot transport an empty directory, so
+   * `rm -rf blueprint/metrics` is indistinguishable from a tree that never modelled
+   * metrics — and withholding silently answered `Applied 0 changes` while the metrics
+   * stayed live. Saying which prunes were withheld, and why, is the difference between
+   * a guard and a surprise.
+   */
+  withheld?: ModelOperation[]
   drift: BindingDrift[]
   unchanged: number
 }
@@ -148,6 +160,37 @@ function describeUpdate(local: Record<string, unknown>, live: Record<string, unk
   return parts.length ? parts.join(', ') : 'fields changed'
 }
 
+/**
+ * Has this artifact changed? Subset for most kinds, EXACT for actions.
+ *
+ * The asymmetry follows the routes, not a preference. An object type, link type or
+ * metric is updated by a patch, so a field the file omits is a field the file has no
+ * opinion about — which is what makes `satisfies` a subset comparison and what lets a
+ * hand-authored file leave every service-derived value out.
+ *
+ * An action's PUT replaces the contract WHOLE. There, omitting a field deletes it. Under
+ * a subset comparison that deletion was invisible: `plan` reported nothing, and a
+ * deletion travelling alongside any other edit was applied without ever being named.
+ * Comparing both directions makes the removal a change, which is what it is.
+ *
+ * Safe because an action file is a total projection — `actionToFile` strips only the ids
+ * the service mints and turns references into names, both of which `apply` puts back. A
+ * pulled tree therefore still reports no changes, which the round-trip test asserts.
+ */
+function matches(
+  kind: ArtifactKind,
+  local: Record<string, unknown>,
+  live: Record<string, unknown>,
+): boolean {
+  if (kind !== 'action') return satisfies(local, live)
+  // Compared against what `apply` will actually SEND, which is the file minus every id
+  // the service mints. The live side is the projection, which already strips them — so
+  // comparing the raw file made a pasted export differ forever, on ids neither side
+  // could ever agree about.
+  const authored = actionWithoutMintedIds(local)
+  return satisfies(authored, live) && satisfies(live, authored)
+}
+
 export function diff(
   localFiles: AuthoredFile[],
   live: DefinitionBundle,
@@ -179,7 +222,7 @@ export function diff(
         })
         continue
       }
-      if (satisfies(file.document, existing.document)) {
+      if (matches(kind, file.document, existing.document)) {
         unchanged += 1
         continue
       }
@@ -194,13 +237,100 @@ export function diff(
     }
     for (const file of liveModel.files.filter((candidate) => candidate.kind === kind)) {
       if (localByKey.has(`${kind}:${file.apiName}`)) continue
-      prunes.push({ operation: 'delete', kind, apiName: file.apiName })
+      // The live document rides along in `liveDocument`, which is what that field
+      // means — `document` is the AUTHORED one, and a delete has no authored side. A
+      // delete needs no body at all, but ORDERING the prunes does: an action naming
+      // another as its compensation must be deleted first, and only the live side
+      // knows which.
+      prunes.push({ operation: 'delete', kind, apiName: file.apiName, liveDocument: file.document })
     }
   }
 
   return { revision, operations, prunes, drift: driftOf(live), unchanged }
 }
 
+/**
+ * Every place the tree names a semantic type, as a path a reader can open.
+ *
+ * Both carrier kinds, because both author the reference: a shared field names one at
+ * its top level, and an object type names one per property. `null` is a detach and
+ * names nothing.
+ */
+function semanticTypeReferences(files: AuthoredFile[]): Array<{ name: string; carrier: string }> {
+  const references: Array<{ name: string; carrier: string }> = []
+  for (const file of files) {
+    if (file.kind === 'shared-field') {
+      const declared = file.document.semanticType
+      if (typeof declared === 'string') references.push({ name: declared, carrier: file.path })
+      continue
+    }
+    if (file.kind !== 'object-type') continue
+    const properties = file.document.properties
+    if (!Array.isArray(properties)) continue
+    for (const property of properties) {
+      const entry = property as { apiName?: unknown; semanticType?: unknown }
+      if (typeof entry.semanticType !== 'string') continue
+      references.push({
+        name: entry.semanticType,
+        carrier: `${file.path} (field "${String(entry.apiName)}")`,
+      })
+    }
+  }
+  return references
+}
+
+/**
+ * Refuse a prune that would delete a semantic type the surviving tree still names.
+ *
+ * The planner compares each authored file against the live draft INDEPENDENTLY of
+ * what else the run prunes, so a tree that keeps `shared-fields/status.yaml` carrying
+ * `semanticType: code` and drops `semantic-types/code.yaml` plans as `unchanged: 1`
+ * plus one prune. Executed, the delete route degrades its carriers — it clears the
+ * very reference the surviving file still declares — so the run reports success and
+ * leaves the draft disagreeing with the tree. The next `apply` then fails on name
+ * resolution, because `code` is no longer in the live id map: the report is right and
+ * the recovery is manual.
+ *
+ * Refused rather than reordered, and refused naming EVERY surviving carrier: the
+ * author has to decide whether the type is going or the carriers are, and doing half
+ * of it for them is how a rule silently stops being enforced.
+ *
+ * Called where `--prune` is honoured rather than from `diff` itself. A tree is allowed
+ * to be partial — one file, applied on its own, is the normal way to work — and only
+ * `--prune` claims the tree is the whole truth.
+ */
+export function assertPrunesLeaveNoDanglingReference(
+  localFiles: AuthoredFile[],
+  prunes: ModelOperation[],
+): void {
+  const pruned = new Set(
+    prunes.filter((operation) => operation.kind === 'semantic-type')
+      .map((operation) => operation.apiName),
+  )
+  if (pruned.size === 0) return
+  const orphaned = new Map<string, string[]>()
+  for (const reference of semanticTypeReferences(localFiles)) {
+    if (!pruned.has(reference.name)) continue
+    const carriers = orphaned.get(reference.name) ?? []
+    carriers.push(reference.carrier)
+    orphaned.set(reference.name, carriers)
+  }
+  if (orphaned.size === 0) return
+  const detail = [...orphaned.entries()]
+    .map(([name, carriers]) => `  ${name} — still carried by ${carriers.join(', ')}`)
+    .join('\n')
+  throw new CliError(
+    `--prune would delete ${orphaned.size === 1 ? 'a semantic type' : 'semantic types'} the tree `
+    + `still references:\n${detail}`,
+    {
+      code: 'USAGE',
+      hint: 'Delete the carriers\' `semanticType:` lines too, or keep the semantic-types/ file. '
+        + 'Deleting the type on its own clears every reference to it, which the surviving files '
+        + 'would then contradict.',
+    },
+  )
+}
+
 /**
  * Bound object types whose pinned schema digest can be checked against the dataset's
  * current revision. The comparison itself needs the dataset read, so this only