@frontera-sdk/cli 1.53.8 → 1.53.10

package/src/blueprint/projection.ts

@@ -188,9 +188,12 @@ function backingToFile(
       ? { column: entry.sourcePath, field: entry.sourceField }
       : entry.sourcePath
   }
-  const editable = (mapping.editableProperties ?? [])
-    .map((id) => apiNameById.get(id))
-    .filter((name): name is string => Boolean(name))
+  // A set, which the service keeps sorted by property id: written in the type's own property order, so the
+  // file reads like the type and stays the same from one read to the next.
+  const editableIds = new Set(mapping.editableProperties ?? [])
+  const editable = object.properties
+    .filter((property) => editableIds.has(property.id))
+    .map((property) => property.apiName)
   return {
     dataset,
     mapping: entries,
@@ -355,6 +358,13 @@ function actionToFile(action: Record<string, unknown>, names: ActionNames): Reco
     if (isRecord(input.valueType)) named(input.valueType, 'objectTypeId', 'objectType', names.object)
   }
 
+  for (const record of Array.isArray(file.records) ? file.records : []) {
+    if (!isRecord(record)) continue
+    named(record, 'objectTypeId', 'objectType', names.object)
+    named(record, 'keyFieldId', 'keyInput', inputNames)
+    named(record, 'versionFieldId', 'versionInput', inputNames)
+  }
+
   for (const criterion of Array.isArray(file.submissionCriteria) ? file.submissionCriteria : []) {
     if (!isRecord(criterion)) continue
     delete criterion.id

package/src/blueprint/property-intents.ts

@@ -0,0 +1,248 @@
+import { parseRef } from '../local/local-sync-refs'
+import type { AuthoredFile, DefinitionBundle } from './model'
+
+/**
+ * What a type file says about a property the draft holds under another name.
+ *
+ * A property the file stops naming and one it names for the first time look the
+ * same whether the person renamed a field or replaced it, and the two do opposite
+ * things to the values behind it. Two keys on the new property say which:
+ *
+ *   renamedFrom: <old>  the same property under a new name. Its id, its column,
+ *                       its edited values, its editability and every Action, link
+ *                       and metric that names it stay with it.
+ *   replaces: <old>     a new property. <old> is removed, and its values are not
+ *                       carried over.
+ *
+ * Read here and taken off the documents, so nothing after this compares or sends
+ * them. A key whose old name the draft no longer holds has already happened (the
+ * draft was renamed, or the name never reached it) and asks for nothing.
+ */
+export interface PropertyRename { objectApiName: string; from: string; to: string }
+/** A saved object set's file, `object-sets/<ref>.yaml` under the Blueprint folder. */
+export interface ObjectSetDocument { path: string; ref: string; document: Record<string, unknown> }
+export interface PropertyReplacement { objectApiName: string; removed: string; added: string }
+export interface PropertyRefusal { objectApiName: string; message: string; next: string }
+
+export interface PropertyIntents {
+  /** The files without `renamedFrom` and `replaces`. */
+  files: AuthoredFile[]
+  /** The draft as it reads once every rename is made: names changed, ids kept. */
+  live: DefinitionBundle
+  renames: PropertyRename[]
+  replacements: PropertyReplacement[]
+  refusals: PropertyRefusal[]
+}
+
+const INTENT_KEYS = ['renamedFrom', 'replaces'] as const
+
+type Doc = Record<string, unknown>
+const isDoc = (value: unknown): value is Doc => typeof value === 'object' && value !== null && !Array.isArray(value)
+const propertiesOf = (doc: Doc): Doc[] => (Array.isArray(doc.properties) ? doc.properties.filter(isDoc) : [])
+
+export function renameCommand(objectApiName: string, from: string, to: string): string {
+  return `frontera blueprint rename property ${objectApiName} ${from} ${to}`
+}
+
+export function readPropertyIntents(files: AuthoredFile[], draft: DefinitionBundle, objectSets: ObjectSetDocument[] = []): PropertyIntents {
+  const live = structuredClone(draft)
+  const renames: PropertyRename[] = []
+  const replacements: PropertyReplacement[] = []
+  const refusals: PropertyRefusal[] = []
+
+  for (const file of files) {
+    if (file.kind !== 'object-type') continue
+    const object = live.objects.find((candidate) => candidate.apiName === file.apiName)
+    if (!object) continue
+    const declared = propertiesOf(file.document)
+    const declaredNames = new Set(declared.map((property) => String(property.apiName)))
+    const liveNames = new Set(object.properties.map((property) => property.apiName))
+    const refuse = (message: string, next: string) => refusals.push({ objectApiName: file.apiName, message: `${file.path}: ${message}`, next })
+
+    const renamedHere = new Map<string, string>()
+    const replaced = new Set<string>()
+    const replacing = new Set<string>()
+    for (const property of declared) {
+      const name = String(property.apiName)
+      const from = property.renamedFrom
+      if (typeof from === 'string' && from !== name && liveNames.has(from)) {
+        if (liveNames.has(name)) {
+          refuse(`${name} says renamedFrom: ${from}, and ${file.apiName} already has both ${from} and ${name}.`,
+            `rename ${from} once ${name} is gone (remove ${name} in an apply of its own), or take renamedFrom off ${name}`)
+        } else if (renamedHere.has(from)) {
+          refuse(`${renamedHere.get(from)} and ${name} both say renamedFrom: ${from}; one property has one new name.`,
+            `keep renamedFrom: ${from} on one of them`)
+        } else {
+          renamedHere.set(from, name)
+        }
+      }
+      const old = property.replaces
+      if (typeof old === 'string' && liveNames.has(old) && !declaredNames.has(old) && !liveNames.has(name)) {
+        replaced.add(old)
+        replacing.add(name)
+        replacements.push({ objectApiName: file.apiName, removed: old, added: name })
+      }
+    }
+    for (const [from, to] of renamedHere) {
+      renames.push({ objectApiName: file.apiName, from, to })
+      object.properties.find((property) => property.apiName === from)!.apiName = to
+    }
+
+    const after = new Set(object.properties.map((property) => property.apiName))
+    // A calculated field is added from its latitude and longitude, never in place of a column.
+    const added = declared
+      .filter((property) => !after.has(String(property.apiName)) && !property.calculation && !replacing.has(String(property.apiName)))
+      .map((property) => String(property.apiName))
+    const removed = [...after].filter((name) => !declaredNames.has(name) && !replaced.has(name))
+    if (added.length && removed.length) {
+      const one = added.length === 1 && removed.length === 1
+      refuse(
+        `this edit removes ${removed.join(', ')} and adds ${added.join(', ')} at once, and a rename and a replacement look the same: `
+          + 'a rename keeps the values, edits and references behind the field, a replacement does not carry them over.',
+        one
+          ? `if ${removed[0]} is now ${added[0]}, run \`${renameCommand(file.apiName, removed[0]!, added[0]!)}\` `
+            + `(or write renamedFrom: ${removed[0]} under ${added[0]}); if ${added[0]} replaces it, write replaces: ${removed[0]} under ${added[0]}, then apply again`
+          : 'under each new property write renamedFrom: <old name> (the same field, renamed) or replaces: <old name> (a new field; the old one\'s values are not carried over), then apply again',
+      )
+    }
+  }
+
+  for (const rename of renames) {
+    // A new property that takes the old name back is what those references mean now.
+    const typeFile = files.find((file) => file.kind === 'object-type' && file.apiName === rename.objectApiName)!
+    if (propertiesOf(typeFile.document).some((property) => property.apiName === rename.from)) continue
+    const stale = [
+      ...files.flatMap((file) => namesOf(file, rename.objectApiName, rename.from).map(() => file.path)),
+      ...objectSets.flatMap((set) => objectSetNamesOf(set, files, objectSets, rename.objectApiName, rename.from).map(() => set.path)),
+    ]
+    if (stale.length) {
+      refusals.push({
+        objectApiName: rename.objectApiName,
+        message: `${[...new Set(stale)].join(', ')} still name${stale.length === 1 ? 's' : ''} ${rename.objectApiName}.${rename.from}, which this apply renames to ${rename.to}.`,
+        next: `\`${renameCommand(rename.objectApiName, rename.from, rename.to)}\` changes every file that names it`,
+      })
+    }
+  }
+
+  return { files: files.map(withoutIntents), live, renames, replacements, refusals }
+}
+
+function withoutIntents(file: AuthoredFile): AuthoredFile {
+  if (file.kind !== 'object-type' || !propertiesOf(file.document).some((property) => INTENT_KEYS.some((key) => key in property))) return file
+  const document = structuredClone(file.document)
+  for (const property of propertiesOf(document)) for (const key of INTENT_KEYS) delete property[key]
+  return { ...file, document }
+}
+
+/**
+ * Each place a file names `<objectApiName>.<name>`, other than the property's own
+ * `apiName`, with how to name `to` there instead: a type's keys, its mapping, its
+ * editable list and its location fields; an Action's changes and the subject
+ * properties it observes; a link's ends; a metric's measures, filters, dimensions
+ * and time property.
+ */
+export function namesOf(file: AuthoredFile, objectApiName: string, name: string): Array<(to: string) => void> {
+  const places: Array<(to: string) => void> = []
+  const doc = file.document
+  const at = (holder: Doc | unknown[], key: string | number) => places.push((to) => { (holder as Record<string | number, unknown>)[key] = to })
+
+  if (file.kind === 'object-type' && file.apiName === objectApiName) {
+    for (const key of ['primaryKey', 'title']) if (doc[key] === name) at(doc, key)
+    const backing = isDoc(doc.backing) ? doc.backing : undefined
+    const mapping = isDoc(backing?.mapping) ? backing.mapping : undefined
+    if (mapping && Object.hasOwn(mapping, name)) {
+      places.push((to) => {
+        backing!.mapping = Object.fromEntries(Object.entries(mapping).map(([key, value]) => [key === name ? to : key, value]))
+      })
+    }
+    if (Array.isArray(backing?.editable)) backing.editable.forEach((entry, index) => { if (entry === name) at(backing.editable as unknown[], index) })
+    for (const property of propertiesOf(doc)) {
+      const calculation = property.calculation
+      if (isDoc(calculation)) for (const key of ['latitude', 'longitude']) if (calculation[key] === name) at(calculation, key)
+    }
+    return places
+  }
+
+  const subject = file.kind === 'action' && isDoc(doc.subject) ? doc.subject.objectType : undefined
+  const measured = file.kind === 'metric' && doc.objectType === objectApiName
+  const walk = (node: unknown, key?: string): void => {
+    if (Array.isArray(node)) {
+      node.forEach((entry, index) => {
+        if (measured && key === 'dimensions' && entry === name) at(node, index)
+        else walk(entry)
+      })
+      return
+    }
+    if (!isDoc(node)) return
+    if (node.property === name) {
+      const own = node.objectType === objectApiName
+        || (node.objectType === undefined && ((subject === objectApiName && node.kind === 'observation_property') || measured))
+      if (own) at(node, 'property')
+    }
+    if (measured && node.timeseries === name) at(node, 'timeseries')
+    for (const [child, value] of Object.entries(node)) walk(value, child)
+  }
+  if (file.kind === 'action' || file.kind === 'link-type' || file.kind === 'metric') walk(doc)
+  return places
+}
+
+/**
+ * Each place a saved object set names `<objectApiName>.<name>`: a condition's
+ * `property` in a filter over a set of that type. The type a filter reads is the
+ * type of the set it narrows, followed through links (by the project's link files)
+ * and references to other sets (by their files' `objectType`).
+ */
+export function objectSetNamesOf(
+  set: ObjectSetDocument,
+  files: AuthoredFile[],
+  sets: ObjectSetDocument[],
+  objectApiName: string,
+  name: string,
+): Array<(to: string) => void> {
+  const places: Array<(to: string) => void> = []
+  const ends = new Map(files.filter((file) => file.kind === 'link-type').map((file) => {
+    const end = (key: string) => (isDoc(file.document[key]) ? (file.document[key] as Doc).objectType : undefined)
+    return [file.apiName, { from: end('from'), to: end('to') }]
+  }))
+  const typeOf = (expr: unknown): unknown => {
+    if (!isDoc(expr)) return undefined
+    switch (expr.type) {
+      case 'base':
+      case 'static':
+        return expr.objectType
+      case 'filter':
+        return typeOf(expr.objectSet)
+      case 'searchAround': {
+        const from = typeOf(expr.objectSet)
+        const link = ends.get(String(expr.link))
+        return from === undefined || !link ? undefined : link.from === from ? link.to : link.to === from ? link.from : undefined
+      }
+      case 'union':
+      case 'intersect':
+      case 'subtract':
+        return Array.isArray(expr.objectSets) ? typeOf(expr.objectSets[0]) : undefined
+      case 'reference': {
+        const ref = typeof expr.objectSetId === 'string' ? parseRef(expr.objectSetId) : null
+        return ref?.kind === 'objectSet'
+          ? sets.find((other) => other.ref === ref.name || other.document.name === ref.name)?.document.objectType
+          : undefined
+      }
+      default:
+        return undefined
+    }
+  }
+  const conditions = (where: unknown): void => {
+    if (Array.isArray(where)) return where.forEach(conditions)
+    if (!isDoc(where)) return
+    if (where.property === name) places.push((to) => { where.property = to })
+    for (const key of ['and', 'or', 'not']) conditions(where[key])
+  }
+  const walk = (expr: unknown): void => {
+    if (!isDoc(expr)) return
+    if (expr.type === 'filter' && typeOf(expr.objectSet) === objectApiName) conditions(expr.where)
+    walk(expr.objectSet)
+    if (Array.isArray(expr.objectSets)) expr.objectSets.forEach(walk)
+  }
+  walk(set.document.definition)
+  return places
+}

package/src/blueprint/publish-plan.ts

@@ -52,6 +52,8 @@ export interface ChangedAction {
   apiName: string
   /** As on `NewAction`: known when the release changes the Action's effect kind. */
   editsBlueprint?: boolean
+  /** The object type whose change changed it, when its own definition did not change. */
+  objectType?: string
 }
 
 export interface PublishPlan {
@@ -120,7 +122,22 @@ const NEXT_STEPS: Record<string, (name: string, signIn: string | null) => { why:
   ACTION_BINDING_STATE_CONTRADICTORY: () => ({ why: 'Its deployment state does not add up.', commands: ['frontera action list'] }),
 }
 
-export function publishPlan(report: ValidationReport, signIn: string | null, profile?: string): PublishPlan {
+/** The object types this release changes other than by adding, by id: a property renamed or retyped changes the contract of an Action that uses it. */
+function changedObjectTypes(report: ValidationReport): Map<string, string> {
+  return new Map((report.evolution?.changes ?? [])
+    .filter((change) => change.subject.kind === 'object' && change.classification !== 'additive')
+    .map((change) => [change.subject.id, change.subject.label]))
+}
+
+/** Whether `publishPlan` needs each Action's object type: a switched-off Action whose own definition this release leaves alone, beside a type it changes. */
+export function needsActionSubjects(report: ValidationReport): boolean {
+  const own = new Set((report.evolution?.changes ?? []).filter((change) => change.subject.kind === 'action').map((change) => change.subject.id))
+  return changedObjectTypes(report).size > 0
+    && (report.bindingReadiness?.actions ?? []).some((action) => action.reason === 'ACTION_DISABLED' && !own.has(action.actionDefinitionId))
+}
+
+/** @param actionSubjects each Action's object type id, read from the draft when `needsActionSubjects` says so. */
+export function publishPlan(report: ValidationReport, signIn: string | null, profile?: string, actionSubjects?: ReadonlyMap<string, string>): PublishPlan {
   const changes = report.evolution?.changes ?? []
   const actions = report.bindingReadiness?.actions ?? []
   // Ids to names: a blocker names its subject only by an id in its path.
@@ -141,6 +158,7 @@ export function publishPlan(report: ValidationReport, signIn: string | null, pro
   const newActionIds = new Set(changes.filter((change) => change.code === NEW_ACTION_ENVIRONMENT_CHANGE).map((change) => change.subject.id))
   const changedActionIds = new Set(changes.filter((change) => change.subject.kind === 'action').map((change) => change.subject.id))
   const editsBlueprint = editsBlueprintById(changes)
+  const changedTypes = changedObjectTypes(report)
   return {
     reportId: report.id,
     draftRevision: report.draftRevision,
@@ -158,16 +176,34 @@ export function publishPlan(report: ValidationReport, signIn: string | null, pro
       }
     }),
     changedSwitchedOff: actions
-      .filter((action) => action.reason === 'ACTION_DISABLED' && changedActionIds.has(action.actionDefinitionId) && !newActionIds.has(action.actionDefinitionId))
-      .map((action) => {
+      .filter((action) => action.reason === 'ACTION_DISABLED' && !newActionIds.has(action.actionDefinitionId))
+      .flatMap((action) => {
+        const objectType = changedActionIds.has(action.actionDefinitionId) ? undefined : changedTypes.get(actionSubjects?.get(action.actionDefinitionId) ?? '')
+        if (!changedActionIds.has(action.actionDefinitionId) && objectType === undefined) return []
         const edits = editsBlueprint.get(action.actionDefinitionId)
-        return { apiName: action.actionApiName, ...(edits === undefined ? {} : { editsBlueprint: edits }) }
+        return [{ apiName: action.actionApiName, ...(edits === undefined ? {} : { editsBlueprint: edits }), ...(objectType ? { objectType } : {}) }]
       }),
     // Only a report that carries the list: one without it says nothing either way.
     unchanged: Array.isArray(report.evolution?.changes) && changes.length === 0,
   }
 }
 
+/**
+ * What a person runs after clearing one blocker, so a publish is not tried while
+ * another remains: the other blockers' commands, then the publish, written with
+ * an instruction to fill in when the release needs one. An Action with no
+ * deployment decision is left to the publish, which records it.
+ */
+export function stepsToPublish(plan: PublishPlan, profile?: string): string[] {
+  const blockers = plan.blockers.filter((blocker) => blocker.code !== 'ACTION_UNBOUND')
+    .flatMap((blocker) => blocker.next?.commands ?? [])
+    .filter((command) => !command.startsWith('frontera blueprint publish'))
+  const publish = plan.instructionsNeeded.length
+    ? 'frontera blueprint publish --label cli-release --instruction "<how existing data and environments take these changes>"'
+    : 'frontera blueprint publish'
+  return [...new Set([...blockers, aimed(publish, profile)])]
+}
+
 /** One instruction per change the publish must explain: the person's text, and a new Action's own. */
 export function migrationInstructions(plan: PublishPlan, instruction: string | undefined): Array<{ changeId: string; instruction: string }> {
   return [

package/src/blueprint/render.ts

@@ -59,6 +59,10 @@ export function renderPlan(plan: Plan, options: { prune: boolean } = { prune: fa
       : { marker: MARKER.update, kind: 'object-type', apiName: change.objectApiName, detail: move })
   }
 
+  for (const refusal of plan.propertyRefusals ?? []) {
+    rows.push({ marker: '✕', kind: 'object-type', apiName: refusal.objectApiName, detail: `cannot apply: ${refusal.message} Next: ${refusal.next}` })
+  }
+
   const withheld = withheldNote(plan)
 
   if (rows.length === 0) {

package/src/blueprint/tree.ts

@@ -10,6 +10,7 @@ import {
   type ArtifactKind,
   type AuthoredFile,
 } from './model'
+import type { ObjectSetDocument } from './property-intents'
 
 /**
  * Reading and writing the `blueprint/` tree. No network, no resolution.
@@ -146,6 +147,27 @@ export function removeFromTree(root: string, paths: string[]): string[] {
   return removed
 }
 
+/**
+ * The saved object sets' files, `object-sets/` beside the model's folders. Not part
+ * of the model `apply` sends (`local dev` saves them itself), but they name its
+ * properties, so a property rename reads and rewrites them.
+ */
+export function readObjectSets(root: string): ObjectSetDocument[] {
+  const directory = join(root, 'object-sets')
+  if (!existsSync(directory)) return []
+  return readdirSync(directory).sort().flatMap((entry) => {
+    const extension = extname(entry)
+    if (!READABLE.has(extension) || entry.startsWith('.') || entry.startsWith('#')) return []
+    const path = `object-sets/${entry}`
+    // One that does not parse is skipped, as `local dev` skips it when it saves the sets.
+    try {
+      return [{ path, ref: entry.slice(0, -extension.length), document: parseDocument(path, readFileSync(join(directory, entry), 'utf8')) }]
+    } catch {
+      return []
+    }
+  })
+}
+
 export function writeTree(root: string, files: AuthoredFile[]): string[] {
   const written: string[] = []
   for (const file of files) {

package/src/commands/action/deploy.ts

@@ -4,7 +4,7 @@ import { GovernedActionApi } from '../../api/governed-action-api'
 import { credentialStore } from '../../credential-store'
 import { readDeviceSession } from '../../device-login'
 import { CliError, UsageError } from '../../errors'
-import { deriveOntologyEditPlan, PlanDerivationError } from '../../blueprint/ontology-edit-plan'
+import { deriveOntologyEditPlan, PlanDerivationError, type ObjectTypeShape } from '../../blueprint/ontology-edit-plan'
 import { validationFindings } from '../../local/local-actions'
 import { selectedOrganization, setSelectedOrganization } from '../../organization'
 import { canPrompt, promptConfirm } from '../../prompt'
@@ -73,15 +73,7 @@ export const actionDeploy: Command = {
     const published = await client.publishedAction(apiName)
     const definition = published.definition
 
-    const objectType = await client.activeObjectType(
-      await resolveObjectTypeApiName(client, definition.subject.objectTypeId, apiName),
-    )
-    if (!objectType) {
-      throw new CliError(`Object type for "${apiName}" is not in the active release.`, {
-        code: 'NOT_FOUND',
-        hint: 'Publish a release that carries it, then deploy.',
-      })
-    }
+    const objectType = await activeObjectTypeOf(client, definition.subject.objectTypeId, `The object type "${apiName}" acts on`)
 
     // An attachment Action (L6): the file arrives in --file-input, and the write fills --attach and/or --attach-item-id.
     const attachProperty = flagString(ctx, 'attach')
@@ -98,9 +90,15 @@ export const actionDeploy: Command = {
       ? { uploadInput: fileInput, ...(attachProperty ? { property: attachProperty } : {}), ...(attachItemId ? { itemIdProperty: attachItemId } : {}), ...(mediaSet ? { mediaSetId: mediaSet } : {}) }
       : undefined
 
+    // Each record the Action writes beside its subject, from the same active release.
+    const relatedTypes = []
+    for (const record of definition.records ?? []) {
+      relatedTypes.push(await activeObjectTypeOf(client, record.objectTypeId, `The object type of record "${record.key}" of "${apiName}"`))
+    }
+
     let plan
     try {
-      plan = deriveOntologyEditPlan(definition, objectType, attachment)
+      plan = deriveOntologyEditPlan(definition, objectType, attachment, relatedTypes)
     } catch (err) {
       if (err instanceof PlanDerivationError) {
         throw new CliError(err.message, { code: 'VALIDATION_ERROR', hint: err.hint })
@@ -113,12 +111,21 @@ export const actionDeploy: Command = {
       ...(plan.mediaAttachment ? [`${[plan.mediaAttachment.propertyApiName, plan.mediaAttachment.itemIdProperty].filter(Boolean).join(' and ')} ← the file in ${plan.mediaAttachment.uploadParameter} (Media Set ${plan.mediaAttachment.mediaSetId})`] : []),
     ].join(', ')
 
+    // Each record the write path writes beside its subject, one line each.
+    const creates = (plan.related ?? []).map((step) => {
+      const sets = Object.entries(step.set).map(([property, parameter]) => `${property} ← ${parameter}`).join(', ')
+      if (step.op === 'create') return `  and creates ${step.record} (${step.objectTypeApiName}), filed under ${step.pkParameter}: ${sets}\n`
+      const checked = `${step.objectTypeApiName}), addressed by ${step.pkParameter}, compare-and-set on ${step.expectedVersionParameter}`
+      return step.op === 'delete' ? `  and deletes ${step.record} (${checked}\n` : `  and patches ${step.record} (${checked}: ${sets}\n`
+    }).join('')
+
     if (flagBool(ctx, 'dry-run')) {
       return {
         data: { plan, dryRun: true },
         text: `${plan.op} ${plan.objectTypeApiName}, addressed by ${plan.pkParameter}\n`
           + `  sets ${writes}\n`
           + (plan.expectedVersionParameter ? `  compare-and-set on ${plan.expectedVersionParameter}\n` : '')
+          + creates
           + '\nNothing was written. Re-run without --dry-run to build it.',
       }
     }
@@ -181,7 +188,7 @@ export const actionDeploy: Command = {
       stateId: binding.stateId,
       validationReportId: validation.id,
     }
-    const summary = `  ${plan.op} ${plan.objectTypeApiName} — sets ${writes}`
+    const summary = `  ${plan.op} ${plan.objectTypeApiName} — sets ${writes}${creates ? `\n${creates.trimEnd()}` : ''}`
     const review = `frontera action review ${binding.id} --report ${validation.id}${at}`
     const again = `frontera action deploy ${apiName} --yes${at}`
     const secondPerson = `a second person who may review Actions turns it on with: ${review}`
@@ -262,22 +269,22 @@ export const actionDeploy: Command = {
 }
 
 /**
- * The Action names its subject by id; every read route addresses object types
- * by API name. One list read bridges them, rather than making the caller pass
- * a name the Action already knows.
+ * The Action names object types by id; every read route addresses them by API
+ * name. One list read bridges them, rather than making the caller pass a name
+ * the Action already knows. `named` says which type a refusal is about.
  */
-async function resolveObjectTypeApiName(
+async function activeObjectTypeOf(
   client: GovernedActionApi,
   objectTypeId: string,
-  actionApiName: string,
-): Promise<string> {
-  const types = await client.listActiveObjectTypes()
-  const match = types.find((t) => t.id === objectTypeId)
-  if (!match?.apiName) {
-    throw new CliError(`The object type "${actionApiName}" acts on is not in the active release.`, {
+  named: string,
+): Promise<ObjectTypeShape> {
+  const apiName = (await client.listActiveObjectTypes()).find((t) => t.id === objectTypeId)?.apiName
+  const objectType = apiName ? await client.activeObjectType(apiName) : null
+  if (!objectType) {
+    throw new CliError(`${named} is not in the active release.`, {
       code: 'NOT_FOUND',
-      hint: 'frontera blueprint catalog',
+      hint: 'Publish a release that carries it, then deploy.',
     })
   }
-  return match.apiName
+  return objectType
 }

package/src/commands/action/retire.ts

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto'
 
+import { BlueprintAuthoringApi } from '../../api/blueprint-authoring-api'
 import { GovernedActionApi, type ExternalWritePath } from '../../api/governed-action-api'
+import { publishPlan, stepsToPublish } from '../../blueprint/publish-plan'
 import { CliError, UsageError } from '../../errors'
 import { canPrompt, promptConfirm } from '../../prompt'
 import { flagBool, flagString, type Command } from '../types'
@@ -99,6 +101,12 @@ export const actionRetire: Command = {
         ? `The last write path "${apiName}" ran calls another system (${external.planKind ?? 'a kind the platform cannot read'}), which a second person reviewed, so a second person reviews the one that replaces it. `
           + `\`frontera action deploy ${apiName}${at}\` builds it and prints the command they run.\n\n`
         : ''
+    // What publishing needs now, read as `blueprint publish` reads it: another Action still to retire
+    // comes before the publish, and the publish carries its instruction when the release needs one.
+    const profile = typeof ctx.flags.profile === 'string' ? ctx.flags.profile : undefined
+    const toPublish = await new BlueprintAuthoringApi(ctx.apiUrl, ctx.token).validate()
+      .then((report) => stepsToPublish(publishPlan(report, null, profile), profile))
+      .catch(() => [`frontera blueprint publish${at}`])
     const what = running
       ? `Switched off the running deployment of "${apiName}" and retired it. "${apiName}" does not run until it is deployed again.`
       : current
@@ -106,7 +114,7 @@ export const actionRetire: Command = {
         : `Retired the deployment of "${apiName}" that was still draining.`
     return {
       data: { action: apiName, retired: true, from: current?.state ?? 'draining', switchedOff: running, deployment: retired, externalWritePath: external, ...(unread !== null ? { externalWritePathError: unread } : {}) },
-      text: `${what}\n\n${secondPerson}Next:\n  frontera blueprint publish${at}${running ? `\n  frontera action deploy ${apiName}${at}` : ''}`,
+      text: `${what}\n\n${secondPerson}Next:\n${[...toPublish, ...(running ? [`frontera action deploy ${apiName}${at}`] : [])].map((command) => `  ${command}`).join('\n')}`,
     }
   },
 }

package/src/commands/action/submit.ts

@@ -4,6 +4,7 @@ import { toEnvelope } from '../../exit'
 import { parseInputFlag } from '../automation/run'
 import { flagString, type Command } from '../types'
 import { criteriaRefusal } from './criteria-refusal'
+import { whyNot } from './list'
 import { requestSummary } from './request-summary'
 
 /**
@@ -23,7 +24,8 @@ import { requestSummary } from './request-summary'
 /**
  * `priority=2` is the number 2 and `title=Broken` the string — unless the
  * Action declares the input a string, when the text is taken as written, so
- * `ticketId=123` stays "123".
+ * `ticketId=123` stays "123". `assignee=null` is null for every input, which
+ * empties the property it sets; the text "null" goes through `--input`.
  */
 function pair(raw: string, stringInputs: ReadonlySet<string>): [string, unknown] {
   const eq = raw.indexOf('=')
@@ -32,6 +34,7 @@ function pair(raw: string, stringInputs: ReadonlySet<string>): [string, unknown]
   }
   const key = raw.slice(0, eq)
   const text = raw.slice(eq + 1)
+  if (text === 'null') return [key, null]
   if (stringInputs.has(key)) return [key, text]
   try {
     return [key, JSON.parse(text)]
@@ -48,7 +51,7 @@ export const actionSubmit: Command = {
     scope: 'workspace' as const,
     args: [
       { name: 'apiName', required: true, description: 'The Action to submit, as `action available` lists it' },
-      { name: 'key=value...', required: false, description: 'Parameters; text for string inputs, otherwise read as JSON when it parses' },
+      { name: 'key=value...', required: false, description: 'Parameters; text for string inputs, otherwise read as JSON when it parses. name=null is null for any input, which clears what it sets' },
     ],
     flags: {
       input: 'string',
@@ -60,12 +63,14 @@ export const actionSubmit: Command = {
     },
     summary: 'Submit a request to a deployed Action',
     details: [
+      '`name=null` empties the property an optional input sets (no default); leaving the input out keeps it as it is. For the text "null", use `--input \'{"name":"null"}\'`.',
       'On the local runtime, `--as <persona>` submits as a local persona (`--as submitter`), so a later step can be decided by another one. Refused anywhere else.',
     ],
     examples: [
       'frontera action submit createTicket title=Broken priority=2',
       'frontera action submit escalateTicket --subject TKT-1 --subject-version 0',
       'frontera action submit escalateTicket id=TKT-1 expectedVersion=0',
+      'frontera action submit updateTicket id=TKT-1 expectedVersion=3 owner=null',
       'frontera action submit createTicket --input @params.json',
       'frontera action submit createTicket --idempotency-key retry-2026-09-26-01',
     ],
@@ -87,7 +92,14 @@ export const actionSubmit: Command = {
     // refused here, by name, instead of by the service without one.
     const action = (await client.discover()).find((a) => a.apiName === apiName)
     if (!action) {
-      throw new CliError(`You cannot submit "${apiName}" in this workspace.`, {
+      // Published but not running (switched off after a change to it or its object type, never
+      // deployed): said as `action list` says it, with the command that turns it on.
+      const listed = await client.listDeployableActions().catch(() => null)
+      const entry = Array.isArray(listed) ? listed.find((e) => e.definition?.apiName === apiName) : undefined
+      const why = entry
+        ? whyNot(apiName, { published: true, deploymentStatus: entry.deploymentStatus, reason: entry.reason ?? null, available: entry.availability === 'available' && entry.executable !== false })
+        : ''
+      throw new CliError(`You cannot submit "${apiName}" in this workspace${why ? `. ${apiName}: ${why}` : '.'}`, {
         code: 'NOT_FOUND',
         hint: 'frontera action available — to list the Actions you can submit',
       })
@@ -189,10 +201,14 @@ function transient(err: unknown): boolean {
   return typeof status === 'number' && (status >= 500 || status === 429)
 }
 
-/** Inputs the Action declares as strings, whose text must not be read as JSON. */
+/**
+ * Inputs the Action declares as strings, whose text must not be read as JSON:
+ * `type: 'string'`, or `['string', 'null']` for an optional input that also
+ * takes null (an older service says only `'string'`).
+ */
 function stringInputs(action: ActionDiscovery): ReadonlySet<string> {
   const properties = action.inputSchema?.properties?.input?.properties ?? {}
   return new Set(Object.entries(properties)
-    .filter(([, schema]) => (schema as { type?: unknown } | null)?.type === 'string')
+    .filter(([, schema]) => ([] as unknown[]).concat((schema as { type?: unknown } | null)?.type).includes('string'))
     .map(([name]) => name))
 }

package/src/commands/auth/login.ts

@@ -39,7 +39,7 @@ export const authLogin: Command = {
     flagHelp: { 'no-open': 'print the approval address without opening a browser' },
     summary: 'Sign in as yourself in the browser, for the commands that act as a person',
     details: [
-      'Prints a code and opens the platform’s approval page; approve the code there while signed in. The CLI then keeps a session for the selected profile, beside its key, and uses it only for commands that act as a person (they refuse API keys). The session lasts 12 hours; `frontera auth logout` ends it sooner.',
+      'Prints a code and opens the platform’s approval page; approve the code there while signed in. The CLI then keeps a session for the selected profile, beside its key, and uses it for commands that act as a person (they refuse API keys), for organization commands when the profile holds a workspace key, and for a project’s change requests when the profile is the one `frontera local sync connect` names. Every other command keeps using the profile’s key. The session lasts 12 hours; `frontera auth logout` ends it sooner.',
       'Approve only a code you started yourself, in your own terminal, just now.',
     ],
     examples: ['frontera auth login --browser', 'frontera auth login --browser --profile acme --no-open'],
@@ -61,7 +61,7 @@ export const authLogin: Command = {
     await saveDeviceSession(store, profile, { ...session, ...(email ? { email } : {}) })
     return {
       data: { profile, signedIn: true, email, expiresAt: session.expiresAt, reused: false },
-      text: `Signed in for ${profile}${email ? ` as ${email}` : ''} until ${session.expiresAt}. Commands that act as a person use this session; every other command keeps using the profile's key.`,
+      text: `Signed in for ${profile}${email ? ` as ${email}` : ''} until ${session.expiresAt}. Commands that act as a person use this session, as do organization commands on a profile that holds a workspace key and a project's change requests on its \`local sync\` profile; every other command keeps using the profile's key.`,
     }
   },
 }