@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/commands/blueprint/declarative.ts

@@ -6,7 +6,10 @@ import {
   linkTypeCreateBody,
   linkTypeStructure,
   objectTypeCreateBody,
+  objectTypeSensitivity,
+  fieldSensitivityOf,
   actionBody,
+  declaredPropertyType,
   metricCreateBody,
   metricPatchBody,
   readBacking,
@@ -18,6 +21,8 @@ import {
   sharedPropertyPatchBody,
   type AuthoringIds,
 } from '../../blueprint/compile'
+import { metricRuleProblems } from '../../blueprint/metric-rules'
+import { actionRuleProblems, type ActionRuleProblems, type InheritedConflict } from '../../blueprint/action-rules'
 import { pickCurrentRevision } from '../../blueprint/dataset-revision'
 import {
   assertPrunesLeaveNoDanglingReference,
@@ -38,11 +43,19 @@ import {
   type DefinitionBundle,
 } from '../../blueprint/model'
 import { toFiles } from '../../blueprint/projection'
+import { sourceSystemHint } from '../../local/local-blueprint-errors'
+import { inheritedFromPull, unchangedSincePull } from '../../local/local-check-inherited'
+import { localProject } from '../../local/local-project'
+import { localRuntimeAt } from '../../local/local-runtime-target'
 import { renderDrift, renderPlan } from '../../blueprint/render'
 import {
   SEMANTIC_TYPE_TEMPLATE_NAMES,
   isSemanticTypeTemplate,
   scaffold,
+  ACTION_TEMPLATES,
+  isActionTemplate,
+  type ActionTemplate,
+  type ScaffoldOptions,
   type SemanticTypeTemplate,
 } from '../../blueprint/scaffold'
 import { pathFor, readTree, removeFromTree, writeTree } from '../../blueprint/tree'
@@ -244,12 +257,36 @@ function existingPaths(directory: string): string[] {
   }
 }
 
+/**
+ * What a pulled project says about its Actions' semantic-type conflicts: which
+ * are the workspace's (`inheritedFromPull`: the Action and what the conflict
+ * rests on unchanged since the pull), and whether this run writes to the
+ * project's own local runtime, which takes such an Action as the workspace
+ * runs it. Anywhere else the service's own check decides (it refuses only a
+ * conflict a write adds), so `plan` is never stricter than the platform.
+ */
+function inheritance(ctx: CommandContext): { conflict?: InheritedConflict; local: boolean } {
+  let root: string
+  try {
+    root = localProject(ctx.cwd).root
+  } catch {
+    return { local: false }
+  }
+  const unchanged = unchangedSincePull(root)
+  if (!unchanged.refs.size) return { local: false }
+  return { conflict: inheritedFromPull(unchanged), local: localRuntimeAt(ctx.cwd, ctx.apiUrl) !== null }
+}
+
 async function computePlan(ctx: CommandContext): Promise<{
   plan: Plan
   files: AuthoredFile[]
   /** The draft the plan was computed against — `apply` indexes it for id resolution. */
   definition: DefinitionBundle
   drift: Array<{ objectApiName: string; datasetName: string; currentDigest: string }>
+  /** The Action files' rule problems (`action-rules.ts`): what the draft would refuse, and what would not deploy. */
+  actionProblems: ActionRuleProblems
+  /** The Actions written to the local runtime as the workspace runs them (`inheritedActions`, on the local runtime only). */
+  inheritedWrites: ReadonlySet<string>
 }> {
   const client = api(ctx)
   const directory = root(ctx)
@@ -260,6 +297,15 @@ async function computePlan(ctx: CommandContext): Promise<{
     })
   }
   const files = readTree(directory)
+  // A measure's filters the draft would refuse: said by `plan`, and before `apply` writes anything.
+  const metricProblems = metricRuleProblems(files)
+  if (metricProblems.length) {
+    throw new CliError(`${metricProblems.length} metric problem${metricProblems.length === 1 ? '' : 's'} the draft would refuse, so nothing was planned or applied:\n${metricProblems.map((p) => `  ✕ ${p}`).join('\n')}`, {
+      code: 'VALIDATION_ERROR',
+      hint: 'fix each line in its file; a measure\'s `filters` is one condition, e.g. { property: state, op: ne, value: closed }, or several combined as { and: [ …conditions ] }',
+      details: { metrics: metricProblems },
+    })
+  }
   const { definition, revision } = await client.draft()
   const plan = withheldPrunes(diff(files, definition, revision), directory)
 
@@ -290,7 +336,87 @@ async function computePlan(ctx: CommandContext): Promise<{
       drift.push({ objectApiName: pin.objectApiName, datasetName, currentDigest: current.schemaDigest })
     }
   }
-  return { plan, files, definition, drift }
+  const inherits = inheritance(ctx)
+  const actionProblems = actionRuleProblems(files, inherits.conflict)
+  const inheritedWrites = new Set(inherits.local ? actionProblems.inheritedActions ?? [] : [])
+  return { plan, files, definition, drift, actionProblems: await withServiceActionChecks(client, plan, files, actionProblems, inheritedWrites), inheritedWrites }
+}
+
+/**
+ * The draft route's own checks of each Action this plan writes, run by the
+ * service with nothing written (`checkAction`), added to the file rules
+ * `actionRuleProblems` checks here. The file rules are a copy of what the
+ * route refuses, and a copy misses some: a rule the route has and the copy
+ * doesn't passes `plan` and is refused at apply.
+ *
+ * An Action that names something this same plan creates (an object type, a
+ * property added to one, another Action) cannot be checked before that is
+ * written; the service says so (`ACTION_REFERENCE_NOT_ON_DRAFT`) and the
+ * write checks it in order. A platform without the check is not asked.
+ */
+async function withServiceActionChecks(
+  client: BlueprintAuthoringApi,
+  plan: Plan,
+  files: AuthoredFile[],
+  problems: ActionRuleProblems,
+  inheritedWrites: ReadonlySet<string> = new Set(),
+): Promise<ActionRuleProblems> {
+  const writing = plan.operations.filter((o) => o.kind === 'action' && o.operation !== 'delete' && !problems.refusedActions.includes(o.apiName))
+  if (writing.length === 0) return problems
+  const planned = new Set(plan.operations.filter((o) => o.operation !== 'delete').map((o) => `${o.kind}:${o.apiName}`))
+  const createdHere = (missing: { what?: unknown; name?: unknown } | undefined): boolean => {
+    const name = typeof missing?.name === 'string' ? missing.name : ''
+    if (missing?.what === 'object type') return planned.has(`object-type:${name}`)
+    if (missing?.what === 'property' || missing?.what === 'lifecycle transition') return planned.has(`object-type:${name.split('.')[0]}`)
+    if (missing?.what === 'action') return planned.has(`action:${name}`)
+    return false
+  }
+  const refused = [...problems.refused]
+  const refusedActions = [...problems.refusedActions]
+  for (const operation of writing) {
+    const file = files.find((f) => f.kind === 'action' && f.apiName === operation.apiName)
+    if (!file) continue
+    try {
+      await client.checkAction(actionBody(file), inheritedWrites.has(operation.apiName))
+    } catch (err) {
+      if (!(err instanceof CliError)) throw err
+      // An older platform (no such route, or one its key lane does not open), or nothing adopted yet: the write is the check.
+      if (err.code === 'NOT_FOUND' || err.code === 'FORBIDDEN') return problems
+      const details = err.details as { reason?: unknown; missing?: { what?: unknown; name?: unknown }; issues?: unknown } | undefined
+      // A name this plan creates is not a problem, but the fields the platform refused alongside it are.
+      const fieldIssues = Array.isArray(details?.issues) && details.issues.length > 0
+      if (details?.reason === 'ACTION_REFERENCE_NOT_ON_DRAFT' && createdHere(details.missing) && !fieldIssues) continue
+      if (err.code !== 'VALIDATION_ERROR' && err.code !== 'CONFLICT') throw err
+      // One line: `local dev` leaves each refused file off by these lines (`refusedByRules`).
+      refused.push(`${file.path}: ${err.message.replace(/\s*\n\s*/g, ' ')}`)
+      refusedActions.push(operation.apiName)
+    }
+  }
+  return { ...problems, refused, refusedActions }
+}
+
+/**
+ * The Action rule problems, said under the plan: a refusal as an error line,
+ * what would not deploy as a warning (`local dev` carries `warning:` lines).
+ */
+function renderActionProblems(problems: ActionRuleProblems): string {
+  return [
+    ...problems.refused.map((p) => `  error: ${p}`),
+    ...problems.undeployable.map((p) => `  warning: ${p} (it applies, but its write path won't deploy)`),
+    ...(problems.inherited ?? []).map((p) => `  warning: ${p}`),
+  ].join('\n')
+}
+
+/** Refused before the first write: an Action the draft route would refuse, in a file this run applies. */
+function assertActionsApplicable(problems: ActionRuleProblems, operations: ModelOperation[]): void {
+  const applying = new Set(operations.filter((o) => o.kind === 'action').map((o) => o.apiName))
+  if (!problems.refusedActions.some((name) => applying.has(name))) return
+  const refused = problems.refused
+  throw new CliError(`${refused.length} governed Action rule${refused.length === 1 ? ' is' : 's are'} broken, so nothing was applied:\n${refused.map((p) => `  ✕ ${p}`).join('\n')}`, {
+    code: 'VALIDATION_ERROR',
+    hint: 'fix each line in its file, then `frontera blueprint plan` checks it again without writing',
+    details: { refused, undeployable: problems.undeployable },
+  })
 }
 
 /**
@@ -333,7 +459,7 @@ export const blueprintPlan: Command = {
     examples: ['frontera blueprint plan', 'frontera blueprint plan --json'],
   },
   async run(ctx) {
-    const { plan, files, definition, drift } = await computePlan(ctx)
+    const { plan, files, definition, drift, actionProblems } = 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
@@ -343,10 +469,10 @@ export const blueprintPlan: Command = {
       assertPrunesLeaveNoDanglingReference(files, plan.prunes)
       orderForPrune(plan.prunes, liveCompensations(definition))
     }
-    const body = [renderPlan(plan, { prune: ctx.flags.prune === true }), renderDrift(drift)]
+    const body = [renderPlan(plan, { prune: ctx.flags.prune === true }), renderDrift(drift), renderActionProblems(actionProblems)]
       .filter(Boolean)
       .join('\n')
-    return { data: { ...plan, drift }, text: body }
+    return { data: { ...plan, drift, actionProblems }, text: body }
   },
 }
 
@@ -367,6 +493,8 @@ export async function applyOperation(
   file: AuthoredFile,
   revision: number,
   ids: AuthoringIds,
+  /** The Actions written as the workspace runs them (`inheritedWrites`). */
+  inheritedWrites: ReadonlySet<string> = new Set(),
 ): Promise<number> {
   const resolveDataset = (name: string) => resolveRevision(client, name)
 
@@ -419,6 +547,8 @@ export async function applyOperation(
         )
       }
       ids.sharedPropertyIdByApiName.set(operation.apiName, id)
+      const createdType = (file.document as { propertyType?: unknown }).propertyType
+      if (typeof createdType === 'string') ids.sharedPropertyTypeByApiName?.set(operation.apiName, createdType)
       return nextRevision(created, revision)
     }
     assertApplicable('shared-field', file, operation.liveDocument)
@@ -436,7 +566,7 @@ export async function applyOperation(
         await objectTypeCreateBody(file, revision, resolveDataset, ids),
         revision,
       )
-      return nextRevision(created, revision)
+      return applyCalculatedFields(client, operation.apiName, file, nextRevision(created, revision))
     }
     // Refused BEFORE the first write, not after some of them. Everything this
     // executor can express is enumerated below; a difference outside that set has no
@@ -457,9 +587,10 @@ export async function applyOperation(
       current = nextRevision(updated, revision)
     }
     current = await applyObjectKeys(client, operation.apiName, file, operation.liveDocument, current)
-    return applyPropertyPlan(
+    current = await applyPropertyPlan(
       client, operation.apiName, file, operation.liveDocument, current, ids,
     )
+    return applyCalculatedFields(client, operation.apiName, file, current)
   }
 
   if (operation.kind === 'link-type') {
@@ -484,9 +615,10 @@ export async function applyOperation(
     if (operation.operation !== 'create') {
       assertApplicable('action', { ...file, document: body }, operation.liveDocument)
     }
+    const inherited = inheritedWrites.has(operation.apiName)
     const result = operation.operation === 'create'
-      ? await client.createAction(body, revision)
-      : await client.updateAction(operation.apiName, body, revision)
+      ? await client.createAction(body, revision, inherited)
+      : await client.updateAction(operation.apiName, body, revision, inherited)
     return nextRevision(result, revision)
   }
 
@@ -598,10 +730,15 @@ export function assertApplicable(
   // The SAME predicate the plan used to decide this artifact changed. An equality
   // comparison here would disagree with it about key order and about the fields a file
   // omits, and refuse the run naming a field the plan never called changed.
-  const unmappable = Object.keys(file.document).filter((field) =>
-    !applicable.has(field) && !satisfies(file.document[field], live[field], field))
+  // An object type's `governance.sensitivity` has a route (the update's `sensitivity`);
+  // the rest of governance (ownership) has none, so only that part is compared here.
+  const comparable = kind === 'object-type' ? withoutSensitivity(file.document) : file.document
+  const against = kind === 'object-type' ? withoutSensitivity(live) : live
+  const unmappable = Object.keys(comparable).filter((field) =>
+    !applicable.has(field) && !satisfies(comparable[field], against[field], field))
   if (kind === 'object-type') unmappable.push(...unmappablePropertyFields(file.document, live))
   if (unmappable.length === 0) return
+  const absent = NOT_CARRIED[kind]
   throw new CliError(
     `${file.path}: ${unmappable.join(', ')} ${unmappable.length === 1 ? 'differs' : 'differ'} from the draft, `
     + 'and no authoring route can apply that.',
@@ -610,15 +747,40 @@ export function assertApplicable(
       hint: kind === 'metric' && unmappable.includes('objectType')
         ? 'A metric measures one object type for its lifetime. To move it, delete the file and '
           + '`apply --prune`, then write it again against the new object type.'
-        : 'Revert those fields to match the draft, or change them in the Console. '
-          + 'Applying would report a change that did not happen.',
+        : absent && unmappable.every((field) => absent.has(field))
+          ? `A ${kind} has no ${[...absent].join(' or ')}: the Blueprint keeps no such value for it. `
+            + `Remove ${unmappable.map((field) => `\`${field}\``).join(' and ')} from ${file.path} and apply again.`
+          : `Remove ${unmappable.length === 1 ? 'that field' : 'those fields'} from ${file.path}, or set `
+            + `${unmappable.length === 1 ? 'it' : 'them'} back to the draft's value, and apply again: a file that `
+            + 'leaves a field out keeps the draft\'s. Applying would report a change that did not happen.',
     },
   )
 }
 
+/**
+ * Fields a kind's file names in other kinds' shapes but that the kind itself does
+ * not have: no route sets them, and no screen does either, so the only fix is to
+ * leave them out. A metric's draft entry has no lifecycle status or visibility
+ * (`blueprintMetricDefinitionSchemaV1` is strict), and the metric file schema no
+ * longer lists them; this names the fix for a file written before it changed.
+ */
+const NOT_CARRIED: Partial<Record<ArtifactKind, Set<string>>> = {
+  metric: new Set(['status', 'visibility']),
+}
+
+/** A document with `governance.sensitivity` (and a top-level `sensitivity`) left out: the part of governance no route takes. */
+export function withoutSensitivity(document: Record<string, unknown>): Record<string, unknown> {
+  const { sensitivity: _top, ...rest } = document
+  const governance = rest.governance
+  if (!governance || typeof governance !== 'object' || Array.isArray(governance)) return rest
+  const { sensitivity: _nested, ...others } = governance as Record<string, unknown>
+  return Object.keys(others).length ? { ...rest, governance: others } : (({ governance: _g, ...noGovernance }) => noGovernance)(rest)
+}
+
 /**
  * Property fields the field commands do not carry. A property's `calculation`
- * (a location included) and its own `sensitivity` have no route from a file:
+ * can only be ADDED (a location, by `applyCalculatedFields`), not changed, and
+ * its own `sensitivity` has no route from a file:
  * applying one would report a classification or a formula that never changed.
  * Named as `properties.<apiName>.<field>`.
  */
@@ -629,13 +791,76 @@ function unmappablePropertyFields(document: Record<string, unknown>, live: Recor
   const liveProperties = Array.isArray(live.properties) ? live.properties as Array<Record<string, unknown>> : []
   const liveByName = new Map(liveProperties.map((property) => [String(property.apiName), property]))
   return declared.flatMap((property) => {
-    const counterpart = liveByName.get(String(property.apiName)) ?? {}
+    const live = liveByName.get(String(property.apiName))
+    const counterpart = live ?? {}
     return UNAPPLICABLE_PROPERTY_FIELDS
+      // A location calculation not on the draft yet is added (`applyCalculatedFields`); one there can't be changed.
+      .filter((field) => !(field === 'calculation' && !live && isLocation(property.calculation)))
       .filter((field) => property[field] !== undefined && !satisfies(property[field], counterpart[field], field))
       .map((field) => `properties.${String(property.apiName)}.${field}`)
   })
 }
 
+/** A location calculation as a file writes it: `{ kind: location, latitude, longitude }`, by apiName. */
+function isLocation(value: unknown): value is { kind: 'location'; latitude: string; longitude: string } {
+  const v = value as { kind?: unknown; latitude?: unknown; longitude?: unknown } | null
+  return !!v && v.kind === 'location' && typeof v.latitude === 'string' && typeof v.longitude === 'string'
+}
+
+/**
+ * The type's calculated location fields that the draft does not have yet:
+ * each added by `add_field` with its calculation, naming its latitude and
+ * longitude fields by this draft's ids. The create route and the property
+ * plan leave them out, since they read no column.
+ */
+async function applyCalculatedFields(client: BlueprintAuthoringApi, apiName: string, file: AuthoredFile, revision: number): Promise<number> {
+  const declared = Array.isArray(file.document.properties) ? (file.document.properties as Array<Record<string, unknown>>) : []
+  const calculated = declared.filter((p) => p.calculation !== undefined)
+  if (!calculated.length) return revision
+  const detail = await client.getObjectTypeDetail(apiName)
+  if (!detail?.id) return revision
+  const idByApiName = new Map(detail.properties.filter((p) => p.apiName && p.id).map((p) => [String(p.apiName), String(p.id)]))
+  let current = revision
+  for (const property of calculated) {
+    const name = String(property.apiName)
+    if (idByApiName.has(name)) continue
+    const calc = property.calculation
+    if (!isLocation(calc)) {
+      throw new CliError(`${file.path}: property "${name}" has a calculation that cannot be authored from a file.`, {
+        code: 'USAGE',
+        hint: 'A file adds a location: calculation: { kind: location, latitude: <field>, longitude: <field> }.',
+      })
+    }
+    const latitudePropertyId = idByApiName.get(calc.latitude)
+    const longitudePropertyId = idByApiName.get(calc.longitude)
+    if (!latitudePropertyId || !longitudePropertyId) {
+      throw new CliError(`${file.path}: "${name}" is a location from ${calc.latitude} and ${calc.longitude}, and ${!latitudePropertyId ? calc.latitude : calc.longitude} is not one of ${apiName}'s fields.`, {
+        code: 'USAGE',
+        hint: 'A location names two number fields of the same type, by apiName.',
+      })
+    }
+    const result = await client.draftCommand({
+      kind: 'add_field',
+      objectId: detail.id,
+      field: {
+        id: crypto.randomUUID(),
+        apiName: name,
+        displayName: String(property.displayName ?? name),
+        valueType: 'geopoint',
+        propertyType: 'attribute',
+        sourceColumn: '',
+        calculation: { kind: 'location', latitudePropertyId, longitudePropertyId },
+        required: false,
+        unique: false,
+        status: 'active',
+        visibility: 'normal',
+      },
+    }, current)
+    current = result.revision
+  }
+  return current
+}
+
 /**
  * `primaryKey` and `title` — the two references a file states by property apiName.
  *
@@ -722,6 +947,9 @@ export function objectTypeMetadataChanges(
   if (Array.isArray(groups) && JSON.stringify(groups) !== JSON.stringify(live?.groups ?? [])) {
     patch.groups = groups
   }
+  // The classification: the update's top-level `sensitivity`, sent when it differs from the draft's.
+  const sensitivity = objectTypeSensitivity(document)
+  if (sensitivity && !satisfies(sensitivity, live ? objectTypeSensitivity(live) : undefined)) patch.sensitivity = sensitivity
   return patch
 }
 
@@ -768,6 +996,8 @@ function planProperties(
   live: Array<Record<string, unknown>>,
   backing: ReturnType<typeof readBacking>,
   idByApiName: Map<string, string>,
+  /** The live object type's classification: a field at it takes it, rather than holding its own. */
+  liveObjectSensitivity?: unknown,
 ): PropertyPlan {
   const declared = Array.isArray(file.document.properties)
     ? (file.document.properties as Array<Record<string, unknown>>)
@@ -781,7 +1011,8 @@ function planProperties(
     const name = String(property.apiName)
     const counterpart = liveByName.get(name)
     if (!counterpart) {
-      plan.adds.push(property)
+      // Added after the plan, once its latitude and longitude fields are there (`applyCalculatedFields`).
+      if (!property.calculation) plan.adds.push(property)
       continue
     }
     const schemaPatch: Record<string, unknown> = {}
@@ -836,6 +1067,16 @@ function planProperties(
         else metadataPatch.semanticType = wanted
       }
     }
+    // The field's own classification, against what it holds now. A read gives every field its
+    // effective one, so a value at the object type's is "takes the object's" on both sides; the
+    // file's absence (or `null`, or its object's own value) is that too, and travels as `null`.
+    // Not on a location, which takes its latitude's and longitude's.
+    if (!property.calculation) {
+      const wanted = fieldSensitivityOf(property, objectTypeSensitivity(file.document)).sensitivity ?? null
+      const liveClass = liveObjectSensitivity && typeof liveObjectSensitivity === 'object' ? (liveObjectSensitivity as { classification?: unknown }).classification : undefined
+      const current = typeof counterpart.sensitivity === 'string' && counterpart.sensitivity !== liveClass ? counterpart.sensitivity : null
+      if (wanted !== current) metadataPatch.sensitivity = 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.
@@ -881,7 +1122,7 @@ async function applyPropertyPlan(
   const liveProperties = Array.isArray(liveDocument?.properties)
     ? (liveDocument.properties as Array<Record<string, unknown>>)
     : []
-  const plan = planProperties(file, liveProperties, backing, idByApiName)
+  const plan = planProperties(file, liveProperties, backing, idByApiName, objectTypeSensitivity(liveDocument ?? {}))
 
   // Every add needs a column, and the service offers no name-match fallback. Checked
   // for ALL of them before the first write, so a partial run cannot start.
@@ -940,7 +1181,7 @@ async function applyPropertyPlan(
         id: crypto.randomUUID(),
         apiName: name,
         displayName: String(property.displayName ?? name),
-        propertyType: (property.propertyType as string | undefined) ?? 'attribute',
+        propertyType: declaredPropertyType(property, ids.sharedPropertyTypeByApiName),
         valueType: String(property.valueType ?? 'string'),
         sourceColumn: column,
         ...(sourceField === undefined || sourceField === null ? {} : { sourceField }),
@@ -955,8 +1196,10 @@ async function applyPropertyPlan(
         // Same collapse: `add_field`'s uuid is not nullable, and a field being
         // created has no meaning to detach from.
         ...(typeof semanticTypeId === 'string' ? { semanticTypeId } : {}),
+        // Its own classification, when the file gives one other than the object type's.
+        ...fieldSensitivityOf(property, objectTypeSensitivity(file.document)),
       },
-    }, current)
+    }, current).catch((err) => { throw stewardRefusal(err, file, name, fieldSensitivityOf(property, objectTypeSensitivity(file.document)).sensitivity !== undefined) })
     current = result.revision
   }
   for (const change of plan.schemaChanges) {
@@ -984,7 +1227,7 @@ async function applyPropertyPlan(
         ...semanticTypeOnWire(file, change.apiName, rest, ids),
         ...(sharedPropertyId === undefined ? {} : { sharedPropertyId }),
       },
-    }, current)
+    }, current).catch((err) => { throw stewardRefusal(err, file, change.apiName, 'sensitivity' in rest) })
     current = result.revision
   }
   for (const removal of plan.removes) {
@@ -996,6 +1239,20 @@ async function applyPropertyPlan(
   return current
 }
 
+/**
+ * A refusal of a command that classifies a field, said as what it needs: a
+ * field's classification is a Blueprint Steward's to set, as its object
+ * type's is, and a key without that role is refused for it alone.
+ */
+function stewardRefusal(err: unknown, file: AuthoredFile, field: string, classifies: boolean): unknown {
+  if (!classifies || !(err instanceof CliError) || (err.code !== 'FORBIDDEN' && err.code !== 'UNAUTHORIZED')) return err
+  return new CliError(`${file.path}: field "${field}" sets its own classification (sensitivity), which only a Blueprint Steward may do: ${err.message}`, {
+    code: err.code,
+    hint: 'apply it with a credential of a Blueprint Steward, or leave `sensitivity` out so the field takes its object type\'s',
+    cause: err,
+  })
+}
+
 /**
  * The file's `semanticType` name, replaced by the wire's `semanticTypeId`.
  *
@@ -1068,7 +1325,9 @@ export const blueprintApply: Command = {
   async run(ctx) {
     const client = api(ctx)
     const prune = ctx.flags.prune === true
-    const { plan, files, definition, drift } = await computePlan(ctx)
+    const { plan, files, definition, drift, actionProblems, inheritedWrites } = await computePlan(ctx)
+    assertActionsApplicable(actionProblems, plan.operations)
+    const actionWarnings = renderActionProblems({ refused: [], undeployable: actionProblems.undeployable, refusedActions: [], ...(actionProblems.inherited ? { inherited: actionProblems.inherited } : {}) })
 
     // 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
@@ -1076,7 +1335,7 @@ export const blueprintApply: Command = {
     if (prune) assertPrunesLeaveNoDanglingReference(files, plan.prunes)
 
     if (isEmpty(plan)) {
-      return { data: { ...plan, applied: [] }, text: renderPlan(plan) }
+      return { data: { ...plan, applied: [], actionProblems }, text: [renderPlan(plan), actionWarnings].filter(Boolean).join('\n') }
     }
 
     // Drift is REPORTED, and blocks only the artifacts it is about. It used to throw
@@ -1117,6 +1376,8 @@ export const blueprintApply: Command = {
 
     const byKey = new Map(files.map((file) => [`${file.kind}:${file.apiName}`, file]))
     const applied: string[] = []
+    // The step being written when a write fails: said, so a caller can tell which file was refused.
+    let current: string | null = null
     try {
       // Seeded from the revision the PLAN was computed against, then advanced by what
       // each write returns. Never re-read — see `nextRevision`.
@@ -1129,18 +1390,27 @@ export const blueprintApply: Command = {
       const ids: AuthoringIds = {
         sharedPropertyIdByApiName: live.sharedPropertyIdByApiName,
         semanticTypeIdByApiName: live.semanticTypeIdByApiName,
+        sharedPropertyTypeByApiName: new Map(
+          (definition.sharedProperties ?? []).flatMap((shared) => {
+            const type = (shared as { propertyType?: unknown }).propertyType
+            return typeof type === 'string' ? [[shared.apiName, type] as const] : []
+          }),
+        ),
       }
       for (const operation of ordered) {
         const file = byKey.get(`${operation.kind}:${operation.apiName}`)!
-        revision = await applyOperation(client, operation, file, revision, ids)
-        applied.push(`${operation.operation} ${operation.kind} ${operation.apiName}`)
+        current = `${operation.operation} ${operation.kind} ${operation.apiName}`
+        revision = await applyOperation(client, operation, file, revision, ids, inheritedWrites)
+        applied.push(current)
       }
       if (prune) {
         for (const operation of orderedPrunes) {
+          current = `delete ${operation.kind} ${operation.apiName}`
           revision = await pruneOperation(client, operation, revision)
-          applied.push(`delete ${operation.kind} ${operation.apiName}`)
+          applied.push(current)
         }
       }
+      current = null
     } catch (err) {
       // What landed is as important as what failed: the draft is shared, and a
       // partial run that does not say where it stopped cannot be resumed safely.
@@ -1152,8 +1422,9 @@ export const blueprintApply: Command = {
       // failure — a draft that moved — handed out for every failure, so a
       // validation refusal read as "Validation failed / re-plan", which no
       // amount of re-planning fixes.
-      const inner = err instanceof CliError ? err.hint : undefined
-      throw new CliError(`${done}${(err as Error).message}`, {
+      const inner = sourceSystemHint(`${(err as Error).message}\n${err instanceof CliError ? err.hint ?? '' : ''}`) ?? (err instanceof CliError ? err.hint : undefined)
+      const stopped = current ? `Stopped at: ${current}\n` : ''
+      throw new CliError(`${done}${stopped}${(err as Error).message}`, {
         code: err instanceof CliError ? err.code : 'FAILURE',
         hint: inner ?? 'frontera blueprint plan — re-plan against the current draft, then re-apply.',
       })
@@ -1161,9 +1432,10 @@ export const blueprintApply: Command = {
 
     const revision = await client.revision()
     return {
-      data: { applied, revision },
+      data: { applied, revision, actionProblems },
       text: `${renderPlan(plan, { prune })}\n\nApplied ${applied.length} change`
-        + `${applied.length === 1 ? '' : 's'}. Draft is at revision ${revision}.`,
+        + `${applied.length === 1 ? '' : 's'}. Draft is at revision ${revision}.`
+        + (actionWarnings ? `\n${actionWarnings}` : ''),
     }
   },
 }
@@ -1372,7 +1644,7 @@ 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', template: 'string' },
+    flags: { dir: 'string', template: 'string', 'object-type': 'string' },
     offline: true,
     summary: 'Scaffold an artifact file that validates as written',
     examples: [
@@ -1380,6 +1652,8 @@ export const blueprintNew: Command = {
       'frontera blueprint new link-type customerHoldsPolicy',
       'frontera blueprint new shared-field accountCode',
       'frontera blueprint new semantic-type completionRate --template percentage',
+      'frontera blueprint new action assignTicket --object-type Ticket',
+      'frontera blueprint new action logTicket --template create --object-type Ticket',
     ],
   },
   async run(ctx) {
@@ -1403,8 +1677,8 @@ 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 options = scaffoldOptions(ctx, kind, directory)
     const relative = pathFor(kind, apiName)
     if (existsSync(resolve(directory, relative))) {
       throw new CliError(`${relative} already exists.`, {
@@ -1416,7 +1690,7 @@ export const blueprintNew: Command = {
       kind,
       apiName,
       path: relative,
-      document: scaffold(kind, apiName, template === undefined ? {} : { template }),
+      document: scaffold(kind, apiName, options),
     }
     writeTree(directory, [file])
     return {
@@ -1426,6 +1700,32 @@ export const blueprintNew: Command = {
   },
 }
 
+/**
+ * `--template` and `--object-type`, read for the kind they apply to. An Action's
+ * subject type, when the tree holds it, also gives the key input its name.
+ */
+function scaffoldOptions(ctx: CommandContext, kind: ArtifactKind, directory: string): ScaffoldOptions {
+  const objectType = typeof ctx.flags['object-type'] === 'string' ? ctx.flags['object-type'] : undefined
+  if (objectType !== undefined && kind !== 'action') {
+    throw new CliError(`--object-type applies to action, not ${kind}.`, { code: 'USAGE', hint: 'frontera blueprint new action <apiName> --object-type <ObjectType>' })
+  }
+  if (kind !== 'action') {
+    const template = semanticTypeTemplate(ctx.flags.template, kind)
+    return template === undefined ? {} : { template }
+  }
+  const declared = ctx.flags.template
+  if (declared !== undefined && !isActionTemplate(String(declared))) {
+    throw new CliError(`Unknown action template "${String(declared)}".`, { code: 'USAGE', hint: `One of: ${ACTION_TEMPLATES.join(', ')} (edit changes a record; create makes one).` })
+  }
+  const options: ScaffoldOptions = { ...(declared === undefined ? {} : { actionTemplate: String(declared) as ActionTemplate }) }
+  if (objectType) {
+    options.objectType = objectType
+    const type = existsSync(directory) ? readTree(directory).find((f) => f.kind === 'object-type' && f.apiName === objectType) : undefined
+    if (typeof type?.document.primaryKey === 'string') options.primaryKey = type.document.primaryKey
+  }
+  return options
+}
+
 /**
  * `--template`, validated where it is read.
  *