@opendatalabs/personal-server-ts-core 0.0.1-canary.01ca694 → 0.0.1-canary.052d47e

package/dist/derivatives/registration.js

@@ -0,0 +1,180 @@
+/**
+ * Question registration: input validation, the naming rule (shared with the
+ * lineage write path) and the cycle guard that keeps recompute-on-refresh
+ * bounded.
+ */
+import { DerivativeCycleError, DerivativeQuestionInvalidError, } from "../errors/catalog.js";
+import { parseDataScopeContract } from "../contracts/data.js";
+import { assertDerivedScopeNaming } from "../lineage/lineage.js";
+import { isWriteScopeEntry } from "../policy/data-write.js";
+import { scopeCoveredByGrant } from "@opendatalabs/vana-sdk/browser";
+export const MAX_QUESTION_SOURCE_SCOPES = 16;
+export const MAX_QUESTION_CHARS = 8_000;
+export const MAX_MODEL_CHARS = 128;
+/** Unvalidated scope strings echoed in 400 details are cut to this. */
+export const MAX_ECHOED_SCOPE_CHARS = 128;
+/** Model ids as providers spell them (`z-ai/glm-5.2`, `gpt-4o-mini`, ...). */
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseScope(value, field) {
+    if (typeof value !== "string") {
+        throw new DerivativeQuestionInvalidError(`${field} must be a scope string`, {
+            field,
+        });
+    }
+    const parsed = parseDataScopeContract(value);
+    if (!parsed.ok) {
+        throw new DerivativeQuestionInvalidError(`${field} is not a valid scope: ${parsed.body.message}`, { field, scope: value.slice(0, MAX_ECHOED_SCOPE_CHARS) });
+    }
+    return parsed.scope;
+}
+/**
+ * Validate the POST body of a question registration. Throws 400
+ * DERIVATIVE_QUESTION_INVALID on shape errors and 400
+ * LINEAGE_SCOPE_UNDER_SOURCE_PREFIX when the derived scope shares its
+ * first segment with a source (the lineage naming rule, applied up front
+ * so a registration that could never be written is refused here).
+ */
+export function parseQuestionInput(body) {
+    if (!isRecord(body)) {
+        throw new DerivativeQuestionInvalidError("Body must be a JSON object");
+    }
+    const derivedScope = parseScope(body.derivedScope, "derivedScope");
+    if (!Array.isArray(body.sourceScopes) || body.sourceScopes.length === 0) {
+        throw new DerivativeQuestionInvalidError("sourceScopes must be a non-empty array of scopes", { field: "sourceScopes" });
+    }
+    if (body.sourceScopes.length > MAX_QUESTION_SOURCE_SCOPES) {
+        throw new DerivativeQuestionInvalidError(`sourceScopes lists ${body.sourceScopes.length} scopes; the maximum is ${MAX_QUESTION_SOURCE_SCOPES}`, { field: "sourceScopes", max: MAX_QUESTION_SOURCE_SCOPES });
+    }
+    const sourceScopes = [];
+    for (const entry of body.sourceScopes) {
+        const scope = parseScope(entry, "sourceScopes[]");
+        if (sourceScopes.includes(scope)) {
+            throw new DerivativeQuestionInvalidError("sourceScopes lists the same scope twice", { field: "sourceScopes", duplicate: scope });
+        }
+        if (scope === derivedScope) {
+            throw new DerivativeQuestionInvalidError("derivedScope cannot be one of its own sources", { field: "sourceScopes", scope });
+        }
+        sourceScopes.push(scope);
+    }
+    if (typeof body.question !== "string" || body.question.trim() === "") {
+        throw new DerivativeQuestionInvalidError("question must be a non-empty string", { field: "question" });
+    }
+    if (body.question.length > MAX_QUESTION_CHARS) {
+        throw new DerivativeQuestionInvalidError(`question is ${body.question.length} characters; the maximum is ${MAX_QUESTION_CHARS}`, { field: "question", max: MAX_QUESTION_CHARS });
+    }
+    let model = null;
+    if (body.model !== undefined && body.model !== null) {
+        if (typeof body.model !== "string" ||
+            body.model.length > MAX_MODEL_CHARS ||
+            !MODEL_ID.test(body.model)) {
+            throw new DerivativeQuestionInvalidError("model must be a provider model id", { field: "model" });
+        }
+        model = body.model;
+    }
+    // Absent (or null, like model) keeps the original follow-every-change
+    // behavior, so existing builder clients register exactly as before.
+    let recompute = "on-change";
+    if (body.recompute !== undefined && body.recompute !== null) {
+        if (body.recompute !== "snapshot" && body.recompute !== "on-change") {
+            throw new DerivativeQuestionInvalidError('recompute must be "snapshot" or "on-change"', { field: "recompute" });
+        }
+        recompute = body.recompute;
+    }
+    assertDerivedScopeNaming(derivedScope, sourceScopes);
+    return {
+        derivedScope,
+        sourceScopes,
+        question: body.question,
+        model,
+        recompute,
+    };
+}
+/**
+ * Recompute-on-refresh follows edges source -> derived. A registration whose
+ * derived scope can reach one of its own sources through other
+ * registrations would recompute forever (A from B, B from A). Refuse it.
+ * Returns the offending path (derived scope back to itself) or null.
+ */
+export function findDerivationCycle(candidate, existing) {
+    // derived scope -> the scopes it is computed from
+    const sourcesOf = new Map();
+    const add = (derived, sources) => {
+        const set = sourcesOf.get(derived) ?? new Set();
+        for (const source of sources)
+            set.add(source);
+        sourcesOf.set(derived, set);
+    };
+    for (const registration of existing) {
+        add(registration.derivedScope, registration.sourceScopes);
+    }
+    add(candidate.derivedScope, candidate.sourceScopes);
+    // Depth-first from the candidate's derived scope through the sources it
+    // depends on; reaching the derived scope again is a cycle. Bounded by the
+    // number of distinct scopes (visited set), so no unbounded walk.
+    const target = candidate.derivedScope;
+    const visited = new Set();
+    const stack = [
+        { scope: target, path: [target] },
+    ];
+    while (stack.length > 0) {
+        const { scope, path } = stack.pop();
+        for (const source of sourcesOf.get(scope) ?? []) {
+            if (source === target)
+                return [...path, source];
+            if (visited.has(source))
+                continue;
+            visited.add(source);
+            stack.push({ scope: source, path: [...path, source] });
+        }
+    }
+    return null;
+}
+/**
+ * Validate, guard against cycles and persist a registration in `pending`.
+ * The caller has already authorized the write on `derivedScope`.
+ */
+export async function createQuestionRegistration(input) {
+    const parsed = parseQuestionInput(input.body);
+    const cycle = findDerivationCycle(parsed, await input.store.list());
+    if (cycle) {
+        throw new DerivativeCycleError({
+            derivedScope: parsed.derivedScope,
+            path: cycle,
+        });
+    }
+    const at = input.now().toISOString();
+    const registration = {
+        questionId: input.questionId,
+        derivedScope: parsed.derivedScope,
+        sourceScopes: parsed.sourceScopes,
+        question: parsed.question,
+        model: parsed.model,
+        recompute: parsed.recompute,
+        registeredBy: input.registeredBy,
+        status: "pending",
+        error: null,
+        errorCode: null,
+        createdAt: at,
+        updatedAt: at,
+        lastComputedAt: null,
+        derivedVersion: null,
+        derivedCollectedAt: null,
+    };
+    await input.store.insert(registration);
+    return registration;
+}
+/**
+ * Consent check for a builder question: the sources feed a prompt whose
+ * answer the builder reads, so every source scope must be covered by a READ
+ * entry of the builder's grant (bare entries; `write:` entries confer
+ * nothing). Returns the uncovered scopes; empty = all covered. The system
+ * prompt is not a security boundary, this is.
+ */
+export function uncoveredSourceScopes(sourceScopes, grantScopes) {
+    const readEntries = (grantScopes ?? []).filter((entry) => !isWriteScopeEntry(entry));
+    return sourceScopes.filter((scope) => !scopeCoveredByGrant(scope, readEntries));
+}
+//# sourceMappingURL=registration.js.map

package/dist/derivatives/registration.js.map

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

package/dist/derivatives/scheduler.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Recompute scheduler: marks registrations stale when one of their source
+ * scopes changes and runs the compute after a quiet period, one in flight
+ * per question. Timers and the clock are injectable so tests drive it
+ * deterministically.
+ */
+import type { ComputeOutcome } from "./compute.js";
+import type { QuestionStore } from "./types.js";
+export interface SchedulerTimers {
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface RecomputeSchedulerOptions {
+    store: QuestionStore;
+    /**
+     * Runs one compute; must not throw for compute failures. The outcome is
+     * what the retry logic classifies — a wrapper that swallows it (returns
+     * void) silently disables automatic retries, so forward it.
+     */
+    compute(questionId: string): Promise<ComputeOutcome | void>;
+    /** Quiet period after a source change (default 5s). */
+    debounceMs?: number;
+    /**
+     * Backoff steps for automatic retry of a compute that failed with the
+     * transient class (`errorCode: "inference_unavailable"`). Default
+     * 1m, 5m, 30m; empty disables retry. Non-transient failures never
+     * retry — they wait for a source change or an explicit recompute.
+     */
+    retryDelaysMs?: readonly number[];
+    /**
+     * Lets `markSourceChanged` recognise a new version that was computed FROM
+     * a question's own derived scope (its `$lineage` names the derived data
+     * point id) and skip that question: a cross-replica cycle then settles
+     * instead of ping-ponging through sync. Without it every change counts.
+     */
+    serverOwner?: `0x${string}`;
+    timers?: SchedulerTimers;
+    now?: () => Date;
+    logger?: {
+        warn?(payload: Record<string, unknown>, message: string): void;
+    };
+}
+export interface RecomputeScheduler {
+    /**
+     * A scope got a new local version (ingest or sync). Every registration
+     * that lists it as a source is marked `stale` (if it had a result) and
+     * scheduled. Fire and forget; failures are logged.
+     */
+    markSourceChanged(scope: string, options?: {
+        /** `$lineage.sources` of the new version, when it is a derivative. */
+        lineageSources?: readonly string[];
+    }): void;
+    /** Schedule one question; `immediate` skips the debounce (owner recompute). */
+    requestRecompute(questionId: string, options?: {
+        immediate?: boolean;
+    }): void;
+    /**
+     * Next scheduled automatic retry for a failed question (ISO time), or
+     * null when none is pending. In-memory, like the rest of the scheduler:
+     * a restart drops the chain and the question waits for a source change
+     * or an explicit recompute.
+     */
+    nextRetryAt(questionId: string): string | null;
+    /**
+     * True while a retry compute is actually RUNNING (its timer fired, the
+     * compute has not settled). `nextRetryAt` is null in that window; without
+     * this signal a status reader would see the terminal
+     * failed-with-no-retry signature during every in-flight retry.
+     */
+    retryInFlight(questionId: string): boolean;
+    /** Resolves once no compute or store lookup is pending or timed. */
+    whenIdle(): Promise<void>;
+    /** Cancel pending timers. In-flight computes finish on their own. */
+    stop(): void;
+    /**
+     * Schedule every question left `pending` or `stale` (immediately). The
+     * first call is the boot reschedule: a restarted process only holds what
+     * the store holds, and those questions have no other way back onto a
+     * timer. Later calls resume after `stop()`; idempotent while running.
+     */
+    start(): void;
+}
+export declare function createRecomputeScheduler(options: RecomputeSchedulerOptions): RecomputeScheduler;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/derivatives/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/derivatives/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,aAAa,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC5D,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;KAChE,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QACR,sEAAsE;QACtE,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,GACA,IAAI,CAAC;IACR,+EAA+E;IAC/E,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9E;;;;;OAKG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/C;;;;;OAKG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C,oEAAoE;IACpE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,qEAAqE;IACrE,IAAI,IAAI,IAAI,CAAC;IACb;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAoDD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GACjC,kBAAkB,CAsQpB"}

package/dist/derivatives/scheduler.js

@@ -0,0 +1,257 @@
+/**
+ * Recompute scheduler: marks registrations stale when one of their source
+ * scopes changes and runs the compute after a quiet period, one in flight
+ * per question. Timers and the clock are injectable so tests drive it
+ * deterministically.
+ */
+import { computeDataPointId } from "../sync/data-point-id.js";
+const DEFAULT_RETRY_DELAYS_MS = [60_000, 300_000, 1_800_000];
+/**
+ * Structural check on the compute callback's resolved value: retry is only
+ * for a failed outcome whose stored class is the one transient kind. A
+ * callback that resolves anything else (older wiring, tests) never retries.
+ */
+/**
+ * A compute skipped because the runtime is unavailable (PS-Lite with the
+ * hosting tab inactive). During a retry chain this must not end the chain:
+ * nothing else would ever reschedule a failed question.
+ */
+function isRuntimeSkipOutcome(outcome) {
+    if (typeof outcome !== "object" || outcome === null)
+        return false;
+    const shaped = outcome;
+    return shaped.status === "skipped" && shaped.reason === "runtime-unavailable";
+}
+function isTransientFailureOutcome(outcome) {
+    if (typeof outcome !== "object" || outcome === null)
+        return false;
+    const shaped = outcome;
+    return (shaped.status === "failed" &&
+        shaped.registration?.errorCode === "inference_unavailable");
+}
+const defaultTimers = {
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export function createRecomputeScheduler(options) {
+    const debounceMs = options.debounceMs ?? 5_000;
+    const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+    const timers = options.timers ?? defaultTimers;
+    const now = options.now ?? (() => new Date());
+    const states = new Map();
+    const pending = new Set();
+    let stopped = false;
+    // Distinguishes the first start() (which must reschedule) from a
+    // redundant one while already running (which must not).
+    let started = false;
+    function track(promise) {
+        pending.add(promise);
+        const done = () => pending.delete(promise);
+        promise.then(done, done);
+        return promise;
+    }
+    function warn(payload, message) {
+        options.logger?.warn?.(payload, message);
+    }
+    function stateFor(questionId) {
+        let state = states.get(questionId);
+        if (!state) {
+            state = {
+                timer: null,
+                running: null,
+                rerun: false,
+                retryAttempts: 0,
+                retryAtMs: null,
+                retryScheduled: false,
+                retryRunning: false,
+            };
+            states.set(questionId, state);
+        }
+        return state;
+    }
+    function run(questionId) {
+        if (stopped)
+            return;
+        const state = stateFor(questionId);
+        if (state.running) {
+            // One in flight per question; a change during the run means the
+            // result is already stale, so run once more when it finishes.
+            state.rerun = true;
+            return;
+        }
+        state.running = track(Promise.resolve()
+            .then(() => options.compute(questionId))
+            .then((outcome) => outcome, (err) => {
+            warn({
+                questionId,
+                error: err instanceof Error ? err.name : String(err),
+            }, "Derivative compute threw");
+            return undefined;
+        })
+            .then(async (outcome) => {
+            state.running = null;
+            state.retryAtMs = null;
+            state.retryRunning = false;
+            const retryable = isTransientFailureOutcome(outcome) ||
+                // A runtime-unavailable skip DURING a chain consumes an attempt
+                // instead of ending the chain; on a fresh compute it keeps the
+                // pre-retry behavior (pending/stale, reswept by start()).
+                (isRuntimeSkipOutcome(outcome) && state.retryAttempts > 0);
+            if (state.rerun) {
+                // A source changed during the run: that supersedes any retry.
+                state.rerun = false;
+                state.retryAttempts = 0;
+                await markStale(questionId);
+                schedule(questionId, 0);
+            }
+            else if (retryable &&
+                // A pending timer means a source change or explicit recompute
+                // arrived during the run and already scheduled a fresher run;
+                // replacing its 5s debounce with a 60s retry would delay the
+                // recompute of data this compute never saw.
+                state.timer === null &&
+                // After stop() nothing may be scheduled; without this a compute
+                // that settles late would record a retryAtMs no timer backs.
+                !stopped &&
+                state.retryAttempts < retryDelaysMs.length) {
+                const delayMs = retryDelaysMs[state.retryAttempts];
+                state.retryAttempts += 1;
+                state.retryAtMs = now().getTime() + delayMs;
+                schedule(questionId, delayMs);
+                state.retryScheduled = true;
+            }
+            else {
+                state.retryAttempts = 0;
+                if (!states.get(questionId)?.timer) {
+                    states.delete(questionId);
+                }
+            }
+        }));
+    }
+    function schedule(questionId, delayMs) {
+        if (stopped)
+            return;
+        const state = stateFor(questionId);
+        if (state.timer !== null)
+            timers.clearTimeout(state.timer);
+        state.timer = timers.setTimeout(() => {
+            state.timer = null;
+            // Whatever this timer was (debounce or retry), any promised retry is
+            // now being consumed: a past retryAtMs would pin the status route's
+            // retryAfterSeconds at 0 for the whole in-flight compute. A firing
+            // RETRY timer hands over to retryRunning so the in-flight window is
+            // still distinguishable from a terminal failure.
+            state.retryAtMs = null;
+            state.retryRunning = state.retryScheduled;
+            state.retryScheduled = false;
+            run(questionId);
+        }, delayMs);
+    }
+    async function markStale(questionId) {
+        const registration = await options.store.get(questionId);
+        if (!registration)
+            return;
+        if (registration.status === "ready" || registration.status === "failed") {
+            await options.store.update(questionId, {
+                status: "stale",
+                // The reader contract says errorCode is null unless failed; a stale
+                // question is a recompute in progress, not a terminal failure.
+                errorCode: null,
+                updatedAt: now().toISOString(),
+            });
+        }
+    }
+    function resetRetry(questionId) {
+        const state = states.get(questionId);
+        if (!state)
+            return;
+        state.retryAttempts = 0;
+        state.retryAtMs = null;
+        state.retryScheduled = false;
+    }
+    return {
+        nextRetryAt(questionId) {
+            const retryAtMs = states.get(questionId)?.retryAtMs;
+            return retryAtMs == null ? null : new Date(retryAtMs).toISOString();
+        },
+        retryInFlight(questionId) {
+            return states.get(questionId)?.retryRunning ?? false;
+        },
+        markSourceChanged(scope, opts) {
+            if (stopped)
+                return;
+            const lineage = new Set((opts?.lineageSources ?? []).map((id) => id.toLowerCase()));
+            void track((async () => {
+                const affected = await options.store.list({ sourceScope: scope });
+                for (const registration of affected) {
+                    if (registration.recompute === "snapshot") {
+                        // A snapshot question computes at registration and on an
+                        // explicit recompute only; source changes never touch it.
+                        continue;
+                    }
+                    if (options.serverOwner &&
+                        lineage.has(computeDataPointId(options.serverOwner, registration.derivedScope))) {
+                        // The new version descends from this question's own output.
+                        continue;
+                    }
+                    await markStale(registration.questionId);
+                    resetRetry(registration.questionId);
+                    schedule(registration.questionId, debounceMs);
+                }
+            })().catch((err) => warn({ scope, error: err instanceof Error ? err.name : String(err) }, "Could not mark derivative questions stale")));
+        },
+        requestRecompute(questionId, opts) {
+            if (stopped)
+                return;
+            void track(markStale(questionId)
+                .catch((err) => warn({
+                questionId,
+                error: err instanceof Error ? err.name : String(err),
+            }, "Could not mark derivative question stale"))
+                .then(() => {
+                resetRetry(questionId);
+                schedule(questionId, opts?.immediate ? 0 : debounceMs);
+            }));
+        },
+        async whenIdle() {
+            // Waits for store lookups and in-flight computes. Real timers are
+            // polled too; injected timers are the caller's to fire.
+            const waitForTimers = !options.timers;
+            for (;;) {
+                while (pending.size > 0) {
+                    await Promise.allSettled([...pending]);
+                }
+                const busy = [...states.values()].some((state) => state.running !== null || (waitForTimers && state.timer !== null));
+                if (!busy)
+                    return;
+                await new Promise((resolve) => setTimeout(resolve, 5));
+            }
+        },
+        stop() {
+            stopped = true;
+            for (const state of states.values()) {
+                if (state.timer !== null)
+                    timers.clearTimeout(state.timer);
+                state.timer = null;
+                state.retryAttempts = 0;
+                state.retryAtMs = null;
+                state.retryScheduled = false;
+            }
+        },
+        start() {
+            if (started && !stopped)
+                return;
+            started = true;
+            stopped = false;
+            void track((async () => {
+                for (const registration of await options.store.list()) {
+                    if (registration.status === "pending" ||
+                        registration.status === "stale") {
+                        schedule(registration.questionId, 0);
+                    }
+                }
+            })().catch((err) => warn({ error: err instanceof Error ? err.name : String(err) }, "Could not reschedule derivative questions")));
+        },
+    };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/derivatives/scheduler.js.map

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

package/dist/derivatives/store.d.ts

@@ -0,0 +1,14 @@
+import type { QuestionRegistration, QuestionStore, QuestionStoreListFilter } from "./types.js";
+export declare function matchesQuestionFilter(registration: QuestionRegistration, filter: QuestionStoreListFilter | undefined): boolean;
+/** Oldest first, the order every store lists in. */
+export declare function sortQuestions(registrations: QuestionRegistration[]): QuestionRegistration[];
+/**
+ * Map-backed store. The PS-Lite store wraps it with persistence; tests use
+ * it as is.
+ */
+export declare function createInMemoryQuestionStore(options?: {
+    /** Called after every mutation with the full current list. */
+    onChange?: (registrations: QuestionRegistration[]) => Promise<void>;
+    initial?: QuestionRegistration[];
+}): QuestionStore;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/derivatives/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EAEpB,aAAa,EACb,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAYpB,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,oBAAoB,EAClC,MAAM,EAAE,uBAAuB,GAAG,SAAS,GAC1C,OAAO,CAkBT;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAC3B,aAAa,EAAE,oBAAoB,EAAE,GACpC,oBAAoB,EAAE,CAMxB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,GAAE;IACP,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,aAAa,EAAE,oBAAoB,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,OAAO,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC7B,GACL,aAAa,CA4Cf"}

package/dist/derivatives/store.js

@@ -0,0 +1,77 @@
+function clone(registration) {
+    return {
+        ...registration,
+        // Registrations persisted before the field existed load as null.
+        errorCode: registration.errorCode ?? null,
+        sourceScopes: [...registration.sourceScopes],
+        registeredBy: { ...registration.registeredBy },
+    };
+}
+export function matchesQuestionFilter(registration, filter) {
+    if (!filter)
+        return true;
+    if (filter.derivedScope && registration.derivedScope !== filter.derivedScope)
+        return false;
+    if (filter.sourceScope &&
+        !registration.sourceScopes.includes(filter.sourceScope))
+        return false;
+    if (filter.builder) {
+        const by = registration.registeredBy;
+        if (by.kind !== "builder" ||
+            by.builder.toLowerCase() !== filter.builder.toLowerCase())
+            return false;
+    }
+    return true;
+}
+/** Oldest first, the order every store lists in. */
+export function sortQuestions(registrations) {
+    return [...registrations].sort((a, b) => a.createdAt.localeCompare(b.createdAt) ||
+        a.questionId.localeCompare(b.questionId));
+}
+/**
+ * Map-backed store. The PS-Lite store wraps it with persistence; tests use
+ * it as is.
+ */
+export function createInMemoryQuestionStore(options = {}) {
+    const byId = new Map();
+    for (const registration of options.initial ?? []) {
+        byId.set(registration.questionId, clone(registration));
+    }
+    async function changed() {
+        if (!options.onChange)
+            return;
+        await options.onChange(sortQuestions([...byId.values()]).map(clone));
+    }
+    return {
+        async list(filter) {
+            return sortQuestions([...byId.values()].filter((registration) => matchesQuestionFilter(registration, filter))).map(clone);
+        },
+        async get(questionId) {
+            const registration = byId.get(questionId);
+            return registration ? clone(registration) : null;
+        },
+        async insert(registration) {
+            if (byId.has(registration.questionId)) {
+                throw new Error(`Question ${registration.questionId} is already registered`);
+            }
+            byId.set(registration.questionId, clone(registration));
+            await changed();
+        },
+        async update(questionId, patch) {
+            const current = byId.get(questionId);
+            if (!current)
+                return null;
+            const next = { ...current, ...patch };
+            byId.set(questionId, next);
+            await changed();
+            return clone(next);
+        },
+        async delete(questionId) {
+            const existed = byId.delete(questionId);
+            if (existed)
+                await changed();
+            return existed;
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/derivatives/store.js.map

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