@frontera-sdk/cli 1.43.6 → 1.43.8

package/src/blueprint/model.ts

@@ -65,45 +65,65 @@ export interface DefinitionBundle {
    * carries no key at all, and the schemas are strict.
    */
   sharedProperties?: BundleNamed[]
+  /** Optional for the same reason `sharedProperties` is. */
+  semanticTypes?: BundleNamed[]
   /** v2 only. Absent on a v1 bundle rather than empty — the schemas are strict. */
   actions?: BundleNamed[]
 }
 
 /**
  * The authorable kinds, in the order a reader meets them — which is also the order
- * `apply` writes them in, so a kind that others reference comes first. A property
- * names its shared field, so shared fields are created before object types.
+ * `apply` writes them in, so a kind that others reference comes first. A property names
+ * its shared field, so shared fields lead; a link names two object types and a metric
+ * names one; an action names object types, their properties and their transitions, so
+ * it comes last.
  *
- * Two things are deliberately absent, for the same reason: a file the CLI can write
- * but never apply is worse than no file, because it breaks the round trip the tree
- * promises and fails only at the end of a deployment.
+ * A SEMANTIC TYPE IS FIRST, and it has to be: both other carrier kinds reference one
+ * — a shared field by `semanticType:` and a property by the same key — so a tree that
+ * introduces a semantic type and something carrying it has to create the type before
+ * either. Same rule that puts shared fields ahead of object types, one level deeper.
+ *
+ * A kind is authorable only when the tree can EXPRESS it: a file the CLI can write but
+ * never apply is worse than no file, because it breaks the round trip the tree promises
+ * and fails only at the end of a deployment. Two things a file may still NAME are not
+ * themselves authorable here, and both are named rather than hidden because a tree
+ * carrying either is portable only to a deployment that already has it.
  *
  * **Source systems** have no route of their own — `createDraftObjectType` synthesises
- * one for an organization's first object type and nothing else ever creates one.
+ * one for an organization's first object type and nothing else ever creates one. An
+ * action's `effect.authoritySourceSystem` therefore names something this tree cannot
+ * itself create, and on a second deployment that name may resolve to nothing.
+ *
+ * **Lifecycles** are the same shape of gap one level down. `objectTypeCreateBody`
+ * refuses a file that declares one — the create route cannot express it — so an
+ * action's `lifecycle_transition` change names a transition the tree cannot author.
+ * Against the draft it was pulled from that resolves; against a fresh organization it
+ * does not, and the refusal lands mid-apply.
  *
- * **Actions** carry several uuid references the projection cannot turn into names:
- * `subject.objectTypeId`, `effect.authoritySourceSystemId` and `compensationActionId`
- * at least. Emitting them as raw uuids makes the tree unportable — the identifiers are
- * per-deployment — and the create route takes the contract whole, so there is nowhere
- * to resolve them back. `blueprint create|update|delete action` still authors them
- * imperatively; only the FILE path is withheld, and withheld visibly rather than
- * shipped broken.
+ * **Actions** joined the list once the service learned to resolve their references by
+ * name and to mint the ids they own — see `action-reference-resolution` and
+ * `action-identity`. Before that they carried uuids that were correct in the
+ * deployment that minted them and wrong in every other.
  */
 export const ARTIFACT_KINDS = [
+  'semantic-type',
   'shared-field',
   'object-type',
   'link-type',
   'metric',
+  'action',
 ] as const
 
 export type ArtifactKind = (typeof ARTIFACT_KINDS)[number]
 
 /** `object-type` → `object-types/`. Plural directory, singular command word. */
 export const KIND_DIRECTORY: Record<ArtifactKind, string> = {
+  'semantic-type': 'semantic-types',
   'shared-field': 'shared-fields',
   'object-type': 'object-types',
   'link-type': 'link-types',
   metric: 'metrics',
+  action: 'actions',
 }
 
 export const DIRECTORY_KIND: Record<string, ArtifactKind> = Object.fromEntries(
@@ -120,10 +140,14 @@ export const DIRECTORY_KIND: Record<string, ArtifactKind> = Object.fromEntries(
  * existed. A name that cannot name a file is refused before anything is written.
  */
 export const API_NAME_RULE: Record<ArtifactKind, RegExp> = {
+  'semantic-type': /^[a-z][A-Za-z0-9]{0,99}$/,
   'shared-field': /^[a-z][A-Za-z0-9]{0,99}$/,
   'object-type': /^[A-Z][A-Za-z0-9]{0,99}$/,
   'link-type': /^[a-z][A-Za-z0-9]{0,99}$/,
   metric: /^[a-z][A-Za-z0-9]{0,99}$/,
+  // `apiNameSchema` in `action-definition-schema.ts`, which governs the action and
+  // every member of it — the same camelCase rule, and the same 100-character bound.
+  action: /^[a-z][A-Za-z0-9]{0,99}$/,
 }
 
 export function describeApiNameRule(kind: ArtifactKind): string {
@@ -164,6 +188,13 @@ export interface LiveIndex {
    * reference a file writes that is not addressed by name on both sides.
    */
   sharedPropertyIdByApiName: Map<string, string>
+  /**
+   * The SECOND such reference, and it needs its own map rather than sharing the one
+   * above: `semanticType: percentage` is resolved on BOTH carrier kinds — a property
+   * entry and a shared field — and the two namespaces are independent, so a shared
+   * field and a semantic type may legitimately share an apiName.
+   */
+  semanticTypeIdByApiName: Map<string, string>
   /** The live object, by apiName — the merge reads `governance.sourceMappings` off it. */
   objectByApiName: Map<string, BundleObject>
   relationshipByApiName: Map<string, BundleRelationship>
@@ -178,6 +209,7 @@ export function emptyIndex(): LiveIndex {
     metricIdByApiName: new Map(),
     actionIdByApiName: new Map(),
     sharedPropertyIdByApiName: new Map(),
+    semanticTypeIdByApiName: new Map(),
     objectByApiName: new Map(),
     relationshipByApiName: new Map(),
   }
@@ -202,6 +234,9 @@ export function indexBundle(bundle: DefinitionBundle): LiveIndex {
   for (const shared of bundle.sharedProperties ?? []) {
     index.sharedPropertyIdByApiName.set(shared.apiName, shared.id)
   }
+  for (const semanticType of bundle.semanticTypes ?? []) {
+    index.semanticTypeIdByApiName.set(semanticType.apiName, semanticType.id)
+  }
   return index
 }
 

package/src/blueprint/projection.ts

@@ -52,31 +52,61 @@ function rest(source: Record<string, unknown>, resolved: Set<string>): Record<st
 }
 
 /**
- * A property entry, with its shared field named rather than identified.
+ * A property entry, with its two references named rather than identified.
  *
- * The wire's `sharedPropertyId` is the one uuid a property carries that HAS a name
- * to resolve to, so it is resolved rather than stripped — a file that kept it would
- * be unportable in the precise sense this whole tree exists to avoid. The authored
- * key is `sharedField`: the tree is what a person writes, and a person writes field.
+ * `sharedPropertyId` and `semanticTypeId` are the uuids a property carries that HAVE
+ * names to resolve to, so both are resolved rather than stripped — a file that kept
+ * either would be unportable in the precise sense this whole tree exists to avoid.
+ * The authored keys are `sharedField` and `semanticType`: the tree is what a person
+ * writes, and a person writes field and type, not property and id.
  *
- * An id the bundle does not declare is a corrupt export, and it fails here rather
- * than writing the uuid: a tree that round-trips a per-deployment identifier reads
- * as portable and is not, and the failure would then appear at the second
- * deployment instead of at the `pull` that produced it.
+ * Both are emitted, and both may be present on the wire even though the bundle
+ * forbids an implementing property from carrying its own — the projection reports
+ * what the draft says rather than re-deciding it.
  */
 function propertyToFile(
   property: Record<string, unknown>,
   objectApiName: string,
   sharedApiNameById: Map<string, string>,
+  semanticApiNameById: Map<string, string>,
 ): Record<string, unknown> {
-  const body = rest(property, new Set(['id', 'sharedPropertyId']))
-  const sharedPropertyId = property.sharedPropertyId
-  if (sharedPropertyId === undefined || sharedPropertyId === null) return body
-  const apiName = sharedApiNameById.get(String(sharedPropertyId))
+  const body = rest(property, new Set(['id', 'sharedPropertyId', 'semanticTypeId']))
+  const semanticType = resolveName(
+    property.semanticTypeId,
+    semanticApiNameById,
+    'semantic type',
+    `Field "${String(property.apiName)}" on ${objectApiName}`,
+  )
+  const withSemanticType = semanticType === undefined ? body : { ...body, semanticType }
+  const sharedField = resolveName(
+    property.sharedPropertyId,
+    sharedApiNameById,
+    'shared field',
+    `Field "${String(property.apiName)}" on ${objectApiName}`,
+  )
+  return sharedField === undefined ? withSemanticType : { ...withSemanticType, sharedField }
+}
+
+/**
+ * A uuid reference, as the name a file may carry — or nothing, when the bundle
+ * carries no reference at all.
+ *
+ * Shared by both reference kinds and both carriers, because the failure is the same
+ * one every time: an id the bundle does not declare is a corrupt export, and writing
+ * it into the file would produce a tree that round-trips here and names nothing in
+ * the next deployment. It fails at the `pull` that produced it instead.
+ */
+function resolveName(
+  id: unknown,
+  apiNameById: Map<string, string>,
+  label: string,
+  subject: string,
+): string | undefined {
+  if (id === undefined || id === null) return undefined
+  const apiName = apiNameById.get(String(id))
   if (!apiName) {
     throw new CliError(
-      `Field "${String(property.apiName)}" on ${objectApiName} references shared field `
-      + `${String(sharedPropertyId)}, which this draft does not declare.`,
+      `${subject} references ${label} ${String(id)}, which this draft does not declare.`,
       {
         code: 'FAILURE',
         hint: 'The draft is inconsistent — re-read it, and report it if it persists. '
@@ -84,7 +114,7 @@ function propertyToFile(
       },
     )
   }
-  return { ...body, sharedField: apiName }
+  return apiName
 }
 
 /**
@@ -130,6 +160,7 @@ function backingToFile(
 function objectToFile(
   object: BundleObject,
   sharedApiNameById: Map<string, string>,
+  semanticApiNameById: Map<string, string>,
   datasetNameByRevisionId?: Map<string, string>,
 ): Record<string, unknown> {
   const byId = new Map(object.properties.map((property) => [property.id, property.apiName]))
@@ -143,7 +174,7 @@ function objectToFile(
     primaryKey: byId.get(object.primaryKeyPropertyId) ?? object.primaryKeyPropertyId,
     title: byId.get(object.titlePropertyId) ?? object.titlePropertyId,
     properties: object.properties.map((property) =>
-      propertyToFile(property, object.apiName, sharedApiNameById)),
+      propertyToFile(property, object.apiName, sharedApiNameById, semanticApiNameById)),
   }
 }
 
@@ -166,6 +197,133 @@ function linkToFile(link: BundleRelationship, objectApiNameById: Map<string, str
   }
 }
 
+/**
+ * Every name an action can reference, indexed by the id the bundle stores.
+ *
+ * Built once per projection because an action reaches into three levels of another
+ * artifact — a type, its properties, its lifecycle transitions — and rebuilding the
+ * maps per action would be quadratic in the size of the draft.
+ */
+interface ActionNames {
+  object: Map<string, string>
+  /** Property and transition ids are globally unique, so one flat map each is enough. */
+  property: Map<string, string>
+  transition: Map<string, string>
+  sourceSystem: Map<string, string>
+  action: Map<string, string>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Replace an id field with the name it stands for.
+ *
+ * A miss LEAVES THE ID IN PLACE rather than dropping the field. A dropped reference
+ * would make the file parse and then mean something else — the projection's one rule
+ * is that what it cannot translate it carries through untouched, so the loss is
+ * visible in a diff instead of silent.
+ */
+function named(
+  target: Record<string, unknown>,
+  idField: string,
+  nameField: string,
+  names: Map<string, string>,
+): void {
+  const id = target[idField]
+  if (typeof id !== 'string') return
+  const name = names.get(id)
+  if (!name) return
+  target[nameField] = name
+  delete target[idField]
+}
+
+/** `{ kind: 'input', fieldId }` → `{ kind: 'input', field }`, anywhere below `node`. */
+function nameFieldRefs(node: unknown, fields: Map<string, string>, properties: Map<string, string>): void {
+  if (Array.isArray(node)) {
+    for (const entry of node) nameFieldRefs(entry, fields, properties)
+    return
+  }
+  if (!isRecord(node)) return
+  if ((node.kind === 'input' || node.kind === 'output') && typeof node.fieldId === 'string') {
+    named(node, 'fieldId', 'field', fields)
+    return
+  }
+  if (node.kind === 'observation_property' && typeof node.propertyId === 'string') {
+    named(node, 'propertyId', 'property', properties)
+    return
+  }
+  for (const value of Object.values(node)) nameFieldRefs(value, fields, properties)
+}
+
+/**
+ * An action as the bundle carries it → the portable file.
+ *
+ * The exact inverse of the service's `resolveActionReferences` and
+ * `assignActionIdentity`, and it has to stay that way: `pull` writes what `apply` must
+ * be able to send back. Ids the contract OWNS are stripped, because the service mints
+ * them; ids it REFERENCES become names, because names mean the same thing in every
+ * deployment and ids do not.
+ */
+function actionToFile(action: Record<string, unknown>, names: ActionNames): Record<string, unknown> {
+  const file = structuredClone(action)
+  delete file.id
+
+  if (isRecord(file.subject)) named(file.subject, 'objectTypeId', 'objectType', names.object)
+  if (isRecord(file.effect)) {
+    named(file.effect, 'authoritySourceSystemId', 'authoritySourceSystem', names.sourceSystem)
+    named(file.effect, 'compensationActionId', 'compensationAction', names.action)
+  }
+
+  // The action's own inputs, named before anything can reference them.
+  const inputNames = new Map<string, string>()
+  for (const input of Array.isArray(file.inputs) ? file.inputs : []) {
+    if (!isRecord(input)) continue
+    if (typeof input.id === 'string' && typeof input.apiName === 'string') {
+      inputNames.set(input.id, input.apiName)
+    }
+    delete input.id
+    if (isRecord(input.valueType)) named(input.valueType, 'objectTypeId', 'objectType', names.object)
+  }
+
+  for (const criterion of Array.isArray(file.submissionCriteria) ? file.submissionCriteria : []) {
+    if (!isRecord(criterion)) continue
+    delete criterion.id
+    // Criteria see inputs only — an output does not exist until the action has run.
+    nameFieldRefs(criterion.assertion, inputNames, names.property)
+  }
+
+  for (const outcome of Array.isArray(file.businessOutcomes) ? file.businessOutcomes : []) {
+    if (!isRecord(outcome)) continue
+    // Output fields are scoped to their outcome, exactly as the bundle validates them.
+    const outputNames = new Map<string, string>()
+    for (const field of Array.isArray(outcome.output) ? outcome.output : []) {
+      if (!isRecord(field)) continue
+      if (typeof field.id === 'string' && typeof field.apiName === 'string') {
+        outputNames.set(field.id, field.apiName)
+      }
+      delete field.id
+      if (isRecord(field.valueType)) named(field.valueType, 'objectTypeId', 'objectType', names.object)
+    }
+    const scope = new Map([...inputNames, ...outputNames])
+    for (const change of Array.isArray(outcome.expectedChanges) ? outcome.expectedChanges : []) {
+      if (!isRecord(change)) continue
+      named(change, 'objectTypeId', 'objectType', names.object)
+      named(change, 'propertyId', 'property', names.property)
+      named(change, 'transitionId', 'transition', names.transition)
+      nameFieldRefs(change.value, scope, names.property)
+    }
+    for (const postcondition of Array.isArray(outcome.postconditions) ? outcome.postconditions : []) {
+      if (!isRecord(postcondition)) continue
+      delete postcondition.id
+      nameFieldRefs(postcondition.assertion, scope, names.property)
+    }
+  }
+
+  return file
+}
+
 /**
  * Live draft → the file tree a person edits. Lossless but for the resolved ids.
  *
@@ -184,18 +342,36 @@ export function toFiles(
   const sharedApiNameById = new Map(
     (bundle.sharedProperties ?? []).map((shared) => [shared.id, shared.apiName]),
   )
+  const semanticApiNameById = new Map(
+    (bundle.semanticTypes ?? []).map((semanticType) => [semanticType.id, semanticType.apiName]),
+  )
   const files: AuthoredFile[] = []
   const push = (kind: AuthoredFile['kind'], apiName: string, document: Record<string, unknown>) => {
     files.push({ kind, apiName, path: `${KIND_DIRECTORY[kind]}/${apiName}.yaml`, document })
   }
 
+  for (const semanticType of bundle.semanticTypes ?? []) {
+    // Metadata plus one rule, and no reference of its own: stripping the id is the
+    // whole projection. First, because both carriers name one.
+    push('semantic-type', semanticType.apiName, rest(semanticType, new Set(['id'])))
+  }
   for (const shared of bundle.sharedProperties ?? []) {
-    // A shared field owns no backing and references nothing, so stripping its id
-    // is the whole projection: what is left is portable as it stands.
-    push('shared-field', shared.apiName, rest(shared, new Set(['id'])))
+    // A shared field owns no backing, and the one reference it does carry is a
+    // semantic type — resolved to its apiName here rather than stripped. Stripping
+    // was the likelier leak: this copy took out `id` alone, so the reference would
+    // have travelled into the file as a per-deployment uuid.
+    const semanticType = resolveName(
+      shared.semanticTypeId, semanticApiNameById, 'semantic type', `Shared field "${shared.apiName}"`,
+    )
+    push('shared-field', shared.apiName, {
+      ...rest(shared, new Set(['id', 'semanticTypeId'])),
+      ...(semanticType === undefined ? {} : { semanticType }),
+    })
   }
   for (const object of bundle.objects) {
-    push('object-type', object.apiName, objectToFile(object, sharedApiNameById, datasetNameByRevisionId))
+    push('object-type', object.apiName, objectToFile(
+      object, sharedApiNameById, semanticApiNameById, datasetNameByRevisionId,
+    ))
   }
   for (const link of bundle.relationships) {
     push('link-type', link.apiName, linkToFile(link, objectApiNameById, propertyApiNameById))
@@ -213,6 +389,26 @@ export function toFiles(
     })
   }
 
+  // v1 has no `actions` key at all — see `carriesActions`. An empty array here would
+  // write an `actions/` directory a v1 draft can never accept back.
+  if (bundle.actions) {
+    const names: ActionNames = {
+      object: objectApiNameById,
+      property: propertyApiNameById,
+      transition: new Map(
+        bundle.objects.flatMap((object) => {
+          const lifecycle = (object as { lifecycle?: { transitions?: Array<{ id: string; apiName: string }> } }).lifecycle
+          return (lifecycle?.transitions ?? []).map((entry) => [entry.id, entry.apiName] as const)
+        }),
+      ),
+      sourceSystem: new Map(bundle.sourceSystems.map((entry) => [entry.id, entry.apiName])),
+      action: new Map(bundle.actions.map((entry) => [entry.id, entry.apiName])),
+    }
+    for (const action of bundle.actions) {
+      push('action', action.apiName, actionToFile(action as Record<string, unknown>, names))
+    }
+  }
+
   return { schemaVersion: bundle.schemaVersion, files: files.sort(byPath) }
 }
 

package/src/blueprint/render.ts

@@ -40,10 +40,13 @@ export function renderPlan(plan: Plan, options: { prune: boolean } = { prune: fa
     })
   }
 
+  const withheld = withheldNote(plan)
+
   if (rows.length === 0) {
-    return plan.unchanged === 0
+    const nothing = plan.unchanged === 0
       ? 'No artifacts, and nothing to do.'
       : `No changes. ${plan.unchanged} artifact${plan.unchanged === 1 ? ' matches' : 's match'} the draft.`
+    return withheld ? `${nothing}\n${withheld}` : nothing
   }
 
   const kindWidth = Math.max(...rows.map((row) => row.kind.length))
@@ -55,9 +58,29 @@ export function renderPlan(plan: Plan, options: { prune: boolean } = { prune: fa
   if (plan.unchanged > 0) {
     lines.push(`  = ${plan.unchanged} unchanged`)
   }
+  if (withheld) lines.push(withheld)
   return lines.join('\n')
 }
 
+/**
+ * The prunes a missing directory withheld, and how to mean them.
+ *
+ * Printed on every plan, with or without `--prune`: the withholding is not about the
+ * flag, and a reader who deleted `metrics/` outright needs to know the artifacts are
+ * still live either way.
+ */
+function withheldNote(plan: Plan): string {
+  const withheld = plan.withheld ?? []
+  if (withheld.length === 0) return ''
+  const kinds = [...new Set(withheld.map((operation) => operation.kind))]
+  return withheld
+    .map((operation) => `  · ${operation.kind}  ${operation.apiName}  withheld — this tree has no ${operation.kind}s/ directory`)
+    .join('\n')
+    + `\n    A missing directory means "not modelled here", not "delete these". To mean `
+    + `the delete, keep ${kinds.map((kind) => `${kind}s/`).join(' and ')} in the tree — `
+    + `git needs a .gitkeep to carry an empty one — then re-run with --prune.`
+}
+
 /** The `!` lines: a bound type whose dataset has moved to a different contract. */
 export function renderDrift(
   drift: Array<{ objectApiName: string; datasetName: string; currentDigest: string }>,

package/src/blueprint/scaffold.ts

@@ -1,4 +1,5 @@
-import type { ArtifactKind } from './model'
+import { CliError } from '../errors'
+import { ARTIFACT_KINDS, type ArtifactKind } from './model'
 
 /**
  * A starting file per kind, complete enough to apply as written once the placeholders
@@ -9,7 +10,82 @@ import type { ArtifactKind } from './model'
  * thing they write omits three more. Every field the create route requires is here,
  * including the ones with dull answers.
  */
-export function scaffold(kind: ArtifactKind, apiName: string): Record<string, unknown> {
+
+/**
+ * The semantic-type starting points, each expressible with the facets this slice
+ * ships — no `pattern`, so no uuid or email template pretends to exist.
+ *
+ * A fixed library rather than a prompt: the CLI does not prompt (see `prompt.ts`),
+ * because an agent's stdin is never a TTY and a command that asked would hang. So the
+ * choice is a flag with a deterministic default, and every template writes a rule the
+ * service accepts unedited.
+ */
+export const SEMANTIC_TYPE_TEMPLATES = {
+  /** A quantity that cannot go below zero — the commonest numeric constraint there is. */
+  'non-negative': {
+    dataType: 'number',
+    // Bounds are canonical decimal STRINGS on the wire, not numbers: one spelling per
+    // value, so a rule can be compared as text and `1` and `1.0` cannot both exist.
+    rule: { minimum: '0' },
+  },
+  percentage: {
+    dataType: 'number',
+    rule: { minimum: '0', maximum: '100' },
+  },
+  'status-enum': {
+    dataType: 'string',
+    rule: { enum: ['active', 'inactive'] },
+  },
+  'code-length': {
+    dataType: 'string',
+    rule: { minLength: 1, maxLength: 64 },
+  },
+} as const satisfies Record<string, { dataType: string; rule: Record<string, unknown> }>
+
+export type SemanticTypeTemplate = keyof typeof SEMANTIC_TYPE_TEMPLATES
+
+export const SEMANTIC_TYPE_TEMPLATE_NAMES = Object.keys(
+  SEMANTIC_TYPE_TEMPLATES,
+) as SemanticTypeTemplate[]
+
+/**
+ * What `new semantic-type` writes without `--template`.
+ *
+ * Deliberately NOT inferred from the apiName: a `percentage` that scaffolded a number
+ * and a `percentComplete` that scaffolded a string would be the same command behaving
+ * two ways, and the reader could not tell which they were about to get. One default,
+ * always, and the flag is how the other three are asked for.
+ */
+export const DEFAULT_SEMANTIC_TYPE_TEMPLATE: SemanticTypeTemplate = 'code-length'
+
+export function isSemanticTypeTemplate(value: string): value is SemanticTypeTemplate {
+  return Object.prototype.hasOwnProperty.call(SEMANTIC_TYPE_TEMPLATES, value)
+}
+
+export interface ScaffoldOptions {
+  template?: SemanticTypeTemplate
+}
+
+export function scaffold(
+  kind: ArtifactKind,
+  apiName: string,
+  options: ScaffoldOptions = {},
+): Record<string, unknown> {
+  if (kind === 'semantic-type') {
+    const template = SEMANTIC_TYPE_TEMPLATES[options.template ?? DEFAULT_SEMANTIC_TYPE_TEMPLATE]
+    return {
+      apiName,
+      displayName: apiName,
+      description: 'CHANGE_ME',
+      // The family the rule is read under. The rule objects are kind-free — a number
+      // rule's `{ minimum, maximum }` is the same two keys a date rule uses — so this
+      // is what says which of the four schemas the rule is judged against, and moving
+      // one without the other is refused.
+      dataType: template.dataType,
+      rule: { ...template.rule },
+    }
+  }
+
   if (kind === 'object-type') {
     return {
       apiName,
@@ -64,16 +140,76 @@ export function scaffold(kind: ArtifactKind, apiName: string): Record<string, un
     }
   }
 
-  // A metric names the type it measures and the measures it computes. Both are
-  // required by the create route, so a scaffold without them would contradict this
-  // command's own promise that what it writes validates as written.
-  return {
-    apiName,
-    displayName: apiName,
-    objectType: 'CHANGE_ME',
-    definition: {
-      measures: [{ agg: 'count', label: 'Count' }],
-      dimensions: [],
-    },
+  if (kind === 'action') {
+    // Every reference is a NAME. The service resolves them against the draft and mints
+    // the ids the contract owns, so nothing here carries a uuid — which is exactly
+    // what makes the file applicable to a second deployment.
+    return {
+      apiName,
+      displayName: apiName,
+      description: 'CHANGE_ME',
+      subject: { objectType: 'CHANGE_ME', mode: 'existing' },
+      effect: {
+        kind: 'update',
+        // Named, but note it cannot be authored from this tree: source systems have no
+        // route, and one is synthesised per organization. On a second deployment this
+        // name may resolve to nothing.
+        authoritySourceSystem: 'CHANGE_ME',
+        description: 'CHANGE_ME',
+      },
+      inputs: [],
+      // `min(1)` on the create route: an action that declares no outcome cannot say
+      // what it did, so a scaffold without one would not apply as written.
+      businessOutcomes: [{
+        code: 'applied',
+        displayName: 'Applied',
+        description: 'CHANGE_ME',
+        effect: 'confirmed_applied',
+        expectedChanges: [],
+        postconditions: [],
+        output: [],
+      }],
+      concurrency: { strategy: 'expected_version' },
+      impact: { maxSubjects: 1 },
+      submissionCriteria: [],
+      governance: {
+        // Shaped, not `CHANGE_ME`: this one is validated by
+        // `/^[a-z][a-z0-9_-]{0,63}:[a-z][a-z0-9_-]{0,63}$/`, so a bare placeholder is
+        // the one field in this file that cannot apply as written — and it fails
+        // server-side, after the plan was confirmed.
+        invokeCapability: 'changeme:invoke',
+        approval: { mode: 'none' },
+        reason: 'optional',
+        sensitivity: 'internal',
+      },
+    }
+  }
+
+  if (kind === 'metric') {
+    // A metric names the type it measures and the measures it computes. Both are
+    // required by the create route, so a scaffold without them would contradict this
+    // command's own promise that what it writes validates as written.
+    return {
+      apiName,
+      displayName: apiName,
+      objectType: 'CHANGE_ME',
+      definition: {
+        measures: [{ agg: 'count', label: 'Count' }],
+        dimensions: [],
+      },
+    }
   }
+
+  // NOT a fall-through to the metric arm, which is what stood here. A kind without a
+  // template used to write metric YAML under that kind's directory: the file
+  // validated as nothing, `readTree` accepted it, and the reader found out at `apply`
+  // — three commands later, in someone else's organization.
+  return unhandledKind(kind)
+}
+
+function unhandledKind(kind: never): never {
+  throw new CliError(`"${String(kind)}" has no scaffold.`, {
+    code: 'USAGE',
+    hint: `Expected one of: ${ARTIFACT_KINDS.join(', ')}.`,
+  })
 }