@sixb/core 0.1.2 → 0.1.3

package/src/materializer/edits/working-state.ts

@@ -25,6 +25,7 @@ import {
   resolveEffectiveLink,
   resolveEffectiveLinkSlot,
   resolveEffectiveObject,
+  storedObjectEditedAt,
   usableLinkSlotOverride,
 } from "../effective/resolve"
 import { linkCardinality } from "./read-set"
@@ -33,6 +34,8 @@ export interface WorkingObject {
   source: MaterializationObjectState["source"]
   originalOverride: StoredObjectOverride | null
   override: ObjectOverride | null
+  originalEditedAt: Readonly<Record<string, string>>
+  editedAt: Record<string, string>
   before: MaterializationObjectState["effective"]
   latestTelemetry: StoredTelemetryPoint[]
 }
@@ -112,11 +115,14 @@ function workingLinkSlotFromState(scope: MaterializationLinkScopeState): Working
 }
 
 export function workingObjectFromState(object: MaterializationObjectState): WorkingObject {
+  const editedAt = storedObjectEditedAt(object.override)
   return {
     ref: object.ref,
     source: object.source,
     originalOverride: object.override,
     override: object.override?.value ?? null,
+    originalEditedAt: editedAt,
+    editedAt: { ...editedAt },
     before: object.effective,
     latestTelemetry: [...object.latestTelemetry],
   }
@@ -141,6 +147,7 @@ export function resolveObject(
     primaryPropertyId: ontology.getPrimaryPropertyId(working.ref.objectTypeId),
     source: working.source,
     override: working.override,
+    editedAt: working.editedAt,
     latestTelemetry: working.latestTelemetry,
   })
 }

package/src/materializer/effective/resolve.ts

@@ -11,6 +11,7 @@ import type {
 import { linkRefKey } from "../../materialization/refs"
 import type {
   StoredLinkSlotOverride,
+  StoredObjectOverride,
   StoredSourceLinkAssertion,
   StoredSourceObjectAssertion,
   StoredTelemetryPoint,
@@ -46,9 +47,10 @@ export function resolveEffectiveObject(input: {
   readonly primaryPropertyId: string
   readonly source: StoredSourceObjectAssertion | null
   readonly override: ObjectOverride | null
+  readonly editedAt: Readonly<Record<string, string>>
   readonly latestTelemetry: readonly StoredTelemetryPoint[]
 }): ResolvedObjectValue | null {
-  const properties = resolveObjectAuthority(input.source, input.override)
+  const properties = resolveObjectAuthority(input.source, input.override, input.editedAt)
   if (!properties) return null
 
   properties[input.primaryPropertyId] = input.ref.primaryId
@@ -58,31 +60,98 @@ export function resolveEffectiveObject(input: {
 
 function resolveObjectAuthority(
   source: StoredSourceObjectAssertion | null,
-  override: ObjectOverride | null
+  override: ObjectOverride | null,
+  editedAt: Readonly<Record<string, string>>
 ): Record<string, JsonValue> | null {
   switch (override?.kind) {
     case "delete":
       return null
     case "create":
-      return { ...override.properties }
+      if (!source) return { ...override.properties }
+      return resolveSourceAndEdits(source, override, editedAt)
     case "patch":
       if (!source) return null
-      return applyObjectPatch(source.assertion.properties, override)
+      return resolveSourceAndEdits(source, override, editedAt)
     default:
       if (!source) return null
       return { ...source.assertion.properties }
   }
 }
 
-function applyObjectPatch(
-  sourceProperties: Readonly<Record<string, JsonValue>>,
-  override: Extract<ObjectOverride, { readonly kind: "patch" }>
+function resolveSourceAndEdits(
+  source: StoredSourceObjectAssertion,
+  override: Exclude<ObjectOverride, { readonly kind: "delete" }>,
+  editedAt: Readonly<Record<string, string>>
 ): Record<string, JsonValue> {
-  const properties = { ...sourceProperties, ...override.set }
-  for (const propertyId of override.unset) delete properties[propertyId]
+  const properties = { ...source.assertion.properties }
+  const absentSourcePropertyIds = new Set(source.assertion.absentSourcePropertyIds ?? [])
+
+  for (const propertyId of objectEditCandidateIds(override, editedAt)) {
+    const edit = objectEditCandidate(override, propertyId)
+    const editTimestamp = editedAt[propertyId]
+    const hasSourceCandidate =
+      Object.hasOwn(source.assertion.properties, propertyId) ||
+      absentSourcePropertyIds.has(propertyId)
+    const sourceWins =
+      hasSourceCandidate &&
+      source.assertion.sourceUpdatedAt !== undefined &&
+      editTimestamp !== undefined &&
+      source.assertion.sourceUpdatedAt.localeCompare(editTimestamp) >= 0
+
+    if (!sourceWins) applyObjectEditCandidate(properties, propertyId, edit)
+  }
   return properties
 }
 
+interface ObjectPropertyCandidate {
+  readonly present: boolean
+  readonly value?: JsonValue
+}
+
+function objectEditCandidateIds(
+  override: Exclude<ObjectOverride, { readonly kind: "delete" }>,
+  editedAt: Readonly<Record<string, string>>
+): string[] {
+  const ids = new Set(Object.keys(editedAt))
+  if (override.kind === "create") {
+    for (const propertyId of Object.keys(override.properties)) ids.add(propertyId)
+  } else {
+    for (const propertyId of Object.keys(override.set)) ids.add(propertyId)
+    for (const propertyId of override.unset) ids.add(propertyId)
+  }
+  return [...ids]
+}
+
+function objectEditCandidate(
+  override: Exclude<ObjectOverride, { readonly kind: "delete" }>,
+  propertyId: string
+): ObjectPropertyCandidate {
+  const values = override.kind === "create" ? override.properties : override.set
+  return Object.hasOwn(values, propertyId)
+    ? { present: true, value: values[propertyId] }
+    : { present: false }
+}
+
+function applyObjectEditCandidate(
+  properties: Record<string, JsonValue>,
+  propertyId: string,
+  candidate: ObjectPropertyCandidate
+): void {
+  if (candidate.present) properties[propertyId] = candidate.value as JsonValue
+  else delete properties[propertyId]
+}
+
+export function storedObjectEditedAt(stored: StoredObjectOverride | null): Record<string, string> {
+  if (!stored || stored.value.kind === "delete") return {}
+  const editedAt = { ...(stored.editedAt ?? {}) }
+  const candidateIds =
+    stored.value.kind === "create"
+      ? Object.keys(stored.value.properties)
+      : [...Object.keys(stored.value.set), ...stored.value.unset]
+  for (const propertyId of candidateIds) editedAt[propertyId] ??= stored.updatedAt
+  return editedAt
+}
+
 function applyLatestTelemetry(
   properties: Record<string, JsonValue>,
   latestTelemetry: readonly StoredTelemetryPoint[]

package/src/materializer/execution/work-records.ts

@@ -22,7 +22,8 @@ export function appendObjectOverrideWork(
 ): void {
   if (
     stableJsonStringify(working.originalOverride?.value ?? null) ===
-    stableJsonStringify(working.override)
+      stableJsonStringify(working.override) &&
+    stableJsonStringify(working.originalEditedAt) === stableJsonStringify(working.editedAt)
   ) {
     return
   }
@@ -32,6 +33,7 @@ export function appendObjectOverrideWork(
       value: {
         ref: working.ref,
         value: working.override,
+        editedAt: working.editedAt,
         expectedLastCommitId: working.originalOverride?.lastCommitId ?? null,
         lastCommitId: identity.commitId,
         updatedAt: identity.committedAt,

package/src/materializer/projections/entry-validator.ts

@@ -118,7 +118,29 @@ function validateObjectAssertion(
       `Projection '${resolved.projectionId}' asserted unowned property '${assertion.ref.objectTypeId}.${propertyId}'.`
     )
   }
-  return { ...assertion, properties }
+  const conflictResolution = resolved.definition.conflictResolution ?? { strategy: "editsWin" }
+  if (conflictResolution.strategy !== "mostRecent") {
+    return { kind: "object", ref: assertion.ref, properties }
+  }
+  if (assertion.sourceUpdatedAt === undefined) {
+    throw new MaterializationValidationError(
+      `Projection '${resolved.projectionId}' requires source update timestamp ` +
+        `'${conflictResolution.sourceTimestamp}' on every object assertion.`
+    )
+  }
+  const primaryPropertyId = ontology.getPrimaryPropertyId(assertion.ref.objectTypeId)
+  const absentSourcePropertyIds = [...owned]
+    .filter(
+      (propertyId) => propertyId !== primaryPropertyId && !Object.hasOwn(properties, propertyId)
+    )
+    .sort()
+  return {
+    kind: "object",
+    ref: assertion.ref,
+    properties,
+    sourceUpdatedAt: assertion.sourceUpdatedAt,
+    ...(absentSourcePropertyIds.length === 0 ? {} : { absentSourcePropertyIds }),
+  }
 }
 
 function validateLinkAssertion(

package/src/materializer/projections/replacement-plan.ts

@@ -33,6 +33,7 @@ import {
   resolveEffectiveLink,
   resolveEffectiveLinkSlotMember,
   resolveEffectiveObject,
+  storedObjectEditedAt,
   usableLinkSlotOverride,
 } from "../effective/resolve"
 import { validateEffectiveObject } from "../effective/validate"
@@ -374,6 +375,7 @@ function resolveReplacementObject(
     primaryPropertyId: context.ontology.getPrimaryPropertyId(state.ref.objectTypeId),
     source: state.candidateSource,
     override: state.override?.value ?? null,
+    editedAt: storedObjectEditedAt(state.override),
     latestTelemetry: state.latestTelemetry,
   })
 }

package/src/materializer/shared/normalize.ts

@@ -25,6 +25,7 @@ import {
   projectionEntityKey,
   telemetryPointKey,
 } from "../../materialization/refs"
+import { parseDatasetTimestamp } from "../../projections/timestamp"
 
 export function normalizeJsonProperties(
   properties: Readonly<Record<string, unknown>>,
@@ -67,6 +68,16 @@ function normalizeTimestamp(value: string, label: string): string {
   return new Date(milliseconds).toISOString()
 }
 
+function normalizeProjectionSourceTimestamp(value: string): string {
+  const timestamp = parseDatasetTimestamp(value)
+  if (!timestamp) {
+    throw new MaterializationValidationError(
+      "Projection source update timestamp must be a valid timestamp."
+    )
+  }
+  return timestamp.toISOString()
+}
+
 function normalizePropertyIds(values: readonly string[], label: string): readonly string[] {
   const seen = new Set<string>()
   const normalized: string[] = []
@@ -347,6 +358,11 @@ function normalizeProjectionAssertion(
         kind: "object",
         ref: normalizeObjectRef(assertion.ref),
         properties: normalizeJsonProperties(assertion.properties),
+        ...(assertion.sourceUpdatedAt !== undefined
+          ? {
+              sourceUpdatedAt: normalizeProjectionSourceTimestamp(assertion.sourceUpdatedAt),
+            }
+          : {}),
       })
     : Object.freeze({
         kind: "link",

package/src/projections/builders.ts

@@ -5,6 +5,7 @@
  */
 
 import type {
+  DatasetColumnDefinitionOf,
   DatasetColumnNameOf,
   DatasetColumnType,
   DatasetColumnTypeOf,
@@ -21,6 +22,7 @@ import type {
   ObjectProjectionTarget,
   ProjectionDefinition,
   ProjectionTarget,
+  SourceEditConflictResolution,
   TelemetryProjectionDefinition,
 } from "./types"
 import {
@@ -153,6 +155,20 @@ type DateLikeDatasetColumnNameOf<TDataset extends DatasetDefinition> =
           : never
       }[DatasetColumnNameOf<TDataset>]
 
+type TimestampDatasetColumnNameOf<TDataset extends DatasetDefinition> =
+  string extends DatasetColumnNameOf<TDataset>
+    ? string
+    : {
+        [TColumnName in DatasetColumnNameOf<TDataset>]: DatasetColumnTypeOf<
+          TDataset,
+          TColumnName
+        > extends "timestamp"
+          ? DatasetColumnDefinitionOf<TDataset, TColumnName> extends { readonly nullable: true }
+            ? never
+            : TColumnName
+          : never
+      }[DatasetColumnNameOf<TDataset>]
+
 type ProjectionMappingFor<TObjectType extends ObjectType, TDataset extends DatasetDefinition> = {
   readonly [TPropertyId in PropertyIdOf<TObjectType>]?: DatasetColumnNameCompatibleWithSchema<
     TDataset,
@@ -239,7 +255,7 @@ type ProjectionForeignKeyTokenInput<
         )
     }
 
-type ProjectionForeignKeyInput<
+export type ProjectionForeignKeyInput<
   TObjectType extends ObjectType,
   TDataset extends DatasetDefinition,
   TLinkId extends LinkIdOf<TObjectType>,
@@ -280,16 +296,27 @@ interface ObjectProjectionMappingBuilder<
 > {
   properties<const TMapping extends ProjectionMappingFor<TObjectType, TDataset>>(
     mapping: ExactProjectionMapping<TObjectType, TMapping>
-  ): ObjectProjectionDefinition & ObjectProjectionLinkBuilder<TObjectType, TDataset>
+  ): ObjectProjectionBuilder<TObjectType, TDataset>
 }
 
-interface ObjectProjectionLinkBuilder<
+export type ObjectProjectionConflictResolution<TDataset extends DatasetDefinition> =
+  | { readonly strategy: "editsWin" }
+  | {
+      readonly strategy: "mostRecent"
+      readonly sourceTimestamp: TimestampDatasetColumnNameOf<TDataset>
+    }
+
+export interface ObjectProjectionBuilder<
   TObjectType extends ObjectType,
   TDataset extends DatasetDefinition,
-> {
+> extends ObjectProjectionDefinition {
+  readonly conflictResolution: SourceEditConflictResolution
   withLinks(
     mapping: { [K in LinkIdOf<TObjectType>]?: ProjectionForeignKeyInput<TObjectType, TDataset, K> }
-  ): ObjectProjectionDefinition
+  ): ObjectProjectionBuilder<TObjectType, TDataset>
+  resolveConflicts(
+    resolution: ObjectProjectionConflictResolution<TDataset>
+  ): ObjectProjectionBuilder<TObjectType, TDataset>
 }
 
 /**
@@ -352,41 +379,17 @@ function buildObjectProjection<const TObjectType extends ObjectType>(
       return {
         properties<const TMapping extends ProjectionMappingFor<TObjectType, TDataset>>(
           mapping: ExactProjectionMapping<TObjectType, TMapping>
-        ): ObjectProjectionDefinition & ObjectProjectionLinkBuilder<TObjectType, TDataset> {
+        ): ObjectProjectionBuilder<TObjectType, TDataset> {
           const propertyMapping = mapping as Record<string, string>
           validatePropertyMapping(objectType, propertyMapping)
 
-          const definition: ObjectProjectionDefinition = {
-            _tag: "ObjectProjectionDefinition",
+          return objectProjectionBuilder({
             id,
-            objectTypeId: objectType.id,
+            objectType,
             datasetId,
-            properties: { ...propertyMapping },
+            propertyMapping,
             links: {},
-          }
-
-          return Object.assign(definition, {
-            withLinks(
-              linkMapping: {
-                [K in LinkIdOf<TObjectType>]?: ProjectionForeignKeyInput<TObjectType, TDataset, K>
-              }
-            ): ObjectProjectionDefinition {
-              const loweredLinkMapping = lowerForeignKeyMapping(linkMapping)
-              const validatedLinks = validateAndLowerLinkMapping(
-                objectType,
-                loweredLinkMapping,
-                propertyMapping
-              )
-
-              return {
-                _tag: "ObjectProjectionDefinition",
-                id,
-                objectTypeId: objectType.id,
-                datasetId,
-                properties: { ...propertyMapping },
-                links: validatedLinks,
-              }
-            },
+            conflictResolution: { strategy: "editsWin" },
           })
         },
       }
@@ -394,6 +397,60 @@ function buildObjectProjection<const TObjectType extends ObjectType>(
   }
 }
 
+function objectProjectionBuilder<
+  TObjectType extends ObjectType,
+  TDataset extends DatasetDefinition,
+>(input: {
+  readonly id: string
+  readonly objectType: TObjectType
+  readonly datasetId: string
+  readonly propertyMapping: Readonly<Record<string, string>>
+  readonly links: Readonly<Record<string, ForeignKeyDescriptor>>
+  readonly conflictResolution: SourceEditConflictResolution
+}): ObjectProjectionBuilder<TObjectType, TDataset> {
+  const definition: ObjectProjectionDefinition & {
+    readonly conflictResolution: SourceEditConflictResolution
+  } = {
+    _tag: "ObjectProjectionDefinition",
+    id: input.id,
+    objectTypeId: input.objectType.id,
+    datasetId: input.datasetId,
+    properties: { ...input.propertyMapping },
+    links: { ...input.links },
+    conflictResolution: { ...input.conflictResolution },
+  }
+
+  return Object.assign(definition, {
+    withLinks(
+      linkMapping: {
+        [K in LinkIdOf<TObjectType>]?: ProjectionForeignKeyInput<TObjectType, TDataset, K>
+      }
+    ): ObjectProjectionBuilder<TObjectType, TDataset> {
+      const loweredLinkMapping = lowerForeignKeyMapping(linkMapping)
+      const validatedLinks = validateAndLowerLinkMapping(
+        input.objectType,
+        loweredLinkMapping,
+        input.propertyMapping as Record<string, string>
+      )
+      return objectProjectionBuilder({ ...input, links: validatedLinks })
+    },
+    resolveConflicts(
+      resolution: ObjectProjectionConflictResolution<TDataset>
+    ): ObjectProjectionBuilder<TObjectType, TDataset> {
+      validateConflictResolution(resolution)
+      return objectProjectionBuilder({
+        ...input,
+        conflictResolution: resolution as SourceEditConflictResolution,
+      })
+    },
+  })
+}
+
+function validateConflictResolution(resolution: SourceEditConflictResolution): void {
+  if (resolution.strategy === "editsWin") return
+  assertNonEmpty(resolution.sourceTimestamp, "source timestamp field")
+}
+
 // ── Telemetry projection ────────────────────────────────────
 
 interface TelemetryProjectionSourceBuilder<TPropertyToken extends TelemetryPropertyToken> {
@@ -672,10 +729,18 @@ export function isObjectProjectionDefinition(value: unknown): value is ObjectPro
     typeof value.objectTypeId === "string" &&
     typeof value.datasetId === "string" &&
     isRecord(value.properties) &&
-    isRecord(value.links)
+    isRecord(value.links) &&
+    isSourceEditConflictResolution(value.conflictResolution)
   )
 }
 
+function isSourceEditConflictResolution(value: unknown): boolean {
+  if (value === undefined) return true
+  if (!isRecord(value) || typeof value.strategy !== "string") return false
+  if (value.strategy === "editsWin") return value.sourceTimestamp === undefined
+  return value.strategy === "mostRecent" && typeof value.sourceTimestamp === "string"
+}
+
 /** Runtime type guard for {@link LinkProjectionDefinition}. */
 export function isLinkProjectionDefinition(value: unknown): value is LinkProjectionDefinition {
   if (!isRecord(value)) return false

package/src/projections/index.ts

@@ -1,5 +1,10 @@
 // ── Builders ─────────────────────────────────────────────────
 
+export type {
+  ObjectProjectionBuilder,
+  ObjectProjectionConflictResolution,
+  ProjectionForeignKeyInput,
+} from "./builders"
 export {
   categorizeProjections,
   defineProjection,
@@ -24,6 +29,7 @@ export type {
   ProjectionKind,
   ProjectionTarget,
   ProjectionTargetByKind,
+  SourceEditConflictResolution,
   TelemetryProjectionDefinition,
 } from "./types"
 // ── Validation ───────────────────────────────────────────────

package/src/projections/internal.ts

@@ -7,7 +7,9 @@ import type { ProjectionDispatchDescriptor } from "./types"
  *
  * `projectionTargetOf` derives the object types a projection writes, to record them on the run.
  * `validateTelemetryProjectionFieldMapping` re-checks a telemetry mapping against the dataset schema
- * before writing. Both are plumbing, so they live here instead of on the `@sixb/core` root.
+ * before writing. `parseDatasetTimestamp` keeps worker timestamps aligned with the materializer's
+ * authoritative validation. These are plumbing, so they live here instead of on the
+ * `@sixb/core` root.
  */
 export { projectionTargetOf } from "./builders"
 export {
@@ -27,6 +29,7 @@ export {
   ProjectionRunDispatcher,
 } from "./run-dispatch"
 export { createProjectionRunId } from "./run-id"
+export { parseDatasetTimestamp } from "./timestamp"
 export { validateTelemetryProjectionFieldMapping } from "./validation"
 
 export type { ProjectionDispatchDescriptor, ProjectionMaterializationIdentity, ProjectionRegistry }

package/src/projections/registry.ts

@@ -241,6 +241,13 @@ function cloneObjectProjectionDefinition(
         },
       ])
     ),
+    conflictResolution:
+      projection.conflictResolution?.strategy === "mostRecent"
+        ? {
+            strategy: "mostRecent",
+            sourceTimestamp: projection.conflictResolution.sourceTimestamp,
+          }
+        : { strategy: "editsWin" },
   }
 }
 

package/src/projections/revision.ts

@@ -147,6 +147,7 @@ function normalizeProjectionDefinition(projection: ProjectionDefinition): JsonVa
             },
           ])
       ),
+      conflictResolution: projection.conflictResolution ?? { strategy: "editsWin" },
     }
   }
   if (projection._tag === "LinkProjectionDefinition") {
@@ -177,6 +178,9 @@ function projectionColumns(projection: ProjectionDefinition): Set<string> {
       ...Object.values(projection.links).flatMap((link) =>
         link.sourceField === undefined ? [] : [link.sourceField]
       ),
+      ...(projection.conflictResolution?.strategy === "mostRecent"
+        ? [projection.conflictResolution.sourceTimestamp]
+        : []),
     ])
   }
   if (projection._tag === "LinkProjectionDefinition") {

package/src/projections/timestamp.ts

@@ -0,0 +1,66 @@
+const DATASET_TIMESTAMP =
+  /^(\d{4})-(\d{1,2})-(\d{1,2})(?:[ T](\d{1,2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?)?([zZ]|[+-]\d{2}:?\d{2})?$/
+
+interface TimestampComponents {
+  readonly year: number
+  readonly month: number
+  readonly day: number
+  readonly hour: number
+  readonly minute: number
+  readonly second: number
+  readonly milliseconds: number
+}
+
+/** Parses a projection dataset timestamp, interpreting zone-less values as UTC. */
+export function parseDatasetTimestamp(value: unknown): Date | null {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value
+  if (typeof value !== "string") return null
+
+  const match = DATASET_TIMESTAMP.exec(value.trim())
+  if (!match) return null
+  const [, year, month, day, hour, minute, second, fraction, zone] = match
+  const offsetMinutes = parseZoneOffsetMinutes(zone)
+  if (offsetMinutes === null) return null
+
+  const components: TimestampComponents = {
+    year: Number(year),
+    month: Number(month),
+    day: Number(day),
+    hour: hour === undefined ? 0 : Number(hour),
+    minute: minute === undefined ? 0 : Number(minute),
+    second: second === undefined ? 0 : Number(second),
+    milliseconds: fraction === undefined ? 0 : Math.trunc(Number(`0.${fraction}`) * 1000),
+  }
+  const wallClock = Date.UTC(
+    components.year,
+    components.month - 1,
+    components.day,
+    components.hour,
+    components.minute,
+    components.second,
+    components.milliseconds
+  )
+  if (!wallClockMatchesComponents(wallClock, components)) return null
+  return new Date(wallClock - offsetMinutes * 60_000)
+}
+
+function parseZoneOffsetMinutes(zone: string | undefined): number | null {
+  if (zone === undefined || zone === "Z" || zone === "z") return 0
+  const digits = zone.slice(1).replace(":", "")
+  const hours = Number(digits.slice(0, 2))
+  const minutes = Number(digits.slice(2, 4))
+  if (hours > 23 || minutes > 59) return null
+  return (zone[0] === "-" ? -1 : 1) * (hours * 60 + minutes)
+}
+
+function wallClockMatchesComponents(wallClock: number, components: TimestampComponents): boolean {
+  const date = new Date(wallClock)
+  return (
+    date.getUTCFullYear() === components.year &&
+    date.getUTCMonth() === components.month - 1 &&
+    date.getUTCDate() === components.day &&
+    date.getUTCHours() === components.hour &&
+    date.getUTCMinutes() === components.minute &&
+    date.getUTCSeconds() === components.second
+  )
+}

package/src/projections/types.ts

@@ -39,6 +39,11 @@ export interface ForeignKeyDescriptor {
   readonly targetObjectTypeId: string
 }
 
+/** Resolves competing source-projection and managed-edit values for projected properties. */
+export type SourceEditConflictResolution =
+  | { readonly strategy: "editsWin" }
+  | { readonly strategy: "mostRecent"; readonly sourceTimestamp: string }
+
 /**
  * Lowered, serializable definition for projecting a dataset into object instances.
  *
@@ -56,6 +61,8 @@ export interface ObjectProjectionDefinition {
   readonly properties: Readonly<Record<string, string>>
   /** Maps link id -> FK descriptor. Empty `{}` when no FK links are projected. */
   readonly links: Readonly<Record<string, ForeignKeyDescriptor>>
+  /** Defaults to `editsWin` when omitted by a legacy lowered definition. */
+  readonly conflictResolution?: SourceEditConflictResolution
 }
 
 /**

package/src/projections/validation.ts

@@ -315,6 +315,30 @@ export function validateProjectionsAtStartup(
     }
 
     const datasetColumnNames = new Set(dataset.schema.columns.map((column) => column.name))
+    const conflictResolution = projection.conflictResolution ?? { strategy: "editsWin" }
+    if (conflictResolution.strategy === "mostRecent") {
+      const sourceTimestamp = dataset.schema.columns.find(
+        (column) => column.name === conflictResolution.sourceTimestamp
+      )
+      if (!sourceTimestamp) {
+        throw new ProjectionValidationError(
+          `${prefix}: source timestamp "${conflictResolution.sourceTimestamp}" references unknown ` +
+            `dataset column on dataset "${projection.datasetId}"`
+        )
+      }
+      if (sourceTimestamp.type !== "timestamp") {
+        throw new ProjectionValidationError(
+          `${prefix}: source timestamp "${conflictResolution.sourceTimestamp}" must reference a ` +
+            `timestamp dataset column`
+        )
+      }
+      if (sourceTimestamp.nullable === true) {
+        throw new ProjectionValidationError(
+          `${prefix}: source timestamp "${conflictResolution.sourceTimestamp}" must reference a ` +
+            `non-null timestamp dataset column`
+        )
+      }
+    }
     const propertyIds = new Set(objectType.properties.map((p) => p.id))
     for (const [propId, columnName] of Object.entries(projection.properties)) {
       if (!propertyIds.has(propId)) {

package/src/queues/index.ts

@@ -4,6 +4,7 @@ export { InMemoryQueues } from "./in-memory"
 export type {
   ActionQueueJobFailureCode,
   ActionRunRequestedQueueJob,
+  AgentAiUsageAccountingPayload,
   AgentAiUsageRecordPayload,
   AgentAiUsageRecordRequestedQueueJob,
   AgentQueueJob,