nexus-ai-pro 2.8.0 → 2.9.0

package/dist/lifecycle/budget.js

@@ -1,12 +1,47 @@
 import { BudgetExceededError } from '../core/lifecycle.js';
+import { randomHex } from '../utils/ids.js';
 import { periodEnd, periodStart } from '../utils/periods.js';
+import { MemoryReservationBook } from './reservations.js';
+const DEFAULT_LEASE_MS = 10 * 60 * 1000;
+const FROM = {
+    settled: ['reserved', 'uncertain', 'expired'],
+    released: ['reserved', 'uncertain'],
+    recovered: ['reserved'],
+};
 export function budgetLedger(options) {
     const now = options.now ?? (() => new Date());
     const period = options.period ?? 'month';
     const store = options.store ?? new MemoryBudgetUsage(() => now().getTime());
+    const records = recordsOf(store);
+    const leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
+    if (!(Number.isFinite(leaseMs) && leaseMs > 0))
+        throw new RangeError('leaseMs must be a positive number');
+    const uncertain = options.uncertain ?? 'charge';
     const windows = new WeakMap();
     const storeKeyOf = (key, at) => `budget:${encodeURIComponent(key)}:${periodStart(period, at)}`;
     const limitOf = async (key) => (typeof options.limit === 'function' ? options.limit(key) : options.limit);
+    const apply = async (record, outcome) => {
+        if (!records)
+            return false;
+        const at = now().getTime();
+        switch (outcome.kind) {
+            case 'running':
+                return records.renew(record.id, at + leaseMs);
+            case 'finished': {
+                const cost = Math.max(0, outcome.cost);
+                return records.settle(record.id, { status: 'settled', charged: cost, actual: cost, from: FROM.settled, at });
+            }
+            case 'never-started':
+                return records.settle(record.id, { status: 'expired', charged: 0, from: FROM.recovered, at });
+            case 'unknown':
+                return records.settle(record.id, {
+                    status: 'uncertain',
+                    charged: uncertain === 'charge' ? record.amount : 0,
+                    from: FROM.recovered,
+                    at,
+                });
+        }
+    };
     return {
         async reserve(operation, estimate) {
             const key = options.key ? options.key(operation) : (operation.tenantId ?? 'default');
@@ -19,17 +54,48 @@ export function budgetLedger(options) {
             const storeKey = storeKeyOf(key, at);
             const resetAt = periodEnd(period, at);
             const amount = Math.max(0, estimate);
-            const total = await store.add(storeKey, amount, resetAt);
+            const id = records ? `rsv_${randomHex(12)}` : undefined;
+            const total = records
+                ? await records.hold({
+                    id: id,
+                    key,
+                    storeKey,
+                    resetAt,
+                    amount,
+                    charged: amount,
+                    operationId: operation.requestId,
+                    family: operation.family,
+                    operation: operation.operation,
+                    status: 'reserved',
+                    leasedUntil: at.getTime() + leaseMs,
+                    createdAt: at.getTime(),
+                })
+                : await store.add(storeKey, amount, resetAt);
             const before = total - amount;
             if (total > limit || before >= limit) {
-                await store.add(storeKey, -amount, resetAt);
+                if (records) {
+                    await records.settle(id, { status: 'released', charged: 0, from: FROM.released, at: at.getTime() });
+                }
+                else
+                    await store.add(storeKey, -amount, resetAt);
                 throw new BudgetExceededError(key, amount, limit - before);
             }
-            const reservation = { key, amount };
+            const reservation = { key, amount, ...(id ? { id } : {}) };
             windows.set(reservation, { storeKey, resetAt });
             return reservation;
         },
         async reconcile(reservation, actual) {
+            if (reservation.id && records) {
+                const cost = Math.max(0, actual);
+                await records.settle(reservation.id, {
+                    status: 'settled',
+                    charged: cost,
+                    actual: cost,
+                    from: FROM.settled,
+                    at: now().getTime(),
+                });
+                return;
+            }
             const window = windows.get(reservation);
             if (!window)
                 return;
@@ -39,6 +105,15 @@ export function budgetLedger(options) {
                 await store.add(window.storeKey, delta, window.resetAt);
         },
         async release(reservation) {
+            if (reservation.id && records) {
+                await records.settle(reservation.id, {
+                    status: 'released',
+                    charged: 0,
+                    from: FROM.released,
+                    at: now().getTime(),
+                });
+                return;
+            }
             const window = windows.get(reservation);
             if (!window)
                 return;
@@ -49,13 +124,67 @@ export function budgetLedger(options) {
         async spent(key) {
             return store.total(storeKeyOf(key, now()));
         },
+        async reservation(id) {
+            return records ? records.reservation(id) : undefined;
+        },
+        async renew(reservation) {
+            if (reservation.id && records)
+                await records.renew(reservation.id, now().getTime() + leaseMs);
+        },
+        async settle(id, outcome) {
+            const record = records ? await records.reservation(id) : undefined;
+            return record ? apply(record, outcome) : false;
+        },
+        async recover(resolve, recoverOptions = {}) {
+            const report = { settled: 0, expired: 0, uncertain: 0, renewed: 0, skipped: 0 };
+            if (!records)
+                return report;
+            const lapsed = await records.lapsed(now().getTime(), recoverOptions.limit ?? 100, recoverOptions.operation);
+            for (const record of lapsed) {
+                const outcome = await resolve(record);
+                if (!outcome) {
+                    report.skipped += 1;
+                    continue;
+                }
+                if (!(await apply(record, outcome)))
+                    continue;
+                if (outcome.kind === 'finished')
+                    report.settled += 1;
+                else if (outcome.kind === 'never-started')
+                    report.expired += 1;
+                else if (outcome.kind === 'unknown')
+                    report.uncertain += 1;
+                else
+                    report.renewed += 1;
+            }
+            return report;
+        },
+    };
+}
+function recordsOf(store) {
+    const names = ['hold', 'settle', 'renew', 'lapsed', 'reservation'];
+    const present = names.filter((name) => typeof store[name] === 'function');
+    if (present.length === 0)
+        return undefined;
+    if (present.length < names.length) {
+        const missing = names.filter((name) => !present.includes(name));
+        throw new TypeError(`A budget store that records reservations implements all five methods; missing ${missing.join(', ')}`);
+    }
+    return {
+        hold: (record) => store.hold.call(store, record),
+        settle: (id, change) => store.settle.call(store, id, change),
+        renew: (id, leasedUntil) => store.renew.call(store, id, leasedUntil),
+        lapsed: (at, limit, operation) => store.lapsed.call(store, at, limit, operation),
+        reservation: (id) => store.reservation.call(store, id),
     };
 }
 export class MemoryBudgetUsage {
     now;
     totals = new Map();
+    book;
     constructor(now = () => Date.now()) {
         this.now = now;
+        this.book = new MemoryReservationBook((key, amount, resetAt) => this.add(key, amount, resetAt), now);
     }
     add(key, amount, resetAt) {
         const current = this.totals.get(key);
@@ -67,4 +196,19 @@ export class MemoryBudgetUsage {
         const current = this.totals.get(key);
         return current && current.resetAt > this.now() ? current.value : 0;
     }
+    hold(record) {
+        return this.book.hold(record);
+    }
+    settle(id, change) {
+        return this.book.settle(id, change);
+    }
+    renew(id, leasedUntil) {
+        return this.book.renew(id, leasedUntil);
+    }
+    lapsed(now, limit, operation) {
+        return this.book.lapsed(now, limit, operation);
+    }
+    reservation(id) {
+        return this.book.get(id);
+    }
 }

package/dist/lifecycle/index.d.ts

@@ -4,5 +4,5 @@
  * building that budget, and for code that runs operations of its own through `ai.lifecycle`.
  */
 export { BudgetExceededError, LIFECYCLE_STAGES, type LifecycleRuntime, OperationDeniedError, OperationLifecycle, type OperationPlan, } from '../core/lifecycle.js';
-export { type BudgetLedgerOptions, type BudgetLedgerWithReport, type BudgetUsageStore, budgetLedger, MemoryBudgetUsage, } from './budget.js';
-export type { BudgetLedger, BudgetPeriod, BudgetReservation, LifecycleConfig, LifecycleHooks, LifecycleStage, OperationDescriptor, OperationFamily, OperationLifecycleLike, OperationOutcome, OperationResultInfo, OperationStartOptions, OperationTicket, ProviderCallContext, } from '../types/lifecycle.js';
+export { type BudgetLedgerOptions, type BudgetLedgerWithReport, type BudgetReservationChange, type BudgetUsageStore, budgetLedger, MemoryBudgetUsage, } from './budget.js';
+export type { BudgetLedger, BudgetPeriod, BudgetRecoverOptions, BudgetRecoveryReport, BudgetReservation, BudgetReservationOutcome, BudgetReservationRecord, BudgetReservationStatus, LifecycleConfig, LifecycleHooks, LifecycleStage, OperationDescriptor, OperationFamily, OperationLifecycleLike, OperationOutcome, OperationResultInfo, OperationStartOptions, OperationTicket, ProviderCallContext, } from '../types/lifecycle.js';

package/dist/lifecycle/reservations.d.ts

@@ -0,0 +1,46 @@
+import type { BudgetReservationRecord, BudgetReservationStatus } from '../types/lifecycle.js';
+/**
+ * A change to one recorded reservation: where it moves, what it charges once there, and the
+ * statuses it may move from. A store applies the status and the difference in what it charges to its
+ * total together, or not at all.
+ */
+export interface BudgetReservationChange {
+    /** Where it moves. */
+    status: Exclude<BudgetReservationStatus, 'reserved'>;
+    /** What it adds to its total once moved. */
+    charged: number;
+    /** The statuses it may move from. From any other, the change is refused. */
+    from: readonly BudgetReservationStatus[];
+    /** When, epoch milliseconds. */
+    at: number;
+    /** What its operation cost, when settled. */
+    actual?: number;
+}
+/**
+ * Reservations in process memory, beside the totals of the store that holds them: what
+ * `MemoryBudgetUsage` and `MemoryTenantUsage` keep them in. Each change and its total move together,
+ * since nothing runs between them on one thread.
+ */
+export declare class MemoryReservationBook {
+    private readonly add;
+    private readonly now;
+    private readonly records;
+    private prunedAt;
+    constructor(add: (key: string, amount: number, resetAt: number) => number, now: () => number);
+    /** Records a reservation and adds what it charges to its total. */
+    hold(record: BudgetReservationRecord): number;
+    /** Moves a reservation, and its total by what it charges differently, if it stands where `from` allows. */
+    settle(id: string, change: BudgetReservationChange): boolean;
+    /** Extends a reserved reservation's lease. */
+    renew(id: string, leasedUntil: number): boolean;
+    /** Reserved reservations whose lease lapsed by `now`, soonest lapsed first. */
+    lapsed(now: number, limit: number, operation?: string): BudgetReservationRecord[];
+    /** One reservation. */
+    get(id: string): BudgetReservationRecord | undefined;
+    /**
+     * Forgets what no report can change any more, at most once a minute: anything whose period has
+     * ended, and a settled, released, or expired reservation after an hour. An uncertain one is kept
+     * for its period, until its operation says what it cost.
+     */
+    private prune;
+}

package/dist/lifecycle/reservations.js

@@ -0,0 +1,67 @@
+const SETTLED_RETENTION_MS = 60 * 60 * 1000;
+export class MemoryReservationBook {
+    add;
+    now;
+    records = new Map();
+    prunedAt = 0;
+    constructor(add, now) {
+        this.add = add;
+        this.now = now;
+    }
+    hold(record) {
+        this.prune();
+        if (this.records.has(record.id))
+            throw new Error(`Budget reservation "${record.id}" already exists`);
+        this.records.set(record.id, { ...record });
+        return this.add(record.storeKey, record.charged, record.resetAt);
+    }
+    settle(id, change) {
+        const record = this.records.get(id);
+        if (!record || !change.from.includes(record.status))
+            return false;
+        const delta = change.charged - record.charged;
+        record.status = change.status;
+        record.charged = change.charged;
+        record.settledAt = change.at;
+        if (change.actual !== undefined)
+            record.actual = change.actual;
+        if (delta !== 0 && record.resetAt > change.at)
+            this.add(record.storeKey, delta, record.resetAt);
+        return true;
+    }
+    renew(id, leasedUntil) {
+        const record = this.records.get(id);
+        if (record?.status !== 'reserved')
+            return false;
+        record.leasedUntil = leasedUntil;
+        return true;
+    }
+    lapsed(now, limit, operation) {
+        const lapsed = [];
+        for (const record of this.records.values()) {
+            if (record.status !== 'reserved' || record.leasedUntil > now)
+                continue;
+            if (operation !== undefined && record.operation !== operation)
+                continue;
+            lapsed.push({ ...record });
+        }
+        return lapsed.sort((a, b) => a.leasedUntil - b.leasedUntil).slice(0, limit);
+    }
+    get(id) {
+        const record = this.records.get(id);
+        return record ? { ...record } : undefined;
+    }
+    prune() {
+        const now = this.now();
+        if (now - this.prunedAt < 60_000)
+            return;
+        this.prunedAt = now;
+        for (const [id, record] of this.records) {
+            if (record.status === 'reserved')
+                continue;
+            const settledLongAgo = record.status !== 'uncertain' && (record.settledAt ?? 0) + SETTLED_RETENTION_MS <= now;
+            if (record.resetAt <= now || settledLongAgo)
+                this.records.delete(id);
+        }
+    }
+}

package/dist/media/rag.d.ts

@@ -5,6 +5,7 @@
 import type { VectorStore } from '../hallucination/retrieval.js';
 import type { AssetStore } from '../images/asset-support.js';
 import type { EmbeddingRequest, EmbeddingResponse } from '../types/embeddings.js';
+import type { Store } from '../types/store.js';
 import { type MediaAnswer, type MediaInput, type MediaKind, type MediaManager } from './index.js';
 /** Anything that embeds, such as an `EmbeddingManager` or a client's `embeddings`. */
 export interface MediaEmbeddingSource {
@@ -64,11 +65,68 @@ export interface MediaIndexOptions {
     };
     /** The longest chunk of page text, in characters; a longer page is split at paragraphs. Defaults to 4,000. */
     maxChunkChars?: number;
+    /**
+     * Where the index remembers what it holds: any `Store`, so it lives in memory, Redis, Postgres, or
+     * SQLite. With one, `add()` skips a medium whose content and options are unchanged and replaces
+     * exactly the chunks of one that changed, and `delete()`, `reindex()`, `describe()`, and `list()`
+     * work by a medium's id. A store with an item limit must hold every medium.
+     */
+    manifest?: Store;
+    /** Names the index. Its manifest is kept under this name, so two indexes never share one. Defaults to `media`. */
+    name?: string;
+}
+/** Who produced a medium's text or caption. */
+export interface MediaIndexReader {
+    /** The provider that answered. */
+    provider: string;
+    /** The model it used. */
+    model: string;
+}
+/** What the manifest records for one medium. */
+export interface MediaIndexEntry {
+    /** The medium's id. */
+    id: string;
+    /**
+     * A hash of the medium's content, source, metadata, and how it was indexed: the medium's version.
+     * Adding it again with the same hash writes nothing.
+     */
+    hash: string;
+    /** Where it came from. */
+    source?: string;
+    /** Its metadata. */
+    metadata?: Record<string, string | number | boolean>;
+    /** Where the medium is kept: its URL, or its asset. */
+    reference: MediaReference;
+    /** The pages that were read. */
+    pages: number;
+    /** Every chunk's id in the vector store. */
+    chunkIds: string[];
+    /** The embedding model, when one was named. */
+    model?: string;
+    /** Who read its pages, when they were read. */
+    reader?: MediaIndexReader;
+    /** Who described it, when it was described. */
+    describer?: MediaIndexReader;
+    /** ISO-8601 time it was first indexed. */
+    createdAt: string;
+    /** ISO-8601 time it was last indexed. */
+    updatedAt: string;
+    /**
+     * A change that began and has not finished, as a crash leaves it: its version, its chunks, and the
+     * asset it stored. The next `add()`, `reindex()`, or `delete()` of the medium finishes or undoes it.
+     */
+    pending?: {
+        hash: string;
+        chunkIds: string[];
+        assetId?: string;
+    };
 }
 /** What `add()` indexed. */
 export interface MediaIndexReport {
     /** Media indexed. */
     media: number;
+    /** Media the manifest already held at the same version, which were not indexed again. */
+    unchanged: number;
     /** Chunks of page text. */
     pages: number;
     /** Captions. */
@@ -106,8 +164,25 @@ export interface MediaSearchOptions {
 }
 /** An index of media in a vector store. */
 export interface MediaIndex {
-    /** Reads, describes, and embeds each medium, and writes its chunks. Adding an id again replaces it. */
+    /**
+     * Reads, describes, and embeds each medium, and writes its chunks. Adding an id again replaces it;
+     * with a manifest, only when its content, source, metadata, or the index's options changed.
+     */
     add(documents: readonly MediaDocument[]): Promise<MediaIndexReport>;
+    /** Removes media by id: their chunks, their stored assets, and their manifest entries. Needs a manifest. */
+    delete(ids: readonly string[]): Promise<number>;
+    /**
+     * Indexes media again by id, from where the manifest says each is kept, even when unchanged: after a
+     * new embedding model or a better reader. Needs a manifest.
+     */
+    reindex(ids: readonly string[]): Promise<MediaIndexReport>;
+    /** What the manifest records for a medium, or `undefined`. Needs a manifest. */
+    describe(id: string): Promise<MediaIndexEntry | undefined>;
+    /** The manifest's entries, newest first, a page at a time. Needs a manifest. */
+    list(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<MediaIndexEntry[]>;
     /** The media a question is about, each once, at its best chunk. */
     search(query: string, options?: MediaSearchOptions): Promise<MediaHit[]>;
     /** The medium behind a hit, to hand a model; `undefined` when its asset is gone. */