@sixb/core 0.1.21 → 0.1.22

package/src/ontology/validation/properties.ts

@@ -3,6 +3,7 @@ import type { ObjectLink, ObjectType, PrimitiveSchema, Property, Schema, ValueTy
 import { OntologyValidationError } from "../errors"
 import { primitiveTraits } from "../primitives"
 import type { LinkToken, ObjectTypeWithPropertyTokens, PropertyToken } from "../tokens"
+import { uniqueValueKind } from "../unique-values"
 import { validateSchemaValue } from "./schema"
 
 export function assertObjectTypeRegistered(
@@ -170,6 +171,7 @@ export function validatePropertyDefinitions(
   for (const [typeId, objectType] of objectTypesById) {
     for (const property of objectType.properties) {
       assertNoObjectRefSchema(property, `Property '${typeId}.${property.id}'`, valueTypesById)
+      assertUniquePropertyDefinition(typeId, property, valueTypesById)
       if (property.mode !== "telemetry") continue
       // Telemetry stores time-series samples, not references, even when the reference is nested.
       const primitive = findPrimitiveSchema(
@@ -187,6 +189,11 @@ export function validatePropertyDefinitions(
       for (const property of link.properties ?? []) {
         const path = `Link property '${typeId}.${link.id}.${property.id}'`
         assertNoObjectRefSchema(property, path, valueTypesById)
+        if (property.unique) {
+          throw new OntologyValidationError(
+            `[Sixb] ${path} cannot be unique. Unique values are supported on object properties only.`
+          )
+        }
         // Link edits do not check that referenced users exist and are active.
         if (
           findPrimitiveSchema(property.schema, valueTypesById, (schema) => schema === "userRef")
@@ -200,6 +207,42 @@ export function validatePropertyDefinitions(
   }
 }
 
+/**
+ * A unique property is a static object property whose values compare as exact keys. Primary
+ * properties are unique by construction.
+ */
+function assertUniquePropertyDefinition(
+  typeId: string,
+  property: Property,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): void {
+  if (!property.unique) return
+  const path = `Unique property '${typeId}.${property.id}'`
+
+  if (property.primary) {
+    throw new OntologyValidationError(
+      `[Sixb] ${path} is primary, and primary properties are already unique. Remove unique: true.`
+    )
+  }
+
+  if (property.mode === "telemetry") {
+    throw new OntologyValidationError(`[Sixb] ${path} cannot be a telemetry property.`)
+  }
+
+  if (uniqueValueKind(property.schema, valueTypesById) === undefined) {
+    throw new OntologyValidationError(
+      `[Sixb] ${path} cannot use ${schemaLabel(property.schema)}. ` +
+        "Unique values must be strings, uuids, integers, dates, enums or user references."
+    )
+  }
+}
+
+function schemaLabel(schema: Schema): string {
+  if (typeof schema === "string") return schema
+  if (schema.type === "valueTypeRef") return `value type '${schema.valueTypeId}'`
+  return schema.type
+}
+
 export function validatePropertyValue(
   property: Property,
   value: unknown,

package/src/ontology/validation/schema.ts

@@ -3,7 +3,7 @@ import { withFailureMessage } from "../../errors/failure-message"
 import type { ObjectFieldSchema, Schema, ValueType, ValueTypeRefSchema } from ".."
 import { isDecimalString } from "../decimal"
 import { OntologyValidationError } from "../errors"
-import { isUserRef } from "../user-ref"
+import { currentUserNotStorableMessage, isCurrentUser, isUserRef } from "../user-ref"
 
 /** Recursive schema validator used by both object and link property validation. */
 export function validateSchemaValue(
@@ -81,6 +81,14 @@ export function validateSchemaValue(
         return
       }
       case "userRef": {
+        if (isCurrentUser(value)) {
+          throw withFailureMessage(
+            new OntologyValidationError(
+              `[Sixb] ${currentUserNotStorableMessage(`Property ${path}`)}`
+            ),
+            currentUserNotStorableMessage(`Property ${diagnosticPath}`)
+          )
+        }
         if (!isUserRef(value)) {
           throw withFailureMessage(
             new OntologyValidationError(

package/src/projections/registry.ts

@@ -4,6 +4,7 @@ import { isProjectionDefinition } from "./builders"
 import { ProjectionValidationError } from "./errors"
 import {
   computeOntologyRevision,
+  computeProjectionOntologyRevision,
   computeProjectionOwnershipHash,
   computeProjectionRevision,
 } from "./revision"
@@ -35,6 +36,10 @@ export interface ProjectionRegistryOptions {
 }
 
 export class ProjectionRegistry implements ProjectionDefinitionCatalog {
+  /**
+   * The whole ontology, for commits no projection owns. A projection pins its own revision
+   * (`ResolvedProjection.ontologyRevision`), so a change elsewhere in the ontology leaves it alone.
+   */
   readonly ontologyRevision: string
   private readonly objectProjections: readonly ObjectProjectionDefinition[]
   private readonly linkProjections: readonly LinkProjectionDefinition[]
@@ -91,22 +96,22 @@ export class ProjectionRegistry implements ProjectionDefinitionCatalog {
 
     const dispatchDescriptors: ProjectionDispatchDescriptor[] = []
     for (const record of validated.objectProjections) {
-      const resolved = createResolvedProjection(record)
+      const resolved = createResolvedProjection(record, input.ontology)
       this.sourceById.set(resolved.projectionId, resolved)
       this.projectionsById.set(resolved.projectionId, resolved.definition)
-      dispatchDescriptors.push(createDispatchDescriptor(resolved, this.ontologyRevision))
+      dispatchDescriptors.push(createDispatchDescriptor(resolved))
     }
     for (const record of validated.linkProjections) {
-      const resolved = createResolvedProjection(record)
+      const resolved = createResolvedProjection(record, input.ontology)
       this.sourceById.set(resolved.projectionId, resolved)
       this.projectionsById.set(resolved.projectionId, resolved.definition)
-      dispatchDescriptors.push(createDispatchDescriptor(resolved, this.ontologyRevision))
+      dispatchDescriptors.push(createDispatchDescriptor(resolved))
     }
     for (const record of validated.telemetryProjections) {
-      const resolved = createResolvedProjection(record)
+      const resolved = createResolvedProjection(record, input.ontology)
       this.telemetryById.set(resolved.projectionId, resolved)
       this.projectionsById.set(resolved.projectionId, resolved.definition)
-      dispatchDescriptors.push(createDispatchDescriptor(resolved, this.ontologyRevision))
+      dispatchDescriptors.push(createDispatchDescriptor(resolved))
     }
     this.dispatchDescriptors = Object.freeze(dispatchDescriptors)
     for (const descriptor of this.dispatchDescriptors) {
@@ -172,13 +177,12 @@ export class ProjectionRegistry implements ProjectionDefinitionCatalog {
 }
 
 function createDispatchDescriptor(
-  resolved: ResolvedProjection<ProjectionDefinition>,
-  ontologyRevision: string
+  resolved: ResolvedProjection<ProjectionDefinition>
 ): ProjectionDispatchDescriptor {
   const common = {
     projectionId: resolved.projectionId,
     datasetId: resolved.datasetId,
-    ontologyRevision,
+    ontologyRevision: resolved.ontologyRevision,
     projectionRevision: resolved.projectionRevision,
     ownershipHash: resolved.ownershipHash,
   }
@@ -204,12 +208,14 @@ function assertUniqueProjectionIds(projections: readonly ProjectionDefinition[])
 }
 
 function createResolvedProjection<TDefinition extends ProjectionDefinition>(
-  validated: ValidatedProjectionRecord<TDefinition>
+  validated: ValidatedProjectionRecord<TDefinition>,
+  ontology: OntologyDefinitionCatalog
 ): ResolvedProjection<TDefinition> {
   const { definition, dataset, ownership } = validated
   return deepFreeze({
     projectionId: definition.id,
     datasetId: definition.datasetId,
+    ontologyRevision: computeProjectionOntologyRevision(definition, ontology),
     projectionRevision: computeProjectionRevision(definition, dataset),
     ownershipHash: computeProjectionOwnershipHash(ownership),
     ownership,

package/src/projections/revision.ts

@@ -2,22 +2,103 @@ import type { DatasetDefinition } from "../datasets"
 import { compareStrings, type JsonValue } from "../json"
 import { sha256Canonical } from "../materialization/identity"
 import type { OntologyDefinitionCatalog } from "../ontology"
-import type { ObjectFieldSchema, Property, Schema } from "../ontology/types"
+import type { ObjectFieldSchema, ObjectType, Property, Schema } from "../ontology/types"
 import type { ProjectionDefinition, ProjectionOwnership } from "./types"
 
+/** The whole ontology a project runs: every object type and the value types they reference. */
 export function computeOntologyRevision(ontology: OntologyDefinitionCatalog): string {
-  const referencedValueTypeIds = collectOntologyValueTypeDependencies(ontology)
+  const objectTypes = [...ontology.getObjectTypesById().values()].sort((left, right) =>
+    compareStrings(left.id, right.id)
+  )
   return sha256Canonical({
-    objectTypes: normalizeOntologyObjectTypes(ontology),
-    valueTypes: normalizeOntologyValueTypes(ontology, referencedValueTypeIds),
+    objectTypes: objectTypes.map(normalizeObjectType),
+    valueTypes: normalizeReferencedValueTypes(ontology, objectTypes),
   })
 }
 
-function collectOntologyValueTypeDependencies(
+/**
+ * The part of the ontology one projection's output depends on, so that a deployment reruns only
+ * the projections whose part changed.
+ *
+ * - The type the projection writes, which inheritance has already flattened. Committing validates
+ *   the whole effective object or link scope against it, not only the mapped properties.
+ * - The supertypes of each type it links to: a link accepts a target that is its declared target
+ *   type or a subtype of it.
+ * - The value types the written type references, transitively.
+ *
+ * Other types are not read. Links of other scopes that a commit re-resolves because it changed an
+ * object's existence follow from that data change, under their own projections' revisions.
+ */
+export function computeProjectionOntologyRevision(
+  projection: ProjectionDefinition,
   ontology: OntologyDefinitionCatalog
+): string {
+  const writtenType = ontology.resolveObjectType(writtenObjectTypeId(projection))
+  return sha256Canonical({
+    objectType: normalizeObjectType(writtenType),
+    linkTargets: [...new Set(linkTargetObjectTypeIds(projection))]
+      .sort(compareStrings)
+      .map((objectTypeId) => ({
+        id: objectTypeId,
+        supertypes: listSupertypeIds(ontology, objectTypeId),
+      })),
+    valueTypes: normalizeReferencedValueTypes(ontology, [writtenType]),
+  })
+}
+
+function writtenObjectTypeId(projection: ProjectionDefinition): string {
+  return projection._tag === "LinkProjectionDefinition"
+    ? projection.sourceObjectTypeId
+    : projection.objectTypeId
+}
+
+function linkTargetObjectTypeIds(projection: ProjectionDefinition): readonly string[] {
+  if (projection._tag === "ObjectProjectionDefinition") {
+    return Object.values(projection.links).map((link) => link.targetObjectTypeId)
+  }
+  if (projection._tag === "LinkProjectionDefinition") return [projection.targetObjectTypeId]
+  return []
+}
+
+/** Transitive `extends` and `parents`, sorted: what `isValidLinkTarget` matches a target against. */
+function listSupertypeIds(ontology: OntologyDefinitionCatalog, objectTypeId: string): string[] {
+  const supertypes = new Set<string>()
+  const pending = [objectTypeId]
+  for (let index = 0; index < pending.length; index += 1) {
+    const objectType = ontology.resolveObjectType(pending[index])
+    for (const supertypeId of [
+      ...(objectType.extends ? [objectType.extends] : []),
+      ...(objectType.parents ?? []),
+    ]) {
+      if (supertypes.has(supertypeId)) continue
+      supertypes.add(supertypeId)
+      pending.push(supertypeId)
+    }
+  }
+  return [...supertypes].sort(compareStrings)
+}
+
+function normalizeReferencedValueTypes(
+  ontology: OntologyDefinitionCatalog,
+  objectTypes: readonly ObjectType[]
+): JsonValue[] {
+  return [...collectReferencedValueTypes(ontology, objectTypes)]
+    .sort(compareStrings)
+    .map((valueTypeId) => ontology.getValueTypesById().get(valueTypeId))
+    .filter((valueType) => valueType !== undefined)
+    .map((valueType) => ({
+      id: valueType.id,
+      schema: normalizeSchema(valueType.schema),
+      semanticType: valueType.semanticType ?? null,
+    }))
+}
+
+function collectReferencedValueTypes(
+  ontology: OntologyDefinitionCatalog,
+  objectTypes: readonly ObjectType[]
 ): ReadonlySet<string> {
   const referencedValueTypeIds = new Set<string>()
-  for (const objectType of ontology.getObjectTypesById().values()) {
+  for (const objectType of objectTypes) {
     for (const property of objectType.properties) {
       collectReferencedValueTypeIds(property.schema, referencedValueTypeIds)
     }
@@ -42,45 +123,28 @@ function collectOntologyValueTypeDependencies(
   return referencedValueTypeIds
 }
 
-function normalizeOntologyValueTypes(
-  ontology: OntologyDefinitionCatalog,
-  referencedValueTypeIds: ReadonlySet<string>
-): JsonValue[] {
-  return [...referencedValueTypeIds]
-    .sort(compareStrings)
-    .map((valueTypeId) => ontology.getValueTypesById().get(valueTypeId))
-    .filter((valueType) => valueType !== undefined)
-    .map((valueType) => ({
-      id: valueType.id,
-      schema: normalizeSchema(valueType.schema),
-      semanticType: valueType.semanticType ?? null,
-    }))
-}
-
-function normalizeOntologyObjectTypes(ontology: OntologyDefinitionCatalog): JsonValue[] {
-  return [...ontology.getObjectTypesById().values()]
-    .sort((left, right) => compareStrings(left.id, right.id))
-    .map((objectType) => ({
-      id: objectType.id,
-      extends: objectType.extends ?? null,
-      parents: [...(objectType.parents ?? [])].sort(),
-      implements: [...(objectType.implements ?? [])].sort(),
-      properties: [...objectType.properties]
-        .sort((left, right) => compareStrings(left.id, right.id))
-        .map(normalizeProperty),
-      links: [...objectType.links]
-        .sort((left, right) => compareStrings(left.id, right.id))
-        .map((link) => ({
-          id: link.id,
-          targetObjectTypeIds: Array.isArray(link.targetObjectTypeId)
-            ? [...link.targetObjectTypeId].sort()
-            : [link.targetObjectTypeId],
-          cardinality: link.cardinality ?? "many",
-          properties: [...(link.properties ?? [])]
-            .sort((left, right) => compareStrings(left.id, right.id))
-            .map(normalizeProperty),
-        })),
-    }))
+function normalizeObjectType(objectType: ObjectType): JsonValue {
+  return {
+    id: objectType.id,
+    extends: objectType.extends ?? null,
+    parents: [...(objectType.parents ?? [])].sort(),
+    implements: [...(objectType.implements ?? [])].sort(),
+    properties: [...objectType.properties]
+      .sort((left, right) => compareStrings(left.id, right.id))
+      .map(normalizeProperty),
+    links: [...objectType.links]
+      .sort((left, right) => compareStrings(left.id, right.id))
+      .map((link) => ({
+        id: link.id,
+        targetObjectTypeIds: Array.isArray(link.targetObjectTypeId)
+          ? [...link.targetObjectTypeId].sort()
+          : [link.targetObjectTypeId],
+        cardinality: link.cardinality ?? "many",
+        properties: [...(link.properties ?? [])]
+          .sort((left, right) => compareStrings(left.id, right.id))
+          .map(normalizeProperty),
+      })),
+  }
 }
 
 function collectReferencedValueTypeIds(schema: Schema, valueTypeIds: Set<string>): void {
@@ -227,6 +291,9 @@ function normalizeProperty(property: Property): JsonValue {
     required: property.required ?? false,
     nullable: property.nullable ?? false,
     primary: property.primary ?? false,
+    // A projection planned before a property became unique carries no claims for its values, so
+    // it must not commit after. Written only when set: other ontologies keep their revision.
+    ...(property.unique ? { unique: true } : {}),
     mode: property.mode ?? "static",
     semanticType: property.semanticType ?? null,
   }

package/src/projections/run-dispatch.ts

@@ -76,20 +76,6 @@ export class ProjectionRunDispatcher implements ProjectionRunDispatchPort {
     if (!projection) {
       throw new ProjectionValidationError(`[Sixb] Unknown projection '${input.projectionId}'.`)
     }
-    const version = await this.dependencies.lakeStorage.getVersion(
-      input.datasetVersion.datasetId,
-      input.datasetVersion.versionId
-    )
-    if (!version || version.createdAt.toISOString() !== input.datasetVersion.createdAt) {
-      throw new ProjectionValidationError(
-        `[Sixb] Dataset '${input.datasetVersion.datasetId}' version '${input.datasetVersion.versionId}' does not match its immutable metadata.`
-      )
-    }
-    if (version.mode === "schema") {
-      throw new ProjectionValidationError(
-        `[Sixb] Projection '${input.projectionId}' cannot materialize a schema-only dataset version.`
-      )
-    }
 
     const { datasetId: _datasetId, ...semanticIdentity } = descriptor
     const identity = {
@@ -98,20 +84,14 @@ export class ProjectionRunDispatcher implements ProjectionRunDispatchPort {
     }
     const runId = createProjectionRunId(this.dependencies.id, identity)
     const projectionRuns = requireProjectionRunStorage(this.dependencies.storage)
+    // Most dispatches repeat an admitted one: the live commit event and the reconciler both
+    // dispatch each version. Only admitProjectionRun creates a run, once the lake confirms its
+    // version, and the run id hashes that version's dataset, id and creation time. An existing run
+    // therefore needs no lake read.
     const existing = await projectionRuns.getById({ projectId: this.dependencies.id, id: runId })
     let persisted = existing
       ? await reuseProjectionRun(this.dependencies, existing, identity)
-      : await persistProjectionRun({
-          dependencies: this.dependencies,
-          runId,
-          identity,
-          projection,
-          producerExecution: await resolveProducerExecution(
-            this.dependencies.storage,
-            this.dependencies.id,
-            version.producer
-          ),
-        })
+      : await admitProjectionRun(this.dependencies, input, { runId, identity, projection })
 
     if (!persisted.publish && persisted.run.status === "queued") {
       persisted = await reuseProjectionRun(this.dependencies, persisted.run, identity)
@@ -121,6 +101,39 @@ export class ProjectionRunDispatcher implements ProjectionRunDispatchPort {
   }
 }
 
+/** Persists a new run once the lake confirms the dispatched version is one it can materialize. */
+async function admitProjectionRun(
+  dependencies: ProjectionRunDispatcherDependencies,
+  input: ProjectionRunDispatchInput,
+  run: {
+    readonly runId: string
+    readonly identity: ProjectionRunRecord["identity"]
+    readonly projection: ProjectionDefinition
+  }
+): Promise<PersistedProjectionRun> {
+  const { datasetId, versionId, createdAt } = input.datasetVersion
+  const version = await dependencies.lakeStorage.getVersion(datasetId, versionId)
+  if (!version || version.createdAt.toISOString() !== createdAt) {
+    throw new ProjectionValidationError(
+      `[Sixb] Dataset '${datasetId}' version '${versionId}' does not match its immutable metadata.`
+    )
+  }
+  if (version.mode === "schema") {
+    throw new ProjectionValidationError(
+      `[Sixb] Projection '${input.projectionId}' cannot materialize a schema-only dataset version.`
+    )
+  }
+  return persistProjectionRun({
+    dependencies,
+    ...run,
+    producerExecution: await resolveProducerExecution(
+      dependencies.storage,
+      dependencies.id,
+      version.producer
+    ),
+  })
+}
+
 async function persistProjectionRun(input: {
   readonly dependencies: ProjectionRunDispatcherDependencies
   readonly runId: string

package/src/projections/types.ts

@@ -182,6 +182,8 @@ interface ProjectionDispatchDescriptorBase {
 export interface ResolvedProjection<TDefinition extends ProjectionDefinition> {
   readonly projectionId: string
   readonly datasetId: string
+  /** The part of the ontology this projection reads; see `computeProjectionOntologyRevision`. */
+  readonly ontologyRevision: string
   readonly projectionRevision: string
   readonly ownershipHash: string
   readonly ownership: ProjectionOwnership

package/src/query.ts

@@ -24,6 +24,7 @@ export type {
   ObjectQueryPage,
   ObjectQueryPredicate,
   ObjectQueryPredicateComparison,
+  ObjectQueryPredicateConstant,
   ObjectQueryPredicateContains,
   ObjectQueryPredicateExists,
   ObjectQueryPredicateGroup,
@@ -77,4 +78,8 @@ export type {
   ObjectWhereBuilder,
   ObjectWhereClause,
   TwinObject,
+  UniquePropertyToken,
+  UniquePropertyValue,
 } from "./runtime/types"
+export type { RedactionReason, Redactions } from "./security/types"
+export type { UserProfile } from "./users"

package/src/rules/execution.ts

@@ -1,5 +1,6 @@
 import { isRuntimeAllowed } from "../authorization"
 import { resolveRuntimeAuthorizationForProject } from "../execution/authorization"
+import { readerClearance, readerViewConditions } from "../execution/authorized-object-reader"
 import type { DefinitionCatalog } from "../runtime/definitions"
 import type { SixbRuntimeContext } from "../runtime/types"
 import type { ListActiveRuleStatesInput, ListActiveRuleStatesResult } from "../storage/rules"
@@ -22,12 +23,16 @@ export function createRulesRuntime(
   source: DefinitionCatalog<RuleDefinition>
 ): RulesRuntime {
   const authority = resolveRuntimeAuthorizationForProject(runtime)
+
+  // A rule on a type the reader views under a condition shows: the reader sees some of its objects.
   const visible = (rule: RuleDefinition) => {
     if (authority.type === "denied" || authority.type === "delegated") return false
-    return isRuntimeAllowed(runtime, {
-      kind: "object.view",
-      objectTypeId: rule.subject.objectTypeId,
-    })
+
+    const objectTypeId = rule.subject.objectTypeId
+    return (
+      isRuntimeAllowed(runtime, { kind: "object.view", objectTypeId }) ||
+      readerViewConditions(runtime.objectReader).has(objectTypeId)
+    )
   }
 
   return {
@@ -41,18 +46,45 @@ export function createRulesRuntime(
       return rule && visible(rule) ? rule : null
     },
     states: {
-      list: (input = {}) => {
+      list: async (input = {}) => {
         if (authority.type === "denied" || authority.type === "delegated") {
-          return Promise.resolve({ states: [], hasMore: false, total: 0 })
+          return { states: [], hasMore: false, total: 0 }
         }
         const storage = runtime.storage.rules
-        if (!storage) return Promise.resolve({ states: [], hasMore: false, total: 0 })
+        if (!storage) return { states: [], hasMore: false, total: 0 }
+        if (authority.type === "unrestricted") {
+          return storage.listActive({ ...input, projectId: runtime.projectId })
+        }
+
+        // A state names its subject's id: it shows where the reader could read that subject, under
+        // the markings of the versions projections applied too.
+        const clearance = await readerClearance(runtime.objectReader)
+
+        // Storage cannot tell which objects of a type viewed under a condition the reader sees, so
+        // their matches list one object at a time, once the reader reads it. A listing that names
+        // no object leaves them out: it lists only the types the reader views whole.
+        const { objectTypeId, primaryId } = input
+        const conditions = readerViewConditions(runtime.objectReader)
+        if (objectTypeId !== undefined && primaryId !== undefined && conditions.has(objectTypeId)) {
+          if (conditions.get(objectTypeId)!.hiddenBy(clearance)) {
+            return { states: [], hasMore: false, total: 0 }
+          }
+
+          const object = await runtime.objectReader.getByPrimaryId({ objectTypeId, primaryId })
+          if (!object) return { states: [], hasMore: false, total: 0 }
+
+          return storage.listActive({
+            ...input,
+            objectTypeIds: [objectTypeId],
+            projectId: runtime.projectId,
+          })
+        }
+
         return storage.listActive({
           ...input,
-          objectTypeIds:
-            authority.type === "principal"
-              ? [...authority.context.grants["view:object"]]
-              : undefined,
+          objectTypeIds: [...authority.context.grants["view:object"]].filter(
+            (objectTypeId) => clearance?.unreadableType(objectTypeId) === undefined
+          ),
           projectId: runtime.projectId,
         })
       },

package/src/runtime/ai-cost.ts

@@ -13,3 +13,33 @@ export async function resolveExecutionCosts(input: {
     executionIds: input.executionIds,
   })
 }
+
+/** The cost of several executions together; nothing when none made a call. */
+export function addCostSummaries(summaries: readonly AiCostSummary[]): AiCostSummary | undefined {
+  const amounts = new Map<string, bigint>()
+  let ratedCallCount = 0
+  let unpriceableCallCount = 0
+  let unvaluedCallCount = 0
+
+  for (const summary of summaries) {
+    for (const money of summary.amounts) {
+      amounts.set(money.currency, (amounts.get(money.currency) ?? 0n) + BigInt(money.amountNanos))
+    }
+    ratedCallCount += summary.ratedCallCount
+    unpriceableCallCount += summary.unpriceableCallCount
+    unvaluedCallCount += summary.unvaluedCallCount
+  }
+
+  if (ratedCallCount + unpriceableCallCount + unvaluedCallCount === 0) {
+    return undefined
+  }
+
+  return {
+    amounts: [...amounts]
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([currency, amount]) => ({ currency, amountNanos: amount.toString() })),
+    ratedCallCount,
+    unpriceableCallCount,
+    unvaluedCallCount,
+  }
+}

package/src/runtime/ai-usage.ts

@@ -1,4 +1,9 @@
-import type { AiModelCallUsage, AiUsageStorage } from "../storage/ai-usage"
+import type { AiModelCallUsage, AiModelCallUsageInput, AiUsageStorage } from "../storage/ai-usage"
+import {
+  AI_USAGE_FIELDS,
+  aggregateAiModelCallUsage,
+  normalizeAiModelCallUsage,
+} from "../storage/ai-usage/usage"
 
 /** Resolve execution usage for runtime views without exposing the accounting provider. */
 export async function resolveExecutionUsage(input: {
@@ -15,3 +20,29 @@ export async function resolveExecutionUsage(input: {
   })
   return summaries.map((summary) => (summary.modelCallCount === 0 ? undefined : summary.usage))
 }
+
+/**
+ * The usage of several executions together. When each knows its token totals, a count is summed
+ * only where all of them know it, as their calls would be one by one. When one does not, such as a
+ * child cut short mid-call, the total keeps what the others know: each count sums the executions
+ * that know it, and the total is `partial`, a floor for what was spent.
+ */
+export function addUsageSummaries(
+  usages: readonly AiModelCallUsage[]
+): AiModelCallUsage | undefined {
+  if (usages.length <= 1) return usages[0]
+  if (usages.every((usage) => usage.reportingStatus === "complete")) {
+    return aggregateAiModelCallUsage(usages)
+  }
+
+  const counts: AiModelCallUsageInput = Object.fromEntries(
+    AI_USAGE_FIELDS.flatMap((field) => {
+      const known = usages.flatMap((usage) => (usage[field] === undefined ? [] : [usage[field]]))
+      return known.length === 0 ? [] : [[field, known.reduce((sum, count) => sum + count, 0)]]
+    })
+  )
+  const total = normalizeAiModelCallUsage(counts)
+  return usages.every((usage) => usage.reportingStatus === "unavailable")
+    ? total
+    : { ...total, reportingStatus: "partial" }
+}