@opendatalabs/personal-server-ts-core 1.7.0 → 1.9.0

package/dist/derivatives/inference.js

@@ -0,0 +1,159 @@
+/**
+ * Inference provider adapter for the derivative compute layer.
+ *
+ * One implementation: OpenAI-compatible chat completions over `fetch`, so it
+ * runs unchanged in Node and in the browser (PS-Lite). In production the
+ * base URL is the Vana inference relay, which holds the provider key; the
+ * optional API key header exists for local development against a provider
+ * directly.
+ *
+ * E2EE SEAM (not implemented): the Phala confidential-inference E2EE v2
+ * protocol encrypts each `messages[i].content` to the model's public key
+ * and adds the headers X-E2EE-Version, X-Client-Pub-Key, X-Model-Pub-Key,
+ * X-E2EE-Nonce and X-E2EE-Timestamp; the response content comes back
+ * encrypted to the client key. `InferenceRequestEncryption` below is the
+ * hook where that lands: it sees the outgoing messages + headers and the
+ * incoming content + headers, and nothing else in this module has to change.
+ */
+export const DEFAULT_INFERENCE_BASE_URL = "https://inference.phala.com/v1";
+export const DEFAULT_INFERENCE_MODEL = "z-ai/glm-5.2";
+export const DEFAULT_INFERENCE_TIMEOUT_MS = 120_000;
+export const DEFAULT_INFERENCE_MAX_TOKENS = 2_048;
+export const DEFAULT_INFERENCE_REQUEST_FIELDS = {
+    provider: { aci_verified: true, zdr: true },
+};
+/** Thrown for a non-2xx or malformed provider reply. Carries no prompt text. */
+export class InferenceRequestError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "InferenceRequestError";
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readUsage(value) {
+    if (!isRecord(value))
+        return undefined;
+    const num = (v) => (typeof v === "number" ? v : undefined);
+    const usage = {
+        promptTokens: num(value.prompt_tokens),
+        completionTokens: num(value.completion_tokens),
+        totalTokens: num(value.total_tokens),
+    };
+    return usage;
+}
+function readContent(body) {
+    if (!isRecord(body) || !Array.isArray(body.choices))
+        return null;
+    const first = body.choices[0];
+    if (!isRecord(first) || !isRecord(first.message))
+        return null;
+    const content = first.message.content;
+    if (typeof content === "string")
+        return content;
+    // Some providers return content parts.
+    if (Array.isArray(content)) {
+        const text = content
+            .map((part) => isRecord(part) && typeof part.text === "string" ? part.text : "")
+            .join("");
+        return text;
+    }
+    return null;
+}
+export function createOpenAiCompatibleInferenceProvider(options = {}) {
+    const base = (options.baseUrl ?? DEFAULT_INFERENCE_BASE_URL).replace(/\/+$/, "");
+    const defaultModel = options.model ?? DEFAULT_INFERENCE_MODEL;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_INFERENCE_TIMEOUT_MS;
+    const doFetch = options.fetch ?? fetch;
+    const requestFields = options.requestFields ?? DEFAULT_INFERENCE_REQUEST_FIELDS;
+    return {
+        defaultModel,
+        async chat(input) {
+            const headers = new Headers({ "Content-Type": "application/json" });
+            if (options.apiKey) {
+                headers.set("Authorization", `Bearer ${options.apiKey}`);
+            }
+            let messages = input.messages;
+            if (options.encryption) {
+                ({ messages } = await options.encryption.encryptRequest({
+                    messages,
+                    headers,
+                }));
+            }
+            const body = {
+                ...requestFields,
+                model: input.model || defaultModel,
+                messages,
+                max_tokens: input.maxTokens ?? DEFAULT_INFERENCE_MAX_TOKENS,
+            };
+            let response;
+            try {
+                response = await doFetch(`${base}/chat/completions`, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (err) {
+                // Transport failure: no status, no body. The message is the error
+                // class name only; it never carries request contents.
+                const name = err instanceof Error ? err.name : "Error";
+                throw new InferenceRequestError(`inference request failed before a response (${name})`, null);
+            }
+            if (!response.ok) {
+                throw new InferenceRequestError(`inference request failed with status ${response.status}`, response.status);
+            }
+            let parsed;
+            try {
+                parsed = await response.json();
+            }
+            catch {
+                throw new InferenceRequestError("inference response was not JSON", response.status);
+            }
+            let content = readContent(parsed);
+            if (content === null || content.trim() === "") {
+                // An empty reply must never become a "ready" derivative.
+                throw new InferenceRequestError("inference response carried no assistant content", response.status);
+            }
+            if (options.encryption) {
+                content = await options.encryption.decryptResponse({
+                    content,
+                    headers: response.headers,
+                });
+            }
+            const receiptId = response.headers.get("x-receipt-id") ?? undefined;
+            const aciIdentity = response.headers.get("x-aci-identity") ?? undefined;
+            return {
+                content,
+                usage: readUsage(isRecord(parsed) ? parsed.usage : undefined),
+                ...(receiptId ? { receiptId } : {}),
+                ...(aciIdentity ? { aciIdentity } : {}),
+            };
+        },
+    };
+}
+/** Test double: records calls, answers with a fixed JSON object by default. */
+export function createFakeInferenceProvider(options = {}) {
+    const calls = [];
+    return {
+        defaultModel: options.model ?? "fake-model",
+        calls,
+        async chat(input) {
+            calls.push(input);
+            if (options.respond)
+                return options.respond(input, calls.length - 1);
+            return {
+                content: JSON.stringify({
+                    answer: "fake answer",
+                    evidence: "fake evidence",
+                }),
+                receiptId: "fake-receipt",
+            };
+        },
+    };
+}
+//# sourceMappingURL=inference.js.map

package/dist/derivatives/inference.js.map

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

package/dist/derivatives/prompt.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Prompt assembly for a question: the source scopes' latest local records,
+ * trimmed newest-first to a bounded number of items each, framed by a system
+ * prompt that pins the model to the provided data and to a JSON answer.
+ *
+ * Nothing here leaves the Personal Server except through the inference
+ * provider call the compute step makes.
+ */
+import type { InferenceMessage } from "./inference.js";
+export declare const DEFAULT_MAX_SOURCE_ITEMS = 50;
+/** Upper bound on the serialized size of one source's trimmed data. */
+export declare const DEFAULT_MAX_SOURCE_CHARS = 200000;
+/**
+ * Newest first. Items that carry a timestamp sort by it; items that do not
+ * keep their relative order after the timestamped ones, reversed, on the
+ * assumption that a connector appends newest last. Stable.
+ */
+export declare function sortNewestFirst<T>(items: readonly T[]): T[];
+export interface TrimResult {
+    data: unknown;
+    /** Items kept / items present, summed over every array that was trimmed. */
+    kept: number;
+    total: number;
+    /** True when the char cap cut the serialization. */
+    truncated: boolean;
+}
+/**
+ * The trim rule. A record whose `data` is an array is trimmed to the newest
+ * `maxItems`; a record object trims every top-level array value the same
+ * way and keeps its other keys; reserved server keys are dropped. When the
+ * serialized result still exceeds `maxChars`, items are dropped from the
+ * old end until it fits (at least one is kept), and as a last resort the
+ * serialization itself is cut at `maxChars`.
+ */
+export declare function trimSourceData(data: unknown, options?: {
+    maxItems?: number;
+    maxChars?: number;
+}): TrimResult;
+export interface PromptSource {
+    scope: string;
+    collectedAt: string;
+    version: number;
+    data: unknown;
+    kept: number;
+    total: number;
+    truncated: boolean;
+}
+export declare const SYSTEM_PROMPT: string;
+/** Assemble the chat messages for one compute. */
+export declare function buildQuestionMessages(input: {
+    question: string;
+    sources: readonly PromptSource[];
+}): InferenceMessage[];
+export interface ParsedAnswer {
+    answer: string;
+    evidence: string | null;
+}
+/**
+ * Read the model's JSON answer. Tolerates a fenced code block or leading
+ * prose around the object; falls back to the whole text as the answer when
+ * no object can be parsed (the answer is still the model's, just unframed).
+ */
+export declare function parseAnswer(content: string): ParsedAnswer;
+//# sourceMappingURL=prompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/derivatives/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAyChD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAW3D;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,UAAU,CA+CZ;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,eAAO,MAAM,aAAa,QAMd,CAAC;AAEb,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAClC,GAAG,gBAAgB,EAAE,CA0BrB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAwBzD"}

package/dist/derivatives/prompt.js

@@ -0,0 +1,186 @@
+/**
+ * Prompt assembly for a question: the source scopes' latest local records,
+ * trimmed newest-first to a bounded number of items each, framed by a system
+ * prompt that pins the model to the provided data and to a JSON answer.
+ *
+ * Nothing here leaves the Personal Server except through the inference
+ * provider call the compute step makes.
+ */
+export const DEFAULT_MAX_SOURCE_ITEMS = 50;
+/** Upper bound on the serialized size of one source's trimmed data. */
+export const DEFAULT_MAX_SOURCE_CHARS = 200_000;
+/** Keys a record commonly carries its own timestamp under, in priority order. */
+const TIMESTAMP_KEYS = [
+    "collectedAt",
+    "updatedAt",
+    "updated_at",
+    "update_time",
+    "createdAt",
+    "created_at",
+    "create_time",
+    "timestamp",
+    "time",
+    "date",
+    "publishedAt",
+    "published_at",
+];
+/** Server-stamped envelope keys that are not user data. */
+const RESERVED_KEYS = new Set(["$lineage", "$writtenBy", "$binary"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function timestampOf(item) {
+    if (!isRecord(item))
+        return null;
+    for (const key of TIMESTAMP_KEYS) {
+        const value = item[key];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            // Seconds vs milliseconds: anything below 1e12 is taken as seconds.
+            return value < 1e12 ? value * 1000 : value;
+        }
+        if (typeof value === "string") {
+            const parsed = Date.parse(value);
+            if (!Number.isNaN(parsed))
+                return parsed;
+        }
+    }
+    return null;
+}
+/**
+ * Newest first. Items that carry a timestamp sort by it; items that do not
+ * keep their relative order after the timestamped ones, reversed, on the
+ * assumption that a connector appends newest last. Stable.
+ */
+export function sortNewestFirst(items) {
+    const indexed = items.map((item, index) => ({
+        item,
+        index,
+        at: timestampOf(item),
+    }));
+    const dated = indexed
+        .filter((entry) => entry.at !== null)
+        .sort((a, b) => b.at - a.at || b.index - a.index);
+    const undated = indexed.filter((entry) => entry.at === null).reverse();
+    return [...dated, ...undated].map((entry) => entry.item);
+}
+/**
+ * The trim rule. A record whose `data` is an array is trimmed to the newest
+ * `maxItems`; a record object trims every top-level array value the same
+ * way and keeps its other keys; reserved server keys are dropped. When the
+ * serialized result still exceeds `maxChars`, items are dropped from the
+ * old end until it fits (at least one is kept), and as a last resort the
+ * serialization itself is cut at `maxChars`.
+ */
+export function trimSourceData(data, options = {}) {
+    const maxItems = Math.max(1, options.maxItems ?? DEFAULT_MAX_SOURCE_ITEMS);
+    const maxChars = Math.max(1, options.maxChars ?? DEFAULT_MAX_SOURCE_CHARS);
+    let kept = 0;
+    let total = 0;
+    const trimArray = (items, limit) => {
+        total += items.length;
+        const sorted = sortNewestFirst(items).slice(0, limit);
+        kept += sorted.length;
+        return sorted;
+    };
+    const build = (limit) => {
+        kept = 0;
+        total = 0;
+        if (Array.isArray(data))
+            return trimArray(data, limit);
+        if (isRecord(data)) {
+            const out = {};
+            for (const [key, value] of Object.entries(data)) {
+                if (RESERVED_KEYS.has(key))
+                    continue;
+                out[key] = Array.isArray(value) ? trimArray(value, limit) : value;
+            }
+            return out;
+        }
+        return data;
+    };
+    let limit = maxItems;
+    let result = build(limit);
+    let text = JSON.stringify(result) ?? "null";
+    // Shrink the item budget while the serialization is over the cap. Each
+    // pass at least halves the budget, so this ends in O(log maxItems) steps.
+    while (text.length > maxChars && limit > 1) {
+        limit = Math.max(1, Math.floor(limit / 2));
+        result = build(limit);
+        text = JSON.stringify(result) ?? "null";
+    }
+    if (text.length > maxChars) {
+        return {
+            data: `${text.slice(0, maxChars)}...[truncated]`,
+            kept,
+            total,
+            truncated: true,
+        };
+    }
+    return { data: result, kept, total, truncated: false };
+}
+export const SYSTEM_PROMPT = [
+    "You answer a question about a person using ONLY the user data provided in the message.",
+    "Do not use outside knowledge and do not guess; if the data does not support an answer, say so in the answer.",
+    "Respond with a single JSON object and nothing else, with exactly these fields:",
+    '  "answer": string, the answer to the question, written for the person the data belongs to;',
+    '  "evidence": string, a short summary of which parts of the data support the answer.',
+].join("\n");
+/** Assemble the chat messages for one compute. */
+export function buildQuestionMessages(input) {
+    const sections = input.sources.map((source) => {
+        const note = source.total > source.kept
+            ? ` (newest ${source.kept} of ${source.total} items)`
+            : "";
+        const cut = source.truncated ? " (truncated)" : "";
+        return [
+            `### Scope: ${source.scope}${note}${cut}`,
+            `Collected at: ${source.collectedAt}`,
+            JSON.stringify(source.data),
+        ].join("\n");
+    });
+    const user = [
+        "## Question",
+        input.question,
+        "",
+        "## User data",
+        ...sections,
+        "",
+        "Answer the question as a JSON object with the fields answer and evidence.",
+    ].join("\n");
+    return [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: user },
+    ];
+}
+/**
+ * Read the model's JSON answer. Tolerates a fenced code block or leading
+ * prose around the object; falls back to the whole text as the answer when
+ * no object can be parsed (the answer is still the model's, just unframed).
+ */
+export function parseAnswer(content) {
+    const candidates = [content.trim()];
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(content);
+    if (fenced?.[1])
+        candidates.unshift(fenced[1].trim());
+    const first = content.indexOf("{");
+    const last = content.lastIndexOf("}");
+    if (first !== -1 && last > first) {
+        candidates.push(content.slice(first, last + 1));
+    }
+    for (const candidate of candidates) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (isRecord(parsed) && typeof parsed.answer === "string") {
+                return {
+                    answer: parsed.answer,
+                    evidence: typeof parsed.evidence === "string" ? parsed.evidence : null,
+                };
+            }
+        }
+        catch {
+            // try the next framing
+        }
+    }
+    return { answer: content.trim(), evidence: null };
+}
+//# sourceMappingURL=prompt.js.map

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,53 @@
+/**
+ * Question registration: input validation, the naming rule (shared with the
+ * lineage write path) and the cycle guard that keeps recompute-on-refresh
+ * bounded.
+ */
+import type { 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;
+}
+/**
+ * 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;
+/**
+ * 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 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;AAUH,OAAO,KAAK,EACV,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;CACtB;AAyBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,CA8DrE;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,CA2B/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,163 @@
+/**
+ * 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;
+    }
+    assertDerivedScopeNaming(derivedScope, sourceScopes);
+    return { derivedScope, sourceScopes, question: body.question, model };
+}
+/**
+ * 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,
+        registeredBy: input.registeredBy,
+        status: "pending",
+        error: 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