@salesforce/agentic-common 0.6.0 → 0.8.0

package/README.md

@@ -309,6 +309,24 @@ type FrontmatterSplit = {
 };
 ```
 
+### `backfillCreatedAt<T extends { createdAt?: Date }>(messages: T[], clock: Clock): T[]`
+
+Backfills missing `createdAt` timestamps on a batch of message-shaped records, stepping per-position via
+`clock.nextAfter` so a bulk insert produces strictly-ascending timestamps rather than ms-precision ties tie-broken by
+stable sort. Records that already carry a `createdAt` pass through unchanged (same reference, no clone). Records missing
+one are cloned with a freshly-stepped value: the first missing position seeds from `clock.now()`, each subsequent
+missing position uses `clock.nextAfter(<prior>)`.
+
+Used by `sfdx-agent-sdk`'s `ChatSession.addContext()` and both harnesses' `addContext` boundaries so the read-side
+"every Message has populated `createdAt`; sort ascending" contract is upheld regardless of consumer-construction style.
+Generic over the record shape, so any consumer with a `createdAt?: Date` field can reuse the same policy.
+
+```typescript
+import { backfillCreatedAt, RealClock } from '@salesforce/agentic-common';
+
+const filled = backfillCreatedAt(messages, new RealClock());
+```
+
 ## Development
 
 See [DEVELOPING.md](../../DEVELOPING.md) for build-from-source setup, scripts, and monorepo commands.

package/dist/backfill-created-at.d.ts

@@ -0,0 +1,24 @@
+import type { Clock } from './clock.js';
+/**
+ * Backfills missing `createdAt` timestamps on a batch of message-shaped
+ * records, stepping per-position via `clock.nextAfter` so a bulk insert
+ * produces strictly-ascending timestamps rather than ms-precision ties
+ * tie-broken by stable sort.
+ *
+ * Records that already carry a `createdAt` are returned unchanged (same
+ * reference, no clone). Records missing one are cloned with a freshly-
+ * stepped `createdAt`. The first missing position seeds from `clock.now()`;
+ * each subsequent missing position uses `clock.nextAfter(<prior>)`.
+ *
+ * Generic over the record shape so this can be reused by:
+ * - The SDK's `DefaultChatSession.addContext` (over `Message`)
+ * - Both production harnesses' `addContext` boundaries
+ *
+ * Anywhere the message-shape contract requires an ascending sortable
+ * timestamp, this is the single backfill site so the three implementations
+ * can't drift on subtle policy questions (clamp-to-lastExplicit, behavior
+ * at the boundary between explicit and implicit positions, etc.).
+ */
+export declare function backfillCreatedAt<T extends {
+    createdAt?: Date;
+}>(messages: T[], clock: Clock): T[];

package/dist/backfill-created-at.js

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Backfills missing `createdAt` timestamps on a batch of message-shaped
+ * records, stepping per-position via `clock.nextAfter` so a bulk insert
+ * produces strictly-ascending timestamps rather than ms-precision ties
+ * tie-broken by stable sort.
+ *
+ * Records that already carry a `createdAt` are returned unchanged (same
+ * reference, no clone). Records missing one are cloned with a freshly-
+ * stepped `createdAt`. The first missing position seeds from `clock.now()`;
+ * each subsequent missing position uses `clock.nextAfter(<prior>)`.
+ *
+ * Generic over the record shape so this can be reused by:
+ * - The SDK's `DefaultChatSession.addContext` (over `Message`)
+ * - Both production harnesses' `addContext` boundaries
+ *
+ * Anywhere the message-shape contract requires an ascending sortable
+ * timestamp, this is the single backfill site so the three implementations
+ * can't drift on subtle policy questions (clamp-to-lastExplicit, behavior
+ * at the boundary between explicit and implicit positions, etc.).
+ */
+export function backfillCreatedAt(messages, clock) {
+    let last;
+    return messages.map((m) => {
+        if (m.createdAt)
+            return m;
+        last = last ? clock.nextAfter(last) : clock.now();
+        return { ...m, createdAt: last };
+    });
+}
+//# sourceMappingURL=backfill-created-at.js.map

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { backfillCreatedAt } from './backfill-created-at.js';
 export { Clock, RealClock } from './clock.js';
 export { type OrgConnection, RealOrgConnection } from './connection.js';
 export { type OrgConnectionFactory, RealOrgConnectionFactory } from './connection-factory.js';

package/dist/index.js

@@ -2,6 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+export { backfillCreatedAt } from './backfill-created-at.js';
 export { Clock, RealClock } from './clock.js';
 export { RealOrgConnection } from './connection.js';
 export { RealOrgConnectionFactory } from './connection-factory.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/agentic-common",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Shared primitives and common utilities for the Salesforce agentic DX packages",
   "type": "module",
   "exports": {