@yadsh/dsh-qa-surface 0.17.0 → 0.19.0

package/lib/forms/attachments.js

@@ -0,0 +1,230 @@
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { readZipEntries, readZipEntry } from "@yadsh/dsh-documents";
+import { z } from "zod";
+import { formAssert, QaFormError } from "./errors.js";
+import { parseFormSchema } from "./schema.js";
+const fileRef = z.object({
+    attachmentId: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    name: z.string().min(1),
+    bytes: z.number().int().positive(),
+});
+const receipt = z.object({ receiptId: z.string().min(1), file: fileRef });
+export function validateFormFile(name, data) {
+    const ext = path.extname(name).toLowerCase();
+    const check = (ok) => formAssert(ok, "FILE_INVALID", "The file content does not match its declared format.");
+    check(data.length > 0);
+    if (ext === ".txt" || ext === ".csv") {
+        check(!data.includes(0));
+        try {
+            new TextDecoder("utf-8", { fatal: true }).decode(data);
+        }
+        catch {
+            check(false);
+        }
+        return ext === ".csv" ? "text/csv" : "text/plain";
+    }
+    if (ext === ".pdf") {
+        check(data.subarray(0, 5).toString("ascii") === "%PDF-" &&
+            data.subarray(-2048).includes(Buffer.from("%%EOF")));
+        return "application/pdf";
+    }
+    if (ext === ".png") {
+        check(data
+            .subarray(0, 8)
+            .equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) &&
+            data.length >= 33);
+        return "image/png";
+    }
+    if (ext === ".jpg" || ext === ".jpeg") {
+        check(data[0] === 255 &&
+            data[1] === 216 &&
+            data[2] === 255 &&
+            data.at(-2) === 255 &&
+            data.at(-1) === 217);
+        return "image/jpeg";
+    }
+    if (ext === ".docx" || ext === ".xlsx") {
+        const entries = readZipEntries(data);
+        check(entries && entries.length <= 10000);
+        const parts = entries;
+        check(new Set(parts.map((p) => p.name)).size === parts.length &&
+            parts.every((p) => p.uncompressedSize <= 64 * 1024 * 1024 &&
+                !/vbaProject|(^|\/)\.\.(\/|$)/iu.test(p.name)) &&
+            parts.reduce((n, p) => n + p.uncompressedSize, 0) <= 128 * 1024 * 1024);
+        const expected = ext === ".docx" ? "word/document.xml" : "xl/workbook.xml";
+        for (const required of ["[Content_Types].xml", "_rels/.rels", expected]) {
+            const entry = parts.find((p) => p.name === required);
+            check(entry && entry.uncompressedSize <= 4 * 1024 * 1024);
+            const bytes = readZipEntry(data, entry);
+            check(bytes &&
+                bytes.length <= 4 * 1024 * 1024 &&
+                !/<!DOCTYPE|<!ENTITY|macroEnabled/iu.test(bytes.toString("utf8")));
+        }
+        return ext === ".docx"
+            ? "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+            : "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    }
+    throw new QaFormError("FILE_TYPE_NOT_ALLOWED", "Unsupported file format.");
+}
+/** Durable bytes belong to the form store; Host objects are verified reader projections. */
+export class QaFormAttachmentAdapter {
+    service;
+    host;
+    grantFile;
+    constructor(service, host, grantFile) {
+        this.service = service;
+        this.host = host;
+        this.grantFile = grantFile;
+    }
+    available() {
+        const host = this.host();
+        return (host !== undefined &&
+            typeof host.root === "string" &&
+            path.isAbsolute(host.root) &&
+            typeof host.readFileStream === "function" &&
+            typeof host.saveFile === "function" &&
+            typeof host.fileHostPath === "function");
+    }
+    check(session, formId, uploadId) {
+        const s = this.service();
+        s.enabled();
+        const r = s.get(session, formId), u = r.uploads.find((v) => v.id === uploadId);
+        formAssert(r.status === "draft" &&
+            u?.state === "uploading" &&
+            u.expires_at > Date.now(), "UPLOAD_FAILED", "This upload is no longer active.");
+        parseFormSchema(r.schema, s.policy());
+    }
+    claim(session, uploadId) {
+        const s = this.service();
+        s.enabled();
+        formAssert(this.available(), "INTERACTION_UNAVAILABLE", "The Host has no durable local file projection.");
+        const record = s.store
+            .list(session)
+            .find((r) => r.uploads.some((u) => u.id === uploadId));
+        formAssert(record, "ACCESS_DENIED", "Upload access is unavailable.");
+        const updated = s.store.update(session, record.id, (r) => {
+            const u = r.uploads.find((v) => v.id === uploadId);
+            formAssert(r.status === "draft" &&
+                u.state === "pending" &&
+                u.expires_at > Date.now(), "UPLOAD_FAILED", "This upload is no longer pending. Check its saved state before retrying.");
+            u.state = "uploading";
+        });
+        return {
+            record: updated,
+            upload: updated.uploads.find((u) => u.id === uploadId),
+        };
+    }
+    async complete(session, formId, uploadId, raw, signal, authorize) {
+        const s = this.service(), host = this.host();
+        formAssert(host, "INTERACTION_UNAVAILABLE", "This Host cannot retain and read form files.");
+        const parsed = receipt.safeParse(raw);
+        formAssert(parsed.success, "FILE_UNAVAILABLE", "The Host returned an unsupported upload receipt.");
+        const r = s.get(session, formId), u = r.uploads.find((v) => v.id === uploadId);
+        formAssert(u && u.state === "uploading", "UPLOAD_FAILED", "This upload is no longer active.");
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of host.readFileStream(parsed.data.file, signal)) {
+            signal.throwIfAborted();
+            authorize();
+            size += chunk.byteLength;
+            formAssert(size <= u.size_bytes && size <= s.policy().maxFileSizeBytes, "FILE_TOO_LARGE", "The uploaded file exceeds its reserved size.");
+            chunks.push(Buffer.from(chunk));
+        }
+        const bytes = Buffer.concat(chunks), hash = createHash("sha256").update(bytes).digest("hex");
+        formAssert(size === u.size_bytes &&
+            size === parsed.data.file.bytes &&
+            parsed.data.file.attachmentId === `sha256:${hash}`, "FILE_INVALID", "The uploaded file failed its integrity check.");
+        const mediaType = validateFormFile(u.name, bytes);
+        if (mediaType === "image/png" || mediaType === "image/jpeg") {
+            formAssert(typeof host.validateImage === "function", "FILE_TYPE_NOT_ALLOWED", "This Host cannot validate image files.");
+            try {
+                await host.validateImage({ data: bytes, mediaType, name: u.name });
+            }
+            catch {
+                throw new QaFormError("FILE_INVALID", "The image failed the Host's content and dimension checks.");
+            }
+        }
+        signal.throwIfAborted();
+        authorize();
+        s.enabled();
+        return s.store.update(session, formId, (record) => {
+            parseFormSchema(record.schema, s.policy());
+            const intent = record.uploads.find((v) => v.id === uploadId);
+            formAssert(record.status === "draft" &&
+                intent.state === "uploading" &&
+                intent.expires_at > Date.now(), "UPLOAD_FAILED", "This upload was cancelled or expired.");
+            const active = record.attachments[intent.item_id] ?? [];
+            formAssert(!active.some((a) => a.sha256 === hash), "FILE_INVALID", "This item already contains the same file.");
+            if (intent.target)
+                formAssert(active.some((a) => a.attachment_id === intent.target?.attachment_id &&
+                    a.version === intent.target.version), "ATTACHMENT_VERSION_CONFLICT", "The replaced file changed while uploading.");
+            const result = {
+                attachment_id: intent.target?.attachment_id ?? randomUUID(),
+                version: (intent.target?.version ?? 0) + 1,
+                name: intent.name,
+                size_bytes: size,
+                media_type: mediaType,
+                sha256: hash,
+                resource_id: randomUUID(),
+            };
+            s.store.saveResource(formId, result.resource_id, bytes);
+            record.attachments[intent.item_id] = [
+                ...active.filter((a) => a.attachment_id !== result.attachment_id),
+                result,
+            ];
+            intent.state = "ready";
+            intent.result = result;
+        });
+    }
+    fail(session, formId, uploadId) {
+        const prior = this.service().get(session, formId);
+        if (prior.status !== "draft" ||
+            !prior.uploads.some((u) => u.id === uploadId && u.state === "uploading"))
+            return;
+        this.service().store.update(session, formId, (r) => {
+            const u = r.uploads.find((v) => v.id === uploadId);
+            if (u?.state === "uploading") {
+                u.state = "failed";
+                u.error = "UPLOAD_FAILED";
+            }
+        });
+    }
+    /** Exact saved bytes are re-projected through the Host on each successful resume. */
+    async readable(submission, sessionId) {
+        if (sessionId !== undefined) {
+            const saved = this.service().get(sessionId, submission.form_id);
+            formAssert(saved.submission?.submission_id === submission.submission_id, "ACCESS_DENIED", "The submitted form is unavailable in this chat.");
+            submission = saved.submission;
+        }
+        const resources = [];
+        for (const item of submission.items)
+            for (const file of item.files) {
+                const host = this.host();
+                formAssert(host, "FILE_UNAVAILABLE", "The Host file reader is unavailable.");
+                const data = this.service().store.resource(submission.form_id, file.resource_id);
+                formAssert(createHash("sha256").update(data).digest("hex") === file.sha256, "FILE_UNAVAILABLE", "The saved file failed its integrity check.");
+                const raw = await host.saveFile({ data, name: file.name }), parsed = fileRef.safeParse(raw);
+                formAssert(parsed.success &&
+                    parsed.data.attachmentId === `sha256:${file.sha256}`, "FILE_UNAVAILABLE", "The Host cannot project the saved version.");
+                const readPath = host.fileHostPath(parsed.data);
+                formAssert(readPath &&
+                    path.isAbsolute(readPath) &&
+                    path.relative(host.root, readPath) !== "" &&
+                    !path.relative(host.root, readPath).startsWith("..") &&
+                    !path.isAbsolute(path.relative(host.root, readPath)), "FILE_UNAVAILABLE", "The Host has no file reader projection.");
+                resources.push({ resource_id: file.resource_id, read_path: readPath });
+                if (sessionId !== undefined)
+                    this.grantFile?.(sessionId, readPath);
+            }
+        return { ...submission, resources };
+    }
+    /** Rebuild exact grants from this chat's persisted, verified submissions. */
+    async restore(sessionId) {
+        for (const record of this.service().store.list(sessionId)) {
+            if (record.status === "submitted" && record.submission !== undefined)
+                await this.readable(record.submission, sessionId);
+        }
+    }
+}
+//# sourceMappingURL=attachments.js.map

package/lib/forms/attachments.js.map

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

package/lib/forms/errors.js

@@ -0,0 +1,37 @@
+export class QaFormError extends Error {
+    code;
+    revision;
+    fields;
+    constructor(code, message, revision, fields) {
+        super(message);
+        this.code = code;
+        this.revision = revision;
+        this.fields = fields;
+    }
+}
+/** Deliberately redact unexpected storage/Host exceptions at the wire boundary. */
+export function formFailure(error) {
+    return {
+        ok: false,
+        error: error instanceof QaFormError
+            ? {
+                code: error.code,
+                message: error.message,
+                ...(error.revision === undefined
+                    ? {}
+                    : { form_revision: error.revision }),
+                ...(error.fields === undefined
+                    ? {}
+                    : { field_errors: error.fields }),
+            }
+            : {
+                code: "STORAGE_UNAVAILABLE",
+                message: "Form storage is unavailable. Retry without discarding your draft.",
+            },
+    };
+}
+export function formAssert(condition, code, message) {
+    if (!condition)
+        throw new QaFormError(code, message);
+}
+//# sourceMappingURL=errors.js.map

package/lib/forms/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/forms/errors.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,WAAY,SAAQ,KAAK;IAEzB,IAAI;IAEJ,QAAQ;IACR,MAAM;IAJjB,YACW,IAAY,EACrB,OAAe,EACN,QAAiB,EACjB,MAA2B;QAEpC,KAAK,CAAC,OAAO,CAAC,CAAC;oBALN,IAAI;wBAEJ,QAAQ;sBACR,MAAM;IAGjB,CAAC;CACF;AACD,mFAAmF;AACnF,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO;QACL,EAAE,EAAE,KAAK;QACT,KAAK,EACH,KAAK,YAAY,WAAW;YAC1B,CAAC,CAAC;gBACE,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS;oBAC9B,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACtC,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS;oBAC5B,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;aACpC;YACH,CAAC,CAAC;gBACE,IAAI,EAAE,qBAAqB;gBAC3B,OAAO,EACL,mEAAmE;aACtE;KACR,CAAC;AACJ,CAAC;AACD,MAAM,UAAU,UAAU,CACxB,SAAkB,EAClB,IAAY,EACZ,OAAe;IAEf,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACvD,CAAC"}

package/lib/forms/fingerprint.js

@@ -0,0 +1,21 @@
+import { createHash } from "node:crypto";
+/**
+ * Stable object-key ordering for schema and idempotency fingerprints.
+ *
+ * Lives apart from the sqlite store so every store implementation hashes the
+ * same way without importing the sqlite bridge: the client test graph mounts a
+ * store too, and a browser environment must not see `@yadsh/dsh-plugin-kit/sqlite`.
+ */
+export function fingerprint(value) {
+    const canonical = (v) => Array.isArray(v)
+        ? v.map(canonical)
+        : v !== null && typeof v === "object"
+            ? Object.fromEntries(Object.entries(v)
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([k, x]) => [k, canonical(x)]))
+            : v;
+    return `sha256:${createHash("sha256")
+        .update(JSON.stringify(canonical(value)))
+        .digest("hex")}`;
+}
+//# sourceMappingURL=fingerprint.js.map

package/lib/forms/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/forms/fingerprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,MAAM,SAAS,GAAG,CAAC,CAAU,EAAW,EAAE,CACxC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACd,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC;QAClB,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;YACnC,CAAC,CAAC,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;iBACd,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;iBACtC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CACtC;YACH,CAAC,CAAC,CAAC,CAAC;IACV,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC;SAClC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;SACxC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACrB,CAAC"}

package/lib/forms/gate.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import { formAssert, QaFormError } from "./errors.js";
+import { parseFormSchema } from "./schema.js";
+const argsParser = z.discriminatedUnion("action", [
+    z
+        .object({
+        action: z.literal("create"),
+        request_key: z.string(),
+        form: z.unknown(),
+    })
+        .strict(),
+    z.object({ action: z.literal("resume"), form_id: z.string() }).strict(),
+]);
+/** A parked tool call is transient. Never reconstruct one from a saved draft. */
+export class QaFormGate {
+    service;
+    rootOf;
+    busy;
+    allowed;
+    filesAvailable;
+    waiters = new Map();
+    disposers = [];
+    closed = false;
+    clients = new Map();
+    constructor(service, rootOf, busy, allowed, filesAvailable = () => false) {
+        this.service = service;
+        this.rootOf = rootOf;
+        this.busy = busy;
+        this.allowed = allowed;
+        this.filesAvailable = filesAvailable;
+    }
+    install(ctx) {
+        this.disposers.push(ctx.on("agent/disposed", ({ agent }) => this.cancel(String(agent.session.id))), ctx.on("agent/status", ({ agent, status }) => {
+            if (status === "idle")
+                this.cancel(String(agent.session.id));
+        }));
+    }
+    waiting(id) {
+        return this.waiters.has(id);
+    }
+    touch(session) {
+        this.clients.set(session, Date.now());
+    }
+    hasSession(session) {
+        return [...this.waiters.values()].some((w) => w.session === session);
+    }
+    async request(raw, exec) {
+        const parsed = argsParser.safeParse(raw);
+        formAssert(parsed.success, "INVALID_SCHEMA", "Provide create with a schema, or resume with a form_id.");
+        exec.signal.throwIfAborted();
+        formAssert(!this.closed && this.allowed(exec), "INTERACTION_UNAVAILABLE", "An interactive QA form is unavailable for this request.");
+        const agentId = exec.agent === undefined ? "" : String(exec.agent.session.id), session = this.rootOf(agentId);
+        formAssert(session &&
+            session === agentId &&
+            exec.agent?.session.header.origin !== "subagent", "ACCESS_DENIED", "Only the main agent of an admitted QA chat can request a form. Ask the main agent to collect the input.");
+        const service = this.service();
+        service.enabled();
+        formAssert(Date.now() - (this.clients.get(session) ?? 0) < 30000, "INTERACTION_UNAVAILABLE", "Open this chat in the QA interface before requesting a form.");
+        const args = parsed.data;
+        formAssert(!this.hasSession(session) && !this.busy(session), "INTERACTION_BUSY", "Finish the current interactive request before opening this form.");
+        if (args.action === "create" && !this.filesAvailable()) {
+            const schema = parseFormSchema(args.form, service.policy());
+            formAssert(schema.steps.every((s) => s.items.every((i) => i.files.requirement === "none")), "INTERACTION_UNAVAILABLE", "This deployment has no authenticated form-file upload and reader pipeline.");
+        }
+        const r = args.action === "create"
+            ? service.create(session, args.request_key, args.form)
+            : service.get(session, args.form_id);
+        formAssert(this.filesAvailable() ||
+            r.schema.steps.every((s) => s.items.every((i) => i.files.requirement === "none")), "INTERACTION_UNAVAILABLE", "This deployment has no authenticated form-file upload and reader pipeline.");
+        service.store.editableOrSubmitted(r);
+        if (r.submission)
+            return r.submission;
+        formAssert(!this.waiters.has(r.id) &&
+            !this.hasSession(session) &&
+            !this.busy(session), "INTERACTION_BUSY", "Finish the current interactive request before opening this form.");
+        return new Promise((resolve, reject) => {
+            const abort = () => finish();
+            const finish = (outcome) => {
+                if (!this.waiters.delete(r.id))
+                    return;
+                exec.signal.removeEventListener("abort", abort);
+                if (outcome === undefined)
+                    reject(exec.signal.aborted
+                        ? exec.signal.reason
+                        : new QaFormError("INTERACTION_CANCELLED", "Form collection stopped. The draft remains available for resume."));
+                else if (!this.allowed(exec))
+                    reject(new QaFormError("ACCESS_DENIED", "Form access is no longer available."));
+                else
+                    resolve(outcome);
+            };
+            this.waiters.set(r.id, { session, call: String(exec.callId), finish });
+            exec.signal.addEventListener("abort", abort, { once: true });
+            if (exec.signal.aborted)
+                abort();
+        });
+    }
+    notify(record, pause = false) {
+        const waiter = this.waiters.get(record.id);
+        if (record.submission)
+            waiter?.finish(record.submission);
+        else if (pause)
+            waiter?.finish({
+                status: "paused",
+                form_id: record.id,
+                reason: "Draft saved. Resume this form; collection is not complete.",
+            });
+    }
+    cancel(session) {
+        for (const w of [...this.waiters.values()])
+            if (w.session === session)
+                w.finish();
+    }
+    cancelAll() {
+        for (const w of [...this.waiters.values()])
+            w.finish();
+    }
+    dispose() {
+        this.closed = true;
+        for (const w of [...this.waiters.values()])
+            w.finish();
+        for (const d of this.disposers.splice(0))
+            d();
+    }
+}
+//# sourceMappingURL=gate.js.map

package/lib/forms/gate.js.map

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

package/lib/forms/schema.js

@@ -0,0 +1,182 @@
+import { z } from "zod";
+import { formAssert, QaFormError } from "./errors.js";
+export const DEFAULT_FORM_POLICY = Object.freeze({
+    enabled: false,
+    maxSteps: 20,
+    maxItemsPerForm: 100,
+    maxOptionsPerItem: 50,
+    maxSchemaBytes: 131072,
+    maxTextLength: 10000,
+    maxTotalAnswerBytes: 32768,
+    maxFilesPerItem: 10,
+    maxFileSizeBytes: 52428800,
+    maxTotalFileBytesPerForm: 262144000,
+    maxConcurrentUploadsPerSession: 2,
+    uploadIntentTtlSeconds: 900,
+    allowedExtensions: Object.freeze([
+        ".pdf",
+        ".docx",
+        ".xlsx",
+        ".csv",
+        ".txt",
+        ".png",
+        ".jpg",
+        ".jpeg",
+    ]),
+});
+const id = z
+    .string()
+    .regex(/^[a-zA-Z][a-zA-Z0-9_-]{0,79}$/u)
+    .refine((v) => !["constructor", "prototype", "__proto__"].includes(v));
+const label = z.string().trim().min(1).max(2000);
+const integer = z.number().int().nonnegative();
+const option = z
+    .object({
+    value: id,
+    label,
+    description: label.optional(),
+    recommended: z.boolean().optional(),
+})
+    .strict();
+const answer = z.discriminatedUnion("type", [
+    z
+        .object({
+        type: z.literal("text"),
+        required: z.boolean(),
+        placeholder: label.optional(),
+        min_length: integer.optional(),
+        max_length: integer.positive().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("textarea"),
+        required: z.boolean(),
+        placeholder: label.optional(),
+        min_length: integer.optional(),
+        max_length: integer.positive().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("single_select"),
+        required: z.boolean(),
+        options: z.array(option).min(1),
+        allow_other: z.boolean().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("multi_select"),
+        required: z.boolean(),
+        options: z.array(option).min(1),
+        allow_other: z.boolean().optional(),
+        min_selected: integer.optional(),
+        max_selected: integer.positive().optional(),
+    })
+        .strict(),
+]);
+const fileFields = {
+    max_count: integer.positive(),
+    accept: z.array(z.string().regex(/^\.[a-z0-9]+$/u)).min(1),
+    max_file_size_bytes: integer.positive(),
+};
+const files = z.discriminatedUnion("requirement", [
+    z.object({ requirement: z.literal("none") }).strict(),
+    z
+        .object({
+        requirement: z.literal("required"),
+        min_count: integer.positive(),
+        ...fileFields,
+    })
+        .strict(),
+    z.object({ requirement: z.literal("optional"), ...fileFields }).strict(),
+]);
+export const formSchemaParser = z
+    .object({
+    schema_version: z.literal(1),
+    title: label,
+    description: label.optional(),
+    submit_label: label.optional(),
+    steps: z
+        .array(z
+        .object({
+        id,
+        title: label,
+        description: label.optional(),
+        items: z
+            .array(z
+            .object({
+            id,
+            title: label,
+            description: label.optional(),
+            answer: answer.optional(),
+            files,
+        })
+            .strict())
+            .min(1),
+    })
+        .strict())
+        .min(1),
+})
+    .strict();
+/** Shared by server and browser. No Node APIs or browser-supplied readiness. */
+export function parseFormSchema(input, policy) {
+    const parsed = formSchemaParser.safeParse(input);
+    if (!parsed.success)
+        throw new QaFormError("INVALID_SCHEMA", "The form schema is invalid; provide explicit requirements and supported fields.");
+    const schema = parsed.data;
+    const check = (ok) => formAssert(ok, "INVALID_SCHEMA", "The form schema exceeds policy or contains conflicting requirements.");
+    check(new TextEncoder().encode(JSON.stringify(schema)).length <=
+        policy.maxSchemaBytes);
+    check(schema.steps.length <= policy.maxSteps);
+    const stepIds = new Set(), itemIds = new Set();
+    for (const step of schema.steps) {
+        check(!stepIds.has(step.id));
+        stepIds.add(step.id);
+        for (const item of step.items) {
+            check(!itemIds.has(item.id));
+            itemIds.add(item.id);
+            check(item.answer !== undefined || item.files.requirement !== "none");
+            const a = item.answer;
+            if (a?.type === "text" || a?.type === "textarea") {
+                check((a.max_length ?? policy.maxTextLength) <= policy.maxTextLength);
+                check((a.min_length ?? 0) <= (a.max_length ?? policy.maxTextLength));
+            }
+            else if (a !== undefined) {
+                check(a.options.length <= policy.maxOptionsPerItem);
+                check(new Set(a.options.map((o) => o.value)).size === a.options.length);
+                if (a.type === "multi_select") {
+                    const maximum = a.max_selected ?? a.options.length + (a.allow_other ? 1 : 0);
+                    check((a.min_selected ?? 0) <= maximum &&
+                        maximum <= a.options.length + (a.allow_other ? 1 : 0));
+                }
+            }
+            const f = item.files;
+            if (f.requirement !== "none") {
+                check(f.max_count <= policy.maxFilesPerItem &&
+                    f.max_file_size_bytes <= policy.maxFileSizeBytes);
+                check(f.accept.every((ext) => policy.allowedExtensions.includes(ext)) &&
+                    new Set(f.accept).size === f.accept.length);
+                if (f.requirement === "required")
+                    check(f.min_count <= f.max_count);
+            }
+        }
+    }
+    check(itemIds.size <= policy.maxItemsPerForm);
+    return schema;
+}
+export function resolveFormPolicy(input = {}) {
+    const policy = { ...DEFAULT_FORM_POLICY, ...input };
+    for (const [key, value] of Object.entries(policy)) {
+        if (key === "enabled" || key === "allowedExtensions")
+            continue;
+        formAssert(typeof value === "number" && Number.isSafeInteger(value) && value > 0, "INVALID_SCHEMA", `forms.${key} must be a positive integer.`);
+    }
+    formAssert(typeof policy.enabled === "boolean" &&
+        Array.isArray(policy.allowedExtensions) &&
+        policy.allowedExtensions.length > 0 &&
+        policy.allowedExtensions.every((ext) => DEFAULT_FORM_POLICY.allowedExtensions.includes(ext)), "INVALID_SCHEMA", "Unsupported form file policy.");
+    return policy;
+}
+//# sourceMappingURL=schema.js.map