@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/blueprint/action-semantic-fit.ts

@@ -0,0 +1,205 @@
+/**
+ * An Action's expected changes against the semantic types of the properties
+ * they set, from the Blueprint's files: a port of the service's rule
+ * (`action-semantic-fit.ts`, with `effective-semantic-type.ts` and
+ * `semantic-type-rule.ts`), which the Action draft route applies when an Action
+ * is saved, and so the local runtime applies when `local dev` writes a pulled
+ * Action. Found here, a pull can say an Action won't run locally before
+ * anything is applied, and `blueprint plan` can say so before a write.
+ *
+ * The same certainty as the service: only an input's declared `enum` members
+ * (and its `default`) the type does not allow, and a literal it does not
+ * allow. A free-text input onto a constrained property may still be given a
+ * good value, and is left to the edit gate. Never stricter than the service:
+ * where a value's reading is in doubt (a number this port cannot read
+ * exactly), it is not a conflict.
+ */
+
+type Doc = Record<string, unknown>
+
+const isRecord = (v: unknown): v is Doc => !!v && typeof v === 'object' && !Array.isArray(v)
+const list = (v: unknown): Doc[] => (Array.isArray(v) ? v.filter(isRecord) : [])
+
+/** A semantic type as its file states it: `semantic-types/<apiName>.yaml`. */
+export interface SemanticTypeFact {
+  apiName: string
+  dataType: string
+  rule: Doc
+}
+
+/** What the rule needs from the Blueprint's files, by apiName. */
+export interface SemanticFacts {
+  semanticTypes: ReadonlyMap<string, SemanticTypeFact>
+  /** Shared field → the semantic type it carries (null: none). */
+  sharedFields: ReadonlyMap<string, string | null>
+  /** Object type → property → what governs its meaning. */
+  objectTypes: ReadonlyMap<string, ReadonlyMap<string, { semanticType?: string | null; sharedField?: string | null }>>
+}
+
+/** One Blueprint file: its path under `blueprint/` or the tree root, and its parsed document. */
+export interface BlueprintDoc {
+  path: string
+  document: Doc
+}
+
+/** The facts from a Blueprint's files (`semantic-types/`, `shared-fields/`, `object-types/`, with or without a `blueprint/` prefix). */
+export function semanticFactsOf(files: Iterable<BlueprintDoc>): SemanticFacts {
+  const semanticTypes = new Map<string, SemanticTypeFact>()
+  const sharedFields = new Map<string, string | null>()
+  const objectTypes = new Map<string, Map<string, { semanticType?: string | null; sharedField?: string | null }>>()
+  for (const { path, document: doc } of files) {
+    const at = path.replace(/^blueprint\//, '')
+    const apiName = typeof doc.apiName === 'string' ? doc.apiName : null
+    if (!apiName) continue
+    if (at.startsWith('semantic-types/') && typeof doc.dataType === 'string' && isRecord(doc.rule)) {
+      semanticTypes.set(apiName, { apiName, dataType: doc.dataType, rule: doc.rule })
+    } else if (at.startsWith('shared-fields/')) {
+      sharedFields.set(apiName, typeof doc.semanticType === 'string' ? doc.semanticType : null)
+    } else if (at.startsWith('object-types/')) {
+      const props = new Map<string, { semanticType?: string | null; sharedField?: string | null }>()
+      for (const p of list(doc.properties)) {
+        if (typeof p.apiName !== 'string') continue
+        props.set(p.apiName, {
+          ...(typeof p.semanticType === 'string' ? { semanticType: p.semanticType } : {}),
+          ...(typeof p.sharedField === 'string' ? { sharedField: p.sharedField } : {}),
+        })
+      }
+      objectTypes.set(apiName, props)
+    }
+  }
+  return { semanticTypes, sharedFields, objectTypes }
+}
+
+/**
+ * The semantic type governing one property. The shared field wins outright
+ * while one is implemented, including when it carries none: a shared field
+ * owns its implementers' meaning (the service's `resolveEffectiveSemanticTypes`).
+ */
+export function effectiveSemanticType(facts: SemanticFacts, objectType: string, property: string): SemanticTypeFact | null {
+  const p = facts.objectTypes.get(objectType)?.get(property)
+  if (!p) return null
+  const name = p.sharedField ? (facts.sharedFields.get(p.sharedField) ?? null) : (p.semanticType ?? null)
+  return name ? (facts.semanticTypes.get(name) ?? null) : null
+}
+
+/** A number as a JavaScript number when it reads as one exactly enough to compare; null otherwise. */
+function numberOf(v: unknown): number | null {
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null
+  if (typeof v === 'string' && /^[+-]?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(v.trim())) {
+    const n = Number(v)
+    return Number.isFinite(n) ? n : null
+  }
+  return null
+}
+
+/** Whether a value satisfies the type's rule; `true` where this port can't be sure it doesn't. */
+export function matchesSemanticRule(type: SemanticTypeFact, value: unknown): boolean {
+  if (value === null || value === undefined) return true
+  const rule = type.rule
+  switch (type.dataType) {
+    case 'string': {
+      if (typeof value !== 'string') return false
+      const normalized = value.normalize('NFC')
+      const length = [...normalized].length
+      if (typeof rule.minLength === 'number' && length < rule.minLength) return false
+      if (typeof rule.maxLength === 'number' && length > rule.maxLength) return false
+      if (Array.isArray(rule.enum) && !rule.enum.map(String).includes(normalized)) return false
+      return true
+    }
+    case 'number': {
+      if (typeof value === 'boolean') return false
+      const n = numberOf(value)
+      // Beyond what a double reads exactly: the service compares decimals exactly; don't guess.
+      if (n === null || !Number.isSafeInteger(Math.trunc(n))) return true
+      if (rule.integer === true && !Number.isInteger(n)) return false
+      const min = numberOf(rule.minimum)
+      const max = numberOf(rule.maximum)
+      if (min !== null && n < min) return false
+      if (max !== null && n > max) return false
+      if (Array.isArray(rule.enum)) {
+        const members = rule.enum.map(numberOf)
+        if (members.some((m) => m === null)) return true
+        if (!members.includes(n)) return false
+      }
+      return true
+    }
+    case 'date': {
+      if (typeof value !== 'string') return false
+      const date = /^\d{4}-\d{2}-\d{2}$/.test(value) ? value : Number.isNaN(Date.parse(value)) ? null : new Date(Date.parse(value)).toISOString().slice(0, 10)
+      if (date === null) return false
+      if (typeof rule.minimum === 'string' && date < rule.minimum) return false
+      if (typeof rule.maximum === 'string' && date > rule.maximum) return false
+      return true
+    }
+    case 'timestamp': {
+      if (typeof value !== 'string') return false
+      const t = Date.parse(value)
+      if (Number.isNaN(t)) return false
+      if (typeof rule.minimum === 'string' && !Number.isNaN(Date.parse(rule.minimum)) && t < Date.parse(rule.minimum)) return false
+      if (typeof rule.maximum === 'string' && !Number.isNaN(Date.parse(rule.maximum)) && t > Date.parse(rule.maximum)) return false
+      return true
+    }
+  }
+  return true
+}
+
+export interface ActionSemanticConflict {
+  /** Where in the Action file (`businessOutcomes[0].expectedChanges[2].value`). */
+  path: string
+  message: string
+  /**
+   * The Blueprint files the conflict rests on besides the Action's own, as a
+   * pull's lock names them (`blueprint/object-types/Escalation`,
+   * `blueprint/semantic-types/escalationSeverityValues`, and the shared field
+   * when the type comes through one): with the Action, unchanged since the
+   * pull, the conflict is the workspace's (`inheritedFromPull`).
+   */
+  refs: string[]
+}
+
+/**
+ * Each expected change whose value the property's semantic type refuses, in
+ * the service's words. `subject` is the Action's own object type, for a change
+ * that names none.
+ */
+export function actionSemanticConflicts(action: Doc, facts: SemanticFacts): ActionSemanticConflict[] {
+  const inputs = new Map(list(action.inputs).flatMap((f) => (typeof f.apiName === 'string' ? [[f.apiName, f] as const] : [])))
+  const subject = isRecord(action.subject) && typeof action.subject.objectType === 'string' ? action.subject.objectType : null
+  const out: ActionSemanticConflict[] = []
+  list(action.businessOutcomes).forEach((outcome, i) => {
+    list(outcome.expectedChanges).forEach((change, j) => {
+      if (change.kind !== 'property_set' || !isRecord(change.value) || typeof change.property !== 'string') return
+      const objectType = typeof change.objectType === 'string' ? change.objectType : subject
+      if (!objectType) return
+      const type = effectiveSemanticType(facts, objectType, change.property)
+      if (!type) return
+      const target = `${objectType}.${change.property}`
+      const sharedField = facts.objectTypes.get(objectType)?.get(change.property)?.sharedField
+      const refs = [`blueprint/object-types/${objectType}`, ...(sharedField ? [`blueprint/shared-fields/${sharedField}`] : []), `blueprint/semantic-types/${type.apiName}`]
+      const allows = type.dataType === 'string' && Array.isArray(type.rule.enum) ? ` (${type.rule.enum.map(String).join(', ')})` : ''
+      const path = `businessOutcomes[${i}].expectedChanges[${j}].value`
+      const refused = (v: unknown) => !matchesSemanticRule(type, v)
+      const value = change.value
+      if (value.kind === 'literal') {
+        if (refused(value.value)) {
+          out.push({ path, refs, message: `${target} takes only what its semantic type "${type.apiName}" allows${allows}, and ${JSON.stringify(value.value)} is not one of them, so every request of it is refused when it is submitted.` })
+        }
+        return
+      }
+      if (value.kind !== 'input' || typeof value.field !== 'string') return
+      const input = inputs.get(value.field)
+      if (!input) return
+      const valueType = isRecord(input.valueType) ? input.valueType : {}
+      const declared = Array.isArray(valueType.enum) ? valueType.enum : null
+      const candidates = [...(declared ?? []), ...(Object.prototype.hasOwnProperty.call(input, 'default') ? [input.default] : [])]
+      const outside = [...new Set(candidates.filter(refused).map((v) => JSON.stringify(v)))]
+      if (!outside.length) return
+      out.push({
+        path,
+        refs,
+        message: `Input "${value.field}" can be ${outside.join(', ')}, which ${target} refuses: it takes only what its semantic type "${type.apiName}" allows${allows}. A request with ${outside.length === 1 ? 'that value' : 'those values'} is refused when it is submitted; give the input only values the type allows.`,
+      })
+    })
+  })
+  return out
+}

package/src/blueprint/compile.ts

@@ -161,6 +161,8 @@ export function resolveSemanticType(
 export interface AuthoringIds {
   sharedPropertyIdByApiName: Map<string, string>
   semanticTypeIdByApiName: Map<string, string>
+  /** Shared field apiName → its `propertyType`, which an implementer that states none takes. */
+  sharedPropertyTypeByApiName?: Map<string, string>
 }
 
 function columnOf(entry: string | { column: string; field?: string | null }): {
@@ -210,7 +212,9 @@ export async function objectTypeCreateBody(
   }
 
   const { revisionId } = await resolveDataset(backing.dataset)
-  const properties = Array.isArray(document.properties) ? document.properties : []
+  // A calculated field (a location from latitude and longitude) reads no column, and the
+  // create route has no channel for it: it is added after the type, by `add_field`.
+  const properties = (Array.isArray(document.properties) ? document.properties : []).filter((entry) => !(entry as { calculation?: unknown }).calculation)
 
   return {
     apiName: requireString(document, 'apiName', file.path),
@@ -228,6 +232,8 @@ export async function objectTypeCreateBody(
     // nothing to carry here — a create has no column to clear.
     ...optional((document.rowAccess as string | null | undefined) ?? undefined, 'rowAccess'),
     ...optional((document.markingsColumn as string | null | undefined) ?? undefined, 'markingsColumn'),
+    // Classified at creation: a PII type is never created as `internal` first.
+    ...optional(objectTypeSensitivity(document), 'sensitivity'),
     datasetRevisionId: revisionId,
     properties: properties.map((entry) => {
       const property = entry as Record<string, unknown>
@@ -258,7 +264,7 @@ export async function objectTypeCreateBody(
         apiName,
         displayName: String(property.displayName ?? apiName),
         ...optional(property.description as string | undefined, 'description'),
-        propertyType: (property.propertyType as string | undefined) ?? 'attribute',
+        propertyType: declaredPropertyType(property, ids.sharedPropertyTypeByApiName),
         dataType: String(property.valueType ?? 'string'),
         column,
         ...(field === undefined || field === null ? {} : { field }),
@@ -271,6 +277,8 @@ export async function objectTypeCreateBody(
         // Same three-state collapse as the shared field beside it: a CREATE has
         // nothing to detach from, and the create body's uuid is not nullable.
         ...(typeof semanticTypeId === 'string' ? { semanticTypeId } : {}),
+        // The field's own classification, when the file gives one other than its object type's.
+        ...fieldSensitivityOf(property, objectTypeSensitivity(document)),
       }
     }),
     columnMappings: Object.entries(backing.mapping).map(([propertyApiName, entry]) => {
@@ -283,6 +291,29 @@ export async function objectTypeCreateBody(
   }
 }
 
+/**
+ * A field's own classification as its file states it (`sensitivity` on the
+ * property), or nothing: absent, `null`, or the same as its object type's
+ * classification, the field takes the object type's. Writing the object's own
+ * value would pin it, and a draft read could not tell the two apart.
+ */
+export function fieldSensitivityOf(property: Record<string, unknown>, objectSensitivity: unknown): { sensitivity?: string } {
+  const own = property.sensitivity
+  const objectClass = objectSensitivity && typeof objectSensitivity === 'object' ? (objectSensitivity as { classification?: unknown }).classification : undefined
+  return typeof own === 'string' && own !== objectClass ? { sensitivity: own } : {}
+}
+
+/**
+ * An object type's classification as its file states it: `governance.sensitivity`
+ * (as a pull writes it), else a top-level `sensitivity`. The create and update
+ * routes take it as a top-level `sensitivity: { classification, categories }`.
+ */
+export function objectTypeSensitivity(document: Record<string, unknown>): Record<string, unknown> | undefined {
+  const governance = document.governance as { sensitivity?: unknown } | undefined
+  const value = governance && typeof governance === 'object' && governance.sensitivity !== undefined ? governance.sensitivity : document.sensitivity
+  return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined
+}
+
 /** `PUT /object-types/:apiName` takes metadata only — fields move by draft command. */
 export function objectTypePatchBody(
   file: AuthoredFile,
@@ -396,6 +427,24 @@ export function metricCreateBody(
  * and invisible afterwards, because the next `pull` strips it again while contract
  * digests and binding rows keep keying off it.
  */
+/**
+ * How a new field is read when its file does not say: a date or timestamp is a
+ * `time` property (so a metric can take it as its timeseries and a `where` can
+ * compare it), anything else an `attribute`. A field that implements a shared
+ * field without its own `propertyType` stays `attribute`, as before: the shared
+ * field's own type is the draft's to say. Only a field being created takes the
+ * default; a field already on the draft keeps what it has unless the file says
+ * otherwise (`planProperties` changes only what a file states).
+ */
+export function declaredPropertyType(property: Record<string, unknown>, sharedPropertyTypes?: ReadonlyMap<string, string>): string {
+  if (typeof property.propertyType === 'string') return property.propertyType
+  // An implementer takes its shared field's type, as the service does when the body leaves it out.
+  if (property.sharedField !== undefined && property.sharedField !== null) {
+    return (typeof property.sharedField === 'string' && sharedPropertyTypes?.get(property.sharedField)) || 'attribute'
+  }
+  return property.valueType === 'timestamp' || property.valueType === 'date' ? 'time' : 'attribute'
+}
+
 export function actionWithoutMintedIds(document: Record<string, unknown>): Record<string, unknown> {
   const drop = (value: unknown): unknown => {
     if (Array.isArray(value)) return value.map(drop)

package/src/blueprint/diff.ts

@@ -1,5 +1,5 @@
 import { actionWithoutMintedIds } from './compile'
-import { toFiles } from './projection'
+import { toFiles, withoutImpliedTiming } from './projection'
 import {
   ARTIFACT_KINDS,
   type ArtifactKind,
@@ -182,13 +182,45 @@ function matches(
   local: Record<string, unknown>,
   live: Record<string, unknown>,
 ): boolean {
+  if (kind === 'object-type') return objectTypeMatches(local, live)
   if (kind !== 'action') return satisfies(local, live)
   // Compared against what `apply` will actually SEND, which is the file minus every id
   // the service mints. The live side is the projection, which already strips them — so
   // comparing the raw file made a pasted export differ forever, on ids neither side
   // could ever agree about.
+  // A postcondition's implied `timing: after` is the same Action written or not (`withoutImpliedTiming`).
   const authored = actionWithoutMintedIds(local)
-  return satisfies(authored, live) && satisfies(live, authored)
+  for (const outcome of Array.isArray(authored.businessOutcomes) ? authored.businessOutcomes : []) {
+    for (const pc of Array.isArray((outcome as { postconditions?: unknown })?.postconditions) ? (outcome as { postconditions: unknown[] }).postconditions : []) withoutImpliedTiming((pc as { assertion?: unknown })?.assertion)
+  }
+  const stored = structuredClone(live)
+  for (const outcome of Array.isArray(stored.businessOutcomes) ? stored.businessOutcomes : []) {
+    for (const pc of Array.isArray((outcome as { postconditions?: unknown })?.postconditions) ? (outcome as { postconditions: unknown[] }).postconditions : []) withoutImpliedTiming((pc as { assertion?: unknown })?.assertion)
+  }
+  return satisfies(authored, stored) && satisfies(stored, authored)
+}
+
+/**
+ * An object type's file against its live projection, with each field's own
+ * classification compared both ways: a file that leaves a field's
+ * `sensitivity` out (or gives its object type's) means "takes the object's",
+ * so a live field holding its own differs from it, and the projection writes
+ * a field at its object's value without one.
+ */
+function objectTypeMatches(local: Record<string, unknown>, live: Record<string, unknown>): boolean {
+  const classOf = (doc: Record<string, unknown>) => ((doc.governance as { sensitivity?: { classification?: unknown } } | undefined)?.sensitivity ?? (doc.sensitivity as { classification?: unknown } | undefined))?.classification
+  const objectClass = classOf(local)
+  const own = (doc: Record<string, unknown>, cls: unknown) => new Map(
+    (Array.isArray(doc.properties) ? (doc.properties as Array<Record<string, unknown>>) : [])
+      .filter((p) => typeof p.apiName === 'string' && !p.calculation)
+      .map((p) => [p.apiName as string, typeof p.sensitivity === 'string' && p.sensitivity !== cls ? p.sensitivity : null] as const),
+  )
+  const authored = structuredClone(local)
+  for (const p of Array.isArray(authored.properties) ? (authored.properties as Array<Record<string, unknown>>) : []) delete p.sensitivity
+  if (!satisfies(authored, live)) return false
+  const wanted = own(local, objectClass)
+  const held = own(live, classOf(live))
+  return [...wanted].every(([name, value]) => !held.has(name) || held.get(name) === value)
 }
 
 export function diff(

package/src/blueprint/metric-query.ts

@@ -0,0 +1,215 @@
+/**
+ * A Blueprint metric query, as `frontera blueprint metric query` and the MCP
+ * `blueprint_query_metric` send it to `POST /v1/blueprint/metrics/:apiName/query`
+ * (the route an App's `useMetric` and an Agent's `blueprint_query_metric` use).
+ *
+ * Every part is optional: the metric's measures (all when absent), the
+ * dimensions to group by, a time window (an ISO duration back from the newest
+ * record, or a start and an end), a grain for a series (the metric's timeseries
+ * dimension is added to the dimensions, which the service requires), and a
+ * comparison with the window before.
+ *
+ * A duration window does NOT end at now. The service anchors it on the
+ * WATERMARK, the newest value of the metric's timeseries in the data
+ * (`timeFilter` in the service's `metric-sql.ts`: `col > max(col) - P7D AND
+ * col <= max(col)`), so a "last 7 days" number keeps its data when a load runs
+ * behind. `resolveRangeWindow` reads that watermark so a caller can be shown the
+ * window it got.
+ */
+
+export const METRIC_GRAINS = ['hour', 'day', 'week', 'month', 'quarter', 'year'] as const
+export type MetricGrain = (typeof METRIC_GRAINS)[number]
+
+export interface MetricQueryOptions {
+  measures?: string[]
+  dimensions?: string[]
+  grain?: string
+  /** An ISO-8601 duration back from the newest record (see the header): P7D, PT12H, P3M. */
+  range?: string
+  from?: string
+  to?: string
+  compare?: boolean | { start: string; end: string }
+}
+
+export interface MetricQueryBody {
+  measures?: string[]
+  dimensions?: string[]
+  grain?: MetricGrain
+  timeRange?: { isoDuration?: string; start?: string; end?: string }
+  compare?: true | { start: string; end: string }
+}
+
+/** What the route answers: rows keyed by dimension and measure names. */
+export interface MetricQueryResult {
+  data?: Array<Record<string, unknown>>
+  rows?: Array<Record<string, unknown>>
+  truncated?: boolean
+  compareWindow?: unknown
+}
+
+const ISO_DURATION = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+(\.\d+)?S)?)?$/
+
+/** A full ISO timestamp: a bare date is read as its midnight UTC (the query engine refuses a date alone). */
+export function fullTimestamp(raw: string, what: string): string {
+  const text = raw.trim()
+  const value = /^\d{4}-\d{2}-\d{2}$/.test(text) ? `${text}T00:00:00Z` : text
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/.test(value) || Number.isNaN(Date.parse(value))) {
+    throw new Error(`${what} must be an ISO date or timestamp, e.g. 2026-10-01 or 2026-10-01T00:00:00Z (not "${raw}")`)
+  }
+  return value
+}
+
+const names = (list: string[] | undefined) => [...new Set((list ?? []).map((s) => s.trim()).filter(Boolean))]
+
+/**
+ * The request body for the options; throws an Error that says what to change.
+ * `timeseries` is the metric's timeseries dimension (null when it has none,
+ * undefined when it could not be read): a grain adds it to the dimensions.
+ */
+export function metricQueryBody(opts: MetricQueryOptions, timeseries: string | null | undefined): MetricQueryBody {
+  const body: MetricQueryBody = {}
+  const measures = names(opts.measures)
+  if (measures.length) body.measures = measures
+  const dimensions = names(opts.dimensions)
+  if (opts.grain !== undefined) {
+    if (!(METRIC_GRAINS as readonly string[]).includes(opts.grain)) throw new Error(`grain must be one of ${METRIC_GRAINS.join(', ')} (not "${opts.grain}")`)
+    if (timeseries === null) throw new Error('this metric has no timeseries dimension, so it has no series by grain: leave the grain out, or give the metric `timeseries:` in its file')
+    if (timeseries && !dimensions.includes(timeseries)) dimensions.push(timeseries)
+    body.grain = opts.grain as MetricGrain
+  }
+  if (dimensions.length) body.dimensions = dimensions
+  if (opts.range !== undefined && (opts.from !== undefined || opts.to !== undefined)) throw new Error('give the window as a range (P7D) or as from and to, not both')
+  if (opts.range !== undefined) {
+    const d = opts.range.trim().toUpperCase()
+    if (!ISO_DURATION.test(d)) throw new Error(`range must be an ISO-8601 duration, e.g. P7D, PT12H or P3M (not "${opts.range}")`)
+    body.timeRange = { isoDuration: d }
+  } else if (opts.from !== undefined || opts.to !== undefined) {
+    body.timeRange = {
+      ...(opts.from !== undefined ? { start: fullTimestamp(opts.from, 'from') } : {}),
+      ...(opts.to !== undefined ? { end: fullTimestamp(opts.to, 'to') } : {}),
+    }
+  }
+  if (opts.compare === true) {
+    if (!body.timeRange) throw new Error('compare reads the window before the one given: give a range (P7D) or from and to')
+    body.compare = true
+  } else if (opts.compare && typeof opts.compare === 'object') {
+    body.compare = { start: fullTimestamp(opts.compare.start, 'compare.start'), end: fullTimestamp(opts.compare.end, 'compare.end') }
+  }
+  return body
+}
+
+/** The rows of an answer, whichever envelope it came in. */
+export function metricRows(result: MetricQueryResult | Array<Record<string, unknown>> | null | undefined): Array<Record<string, unknown>> {
+  if (Array.isArray(result)) return result
+  if (Array.isArray(result?.data)) return result.data
+  if (Array.isArray(result?.rows)) return result.rows
+  return []
+}
+
+/** The timeseries dimension of a metric row as the service gives it (`definition.timeseries`); null when it has none. */
+export function timeseriesOf(metric: unknown): string | null {
+  const m = metric as { definition?: { timeseries?: unknown }; timeseries?: unknown } | null
+  const t = m?.definition?.timeseries ?? m?.timeseries
+  return typeof t === 'string' && t ? t : null
+}
+
+/**
+ * The window a duration range covered, as the service resolved it: after
+ * `newest − range`, up to and including `newest`, where `newest` is the latest
+ * value of the metric's timeseries in the data. Null bounds when the newest
+ * value could not be read; `note` says the rule either way.
+ */
+export interface RangeWindow {
+  range: string
+  /** The property the window is over, when known. */
+  timeseries: string | null
+  /** The newest value of it in the data: where the window ends. */
+  newest: string | null
+  /** Exclusive. */
+  after: string | null
+  /** Inclusive: the newest value. */
+  through: string | null
+  note: string
+}
+
+/** What `resolveRangeWindow` reads, so the CLI (`PlatformApi`) and the MCP tool (`serviceCall`) share it. */
+export interface RangeWindowReads {
+  /** The metric as `GET /v1/blueprint/metrics/:apiName` answers. */
+  metric(): Promise<unknown>
+  /** The object types as `GET /v1/blueprint/object-types` answers. */
+  objectTypes(): Promise<unknown>
+  /** `POST /v1/blueprint/aggregate`. */
+  aggregate(body: unknown): Promise<unknown>
+}
+
+const DURATION_PARTS = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/
+
+/**
+ * `at` moved back by an ISO duration, years and months in calendar units, as the
+ * engine's `INTERVAL` arithmetic does (and the service's `subtractIsoDuration`).
+ * Null for a duration it does not read (fractional seconds).
+ */
+export function minusDuration(at: Date, duration: string): Date | null {
+  const m = DURATION_PARTS.exec(duration)
+  if (!m) return null
+  const [years, months, weeks, days, hours, minutes, seconds] = m.slice(1, 8).map((v) => (v ? Number(v) : 0)) as number[]
+  const out = new Date(at)
+  if (years || months) out.setUTCMonth(out.getUTCMonth() - (years! * 12 + months!))
+  return new Date(out.getTime() - (((weeks! * 7 + days!) * 24 + hours!) * 60 + minutes!) * 60_000 - seconds! * 1000)
+}
+
+/** A timestamp as the query engine returns it (`2026-10-20 21:34:00+00`), as ISO; null when it is not one. */
+export function engineTimestamp(raw: unknown): string | null {
+  if (raw instanceof Date) return Number.isNaN(raw.getTime()) ? null : raw.toISOString()
+  if (typeof raw !== 'string' || !raw.trim()) return null
+  const text = raw.trim().replace(/^(\d{4}-\d{2}-\d{2}) /, '$1T').replace(/([+-]\d{2})$/, '$1:00')
+  const ms = Date.parse(text)
+  return Number.isNaN(ms) ? null : new Date(ms).toISOString()
+}
+
+const listOf = (value: unknown): Array<Record<string, unknown>> => {
+  const list = Array.isArray(value) ? value : (value as { data?: unknown } | null)?.data
+  return Array.isArray(list) ? list.filter((x): x is Record<string, unknown> => !!x && typeof x === 'object') : []
+}
+
+/**
+ * The window a `range` covered: reads the newest value of the metric's
+ * timeseries with the same grants the metric query ran under (an aggregate over
+ * the metric's object type, the set the service's watermark is taken over).
+ * Never throws: a read that fails leaves the bounds null and the rule stated.
+ */
+export async function resolveRangeWindow(range: string, reads: RangeWindowReads): Promise<RangeWindow> {
+  let timeseries: string | null = null
+  let newest: string | null = null
+  try {
+    const metric = (await reads.metric()) as { objectTypeId?: unknown; objectTypeApiName?: unknown } | null
+    timeseries = timeseriesOf(metric)
+    const typeId = metric?.objectTypeId
+    const objectType = typeof metric?.objectTypeApiName === 'string'
+      ? metric.objectTypeApiName
+      : listOf(await reads.objectTypes()).find((t) => t.id === typeId)?.apiName
+    if (timeseries && typeof objectType === 'string') {
+      const answer = await reads.aggregate({
+        objectSet: { type: 'base', objectType },
+        groupBy: [],
+        aggregations: [{ fn: 'max', property: timeseries, alias: 'newest' }],
+      }) as { rows?: unknown; data?: unknown } | null
+      const rows = listOf(answer?.rows ?? answer?.data ?? answer)
+      newest = engineTimestamp(rows[0]?.newest)
+    }
+  } catch {
+    // The rule is still worth stating without the timestamps.
+  }
+  const start = newest ? minusDuration(new Date(newest), range) : null
+  const over = timeseries ?? 'the metric’s timeseries'
+  return {
+    range,
+    timeseries,
+    newest,
+    after: start ? start.toISOString() : null,
+    through: start ? newest : null,
+    note: start
+      ? `${range} back from the newest ${over} in the data (${newest}), not from now: after ${start.toISOString()}, through ${newest}.`
+      : `${range} is counted back from the newest ${over} in the data, not from now.`,
+  }
+}