@frontera-sdk/cli 1.52.38 → 1.52.40

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

@@ -0,0 +1,582 @@
+import { API_NAME_RULE, describeApiNameRule, KIND_DIRECTORY, type ArtifactKind } from '../blueprint/model'
+import { BLUEPRINT_DATA_TYPES } from '../blueprint-types'
+
+/**
+ * The Blueprint's file formats (`blueprint/<kind>/<apiName>.yaml`), as JSON
+ * Schema, for `frontera local schema blueprint-<kind>`.
+ *
+ * Only this CLI reads these files: `blueprint apply` turns each into the
+ * service's create body (`blueprint/compile.ts`), and `blueprint pull` and
+ * `blueprint new` write them (`blueprint/projection.ts`, `blueprint/scaffold.ts`).
+ * So the schemas are built from those readers' own rules: the apiName rule per
+ * kind (`API_NAME_RULE`), the value types (`BLUEPRINT_DATA_TYPES`), and the
+ * keys each reader requires. Every reference is a NAME (`objectType: Customer`),
+ * never an id: the tree carries none. What the service checks beyond the shape
+ * (a rule's grammar, an expression) is left open and refused, with its path,
+ * when the file is applied.
+ */
+
+const DRAFT = 'https://json-schema.org/draft/2020-12/schema'
+
+/**
+ * The source system an Action names when it writes the Blueprint's own records:
+ * the service adds it to the draft with the first object type
+ * (`blueprint-draft-catalog.ts`); source systems have no route or file of their own.
+ */
+export const ACTIVE_CATALOG = 'active-catalog'
+
+type JsonSchema = Record<string, unknown>
+
+function apiName(kind: ArtifactKind): JsonSchema {
+  return {
+    type: 'string',
+    pattern: API_NAME_RULE[kind].source,
+    description: `${describeApiNameRule(kind)}. It is the file's name too: blueprint/${KIND_DIRECTORY[kind]}/<apiName>.yaml.`,
+  }
+}
+
+/** A name another file declares, by its apiName. */
+const ref = (what: string, kind: ArtifactKind): JsonSchema => ({ type: 'string', pattern: API_NAME_RULE[kind].source, description: `${what}, by apiName.` })
+
+const text = (description?: string): JsonSchema => ({ type: 'string', minLength: 1, ...(description ? { description } : {}) })
+
+const VALUE_TYPE: JsonSchema = { enum: [...BLUEPRINT_DATA_TYPES], description: 'The value type.' }
+const PROPERTY_TYPE: JsonSchema = {
+  enum: ['attribute', 'measure', 'time'],
+  description: 'How the field is read. `attribute`: a value you filter and group by with equals and in (the default for every field but a date or timestamp). `measure`: a number a metric adds up or averages, compared with lt/gt. `time`: a date or timestamp, the default for one; only a time field can be a metric\'s `timeseries` or be compared in a query or workflow `where` (`dueAt < $now` is refused on an attribute), so never write `attribute` on a date or timestamp you compare or chart over time.',
+}
+const SENSITIVITY: JsonSchema = { enum: ['internal', 'confidential', 'restricted'] }
+const STATUS: JsonSchema = { type: 'string', description: 'Lifecycle status the Blueprint shows (for example active, experimental, deprecated).' }
+const VISIBILITY: JsonSchema = { type: 'string', description: 'Where it is shown (for example normal, prominent, hidden).' }
+
+/** Metadata every artifact may carry. */
+const DISPLAY = {
+  displayName: text('What people see.'),
+  description: { type: 'string' },
+  status: STATUS,
+  visibility: VISIBILITY,
+}
+
+const OBJECT_TYPE: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Blueprint object type (blueprint/object-types/<ApiName>.yaml)',
+  description:
+    'A kind of record, read from a dataset. `frontera blueprint apply` creates it with every property and the column each reads; `primaryKey` and `title` name properties by apiName. `validations` and `lifecycle` cannot be created from a file (the create route has no channel for them).',
+  type: 'object',
+  properties: {
+    apiName: apiName('object-type'),
+    ...DISPLAY,
+    pluralDisplayName: text('The plural people see.'),
+    icon: { type: 'string' },
+    color: { type: 'string' },
+    groups: { type: 'array', items: { type: 'string' } },
+    primaryKey: text('The property that identifies a record, by apiName.'),
+    title: text('The property that names a record, by apiName.'),
+    rowAccess: { anyOf: [{ type: 'string' }, { type: 'null' }], description: 'How rows are restricted, when they are.' },
+    markingsColumn: { anyOf: [{ type: 'string' }, { type: 'null' }], description: 'The column holding each row’s markings; null detaches it.' },
+    governance: {
+      type: 'object',
+      description: 'Ownership and sensitivity. The sensitivity (classification and categories) is applied on create and on update; ownership is set in the Console, and a file whose ownership differs from the draft is refused.',
+      properties: {
+        ownership: { type: 'object', properties: { kind: { type: 'string' }, ownerId: { type: 'string' } } },
+        sensitivity: { type: 'object', properties: { classification: SENSITIVITY, categories: { type: 'array', items: { type: 'string' } } } },
+      },
+    },
+    properties: {
+      type: 'array',
+      minItems: 1,
+      description: 'Every field. Each names the column it reads in backing.mapping.',
+      items: {
+        type: 'object',
+        properties: {
+          apiName: { type: 'string', pattern: '^[a-z][A-Za-z0-9]{0,99}$', description: 'camelCase.' },
+          displayName: text('Defaults to apiName.'),
+          description: { type: 'string', description: 'Sample data reads the values a description lists ("open, pending or closed").' },
+          valueType: VALUE_TYPE,
+          required: { type: 'boolean' },
+          unique: { type: 'boolean' },
+          propertyType: PROPERTY_TYPE,
+          formatConfig: { type: 'object' },
+          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 }.' },
+          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.",
+          },
+        },
+        required: ['apiName'],
+      },
+    },
+    validations: { type: 'array', maxItems: 0, description: 'Must be empty: validations are added in the platform, not from a file.' },
+    backing: {
+      type: 'object',
+      description: 'Where the records come from: the dataset by NAME (its revision is resolved when applied), and one column per property. There is no name-match fallback.',
+      properties: {
+        dataset: text('The dataset’s apiName (datasets/<apiName>.json).'),
+        mapping: {
+          type: 'object',
+          description: 'property apiName → its column, or { column, field } for a field inside a column.',
+          additionalProperties: {
+            anyOf: [
+              { type: 'string', minLength: 1 },
+              { type: 'object', properties: { column: text(), field: { anyOf: [{ type: 'string' }, { type: 'null' }] } }, required: ['column'], additionalProperties: false },
+            ],
+          },
+        },
+        editable: { type: 'array', items: { type: 'string' }, description: 'The properties a governed Action may write.' },
+      },
+      required: ['dataset', 'mapping'],
+    },
+  },
+  required: ['apiName', 'displayName', 'pluralDisplayName', 'primaryKey', 'title', 'properties', 'backing'],
+}
+
+const ENDPOINT: JsonSchema = {
+  type: 'object',
+  properties: {
+    objectType: ref('The object type at this end', 'object-type'),
+    property: text('The property the link joins on, by apiName.'),
+    displayName: text('How this end is named from the other one; defaults to the other type.'),
+    phrase: { type: 'string', description: 'The verb phrase read from this end ("has", "belongs to").' },
+  },
+  required: ['objectType', 'property'],
+}
+
+const LINK_TYPE: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Blueprint link type (blueprint/link-types/<apiName>.yaml)',
+  description:
+    'A relation between two object types, joined on a property of each. For one_to_many and one_to_one the `to` side’s property holds the `from` side’s key; sample data fills it from the other type’s records.',
+  type: 'object',
+  properties: {
+    apiName: apiName('link-type'),
+    description: { type: 'string' },
+    cardinality: { enum: ['one_to_one', 'one_to_many', 'many_to_many'], default: 'one_to_many' },
+    from: ENDPOINT,
+    to: ENDPOINT,
+  },
+  required: ['apiName', 'from', 'to'],
+}
+
+const SHARED_FIELD: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Blueprint shared field (blueprint/shared-fields/<apiName>.yaml)',
+  description: 'What a field means wherever it is used: identity and semantics, no column. An object type’s property implements it with `sharedField: <apiName>`.',
+  type: 'object',
+  properties: {
+    apiName: apiName('shared-field'),
+    ...DISPLAY,
+    valueType: VALUE_TYPE,
+    propertyType: PROPERTY_TYPE,
+    formatConfig: { type: 'object' },
+    semanticType: { anyOf: [ref('The semantic type its values follow', 'semantic-type'), { type: 'null' }] },
+  },
+  required: ['apiName', 'displayName', 'valueType', 'propertyType'],
+}
+
+const SEMANTIC_TYPE: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Blueprint semantic type (blueprint/semantic-types/<apiName>.yaml)',
+  description:
+    'A rule values follow, carried by a property or a shared field (`semanticType: <apiName>`). Sample data generates values within it. Bounds are canonical decimal strings ("0", "100"); the service checks the rule’s grammar when it is applied.',
+  type: 'object',
+  properties: {
+    apiName: apiName('semantic-type'),
+    ...DISPLAY,
+    dataType: { enum: ['string', 'number', 'date', 'timestamp'], description: 'Which family the rule is read under.' },
+    rule: {
+      type: 'object',
+      description: 'string: enum, minLength, maxLength; number, date, timestamp: minimum, maximum.',
+      properties: {
+        enum: { type: 'array', minItems: 1, items: { type: 'string' }, description: 'The allowed values.' },
+        minLength: { type: 'integer', minimum: 0 },
+        maxLength: { type: 'integer', minimum: 0 },
+        minimum: { type: 'string', description: 'A canonical decimal (or date) string.' },
+        maximum: { type: 'string', description: 'A canonical decimal (or date) string.' },
+      },
+    },
+  },
+  required: ['apiName', 'displayName', 'dataType', 'rule'],
+}
+
+/**
+ * A metric takes `displayName` and `description` from `DISPLAY`, not `status` or
+ * `visibility`: the Blueprint keeps neither for a metric (its draft entry has no
+ * such field), so `apply` refuses a file that sets one. Listing them here sent an
+ * agent that followed the schema into that refusal.
+ */
+const METRIC: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Blueprint metric (blueprint/metrics/<apiName>.yaml)',
+  description:
+    'A measure over one object type, carried to the service as written (`objectType` becomes objectTypeApiName). '
+    + 'A metric has no `status` or `visibility`: unlike the other kinds, the Blueprint keeps neither for it, and `apply` refuses a file that sets one.',
+  type: 'object',
+  properties: {
+    apiName: apiName('metric'),
+    displayName: DISPLAY.displayName,
+    description: DISPLAY.description,
+    objectType: ref('The object type it measures', 'object-type'),
+    formatConfig: { type: 'object', description: 'How the numbers are shown.' },
+    definition: {
+      type: 'object',
+      properties: {
+        measures: {
+          type: 'array',
+          minItems: 1,
+          items: {
+            type: 'object',
+            description: 'An aggregate (agg, property, label, filters…) or a composed measure (operands); the service checks the measure grammar when the file is applied.',
+            properties: { agg: { enum: ['sum', 'avg', 'min', 'max', 'count', 'countDistinct', 'share', 'ratio'] }, property: { type: 'string' }, label: text(), apiName: { type: 'string' } },
+          },
+        },
+        dimensions: { type: 'array', items: {} },
+        timeseries: {
+          type: 'string',
+          description: 'The time property the metric is charted over, by apiName (a `time` field). A query by grain, or over a window (`--range P7D`, `--start`/`--end`), reads it. A `--range` window ends at the newest value of it in the data, not at now.',
+        },
+        smallestGrain: { enum: ['day', 'week', 'month', 'quarter', 'year'], description: 'The finest grain the metric is meant to be read at.' },
+      },
+      required: ['measures'],
+    },
+  },
+  required: ['apiName', 'objectType', 'definition'],
+}
+
+/** An Action member's apiName (`apiNameSchema` in the service's Action contract). */
+const MEMBER_NAME = '^[a-z][A-Za-z0-9]{0,99}$'
+/** An outcome's, criterion's or postcondition's code (`stableCodeSchema`). */
+const STABLE_CODE: JsonSchema = { type: 'string', pattern: '^[a-z][a-z0-9_]{0,99}$', description: 'A stable code, lowercase snake_case (`resolution_meaningful`), unique in its list.' }
+
+const WHOLE = { type: 'integer', minimum: 0 }
+
+/** An Action field's value type, one shape per kind; each takes only its own keys. */
+const ACTION_VALUE_TYPE: JsonSchema = {
+  description:
+    'One of: string (minLength, maxLength, pattern, enum), number (integer — required — and minimum, maximum as NUMBERS), boolean, date, timestamp, json, geopoint, or object_reference with `objectType: <ApiName>`. Each kind takes only its own keys. A string `enum` is also what sample data writes into the property the input sets.',
+  oneOf: [
+    {
+      title: 'string',
+      type: 'object',
+      properties: {
+        kind: { const: 'string' },
+        minLength: WHOLE,
+        maxLength: WHOLE,
+        pattern: {
+          type: 'string',
+          pattern: '^\\^.*\\$$',
+          maxLength: 256,
+          description: 'Matches the whole value: starts with ^ and ends with $; characters, character classes and the escapes \\d \\w \\s (and capitals) or an escaped symbol; no groups, alternation or nesting; at most one variable-width repetition (* + ? {m,n}), each at most 64 (`^WO-[0-9A-Z]{4,12}$`).',
+        },
+        enum: { type: 'array', minItems: 1, uniqueItems: true, items: { type: 'string' }, description: 'The allowed values, each once; each must fit minLength, maxLength and pattern.' },
+      },
+      required: ['kind'],
+      additionalProperties: false,
+    },
+    {
+      title: 'number',
+      type: 'object',
+      properties: {
+        kind: { const: 'number' },
+        integer: { type: 'boolean', description: 'Required: true for a whole number, false for any number.' },
+        minimum: { type: 'number', description: 'A number (`minimum: 0`), not a decimal string: decimal strings are a semantic type’s spelling.' },
+        maximum: { type: 'number', description: 'A number, at least minimum.' },
+      },
+      required: ['kind', 'integer'],
+      additionalProperties: false,
+    },
+    ...['boolean', 'date', 'timestamp', 'json', 'geopoint'].map((kind) => ({
+      title: kind,
+      type: 'object',
+      properties: { kind: { const: kind } },
+      required: ['kind'],
+      additionalProperties: false,
+      ...(kind === 'date' ? { description: 'A date, YYYY-MM-DD.' } : kind === 'timestamp' ? { description: 'An ISO 8601 time with a zone: 2026-10-18T09:00:00Z.' } : kind === 'geopoint' ? { description: '{ lat, lon } in decimal degrees; it writes a location field. Takes no default.' } : {}),
+    })),
+    {
+      title: 'object_reference',
+      description: 'A record of the object type: a submission passes the record\'s primary key, as text (`TCH-00026`). Takes no default: only a record\'s UUID fits one, and that is not portable.',
+      type: 'object',
+      properties: { kind: { const: 'object_reference' }, objectType: ref('The object type it points at', 'object-type') },
+      required: ['kind', 'objectType'],
+      additionalProperties: false,
+    },
+  ],
+}
+
+/** An Action's input or output field, by name: the service mints its id. */
+const ACTION_FIELD: JsonSchema = {
+  type: 'object',
+  properties: {
+    apiName: { type: 'string', pattern: MEMBER_NAME, description: 'camelCase. An edit or create on the Blueprint’s records takes the object type’s primary key as a required input of the same name (`id`); with expected_version concurrency it also takes `expectedVersion`.' },
+    displayName: text(),
+    description: text(),
+    valueType: ACTION_VALUE_TYPE,
+    required: { type: 'boolean' },
+    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,
+  },
+  required: ['apiName', 'displayName', 'valueType', 'required', 'sensitivity'],
+  additionalProperties: false,
+}
+
+/** 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.',
+  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 },
+    { title: 'literal', type: 'object', properties: { kind: { const: 'literal' }, value: { type: ['string', 'number', 'boolean', 'null'] } }, required: ['kind', 'value'], additionalProperties: false },
+  ],
+}
+
+const ON_TYPE = ref('The object type it changes (the subject’s, for an edit or create)', 'object-type')
+
+/** One expected change, by kind; each names its object type. */
+const EXPECTED_CHANGE: JsonSchema = {
+  oneOf: [
+    {
+      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 },
+      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: 'lifecycle_transition',
+      type: 'object',
+      properties: { kind: { const: 'lifecycle_transition' }, objectType: ON_TYPE, transition: text('The lifecycle transition, by apiName.') },
+      required: ['kind', 'objectType', 'transition'],
+      additionalProperties: false,
+    },
+  ],
+}
+
+/** A condition over the inputs (and, at approval, the record): an expression tree. */
+const EXPRESSION: JsonSchema = {
+  type: 'object',
+  description:
+    'An expression: { kind: literal, value }, { kind: input, field: <input apiName> }, { kind: observation_property, property: <subject property> }, { kind: principal_attribute, attribute, valueType, whenAbsent }, { kind: principal_has_role, role, whenAbsent }, or { kind: call, operator, args: [expressions] } with operator eq, neq, gt, gte, lt, lte, and, or, not, add, subtract, multiply, divide, concat, coalesce, matches, length. At most 32 levels and 256 nodes. No expression takes a timing: in a postcondition, observation_property reads the record after the change (a postcondition reads only properties its outcome sets); in submission criteria and approval conditions it reads the record as it is when the request is checked.',
+  properties: {
+    kind: { enum: ['literal', 'input', 'observation_property', 'principal_attribute', 'principal_has_role', 'call'] },
+    operator: { enum: ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'and', 'or', 'not', 'add', 'subtract', 'multiply', 'divide', 'concat', 'coalesce', 'matches', 'length'] },
+    args: { type: 'array', items: { type: 'object' } },
+    field: { type: 'string', pattern: MEMBER_NAME },
+    property: { type: 'string' },
+  },
+  required: ['kind'],
+}
+
+const CRITERION: JsonSchema = {
+  type: 'object',
+  properties: {
+    code: STABLE_CODE,
+    message: text('What the person is told when it fails.'),
+    assertion: EXPRESSION,
+  },
+  required: ['code', 'message', 'assertion'],
+  additionalProperties: false,
+}
+
+const APPROVAL: JsonSchema = {
+  type: 'object',
+  description:
+    'none; required { threshold 1–10, separationOfDuties: boolean, policyKey? }; conditional { threshold, separationOfDuties, policyKey }; or chain { separationOfDuties: strict, expiresAfter? ("24h", "3d", at most 7 days), stages: [{ key, when: always | <expression>, approver: { members: true } | { role, scope: subject }, quorum }] } — 1 to 5 steps, run one after another.',
+  properties: {
+    mode: { enum: ['none', 'required', 'conditional', 'chain'] },
+    threshold: { type: 'integer', minimum: 1, maximum: 10 },
+    separationOfDuties: { anyOf: [{ type: 'boolean' }, { const: 'strict' }] },
+    policyKey: { type: 'string', minLength: 1 },
+    expiresAfter: { type: 'string', pattern: '^[1-9][0-9]*[hd]$' },
+    stages: {
+      type: 'array',
+      minItems: 1,
+      maxItems: 5,
+      items: {
+        type: 'object',
+        properties: {
+          key: { type: 'string', description: 'The step’s name, unique in the chain (lowercase snake_case).' },
+          when: { anyOf: [{ const: 'always' }, EXPRESSION], description: '"always", or a condition on the inputs and the record.' },
+          approver: { type: 'object', description: '{ members: true } — any member who may decide Action Requests — or { role: <App role>, scope: subject }.' },
+          quorum: { type: 'integer', minimum: 1, maximum: 10 },
+        },
+        required: ['key', 'when', 'approver', 'quorum'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['mode'],
+}
+
+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. '
+    + '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. '
+    + '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',
+  properties: {
+    apiName: apiName('action'),
+    displayName: text(),
+    description: text(),
+    subject: {
+      type: 'object',
+      properties: { objectType: ref('The object type it acts on', 'object-type'), mode: { enum: ['existing', 'create'], description: 'existing: it changes a record (effect update, delete, transition or command); create: it makes one (effect create).' } },
+      required: ['objectType', 'mode'],
+      additionalProperties: false,
+    },
+    effect: {
+      type: 'object',
+      properties: {
+        kind: { enum: ['create', 'update', 'delete', 'transition', 'command'] },
+        authoritySourceSystem: {
+          type: 'string',
+          minLength: 1,
+          default: ACTIVE_CATALOG,
+          examples: [ACTIVE_CATALOG],
+          description:
+            `The source system with authority over the records, by apiName. An Action that writes the Blueprint's own records names \`${ACTIVE_CATALOG}\`: the source system the service adds to the draft with its first object type, and the one it takes when the key is left out and \`${ACTIVE_CATALOG}\` is the draft's only source system. Source systems have no file or command of their own, so another name is refused.`,
+        },
+        description: text(),
+        compensationAction: { type: 'string', description: 'The Action that undoes it, by apiName.' },
+      },
+      required: ['kind', 'description'],
+      additionalProperties: false,
+    },
+    inputs: { type: 'array', items: ACTION_FIELD },
+    businessOutcomes: {
+      type: 'array',
+      minItems: 1,
+      items: {
+        type: 'object',
+        properties: {
+          code: STABLE_CODE,
+          displayName: text(),
+          description: text(),
+          effect: { enum: ['confirmed_applied', 'confirmed_not_applied'] },
+          expectedChanges: { type: 'array', description: 'What it changes; none for confirmed_not_applied.', items: EXPECTED_CHANGE },
+          postconditions: { type: 'array', items: CRITERION },
+          output: { type: 'array', items: ACTION_FIELD },
+        },
+        required: ['code', 'displayName', 'description', 'effect', 'expectedChanges', 'postconditions', 'output'],
+        additionalProperties: false,
+      },
+    },
+    concurrency: {
+      type: 'object',
+      properties: {
+        strategy: { enum: ['expected_version', 'create_if_absent', 'append_once'], description: 'expected_version for an existing subject; append_once for a create on the Blueprint’s records (create_if_absent does not deploy there).' },
+        openRequests: {
+          enum: ['one_per_subject'],
+          description:
+            'one_per_subject: a record has at most one open request of this Action from the same requester; another submit is refused with ACTION_REQUEST_ALREADY_OPEN (the CLI exits 3), naming the open request in details.openRequest. Only with subject.mode existing. A workflow sweep that may meet it gives the step continueOnError: true and branches on $steps.<id>.error.code.',
+        },
+      },
+      required: ['strategy'],
+      additionalProperties: false,
+    },
+    impact: { type: 'object', properties: { maxSubjects: { const: 1 } }, required: ['maxSubjects'], additionalProperties: false },
+    submissionCriteria: { type: 'array', items: CRITERION, description: 'Conditions every submission must meet, checked before it is accepted.' },
+    governance: {
+      type: 'object',
+      properties: {
+        invokeCapability: { type: 'string', pattern: '^[a-z][a-z0-9_-]{0,63}:[a-z][a-z0-9_-]{0,63}$', description: 'resource:action — the capability a role needs to run it.' },
+        approval: APPROVAL,
+        reason: { enum: ['required', 'optional'] },
+        sensitivity: SENSITIVITY,
+      },
+      required: ['invokeCapability', 'approval', 'reason', 'sensitivity'],
+      additionalProperties: false,
+    },
+  },
+  required: ['apiName', 'displayName', 'description', 'subject', 'effect', 'inputs', 'businessOutcomes', 'concurrency', 'impact', 'submissionCriteria', 'governance'],
+}
+
+/** One object set expression, as the Blueprint's query reads it (`query/expression.ts` in the service). */
+const OBJECT_SET_EXPR: JsonSchema = {
+  type: 'object',
+  description:
+    'base { objectType }; filter { objectSet, where }; searchAround { objectSet, link }; union, intersect, subtract { objectSets: [...] }; static { objectType, pks }; reference { objectSetId: `objectSet/<name>` } — another saved set, by its name as people say it (`objectSet/Open work orders`) or its file name. The service checks the expression when the set is saved.',
+  properties: {
+    type: { enum: ['base', 'filter', 'searchAround', 'union', 'intersect', 'subtract', 'static', 'reference'] },
+    objectType: ref('base, static: the object type', 'object-type'),
+    objectSet: { type: 'object', description: 'filter, searchAround: the set it narrows or walks from (an expression).' },
+    where: { type: 'object', description: 'filter: a condition ({ property, op, value | values }, or { and | or: [...] }, { not }).' },
+    link: { type: 'string', description: 'searchAround: the link type to walk, by apiName.' },
+    objectSets: { type: 'array', items: { type: 'object' }, description: 'union, intersect, subtract: the sets combined.' },
+    pks: { type: 'array', items: { type: ['string', 'number'] } },
+    objectSetId: { type: 'string', description: 'reference: `objectSet/<name>`, resolved to this runtime’s id when the set is saved.' },
+  },
+  required: ['type'],
+}
+
+const OBJECT_SET: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Blueprint saved object set (blueprint/object-sets/<name>.yaml)',
+  description:
+    'A named set of one object type’s records that workflows, Agents and Apps reuse: dynamic (a definition, re-evaluated on every read) or static (a fixed list of primary keys). `frontera local dev` saves each file on the local runtime once the Blueprint is published there, so a reset brings it back. Other files name it `objectSet/<name>`, where the name is the set’s `name` (spaces allowed: `objectSet/Open work orders`) or the file’s name (`objectSet/open-work-orders`).',
+  type: 'object',
+  properties: {
+    name: text('What people call it ("Open work orders"); the file’s name when absent.'),
+    description: { type: 'string' },
+    objectType: ref('The object type its records are', 'object-type'),
+    kind: { enum: ['dynamic', 'static'], default: 'dynamic' },
+    definition: { ...OBJECT_SET_EXPR, description: `dynamic: the expression the set reads. ${String(OBJECT_SET_EXPR.description)}` },
+    records: { type: 'array', minItems: 1, items: { type: ['string', 'number'] }, description: 'static: the primary keys of the records it lists.' },
+  },
+  required: ['objectType'],
+  additionalProperties: false,
+}
+
+const WORKSPACE_GRANTS: JsonSchema = {
+  $schema: DRAFT,
+  title: 'Workspace grants beyond read (blueprint/workspace-grants.yaml)',
+  description:
+    "What the workspace itself (its workflows, Functions and Apps, which read through the workspace rather than as an Agent) may read of an object type beyond plain read: `read_sensitive` is clearance over the type's confidential and restricted fields. `frontera local dev` grants every object type `read` and then these, after each Blueprint publish. An Agent's own clearance is `read_sensitive` in its bindings.json. `frontera local sync pull` writes the file when the workspace holds read_sensitive on a type (none: no file), and `frontera local sync push` proposes a change to it in a change request: each type listed gets the listed permissions when it is applied, a type left out keeps its grant. Deleting the file changes no grant and is not proposed: to take read_sensitive away, list the type with `permissions: [read]`.",
+  type: 'object',
+  properties: {
+    grants: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          objectType: { type: 'string', pattern: '^(objectType/)?[A-Z][A-Za-z0-9]*$', description: 'The object type, as objectType/<ApiName>.' },
+          permissions: { type: 'array', items: { enum: ['read', 'read_sensitive'] }, description: '`read` is always included; `read_sensitive` is the only other permission.' },
+        },
+        required: ['objectType', 'permissions'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['grants'],
+  additionalProperties: false,
+}
+
+export const BLUEPRINT_SCHEMAS = {
+  'blueprint-object-type': OBJECT_TYPE,
+  'blueprint-link-type': LINK_TYPE,
+  'blueprint-shared-field': SHARED_FIELD,
+  'blueprint-semantic-type': SEMANTIC_TYPE,
+  'blueprint-metric': METRIC,
+  'blueprint-action': ACTION,
+  'blueprint-object-set': OBJECT_SET,
+  'blueprint-workspace-grants': WORKSPACE_GRANTS,
+} as const satisfies Record<string, JsonSchema>
+
+export const BLUEPRINT_SCHEMA_FILES: Record<keyof typeof BLUEPRINT_SCHEMAS, string> = {
+  'blueprint-object-type': 'blueprint/object-types/<ApiName>.yaml',
+  'blueprint-link-type': 'blueprint/link-types/<apiName>.yaml',
+  'blueprint-shared-field': 'blueprint/shared-fields/<apiName>.yaml',
+  'blueprint-semantic-type': 'blueprint/semantic-types/<apiName>.yaml',
+  'blueprint-metric': 'blueprint/metrics/<apiName>.yaml',
+  'blueprint-action': 'blueprint/actions/<apiName>.yaml',
+  'blueprint-object-set': 'blueprint/object-sets/<name>.yaml',
+  'blueprint-workspace-grants': 'blueprint/workspace-grants.yaml',
+}

package/src/local/local-build-inputs.ts

@@ -0,0 +1,48 @@
+import { liveActionStates, localActionCalls, type LiveAction } from './local-actions'
+import { liveAppDeployments, workspaceGet, type LiveApp } from './local-app-runtime'
+import { projectBuildRows, projectBuildSummary, type BuildRow, type ProjectBuildSummary } from './local-build-summary'
+import { localSecretPresence, type SecretPresence } from './local-secrets'
+import { isAlive, type LocalState } from './local-state'
+
+/**
+ * What the build is counted with besides the project's files, read from the
+ * running runtime: each governed Action's deployment (where `frontera action
+ * list` reads it) and the secrets it holds (names, and whether each has a
+ * value; never a value). `local status` and Studio's build summary read them
+ * the same way, so their counts agree. Both null while the runtime is not
+ * running or does not answer: the last build's record speaks then.
+ */
+export interface RuntimeBuildInputs {
+  live: Map<string, LiveAction> | null
+  secrets: SecretPresence | null
+  /** Whether the runtime has each Custom App's deployment, by App folder name (`local-app-runtime.ts`). */
+  apps?: Map<string, LiveApp> | null
+}
+
+export async function runtimeBuildInputs(state: LocalState | null, root?: string): Promise<RuntimeBuildInputs> {
+  if (!state?.credentials || state.phase !== 'ready' || !state.supervisorPid || !isAlive(state.supervisorPid)) return { live: null, secrets: null, apps: null }
+  const serviceUrl = `http://127.0.0.1:${state.ports.service}`
+  const creds = state.credentials
+  const [live, secrets, apps] = await Promise.all([
+    creds.orgKey ? Promise.resolve().then(() => liveActionStates(localActionCalls(serviceUrl, creds))).catch(() => null) : Promise.resolve(null),
+    localSecretPresence(serviceUrl, creds).catch(() => null),
+    root ? liveAppDeployments(root, workspaceGet(serviceUrl, creds)).catch(() => null) : Promise.resolve(null),
+  ])
+  return { live, secrets, apps }
+}
+
+/**
+ * The build summary as `local status` counts it, with the runtime read the
+ * same way: what Studio's sidebar says ("5 items failed to apply") is the
+ * failed count `local status` prints.
+ */
+/** The build's rows as `local status --json` lists them, with the runtime read the same way: Studio's lists mark each from them. */
+export async function currentBuildRows(root: string, id: string, state: LocalState | null, read: (state: LocalState | null, root?: string) => Promise<RuntimeBuildInputs> = runtimeBuildInputs): Promise<BuildRow[] | null> {
+  const { live, secrets, apps } = await read(state, root)
+  return projectBuildRows(root, id, live, null, secrets, apps ?? null)
+}
+
+export async function currentBuildSummary(root: string, id: string, state: LocalState | null, read: (state: LocalState | null, root?: string) => Promise<RuntimeBuildInputs> = runtimeBuildInputs): Promise<ProjectBuildSummary | null> {
+  const { live, secrets, apps } = await read(state, root)
+  return projectBuildSummary(root, id, live, secrets, apps ?? null)
+}