@frontera-sdk/cli 1.53.8 → 1.53.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/cli",
-  "version": "1.53.8",
+  "version": "1.53.9",
   "description": "The frontera CLI — scaffold, pull, save and deploy Frontera apps and automations.",
   "keywords": [
     "frontera",
@@ -40,8 +40,8 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.251",
     "@faker-js/faker": "10.6.0",
-    "@frontera-sdk/core": "1.53.8",
-    "@frontera-sdk/functions": "1.53.8",
+    "@frontera-sdk/core": "1.53.9",
+    "@frontera-sdk/functions": "1.53.9",
     "ai": "^6.0.116",
     "axe-core": "4.12.1",
     "gray-matter": "^4.0.3",
@@ -49,7 +49,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@frontera-sdk/forge-contracts": "1.53.8",
+    "@frontera-sdk/forge-contracts": "1.53.9",
     "@types/bun": "^1.3.14",
     "typescript": "^5.9.3"
   }

package/src/api/governed-action-api.ts

@@ -600,10 +600,12 @@ export class GovernedActionApi {
  * A validation refusal's issues (`details.issues: [{ kind?, path, message }]`,
  * `kind` being `invocation_input` or `invocation` for a submission), one line
  * each as `path: message`, and a stale version's `details.currentVersion` as
- * the version to submit instead; empty when the details carry neither.
+ * the version to submit instead, in the record's own version input when the
+ * stale record is one the Action changes beside its subject (`details.record`);
+ * empty when the details carry neither.
  */
 export function issueLines(details: unknown): string[] {
-  const d = (details && typeof details === 'object' ? details : {}) as { issues?: unknown; currentVersion?: unknown }
+  const d = (details && typeof details === 'object' ? details : {}) as { issues?: unknown; currentVersion?: unknown; record?: unknown; versionInput?: unknown }
   const lines: string[] = []
   if (Array.isArray(d.issues)) {
     for (const i of d.issues) {
@@ -615,7 +617,11 @@ export function issueLines(details: unknown): string[] {
       lines.push(where ? `${where}: ${message}` : message)
     }
   }
-  if (typeof d.currentVersion === 'number' || typeof d.currentVersion === 'string') {
+  if ((typeof d.currentVersion === 'number' || typeof d.currentVersion === 'string') && typeof d.record === 'string') {
+    // A record the Action changes beside its subject, checked against its own version input.
+    const input = typeof d.versionInput === 'string' ? d.versionInput : 'its version input'
+    lines.push(`record ${d.record} is now at version ${String(d.currentVersion)}: read it again and submit with ${input} ${String(d.currentVersion)}`)
+  } else if (typeof d.currentVersion === 'number' || typeof d.currentVersion === 'string') {
     lines.push(`the record is now at version ${String(d.currentVersion)}: read it again and submit with expectedVersion ${String(d.currentVersion)}`)
   }
   return [...new Set(lines)].slice(0, 8)

package/src/blueprint/action-rules.ts

@@ -272,6 +272,8 @@ interface ObjectTypeFacts {
   valueTypes?: ReadonlyMap<string, string>
   /** `backing.editable`: what a governed Action may write; null when the file declares none. */
   editable?: ReadonlySet<string> | null
+  /** The properties the type requires (`required: true`), which nothing may set to null. */
+  required?: ReadonlySet<string>
 }
 
 /** The input kinds that may set a property of each base type. */
@@ -295,6 +297,7 @@ export function actionRuleProblems(files: AuthoredFile[], inheritedConflict?: In
       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,
+      required: new Set(properties.flatMap((p) => (p.required === true && typeof p.apiName === 'string' ? [p.apiName] : []))),
     })
   }
   const refused: string[] = []
@@ -324,8 +327,163 @@ export function actionRuleProblems(files: AuthoredFile[], inheritedConflict?: In
   return { refused, undeployable, refusedActions, ...(inherited.length ? { inherited, inheritedActions } : {}) }
 }
 
-/** One Action document: what the draft route refuses (`refused`) and what will not deploy (`undeployable`). */
+/**
+ * One Action document: what the draft route refuses (`refused`) and what will not deploy (`undeployable`).
+ * An Action with `records` is checked as its subject, and then each record as the subject of a create
+ * (`actionFileForRecord`): a created record as the subject of a create, an existing one as the subject
+ * of an edit or delete, each addressed by its own key input and, when it exists, its own version input.
+ */
 export function checkAction(doc: Doc, types: ReadonlyMap<string, ObjectTypeFacts>, refused: string[], undeployable: string[]): void {
+  if (!Array.isArray(doc.records)) {
+    checkRecord(doc, types, refused, undeployable)
+    return
+  }
+  recordProblems(doc, types, refused, undeployable)
+  const subjectRefused: string[] = []
+  const subjectUndeployable: string[] = []
+  checkRecord(actionFileForRecord(doc, null), types, subjectRefused, subjectUndeployable)
+  refused.push(...subjectRefused)
+  undeployable.push(...subjectUndeployable)
+  for (const record of list(doc.records)) {
+    if (typeof record.key !== 'string') continue
+    const r: string[] = []
+    const u: string[] = []
+    checkRecord(actionFileForRecord(doc, record.key), types, r, u, {
+      keyInput: typeof record.keyInput === 'string' ? record.keyInput : undefined,
+      versionInput: typeof record.versionInput === 'string' ? record.versionInput : undefined,
+    })
+    refused.push(...recordOwnProblems(record.key, subjectRefused, r))
+    undeployable.push(...recordOwnProblems(record.key, subjectUndeployable, u))
+  }
+}
+
+/** A record's problems under its key. A problem with the file as a whole (an input's own shape) is reported once, by the subject. */
+function recordOwnProblems(key: string, subjectProblems: readonly string[], problems: readonly string[]): string[] {
+  return problems.filter((problem) => !subjectProblems.includes(problem)).map((problem) => `records.${key}: ${problem}`)
+}
+
+/**
+ * The Action file as one record sees it: `null` is the subject, with only the changes that name no
+ * record; a record key is that record as a subject, with only its changes: a create for a record the
+ * Action creates, an update or delete under expected_version for one that exists. The service
+ * reviews each record the same way (`actionDefinitionForRecord`).
+ */
+export function actionFileForRecord(doc: Doc, key: string | null): Doc {
+  const outcomes = list(doc.businessOutcomes)
+  const { records: _records, ...rest } = doc
+  // Another record's change stays as an empty placeholder, so every problem keeps the file's own path.
+  const changesOf = (o: Doc) => list(o.expectedChanges).map((c) => {
+    if ((c.record ?? null) !== key) return {}
+    const { record: _record, ...change } = c
+    return change
+  })
+  if (key === null) {
+    return { ...rest, businessOutcomes: outcomes.map((o) => ({ ...o, expectedChanges: changesOf(o) })) }
+  }
+  const record = list(doc.records).find((candidate) => candidate.key === key)
+  const existing = record?.mode === 'existing'
+  const deletes = outcomes.some((o) => o.effect === 'confirmed_applied' && list(o.expectedChanges).some((c) => c.record === key && c.kind === 'object_deleted'))
+  return {
+    ...rest,
+    subject: { objectType: record?.objectType, mode: existing ? 'existing' : 'create' },
+    effect: { ...(isRecord(doc.effect) ? doc.effect : {}), kind: existing ? (deletes ? 'delete' : 'update') : 'create' },
+    concurrency: { strategy: existing ? 'expected_version' : 'append_once' },
+    submissionCriteria: [],
+    businessOutcomes: outcomes.map((o) => ({ ...o, expectedChanges: changesOf(o), postconditions: [], output: [] })),
+  }
+}
+
+/**
+ * The rules on `records` themselves: each is named once and addressed by its own required, internal key
+ * input; a created record is created by this Action, and an existing one is checked against its own
+ * required version input and changed or deleted by it. One whose key or version input is the subject's
+ * key or version input saves, and its write path refuses it (`deriveOntologyEditPlan`).
+ */
+function recordProblems(doc: Doc, types: ReadonlyMap<string, ObjectTypeFacts>, refused: string[], undeployable: string[]): void {
+  const records = list(doc.records)
+  const inputs = new Map(list(doc.inputs).flatMap((f) => (typeof f.apiName === 'string' ? [[f.apiName, f] as const] : [])))
+  const subjectType = isRecord(doc.subject) && typeof doc.subject.objectType === 'string' ? doc.subject.objectType : undefined
+  const subjectKey = subjectType ? types.get(subjectType)?.primaryKey : undefined
+  if (records.length > 10) refused.push(`records lists ${records.length} records; an Action writes at most 10 beside its subject`)
+  const keys = new Set<string>()
+  const keyInputs = new Set<string>()
+  const own = (where: string, role: string, name: string) => {
+    if (keyInputs.has(name)) refused.push(`${where} takes its ${role} from input ${name}, as another record does; give each record its own ${role} input`)
+    if (name === subjectKey || name === 'expectedVersion') undeployable.push(`${where} takes its ${role} from input ${name}, which already ${name === 'expectedVersion' ? 'carries the subject’s version' : 'addresses the subject'}; give the record its own ${role} input`)
+    keyInputs.add(name)
+  }
+  records.forEach((record, i) => {
+    const where = `records[${i}]`
+    if (typeof record.key !== 'string' || !/^[a-z][a-z0-9_]{0,99}$/.test(record.key)) refused.push(`${where} needs key: the record’s name in this Action, lowercase snake_case (key: event)`)
+    else if (keys.has(record.key)) refused.push(`${where}: two records are both named ${record.key}; give each its own key`)
+    else keys.add(record.key)
+    if (record.mode !== 'create' && record.mode !== 'existing') refused.push(`${where} needs mode: create (a record this Action creates) or existing (one it changes or deletes)`)
+    if (typeof record.objectType !== 'string') refused.push(`${where} needs objectType: the object type of the record, by apiName`)
+    else if (!types.has(record.objectType)) refused.push(`${where} names a ${record.objectType}, which no blueprint/object-types file defines`)
+    const keyInput = typeof record.keyInput === 'string' ? record.keyInput : undefined
+    if (!keyInput) refused.push(`${where} needs keyInput: the required input that carries the record’s primary key, by apiName`)
+    else {
+      const input = inputs.get(keyInput)
+      if (!input) refused.push(`${where} takes its key from input ${keyInput}, which the Action does not declare; add it under inputs (required: true)`)
+      else if (input.required !== true) refused.push(`${where} takes its key from input ${keyInput}, which must be required: true`)
+      else if (input.sensitivity !== 'internal') refused.push(`${where} takes its key from input ${keyInput}, which must be sensitivity: internal; a request names the records it writes wherever it is shown`)
+      own(where, 'key', keyInput)
+    }
+    if (record.mode !== 'existing') {
+      if (record.versionInput !== undefined) refused.push(`${where} is created by this Action, so it has no version to check; remove versionInput`)
+      return
+    }
+    const versionInput = typeof record.versionInput === 'string' ? record.versionInput : undefined
+    if (!versionInput) {
+      refused.push(`${where} needs versionInput: the required input that carries the version the request was decided on (a query row’s _meta.recordVersion), by apiName`)
+      return
+    }
+    const input = inputs.get(versionInput)
+    if (!input) refused.push(`${where} takes its version from input ${versionInput}, which the Action does not declare; add it under inputs ({ kind: number, integer: true, minimum: 0 }, required: true)`)
+    else if (input.required !== true) refused.push(`${where} takes its version from input ${versionInput}, which must be required: true`)
+    own(where, 'version', versionInput)
+  })
+  const byKey = new Map(records.flatMap((record) => (typeof record.key === 'string' ? [[record.key, record] as const] : [])))
+  const created = new Set<string>()
+  const changed = new Set<string>()
+  list(doc.businessOutcomes).forEach((o, i) => list(o.expectedChanges).forEach((c, j) => {
+    if (c.record === undefined) return
+    const where = `businessOutcomes[${i}].expectedChanges[${j}]`
+    const record = typeof c.record === 'string' ? byKey.get(c.record) : undefined
+    if (!record) {
+      refused.push(`${where} names record ${String(c.record)}, which records does not declare`)
+      return
+    }
+    if (c.objectType !== undefined && c.objectType !== record.objectType) refused.push(`${where} changes a ${String(c.objectType)}, but record ${String(c.record)} is a ${String(record.objectType)}`)
+    if (c.kind === 'lifecycle_transition') refused.push(`${where}: a lifecycle_transition changes the subject only, so it cannot name record ${String(c.record)}`)
+    else if (record.mode === 'existing' && c.kind === 'object_created') refused.push(`${where}: record ${String(c.record)} exists already, so object_created cannot name it; declare it with mode: create to create it`)
+    else if (record.mode !== 'existing' && c.kind === 'object_deleted') refused.push(`${where}: record ${String(c.record)} is created by this Action, so object_deleted cannot name it`)
+    if (o.effect !== 'confirmed_applied') return
+    if (c.kind === 'object_created') created.add(String(c.record))
+    else changed.add(String(c.record))
+  }))
+  for (const key of keys) {
+    const record = byKey.get(key)
+    const type = String(record?.objectType ?? '<ObjectType>')
+    if (record?.mode === 'existing') {
+      if (!changed.has(key)) refused.push(`records.${key} exists already and nothing changes it: add { kind: object_deleted, objectType: ${type}, record: ${key} } or a property_set with record: ${key} to its applied outcome`)
+    } else if (!created.has(key)) refused.push(`records.${key} is created by this Action: add { kind: object_created, objectType: ${type}, record: ${key} } to its applied outcome`)
+  }
+}
+
+function checkRecord(
+  doc: Doc,
+  types: ReadonlyMap<string, ObjectTypeFacts>,
+  refused: string[],
+  undeployable: string[],
+  /**
+   * A related record's key and version inputs; a subject's key input is named like its primary key,
+   * and its version input is expectedVersion.
+   */
+  record?: { keyInput?: string; versionInput?: string },
+): void {
+  const keyInput = record?.keyInput
+  const versionName = record?.versionInput ?? 'expectedVersion'
   const subject = isRecord(doc.subject) ? doc.subject : {}
   const effect = isRecord(doc.effect) ? doc.effect : {}
   const concurrency = isRecord(doc.concurrency) ? doc.concurrency : {}
@@ -403,8 +561,11 @@ export function checkAction(doc: Doc, types: ReadonlyMap<string, ObjectTypeFacts
   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) {
+  const keyName = keyInput ?? pk
+  const key = keyName ? byName.get(keyName) : undefined
+  if (keyInput !== undefined) {
+    if (key && key.required !== true) undeployable.push(`inputs: "${keyInput}" is the record’s key, so it must be required: true`)
+  } else 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`
@@ -417,7 +578,7 @@ export function checkAction(doc: Doc, types: ReadonlyMap<string, ObjectTypeFacts
     // 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)')
+    if (record === undefined && !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))
@@ -446,21 +607,26 @@ export function checkAction(doc: Doc, types: ReadonlyMap<string, ObjectTypeFacts
     }
     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) {
+      else if (effectKind !== 'create' || st.value.field === keyName) {
         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}; a create already files the record under its "${keyName}" 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 === 'literal') {
+      if (st.value.value === null && subjectType?.required?.has(st.property)) {
+        undeployable.push(`${st.where} sets ${st.property} to null, and ${typeName} requires it; set a value, or make ${st.property} optional (required: false)`)
+      }
+      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`)
+    if (st.value.field === versionName && strategy === 'expected_version') {
+      undeployable.push(`${st.where} sets ${st.property} from ${versionName}, 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)

package/src/blueprint/diff.ts

@@ -8,6 +8,7 @@ import {
   type DefinitionBundle,
 } from './model'
 import { CliError } from '../errors'
+import type { PropertyIntents, PropertyRefusal } from './property-intents'
 
 /**
  * The plan: what the files say that the live draft does not, expressed as typed
@@ -37,6 +38,8 @@ export interface ModelOperation {
    * field is not merely wasteful, it fails the run.
    */
   liveDocument?: Record<string, unknown>
+  /** An object type's properties that keep their id and take a new name (`renamedFrom`), made before anything else on it. */
+  renames?: Array<{ from: string; to: string }>
 }
 
 export interface BindingDrift {
@@ -66,6 +69,8 @@ export interface Plan {
   editable: EditableChange[]
   /** Object types whose `backing.dataset` names another Dataset than the draft reads. */
   rebind: RebindChange[]
+  /** What the files' `renamedFrom` and `replaces` keys cannot be applied as (`property-intents.ts`). */
+  propertyRefusals?: PropertyRefusal[]
   unchanged: number
 }
 
@@ -270,13 +275,18 @@ function propertyNames(document: Record<string, unknown>): string[] {
     .filter((name): name is string => typeof name === 'string')
 }
 
-/** `+1 property (tier)` / `-1 property (legacyCode)`, or a bare field count. */
-function describeUpdate(local: Record<string, unknown>, live: Record<string, unknown>): string {
+/** `+1 property (tier)` / `-1 property (legacyCode)`, a rename or a replacement said as one, or a bare field count. */
+function describeUpdate(local: Record<string, unknown>, live: Record<string, unknown>, intents?: Pick<PropertyIntents, 'renames' | 'replacements'>, objectApiName?: string): string {
   const before = new Set(propertyNames(live))
   const after = propertyNames(local)
-  const added = after.filter((name) => !before.has(name))
-  const removed = [...before].filter((name) => !after.includes(name))
-  const parts: string[] = []
+  const replacements = (intents?.replacements ?? []).filter((entry) => entry.objectApiName === objectApiName)
+  const added = after.filter((name) => !before.has(name) && !replacements.some((entry) => entry.added === name))
+  const removed = [...before].filter((name) => !after.includes(name) && !replacements.some((entry) => entry.removed === name))
+  const parts: string[] = [
+    ...(intents?.renames ?? []).filter((entry) => entry.objectApiName === objectApiName)
+      .map((entry) => `rename ${entry.from} → ${entry.to} (its values, edits and references stay)`),
+    ...replacements.map((entry) => `replace ${entry.removed} with ${entry.added} (${entry.removed}'s values are not carried over)`),
+  ]
   if (added.length) parts.push(`+${added.length} propert${added.length === 1 ? 'y' : 'ies'} (${added.join(', ')})`)
   if (removed.length) parts.push(`-${removed.length} propert${removed.length === 1 ? 'y' : 'ies'} (${removed.join(', ')})`)
   return parts.length ? parts.join(', ') : 'fields changed'
@@ -351,6 +361,8 @@ export function diff(
   revision: number,
   /** Absent when the Datasets were not read: no rebind is planned. */
   datasets?: DatasetIndex,
+  /** Read from the files first (`readPropertyIntents`): then `localFiles` and `live` are its own. */
+  intents?: Omit<PropertyIntents, 'files' | 'live'>,
 ): Plan {
   const liveModel = toFiles(live)
   const liveByKey = new Map(liveModel.files.map((file) => [`${file.kind}:${file.apiName}`, file]))
@@ -382,7 +394,10 @@ export function diff(
         })
         continue
       }
-      if (matches(kind, file.document, existing.document)) {
+      const renames = kind === 'object-type'
+        ? (intents?.renames ?? []).filter((entry) => entry.objectApiName === file.apiName).map(({ from, to }) => ({ from, to }))
+        : []
+      if (matches(kind, file.document, existing.document) && renames.length === 0) {
         if (kind !== 'object-type' || !editableNames.has(file.apiName)) unchanged += 1
         continue
       }
@@ -392,7 +407,8 @@ export function diff(
         apiName: file.apiName,
         document: file.document,
         liveDocument: existing.document,
-        detail: describeUpdate(file.document, existing.document),
+        detail: describeUpdate(file.document, existing.document, intents, file.apiName),
+        ...(renames.length ? { renames } : {}),
       })
     }
     for (const file of liveModel.files.filter((candidate) => candidate.kind === kind)) {
@@ -406,7 +422,10 @@ export function diff(
     }
   }
 
-  return { revision, operations, prunes, drift: driftOf(live), editable, rebind, unchanged }
+  return {
+    revision, operations, prunes, drift: driftOf(live), editable, rebind, unchanged,
+    ...(intents?.refusals.length ? { propertyRefusals: intents.refusals } : {}),
+  }
 }
 
 /**

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

@@ -25,6 +25,11 @@ export interface PublishedActionDefinition {
   businessOutcomes: Array<{
     expectedChanges?: Array<Record<string, unknown>>
   }>
+  /** Records the Action writes beside its subject; each becomes a related step of the plan. */
+  records?: Array<
+    | { key: string; objectTypeId: string; mode: 'create'; keyFieldId: string }
+    | { key: string; objectTypeId: string; mode: 'existing'; keyFieldId: string; versionFieldId: string }
+  >
 }
 
 export interface ObjectTypeShape {
@@ -63,6 +68,16 @@ export interface OntologyEditPlan {
   mediaAttachment?: { propertyApiName?: string; itemIdProperty?: string; mediaSetId: string; uploadParameter: string }
   impactBounds: { maxAffectedRows: number; maxTouchedRows: number }
   capabilities: Record<string, unknown>
+  related?: Array<{
+    record: string
+    objectTypeId: string
+    objectTypeApiName: string
+    op: 'create' | 'patch' | 'delete'
+    set: Record<string, string>
+    pkParameter: string
+    /** Present exactly when the record exists already. */
+    expectedVersionParameter?: string
+  }>
 }
 
 export class PlanDerivationError extends Error {
@@ -94,6 +109,46 @@ export function ontologyEditCompatibilityFingerprint(
   return `sha256:${createHash('sha256').update(canonical).digest('hex')}`
 }
 
+/**
+ * The service's `ontologyEditPlanFingerprint`, reproduced: the subject's
+ * fingerprint alone, or for a plan with related records, one over the subject's
+ * and each record's (canonical JSON, keys in lexicographic order).
+ */
+export function ontologyEditPlanFingerprint(plan: Pick<OntologyEditPlan, 'targetCompatibility' | 'related'>): string {
+  const subject = plan.targetCompatibility.expectedFingerprint
+  if (!plan.related?.length) return subject
+  const related = plan.related
+    .map((step) => ({ fingerprint: ontologyEditCompatibilityFingerprint(step.objectTypeId, Object.keys(step.set)), record: step.record }))
+    .sort((a, b) => (a.record < b.record ? -1 : a.record > b.record ? 1 : 0))
+  return `sha256:${createHash('sha256').update(JSON.stringify({ related, subject })).digest('hex')}`
+}
+
+/** The Action as one record sees it: the service's `actionDefinitionForRecord`. */
+function actionForRecord(
+  action: PublishedActionDefinition,
+  record: NonNullable<PublishedActionDefinition['records']>[number] | null,
+): PublishedActionDefinition {
+  const changesOf = (outcome: PublishedActionDefinition['businessOutcomes'][number]) =>
+    (outcome.expectedChanges ?? [])
+      .filter((change) => change.record === record?.key)
+      .map(({ record: _record, ...change }) => change)
+  if (record === null) {
+    return { ...action, businessOutcomes: action.businessOutcomes.map((outcome) => ({ ...outcome, expectedChanges: changesOf(outcome) })) }
+  }
+  const businessOutcomes = action.businessOutcomes.map((outcome) => ({ ...outcome, expectedChanges: changesOf(outcome) }))
+  if (record.mode === 'create') {
+    return { ...action, subject: { objectTypeId: record.objectTypeId, mode: 'create' }, effect: { kind: 'create' }, concurrency: { strategy: 'append_once' }, businessOutcomes }
+  }
+  const deletes = businessOutcomes.some((outcome) => outcome.expectedChanges.some((change) => change.kind === 'object_deleted'))
+  return {
+    ...action,
+    subject: { objectTypeId: record.objectTypeId, mode: 'existing' },
+    effect: { kind: deletes ? 'delete' : 'update' },
+    concurrency: { strategy: 'expected_version' },
+    businessOutcomes,
+  }
+}
+
 const OP_FOR_EFFECT: Readonly<Record<string, OntologyEditPlan['op']>> = {
   update: 'patch',
   create: 'create',
@@ -104,6 +159,102 @@ export function deriveOntologyEditPlan(
   action: PublishedActionDefinition,
   objectType: ObjectTypeShape,
   attachment?: MediaAttachmentChoice,
+  /** The object types of the records the Action writes beside its subject. */
+  relatedTypes: readonly ObjectTypeShape[] = [],
+): OntologyEditPlan {
+  if (!action.records?.length) return deriveStep(action, objectType, attachment)
+  const subject = deriveStep(actionForRecord(action, null), objectType, attachment)
+  const inputName = (id: string) => action.inputs.find((input) => input.id === id)?.apiName
+  // Every version parameter of the edit: none may also be written as a value.
+  const versions = [
+    ...(subject.expectedVersionParameter ? [subject.expectedVersionParameter] : []),
+    ...action.records.flatMap((record) => (record.mode === 'existing' ? [inputName(record.versionFieldId)].filter((name): name is string => name !== undefined) : [])),
+  ]
+  const related = action.records.map((record) => {
+    const type = relatedTypes.find((candidate) => candidate.id === record.objectTypeId)
+    if (!type) {
+      throw new PlanDerivationError(
+        `Action "${action.apiName}" writes record "${record.key}" of an object type this deploy did not find.`,
+        'Publish the object type the record names, then deploy again.',
+      )
+    }
+    const keyParameter = action.inputs.find((input) => input.id === record.keyFieldId)?.apiName
+    if (!keyParameter) {
+      throw new PlanDerivationError(
+        `Action "${action.apiName}" files record "${record.key}" under an input it does not declare.`,
+        'Name a required input of the Action as the record’s keyInput.',
+      )
+    }
+    if (keyParameter === subject.pkParameter || keyParameter === subject.expectedVersionParameter) {
+      throw new PlanDerivationError(
+        `Action "${action.apiName}" files record "${record.key}" under ${keyParameter}, which already ${keyParameter === subject.pkParameter ? 'addresses the subject' : 'carries the subject’s version'}.`,
+        'Give the record its own required key input.',
+      )
+    }
+    const versionParameter = record.mode === 'existing' ? inputName(record.versionFieldId) : undefined
+    if (record.mode === 'existing' && !versionParameter) {
+      throw new PlanDerivationError(
+        `Action "${action.apiName}" checks record "${record.key}" against a version input it does not declare.`,
+        'Name a required input of the Action as the record’s versionInput.',
+      )
+    }
+    if (versionParameter && (versionParameter === subject.pkParameter || versionParameter === subject.expectedVersionParameter)) {
+      throw new PlanDerivationError(
+        `Action "${action.apiName}" checks record "${record.key}" against ${versionParameter}, which already ${versionParameter === subject.pkParameter ? 'addresses the subject' : 'carries the subject’s version'}.`,
+        'Give the record its own required version input.',
+      )
+    }
+    let step: OntologyEditPlan
+    try {
+      step = deriveStep(actionForRecord(action, record), type, undefined, keyParameter, versionParameter)
+    } catch (error) {
+      if (!(error instanceof PlanDerivationError)) throw error
+      throw new PlanDerivationError(`Record "${record.key}": ${error.message}`, error.hint)
+    }
+    const fromVersion = Object.values(step.set).find((parameter) => versions.includes(parameter))
+    if (fromVersion) {
+      throw new PlanDerivationError(
+        `Record "${record.key}" writes a property from ${fromVersion}, which carries a record’s version.`,
+        'Give that property its own input: every mapped parameter carries exactly one role.',
+      )
+    }
+    return {
+      record: record.key,
+      objectTypeId: step.objectTypeId,
+      objectTypeApiName: step.objectTypeApiName,
+      op: step.op,
+      set: step.set,
+      pkParameter: step.pkParameter,
+      ...(step.expectedVersionParameter ? { expectedVersionParameter: step.expectedVersionParameter } : {}),
+    }
+  })
+  const addresses = related.flatMap((step) => [step.pkParameter, ...(step.expectedVersionParameter ? [step.expectedVersionParameter] : [])])
+  const reused = addresses.find((parameter, index) => addresses.indexOf(parameter) !== index)
+  if (reused) {
+    throw new PlanDerivationError(
+      `Action "${action.apiName}" addresses two records with the same input, ${reused}.`,
+      'Give each record its own required key input and, when it exists, its own version input.',
+    )
+  }
+  const rows = 1 + related.length
+  return {
+    ...subject,
+    targetCompatibility: { kind: 'ontology_edit', expectedFingerprint: ontologyEditPlanFingerprint({ ...subject, related }) },
+    impactBounds: { maxAffectedRows: rows, maxTouchedRows: rows },
+    related,
+  }
+}
+
+/**
+ * One record's step: the subject's, or a related record's addressed by `keyParameter` and, when it
+ * exists, checked against `versionParameter`.
+ */
+function deriveStep(
+  action: PublishedActionDefinition,
+  objectType: ObjectTypeShape,
+  attachment?: MediaAttachmentChoice,
+  keyParameter?: string,
+  versionParameter?: string,
 ): OntologyEditPlan {
   const op = OP_FOR_EFFECT[action.effect.kind]
   if (!op) {
@@ -134,7 +285,7 @@ export function deriveOntologyEditPlan(
   const constants: string[] = []
   for (const outcome of action.businessOutcomes) {
     for (const change of outcome.expectedChanges ?? []) {
-      if (change.kind !== 'property_set') continue
+      if (change.kind !== 'property_set' || change.record !== undefined) continue
       const value = change.value as { kind?: string; fieldId?: string } | undefined
       if (value?.kind === 'literal') {
         const property = propertyApiNameById.get(String(change.propertyId))
@@ -177,7 +328,7 @@ export function deriveOntologyEditPlan(
       'Set one with `frontera blueprint update object-type`, then publish.',
     )
   }
-  const pkParameter = action.inputs.find((i) => i.apiName === pkApiName)?.apiName
+  const pkParameter = keyParameter ?? action.inputs.find((i) => i.apiName === pkApiName)?.apiName
   if (!pkParameter) {
     throw new PlanDerivationError(
       `Action "${action.apiName}" takes no "${pkApiName}" parameter, so an edit has no address.`,
@@ -213,7 +364,7 @@ export function deriveOntologyEditPlan(
   // 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'
-    ? action.inputs.find((i) => i.apiName === 'expectedVersion')?.apiName
+    ? versionParameter ?? action.inputs.find((i) => i.apiName === 'expectedVersion')?.apiName
     : undefined
   if (action.concurrency.strategy === 'expected_version' && !expectedVersionParameter) {
     throw new PlanDerivationError(
@@ -229,7 +380,7 @@ export function deriveOntologyEditPlan(
   }
   if (expectedVersionParameter && Object.values(set).includes(expectedVersionParameter)) {
     throw new PlanDerivationError(
-      `Action "${action.apiName}" writes a property from expectedVersion, which carries the record version.`,
+      `Action "${action.apiName}" writes a property from ${expectedVersionParameter}, which carries the record version.`,
       'Give that property its own input: every mapped parameter carries exactly one role.',
     )
   }

package/src/blueprint/org-name-check.ts

@@ -1,6 +1,7 @@
 import { localProject } from '../local/local-project'
-import { syncClient, unwrap, type SyncClient } from '../local/local-sync-client'
-import { getSyncKey, readLink } from '../local/local-sync-link'
+import { signInCommand } from '../device-login'
+import { unwrap, type SyncClient } from '../local/local-sync-client'
+import { organizationReader, readLink, targetProfileName } from '../local/local-sync-link'
 import type { ArtifactKind } from './model'
 
 /**
@@ -8,9 +9,9 @@ import type { ArtifactKind } from './model'
  * (Forge improvement plan X11). A workspace sees only its slice of the
  * organization's Blueprint, so `blueprint new object-type Activity` wrote a
  * file a change request then refused: the organization had an `Activity`
- * outside the slice (P5 A9). Read with the project's organization key from
- * `frontera local sync connect`; without a link or that key it is not
- * checked, and says so.
+ * outside the slice (P5 A9). Read as the person signed in for the project's
+ * workspace, or with its organization key; without a link or either it is
+ * not checked, and says so.
  */
 export type NameCheck =
   | { checked: false; why: string }
@@ -39,9 +40,10 @@ export async function orgNameCheck(root: string, kind: ArtifactKind, apiName: st
     const project = localProject(root)
     const link = readLink(project.root)
     if (!link) return { checked: false, why: 'the project is linked to no workspace' }
-    const key = getSyncKey(project, 'organization')
-    if (!key) return { checked: false, why: 'the project has no organization key (`frontera local sync connect --org-key -`)' }
-    client = syncClient(link.platform, key)
+    const reader = await organizationReader(project, link)
+    if (reader.notSteward) return { checked: false, why: `${reader.notSteward}, signed in for the project's workspace, is not a Blueprint Steward, who reads the organization's names` }
+    if (!reader.client) return { checked: false, why: `no one is signed in for the project's workspace (\`${signInCommand(targetProfileName(project, link))}\`)` }
+    client = reader.client
   }
   try {
     const found = await client.find<unknown>('/v1/blueprint/lifecycle')