@acquiredintelligence/attend 0.0.0-stage → 0.2.0

package/dist/store/types.d.ts

@@ -0,0 +1,137 @@
+import type { DecisionAppend, DeliveredRoute, LoggedInput, ScopeRecord, SettlePolicy } from '../core/types.js';
+/** A snapshot is a ScopeRecord plus what replay needs: the policy and the reducer version it was taken under. */
+export interface Snapshot {
+    version: number;
+    record: ScopeRecord;
+    policy: SettlePolicy;
+    reducer: number;
+}
+/** A scope as stored: the latest snapshot and every input committed after it, oldest first. */
+export interface StoredScope {
+    version: number;
+    snapshot: Snapshot | null;
+    tail: readonly LoggedInput[];
+}
+/**
+ * One scope's part of a group commit. It applies iff the stored version equals
+ * `expectedVersion`; 0 means no stored scope. On success the stored version becomes
+ * `expectedVersion + inputs.length`. A snapshot is always taken at the write's final version: it
+ * replaces the stored one and trims every input at or below its version, so an adapter writes no
+ * input rows for a write that carries one. Everything in one write lands together or not at all.
+ */
+export interface ScopeWrite {
+    scope: string;
+    expectedVersion: number;
+    inputs: readonly LoggedInput[];
+    snapshot: Snapshot | null;
+    /** The coarse due value, already rounded up to the second by the shell, and stored as given. Undefined: unchanged. Null: clear it. */
+    due?: number | null;
+    appends: readonly DecisionAppend[];
+    serialized?: SerializedWrite;
+}
+/**
+ * The JSON of a write's pieces, made when each piece was produced, so a group commit only binds
+ * strings. `inputs[i]` is `JSON.stringify(write.inputs[i])`; `snapshot` is
+ * `JSON.stringify(write.snapshot.record)`, or null without a snapshot; `appends[i]` is
+ * `JSON.stringify(write.appends[i].body)`. The shell sets it on every write to a durable store,
+ * and the memory store ignores it.
+ */
+export interface SerializedWrite {
+    inputs: string[];
+    snapshot: string | null;
+    appends: string[];
+}
+export type CommitOutcome = 'ok' | 'conflict';
+/** A keyset position in the due index: ascending by `due`, then `scope`. */
+export interface DueKey {
+    due: number;
+    scope: string;
+}
+/**
+ * The store port. `commit` resolves once the group is durable, with one outcome per write, in
+ * order. Writes for different scopes are independent: a conflict changes nothing for its scope,
+ * and the others commit. A group that names one scope twice rejects. A rejected `commit` applied
+ * nothing. Every value a store returns is plain, cloneable data that it never changes afterwards,
+ * and a store never changes the writes or queries it is given. Proven by `scopeStoreConformance`
+ * and `decisionLogConformance`.
+ */
+export interface ScopeStore {
+    /** False for the memory store: snapshots and inputs survive the instance, not the process. */
+    readonly durable: boolean;
+    load(scope: string): Promise<StoredScope | null>;
+    commit(writes: readonly ScopeWrite[]): Promise<readonly CommitOutcome[]>;
+    /** Scopes whose due value is <= now, ascending by (due, scope), strictly after `after`, at most `limit`. A read, not a claim. */
+    due(now: number, limit: number, after?: DueKey): Promise<DueKey[]>;
+    /** Forgets the scope: a later load is null, it is no longer due, and a commit at version 0 succeeds. */
+    remove(scope: string): Promise<void>;
+    readonly log: DecisionLog;
+    /** Releases what the store itself opened, such as a worker. Never closes a client the app passed in. */
+    close?(): Promise<void>;
+}
+/** Opaque, and ordered by `DecisionLog.compare`: a memory sequence number, a SQLite rowid, a Postgres `txid.n`, a Redis stream id. */
+export type Position = string;
+export type DecisionKind = DecisionAppend['kind'];
+export type DecisionRow = DecisionAppend & {
+    position: Position;
+};
+export interface DecisionQuery {
+    /** Strictly after this position; null starts from the oldest retained row. */
+    after: Position | null;
+    /** Only this scope. Rows of other scopes are never examined. */
+    scope?: string;
+    /** Scopes that start with this. Like `kinds` and `routes`, every row examined counts toward `scanLimit`. */
+    scopePrefix?: string;
+    kinds?: readonly DecisionKind[];
+    /** Rows whose route is one of these. A row with a null route never matches. */
+    routes?: readonly DeliveredRoute[];
+    /** Skip rows decided before this instant. */
+    sinceAt?: number;
+    limit: number;
+    /** Rows examined before stopping with `more: true`. Default 4 × `limit`. */
+    scanLimit?: number;
+}
+export interface DecisionPage {
+    /** Matching rows, oldest first. */
+    rows: DecisionRow[];
+    /**
+     * The position checked up to, whether or not anything matched: the cursor to hand out. When
+     * `more` is false it is the head the read saw (never behind `after`, and null on an empty log).
+     * When `more` is true it is the last row examined, so reading on from it skips nothing.
+     */
+    checked: Position | null;
+    /** True when the read stopped at `limit` or `scanLimit` with rows left past `checked`; false when it reached the head. */
+    more: boolean;
+}
+export interface LogBounds {
+    /** The retention floor: the oldest readable position. */
+    first: Position | null;
+    /** The head: the newest readable position. */
+    last: Position | null;
+}
+export interface Retention {
+    olderThanMs?: number;
+    maxRows?: number;
+}
+/**
+ * Decisions and dead letters in one total order per store, written only by `ScopeStore.commit`
+ * in the same commit as the input that produced them. An append whose (kind, id) is already
+ * logged is skipped, and its write still commits. A reader never sees a row appear below a
+ * position it has already read.
+ */
+export interface DecisionLog {
+    /** Names the log's incarnation: random per instance for memory, persistent for durable stores. */
+    epoch(): Promise<string>;
+    bounds(): Promise<LogBounds>;
+    read(query: DecisionQuery): Promise<DecisionPage>;
+    find(kind: DecisionKind, id: string): Promise<DecisionRow | null>;
+    /** Resolves when the head passes `after`, after `blockMs`, or on abort. Never rejects. */
+    wait(after: Position | null, blockMs: number, signal: AbortSignal): Promise<void>;
+    /**
+     * Drops rows from the oldest end: keeps at most `maxRows` newest rows, and drops leading rows
+     * whose `at` is older than `Date.now() - olderThanMs`. Never drops the head.
+     */
+    trim(retention: Retention): Promise<void>;
+    /** Negative, zero or positive, as `a` comes before, equals or follows `b`. */
+    compare(a: Position, b: Position): number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/store/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/store/types.ts"],"names":[],"mappings":"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"}

package/dist/store/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/store/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/store/types.ts"],"names":[],"mappings":""}

package/dist/testing/conformance.d.ts

@@ -0,0 +1,13 @@
+import type { ConformanceCase } from '../testing.js';
+import type { ScopeStore } from '../store/types.js';
+/** Every guarantee in ScopeStore's doc comments, as cases. `make` returns a fresh, empty store per case. */
+export declare function scopeStoreConformance(make: () => Promise<ScopeStore> | ScopeStore): ConformanceCase[];
+/**
+ * Every guarantee in DecisionLog's doc comments. With `concurrent`, which returns two stores over
+ * one database, it also checks that a reader never skips a row while two writers commit at once,
+ * and that durable stores share an epoch.
+ */
+export declare function decisionLogConformance(make: () => Promise<ScopeStore> | ScopeStore, options?: {
+    concurrent?: () => Promise<[ScopeStore, ScopeStore]>;
+}): ConformanceCase[];
+//# sourceMappingURL=conformance.d.ts.map

package/dist/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../src/testing/conformance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,KAAK,EAAwC,UAAU,EAAwB,MAAM,mBAAmB,CAAC;AA4HhH,4GAA4G;AAC5G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,GAAG,eAAe,EAAE,CAkLrG;AA4BD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,EAAE,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAA;CAAE,GAAG,eAAe,EAAE,CA2M1K"}