@frontera-sdk/cli 1.43.6 → 1.43.8

package/src/commands/blueprint/declarative.ts

@@ -6,15 +6,27 @@ import {
   linkTypeCreateBody,
   linkTypeStructure,
   objectTypeCreateBody,
+  actionBody,
   metricCreateBody,
   metricPatchBody,
   readBacking,
+  resolveSemanticType,
   resolveSharedProperty,
+  semanticTypeCreateBody,
+  semanticTypePatchBody,
   sharedPropertyCreateBody,
   sharedPropertyPatchBody,
+  type AuthoringIds,
 } from '../../blueprint/compile'
 import { pickCurrentRevision } from '../../blueprint/dataset-revision'
-import { diff, isEmpty, satisfies, type ModelOperation, type Plan } from '../../blueprint/diff'
+import {
+  assertPrunesLeaveNoDanglingReference,
+  diff,
+  isEmpty,
+  satisfies,
+  type ModelOperation,
+  type Plan,
+} from '../../blueprint/diff'
 import {
   API_NAME_RULE,
   ARTIFACT_KINDS,
@@ -27,7 +39,12 @@ import {
 } from '../../blueprint/model'
 import { toFiles } from '../../blueprint/projection'
 import { renderDrift, renderPlan } from '../../blueprint/render'
-import { scaffold } from '../../blueprint/scaffold'
+import {
+  SEMANTIC_TYPE_TEMPLATE_NAMES,
+  isSemanticTypeTemplate,
+  scaffold,
+  type SemanticTypeTemplate,
+} from '../../blueprint/scaffold'
 import { pathFor, readTree, removeFromTree, writeTree } from '../../blueprint/tree'
 import { CliError } from '../../errors'
 import type { Command, CommandContext } from '../types'
@@ -244,7 +261,7 @@ async function computePlan(ctx: CommandContext): Promise<{
   }
   const files = readTree(directory)
   const { definition, revision } = await client.draft()
-  const plan = diff(files, definition, revision)
+  const plan = withheldPrunes(diff(files, definition, revision), 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
@@ -276,6 +293,36 @@ async function computePlan(ctx: CommandContext): Promise<{
   return { plan, files, definition, drift }
 }
 
+/**
+ * Withhold — and REPORT — prunes for a kind the tree has no directory for at all.
+ *
+ * `action` joining `ARTIFACT_KINDS` made every EXISTING tree suddenly claim authority
+ * over actions it had never modelled: such a tree has no `actions/`, so the first
+ * `apply --prune` after upgrading planned a delete for every live action in the
+ * organization — including ones authored through the Console or `blueprint create
+ * action`. Nothing writes the directory into an old tree, and nothing required a `pull`
+ * first, so an upgrade alone could delete work the tree had never seen.
+ *
+ * A missing directory is "this tree does not model that kind", which is not the same
+ * claim as an empty one. An empty `actions/` still prunes — that is a tree saying it
+ * models actions and has none.
+ */
+function withheldPrunes(plan: Plan, directory: string): Plan {
+  const modelled = new Set(
+    ARTIFACT_KINDS.filter((kind) => existsSync(join(directory, KIND_DIRECTORY[kind]))),
+  )
+  const prunes = plan.prunes.filter((operation) => modelled.has(operation.kind))
+  if (prunes.length === plan.prunes.length) return plan
+  // Moved, not dropped: `renderPlan` prints these under their own heading so a tree
+  // that deleted a whole directory sees WHY nothing was pruned, instead of reading
+  // "Applied 0 changes" and concluding the artifacts were already gone.
+  return {
+    ...plan,
+    prunes,
+    withheld: plan.prunes.filter((operation) => !modelled.has(operation.kind)),
+  }
+}
+
 export const blueprintPlan: Command = {
   meta: {
     noun: 'blueprint',
@@ -286,7 +333,16 @@ export const blueprintPlan: Command = {
     examples: ['frontera blueprint plan', 'frontera blueprint plan --json'],
   },
   async run(ctx) {
-    const { plan, drift } = await computePlan(ctx)
+    const { plan, files, definition, drift } = await computePlan(ctx)
+    // Every refusal `apply` will raise, raised here too, and for the reason `plan`
+    // exists: a plan that cannot be applied is not one a reader should be shown as if
+    // it could. Two independent checks — a prune that would dangle a reference, and an
+    // ordering that has no solution.
+    orderForApply(plan.operations)
+    if (ctx.flags.prune === true) {
+      assertPrunesLeaveNoDanglingReference(files, plan.prunes)
+      orderForPrune(plan.prunes, liveCompensations(definition))
+    }
     const body = [renderPlan(plan, { prune: ctx.flags.prune === true }), renderDrift(drift)]
       .filter(Boolean)
       .join('\n')
@@ -297,24 +353,56 @@ export const blueprintPlan: Command = {
 /**
  * Apply one operation, on the route that carries its guard.
  *
+ * Exported for the same reason `assertApplicable` is: the tests drive this dispatch
+ * directly, which is the only way to reach the refusal an unknown kind gets.
+ *
  * Creations go to the per-artifact POST rather than to a whole-bundle write: the
  * create route mints every id, derives each property's base type from the pinned
  * column, and writes the `governance.sourceMappings` shell that a later `bind`
  * requires. An object type inserted any other way can never afterwards be bound.
  */
-async function applyOperation(
+export async function applyOperation(
   client: BlueprintAuthoringApi,
   operation: ModelOperation,
   file: AuthoredFile,
   revision: number,
-  sharedPropertyIds: Map<string, string>,
+  ids: AuthoringIds,
 ): Promise<number> {
   const resolveDataset = (name: string) => resolveRevision(client, name)
 
+  if (operation.kind === 'semantic-type') {
+    if (operation.operation === 'create') {
+      const created = await client.createSemanticType(
+        semanticTypeCreateBody(file, revision),
+        revision,
+      )
+      // Threaded exactly as a shared field's id is, and for the same run: a tree
+      // that introduces a semantic type and the field carrying it has no id at plan
+      // time, and both carriers resolve this map at the moment of their write.
+      const id = created?.semanticType?.id
+      if (!id) {
+        throw new CliError(
+          `Creating semantic type "${operation.apiName}" returned no id, so nothing can carry it.`,
+          {
+            code: 'FAILURE',
+            hint: 'The service is expected to answer with the created row. Re-run `frontera blueprint plan`.',
+          },
+        )
+      }
+      ids.semanticTypeIdByApiName.set(operation.apiName, id)
+      return nextRevision(created, revision)
+    }
+    assertApplicable('semantic-type', file, operation.liveDocument)
+    const updated = await client.updateSemanticType(
+      operation.apiName, semanticTypePatchBody(file, revision), revision,
+    )
+    return nextRevision(updated, revision)
+  }
+
   if (operation.kind === 'shared-field') {
     if (operation.operation === 'create') {
       const created = await client.createSharedProperty(
-        sharedPropertyCreateBody(file, revision),
+        sharedPropertyCreateBody(file, revision, ids.semanticTypeIdByApiName),
         revision,
       )
       // The minted id, threaded into the property writes that follow in THIS run —
@@ -330,12 +418,14 @@ async function applyOperation(
           },
         )
       }
-      sharedPropertyIds.set(operation.apiName, id)
+      ids.sharedPropertyIdByApiName.set(operation.apiName, id)
       return nextRevision(created, revision)
     }
     assertApplicable('shared-field', file, operation.liveDocument)
     const updated = await client.updateSharedProperty(
-      operation.apiName, sharedPropertyPatchBody(file, revision), revision,
+      operation.apiName,
+      sharedPropertyPatchBody(file, revision, ids.semanticTypeIdByApiName),
+      revision,
     )
     return nextRevision(updated, revision)
   }
@@ -343,7 +433,7 @@ async function applyOperation(
   if (operation.kind === 'object-type') {
     if (operation.operation === 'create') {
       const created = await client.createObjectType(
-        await objectTypeCreateBody(file, revision, resolveDataset, sharedPropertyIds),
+        await objectTypeCreateBody(file, revision, resolveDataset, ids),
         revision,
       )
       return nextRevision(created, revision)
@@ -368,7 +458,7 @@ async function applyOperation(
     }
     current = await applyObjectKeys(client, operation.apiName, file, operation.liveDocument, current)
     return applyPropertyPlan(
-      client, operation.apiName, file, operation.liveDocument, current, sharedPropertyIds,
+      client, operation.apiName, file, operation.liveDocument, current, ids,
     )
   }
 
@@ -380,11 +470,52 @@ async function applyOperation(
     return nextRevision(body, revision)
   }
 
-  if (operation.operation !== 'create') assertApplicable('metric', file, operation.liveDocument)
-  const result = operation.operation === 'create'
-    ? await client.createMetric(metricCreateBody(file, revision), revision)
-    : await client.updateMetric(operation.apiName, metricPatchBody(file, revision), revision)
-  return nextRevision(result, revision)
+  if (operation.kind === 'action') {
+    // Sent as authored, names and all. The service resolves the references against the
+    // draft and mints the ids the contract owns, so the file carries no uuid — see
+    // `action-reference-resolution` and `action-identity`. An update PRESERVES those
+    // ids by matching children on apiName, which is why re-applying an unchanged tree
+    // is a no-op rather than a churn of fresh identifiers.
+    const body = actionBody(file)
+    // Checked against what will actually be SENT, not against the file. `actionBody`
+    // drops a pasted `id`, and `id` is not applicable — so checking the file first
+    // refused every apply after the first with "id differs from the draft", naming a
+    // field the projection never writes and the author therefore cannot revert.
+    if (operation.operation !== 'create') {
+      assertApplicable('action', { ...file, document: body }, operation.liveDocument)
+    }
+    const result = operation.operation === 'create'
+      ? await client.createAction(body, revision)
+      : await client.updateAction(operation.apiName, body, revision)
+    return nextRevision(result, revision)
+  }
+
+  if (operation.kind === 'metric') {
+    if (operation.operation !== 'create') assertApplicable('metric', file, operation.liveDocument)
+    const result = operation.operation === 'create'
+      ? await client.createMetric(metricCreateBody(file, revision), revision)
+      : await client.updateMetric(operation.apiName, metricPatchBody(file, revision), revision)
+    return nextRevision(result, revision)
+  }
+
+  return assertNever(operation.kind, 'apply')
+}
+
+/**
+ * A kind this dispatch does not handle, refused loudly rather than fallen through.
+ *
+ * All three dispatches used to end in an UNCONDITIONAL metric arm, so a new kind was
+ * not a compile error and not a runtime error either: it was silently treated as a
+ * metric. `scaffold` wrote metric YAML under the new kind's path, `apply` POSTed it
+ * to `/metrics`, and `--prune` DELETED a metric that happened to share its apiName.
+ * The `never` parameter makes adding a kind a type error at each of the three, and
+ * this message is what a build that skipped the type check would say.
+ */
+export function assertNever(kind: never, site: string): never {
+  throw new CliError(`"${String(kind)}" is not an artifact kind this ${site} can handle.`, {
+    code: 'USAGE',
+    hint: `Expected one of: ${ARTIFACT_KINDS.join(', ')}.`,
+  })
 }
 
 /**
@@ -431,9 +562,12 @@ function nextRevision(response: unknown, previous: number): number {
  * route refuses.
  */
 const APPLICABLE_FIELDS: Record<ArtifactKind, Set<string>> = {
+  'semantic-type': new Set([
+    'apiName', 'displayName', 'description', 'dataType', 'rule', 'status', 'visibility',
+  ]),
   'shared-field': new Set([
     'apiName', 'displayName', 'description', 'valueType', 'propertyType', 'formatConfig',
-    'status', 'visibility',
+    'semanticType', 'status', 'visibility',
   ]),
   'object-type': new Set([
     'apiName', 'displayName', 'pluralDisplayName', 'description', 'icon', 'color',
@@ -441,6 +575,14 @@ const APPLICABLE_FIELDS: Record<ArtifactKind, Set<string>> = {
   ]),
   'link-type': new Set(['apiName', 'cardinality', 'description', 'from', 'to']),
   metric: new Set(['apiName', 'displayName', 'description', 'definition', 'formatConfig']),
+  // Every field, because the action PUT replaces the contract whole — there is no
+  // field an update cannot carry. Enumerated rather than left open so that a field the
+  // bundle gains later is refused here until someone confirms the route takes it,
+  // which is the same bargain the other kinds make.
+  action: new Set([
+    'apiName', 'displayName', 'description', 'subject', 'effect', 'inputs',
+    'businessOutcomes', 'concurrency', 'impact', 'submissionCriteria', 'governance',
+  ]),
 }
 
 export function assertApplicable(
@@ -634,6 +776,27 @@ function planProperties(
       const current = counterpart.sharedField ?? null
       if (wanted !== current) metadataPatch.sharedField = wanted
     }
+    // A semantic type is carried by NAME for the same reason and resolved at the same
+    // moment, and `null` is compared against a live absence for the same reason: a
+    // file that says `semanticType: null` against a field that carries none must plan
+    // nothing, or every run re-issues a detach the service refuses as a no-op.
+    //
+    // WHICH COMMAND IT RIDES is decided here rather than by the loop below, and the
+    // ordering is why. The executor sends every schema command before every metadata
+    // command, so a file that moves `valueType` and `semanticType` together would
+    // otherwise validate the new value type against the OLD semantic type and then
+    // the new semantic type against the already-changed value type — one of the two
+    // intermediate states contradicts, and the run fails halfway. Riding the same
+    // `update_field_schema` patch makes it one command, and R4.4's next-state
+    // validation judges the pair the command settles on. It is never on both.
+    if (property.semanticType !== undefined) {
+      const wanted = property.semanticType === null ? null : property.semanticType
+      const current = counterpart.semanticType ?? null
+      if (wanted !== current) {
+        if (Object.keys(schemaPatch).length > 0) schemaPatch.semanticType = wanted
+        else metadataPatch.semanticType = wanted
+      }
+    }
     const id = idByApiName.get(name)
     // A declared property with no live id is either brand new (handled above) or the
     // draft moved; skipping it quietly is how a change goes missing.
@@ -659,7 +822,7 @@ async function applyPropertyPlan(
   file: AuthoredFile,
   liveDocument: Record<string, unknown> | undefined,
   revision: number,
-  sharedPropertyIds: Map<string, string>,
+  ids: AuthoringIds,
 ): Promise<number> {
   const detail = await client.getObjectTypeDetail(apiName)
   if (!detail?.id) {
@@ -723,7 +886,10 @@ async function applyPropertyPlan(
     // Resolved here rather than at plan time: a shared field created earlier in
     // this same run only entered the map when its create answered.
     const sharedPropertyId = resolveSharedProperty(
-      file, name, property.sharedField, sharedPropertyIds,
+      file, name, property.sharedField, ids.sharedPropertyIdByApiName,
+    )
+    const semanticTypeId = resolveSemanticType(
+      file, `field "${name}"`, property.semanticType, ids.semanticTypeIdByApiName,
     )
     const result = await client.draftCommand({
       kind: 'add_field',
@@ -747,13 +913,19 @@ async function applyPropertyPlan(
         // is simply "no shared field" — `add_field`'s uuid is not nullable, and a
         // detach command on a field that is being created makes no sense anyway.
         ...(typeof sharedPropertyId === 'string' ? { sharedPropertyId } : {}),
+        // Same collapse: `add_field`'s uuid is not nullable, and a field being
+        // created has no meaning to detach from.
+        ...(typeof semanticTypeId === 'string' ? { semanticTypeId } : {}),
       },
     }, current)
     current = result.revision
   }
   for (const change of plan.schemaChanges) {
     const result = await client.draftCommand({
-      kind: 'update_field_schema', objectId: detail.id, fieldId: change.id, patch: change.patch,
+      kind: 'update_field_schema',
+      objectId: detail.id,
+      fieldId: change.id,
+      patch: semanticTypeOnWire(file, change.apiName, change.patch, ids),
     }, current)
     current = result.revision
   }
@@ -761,16 +933,16 @@ async function applyPropertyPlan(
     // `sharedField` is the file's name for it and `sharedPropertyId` the wire's.
     // `null` survives the resolution and travels as `null`: that is the detach
     // signal on both sides, and dropping it left this patch empty.
-    const { sharedField, ...patch } = change.patch
+    const { sharedField, ...rest } = change.patch
     const sharedPropertyId = resolveSharedProperty(
-      file, change.apiName, sharedField, sharedPropertyIds,
+      file, change.apiName, sharedField, ids.sharedPropertyIdByApiName,
     )
     const result = await client.draftCommand({
       kind: 'update_field_metadata',
       objectId: detail.id,
       fieldId: change.id,
       patch: {
-        ...patch,
+        ...semanticTypeOnWire(file, change.apiName, rest, ids),
         ...(sharedPropertyId === undefined ? {} : { sharedPropertyId }),
       },
     }, current)
@@ -785,7 +957,28 @@ async function applyPropertyPlan(
   return current
 }
 
-async function pruneOperation(
+/**
+ * The file's `semanticType` name, replaced by the wire's `semanticTypeId`.
+ *
+ * ONE function for both commands, because both carry the reference: the planner
+ * decides which of the two a given change rides (see `planProperties`), and a
+ * translation written twice is how one of them keeps the authored key and reports a
+ * change it did not make. `null` survives — it is the detach signal on both sides.
+ */
+function semanticTypeOnWire(
+  file: AuthoredFile,
+  propertyApiName: string,
+  patch: Record<string, unknown>,
+  ids: AuthoringIds,
+): Record<string, unknown> {
+  const { semanticType, ...rest } = patch
+  const semanticTypeId = resolveSemanticType(
+    file, `field "${propertyApiName}"`, semanticType, ids.semanticTypeIdByApiName,
+  )
+  return { ...rest, ...(semanticTypeId === undefined ? {} : { semanticTypeId }) }
+}
+
+export async function pruneOperation(
   client: BlueprintAuthoringApi,
   operation: ModelOperation,
   revision: number,
@@ -800,12 +993,23 @@ async function pruneOperation(
   }
   // Deleting a shared field DEGRADES its implementers rather than being refused:
   // each keeps the description and format it was inheriting. Deleting a label must
-  // not delete the mappings underneath it.
+  // not delete the mappings underneath it. A semantic type degrades the same way —
+  // every carrier reverts to an unconstrained field, which is what a field without
+  // one has always been.
   const result = operation.kind === 'link-type'
     ? await client.deleteLinkType(operation.apiName, revision)
-    : operation.kind === 'shared-field'
-      ? await client.deleteSharedProperty(operation.apiName, revision)
-      : await client.deleteMetric(operation.apiName, revision)
+    : operation.kind === 'action'
+      ? await client.deleteAction(operation.apiName, revision)
+      : operation.kind === 'shared-field'
+        ? await client.deleteSharedProperty(operation.apiName, revision)
+        : operation.kind === 'semantic-type'
+          ? await client.deleteSemanticType(operation.apiName, revision)
+          : operation.kind === 'metric'
+            ? await client.deleteMetric(operation.apiName, revision)
+            // Exhaustive on purpose — `assertNever` makes a kind added later a
+            // TYPE error here rather than a silent fall-through to whichever
+            // delete happened to be last.
+            : assertNever(operation.kind, 'prune')
   return nextRevision(result, revision)
 }
 
@@ -827,6 +1031,11 @@ export const blueprintApply: Command = {
     const prune = ctx.flags.prune === true
     const { plan, files, definition, drift } = await computePlan(ctx)
 
+    // BEFORE the first write, not before the prune loop: the operations land first,
+    // so discovering the contradiction between them and the prunes at the end would
+    // leave a half-applied run to unwind by hand.
+    if (prune) assertPrunesLeaveNoDanglingReference(files, plan.prunes)
+
     if (isEmpty(plan)) {
       return { data: { ...plan, applied: [] }, text: renderPlan(plan) }
     }
@@ -846,6 +1055,19 @@ export const blueprintApply: Command = {
       )
     }
 
+    // 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
+    // the prune side did, dying on a raw 409 from the service rather than on the
+    // CliError the create side had already learned to raise.
+    //
+    // Creations before updates, and object types before the kinds that reference them:
+    // a link names both of its endpoints, and a metric names the type it measures.
+    // `ARTIFACT_KINDS` fixes that. Then one pass more, because actions can reference
+    // EACH OTHER: a compensation target has to exist before the action naming it.
+    const ordered = orderForApply(plan.operations)
+    const orderedPrunes = prune ? orderForPrune(plan.prunes, liveCompensations(definition)) : []
+
     if (ctx.flags.yes !== true) {
       throw new CliError(
         `This would apply ${plan.operations.length} change${plan.operations.length === 1 ? '' : 's'}.\n`
@@ -857,24 +1079,25 @@ export const blueprintApply: Command = {
     const byKey = new Map(files.map((file) => [`${file.kind}:${file.apiName}`, file]))
     const applied: string[] = []
     try {
-      // Creations before updates, and object types before the kinds that reference
-      // them: a link names both of its endpoints, and a metric names the type it
-      // measures. `ARTIFACT_KINDS` fixes that order.
-      const ordered = [...plan.operations].sort(byKindThenCreateFirst)
       // Seeded from the revision the PLAN was computed against, then advanced by what
       // each write returns. Never re-read — see `nextRevision`.
       let revision = plan.revision
       // Shared field apiName → id: what the draft already had, plus what this run
       // creates. A file references a shared field by name and the wire takes an
       // id, and one created in this run has no id until its create answers.
-      const sharedPropertyIds = indexBundle(definition).sharedPropertyIdByApiName
+      // …and the same for semantic types, which BOTH carrier kinds resolve.
+      const live = indexBundle(definition)
+      const ids: AuthoringIds = {
+        sharedPropertyIdByApiName: live.sharedPropertyIdByApiName,
+        semanticTypeIdByApiName: live.semanticTypeIdByApiName,
+      }
       for (const operation of ordered) {
         const file = byKey.get(`${operation.kind}:${operation.apiName}`)!
-        revision = await applyOperation(client, operation, file, revision, sharedPropertyIds)
+        revision = await applyOperation(client, operation, file, revision, ids)
         applied.push(`${operation.operation} ${operation.kind} ${operation.apiName}`)
       }
       if (prune) {
-        for (const operation of plan.prunes) {
+        for (const operation of orderedPrunes) {
           revision = await pruneOperation(client, operation, revision)
           applied.push(`delete ${operation.kind} ${operation.apiName}`)
         }
@@ -907,6 +1130,195 @@ function byKindThenCreateFirst(left: ModelOperation, right: ModelOperation): num
   return rank(left) - rank(right)
 }
 
+/**
+ * Reorder action creates so a compensation target is created before the action naming
+ * it.
+ *
+ * `effect.compensationAction` is the one reference an artifact can make to ANOTHER
+ * ARTIFACT OF ITS OWN KIND, and the service resolves it against the draft — so on a
+ * fresh deployment, creating `approveLoan` before `reverseApproval` is refused with
+ * "names an action which is not on the draft". Alphabetical order decided which of the
+ * two a tree got, which is to say it worked or not by accident of naming.
+ *
+ * Only creates are reordered. An update names a target that is already on the draft by
+ * definition, and a plan that mixes the two still creates first — `byKindThenCreateFirst`
+ * has already run.
+ */
+export function orderForApply(operations: ModelOperation[]): ModelOperation[] {
+  return byCompensationDependency([...operations].sort(byKindThenCreateFirst))
+}
+
+/**
+ * Live actions, each with the apiName of the action it compensates.
+ *
+ * The bundle stores `compensationActionId`, so the id is mapped back through the
+ * action list — the prune preflight reasons in names, because that is what a prune
+ * operation carries.
+ */
+function liveCompensations(
+  definition: DefinitionBundle,
+): Array<{ apiName: string; compensates?: string }> {
+  const actions = definition.actions ?? []
+  const byId = new Map(actions.map((action) => [action.id, action.apiName]))
+  return actions.map((action) => {
+    const effect = (action as Record<string, unknown>).effect
+    const id = effect && typeof effect === 'object'
+      ? (effect as Record<string, unknown>).compensationActionId
+      : undefined
+    const compensates = typeof id === 'string' ? byId.get(id) : undefined
+    return compensates === undefined ? { apiName: action.apiName } : { apiName: action.apiName, compensates }
+  })
+}
+
+/**
+ * Deleting runs every dependency the other way round.
+ *
+ * REVERSE `ARTIFACT_KINDS`, because an action names an object type: pruning in creation
+ * order removed the type out from under everything still pointing at it. And within the
+ * action group, the MIRROR of `byCompensationDependency` — `deleteDraftBlueprintAction`
+ * refuses with `ACTION_COMPENSATION_REFERENCE_CONFLICT` while any surviving action still
+ * names the target, so a compensator has to go before the action it compensates.
+ * Sorting by apiName alone meant renaming a pair decided whether the same tree pruned.
+ */
+export function orderForPrune(
+  prunes: ModelOperation[],
+  liveActions: ReadonlyArray<{ apiName: string; compensates?: string }> = [],
+): ModelOperation[] {
+  const byKind = [...prunes].sort(
+    (left, right) => ARTIFACT_KINDS.indexOf(right.kind) - ARTIFACT_KINDS.indexOf(left.kind),
+  )
+  const actions = byKind.filter((operation) => operation.kind === 'action')
+  if (actions.length === 0) return byKind
+
+  const pruned = new Set(actions.map((operation) => operation.apiName))
+
+  // A SURVIVOR blocks the delete just as surely as a pruned pair does, and it is the
+  // commoner case: `deleteDraftBlueprintAction` refuses while ANY remaining action
+  // still names the target. Ordering among the prune set alone missed it entirely —
+  // deleting one half of a pair planned clean and then died on a raw 409 mid-apply,
+  // after the creates had committed, which is the half-applied outcome this pass
+  // exists to prevent.
+  const blocked = liveActions.filter((action) =>
+    action.compensates !== undefined
+    && pruned.has(action.compensates)
+    && !pruned.has(action.apiName))
+  if (blocked.length > 0) {
+    const named = blocked
+      .map((action) => `${action.apiName} → ${action.compensates}`)
+      .sort()
+      .join(', ')
+    throw new CliError(
+      `${blocked.length === 1 ? 'An action that survives this prune still names' : 'Actions that survive this prune still name'} `
+        + `one being deleted as its compensation: ${named}.`,
+      {
+        code: 'USAGE',
+        hint: 'Remove `compensationAction` from the surviving action and apply, then prune.',
+      },
+    )
+  }
+  if (actions.length < 2) return byKind
+  // Reversed edge: `compensator → target` means the compensator is deleted FIRST, so
+  // the target depends on it rather than the other way round.
+  const compensatorsOf = new Map<string, ModelOperation[]>()
+  for (const operation of actions) {
+    const effect = operation.liveDocument?.effect
+    const named = effect && typeof effect === 'object'
+      ? (effect as Record<string, unknown>).compensationAction
+      : undefined
+    if (typeof named !== 'string' || !pruned.has(named)) continue
+    const list = compensatorsOf.get(named) ?? []
+    list.push(operation)
+    compensatorsOf.set(named, list)
+  }
+
+  const ordered: ModelOperation[] = []
+  const placed = new Set<string>()
+  const visiting = new Set<string>()
+  const visit = (operation: ModelOperation): void => {
+    if (placed.has(operation.apiName)) return
+    // A mutual pair cannot be pruned by ordering alone, and it is refused HERE rather
+    // than left to the service. There is a way through — drop the link, then prune —
+    // but the service's 409 arrives mid-run, after every create and update in the same
+    // apply has already committed. The create side pre-flights the mirror case; the
+    // asymmetry was the defect, not the refusal.
+    if (visiting.has(operation.apiName)) {
+      throw new CliError(
+        `${operation.apiName} and its compensation action name each other, so neither can be deleted first.`,
+        {
+          code: 'USAGE',
+          hint: 'Remove `compensationAction` from one of them and apply, then prune both.',
+        },
+      )
+    }
+    visiting.add(operation.apiName)
+    for (const compensator of compensatorsOf.get(operation.apiName) ?? []) visit(compensator)
+    visiting.delete(operation.apiName)
+    placed.add(operation.apiName)
+    ordered.push(operation)
+  }
+  for (const operation of actions) visit(operation)
+
+  return [...ordered, ...byKind.filter((operation) => operation.kind !== 'action')]
+}
+
+function byCompensationDependency(operations: ModelOperation[]): ModelOperation[] {
+  const creates = new Map<string, ModelOperation>()
+  for (const operation of operations) {
+    if (operation.kind === 'action' && operation.operation === 'create') {
+      creates.set(operation.apiName, operation)
+    }
+  }
+  if (creates.size < 2) return operations
+
+  const target = (operation: ModelOperation): string | undefined => {
+    const effect = operation.document?.effect
+    if (!effect || typeof effect !== 'object') return undefined
+    const named = (effect as Record<string, unknown>).compensationAction
+    // Only a name that is ALSO being created here constrains the order. One that is
+    // already on the draft resolves whenever this runs.
+    return typeof named === 'string' && creates.has(named) ? named : undefined
+  }
+
+  const ordered: ModelOperation[] = []
+  const placed = new Set<string>()
+  const visiting = new Set<string>()
+  const visit = (operation: ModelOperation): void => {
+    if (placed.has(operation.apiName)) return
+    if (visiting.has(operation.apiName)) {
+      // Two actions naming each other cannot both be created first, by either party.
+      // Saying so beats a 409 from the service that names only one of the pair.
+      throw new CliError(
+        `${operation.apiName} and its compensation action name each other, so neither can be created first.`,
+        {
+          code: 'USAGE',
+          hint: 'Apply one without `compensationAction`, then add the link in a second apply.',
+        },
+      )
+    }
+    visiting.add(operation.apiName)
+    const dependency = target(operation)
+    if (dependency) visit(creates.get(dependency)!)
+    visiting.delete(operation.apiName)
+    placed.add(operation.apiName)
+    ordered.push(operation)
+  }
+
+  // THREE buckets, not two. Collecting everything that is not an action create into
+  // one `rest` and appending the creates after it put every action UPDATE ahead of
+  // every action CREATE — inverting the create-first rule the incoming sort had just
+  // established, and aborting a mixed plan after the earlier writes had committed.
+  const before: ModelOperation[] = []
+  const updates: ModelOperation[] = []
+  for (const operation of operations) {
+    if (operation.kind !== 'action') before.push(operation)
+    else if (operation.operation === 'create') visit(operation)
+    else updates.push(operation)
+  }
+  // Actions sort last in `ARTIFACT_KINDS`, so the other kinds keep their place ahead of
+  // them; only the action creates are permuted, and only among themselves.
+  return [...before, ...ordered, ...updates]
+}
+
 export const blueprintNew: Command = {
   meta: {
     noun: 'blueprint',
@@ -915,13 +1327,14 @@ export const blueprintNew: Command = {
       { name: 'kind', required: true, description: `One of: ${ARTIFACT_KINDS.join(', ')}` },
       { name: 'apiName', required: true, description: 'The artifact’s API name' },
     ],
-    flags: { dir: 'string' },
+    flags: { dir: 'string', template: 'string' },
     offline: true,
     summary: 'Scaffold an artifact file that validates as written',
     examples: [
       'frontera blueprint new object-type Customer',
       'frontera blueprint new link-type customerHoldsPolicy',
       'frontera blueprint new shared-field accountCode',
+      'frontera blueprint new semantic-type completionRate --template percentage',
     ],
   },
   async run(ctx) {
@@ -945,6 +1358,7 @@ export const blueprintNew: Command = {
         hint: `${describeApiNameRule(kind)} — and it becomes the file name, so nothing else fits.`,
       })
     }
+    const template = semanticTypeTemplate(ctx.flags.template, kind)
     const directory = root(ctx)
     const relative = pathFor(kind, apiName)
     if (existsSync(resolve(directory, relative))) {
@@ -957,7 +1371,7 @@ export const blueprintNew: Command = {
       kind,
       apiName,
       path: relative,
-      document: scaffold(kind, apiName),
+      document: scaffold(kind, apiName, template === undefined ? {} : { template }),
     }
     writeTree(directory, [file])
     return {
@@ -967,6 +1381,35 @@ export const blueprintNew: Command = {
   },
 }
 
+/**
+ * `--template`, validated where it is read.
+ *
+ * Refused on the kinds that have none rather than ignored: a flag silently doing
+ * nothing is how a reader concludes the scaffold ignored their choice and edits the
+ * file by hand ever after.
+ */
+function semanticTypeTemplate(
+  declared: unknown,
+  kind: ArtifactKind,
+): SemanticTypeTemplate | undefined {
+  if (declared === undefined) return undefined
+  if (kind !== 'semantic-type') {
+    throw new CliError(`--template applies to semantic-type, not ${kind}.`, {
+      code: 'USAGE',
+      hint: `frontera blueprint new semantic-type <apiName> --template ${SEMANTIC_TYPE_TEMPLATE_NAMES[0]}`,
+    })
+  }
+  const name = String(declared)
+  if (!isSemanticTypeTemplate(name)) {
+    throw new CliError(`Unknown template "${name}".`, {
+      code: 'USAGE',
+      hint: `One of: ${SEMANTIC_TYPE_TEMPLATE_NAMES.join(', ')}. `
+        + 'Each writes a rule the service accepts unedited.',
+    })
+  }
+  return name
+}
+
 export const blueprintRename: Command = {
   meta: {
     noun: 'blueprint',