@mastra/pg 1.31.0 → 1.31.1-alpha.0

package/dist/_types/@internal_core/dist/memory/index.d.ts

@@ -0,0 +1,102 @@
+//#region src/memory/index.d.ts
+/**
+ * Shared rules for observational memory lifecycle writes. Every storage adapter applies
+ * these inside its own atomic section (lock, transaction, or conditional update), so the
+ * decisions are identical across adapters.
+ */
+/**
+ * Observational memory columns that lifecycle writes depend on. Storage adapters merge these
+ * into the table schema they get from `@mastra/core`, so the columns exist even when the
+ * installed core predates them.
+ */
+declare const OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS: {
+  readonly supersededBy: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+};
+/** `schema` plus {@link OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS}; `undefined` when `schema` is. */
+declare function withObservationalMemoryLifecycleColumns<T extends object>(schema: T | undefined): (T & typeof OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS) | undefined;
+/**
+ * Result of `commitActiveObservations`.
+ */
+interface UpdateActiveObservationsResult {
+  /** Whether the observations were written. */
+  applied: boolean;
+  /**
+   * Why nothing was written: `retired` — the target record was superseded by a newer
+   * generation; `conflict` — `expectedActiveObservations` no longer matches the stored text.
+   */
+  reason?: 'retired' | 'conflict';
+}
+/**
+ * Result of `appendBufferedObservations`.
+ *
+ * The append targets the head generation: when `input.id` was superseded, the chunk is
+ * appended to the current head instead. The append is skipped (`persisted: false`) when the
+ * head already holds a chunk with the same `cycleId`, or when the chunk is wholly covered by
+ * the head's cursor. Chunks carry `lastObservedAt = max message time + 1ms`, so a chunk is
+ * wholly covered iff `head.lastObservedAt >= chunk.lastObservedAt - 1ms`.
+ */
+interface UpdateBufferedObservationsResult {
+  /** Whether the chunk was stored. */
+  persisted: boolean;
+  /** The record the chunk was written to (or would have been written to). */
+  recordId: string;
+}
+/** The fields of an observational memory record that decide head order. */
+interface ObservationalMemoryHeadOrderFields {
+  generationCount: number;
+  createdAt: Date | string;
+  id: string;
+}
+/**
+ * Canonical head order: `generationCount DESC, createdAt ASC, id ASC`.
+ * Returns a negative number when `a` sorts before `b` (i.e. `a` is the better head candidate).
+ */
+declare function compareObservationalMemoryHeadOrder(a: ObservationalMemoryHeadOrderFields, b: ObservationalMemoryHeadOrderFields): number;
+/**
+ * A buffered chunk stores `lastObservedAt = max message time + 1ms`. It is wholly covered
+ * (every message it observed is already at or before the cursor) iff
+ * `cursor >= chunk.lastObservedAt - 1ms`.
+ */
+declare function isBufferedChunkCoveredByCursor(chunkLastObservedAt: Date | string, cursor: Date | string | null | undefined): boolean;
+/** The later of two cursors; `undefined` only when both are absent. */
+declare function maxObservationCursor(a: Date | string | null | undefined, b: Date | string | null | undefined): Date | undefined;
+interface ReflectionTextPlan {
+  /** `equal`: stored text equals the snapshot. `append`: observations were appended after the snapshot. */
+  mode: 'equal' | 'append';
+  observations: string;
+  tokenCount: number;
+}
+/**
+ * Decide the new generation's text when a reflection built from `snapshot` commits against
+ * the stored record.
+ *
+ * - Stored text equals the snapshot: the reflection replaces it.
+ * - Stored text extends the snapshot (activation only appends): the appended tail is kept
+ *   after the reflection, and its tokens are added.
+ * - Anything else (a non-append rewrite): `null` — the reflection must not be applied.
+ */
+declare function planReflectionGenerationText(input: {
+  storedObservations: string;
+  storedObservationTokenCount: number;
+  snapshotObservations: string;
+  snapshotObservationTokenCount: number;
+  reflection: string;
+  tokenCount: number;
+}): ReflectionTextPlan | null;
+/**
+ * Backs `updateActiveObservations` in adapters that implement `commitActiveObservations`.
+ * Callers of `updateActiveObservations` (which resolves `void`) can't see a commit result, so a
+ * write that was not applied throws instead of resolving as if it had committed.
+ */
+declare function assertActiveObservationsApplied(result: UpdateActiveObservationsResult, id: string): void;
+/**
+ * Whether the stored text can still accept a reflection built from `snapshot`
+ * (equal, or only appended to since).
+ */
+declare function isAppendOnlySince(storedObservations: string, snapshotObservations: string): boolean;
+//#endregion
+export { OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS, ObservationalMemoryHeadOrderFields, ReflectionTextPlan, UpdateActiveObservationsResult, UpdateBufferedObservationsResult, assertActiveObservationsApplied, compareObservationalMemoryHeadOrder, isAppendOnlySince, isBufferedChunkCoveredByCursor, maxObservationCursor, planReflectionGenerationText, withObservationalMemoryLifecycleColumns };
+//# sourceMappingURL=index.d.ts.map

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-pg
 description: Documentation for @mastra/pg. Use when working with @mastra/pg APIs, configuration, or implementation.
 metadata:
   package: "@mastra/pg"
-  version: "1.31.0"
+  version: "1.31.1-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.31.0",
+  "version": "1.31.1-alpha.0",
   "package": "@mastra/pg",
   "exports": {},
   "modules": {}