@opendatalabs/personal-server-ts-core 0.0.1-canary.00328bf

package/dist/derivatives/prompt.js.map

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

package/dist/derivatives/registration.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Question registration: input validation, the naming rule (shared with the
+ * lineage write path) and the cycle guard that keeps a chain of recomputes
+ * bounded.
+ */
+import { type AnswerShape } from "./answer-shape.js";
+import type { QuestionRecompute, QuestionRegisteredBy, QuestionRegistration, QuestionStore } from "./types.js";
+export declare const MAX_QUESTION_SOURCE_SCOPES = 16;
+export declare const MAX_QUESTION_CHARS = 8000;
+export declare const MAX_MODEL_CHARS = 128;
+/** Unvalidated scope strings echoed in 400 details are cut to this. */
+export declare const MAX_ECHOED_SCOPE_CHARS = 128;
+export interface ParsedQuestionInput {
+    derivedScope: string;
+    sourceScopes: string[];
+    question: string;
+    model: string | null;
+    answerShape: AnswerShape | null;
+    recompute: QuestionRecompute;
+}
+/**
+ * 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 declare function parseQuestionInput(body: unknown): ParsedQuestionInput;
+/**
+ * Staleness 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 declare function findDerivationCycle(candidate: Pick<QuestionRegistration, "derivedScope" | "sourceScopes">, existing: readonly Pick<QuestionRegistration, "derivedScope" | "sourceScopes">[]): string[] | null;
+export interface CreateQuestionRegistrationInput {
+    body: unknown;
+    registeredBy: QuestionRegisteredBy;
+    store: QuestionStore;
+    questionId: string;
+    now: () => Date;
+}
+/**
+ * Validate, guard against cycles and persist a registration in `pending`.
+ * The caller has already authorized the write on `derivedScope`.
+ */
+export declare function createQuestionRegistration(input: CreateQuestionRegistrationInput): Promise<QuestionRegistration>;
+/**
+ * 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 declare function uncoveredSourceScopes(sourceScopes: readonly string[], grantScopes: readonly string[] | undefined): string[];
+//# sourceMappingURL=registration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../src/derivatives/registration.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,EAAyB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE5E,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AACxC,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAK1C,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAyBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,CAqFrE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,IAAI,CAAC,oBAAoB,EAAE,cAAc,GAAG,cAAc,CAAC,EACtE,QAAQ,EAAE,SAAS,IAAI,CACrB,oBAAoB,EACpB,cAAc,GAAG,cAAc,CAChC,EAAE,GACF,MAAM,EAAE,GAAG,IAAI,CA+BjB;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,oBAAoB,CAAC;IACnC,KAAK,EAAE,aAAa,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,IAAI,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,+BAA+B,GACrC,OAAO,CAAC,oBAAoB,CAAC,CA8B/B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACzC,MAAM,EAAE,CAOV"}

package/dist/derivatives/registration.js

@@ -0,0 +1,187 @@
+/**
+ * Question registration: input validation, the naming rule (shared with the
+ * lineage write path) and the cycle guard that keeps a chain of recomputes
+ * 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 { parseAnswerShapeInput } from "./answer-shape.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) keeps the free-text answer: the model is asked for a
+    // prose answer and nothing about the reply is enforced beyond the token
+    // cap, exactly as before this field existed.
+    const answerShape = parseAnswerShapeInput(body.answerShape);
+    // 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,
+        answerShape,
+        recompute,
+    };
+}
+/**
+ * Staleness 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,
+        answerShape: parsed.answerShape,
+        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,114 @@
+/**
+ * Recompute scheduler: marks registrations stale when one of their source
+ * scopes changes and runs the compute when someone actually asks for the
+ * answer, one in flight per question. Timers and the clock are injectable
+ * so tests drive it deterministically.
+ *
+ * Compute is just-in-time, not preemptive. A source refresh only marks the
+ * answer stale; the recompute happens on the next authorized demand (a read
+ * of the derived scope, the reader-facing status route, or an explicit
+ * `POST /questions/:id/recompute`). Otherwise the inference bill would
+ * scale with how often the owner's sources refresh rather than with how
+ * often anyone reads the answer.
+ */
+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 before a recompute that was requested without `immediate`
+     * (default 5s). A source change schedules nothing at all, and demand runs
+     * at once, so nothing on the default deployment waits on this.
+     */
+    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
+     * NOTHING is scheduled: the recompute waits for demand. 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;
+    /**
+     * An authorized caller asked for the answer behind `derivedScope` — a read
+     * of the derived data, or the reader-facing status route. Every
+     * `on-change` question on that scope that is waiting for a compute
+     * (`stale` or `pending`) runs now; one already running or already
+     * scheduled is left alone, so N concurrent readers cause one compute.
+     *
+     * Callers MUST authorize first: this spends an inference call, and the
+     * whole point of running on demand is that the bill follows real reads.
+     * A `failed` question is not woken (its backoff chain or an explicit
+     * recompute owns it) so that polling a permanently failing question
+     * cannot spend a call per poll. Fire and forget; failures are logged.
+     */
+    markDemand(derivedScope: 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` (immediately). The first call is
+     * the boot reschedule: a question that has never produced an answer is
+     * owed the compute its registration asked for, and a restarted process
+     * only holds what the store holds. A `stale` question is NOT swept — it
+     * has an answer to serve and waits for demand, otherwise every restart
+     * (and in PS-Lite every tab that opens) would pay for the recomputes this
+     * scheduler exists to defer. 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;;;;;;;;;;;;GAYG;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;;;;OAIG;IACH,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;;;;;OAKG;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;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,+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;;;;;;;;;OASG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AA0DD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GACjC,kBAAkB,CA8UpB"}