@abloatai/humans 0.37.0

package/dist/local/transactions/mutations/replayValidation.d.ts

@@ -0,0 +1,187 @@
+/**
+ * The validation boundary for replaying persisted transactions after a restart.
+ *
+ * Rows read back from the on-disk transaction store may have been written by an
+ * earlier run — possibly by an older version of this package, possibly
+ * corrupted. Rather than trust them, the schemas here validate exactly the
+ * fields the settlement queue and the local journal restore read during
+ * replay. A row that fails to parse is dropped and reported, never replayed as
+ * a malformed commit.
+ *
+ * The same store also holds two kinds of rows that are not replayable
+ * transactions — the legacy local mutation journal (`type: 'queue'`) and delta-await
+ * markers (`type: 'awaiting_delta'`), each owned by another part of the client.
+ * {@link isNonReplayablePersistedRow} recognizes them so they are skipped
+ * quietly rather than flagged as corruption.
+ */
+import { z } from 'zod';
+import type { QueuedMutation } from './commitPayload.js';
+import type { RuntimeContext } from '../../RuntimeContext.js';
+/**
+ * The shape of a persisted transaction that can be replayed: the fields the
+ * transaction queue reads when it re-enqueues the row — its id, operation type,
+ * model addressing, payload, and identity context. Any remaining bookkeeping is
+ * filled in with defaults when the row is rehydrated by
+ * {@link deserializePersistedTransaction}.
+ */
+export declare const persistedTransactionSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        update: "update";
+        create: "create";
+        delete: "delete";
+        archive: "archive";
+        unarchive: "unarchive";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    modelKey: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    context: z.ZodObject<{
+        userId: z.ZodString;
+        organizationId: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+        teamIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    createdAt: z.ZodOptional<z.ZodNumber>;
+    batchId: z.ZodOptional<z.ZodString>;
+    commitEnvelope: z.ZodOptional<z.ZodObject<{
+        idempotencyKey: z.core.$ZodBranded<z.ZodString, "IdempotencyKey", "out">;
+        operationIndex: z.ZodNumber;
+        operationCount: z.ZodNumber;
+        sealedAt: z.ZodOptional<z.ZodNumber>;
+        sequence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    sourceMutationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    writeOptions: z.ZodOptional<z.ZodObject<{
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>;
+    localOnly: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export type PersistedReplayableTransaction = z.infer<typeof persistedTransactionSchema>;
+/**
+ * Reports whether a stored row is one of the non-transaction kinds, so callers
+ * skip it instead of treating it as a corrupt transaction.
+ */
+export declare function isNonReplayablePersistedRow(row: unknown): boolean;
+/**
+ * Validates one stored row and rehydrates it into a {@link QueuedMutation} ready
+ * to replay, or returns `null` when the row fails validation. Bookkeeping
+ * fields the stored row lacks — status, attempts, priority, timestamp — are
+ * re-derived the same way a freshly staged transaction derives them.
+ */
+export declare function deserializePersistedTransaction(row: unknown, runtime?: RuntimeContext): QueuedMutation | null;
+/**
+ * The shape of one entry in the persisted legacy local mutation journal — an item of
+ * the `'queue'` row's `mutations` array, carrying the fields read when the
+ * queue is restored on reconnect.
+ */
+export declare const persistedMutationSchema: z.ZodObject<{
+    mutationId: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<{
+        update: "update";
+        create: "create";
+        delete: "delete";
+        archive: "archive";
+    }>;
+    modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    modelName: z.ZodString;
+    timestamp: z.ZodString;
+    capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    writeOptions: z.ZodOptional<z.ZodObject<{
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type PersistedQueuedMutation = z.infer<typeof persistedMutationSchema>;
+export declare const PENDING_MUTATION_RECORD_PREFIX = "pending-mutation:";
+/**
+ * Stay one hour inside the server's 24-hour idempotency retention window.
+ * A journaled write older than this can no longer be deduplicated by the
+ * server, so restore holds it for review instead of replaying it.
+ */
+export declare const PENDING_MUTATION_REPLAY_WINDOW_MS: number;
+/** Scope-less records written by the first aggregate-journal release. */
+export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
+    storageVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    type: z.ZodLiteral<"pending_mutation">;
+    mutation: z.ZodObject<{
+        type: z.ZodEnum<{
+            update: "update";
+            create: "create";
+            delete: "delete";
+            archive: "archive";
+        }>;
+        modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        modelName: z.ZodString;
+        timestamp: z.ZodString;
+        capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        writeOptions: z.ZodOptional<z.ZodObject<{
+            readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>>;
+            idempotencyKey: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>;
+        mutationId: z.ZodString;
+    }, z.core.$loose>;
+    timestamp: z.ZodNumber;
+}, z.core.$strict>;
+export declare const pendingMutationRecordSchema: z.ZodObject<{
+    storageVersion: z.ZodLiteral<2>;
+    scope: z.ZodObject<{
+        organizationId: z.ZodString;
+        participantId: z.ZodString;
+        namespace: z.ZodString;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    type: z.ZodLiteral<"pending_mutation">;
+    mutation: z.ZodObject<{
+        type: z.ZodEnum<{
+            update: "update";
+            create: "create";
+            delete: "delete";
+            archive: "archive";
+        }>;
+        modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        modelName: z.ZodString;
+        timestamp: z.ZodString;
+        capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        writeOptions: z.ZodOptional<z.ZodObject<{
+            readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>>;
+            idempotencyKey: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            fenceToken: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$loose>>;
+        mutationId: z.ZodString;
+    }, z.core.$loose>;
+    timestamp: z.ZodNumber;
+}, z.core.$strict>;
+export type PendingMutationRecord = z.infer<typeof pendingMutationRecordSchema>;
+export declare function pendingMutationRecordId(mutationId: string): string;

package/dist/local/transactions/mutations/replayValidation.js

@@ -0,0 +1,164 @@
+/**
+ * The validation boundary for replaying persisted transactions after a restart.
+ *
+ * Rows read back from the on-disk transaction store may have been written by an
+ * earlier run — possibly by an older version of this package, possibly
+ * corrupted. Rather than trust them, the schemas here validate exactly the
+ * fields the settlement queue and the local journal restore read during
+ * replay. A row that fails to parse is dropped and reported, never replayed as
+ * a malformed commit.
+ *
+ * The same store also holds two kinds of rows that are not replayable
+ * transactions — the legacy local mutation journal (`type: 'queue'`) and delta-await
+ * markers (`type: 'awaiting_delta'`), each owned by another part of the client.
+ * {@link isNonReplayablePersistedRow} recognizes them so they are skipped
+ * quietly rather than flagged as corruption.
+ */
+import { z } from 'zod';
+import { computePriorityScore, normalizeModelKey } from './commitPayload.js';
+import { globalRuntime } from '../../context.js';
+import { commitEnvelopeMemberSchema, commitOutboxScopeSchema, } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import { onStaleModeSchema } from '@abloatai/transaction/coordination/schema';
+/** The subset of a write's options that is stored with each transaction or queued mutation. */
+const persistedWriteOptionsSchema = z
+    .object({
+    readAt: z.number().nullable().optional(),
+    onStale: onStaleModeSchema.nullable().optional(),
+    idempotencyKey: z.string().optional(),
+    label: z.string().optional(),
+    // Aligned with the `WriteOptions` type: a claimed write persisted locally
+    // must replay carrying its fencing token (Option B), or a queued write that
+    // survives a reload would lose its fence and could land as a stale blind
+    // write. Declared (not just loose-passthrough) so it is validated as a
+    // number on rehydration.
+    fenceToken: z.number().nullable().optional(),
+})
+    .loose();
+/**
+ * The shape of a persisted transaction that can be replayed: the fields the
+ * transaction queue reads when it re-enqueues the row — its id, operation type,
+ * model addressing, payload, and identity context. Any remaining bookkeeping is
+ * filled in with defaults when the row is rehydrated by
+ * {@link deserializePersistedTransaction}.
+ */
+export const persistedTransactionSchema = z
+    .object({
+    id: z.string().min(1),
+    type: z.enum(['create', 'update', 'delete', 'archive', 'unarchive']),
+    modelName: z.string().min(1),
+    modelId: z.string().min(1),
+    modelKey: z.string().min(1).optional(),
+    data: z.record(z.string(), z.unknown()).optional(),
+    previousData: z.record(z.string(), z.unknown()).nullable().optional(),
+    context: z.object({
+        userId: z.string().min(1),
+        organizationId: z.string().min(1),
+        role: z.string().optional(),
+        teamIds: z.array(z.string()).optional(),
+    }),
+    createdAt: z.number().optional(),
+    batchId: z.string().optional(),
+    commitEnvelope: commitEnvelopeMemberSchema.optional(),
+    sourceMutationIds: z.array(z.string().min(1)).optional(),
+    writeOptions: persistedWriteOptionsSchema.optional(),
+    localOnly: z.boolean().optional(),
+})
+    .loose();
+/** The `type` values of stored rows that belong to other parts of the client and are not replayable transactions. */
+const NON_REPLAYABLE_TYPES = new Set([
+    'queue',
+    'awaiting_delta',
+    'pending_mutation',
+    'commit_envelope',
+    'http_commit_envelope',
+]);
+/**
+ * Reports whether a stored row is one of the non-transaction kinds, so callers
+ * skip it instead of treating it as a corrupt transaction.
+ */
+export function isNonReplayablePersistedRow(row) {
+    return (typeof row === 'object' &&
+        row !== null &&
+        typeof row.type === 'string' &&
+        NON_REPLAYABLE_TYPES.has(row.type));
+}
+/**
+ * Validates one stored row and rehydrates it into a {@link QueuedMutation} ready
+ * to replay, or returns `null` when the row fails validation. Bookkeeping
+ * fields the stored row lacks — status, attempts, priority, timestamp — are
+ * re-derived the same way a freshly staged transaction derives them.
+ */
+export function deserializePersistedTransaction(row, runtime = globalRuntime) {
+    const parsed = persistedTransactionSchema.safeParse(row);
+    if (!parsed.success)
+        return null;
+    const tx = parsed.data;
+    return {
+        id: tx.id,
+        type: tx.type,
+        modelName: tx.modelName,
+        modelId: tx.modelId,
+        modelKey: tx.modelKey ?? normalizeModelKey(tx.modelName),
+        ...(tx.data !== undefined ? { data: tx.data } : {}),
+        ...(tx.previousData !== undefined ? { previousData: tx.previousData } : {}),
+        context: tx.context,
+        status: 'pending',
+        createdAt: tx.createdAt ?? Date.now(),
+        attempts: 0,
+        priority: 'normal',
+        priorityScore: computePriorityScore(tx.type, tx.modelName, runtime),
+        ...(tx.batchId !== undefined ? { batchId: tx.batchId } : {}),
+        ...(tx.commitEnvelope !== undefined
+            ? { commitEnvelope: tx.commitEnvelope }
+            : {}),
+        ...(tx.sourceMutationIds !== undefined
+            ? { sourceMutationIds: tx.sourceMutationIds }
+            : {}),
+        ...(tx.writeOptions !== undefined ? { writeOptions: tx.writeOptions } : {}),
+        ...(tx.localOnly !== undefined ? { localOnly: tx.localOnly } : {}),
+    };
+}
+/**
+ * The shape of one entry in the persisted legacy local mutation journal — an item of
+ * the `'queue'` row's `mutations` array, carrying the fields read when the
+ * queue is restored on reconnect.
+ */
+export const persistedMutationSchema = z
+    .object({
+    mutationId: z.string().min(1).optional(),
+    type: z.enum(['create', 'update', 'delete', 'archive']),
+    modelData: z.record(z.string(), z.unknown()),
+    modelName: z.string().min(1),
+    timestamp: z.string(),
+    capturedChanges: z.record(z.string(), z.unknown()).optional(),
+    writeOptions: persistedWriteOptionsSchema.optional(),
+})
+    .loose();
+export const PENDING_MUTATION_RECORD_PREFIX = 'pending-mutation:';
+/**
+ * Stay one hour inside the server's 24-hour idempotency retention window.
+ * A journaled write older than this can no longer be deduplicated by the
+ * server, so restore holds it for review instead of replaying it.
+ */
+export const PENDING_MUTATION_REPLAY_WINDOW_MS = 23 * 60 * 60 * 1000;
+const pendingMutationRecordBaseShape = {
+    id: z.string().startsWith(PENDING_MUTATION_RECORD_PREFIX),
+    type: z.literal('pending_mutation'),
+    mutation: persistedMutationSchema.extend({
+        mutationId: z.string().min(1),
+    }),
+    timestamp: z.number().int().nonnegative(),
+};
+/** Scope-less records written by the first aggregate-journal release. */
+export const legacyPendingMutationRecordSchema = z.strictObject({
+    ...pendingMutationRecordBaseShape,
+    storageVersion: z.literal(1),
+});
+export const pendingMutationRecordSchema = z.strictObject({
+    ...pendingMutationRecordBaseShape,
+    storageVersion: z.literal(2),
+    scope: commitOutboxScopeSchema,
+});
+export function pendingMutationRecordId(mutationId) {
+    return `${PENDING_MUTATION_RECORD_PREFIX}${mutationId}`;
+}

package/dist/local/transactions/reconnectDrain.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Human-side reconnect adapter.
+ *
+ * The settlement callback owns ordering and receipts. This adapter owns the
+ * local client's reconnect concurrency: repeated online/connect signals join
+ * the same drain instead of starting competing local recovery passes.
+ */
+export interface ReconnectDrain {
+    drain(run: () => Promise<void>): Promise<void>;
+}
+export declare function createReconnectDrain(): ReconnectDrain;

package/dist/local/transactions/reconnectDrain.js

@@ -0,0 +1,13 @@
+export function createReconnectDrain() {
+    let inFlight = null;
+    return {
+        drain(run) {
+            if (inFlight)
+                return inFlight;
+            inFlight = run().finally(() => {
+                inFlight = null;
+            });
+            return inFlight;
+        },
+    };
+}

package/dist/local/utils/mobxSetup.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Wires a model instance into MobX so its schema-defined fields become
+ * observable and its mutations are tracked. This module reads the property
+ * metadata generated from a schema and applies the matching MobX annotation to
+ * each field, leaving any hand-written getter or setter in place.
+ */
+import { type AnnotationMapEntry } from 'mobx';
+import { type PropertyMetadata, type ReferenceMetadata } from '@abloatai/transaction/types';
+/**
+ * The subset of a model instance that {@link M1} reads and writes. A model calls
+ * {@link M1} from its constructor, where these members exist on `this`;
+ * declaring them here lets {@link M1} reference them without loose casts. Every
+ * member is optional, so a partial model — such as a test fixture — still
+ * satisfies the type.
+ */
+interface M1Target {
+    _hasCustomObservability?: boolean;
+    _isConstructing?: boolean;
+    _extraMobxAnnotations?: Record<string, AnnotationMapEntry>;
+    setupObservability?(): void;
+    propertyChanged?(name: string, oldValue: unknown, newValue: unknown): void;
+}
+/**
+ * Makes a model instance's schema-defined properties observable with MobX. For
+ * each field it reads the {@link PropertyMetadata} and applies the matching MobX
+ * annotation — a plain observable for stored values, a computed for derived
+ * getters, and an action for mutating methods — while leaving any field that
+ * already declares its own getter and setter untouched. If the model provides
+ * its own `setupObservability` or sets `_hasCustomObservability`, this function
+ * defers to it and does nothing.
+ */
+export declare function M1<T extends M1Target>(target: T, propertyMetadata: Map<string, PropertyMetadata>, referenceMetadata?: Map<string, ReferenceMetadata>): void;
+/**
+ * Wraps a model class so every instance is made observable at construction time
+ * by calling {@link M1}. A class that manages its own observability — one whose
+ * prototype declares `setupObservability` or `_hasCustomObservability` — is
+ * returned unchanged. The wrapper preserves the original class name and its
+ * static members.
+ */
+export declare function makeModelObservable(modelClass: any, propertyMetadata: Map<string, PropertyMetadata>, referenceMetadata?: Map<string, any>): any;
+/**
+ * Reports whether a named property is one that {@link M1} makes observable —
+ * that is, a stored value, an ephemeral value, a reference collection, or a
+ * reference array. Returns `false` for an unknown property and for a computed
+ * reference.
+ */
+export declare function isObservableProperty(target: any, propName: string, propertyMetadata: Map<string, PropertyMetadata>): boolean;
+/**
+ * Returns the names of the properties that {@link M1} treats as computed: the
+ * referenced-model and back-reference fields derived from a foreign key.
+ */
+export declare function getComputedProperties(propertyMetadata: Map<string, PropertyMetadata>): string[];
+export {};