@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/blueprint/action-rules.ts

@@ -0,0 +1,516 @@
+import { actionSemanticConflicts, semanticFactsOf } from './action-semantic-fit'
+import type { AuthoredFile } from './model'
+
+/**
+ * The rules a governed Action file must follow that its shape alone does not
+ * show, checked against the tree before anything is written.
+ *
+ * Each rule is one the platform enforces, said here with the file's path and
+ * what to write instead, so an author learns it from `blueprint plan` rather
+ * than from a refusal at apply or, worse, at deploy:
+ *
+ * - `refused`: the Action draft route refuses the file (the service's Action
+ *   contract: `action-definition-schema.ts`, `action-reference-resolution.ts`,
+ *   and `action-semantic-fit.ts`: a value the set property's semantic type
+ *   refuses, unless the Action is still as the workspace gave it: then it is
+ *   `inherited`, a warning).
+ *   `blueprint apply` stops before its first write, so a run never lands half.
+ * - `undeployable`: the file applies, but the write path the local runtime
+ *   derives for it (`ontology-edit-plan.ts`) or the deployment's checks
+ *   (`action-binding-service.ts`, `mutation-plan-schema.ts`) refuse it. Said as
+ *   a warning: the Blueprint is still usable, only that Action does not run.
+ *
+ * Only what those validators check is checked here; anything else is left to
+ * them, so this is never stricter than the platform.
+ */
+
+export interface ActionRuleProblems {
+  refused: string[]
+  undeployable: string[]
+  /** The Actions with a `refused` problem, by apiName. */
+  refusedActions: string[]
+  /**
+   * A semantic-type conflict in an Action still as the workspace gave it
+   * (`inheritedFromPull`): not a refusal. It is applied as the workspace runs
+   * it, and said as a warning, with whose fix it is.
+   */
+  inherited?: string[]
+  /** The Actions with an `inherited` line, by apiName: written to the local runtime as inherited. */
+  inheritedActions?: string[]
+}
+
+/** Is this Action's conflict, resting on these files, the workspace's? (`inheritedFromPull`) */
+export type InheritedConflict = (action: string, refs: readonly string[]) => boolean
+
+/** What starts every inherited conflict's line, so a reader of the apply's output can tell it from an adaptation. */
+export const INHERITED_FROM_PULL = 'inherited from the workspace (unchanged since the pull)'
+
+/** An inherited conflict's line: what it is, that it runs, and whose fix it is. */
+export function inheritedConflictLine(message: string): string {
+  return `${INHERITED_FROM_PULL}: ${message} It is applied as the workspace runs it, and a request with such a value is refused when it is submitted; the Action's owner fixes its contract in the workspace.`
+}
+
+type Doc = Record<string, unknown>
+
+const isRecord = (v: unknown): v is Doc => !!v && typeof v === 'object' && !Array.isArray(v)
+const list = (v: unknown): Doc[] => (Array.isArray(v) ? v.filter(isRecord) : [])
+
+/** An input's or output's apiName (`apiNameSchema`). */
+export const ACTION_MEMBER_NAME = /^[a-z][A-Za-z0-9]{0,99}$/
+/** An outcome's, criterion's or postcondition's code (`stableCodeSchema`). */
+export const ACTION_STABLE_CODE = /^[a-z][a-z0-9_]{0,99}$/
+
+const VALUE_KINDS = new Set(['string', 'number', 'boolean', 'date', 'timestamp', 'json', 'object_reference', 'geopoint'])
+const VALUE_KEYS: Record<string, string[]> = {
+  string: ['kind', 'minLength', 'maxLength', 'pattern', 'enum'],
+  number: ['kind', 'integer', 'minimum', 'maximum'],
+  object_reference: ['kind', 'objectType', 'objectTypeId'],
+}
+const EDITS = new Set(['create', 'update', 'delete'])
+
+const isNonNegativeInteger = (v: unknown) => typeof v === 'number' && Number.isInteger(v) && v >= 0
+
+const PATTERN_MAX_LENGTH = 256
+const PATTERN_MAX_REPEAT = 64
+
+/**
+ * Why a string pattern is outside the subset the platform accepts, or null:
+ * the service's `isSafeBlueprintActionPattern`, said as a reason. It must match
+ * the whole value (^…$), use no groups or alternation, and have at most one
+ * variable-width repetition (`*`, `+`, `?`, `{m,n}`) of at most 64.
+ */
+export function patternProblem(pattern: string): string | null {
+  if (pattern.length < 2 || pattern.length > PATTERN_MAX_LENGTH) return `must be 2 to ${PATTERN_MAX_LENGTH} characters`
+  if (!pattern.startsWith('^') || !pattern.endsWith('$')) return 'must match the whole value: start it with ^ and end it with $'
+  if (pattern !== pattern.normalize('NFC') || /[\u0000-\u001f\u007f]/.test(pattern)) return 'must be plain NFC text with no control characters'
+  try {
+    new RegExp(pattern)
+  } catch {
+    return 'is not a valid regular expression'
+  }
+  const body = pattern.slice(1, -1)
+  let i = 0
+  let width = 0
+  let variable = 0
+  while (i < body.length) {
+    const c = body[i]!
+    if (c === '\\') {
+      const escaped = body[i + 1]
+      if (!escaped || !/[dDwWsS^$\\.*+?()[\]{}|\-]/.test(escaped)) return `uses an escape (\\${escaped ?? ''}) outside the accepted set: \\d \\w \\s and their capitals, or an escaped symbol`
+      i += 2
+    } else if (c === '[') {
+      let j = i + 1
+      if (body[j] === '^') j += 1
+      const first = j
+      let closed = false
+      while (j < body.length) {
+        if (body[j] === '\\') {
+          if (j + 1 >= body.length) return 'ends inside a character class'
+          j += 2
+          continue
+        }
+        if (body[j] === ']') {
+          closed = true
+          break
+        }
+        j += 1
+      }
+      if (!closed || j === first) return 'has an unclosed or empty character class'
+      i = j + 1
+    } else {
+      if (c === '(' || c === ')' || c === '|') return 'cannot use groups or alternation ( ( ) | ); write one character class per position'
+      if (/[*+?{}^$\]]/.test(c)) return `has a stray "${c}": a repetition follows a character or class, and ^ $ only open and close it`
+      i += 1
+    }
+    let repeat = 1
+    if (body[i] === '{') {
+      const close = body.indexOf('}', i + 1)
+      const q = close < 0 ? null : /^(\d+)(?:,(\d*))?$/.exec(body.slice(i + 1, close))
+      if (!q) return 'has a malformed {m,n} repetition'
+      const min = Number(q[1])
+      const ranged = q[2] !== undefined
+      const max = ranged && q[2] !== '' ? Number(q[2]) : min
+      if (min > max || max > PATTERN_MAX_REPEAT) return `repeats more than ${PATTERN_MAX_REPEAT} times, or {m,n} has m above n`
+      if (ranged) variable += 1
+      repeat = ranged && q[2] === '' ? min : max
+      i = close + 1
+    } else if (body[i] === '*' || body[i] === '+' || body[i] === '?') {
+      variable += 1
+      i += 1
+    }
+    if (variable > 1) return 'has more than one variable-width repetition (* + ? {m,n}); keep one, and fix the other widths ({4})'
+    width += repeat
+    if (width > PATTERN_MAX_LENGTH) return `can match more than ${PATTERN_MAX_LENGTH} characters`
+  }
+  return null
+}
+
+/** `BLUEPRINT_ACTION_VALUE_MAX_BYTES`: the most an Action value may carry. */
+const VALUE_MAX_BYTES = 65_536
+
+function isIsoDate(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false
+  const date = new Date(`${value}T00:00:00.000Z`)
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value
+}
+
+function isIsoTimestamp(value: string): boolean {
+  const match = /^(\d{4}-\d{2}-\d{2})T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,3})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.exec(value)
+  if (match === null || !isIsoDate(match[1]!)) return false
+  const time = Date.parse(value)
+  return !Number.isNaN(time) && /^\d{4}-/.test(new Date(time).toISOString())
+}
+
+const bytes = (value: string) => new TextEncoder().encode(value).length
+const show = (value: unknown) => JSON.stringify(value)
+
+/** The note an `object_reference` field with a default gets: a portable file names no record's UUID. */
+export const OBJECT_REFERENCE_DEFAULT_PROBLEM = 'takes no portable default (only a record\'s UUID fits); leave it off, or make it required'
+
+/**
+ * Why a field's default does not fit its value type, or null: the service's
+ * `defaultMatchesField`, said as a reason. A default is a JSON scalar; `null`
+ * fits only a json field. An `object_reference` takes only a record's UUID,
+ * which differs per runtime, so a portable file carries none.
+ */
+export function defaultProblem(value: unknown, vt: Doc): string | null {
+  const kind = vt.kind
+  if (kind === 'object_reference') return OBJECT_REFERENCE_DEFAULT_PROBLEM
+  if (kind === 'geopoint') return 'takes no default: a point is { lat, lon }, and a default is a single value; leave it off'
+  if (value !== null && !['boolean', 'number', 'string'].includes(typeof value)) return `must be a single value (text, a number or true/false), not ${Array.isArray(value) ? 'a list' : 'an object'}`
+  if (value === null && kind !== 'json') return `is null, which only a json field takes; leave the default off for "no value"`
+  if (typeof value === 'number' && (!Number.isFinite(value) || Object.is(value, -0))) return 'must be a finite number other than -0'
+  switch (kind) {
+    case 'string': {
+      if (typeof value !== 'string') return `must be text for a string field (it is ${show(value)})`
+      if (value !== value.normalize('NFC')) return 'must be NFC-normalized text'
+      if (bytes(value) > VALUE_MAX_BYTES) return `is longer than ${VALUE_MAX_BYTES} bytes`
+      if (isNonNegativeInteger(vt.minLength) && value.length < (vt.minLength as number)) return `${show(value)} is shorter than minLength ${String(vt.minLength)}`
+      if (isNonNegativeInteger(vt.maxLength) && value.length > (vt.maxLength as number)) return `${show(value)} is longer than maxLength ${String(vt.maxLength)}`
+      if (Array.isArray(vt.enum) && !vt.enum.includes(value)) return `${show(value)} is not one of its enum values (${vt.enum.map(show).join(', ')})`
+      if (typeof vt.pattern === 'string' && patternProblem(vt.pattern) === null) {
+        const match = new RegExp(vt.pattern).exec(value)
+        if (!match || match.index !== 0 || match[0].length !== value.length) return `${show(value)} does not match its pattern ${vt.pattern}`
+      }
+      return null
+    }
+    case 'number':
+      if (typeof value !== 'number') return `must be a number for a number field (it is ${show(value)})`
+      if (vt.integer === true && !Number.isInteger(value)) return `${value} is not a whole number, and the field is integer: true`
+      if (typeof vt.minimum === 'number' && value < vt.minimum) return `${value} is below minimum ${vt.minimum}`
+      if (typeof vt.maximum === 'number' && value > vt.maximum) return `${value} is above maximum ${vt.maximum}`
+      return null
+    case 'boolean':
+      return typeof value === 'boolean' ? null : `must be true or false for a boolean field (it is ${show(value)})`
+    case 'date':
+      return typeof value === 'string' && isIsoDate(value) ? null : `must be a date, YYYY-MM-DD (it is ${show(value)})`
+    case 'timestamp':
+      return typeof value === 'string' && isIsoTimestamp(value) ? null : `must be an ISO 8601 time with a zone, like 2026-10-18T09:00:00Z (it is ${show(value)})`
+    case 'json':
+      return bytes(JSON.stringify(value)) > VALUE_MAX_BYTES ? `is longer than ${VALUE_MAX_BYTES} bytes` : null
+    default:
+      return null
+  }
+}
+
+function fieldProblems(fields: Doc[], at: string, out: string[]): void {
+  fields.forEach((field, i) => {
+    const where = `${at}[${i}]`
+    const name = field.apiName
+    if (typeof name === 'string' && !ACTION_MEMBER_NAME.test(name)) out.push(`${where}.apiName "${name}" must be camelCase: a lowercase letter, then letters and digits`)
+    if (field.required === true && Object.prototype.hasOwnProperty.call(field, 'default')) {
+      out.push(`${where} is required and has a default; a required field cannot carry one — drop the default, or make it required: false`)
+    }
+    const vt = field.valueType
+    if (!isRecord(vt)) return
+    const kind = typeof vt.kind === 'string' ? vt.kind : ''
+    if (!VALUE_KINDS.has(kind)) return
+    const allowed = VALUE_KEYS[kind] ?? ['kind']
+    for (const key of Object.keys(vt)) {
+      if (!allowed.includes(key)) out.push(`${where}.valueType.${key} is not part of a ${kind} value type (it takes ${allowed.filter((k) => k !== 'kind' && k !== 'objectTypeId').join(', ') || 'only kind'})`)
+    }
+    if (kind === 'number') {
+      if (typeof vt.integer !== 'boolean') out.push(`${where}.valueType.integer is required for a number: true for a whole number, false otherwise`)
+      for (const bound of ['minimum', 'maximum'] as const) {
+        if (vt[bound] === undefined) continue
+        if (typeof vt[bound] === 'string') out.push(`${where}.valueType.${bound} must be a number (${bound}: ${Number(vt[bound]) || 0}), not the text "${String(vt[bound])}" — decimal strings are a semantic type's spelling, not an Action's`)
+        else if (typeof vt[bound] !== 'number') out.push(`${where}.valueType.${bound} must be a number`)
+      }
+    }
+    if (kind === 'string') {
+      for (const bound of ['minLength', 'maxLength'] as const) {
+        if (vt[bound] !== undefined && !isNonNegativeInteger(vt[bound])) out.push(`${where}.valueType.${bound} must be a whole number, 0 or more`)
+      }
+      if (typeof vt.pattern === 'string') {
+        const why = patternProblem(vt.pattern)
+        if (why) out.push(`${where}.valueType.pattern ${why}`)
+      }
+      if (Array.isArray(vt.enum) && new Set(vt.enum).size !== vt.enum.length) out.push(`${where}.valueType.enum lists a value twice; each value once`)
+    }
+    if (kind === 'object_reference' && typeof vt.objectType !== 'string' && typeof vt.objectTypeId !== 'string') {
+      out.push(`${where}.valueType needs objectType: the object type it points at, by apiName`)
+    }
+    // A required field's default is already said above; this is what an optional one's must fit.
+    if (field.required !== true && Object.prototype.hasOwnProperty.call(field, 'default')) {
+      const why = defaultProblem(field.default, vt)
+      if (why) out.push(`${where}.default ${why}`)
+    }
+  })
+}
+
+function codeProblems(items: Doc[], at: string, what: string, out: string[]): void {
+  items.forEach((item, i) => {
+    if (typeof item.code === 'string' && !ACTION_STABLE_CODE.test(item.code)) {
+      out.push(`${at}[${i}].code "${item.code}" must be lowercase snake_case (${what}): a lowercase letter, then lowercase letters, digits or _`)
+    }
+  })
+}
+
+interface ObjectTypeFacts {
+  primaryKey?: string
+  /** Each property's value type, by apiName. */
+  valueTypes?: ReadonlyMap<string, string>
+  /** `backing.editable`: what a governed Action may write; null when the file declares none. */
+  editable?: ReadonlySet<string> | null
+}
+
+/** The input kinds that may set a property of each base type. */
+const FITS: Record<string, string[]> = {
+  string: ['string', 'object_reference'],
+  number: ['number'],
+  date: ['date'],
+  timestamp: ['timestamp'],
+  boolean: ['boolean'],
+  geopoint: ['geopoint'],
+}
+
+/** Every rule problem in the tree's Action files, by file. `inheritedConflict` says which semantic-type conflicts are the workspace's. */
+export function actionRuleProblems(files: AuthoredFile[], inheritedConflict?: InheritedConflict): ActionRuleProblems {
+  const types = new Map<string, ObjectTypeFacts>()
+  for (const f of files) {
+    if (f.kind !== 'object-type') continue
+    const properties = list(f.document.properties)
+    const backing = isRecord(f.document.backing) ? f.document.backing : {}
+    types.set(f.apiName, {
+      primaryKey: typeof f.document.primaryKey === 'string' ? f.document.primaryKey : undefined,
+      valueTypes: new Map(properties.flatMap((p) => (typeof p.apiName === 'string' && typeof p.valueType === 'string' ? [[p.apiName, p.valueType] as const] : []))),
+      editable: Array.isArray(backing.editable) ? new Set(backing.editable.map(String)) : null,
+    })
+  }
+  const refused: string[] = []
+  const undeployable: string[] = []
+  const refusedActions: string[] = []
+  const inherited: string[] = []
+  const inheritedActions: string[] = []
+  // The semantic types of the properties an Action sets (the draft route's `addedSemanticConflicts`):
+  // refused when the person made the conflict, said as a warning when the workspace's Action has it.
+  const facts = semanticFactsOf(files)
+  for (const file of files) {
+    if (file.kind !== 'action') continue
+    const r: string[] = []
+    const u: string[] = []
+    const i: string[] = []
+    checkAction(file.document, types, r, u)
+    for (const c of actionSemanticConflicts(file.document, facts)) {
+      if (inheritedConflict?.(file.apiName, c.refs)) i.push(`${c.path}: ${inheritedConflictLine(c.message)}`)
+      else r.push(`${c.path}: ${c.message}`)
+    }
+    if (r.length) refusedActions.push(file.apiName)
+    else if (i.length) inheritedActions.push(file.apiName)
+    refused.push(...r.map((p) => `${file.path}: ${p}`))
+    undeployable.push(...u.map((p) => `${file.path}: ${p}`))
+    inherited.push(...i.map((p) => `${file.path}: ${p}`))
+  }
+  return { refused, undeployable, refusedActions, ...(inherited.length ? { inherited, inheritedActions } : {}) }
+}
+
+/** One Action document: what the draft route refuses (`refused`) and what will not deploy (`undeployable`). */
+export function checkAction(doc: Doc, types: ReadonlyMap<string, ObjectTypeFacts>, refused: string[], undeployable: string[]): void {
+  const subject = isRecord(doc.subject) ? doc.subject : {}
+  const effect = isRecord(doc.effect) ? doc.effect : {}
+  const concurrency = isRecord(doc.concurrency) ? doc.concurrency : {}
+  const mode = subject.mode
+  const effectKind = typeof effect.kind === 'string' ? effect.kind : ''
+  const strategy = concurrency.strategy
+  const inputs = list(doc.inputs)
+  const outcomes = list(doc.businessOutcomes)
+
+  fieldProblems(inputs, 'inputs', refused)
+  outcomes.forEach((o, i) => fieldProblems(list(o.output), `businessOutcomes[${i}].output`, refused))
+  codeProblems(outcomes, 'businessOutcomes', 'an outcome code', refused)
+  codeProblems(list(doc.submissionCriteria), 'submissionCriteria', 'a criterion code', refused)
+  outcomes.forEach((o, i) => codeProblems(list(o.postconditions), `businessOutcomes[${i}].postconditions`, 'a postcondition code', refused))
+
+  // A criterion, an approval condition or a postcondition reads only inputs that always have a value.
+  const optional = new Set(inputs.filter((f) => typeof f.apiName === 'string' && f.required !== true && !Object.prototype.hasOwnProperty.call(f, 'default')).map((f) => f.apiName as string))
+  if (optional.size) {
+    const reads = (where: string, node: unknown) => {
+      for (const field of new Set(inputReads(node))) {
+        if (optional.has(field)) refused.push(`${where} reads input ${field}, which is optional with no default: make it required: true, or give it a default`)
+      }
+    }
+    list(doc.submissionCriteria).forEach((c, i) => reads(`submissionCriteria[${i}]`, c.assertion))
+    const approval = isRecord(doc.governance) && isRecord(doc.governance.approval) ? doc.governance.approval : null
+    list(approval?.stages).forEach((s, i) => reads(`governance.approval.stages[${i}].when`, s.when))
+    outcomes.forEach((o, i) => list(o.postconditions).forEach((pc, j) => reads(`businessOutcomes[${i}].postconditions[${j}]`, pc.assertion)))
+  }
+
+  if (mode === 'existing') {
+    if (effectKind === 'create') refused.push('subject.mode is existing but effect.kind is create: an Action on an existing record updates, deletes, transitions or runs a command; use subject.mode: create to create one')
+    if (strategy !== undefined && strategy !== 'expected_version') refused.push(`concurrency.strategy must be expected_version for an existing subject (it is ${String(strategy)})`)
+  } else if (mode === 'create') {
+    if (effectKind && effectKind !== 'create') refused.push(`subject.mode is create, so effect.kind must be create (it is ${effectKind})`)
+    if (strategy !== undefined && strategy !== 'create_if_absent' && strategy !== 'append_once') refused.push(`concurrency.strategy must be append_once for a create (it is ${String(strategy)})`)
+  }
+  // One open request per record: only on an existing record, and only that value.
+  if (concurrency.openRequests !== undefined) {
+    if (concurrency.openRequests !== 'one_per_subject') refused.push(`concurrency.openRequests must be one_per_subject (it is ${JSON.stringify(concurrency.openRequests)})`)
+    else if (mode !== 'existing') refused.push('concurrency.openRequests: one_per_subject keeps one open request per existing record, so it takes subject.mode: existing')
+  }
+
+  // Every change names the object type it is on; the property, transition and input by name.
+  const sets: Array<{ property: string; value: Doc; where: string; outcome: number }> = []
+  outcomes.forEach((o, i) => {
+    const changes = list(o.expectedChanges)
+    if (o.effect === 'confirmed_not_applied' && changes.length) refused.push(`businessOutcomes[${i}] is confirmed_not_applied, which declares no expected changes: move them to a confirmed_applied outcome`)
+    changes.forEach((c, j) => {
+      const where = `businessOutcomes[${i}].expectedChanges[${j}]`
+      const named = typeof c.objectType === 'string' || typeof c.objectTypeId === 'string'
+      if (!named && ['property_set', 'object_created', 'object_deleted', 'lifecycle_transition'].includes(String(c.kind))) {
+        const subjectType = typeof subject.objectType === 'string' ? subject.objectType : '<ObjectType>'
+        refused.push(`${where} (${String(c.kind)}) needs objectType: the object type it changes, by apiName (objectType: ${subjectType})`)
+      }
+      if (c.kind === 'property_set') {
+        if (typeof c.property !== 'string' && typeof c.propertyId !== 'string') refused.push(`${where} needs property: the property it sets, by apiName`)
+        const value = isRecord(c.value) ? c.value : null
+        if (!value) refused.push(`${where} needs value: { kind: input, field: <input apiName> }, { kind: output, field: … } or { kind: literal, value: … }`)
+        else {
+          // An optional input with no default may set a property: absent, it leaves the property unset (a create)
+          // or unchanged (an edit). Only criteria, approval conditions and postconditions need a value (above).
+          if (typeof c.property === 'string') sets.push({ property: c.property, value, where, outcome: i })
+        }
+      }
+    })
+  })
+
+  // The write path the local runtime derives (`deriveOntologyEditPlan`) and the deployment's
+  // checks (`action-binding-service.ts`, `mutation-plan-schema.ts`).
+  if (!EDITS.has(effectKind)) return
+  const typeName = typeof subject.objectType === 'string' ? subject.objectType : undefined
+  const subjectType = typeName ? types.get(typeName) : undefined
+  const pk = subjectType?.primaryKey
+  const byName = new Map(inputs.flatMap((f) => (typeof f.apiName === 'string' ? [[f.apiName, f] as const] : [])))
+  const kindOf = (f: Doc | undefined) => (f && isRecord(f.valueType) && typeof f.valueType.kind === 'string' ? f.valueType.kind : undefined)
+
+  // The key: an edit or delete finds its record by it; a create files the new record under it.
+  const key = pk ? byName.get(pk) : undefined
+  if (pk && !key) {
+    undeployable.push(
+      effectKind === 'create'
+        ? `a create files the new record under its primary key, so it takes a required "${pk}" input (valueType: { kind: string, minLength: 1 }); add one`
+        : `${effectKind === 'delete' ? 'a delete' : 'an edit'} finds its record by the primary key, so it takes a required "${pk}" input (valueType: { kind: string, minLength: 1 }); add one`,
+    )
+  } else if (key && key.required !== true) undeployable.push(`inputs: "${pk}" is the record’s key, so it must be required: true`)
+
+  if (strategy === 'expected_version') {
+    // Deploy refuses only an Action with no "expectedVersion" input to map (the plan has nothing to
+    // compare and set on). Its value type is not a deploy rule: the version is checked as a whole
+    // number from 0 when the Action is submitted, and the platform itself writes `{ kind: number }`
+    // with `integer: false` and no minimum on Actions that deploy.
+    if (!byName.get('expectedVersion')) undeployable.push('concurrency expected_version needs an "expectedVersion" input: { apiName: expectedVersion, valueType: { kind: number, integer: true, minimum: 0 }, required: true } — the record version the change was decided on (a query row’s _meta.recordVersion)')
+  }
+
+  const changes = outcomes.flatMap((o) => list(o.expectedChanges))
+  if (effectKind === 'create') {
+    if (strategy === 'create_if_absent') undeployable.push('a create over the Blueprint’s records takes its identity from its primary key input, so concurrency.strategy must be append_once (create_if_absent has the platform mint an identity the record is never filed under)')
+    if (!changes.some((c) => c.kind === 'object_created')) undeployable.push(`a create declares the record it makes: add { kind: object_created, objectType: ${typeName ?? '<ObjectType>'} } to its outcome`)
+  }
+  if (effectKind === 'delete') {
+    if (!changes.some((c) => c.kind === 'object_deleted')) undeployable.push(`a delete declares the record it removes: add { kind: object_deleted, objectType: ${typeName ?? '<ObjectType>'} } to its outcome`)
+    for (const st of sets) undeployable.push(`${st.where} sets ${st.property}, but a delete removes the whole record and sets nothing; remove this change`)
+    return
+  }
+
+  const feeds = new Map<string, string[]>()
+  const byLiteral = new Set(sets.filter((x) => x.value.kind === 'literal').map((x) => x.property))
+  let fromInput = 0
+  for (const st of sets) {
+    if (subjectType?.editable && !subjectType.editable.has(st.property)) {
+      undeployable.push(`${st.where} sets ${st.property}, which ${typeName}’s backing.editable doesn’t list; add it there (blueprint/object-types/${typeName}.yaml)`)
+    } else if (subjectType && subjectType.editable === null) {
+      undeployable.push(`${st.where} sets ${st.property}, but ${typeName} declares no backing.editable; list the properties its Actions write there`)
+    }
+    if (st.value.kind === 'output') {
+      undeployable.push(`${st.where} sets ${st.property} from an output; a write sets each value from an input or a constant`)
+      continue
+    }
+    if (pk && st.property === pk) {
+      if (st.value.kind === 'literal') undeployable.push(`${st.where} sets the primary key ${pk} to a constant; the key comes from its "${pk}" input, so remove this change`)
+      else if (effectKind !== 'create' || st.value.field === pk) {
+        undeployable.push(
+          effectKind === 'create'
+            ? `${st.where} sets the primary key ${pk}; a create already files the record under its "${pk}" input, so remove this change`
+            : `${st.where} sets the primary key ${pk}, which addresses the record and cannot be changed; remove this change`,
+        )
+      }
+      continue
+    }
+    if (st.value.kind === 'literal') continue
+    if (st.value.kind !== 'input' || typeof st.value.field !== 'string') continue
+    fromInput++
+    if (byLiteral.has(st.property)) undeployable.push(`${st.where} sets ${st.property} from input ${st.value.field}, and another change sets it to a constant; keep one`)
+    if (st.value.field === 'expectedVersion' && strategy === 'expected_version') {
+      undeployable.push(`${st.where} sets ${st.property} from expectedVersion, which already carries the record version; give ${st.property} its own input`)
+    }
+    // The input's kind fits the property's base type.
+    const base = subjectType?.valueTypes?.get(st.property)
+    const kind = kindOf(byName.get(st.value.field))
+    if (base && kind && FITS[base] && !FITS[base]!.includes(kind)) {
+      undeployable.push(`${st.where} sets ${st.property} (${base}) from input ${st.value.field} (${kind}); a ${base} property takes ${FITS[base]!.join(' or ')}`)
+    } else if (kind === 'geopoint' && base && base !== 'geopoint') {
+      undeployable.push(`${st.where} sets ${st.property} (${base}) from a geopoint input; only a geopoint property takes one`)
+    }
+    feeds.set(st.value.field, [...(feeds.get(st.value.field) ?? []), st.property])
+  }
+  for (const [input, properties] of feeds) {
+    if (new Set(properties).size > 1) undeployable.push(`input ${input} sets ${[...new Set(properties)].join(' and ')}; each input feeds one property, so give each its own input`)
+  }
+  if (fromInput === 0) {
+    undeployable.push(byLiteral.size
+      ? `it sets only constants (${[...byLiteral].join(', ')}); its write path needs at least one property set from an input ({ kind: input, field: <input apiName> })`
+      : 'it sets no property from an input, so there is nothing to write: add a property_set with value { kind: input, field: <input apiName> }')
+  }
+
+  // What an outcome checks after the write: only properties that outcome sets, and no required output.
+  outcomes.forEach((o, i) => {
+    const setHere = new Set(sets.filter((x) => x.outcome === i).map((x) => x.property))
+    list(o.postconditions).forEach((pc, j) => {
+      for (const read of observedProperties(pc.assertion)) {
+        if (!setHere.has(read)) undeployable.push(`businessOutcomes[${i}].postconditions[${j}] reads ${read}, which this outcome doesn’t set; a postcondition reads only what its outcome sets`)
+      }
+    })
+    list(o.output).forEach((f, j) => {
+      if (f.required === true) undeployable.push(`businessOutcomes[${i}].output[${j}] (${String(f.apiName)}) is required, and a write over the Blueprint’s records returns no outputs; make it required: false or remove it`)
+    })
+  })
+}
+
+/** The inputs an expression reads (`{ kind: input, field }`). */
+function inputReads(node: unknown, out: string[] = []): string[] {
+  if (Array.isArray(node)) node.forEach((n) => inputReads(n, out))
+  else if (isRecord(node)) {
+    if (node.kind === 'input' && typeof node.field === 'string') out.push(node.field)
+    for (const v of Object.values(node)) if (v && typeof v === 'object') inputReads(v, out)
+  }
+  return out
+}
+
+/** The record properties an expression reads (`observation_property`). */
+function observedProperties(node: unknown, out: string[] = []): string[] {
+  if (Array.isArray(node)) node.forEach((n) => observedProperties(n, out))
+  else if (isRecord(node)) {
+    if (node.kind === 'observation_property' && typeof node.property === 'string') out.push(node.property)
+    for (const v of Object.values(node)) if (v && typeof v === 'object') observedProperties(v, out)
+  }
+  return out
+}