@frontera-sdk/cli 1.53.8 → 1.53.10

package/src/commands/local/sync.ts

@@ -11,7 +11,8 @@ import { lessonsToPropose, pullLessons, type LessonsPulled } from '../../local/l
 import { analyticsNeeded, connectionsNeeded, documentationNeeded, standInPath, writePlatformOnly, writeStandIns } from '../../local/local-stand-ins'
 import { localProject, type LocalProject } from '../../local/local-project'
 import { normalizeOrigin, syncClient, type SyncClient } from '../../local/local-sync-client'
-import { getSyncKey, projectFile, projectKeyFingerprints, readLink, registerTargetProfile, removeSyncKey, removeTargetProfile, setSyncKey, targetProfileName, writeLink, type SyncLink } from '../../local/local-sync-link'
+import { getSyncKey, organizationReader, projectFile, projectKeyFingerprints, readLink, registerTargetProfile, removeSyncKey, removeTargetProfile, setSyncKey, targetProfileName, targetSession, writeLink, type SyncLink } from '../../local/local-sync-link'
+import { signInStep } from '../../device-login'
 import { describeRepair, repairBases, type BaseRepair } from '../../local/local-sync-base'
 import { conflictsId, mergeItemFiles, type Choice, type Conflict, type Side } from '../../local/local-sync-merge'
 import {
@@ -106,14 +107,16 @@ function needLink(project: LocalProject): SyncLink {
   return link
 }
 
-export function sourceFor(project: LocalProject, link: SyncLink): SyncSource {
+/** The project's readers: the workspace's with its key, and the organization's (`organizationReader`) when there is one. */
+export async function sourceFor(project: LocalProject, link: SyncLink): Promise<SyncSource> {
   const key = getSyncKey(project, 'workspace')
   if (!key) throw new CliError('no workspace key for this project on this machine', { code: 'SYNC_NO_KEY', hint: 'run `frontera local sync connect` to store one (the link is in frontera.yaml; keys are per machine)' })
-  const org = getSyncKey(project, 'organization')
+  const { client, notSteward } = await organizationReader(project, link)
   return {
     workspace: syncClient(link.platform, key),
-    organization: org ? syncClient(link.platform, org) : undefined,
+    ...(client ? { organization: client } : {}),
     workspaceId: link.workspace,
+    ...(notSteward ? { notSteward } : {}),
   }
 }
 
@@ -186,7 +189,7 @@ export async function settleConflicts(project: LocalProject, link: SyncLink, sna
 
 /** Fetch into the snapshot with the project's keys, then bring conflicted items up to the newer version. */
 export async function fetchFor(project: LocalProject, link: SyncLink, opts: { full?: boolean } = {}): Promise<FetchResult & { conflicts: ConflictsSettled }> {
-  const source = sourceFor(project, link)
+  const source = await sourceFor(project, link)
   const result = await fetchWorkspace(project.root, source, { blueprint: link.blueprint, full: opts.full })
   await nameLink(project, link, source)
   return { ...result, conflicts: await settleConflicts(project, link, result.snapshot, source) }
@@ -215,12 +218,8 @@ function snapshotFor(project: LocalProject, link: SyncLink): RemoteSnapshot | nu
 }
 
 /** The platform with the project's keys, or nothing when this machine has no workspace key. */
-function sourceIfKeyed(project: LocalProject, link: SyncLink): SyncSource | undefined {
-  try {
-    return sourceFor(project, link)
-  } catch {
-    return undefined
-  }
+function sourceIfKeyed(project: LocalProject, link: SyncLink): Promise<SyncSource | undefined> {
+  return sourceFor(project, link).catch(() => undefined)
 }
 
 /**
@@ -250,7 +249,7 @@ export async function planFor(project: LocalProject, link: SyncLink, opts: { kin
   if (opts.drafts?.size) {
     const lock = readLock(project.root)
     const base = lock?.workspace === link.workspace ? lock : null
-    const remote = await readWorkspace(sourceFor(project, link), { kinds: opts.kinds, drafts: opts.drafts, blueprint: link.blueprint })
+    const remote = await readWorkspace(await sourceFor(project, link), { kinds: opts.kinds, drafts: opts.drafts, blueprint: link.blueprint })
     return { remote, plan: computePlan(project.root, remote.items, base, local, { base: readFromBase, directory: remote.directory }), lock, snapshot: null, fetched: null, bases: noBases }
   }
   let snapshot = snapshotFor(project, link)
@@ -272,7 +271,7 @@ export async function planFor(project: LocalProject, link: SyncLink, opts: { kin
     const byRef = new Map(items.map((i) => [i.ref, i]))
     const targets = plan.flatMap((p) => (p.status === 'conflict' || p.status === 'unresolved') && base.items[p.ref] ? [{ ref: p.ref, entry: base.items[p.ref]!, remote: byRef.get(p.ref)?.files }] : [])
     if (targets.length) {
-      bases = await repairBases(project.root, targets, { source: opts.repair === 'online' ? sourceIfKeyed(project, link) : undefined, capabilities: snapshot.capabilities, directory: directoryOf(snapshot) })
+      bases = await repairBases(project.root, targets, { source: opts.repair === 'online' ? await sourceIfKeyed(project, link) : undefined, capabilities: snapshot.capabilities, directory: directoryOf(snapshot) })
       if (bases.some((b) => b.restored.length)) plan = computePlan(project.root, items, base, local, planOpts)
     }
   }
@@ -457,16 +456,19 @@ const connect = async (ctx: CommandContext) => {
   else if (!keepsOrganizationKey) removeSyncKey(project, 'organization')
   writeLink(project.root, link)
   // The workspace as a CLI profile: a change request's steps for a person name it (`--profile`).
-  const { profile, profileError } = await registerTargetProfile(project, link, previousKeys).then(
+  const { profile, profileError } = await registerTargetProfile(project, link, previousKeys, me.orgId).then(
     (name) => ({ profile: name, profileError: null }),
     (err: Error) => ({ profile: null, profileError: err.message }),
   )
+  // A change request is applied as the person signed in for this profile; no organization key needs to be here.
+  const signIn = profile ? await signInStep({ profile, apiUrl: link.platform, named: true }) : null
   return {
-    data: { link, keys: { workspace: true, organization: !!(keys.organization || getSyncKey(project, 'organization')) }, profile },
+    data: { link, keys: { workspace: true, organization: !!(keys.organization || getSyncKey(project, 'organization')) }, profile, signIn },
     text: [
       `Linked to ${link.workspaceName ?? link.workspace}${link.organizationName ? ` (${link.organizationName})` : ''} on ${new URL(platform).host}.`,
       'Keys are in your keychain; the link is in frontera.yaml.',
       ...(profile ? [`A change request's steps for a person reach this platform with \`--profile ${profile}\`, not the local runtime.`] : []),
+      ...(signIn ? [`Change requests you apply, and the steps they leave, act as you: sign in first with \`${signIn}\`.`] : []),
       ...(profileError ? [`No CLI profile was recorded for this platform (${profileError}); a change request's steps for a person name none until one is.`] : []),
       'See what you can pull: `frontera local sync pull --preview`.',
     ].join('\n'),
@@ -538,8 +540,10 @@ const status = async (ctx: CommandContext) => {
       ].filter(Boolean)
     : []
   const fetchedAt = snapshot?.fetchedAt ?? null
-  // Governed Actions are read only with an organization key (§15.1): ask for one when the workspace uses them.
-  const organizationKeyFor = !keys.organization && usesGovernedActions(snapshot) ? 'actions' : null
+  // Governed Actions are read at organization grain (§15.1): as the person signed in for the target, or with an organization key.
+  const person = await targetSession(project, link)
+  const signIn = person || !keys.workspace ? null : await signInStep({ profile: targetProfileName(project, link), apiUrl: link.platform, named: true })
+  const organizationKeyFor = !keys.organization && !person && usesGovernedActions(snapshot) ? 'actions' : null
   // The project's change request, as Forge's card line says it.
   const kept = currentRequest(readRequests(project.root, link.workspace))
   // How the last `local dev` left the project, counted as Forge's home counts it.
@@ -547,18 +551,19 @@ const status = async (ctx: CommandContext) => {
   const mcp = mcpServersNotCarried(project.root)
   const request = kept ? `${kept.state === 'merged' ? 'Applied' : kept.applied && !kept.applied.ok && kept.state !== 'closed' ? 'Apply failed' : kept.state === 'closed' ? 'Closed' : 'Proposed'} · ${plural(kept.refs.length, 'item')} · ${kept.title}` : null
   return {
-    data: { link, keys, lastPull, ...none, ...(tally ?? { counts: null }), ...(plan ? { items: { ...itemStates(plan), ...Object.fromEntries(lessons.map((slug) => [`lessons/${slug}`, 'outgoing' as const])) } } : {}), fetchedAt, platform: platformOf(snapshot), error, organizationKeyFor, build, notCarried: mcp ? { mcpServers: mcp.files, save: mcp.command } : null },
+    data: { link, keys, signedIn: person ? { email: person.email ?? null, until: person.expiresAt } : null, signIn, lastPull, ...none, ...(tally ?? { counts: null }), ...(plan ? { items: { ...itemStates(plan), ...Object.fromEntries(lessons.map((slug) => [`lessons/${slug}`, 'outgoing' as const])) } } : {}), fetchedAt, platform: platformOf(snapshot), error, organizationKeyFor, build, notCarried: mcp ? { mcpServers: mcp.files, save: mcp.command } : null },
     text: [
       `Linked to ${link.workspaceName ?? link.workspace}${link.organizationName ? ` (${link.organizationName})` : ''} on ${new URL(link.platform).host}`,
       `  Last pull   ${lastPull ? when(lastPull) : 'never'}`,
       `  Fetched     ${fetchedAt ? when(fetchedAt) : 'never: run `frontera local sync fetch`'}`,
       `  Keys        workspace ${keys.workspace ? 'stored' : 'missing'}, organization ${keys.organization ? 'stored' : 'none'}`,
+      `  Signed in   ${person ? `as ${person.email ?? 'you'}, until ${person.expiresAt}` : signIn ? `no: \`${signIn}\`` : 'no'}`,
       tally ? `  Workspace   ${parts.length ? parts.join(', ') : 'matches the project'}` : `  Workspace   ${error ?? 'not fetched yet'}`,
       ...(tally && error ? [`  Fetch       ${error}`] : []),
       ...(snapshot?.full ? ['  Platform    older: fast checks aren’t available, so each fetch reads the whole workspace'] : []),
       ...(request ? [`  Request     ${request}`] : []),
       ...(build ? [`  Build       ${buildStatusText(build)}`] : []),
-      ...(organizationKeyFor ? ['  Actions     this workspace’s workflows use governed Actions: run `frontera local sync connect` again with an organization key to bring them'] : []),
+      ...(organizationKeyFor ? [`  Actions     this workspace’s workflows use governed Actions: ${signIn ? `sign in with \`${signIn}\`` : 'connect this computer, then sign in,'} to bring them`] : []),
       ...(mcp ? [`  MCP servers ${mcp.files.join(', ')}: not in a change request; save with \`${mcp.command}\``] : []),
     ].join('\n'),
   }
@@ -575,7 +580,7 @@ const pull = async (ctx: CommandContext) => {
   // A conflicted item whose workspace version moved by a fetch that did not settle it (an older CLI's):
   // settle it before pulling, and plan again. A preview writes nothing, so it only plans.
   if (snapshot && !flagBool(ctx, 'preview')) {
-    const settled = await settleConflicts(project, link, snapshot, repair === 'online' ? sourceIfKeyed(project, link) : undefined)
+    const settled = await settleConflicts(project, link, snapshot, repair === 'online' ? await sourceIfKeyed(project, link) : undefined)
     if (settled.refreshed.length || settled.cleared.length) ({ remote, plan, lock, snapshot, bases } = await planFor(project, link, { kinds, drafts, fetch: 'never', repair }))
   }
   if (!plan) throw new CliError('nothing fetched from the workspace yet', { code: 'SYNC_NOT_FETCHED', hint: 'run `frontera local sync fetch`, or pull without --offline' })
@@ -670,7 +675,7 @@ const pull = async (ctx: CommandContext) => {
   if (!noDocuments) for (const r of pulled) if (r.startsWith('knowledge/') && !documents.includes(r.slice('knowledge/'.length))) documents.push(r.slice('knowledge/'.length))
   const docs: Record<string, DocumentsPulled> = {}
   if (documents.length) {
-    const client = sourceFor(project, link).workspace
+    const client = (await sourceFor(project, link)).workspace
     for (const n of documents) {
       const id = byRef.get(`knowledge/${n}`)?.id
       docs[n] = id ? await pullDocuments(project.root, client, { name: n, id }) : { written: [], present: [], skipped: [], failed: ['its id is not in the fetched snapshot: fetch again'] }
@@ -689,7 +694,7 @@ const pull = async (ctx: CommandContext) => {
       return it?.id && version && (replaceEarlierPull || !existsSync(join(project.root, 'apps', slug))) ? [{ slug, id: it.id, version, ...(replaceEarlierPull ? { replaceEarlierPull } : {}) }] : []
     })
     if (wantCode.length) {
-      const client = sourceFor(project, link).workspace
+      const client = (await sourceFor(project, link)).workspace
       for (const app of wantCode) appCode.push(await pullAppCode(project.root, client, app))
     }
   }
@@ -709,7 +714,7 @@ const pull = async (ctx: CommandContext) => {
   const heldItems = remote.items.filter((i) => held.has(i.ref))
   const needs = connectionsNeeded(heldItems)
   const documentation = documentationNeeded(heldItems)
-  const standIns = needs.length ? await writeStandIns(project.root, needs, fetchMode === 'never' ? undefined : sourceIfKeyed(project, link)?.workspace, documentation) : { written: [], replaced: [] }
+  const standIns = needs.length ? await writeStandIns(project.root, needs, fetchMode === 'never' ? undefined : (await sourceIfKeyed(project, link))?.workspace, documentation) : { written: [], replaced: [] }
   // The workspace's analytics stays on the platform: declared, so the build says it on each Agent that uses it.
   const platformOnly = writePlatformOnly(project.root, analyticsNeeded(heldItems))
   const connectionStandIns = standIns.written.filter((n) => !documentation.has(n))
@@ -723,7 +728,7 @@ const pull = async (ctx: CommandContext) => {
   let lessons: LessonsPulled | null = null
   if (flagBool(ctx, 'lessons')) {
     const agents = Object.keys(readLock(project.root)?.items ?? {}).flatMap((r) => (r.startsWith('agent/') ? [r.slice('agent/'.length)] : []))
-    lessons = await pullLessons(project.root, link.workspace, sourceFor(project, link).workspace, agents)
+    lessons = await pullLessons(project.root, link.workspace, (await sourceFor(project, link)).workspace, agents)
   }
   const lessonLines = !flagBool(ctx, 'lessons')
     ? []

package/src/device-login.ts

@@ -128,6 +128,11 @@ export async function readDeviceSession(store: CredentialStore, profile: string,
   }
 }
 
+/** The browser sign-in, for one profile when named. */
+export function signInCommand(profile?: string): string {
+  return `frontera auth login --browser${profile ? ` --profile ${profile}` : ''}`
+}
+
 /** How long a stored session must still last for a printed sign-in step to be left out: the steps after it take a few minutes. */
 const SIGN_IN_STEP_MARGIN_MS = 5 * 60_000
 
@@ -143,7 +148,7 @@ export async function signInStep(
   now = Date.now(),
 ): Promise<string | null> {
   if (at.profile && (await readDeviceSession(store, at.profile, at.apiUrl, now + SIGN_IN_STEP_MARGIN_MS))) return null
-  return `frontera auth login --browser${at.named && at.profile ? ` --profile ${at.profile}` : ''}`
+  return signInCommand(at.named ? at.profile : undefined)
 }
 
 /** Revoke the session on the platform (best effort) and forget it here. */

package/src/local/local-actions.ts

@@ -261,6 +261,18 @@ async function deployOne(call: Call, published: Deployable, attachment?: LocalAc
     await call('org', 'GET', `/v1/blueprint/object-types/${encodeURIComponent(subject)}`),
   )
   if (!shape?.objectType?.id) return `${subject} is not published here`
+  // Each record the Action writes beside its subject, read the same way.
+  const relatedTypes: ObjectTypeShape[] = []
+  for (const record of definition.records ?? []) {
+    const name = (Array.isArray(types) ? types : []).find((t) => t.id === record.objectTypeId)?.apiName
+    const related = name
+      ? data<{ objectType?: { id?: string; apiName?: string; primaryKeyPropertyId?: string | null }; properties?: ObjectTypeShape['properties'] }>(
+        await call('org', 'GET', `/v1/blueprint/object-types/${encodeURIComponent(name)}`),
+      )
+      : null
+    if (!name || !related?.objectType?.id) return `the object type of its record ${record.key} is not published here`
+    relatedTypes.push({ id: related.objectType.id, apiName: related.objectType.apiName ?? name, primaryKeyPropertyId: related.objectType.primaryKeyPropertyId ?? null, properties: related.properties ?? [] })
+  }
   // A Media Set named in the file is found by its API name among this runtime's sets (the stand-ins included).
   let mediaSetId: string | undefined
   if (attachment?.mediaSet) {
@@ -273,7 +285,7 @@ async function deployOne(call: Call, published: Deployable, attachment?: LocalAc
     : undefined
   let plan
   try {
-    plan = deriveOntologyEditPlan(definition, { id: shape.objectType.id, apiName: shape.objectType.apiName ?? subject, primaryKeyPropertyId: shape.objectType.primaryKeyPropertyId ?? null, properties: shape.properties ?? [] }, choice)
+    plan = deriveOntologyEditPlan(definition, { id: shape.objectType.id, apiName: shape.objectType.apiName ?? subject, primaryKeyPropertyId: shape.objectType.primaryKeyPropertyId ?? null, properties: shape.properties ?? [] }, choice, relatedTypes)
   } catch (err) {
     if (err instanceof PlanDerivationError) return err.message
     throw err

package/src/local/local-applied.ts

@@ -555,7 +555,7 @@ export function buildView(project: LocalProject, organizationId: string | null):
         // Held back for its own reason (the apply watchdog): its words, not a missing dependency.
         if (entry.error) return entry.error
         const n = entry.unnamedActions ?? 0
-        return `Runs ${n === 1 ? 'a governed Action' : `${n} governed Actions`} named only by the platform’s id: add an organization key and pull it again`
+        return `Runs ${n === 1 ? 'a governed Action' : `${n} governed Actions`} named only by the platform’s id: sign in for the project’s workspace and pull it again`
       }
       return `Needs ${needWords(needs[0]!, depth)}${needs.length > 1 ? ` (and ${needs.length - 1} more)` : ''}`
     }

package/src/local/local-blueprint-schemas.ts

@@ -100,6 +100,16 @@ const OBJECT_TYPE: JsonSchema = {
           sharedField: { anyOf: [ref('The shared field it implements', 'shared-field'), { type: 'null' }], description: 'The shared field it implements, by apiName; null detaches it.' },
           semanticType: { anyOf: [ref('The semantic type it carries', 'semantic-type'), { type: 'null' }], description: 'The semantic type its values follow (allowed values, bounds), by apiName; null detaches it.' },
           calculation: { type: 'object', description: 'A calculated field. A location names its latitude and longitude fields: { kind: location, latitude, longitude }.' },
+          renamedFrom: {
+            type: 'string',
+            pattern: '^[a-z][A-Za-z0-9]{0,99}$',
+            description: 'This property is the one named <renamedFrom> until now: `frontera blueprint apply` and a change request rename it, keeping its id, its column, its edited values, its editability and every Action, link and metric that names it. Without it, a property removed and another added in one edit are refused, since a rename and a replacement look the same. `frontera blueprint rename property <ObjectType> <old> <new>` writes it and changes the files that name the old name. Kept after the rename, it asks for nothing.',
+          },
+          replaces: {
+            type: 'string',
+            pattern: '^[a-z][A-Za-z0-9]{0,99}$',
+            description: 'This new property replaces <replaces>, which the file no longer lists: the old property is removed and its values (including values Actions wrote) are not carried over. Use renamedFrom to keep them.',
+          },
           sensitivity: {
             anyOf: [{ enum: ['public', 'internal', 'confidential', 'restricted'] }, { type: 'null' }],
             description: "The field's own classification, when it differs from its object type's (`governance.sensitivity.classification`), which every field without one takes: lower for a key that only identifies a record (a `confidential` Customer's `customerId` as `internal`, so references to it resolve), higher for one field of personal data. Leave it out, or `null`, to take the object type's. A location takes its latitude's and longitude's and declares none. Set by a Blueprint Steward, as the object type's classification is.",
@@ -313,7 +323,7 @@ const ACTION_FIELD: JsonSchema = {
     displayName: text(),
     description: text(),
     valueType: ACTION_VALUE_TYPE,
-    required: { type: 'boolean' },
+    required: { type: 'boolean', description: 'An input with required: false and no default may be left out of a request, which keeps the property it sets as it is, or sent as null, which empties that property (not set, on a create). null is refused on a required input, on one with a default, on one that sets a property its object type requires, and on an Action that writes to another system.' },
     default: { type: ['string', 'number', 'boolean', 'null'], description: 'A JSON scalar that fits valueType. Only on a field with required: false: a required field cannot carry a default.' },
     sensitivity: SENSITIVITY,
   },
@@ -323,7 +333,7 @@ const ACTION_FIELD: JsonSchema = {
 
 /** A value an expected change sets: an input or output by name, or a constant. */
 const CHANGE_VALUE: JsonSchema = {
-  description: '{ kind: input, field: <input apiName> } (the usual), or { kind: literal, value: <scalar> } for a constant ("move to assigned": the platform writes it from the published contract). An Action needs at least one property set from an input besides its key, a constant never sets the key, and a property is set one way, not both. { kind: output } is part of the format, but a write over the Blueprint’s records does not deploy with it.',
+  description: '{ kind: input, field: <input apiName> } (the usual), or { kind: literal, value: <scalar> } for a constant ("move to assigned": the platform writes it from the published contract; null empties the property, never one its object type requires). An Action needs at least one property set from an input besides its key, a constant never sets the key, and a property is set one way, not both. { kind: output } is part of the format, but a write over the Blueprint’s records does not deploy with it.',
   oneOf: [
     { title: 'input', type: 'object', properties: { kind: { const: 'input' }, field: { type: 'string', pattern: MEMBER_NAME, description: 'The input’s apiName.' } }, required: ['kind', 'field'], additionalProperties: false },
     { title: 'output', type: 'object', properties: { kind: { const: 'output' }, field: { type: 'string', pattern: MEMBER_NAME, description: 'The outcome output’s apiName.' } }, required: ['kind', 'field'], additionalProperties: false },
@@ -332,6 +342,11 @@ const CHANGE_VALUE: JsonSchema = {
 }
 
 const ON_TYPE = ref('The object type it changes (the subject’s, for an edit or create)', 'object-type')
+const ON_RECORD: JsonSchema = {
+  type: 'string',
+  pattern: '^[a-z][a-z0-9_]{0,99}$',
+  description: 'The record it changes: one of the Action’s records, by key. Leave it out for the subject.',
+}
 
 /** One expected change, by kind; each names its object type. */
 const EXPECTED_CHANGE: JsonSchema = {
@@ -340,12 +355,12 @@ const EXPECTED_CHANGE: JsonSchema = {
       title: 'property_set',
       type: 'object',
       description: 'Sets one property, which the object type’s backing.editable must list; the input’s kind fits the property’s type (a string property takes string or object_reference, number takes number, date date, timestamp timestamp, boolean boolean, and only a geopoint property takes geopoint). A create never sets its primary key (the record is filed under its key input), a delete sets nothing, and each input feeds one property.',
-      properties: { kind: { const: 'property_set' }, objectType: ON_TYPE, property: text('The property it sets, by apiName.'), value: CHANGE_VALUE },
+      properties: { kind: { const: 'property_set' }, objectType: ON_TYPE, property: text('The property it sets, by apiName.'), value: CHANGE_VALUE, record: ON_RECORD },
       required: ['kind', 'objectType', 'property', 'value'],
       additionalProperties: false,
     },
-    { title: 'object_created', type: 'object', properties: { kind: { const: 'object_created' }, objectType: ON_TYPE }, required: ['kind', 'objectType'], additionalProperties: false },
-    { title: 'object_deleted', type: 'object', properties: { kind: { const: 'object_deleted' }, objectType: ON_TYPE }, required: ['kind', 'objectType'], additionalProperties: false },
+    { title: 'object_created', type: 'object', properties: { kind: { const: 'object_created' }, objectType: ON_TYPE, record: ON_RECORD }, required: ['kind', 'objectType'], additionalProperties: false },
+    { title: 'object_deleted', type: 'object', properties: { kind: { const: 'object_deleted' }, objectType: ON_TYPE, record: ON_RECORD }, required: ['kind', 'objectType'], additionalProperties: false },
     {
       title: 'lifecycle_transition',
       type: 'object',
@@ -416,9 +431,10 @@ const ACTION: JsonSchema = {
   $schema: DRAFT,
   title: 'Blueprint governed Action (blueprint/actions/<apiName>.yaml)',
   description:
-    'A governed write on one object type. Every reference is a name (subject.objectType, effect.authoritySourceSystem, an expected change’s objectType and property or transition, an input’s field); the service resolves them and mints every id. On the local runtime an Action that writes only the Blueprint’s records (effect create, update or delete) is deployed by `local dev`, and one whose effect reaches another system stays switched off. '
+    'A governed write on its subject, and on the records it writes beside it (`records`), in one request. Every reference is a name (subject.objectType, effect.authoritySourceSystem, an expected change’s objectType and property or transition, an input’s field); the service resolves them and mints every id. On the local runtime an Action that writes only the Blueprint’s records (effect create, update or delete) is deployed by `local dev`, and one whose effect reaches another system stays switched off. '
     + 'An edit (subject.mode existing, effect update or delete) takes the subject’s primary key as a required input of the same name, uses concurrency expected_version, and so takes a required `expectedVersion` input ({ kind: number, integer: true, minimum: 0 }: a query row’s _meta.recordVersion). '
     + 'A create (subject.mode create, effect create) uses concurrency append_once, takes the primary key as a required input and never sets it in expectedChanges, and declares object_created. A delete declares object_deleted and sets no property. '
+    + 'An Action may also write up to 10 records beside its subject, in the same request and transaction: each is declared under `records` with a key, its objectType, a mode and the required input that carries its primary key (keyInput, sensitivity internal), and its changes name it with `record: <key>`; a change with no `record` is the subject’s. A record with mode create is one it creates (an Issue edit that logs an IssueEvent): it declares object_created, never sets its own key, and is held to the rules a created subject is. A record with mode existing is one that exists already, which it patches (property_set) or deletes (object_deleted): it also names the required input that carries the version the request was decided on (versionInput, { kind: number, integer: true, minimum: 0 }), is checked against that version at submission and when it is applied, and is held to the rules an edited subject is. All of it is applied, or none of it. '
     + 'A postcondition reads only properties its outcome sets; a submission criterion and an approval step’s condition may read the inputs and the record (observation_property). '
     + 'Each input feeds one property. `frontera blueprint plan` checks these rules before anything is written; `frontera blueprint new action <apiName> --template edit|create --object-type <Type>` writes a file that follows them.',
   type: 'object',
@@ -483,6 +499,24 @@ const ACTION: JsonSchema = {
       additionalProperties: false,
     },
     impact: { type: 'object', properties: { maxSubjects: { const: 1 } }, required: ['maxSubjects'], additionalProperties: false },
+    records: {
+      type: 'array',
+      minItems: 1,
+      maxItems: 10,
+      description: 'Records the Action writes beside its subject, applied together with the subject’s change or not at all.',
+      items: {
+        type: 'object',
+        properties: {
+          key: { type: 'string', pattern: '^[a-z][a-z0-9_]{0,99}$', description: 'The record’s name in this Action; its changes say `record: <key>`.' },
+          objectType: ref('The object type of the record', 'object-type'),
+          mode: { enum: ['create', 'existing'], description: 'create: a record this Action creates. existing: a record that exists already, which it patches or deletes under its own version check.' },
+          keyInput: { type: 'string', pattern: MEMBER_NAME, description: 'The required, internal input that carries the record’s primary key, by apiName. Each record has its own.' },
+          versionInput: { type: 'string', pattern: MEMBER_NAME, description: 'For mode existing only: the required input that carries the record version the request was decided on (a query row’s _meta.recordVersion), by apiName. Each record has its own.' },
+        },
+        required: ['key', 'objectType', 'mode', 'keyInput'],
+        additionalProperties: false,
+      },
+    },
     submissionCriteria: { type: 'array', items: CRITERION, description: 'Conditions every submission must meet, checked before it is accepted.' },
     governance: {
       type: 'object',

package/src/local/local-dev-references.ts

@@ -425,8 +425,8 @@ export async function resolveTarget(
         `error [UNRESOLVED_REFERENCE]: ${target.file} names what this runtime does not have`,
         ...describeUnresolved(unresolved).map((l) => `  ${l}`),
         ...byPlatformId.map((a) => `  ${a.path}: a governed Action named by its platform id (${a.id}), which this runtime does not have`),
-        ...(byPlatformId.length ? ['  hint: pull the workflow again with an organization key connected (`frontera local sync connect`) to name its Actions'] : []),
-        ...(actions ? [`  hint: governed Actions come with the Blueprint (pulled with an organization key) and are deployed on this runtime when it applies; ${actions === 1 ? 'this one is' : 'these are'} not in the project's blueprint/actions/`] : []),
+        ...(byPlatformId.length ? ['  hint: sign in for the project’s workspace (`frontera local sync status` names the sign-in), then pull the workflow again to name its Actions'] : []),
+        ...(actions ? [`  hint: governed Actions come with the Blueprint (pulled while signed in for the project’s workspace) and are deployed on this runtime when it applies; ${actions === 1 ? 'this one is' : 'these are'} not in the project's blueprint/actions/`] : []),
         ...(others ? ['  hint: pull it from the workspace (`frontera local sync pull <kind/name>`) or add its file to the project'] : []),
       ].join('\n'),
     }
@@ -668,7 +668,8 @@ export function resolveBlueprint(project: LocalProject, refused: BlueprintRefusa
     const fit = actionFit(doc)
     const changes = (Array.isArray(doc.businessOutcomes) ? doc.businessOutcomes : []).flatMap((o: Record<string, any>) => (Array.isArray(o?.expectedChanges) ? o.expectedChanges : [])) as Array<Record<string, any>>
     const inputs = (Array.isArray(doc.inputs) ? doc.inputs : []) as Array<Record<string, any>>
-    const touches = [fit.subject, ...changes.map((c) => c?.objectType), ...inputs.map((i) => i?.valueType?.objectType)].filter((t): t is string => typeof t === 'string')
+    const records = (Array.isArray(doc.records) ? doc.records : []) as Array<Record<string, any>>
+    const touches = [fit.subject, ...records.map((r) => r?.objectType), ...changes.map((c) => c?.objectType), ...inputs.map((i) => i?.valueType?.objectType)].filter((t): t is string => typeof t === 'string')
     const offType = touches.find((t) => dropped.has(t))
     const offField = changes.map((c) => `${c?.objectType ?? fit.subject}.${c?.property}`).find((f) => droppedFields.has(f))
     const refusal = refused.get(`action:${doc.apiName}`)

package/src/local/local-jobs.ts

@@ -1,4 +1,5 @@
 import { containerState, followLogs, startContainer, stopContainer } from './local-docker'
+import { withFix } from './fix-words'
 import type { LocalProject } from './local-project'
 import { waitForHttp } from './local-process'
 import { recordRuntime } from './local-runtime-history'
@@ -106,3 +107,30 @@ export function watchJobs(opts: { probe: () => Promise<boolean>; restart: () =>
   timer.unref?.()
   return () => clearInterval(timer)
 }
+
+/** What gets governed work moving again, and where to see why it stopped. */
+export const JOBS_STALL_FIX = '`frontera local restart jobs` restarts the jobs engine and keeps the service and App dev servers running; `frontera local logs jobs` says why it stopped'
+
+/**
+ * Whether the jobs engine is delivering, as the running service reports it on
+ * `/v1/health` (`jobs`): governed Action work that has waited past the
+ * service's threshold to be picked up. The engine can answer on its port and
+ * still not reach the service (its calls in time out), so the port check
+ * that restarts it never sees this. Said, never acted on: restarting it on a
+ * stall would loop if the cause is elsewhere. Null when nothing waits, the
+ * service doesn't answer (other checks say so), or it is a release from
+ * before the report.
+ */
+export async function runtimeJobsProblem(serviceUrl: string, doFetch: (url: string, init?: RequestInit) => Promise<Response> = fetch): Promise<string | null> {
+  try {
+    const res = await doFetch(`${serviceUrl.replace(/\/+$/, '')}/v1/health`, { signal: AbortSignal.timeout(3000) })
+    if (!res.ok) return null
+    const body = (await res.json().catch(() => null)) as { data?: { jobs?: { state?: string; thresholdSeconds?: number } } } | null
+    const jobs = body?.data?.jobs
+    if (jobs?.state !== 'stalled') return null
+    const minutes = Math.round((jobs.thresholdSeconds ?? 120) / 60)
+    return withFix(`the jobs engine isn’t delivering work: governed Action work has waited more than ${minutes} minute${minutes === 1 ? '' : 's'} for it, so writes, approvals and their follow-up stay pending`, JOBS_STALL_FIX)
+  } catch {
+    return null
+  }
+}

package/src/local/local-portability.ts

@@ -143,7 +143,7 @@ export function judge(need: Need, ctx: Context = {}): { class: PortabilityClass;
       // It runs here as it does in the workspace: a warning, not an adaptation.
       return { class: 'portable', text: `runs here as the workspace runs it, with a warning inherited from the workspace: ${need.reasons.join(' ')} The Blueprint’s author fixes the Action’s contract in the workspace` }
     case 'action-unnamed':
-      return { class: 'platform-only', text: `runs ${need.count === 1 ? 'a governed Action' : `${need.count} governed Actions`} this key can’t name: add an organization key to bring ${need.count === 1 ? 'it' : 'them'}` }
+      return { class: 'platform-only', text: `runs ${need.count === 1 ? 'a governed Action' : `${need.count} governed Actions`} this key can’t name: sign in for the project’s workspace to bring ${need.count === 1 ? 'it' : 'them'}` }
     case 'connection':
       return caps.connections ? null : { class: 'stubbed', text: `${ctx.titles?.get(need.name) ?? need.name} isn’t connected here: a stand-in answers its tools with “not connected”` }
     case 'documentation':

package/src/local/local-sync-link.ts

@@ -6,10 +6,11 @@ import { join } from 'node:path'
 import { parseDocument } from 'yaml'
 
 import { credentialStore } from '../credential-store'
-import { forgetDeviceSession } from '../device-login'
+import { forgetDeviceSession, readDeviceSession, type DeviceSession } from '../device-login'
 import { writeFileAtomic } from '../fs-atomic'
 import { configDir } from '../paths'
 import { deleteProfile, fingerprint, getProfile, putProfile } from '../profiles'
+import { syncClient, type SyncClient } from './local-sync-client'
 import { PROJECT_FILES, type LocalProject } from './local-project'
 
 /**
@@ -186,6 +187,59 @@ export function targetProfileName(project: LocalProject, link: SyncLink): string
 /** Where a recorded step acts, `<host>/<workspace>`: a step whose target is not the folder's link is stale. */
 export const targetOf = (link: SyncLink) => `${new URL(link.platform).host}/${link.workspace}`
 
+/**
+ * The person signed in for the project's target (`frontera auth login
+ * --browser --profile <target>`), when the sign-in is for the linked
+ * platform and still lasts; null otherwise. Only the target profile's own
+ * sign-in counts: one kept for another profile is never borrowed.
+ */
+export function targetSession(project: LocalProject, link: SyncLink): Promise<DeviceSession | null> {
+  return readDeviceSession(credentialStore(), targetProfileName(project, link), link.platform)
+}
+
+/**
+ * The project's reader at organization grain (`client`): the person signed
+ * in for the target, in the linked workspace's organization, when they may
+ * read there (a Blueprint Steward, or an owner or admin); else the
+ * organization key stored; null with neither. `notSteward` names the person
+ * signed in when they may not and no key reads in their place.
+ */
+export async function organizationReader(project: LocalProject, link: SyncLink): Promise<{ client: SyncClient | null; notSteward: string | null }> {
+  const key = getSyncKey(project, 'organization')
+  const byKey = key ? syncClient(link.platform, key) : null
+  const person = await targetSession(project, link)
+  const orgId = person ? await targetOrganization(project, link) : null
+  if (!person || !orgId) return { client: byKey, notSteward: null }
+  const client = syncClient(link.platform, person.token, { 'x-org-id': orgId })
+  if (await readsOrganization(client, person.token, orgId)) return { client, notSteward: null }
+  return { client: byKey, notSteward: byKey ? null : (person.email ?? 'the person') }
+}
+
+const organizationReads = new Map<string, Promise<boolean>>()
+
+/** Whether the person may read the organization's Blueprint, asked once per process: a refusal there is a refusal of every organization read. */
+function readsOrganization(client: SyncClient, token: string, orgId: string): Promise<boolean> {
+  const asked = [client.origin, orgId, token].join('\n')
+  if (!organizationReads.has(asked)) {
+    organizationReads.set(asked, client.find('/v1/blueprint/lifecycle').then(() => true, (err: { code?: string }) => err.code !== 'FORBIDDEN' && err.code !== 'UNAUTHORIZED'))
+  }
+  return organizationReads.get(asked)!
+}
+
+/** The linked workspace's organization, as the target profile records it: a profile recorded before it knew one is recorded again. */
+async function targetOrganization(project: LocalProject, link: SyncLink): Promise<string | null> {
+  const name = targetProfileName(project, link)
+  if (!getProfile(name)?.orgId) await registerTargetProfile(project, link).catch(() => null)
+  return getProfile(name)?.orgId ?? null
+}
+
+/** The linked workspace's organization as the platform answers the workspace key; null when it does not. */
+async function workspaceOrganization(project: LocalProject, link: SyncLink): Promise<string | null> {
+  const key = getSyncKey(project, 'workspace')
+  const me = key ? await syncClient(link.platform, key).get<{ orgId?: string | null }>('/v1/whoami').catch(() => null) : null
+  return me?.orgId ?? null
+}
+
 /** The fingerprints of the keys stored for the project now. */
 export function projectKeyFingerprints(project: LocalProject): string[] {
   return (['organization', 'workspace'] as const).flatMap((role) => {
@@ -202,9 +256,11 @@ export function projectKeyFingerprints(project: LocalProject): string[] {
  * or before `connect` replaced them (`previous`), and then takes the current
  * key; one holding another key is left alone. The key is stored as every
  * profile's is, so a machine without a secure store refuses it unless its
- * person chose the 0600 file.
+ * person chose the 0600 file. `orgId` is the workspace's organization,
+ * which `connect` knows even with no organization key; without it, the one
+ * recorded, else the platform's answer to the workspace key.
  */
-export async function registerTargetProfile(project: LocalProject, link: SyncLink, previous: readonly string[] = []): Promise<string | null> {
+export async function registerTargetProfile(project: LocalProject, link: SyncLink, previous: readonly string[] = [], orgId: string | null = null): Promise<string | null> {
   const organizationKey = getSyncKey(project, 'organization')
   const key = organizationKey ?? getSyncKey(project, 'workspace')
   if (!key) return null
@@ -219,7 +275,9 @@ export async function registerTargetProfile(project: LocalProject, link: SyncLin
     apiUrl: link.platform,
     credentialKind: organizationKey ? 'organization' : 'workspace',
     workspaceId: organizationKey ? null : link.workspace,
-    orgId: link.organization ?? null,
+    // The workspace's organization as the platform reports it, so the person signed in on the profile addresses it
+    // when they belong to several. Never frontera.yaml's: a file in the repository does not choose it.
+    orgId: orgId ?? existing?.orgId ?? (await workspaceOrganization(project, link)),
     fingerprint: fingerprint(key),
     createdAt: existing?.createdAt ?? now,
     lastVerifiedAt: now,

package/src/local/local-sync-merge.ts

@@ -21,7 +21,12 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
  *   every element of all three versions). Such a list merges element by
  *   element, matched by that key, with the object rules above. Its order is
  *   ours, as the folder has it, unless only the workspace reordered the
- *   elements all three share; what the other side added comes after.
+ *   elements all three share; what the other side added comes after. A list
+ *   that is a set (`SET_LISTS`: an object type's `backing.editable`) is no
+ *   conflict where a side only reordered it: the other side's elements are
+ *   taken, in our order when both hold the same. Any other list keeps its
+ *   order's meaning (an evaluation's conversation turns, a dataset's key
+ *   columns).
  * - **Multi-line strings** inside JSON or YAML (an Agent's prompts, a
  *   procedure's instructions) and **every other file** (Markdown, code) merge
  *   line by line, diff3-style: edits to different lines merge; the same lines
@@ -125,6 +130,12 @@ class Merger {
 
   array(path: string, b: unknown[] | null, o: unknown[], t: unknown[]): unknown {
     const key = stableKey([...(b ? [b] : []), o, t])
+    // A set a side only reordered (the platform lists it its own way) changed nothing on that side: the other side's
+    // set, and ours, as the folder has it, when both hold the same elements.
+    if (!key && SET_LISTS.has(path)) {
+      if (sameElements(o, t) || (b && sameElements(b, t))) return o
+      if (b && sameElements(b, o)) return t
+    }
     if (!key) {
       const both = union(o, t)
       const choice = this.conflict({ path, base: b ?? ABSENT, ours: o, theirs: t, both })
@@ -172,6 +183,21 @@ function union(ours: unknown[], theirs: unknown[]): unknown[] {
   return out
 }
 
+/** Lists whose order means nothing, by field: an object type's `backing.editable`, which the service keeps by property id. */
+const SET_LISTS = new Set(['backing.editable'])
+
+/** Two lists holding the same elements, each as many times, in any order. */
+function sameElements(a: unknown[], b: unknown[]): boolean {
+  if (a.length !== b.length) return false
+  const left = [...b]
+  for (const x of a) {
+    const at = left.findIndex((y) => deepEqual(x, y))
+    if (at < 0) return false
+    left.splice(at, 1)
+  }
+  return true
+}
+
 /** A conflict's version as a reader sees it: `undefined` where it is absent. */
 function shown(v: unknown): unknown {
   return v === ABSENT ? undefined : v
@@ -327,6 +353,16 @@ function parse(format: Format, text: string): { ok: true; value: unknown } | { o
   }
 }
 
+/** Whether two versions of a file say the same: the same document for JSON and YAML (key order aside), the same text otherwise. */
+export function sameContent(path: string, a: string, b: string): boolean {
+  if (a === b) return true
+  const format = formatOf(path)
+  if (format === 'text') return false
+  const x = parse(format, a)
+  const y = parse(format, b)
+  return x.ok && y.ok && deepEqual(x.value, y.value)
+}
+
 /** A document as a pull writes it: two-space JSON with a final newline, YAML without wrapping. */
 function render(format: Format, value: unknown): string {
   return format === 'json' ? `${JSON.stringify(value, null, 2)}\n` : stringifyYaml(value, { lineWidth: 0 })