@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/blueprint/metric-rules.ts

@@ -0,0 +1,122 @@
+import type { AuthoredFile } from './model'
+
+/**
+ * What the draft refuses in a metric file, found before anything is written.
+ *
+ * A measure's `filters` is ONE where node, as a query's `where` is: a
+ * condition (`{ property, op, value }`) or a combinator (`{ and: [...] }`,
+ * `{ or: [...] }`, `{ not: {...} }`). A list of conditions reads naturally
+ * in YAML and `plan` used to show it as a clean change, while the service
+ * refused it at apply (`where node must be a JSON object`). The same shape
+ * rules the service checks (`metric-definition.ts`), minus the properties,
+ * which only the draft knows: a relative date window and a location
+ * condition are refused in a metric too.
+ */
+
+const GEO_OPS = new Set(['nearby', 'withinBbox'])
+
+/** Why a where node is not one, or null when its shape is right. */
+export function whereShapeProblem(node: unknown): string | null {
+  if (Array.isArray(node)) return 'it is a list; it must be one where node: a condition, or several combined as { and: [ … ] }'
+  if (!node || typeof node !== 'object') return 'it must be a where node (a mapping): { property, op, value }, or { and: [ … ] }, { or: [ … ] }, { not: … }'
+  const o = node as Record<string, unknown>
+  if (typeof o.property === 'string') {
+    if (o.op === 'dateRange') return 'dateRange presets are not supported in metric filters: a compiled metric is static, so use explicit comparisons'
+    if (typeof o.op === 'string' && GEO_OPS.has(o.op)) return 'location conditions (nearby, withinBbox) are not supported in metric filters'
+    return null
+  }
+  for (const key of ['and', 'or'] as const) {
+    if (key in o) {
+      if (!Array.isArray(o[key])) return `\`${key}\` must be a list of where nodes`
+      for (const child of o[key] as unknown[]) {
+        const why = whereShapeProblem(child)
+        if (why) return why
+      }
+      return null
+    }
+  }
+  if ('not' in o) return whereShapeProblem(o.not)
+  return 'it must be a condition ({ property, op, value }) or and/or/not'
+}
+
+/**
+ * A property's type as the tree declares it, by `Type.property`: what a file
+ * says, `attribute` when it says nothing (`compile.ts` sends that default).
+ * A field carrying a shared field without its own `propertyType` takes the
+ * shared field's, which only the draft knows, so it is left out. So is a date
+ * or timestamp a file leaves unsaid: a new one is created `time`
+ * (`declaredPropertyType`), one already on the draft keeps its own.
+ */
+function declaredPropertyTypes(files: readonly AuthoredFile[]): Map<string, { propertyType: string; valueType: string; file: string }> {
+  const out = new Map<string, { propertyType: string; valueType: string; file: string }>()
+  for (const file of files) {
+    if (file.kind !== 'object-type') continue
+    const properties = (file.document as { properties?: unknown }).properties
+    for (const p of Array.isArray(properties) ? (properties as Array<Record<string, unknown>>) : []) {
+      if (!p || typeof p.apiName !== 'string') continue
+      if (p.propertyType === undefined && p.sharedField !== undefined && p.sharedField !== null) continue
+      // A date or timestamp left unsaid is `time` when it is created, but one already on the draft keeps its own: unknown here.
+      if (p.propertyType === undefined && (p.valueType === 'timestamp' || p.valueType === 'date')) continue
+      out.set(`${file.apiName}.${p.apiName}`, {
+        propertyType: typeof p.propertyType === 'string' ? p.propertyType : 'attribute',
+        valueType: typeof p.valueType === 'string' ? p.valueType : 'string',
+        file: file.path,
+      })
+    }
+  }
+  return out
+}
+
+/**
+ * What the runtime checks of a metric against its type's properties
+ * (`validateMetricDefinitionAgainstType`): the timeseries is a `time`
+ * property, a dimension an `attribute` or `time` one, and a `sum` or `avg`
+ * reads a `measure`. `plan` passed a timeseries on an `attribute` timestamp
+ * and the runtime refused it. Checked only where the tree holds the type.
+ */
+function metricTypeProblems(file: AuthoredFile, types: ReturnType<typeof declaredPropertyTypes>): string[] {
+  const doc = file.document as { objectType?: unknown; definition?: Record<string, unknown> }
+  if (typeof doc.objectType !== 'string') return []
+  const type = doc.objectType
+  const definition = doc.definition ?? {}
+  const out: string[] = []
+  const fix = (property: string, want: string) => {
+    const declared = types.get(`${type}.${property}`)
+    return declared ? ` — give ${property} \`propertyType: ${want}\` in ${declared.file}` : ''
+  }
+  if (typeof definition.timeseries === 'string') {
+    const p = types.get(`${type}.${definition.timeseries}`)
+    if (p && p.propertyType !== 'time') out.push(`${file.path}: timeseries "${definition.timeseries}" must be a time property, but ${type}.${definition.timeseries} is "${p.propertyType}"${fix(definition.timeseries, 'time')}`)
+  }
+  for (const dim of Array.isArray(definition.dimensions) ? definition.dimensions : []) {
+    if (typeof dim !== 'string') continue
+    const p = types.get(`${type}.${dim}`)
+    if (p && p.propertyType !== 'attribute' && p.propertyType !== 'time') out.push(`${file.path}: dimension "${dim}" must be an attribute or time property, but ${type}.${dim} is "${p.propertyType}"`)
+  }
+  for (const [i, measure] of (Array.isArray(definition.measures) ? (definition.measures as Array<Record<string, unknown>>) : []).entries()) {
+    if (!measure || (measure.agg !== 'sum' && measure.agg !== 'avg') || typeof measure.property !== 'string' || measure.expression !== undefined) continue
+    const p = types.get(`${type}.${measure.property}`)
+    const name = typeof measure.label === 'string' ? measure.label : `#${i + 1}`
+    if (p && p.propertyType !== 'measure') out.push(`${file.path}: measure "${name}": agg "${measure.agg}" requires a measure property, but ${type}.${measure.property} is "${p.propertyType}"${fix(measure.property, 'measure')}`)
+  }
+  return out
+}
+
+/** Each refusal in the tree's metric files, as `<file>: measure "<label>": filters …`. */
+export function metricRuleProblems(files: readonly AuthoredFile[]): string[] {
+  const out: string[] = []
+  const types = declaredPropertyTypes(files)
+  for (const file of files) {
+    if (file.kind !== 'metric') continue
+    out.push(...metricTypeProblems(file, types))
+    const definition = (file.document as { definition?: { measures?: unknown } }).definition
+    const measures = Array.isArray(definition?.measures) ? (definition!.measures as Array<Record<string, unknown>>) : []
+    for (const [i, measure] of measures.entries()) {
+      if (!measure || typeof measure !== 'object' || measure.filters === undefined) continue
+      const why = whereShapeProblem(measure.filters)
+      const name = typeof measure.label === 'string' ? measure.label : typeof measure.apiName === 'string' ? measure.apiName : `#${i + 1}`
+      if (why) out.push(`${file.path}: measure "${name}": filters — ${why}`)
+    }
+  }
+  return out
+}

package/src/blueprint/object-sets.ts

@@ -0,0 +1,116 @@
+import { readObjectSetFiles } from '../local/local-object-sets'
+import { isUuid, refName } from '../local/local-sync-refs'
+import { objectSetNames } from '../local/local-sync-remote'
+
+/**
+ * Saved object sets as the CLI shows and addresses them.
+ *
+ * Two list routes answer with sets, in two shapes: the workspace's slice
+ * (`/v1/sync/object-sets`, a workspace key; each row names its object type)
+ * and the organization's (`/v1/blueprint/object-sets`, an organization key;
+ * rows carry the object type's id). Both are read into one row here.
+ *
+ * A set is addressed the way a project file names it: its id, its name
+ * (`Open work orders`), its name as a reference holds it
+ * (`objectSet/open-work-orders`), or, in a project, its file's name
+ * (`blueprint/object-sets/open-work-orders.yaml` → `objectSet/open-work-orders`).
+ */
+
+export interface SavedObjectSet {
+  id: string
+  name: string
+  description: string | null
+  kind: string
+  /** The object type's API name, when the route says it; else its id. */
+  objectType: string
+  /** How a file names it: `objectSet/open-work-orders`. */
+  ref: string
+}
+
+const text = (v: unknown): string | null => (typeof v === 'string' && v ? v : null)
+
+/**
+ * Rows from either list route, unwrapped from `{ data }` when the client left one.
+ *
+ * `files` are a project's object set files (file name → the set's `name:`, from
+ * `projectObjectSetNames`): a set one file saves takes that file's name as its
+ * reference, as `status` names it, rather than a slug of its name (which stops at
+ * 24 characters, so `Critical open work orders` was `critical-open-work-order`).
+ */
+export function normalizeObjectSets(body: unknown, files: ReadonlyMap<string, string> = new Map()): SavedObjectSet[] {
+  const raw = Array.isArray(body) ? body : Array.isArray((body as { data?: unknown } | null)?.data) ? ((body as { data: unknown[] }).data) : []
+  const rows = raw.flatMap((r) => {
+    const o = (r ?? {}) as Record<string, unknown>
+    const id = text(o.id)
+    const name = text(o.name)
+    if (!id || !name) return []
+    return [{
+      id,
+      name,
+      description: text(o.description),
+      kind: text(o.kind) ?? 'dynamic',
+      objectType: text(o.objectType) ?? text(o.objectTypeApiName) ?? text(o.resultObjectTypeApiName) ?? text(o.resultObjectTypeId) ?? '',
+    }]
+  })
+  const refs = objectSetNames(rows.map((r) => ({ ...r, kind: r.kind as 'dynamic' | 'static' })))
+  const fileRefs = new Map<string, string[]>()
+  for (const [file, name] of files) fileRefs.set(name, [...(fileRefs.get(name) ?? []), file])
+  // Only when one file and one set share the name: else the file's name could mean either.
+  const fileOf = (name: string) => {
+    const own = fileRefs.get(name)
+    return own?.length === 1 && rows.filter((r) => r.name === name).length === 1 ? own[0] : undefined
+  }
+  return rows.map((r) => ({ ...r, ref: `objectSet/${fileOf(r.name) ?? refs.get(r.id) ?? refName(r.name)}` }))
+}
+
+/** A project's object set files by the reference their file name gives (`open-work-orders`) → the set's name. */
+export function projectObjectSetNames(root: string | null): Map<string, string> {
+  const out = new Map<string, string>()
+  if (!root) return out
+  for (const f of readObjectSetFiles(root)) out.set(f.ref, typeof f.doc.name === 'string' && f.doc.name ? f.doc.name : f.ref)
+  return out
+}
+
+/**
+ * The set `wanted` names: an id, a name (any case), `objectSet/<ref>` or
+ * `objectSet:<ref>`, or a project file's name. `{ set }` when one matches,
+ * else why not, with the near names.
+ */
+export function findObjectSet(sets: SavedObjectSet[], wanted: string, files: ReadonlyMap<string, string> = new Map()): { set: SavedObjectSet } | { problem: string; ambiguous?: SavedObjectSet[] } {
+  const raw = wanted.trim()
+  if (isUuid(raw)) {
+    const byId = sets.find((s) => s.id.toLowerCase() === raw.toLowerCase())
+    return byId ? { set: byId } : { problem: `no saved object set has the id ${raw}` }
+  }
+  const bare = raw.replace(/^objectSet[/:]/, '')
+  const lower = bare.toLowerCase()
+  const tries: Array<(s: SavedObjectSet) => boolean> = [
+    (s) => s.ref === `objectSet/${bare}`,
+    (s) => s.name.toLowerCase() === lower,
+    (s) => s.ref.toLowerCase() === `objectset/${refName(bare).toLowerCase()}`,
+  ]
+  // A project file's name, as `local dev` saves it: the set carries the file's `name:`.
+  const fileName = files.get(bare)
+  if (fileName) tries.push((s) => s.name === fileName)
+  for (const match of tries) {
+    const found = sets.filter(match)
+    if (found.length === 1) return { set: found[0]! }
+    if (found.length > 1) return { problem: `${found.length} saved object sets match "${raw}"`, ambiguous: found }
+  }
+  return { problem: `no saved object set is named "${raw}"` }
+}
+
+/**
+ * A query document with each `{ type: "reference", objectSetId }` that names
+ * a set in words resolved to the set's id. `resolve` answers an id for a name,
+ * or throws why it can't. The document is copied, never changed in place.
+ */
+export async function resolveObjectSetReferences(doc: unknown, resolve: (name: string) => Promise<string>): Promise<unknown> {
+  if (Array.isArray(doc)) return Promise.all(doc.map((d) => resolveObjectSetReferences(d, resolve)))
+  if (!doc || typeof doc !== 'object') return doc
+  const o = doc as Record<string, unknown>
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(o)) out[k] = await resolveObjectSetReferences(v, resolve)
+  if (o.type === 'reference' && typeof o.objectSetId === 'string' && !isUuid(o.objectSetId)) out.objectSetId = await resolve(o.objectSetId)
+  return out
+}

package/src/blueprint/ontology-edit-plan.ts

@@ -73,7 +73,7 @@ export function ontologyEditCompatibilityFingerprint(
 ): string {
   const canonical = JSON.stringify({
     objectTypeId,
-    usedProperties: [...new Set(usedProperties)].sort(),
+    usedProperties: [...new Set(usedProperties)].sort((a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0)),
   })
   return `sha256:${createHash('sha256').update(canonical).digest('hex')}`
 }
@@ -112,10 +112,18 @@ export function deriveOntologyEditPlan(
   // deployment that wrote a different set would be executing something other
   // than what was published and reviewed.
   const set: Record<string, string> = {}
+  // A constant (`{ kind: literal }`) is written by the service from the binding's pinned
+  // contract, not from a parameter: it stays out of `set` and out of the fingerprint.
+  const constants: string[] = []
   for (const outcome of action.businessOutcomes) {
     for (const change of outcome.expectedChanges ?? []) {
       if (change.kind !== 'property_set') continue
       const value = change.value as { kind?: string; fieldId?: string } | undefined
+      if (value?.kind === 'literal') {
+        const property = propertyApiNameById.get(String(change.propertyId))
+        if (property) constants.push(property)
+        continue
+      }
       if (value?.kind !== 'input' || !value.fieldId) continue
       const property = propertyApiNameById.get(String(change.propertyId))
       const parameter = inputApiNameById.get(value.fieldId)
@@ -124,10 +132,15 @@ export function deriveOntologyEditPlan(
     }
   }
 
+  // The plan must map at least one parameter, so constants alone cannot be deployed.
   if (op !== 'delete' && Object.keys(set).length === 0) {
     throw new PlanDerivationError(
-      `Action "${action.apiName}" sets no properties, so there is nothing to deploy.`,
-      'Open the Action and tick at least one property under "What it changes".',
+      constants.length
+        ? `Action "${action.apiName}" sets only constants (${constants.join(', ')}), and its write path needs at least one property set from an input.`
+        : `Action "${action.apiName}" sets no properties, so there is nothing to deploy.`,
+      constants.length
+        ? 'Set at least one property from an input ({ kind: input, field: <input> }) beside the constants.'
+        : 'Open the Action and tick at least one property under "What it changes".',
     )
   }
 
@@ -146,10 +159,35 @@ export function deriveOntologyEditPlan(
   if (!pkParameter) {
     throw new PlanDerivationError(
       `Action "${action.apiName}" takes no "${pkApiName}" parameter, so an edit has no address.`,
-      `Add a required "${pkApiName}" parameter to the Action, then publish.`,
+      `Add a required "${pkApiName}" input to the Action (valueType: { kind: string, minLength: 1 }): ${op === 'create' ? 'the new record is filed under it' : 'the write finds its record by it'}. Then publish.`,
     )
   }
 
+  if (constants.includes(pkApiName)) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" sets its primary key ${pkApiName} to a constant.`,
+      `Remove that change: the key comes from the required "${pkParameter}" input.`,
+    )
+  }
+  // The key addresses the record (an edit) or files it (a create): it is never also a written value.
+  if (Object.prototype.hasOwnProperty.call(set, pkApiName) && (op !== 'create' || set[pkApiName] === pkParameter)) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" sets its primary key ${pkApiName}, which ${op === 'create' ? 'a create already files the new record under (from its "' + pkParameter + '" parameter)' : 'addresses the record and cannot change'}.`,
+      `Remove the property_set of ${pkApiName} from its outcome; keep the required "${pkParameter}" input.`,
+    )
+  }
+  // One parameter, one role: the deployment refuses a parameter feeding two properties.
+  const byParameter = new Map<string, string[]>()
+  for (const [property, parameter] of Object.entries(set)) byParameter.set(parameter, [...(byParameter.get(parameter) ?? []), property])
+  for (const [parameter, properties] of byParameter) {
+    if (properties.length > 1) {
+      throw new PlanDerivationError(
+        `Action "${action.apiName}" sets ${properties.join(' and ')} from the same input, ${parameter}.`,
+        'Give each property its own input: every mapped parameter carries exactly one role.',
+      )
+    }
+  }
+
   // Only when the Action asked for it. Compare-and-set is the Action's
   // concurrency contract, not a deployment preference.
   const expectedVersionParameter = action.concurrency.strategy === 'expected_version'
@@ -158,7 +196,13 @@ export function deriveOntologyEditPlan(
   if (action.concurrency.strategy === 'expected_version' && !expectedVersionParameter) {
     throw new PlanDerivationError(
       `Action "${action.apiName}" declares expected_version concurrency but takes no "expectedVersion" parameter.`,
-      'Add it to the Action, or change the concurrency strategy.',
+      'Add a required input { apiName: expectedVersion, valueType: { kind: number, integer: true, minimum: 0 } }: the record version the change was decided on (a query row\'s _meta.recordVersion).',
+    )
+  }
+  if (expectedVersionParameter && Object.values(set).includes(expectedVersionParameter)) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" writes a property from expectedVersion, which carries the record version.`,
+      'Give that property its own input: every mapped parameter carries exactly one role.',
     )
   }
 

package/src/blueprint/projection.ts

@@ -80,10 +80,15 @@ function propertyToFile(
   sharedApiNameById: Map<string, string>,
   semanticApiNameById: Map<string, string>,
   siblingApiNameById: Map<string, string>,
+  objectClassification?: unknown,
 ): Record<string, unknown> {
   const body = rest(property, new Set(['id', 'sharedPropertyId', 'semanticTypeId']))
   const location = locationToFile(property, objectApiName, siblingApiNameById)
   if (location) body.calculation = location
+  // A field's own classification is written only where it differs from its object type's: a read
+  // gives every field its effective one, and writing the inherited value would pin it. A location
+  // takes its latitude's and longitude's, and declares none.
+  if (body.sensitivity !== undefined && (body.sensitivity === null || body.sensitivity === objectClassification || location)) delete body.sensitivity
   const semanticType = resolveName(
     property.semanticTypeId,
     semanticApiNameById,
@@ -220,7 +225,7 @@ function objectToFile(
     primaryKey: byId.get(object.primaryKeyPropertyId) ?? object.primaryKeyPropertyId,
     title: byId.get(object.titlePropertyId) ?? object.titlePropertyId,
     properties: object.properties.map((property) =>
-      propertyToFile(property, object.apiName, sharedApiNameById, semanticApiNameById, byId)),
+      propertyToFile(property, object.apiName, sharedApiNameById, semanticApiNameById, byId, (object.governance as { sensitivity?: { classification?: unknown } } | undefined)?.sensitivity?.classification)),
   }
 }
 
@@ -303,6 +308,23 @@ function nameFieldRefs(node: unknown, fields: Map<string, string>, properties: M
   for (const value of Object.values(node)) nameFieldRefs(value, fields, properties)
 }
 
+/**
+ * A postcondition reads the record after the change, and that is the only timing it
+ * may have: the service stores it spelled out (`timing: after`) whether the author
+ * wrote it or not. The file format takes no timing, so the implied one is dropped
+ * (in place, anywhere below `node`): a pulled file stays one an author can write, and
+ * `blueprint plan` compares a file with the live Action as equal.
+ */
+export function withoutImpliedTiming(node: unknown): void {
+  if (Array.isArray(node)) {
+    for (const entry of node) withoutImpliedTiming(entry)
+    return
+  }
+  if (!isRecord(node)) return
+  if (node.kind === 'observation_property' && node.timing === 'after') delete node.timing
+  for (const value of Object.values(node)) withoutImpliedTiming(value)
+}
+
 /**
  * An action as the bundle carries it → the portable file.
  *
@@ -375,6 +397,7 @@ function actionToFile(action: Record<string, unknown>, names: ActionNames): Reco
       if (!isRecord(postcondition)) continue
       delete postcondition.id
       nameFieldRefs(postcondition.assertion, scope, names.property)
+      withoutImpliedTiming(postcondition.assertion)
     }
   }
 

package/src/blueprint/scaffold.ts

@@ -64,6 +64,89 @@ export function isSemanticTypeTemplate(value: string): value is SemanticTypeTemp
 
 export interface ScaffoldOptions {
   template?: SemanticTypeTemplate
+  /** An Action's shape: `edit` (the default) changes a record, `create` makes one. */
+  actionTemplate?: ActionTemplate
+  /** An Action's subject, and the name of its primary key (read from the tree when it has the type). */
+  objectType?: string
+  primaryKey?: string
+}
+
+export const ACTION_TEMPLATES = ['edit', 'create'] as const
+export type ActionTemplate = (typeof ACTION_TEMPLATES)[number]
+
+export function isActionTemplate(value: string): value is ActionTemplate {
+  return (ACTION_TEMPLATES as readonly string[]).includes(value)
+}
+
+/**
+ * A governed Action over the Blueprint's records that deploys as written once
+ * the placeholders are filled: every rule the write path holds it to is
+ * already met (`action-rules.ts`), so the reader starts from a file that
+ * works and changes what it sets.
+ *
+ * Every reference is a NAME. The service resolves them against the draft and mints
+ * the ids the contract owns, so nothing here carries a uuid — which is exactly what
+ * makes the file applicable to a second deployment.
+ */
+function actionScaffold(apiName: string, options: ScaffoldOptions): Record<string, unknown> {
+  const create = options.actionTemplate === 'create'
+  const objectType = options.objectType ?? 'CHANGE_ME'
+  const pk = options.primaryKey ?? 'id'
+  const field = (name: string, displayName: string, description: string, valueType: Record<string, unknown>, extra: Record<string, unknown> = { required: true }) => ({
+    apiName: name, displayName, description, valueType, ...extra, sensitivity: 'internal',
+  })
+  const inputs = [
+    // The key: an edit finds its record by it, a create files the new record under it.
+    field(pk, create ? 'New record ID' : 'Record', create ? 'The new record’s key; the record is filed under it.' : 'The record to change, by its key.', { kind: 'string', minLength: 1 }),
+    // Compare-and-set: the version the change was decided on (a query row's `_meta.recordVersion`).
+    ...(create ? [] : [field('expectedVersion', 'Expected version', 'The record version the change was decided on.', { kind: 'number', integer: true, minimum: 0 })]),
+    field('value', 'CHANGE_ME', 'CHANGE_ME: the value it writes.', { kind: 'string', minLength: 1 }),
+  ]
+  return {
+    apiName,
+    displayName: apiName,
+    description: 'CHANGE_ME',
+    subject: { objectType, mode: create ? 'create' : 'existing' },
+    effect: {
+      kind: create ? 'create' : 'update',
+      // The Blueprint's own records: `active-catalog` is the source system the service
+      // adds to the draft with the first object type (`blueprint-draft-catalog.ts`).
+      // Source systems have no route or file of their own, so this is the one name an
+      // Action that writes Blueprint records can give, here and on every deployment.
+      authoritySourceSystem: 'active-catalog',
+      description: 'CHANGE_ME',
+    },
+    inputs,
+    // `min(1)` on the create route: an action that declares no outcome cannot say
+    // what it did. Each change names its object type; each input feeds one property,
+    // and a create never sets its key (it is filed under the key input).
+    businessOutcomes: [{
+      code: create ? 'created' : 'applied',
+      displayName: create ? 'Created' : 'Applied',
+      description: 'CHANGE_ME',
+      effect: 'confirmed_applied',
+      expectedChanges: [
+        ...(create ? [{ kind: 'object_created', objectType }] : []),
+        { kind: 'property_set', objectType, property: 'CHANGE_ME', value: { kind: 'input', field: 'value' } },
+      ],
+      postconditions: [],
+      output: [],
+    }],
+    // An edit compares the record's version; a create over the Blueprint's records is append_once.
+    concurrency: { strategy: create ? 'append_once' : 'expected_version' },
+    impact: { maxSubjects: 1 },
+    submissionCriteria: [],
+    governance: {
+      // Shaped, not `CHANGE_ME`: this one is validated by
+      // `/^[a-z][a-z0-9_-]{0,63}:[a-z][a-z0-9_-]{0,63}$/`, so a bare placeholder is
+      // the one field in this file that cannot apply as written — and it fails
+      // server-side, after the plan was confirmed.
+      invokeCapability: 'changeme:invoke',
+      approval: { mode: 'none' },
+      reason: 'optional',
+      sensitivity: 'internal',
+    },
+  }
 }
 
 export function scaffold(
@@ -141,48 +224,7 @@ export function scaffold(
   }
 
   if (kind === 'action') {
-    // Every reference is a NAME. The service resolves them against the draft and mints
-    // the ids the contract owns, so nothing here carries a uuid — which is exactly
-    // what makes the file applicable to a second deployment.
-    return {
-      apiName,
-      displayName: apiName,
-      description: 'CHANGE_ME',
-      subject: { objectType: 'CHANGE_ME', mode: 'existing' },
-      effect: {
-        kind: 'update',
-        // Named, but note it cannot be authored from this tree: source systems have no
-        // route, and one is synthesised per organization. On a second deployment this
-        // name may resolve to nothing.
-        authoritySourceSystem: 'CHANGE_ME',
-        description: 'CHANGE_ME',
-      },
-      inputs: [],
-      // `min(1)` on the create route: an action that declares no outcome cannot say
-      // what it did, so a scaffold without one would not apply as written.
-      businessOutcomes: [{
-        code: 'applied',
-        displayName: 'Applied',
-        description: 'CHANGE_ME',
-        effect: 'confirmed_applied',
-        expectedChanges: [],
-        postconditions: [],
-        output: [],
-      }],
-      concurrency: { strategy: 'expected_version' },
-      impact: { maxSubjects: 1 },
-      submissionCriteria: [],
-      governance: {
-        // Shaped, not `CHANGE_ME`: this one is validated by
-        // `/^[a-z][a-z0-9_-]{0,63}:[a-z][a-z0-9_-]{0,63}$/`, so a bare placeholder is
-        // the one field in this file that cannot apply as written — and it fails
-        // server-side, after the plan was confirmed.
-        invokeCapability: 'changeme:invoke',
-        approval: { mode: 'none' },
-        reason: 'optional',
-        sensitivity: 'internal',
-      },
-    }
+    return actionScaffold(apiName, options)
   }
 
   if (kind === 'metric') {

package/src/commands/action/available.ts

@@ -48,7 +48,7 @@ export const actionAvailable: Command = {
     authLane: 'session',
     scope: 'workspace' as const,
     args: [],
-    flags: {},
+    flags: { as: 'string' },
     summary: 'List the Actions you can submit in this workspace, and their inputs',
     examples: ['frontera action available', 'frontera action available --json'],
   },

package/src/commands/action/criteria-refusal.ts

@@ -0,0 +1,84 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { parse } from 'yaml'
+
+import { CliError } from '../../errors'
+import { findSolutionRoot } from '../../local/local-project'
+
+/** One criterion a refusal names: its code, and its message when known. */
+export interface FailedCriterion {
+  code: string
+  message?: string
+}
+
+/**
+ * The criteria an `ACTION_CRITERIA_FAILED` refusal names (`details.criteria`,
+ * at the top or one level under `details`), with each one's message when the
+ * refusal carries it.
+ */
+export function failedCriteria(details: unknown): FailedCriterion[] {
+  const body = (details && typeof details === 'object' ? details : null) as { criteria?: unknown; details?: { criteria?: unknown } } | null
+  const raw = Array.isArray(body?.criteria) ? body.criteria : Array.isArray(body?.details?.criteria) ? body.details.criteria : []
+  return raw.flatMap((c) => {
+    const entry = (c && typeof c === 'object' ? c : null) as { code?: unknown; criterionId?: unknown; message?: unknown } | null
+    const code = typeof entry?.code === 'string' ? entry.code : typeof entry?.criterionId === 'string' ? entry.criterionId : null
+    if (!code) return []
+    return [{ code, ...(typeof entry?.message === 'string' && entry.message.trim() ? { message: entry.message.trim() } : {}) }]
+  })
+}
+
+/**
+ * The messages the project's own file for an Action gives its submission
+ * criteria, by code: `blueprint/actions/<file>.yaml` whose `apiName` (or file
+ * name) is the Action's. Empty outside a project, or when no file matches.
+ */
+export function projectCriteriaMessages(cwd: string, apiName: string): Record<string, string> {
+  const dir = join(findSolutionRoot(cwd), 'blueprint', 'actions')
+  if (!existsSync(dir)) return {}
+  for (const name of readdirSync(dir).filter((f) => /\.(ya?ml|json)$/.test(f))) {
+    let doc: { apiName?: unknown; submissionCriteria?: unknown } | null
+    try {
+      doc = parse(readFileSync(join(dir, name), 'utf8')) as typeof doc
+    } catch {
+      continue
+    }
+    const matches = doc?.apiName === apiName || (doc?.apiName === undefined && name.replace(/\.(ya?ml|json)$/, '') === apiName)
+    if (!matches || !Array.isArray(doc?.submissionCriteria)) continue
+    return Object.fromEntries(
+      doc.submissionCriteria.flatMap((c: { code?: unknown; message?: unknown }) => (typeof c?.code === 'string' && typeof c.message === 'string' ? [[c.code, c.message.trim()]] : [])),
+    )
+  }
+  return {}
+}
+
+/** The criterion every create carries: the record it would create must not exist yet. */
+export const RECORD_ALREADY_EXISTS = 'record_already_exists'
+
+/**
+ * A submission-criteria refusal said with each criterion's message, not only
+ * its code (`still_open: Only a request nobody has started on can be
+ * withdrawn`). The message comes from the refusal when the service sends it
+ * (it wins over the project's file, which may be ahead of what is deployed),
+ * else from the project's file for the Action. Null for any other refusal.
+ */
+export function criteriaRefusal(err: unknown, apiName: string, cwd: string): CliError | null {
+  if (!(err instanceof CliError) || err.code !== 'ACTION_CRITERIA_FAILED') return null
+  const failed = failedCriteria(err.details)
+  if (!failed.length) return null
+  const known = failed.some((c) => !c.message) ? projectCriteriaMessages(cwd, apiName) : {}
+  const said = failed.map((c) => {
+    const message = c.message ?? known[c.code]
+    return message ? `${c.code}: ${message}` : c.code
+  })
+  // A create's own criterion (the platform's, with no project file behind it): the record is there already.
+  const exists = failed.length === 1 && failed[0]!.code === RECORD_ALREADY_EXISTS
+  return new CliError(`${apiName} refused this request: its submission criteria were not met (${said.join('; ')})`, {
+    code: err.code,
+    hint: exists
+      ? 'the record this request would create exists already, so the same request is refused again: give it another identity, or change the existing record with an Action that edits it (`frontera blueprint instance` shows it)'
+      : 'the record or the input does not meet the criteria, so the same request is refused again: change the input, or act on a record that meets them (`frontera blueprint instance` shows its current values)',
+    details: { reason: 'ACTION_CRITERIA_FAILED', criteria: failed.map((c) => ({ code: c.code, ...(c.message ?? known[c.code] ? { message: c.message ?? known[c.code] } : {}) })) },
+    cause: err,
+  })
+}

package/src/commands/action/decide.ts

@@ -33,11 +33,14 @@ function decision(verb: 'approve' | 'reject'): Command {
       // `--stage` names the approval-chain step being decided. Required for a
       // request approved in steps; a decision for a step that is no longer
       // the one waiting is refused, not recorded.
-      flags: { reason: 'string', stage: 'string' },
+      flags: { reason: 'string', stage: 'string', as: 'string' },
       summary: verb === 'approve'
         ? 'Approve an Action request waiting on approval'
         : 'Reject an Action request waiting on approval',
-      examples: [`frontera action ${verb} <requestId> --reason "Checked against the ticket"`],
+      details: [
+        'On the local runtime, `--as <persona>` decides as a local persona: `local dev` seeds one per approval step in blueprint/actions/ (`--as dispatch_lead`), plus `submitter`. Refused anywhere else.',
+      ],
+      examples: [`frontera action ${verb} <requestId> --reason "Checked against the ticket"`, `frontera action ${verb} <requestId> --stage lead --reason "Checked" --as lead`],
     },
 
     async run(ctx: CommandContext) {