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

package/dist/derivatives/answer-shape.js

@@ -0,0 +1,320 @@
+/**
+ * The declared shape of a question's answer.
+ *
+ * Without one an answer is free text, so a builder can ask for anything the
+ * prompt saw and get it back verbatim in a string field. A registration may
+ * instead declare, up front, the fields its answer is made of; the compute
+ * step then instructs the model to answer in that shape and validates the
+ * reply against it, so a 1-5 score is a number between 1 and 5 and not a
+ * field the raw conversations can be poured into. The declaration is part
+ * of what the owner approves, which is also what makes a later recompute
+ * the same promise: a new version matches the shape the old one did.
+ *
+ * The grammar is deliberately tiny and flat: a list of named fields with a
+ * primitive type and a couple of constraints, no nesting and no free-text
+ * keys. Everything a builder can put in it is bounded (see the limits
+ * below), so a shape cannot be used to smuggle a second prompt past the
+ * 8000-character cap on the question text.
+ */
+import { z } from "zod";
+import { DerivativeQuestionInvalidError } from "../errors/catalog.js";
+export const MAX_ANSWER_SHAPE_FIELDS = 16;
+export const MAX_ANSWER_FIELD_NAME_CHARS = 64;
+/** Also the cap on a declared `maxLength`, and the default when none is. */
+export const MAX_ANSWER_STRING_CHARS = 4_000;
+export const MAX_ANSWER_ENUM_VALUES = 32;
+export const MAX_ANSWER_ENUM_VALUE_CHARS = 64;
+/** Field names are identifiers: they go into the prompt verbatim. */
+const FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+const FIELD_TYPES = [
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "enum",
+];
+/** Keys accepted on a field, by type. Anything else is refused. */
+const KEYS_BY_TYPE = {
+    string: ["name", "type", "required", "maxLength"],
+    number: ["name", "type", "required", "min", "max"],
+    integer: ["name", "type", "required", "min", "max"],
+    boolean: ["name", "type", "required"],
+    enum: ["name", "type", "required", "values"],
+};
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function invalid(message, details) {
+    throw new DerivativeQuestionInvalidError(message, {
+        field: "answerShape",
+        ...details,
+    });
+}
+function parseFieldName(value, index) {
+    if (typeof value !== "string" || value === "") {
+        invalid(`answerShape.fields[${index}].name must be a non-empty string`, {
+            index,
+        });
+    }
+    if (value.length > MAX_ANSWER_FIELD_NAME_CHARS) {
+        invalid(`answerShape.fields[${index}].name is ${value.length} characters; the maximum is ${MAX_ANSWER_FIELD_NAME_CHARS}`, { index, max: MAX_ANSWER_FIELD_NAME_CHARS });
+    }
+    if (!FIELD_NAME.test(value)) {
+        invalid(`answerShape.fields[${index}].name must start with a letter and hold only letters, digits and underscores`, { index });
+    }
+    return value;
+}
+function parseBound(value, index, key, integer) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        invalid(`answerShape.fields[${index}].${key} must be a finite number`, {
+            index,
+            key,
+        });
+    }
+    if (integer && !Number.isSafeInteger(value)) {
+        invalid(`answerShape.fields[${index}].${key} must be a safe integer for an integer field`, { index, key });
+    }
+    return value;
+}
+function parseEnumValues(value, index) {
+    if (!Array.isArray(value) || value.length === 0) {
+        invalid(`answerShape.fields[${index}].values must be a non-empty array of strings`, { index });
+    }
+    if (value.length > MAX_ANSWER_ENUM_VALUES) {
+        invalid(`answerShape.fields[${index}].values lists ${value.length} values; the maximum is ${MAX_ANSWER_ENUM_VALUES}`, { index, max: MAX_ANSWER_ENUM_VALUES });
+    }
+    const values = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || entry === "") {
+            invalid(`answerShape.fields[${index}].values must hold non-empty strings`, { index });
+        }
+        if (entry.length > MAX_ANSWER_ENUM_VALUE_CHARS) {
+            invalid(`answerShape.fields[${index}].values holds a ${entry.length} character value; the maximum is ${MAX_ANSWER_ENUM_VALUE_CHARS}`, { index, max: MAX_ANSWER_ENUM_VALUE_CHARS });
+        }
+        // Enum values are the one place a builder writes free text into the
+        // prompt. Line breaks would let a value pose as its own instruction
+        // line in the shape description, so they are refused outright.
+        if (/[\n\r\t]/.test(entry)) {
+            invalid(`answerShape.fields[${index}].values must not hold line breaks or tabs`, { index });
+        }
+        if (values.includes(entry)) {
+            invalid(`answerShape.fields[${index}].values lists the same value twice`, { index });
+        }
+        values.push(entry);
+    }
+    return values;
+}
+function parseField(value, index) {
+    if (!isRecord(value)) {
+        invalid(`answerShape.fields[${index}] must be an object`, { index });
+    }
+    const name = parseFieldName(value.name, index);
+    if (typeof value.type !== "string" ||
+        !FIELD_TYPES.includes(value.type)) {
+        invalid(`answerShape.fields[${index}].type must be one of ${FIELD_TYPES.join(", ")}`, { index });
+    }
+    const type = value.type;
+    const allowed = KEYS_BY_TYPE[type];
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            invalid(`answerShape.fields[${index}] does not accept "${key}" on a ${type} field`, { index, key: key.slice(0, MAX_ANSWER_FIELD_NAME_CHARS) });
+        }
+    }
+    // A declared field is part of the promise, so it is required unless the
+    // registration says otherwise.
+    let required = true;
+    if (value.required !== undefined && value.required !== null) {
+        if (typeof value.required !== "boolean") {
+            invalid(`answerShape.fields[${index}].required must be a boolean`, {
+                index,
+            });
+        }
+        required = value.required;
+    }
+    const field = { name, type, required };
+    if (type === "string") {
+        let maxLength = MAX_ANSWER_STRING_CHARS;
+        if (value.maxLength !== undefined && value.maxLength !== null) {
+            if (typeof value.maxLength !== "number" ||
+                !Number.isSafeInteger(value.maxLength) ||
+                value.maxLength < 1 ||
+                value.maxLength > MAX_ANSWER_STRING_CHARS) {
+                invalid(`answerShape.fields[${index}].maxLength must be an integer between 1 and ${MAX_ANSWER_STRING_CHARS}`, { index, max: MAX_ANSWER_STRING_CHARS });
+            }
+            maxLength = value.maxLength;
+        }
+        field.maxLength = maxLength;
+    }
+    if (type === "number" || type === "integer") {
+        const integer = type === "integer";
+        if (value.min !== undefined && value.min !== null) {
+            field.min = parseBound(value.min, index, "min", integer);
+        }
+        if (value.max !== undefined && value.max !== null) {
+            field.max = parseBound(value.max, index, "max", integer);
+        }
+        if (field.min !== undefined &&
+            field.max !== undefined &&
+            field.min > field.max) {
+            invalid(`answerShape.fields[${index}].min is greater than its max`, {
+                index,
+            });
+        }
+    }
+    if (type === "enum") {
+        field.values = parseEnumValues(value.values, index);
+    }
+    return field;
+}
+/**
+ * Validate the optional `answerShape` of a registration body. Absent (or
+ * null, like `model`) means free text, the original behavior.
+ */
+export function parseAnswerShapeInput(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (!isRecord(value)) {
+        invalid("answerShape must be an object with a fields array", {});
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== "fields") {
+            invalid(`answerShape does not accept "${key}"`, {
+                key: key.slice(0, MAX_ANSWER_FIELD_NAME_CHARS),
+            });
+        }
+    }
+    if (!Array.isArray(value.fields) || value.fields.length === 0) {
+        invalid("answerShape.fields must be a non-empty array", {});
+    }
+    if (value.fields.length > MAX_ANSWER_SHAPE_FIELDS) {
+        invalid(`answerShape.fields lists ${value.fields.length} fields; the maximum is ${MAX_ANSWER_SHAPE_FIELDS}`, { max: MAX_ANSWER_SHAPE_FIELDS });
+    }
+    const fields = [];
+    const names = new Set();
+    value.fields.forEach((entry, index) => {
+        const field = parseField(entry, index);
+        if (names.has(field.name)) {
+            invalid(`answerShape.fields names "${field.name}" twice`, { index });
+        }
+        names.add(field.name);
+        fields.push(field);
+    });
+    return { fields };
+}
+/**
+ * Compile the declaration to the zod schema the reply is checked against.
+ * The object STRIPS unknown keys rather than refusing them: a model that
+ * adds chatter next to the declared fields still produces a valid answer,
+ * and the extra key never reaches the record.
+ */
+export function compileAnswerShape(shape) {
+    const entries = {};
+    for (const field of shape.fields) {
+        let schema;
+        switch (field.type) {
+            case "string":
+                schema = z.string().max(field.maxLength ?? MAX_ANSWER_STRING_CHARS);
+                break;
+            case "number":
+            case "integer": {
+                // zod rejects NaN and Infinity for `number` already, so the bounds
+                // are the only thing left to apply.
+                let numeric = field.type === "integer" ? z.int() : z.number();
+                if (field.min !== undefined)
+                    numeric = numeric.min(field.min);
+                if (field.max !== undefined)
+                    numeric = numeric.max(field.max);
+                schema = numeric;
+                break;
+            }
+            case "boolean":
+                schema = z.boolean();
+                break;
+            case "enum":
+                schema = z.enum(field.values ?? []);
+                break;
+        }
+        entries[field.name] = field.required ? schema : schema.nullish();
+    }
+    return z.object(entries);
+}
+/**
+ * Check one candidate answer object against a compiled shape. On success
+ * the value is rebuilt in declaration order with the optional fields the
+ * model left out (or nulled) dropped, so the stored value has one form.
+ */
+export function validateAnswerShape(shape, compiled, candidate) {
+    const parsed = compiled.safeParse(candidate);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            // zod's messages state the constraint ("expected int", "<=5") and
+            // never echo the received value, so they are safe to hand back to
+            // the model in the corrective turn.
+            issues: parsed.error.issues.map((issue) => {
+                const path = issue.path.join(".");
+                return path ? `${path}: ${issue.message}` : issue.message;
+            }),
+        };
+    }
+    const value = {};
+    for (const field of shape.fields) {
+        const entry = parsed.data[field.name];
+        if (entry === undefined || entry === null)
+            continue;
+        value[field.name] = entry;
+    }
+    return { ok: true, value };
+}
+function describeField(field) {
+    const requirement = field.required ? "required" : "optional";
+    switch (field.type) {
+        case "string":
+            return `"${field.name}": string, at most ${field.maxLength ?? MAX_ANSWER_STRING_CHARS} characters (${requirement})`;
+        case "number":
+        case "integer": {
+            const kind = field.type === "integer" ? "integer" : "number";
+            const range = field.min !== undefined && field.max !== undefined
+                ? ` between ${field.min} and ${field.max}`
+                : field.min !== undefined
+                    ? ` of at least ${field.min}`
+                    : field.max !== undefined
+                        ? ` of at most ${field.max}`
+                        : "";
+            return `"${field.name}": ${kind}${range} (${requirement})`;
+        }
+        case "boolean":
+            return `"${field.name}": true or false (${requirement})`;
+        case "enum":
+            return `"${field.name}": exactly one of ${(field.values ?? [])
+                .map((entry) => JSON.stringify(entry))
+                .join(", ")} (${requirement})`;
+    }
+}
+/** The shape as prompt lines, one per field, in declaration order. */
+export function describeAnswerShape(shape) {
+    return shape.fields.map((field) => `  ${describeField(field)}`);
+}
+/**
+ * The human-readable rendering kept in the record's `answer` string. The
+ * structured value next to it is authoritative; this is what a reader that
+ * only knows the old free-text field sees.
+ */
+export function renderShapedAnswer(shape, value) {
+    return shape.fields
+        .filter((field) => value[field.name] !== undefined)
+        .map((field) => `${field.name}: ${String(value[field.name])}`)
+        .join("\n");
+}
+/** Deep copy, so a stored shape is never aliased by a view or a caller. */
+export function cloneAnswerShape(shape) {
+    if (!shape)
+        return null;
+    return {
+        fields: shape.fields.map((field) => ({
+            ...field,
+            ...(field.values ? { values: [...field.values] } : {}),
+        })),
+    };
+}
+//# sourceMappingURL=answer-shape.js.map

package/dist/derivatives/answer-shape.js.map

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

package/dist/derivatives/api.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HTTP surface of the compute layer, mounted under `/v1/derivatives`:
+ *
+ *   POST   /questions                 register (builder write auth or owner)
+ *   GET    /questions                 list (owner; builder with ?derivedScope=)
+ *   GET    /questions/:id             status (owner or the registering builder)
+ *   POST   /questions/:id/recompute   owner or the registering builder
+ *   DELETE /questions/:id             owner or the registering builder
+ *
+ * Builder authentication is the Write API's: a write-session bearer token
+ * plus the X-Vana-Write-Signature proof over the request, authorized for
+ * `write:<derivedScope>` (api-auth authorizeWrite). No new credential.
+ *
+ * The proof signs the request URI INCLUDING its query string (see
+ * canonicalSignedUri in write/attribution.ts), because on the list route the
+ * query decides the authorization: `?derivedScope=X` is the scope the caller
+ * is authorized against, and a proof that did not commit to it could be
+ * captured on one scope and replayed on another.
+ */
+import type { PersonalServerApiAuthPort, PersonalServerApiDispatchOptions } from "../api/index.js";
+import type { RecomputeScheduler } from "./scheduler.js";
+import { type QuestionStore } from "./types.js";
+/** Registration bodies are small; anything larger is refused up front. */
+export declare const MAX_QUESTION_BODY_BYTES: number;
+export interface PersonalServerDerivativesApiDeps {
+    auth: Pick<PersonalServerApiAuthPort, "authorizeOwner" | "authorizeWrite" | "authorizeWriteSession" | "authorizeBuilderRead">;
+    /** Absent = the compute layer is not wired; every route answers 503. */
+    compute?: {
+        store: QuestionStore;
+        scheduler: Pick<RecomputeScheduler, "requestRecompute" | "markSourceChanged" | "markDemand"> & {
+            /**
+             * Next scheduled automatic retry of a failed question (ISO time), or
+             * null. Optional so a minimal scheduler stays a valid dependency; the
+             * status route then reports no retry.
+             */
+            nextRetryAt?(questionId: string): string | null;
+            /** True while a retry compute is running (timer fired, not settled). */
+            retryInFlight?(questionId: string): boolean;
+        };
+    } | null;
+    now?: () => Date;
+    createQuestionId?: () => string;
+    logger?: {
+        info?(payload: Record<string, unknown>, message: string): void;
+    };
+}
+export declare function handlePersonalServerDerivativesRequest(request: Request, deps: PersonalServerDerivativesApiDeps, options?: PersonalServerApiDispatchOptions): Promise<Response>;
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/derivatives/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAaH,OAAO,KAAK,EACV,yBAAyB,EACzB,gCAAgC,EAGjC,MAAM,iBAAiB,CAAC;AAMzB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAEpB,0EAA0E;AAC1E,eAAO,MAAM,uBAAuB,QAAY,CAAC;AAKjD,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,IAAI,CACR,yBAAyB,EACvB,gBAAgB,GAChB,gBAAgB,GAChB,uBAAuB,GACvB,sBAAsB,CACzB,CAAC;IACF,wEAAwE;IACxE,OAAO,CAAC,EAAE;QACR,KAAK,EAAE,aAAa,CAAC;QACrB,SAAS,EAAE,IAAI,CACb,kBAAkB,EAClB,kBAAkB,GAAG,mBAAmB,GAAG,YAAY,CACxD,GAAG;YACF;;;;eAIG;YACH,WAAW,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;YAChD,wEAAwE;YACxE,aAAa,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;SAC7C,CAAC;KACH,GAAG,IAAI,CAAC;IACT,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,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;AA+OD,wBAAsB,sCAAsC,CAC1D,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,gCAAgC,EACtC,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CAAC,QAAQ,CAAC,CAqMnB"}