@firedrill-tools/unstructured 0.1.4

package/test/flows/partition.mjs

@@ -0,0 +1,225 @@
+// Partition flow: element rules per document type, ids, languages, pages, multi-file requests, CSV output.
+import assert from "node:assert/strict";
+import { HEX32, ID, UUID, fixtures, op, partition, types } from "../lib.mjs";
+
+export async function partitionFlow() {
+  const fx = fixtures();
+  const file = (name) => ({ filename: name, content: fx.get(name).content });
+
+  // 1. Markdown: heading depths, parent chain, lists, table, code, emphasis, links, ids, metadata.
+  const md = (await partition([file("handbook.md")])).json;
+  assert.ok(Array.isArray(md) && md.length > 15, `handbook elements ${md.length}`);
+  const titles = md.filter((e) => e.type === "Title");
+  assert.deepEqual(titles.map((e) => e.metadata.category_depth), [0, 1, 2, 1, 2, 1, 1]);
+  assert.equal(titles[0].text, "Northgate Research Employee Handbook");
+  assert.equal(titles[1].metadata.parent_id, titles[0].element_id, "h2 parent is h1");
+  assert.equal(titles[2].metadata.parent_id, titles[1].element_id, "h3 parent is h2");
+  const remote = md[md.indexOf(titles[2]) + 1];
+  assert.equal(remote.type, "NarrativeText");
+  assert.equal(remote.metadata.parent_id, titles[2].element_id);
+  assert.deepEqual(remote.metadata.link_texts, ["people team"]);
+  assert.deepEqual(remote.metadata.link_urls, ["https://people.northgate-research.test/requests"]);
+  assert.deepEqual(remote.metadata.emphasized_text_contents, ["three"]);
+  assert.deepEqual(remote.metadata.emphasized_text_tags, ["i"]);
+  assert.equal(md.filter((e) => e.type === "ListItem").length, 8);
+  assert.deepEqual(md.filter((e) => e.type === "ListItem").slice(0, 5).map((e) => e.metadata.category_depth), [0, 0, 1, 1, 0]);
+  const table = md.find((e) => e.type === "Table");
+  assert.ok(table.metadata.text_as_html.startsWith("<table><tr><td>Item</td><td>Standard</td>"), table.metadata.text_as_html);
+  assert.equal(table.text.split("\n").length, 4);
+  assert.equal(md.find((e) => e.type === "CodeSnippet").text, "ngctl ticket create --tag equipment --cost-centre 4410");
+  for (const element of md) {
+    assert.match(element.element_id, HEX32);
+    assert.deepEqual(element.metadata.languages, ["eng"]);
+    assert.equal(element.metadata.filename, "handbook.md");
+    assert.equal(element.metadata.filetype, "text/markdown");
+    assert.equal(element.metadata.page_number, 1);
+  }
+  assert.equal(new Set(md.map((e) => e.element_id)).size, md.length, "ids are unique");
+
+  // 2. unique_element_ids -> UUIDs; 3. repeated languages[] parts.
+  const uuids = (await partition([file("handbook.md")], { unique_element_ids: "true" })).json;
+  for (const element of uuids) assert.match(element.element_id, UUID);
+  const deu = (await partition([file("2026-09-08-site-visit.txt")], { languages: ["deu", "fra"] })).json;
+  assert.equal(deu.length, 4);
+  for (const element of deu) assert.deepEqual(element.metadata.languages, ["deu", "fra"]);
+
+  // 4. Plain text with a form feed: page breaks, Address, EmailAddress, ListItem; 5. starting_page_number.
+  const refund = (await partition([file("refund-policy.txt")], { include_page_breaks: "true" })).json;
+  const breakAt = refund.findIndex((e) => e.type === "PageBreak");
+  assert.ok(breakAt > 0, "PageBreak present");
+  assert.ok(refund.slice(0, breakAt).every((e) => e.metadata.page_number === 1));
+  assert.ok(refund.slice(breakAt + 1).every((e) => e.metadata.page_number === 2) && refund.length > breakAt + 2);
+  assert.ok(types(refund).includes("Address") && types(refund).includes("EmailAddress"));
+  assert.equal(refund.find((e) => e.type === "EmailAddress").text, "billing@northgate-research.test");
+  assert.equal(refund.filter((e) => e.type === "ListItem").length, 3);
+  assert.equal(refund[0].type, "Title");
+  const paged = (await partition([file("refund-policy.txt")], { starting_page_number: "7" })).json;
+  assert.equal(paged[0].metadata.page_number, 7);
+  assert.equal(paged[paged.length - 1].metadata.page_number, 8);
+  assert.ok(!types(paged).includes("PageBreak"));
+
+  // 6. CSV: one Table with header + 12 rows, quoted field with a comma and a newline parsed.
+  const csv = (await partition([file("vendors.csv")])).json;
+  assert.equal(csv.length, 1);
+  assert.equal(csv[0].type, "Table");
+  assert.equal(csv[0].text.split("\n").length, 13);
+  assert.equal((csv[0].metadata.text_as_html.match(/<tr>/g) ?? []).length, 13);
+  assert.ok(csv[0].metadata.text_as_html.includes("<td>Preferred, quarterly review</td>"));
+
+  // 7. HTML: script dropped, Header/Footer, headings, list, table, code, links, emphasis.
+  const html = (await partition([file("release-notes.html")])).json;
+  assert.ok(html.every((e) => !e.text.includes("never shown") && !e.text.includes("<script")));
+  assert.equal(html[0].type, "Header");
+  assert.equal(html[html.length - 1].type, "Footer");
+  assert.equal(html[html.length - 1].text, "© 2026 Northgate Research. Confidential.");
+  assert.deepEqual(html.filter((e) => e.type === "Title").map((e) => e.metadata.category_depth), [0, 1, 1, 1]);
+  assert.equal(html.filter((e) => e.type === "ListItem").length, 3);
+  const layers = html.find((e) => Array.isArray(e.metadata.link_urls) && e.metadata.link_urls.includes("https://fieldkit.northgate-research.test/docs/layers"));
+  assert.ok(layers && layers.metadata.link_texts.includes("layer catalogue"));
+  assert.ok(html.find((e) => e.type === "NarrativeText").metadata.emphasized_text_contents.includes("38 percent"));
+  assert.equal(html.find((e) => e.type === "Table").text.split("\n").length, 4);
+  assert.equal(html.find((e) => e.type === "CodeSnippet").text, "ngctl fieldkit migrate --to 4.2\nngctl fieldkit verify");
+
+  // 8. RFC 822: subject as Title, addresses in metadata, folded header, list in body.
+  const eml = (await partition([file("inbound.eml")])).json;
+  assert.equal(eml[0].type, "Title");
+  assert.equal(eml[0].text, "Site visit follow-up: Harbour Street");
+  for (const element of eml) {
+    assert.deepEqual(element.metadata.sent_from, ["Priya Raman <priya.raman@northgate-research.test>"]);
+    assert.equal(element.metadata.sent_to.length, 2);
+    assert.deepEqual(element.metadata.cc_recipient, ["archive@northgate-research.test"]);
+    assert.equal(element.metadata.email_message_id, "<20260908-1715.4a1@mail.northgate-research.test>");
+    assert.equal(element.metadata.filetype, "message/rfc822");
+  }
+  assert.equal(eml.filter((e) => e.type === "ListItem").length, 2);
+
+  // 9. Pre-partitioned JSON passthrough; 10. empty file.
+  const json = (await partition([file("elements.json")])).json;
+  assert.deepEqual(types(json), ["Title", "NarrativeText", "ListItem"]);
+  assert.equal(json[0].element_id, "4f3c2a1b9d8e7f6a5b4c3d2e1f0a9b8c");
+  assert.match(json[2].element_id, HEX32);
+  assert.equal(json[2].metadata.page_number, 2);
+  assert.deepEqual((await partition([file("empty.txt")])).json, []);
+
+  // 11. Two files in one request are concatenated in part order.
+  const both = (await partition([file("vendors.csv"), file("handbook.md")])).json;
+  assert.equal(both.length, csv.length + md.length);
+  assert.equal(both[0].metadata.filename, "vendors.csv");
+  assert.equal(both[1].metadata.filename, "handbook.md");
+
+  // 12. CSV output: fixed header + one row per element, quoted cells.
+  const out = await partition([file("2026-09-08-site-visit.txt")], { output_format: "text/csv" });
+  assert.ok((out.headers.get("content-type") ?? "").startsWith("text/csv"), out.headers.get("content-type"));
+  assert.equal(out.headers.get("unstructured-api-version"), "0.1.0-firedrill");
+  const lines = out.text.split("\r\n").filter((line) => line.length > 0);
+  assert.equal(lines[0], "type,element_id,text,filename,filetype,languages,page_number,parent_id,category_depth,text_as_html,last_modified,link_urls,link_texts,emphasized_text_contents,emphasized_text_tags,is_continuation,orig_elements");
+  assert.equal(lines.length, 1 + deu.length);
+  assert.ok(lines[1].startsWith("Title,"));
+
+  // 13. Canonical operation call returns the same array as the wire route.
+  const canonical = await op("general.partition", { files: [{ filename: "handbook.md", content: fx.get("handbook.md").content }] });
+  assert.deepEqual(canonical, md);
+
+  // 14. Markdown edge shapes that must partition in linear time: a pipe row before a 200,000-space line, an unclosed
+  // image, a heading padded with spaces, and a pre-formatted trailing-space line. Each answers in well under a second.
+  const hostile = [
+    ["a|b\n" + " ".repeat(200000) + "x", ["UncategorizedText"]],
+    ["![a](" + "a".repeat(200000), ["UncategorizedText", "UncategorizedText", "UncategorizedText"]],
+    ["# " + " ".repeat(200000) + "x", ["Title"]],
+    ["1 " + " ".repeat(200000) + "x", ["UncategorizedText", "UncategorizedText", "UncategorizedText"]],
+  ];
+  for (const [content, expected] of hostile) {
+    const started = Date.now();
+    const result = (await partition([{ filename: "edge.md", content }])).json;
+    assert.ok(Date.now() - started < 3000, `hostile markdown took ${Date.now() - started}ms`);
+    assert.deepEqual(types(result), expected, JSON.stringify(types(result)));
+  }
+  const gfm = (await partition([{ filename: "t.md", content: "| a | b |\n| --- | :-: |\n| 1 | 2 |\n\n![alt](img.png \"t\")\n" }])).json;
+  assert.deepEqual(types(gfm), ["Table", "Image"]);
+  assert.equal(gfm[0].metadata.text_as_html, "<table><tr><td>a</td><td>b</td></tr><tr><td>1</td><td>2</td></tr></table>");
+  assert.equal(gfm[1].text, "alt");
+  assert.equal(gfm[1].metadata.image_url, "img.png");
+
+  // 15. HTML shapes that must partition in linear time and keep everything they carry: a 300 KB attribute, a table at
+  // the 10,000-row bound (every row kept), 200 nested divs, 50,000 links in one block (no cap on link metadata), 100,000
+  // unmatched close tags, and a 200 KB Markdown run of "[" (a forward search that is never rescanned).
+  const hostileHtml = [
+    [`<p class="${"a".repeat(300000)}">x</p>`, "h.html", ["UncategorizedText"]],
+    ["<table>" + "<tr><td>a</td><td>b</td></tr>".repeat(10000) + "</table>", "h.html", ["Table"]],
+    ["<div>a".repeat(200), "h.html", Array(200).fill("UncategorizedText")],
+    ["<a href=\"u\">t</a> ".repeat(50000), "h.html", ["UncategorizedText"]],
+    ["<span>".repeat(200) + "t" + "</div>".repeat(100000), "h.html", ["UncategorizedText"]],
+    ["[a".repeat(100000), "h.md", ["UncategorizedText", "UncategorizedText"]],
+  ];
+  const kept = [];
+  for (const [content, filename, expected] of hostileHtml) {
+    const started = Date.now();
+    const result = (await partition([{ filename, content }])).json;
+    assert.ok(Date.now() - started < 3000, `hostile ${filename} took ${Date.now() - started}ms`);
+    assert.deepEqual(types(result), expected, `${filename}: ${JSON.stringify(types(result)).slice(0, 120)}`);
+    kept.push(result);
+  }
+  assert.equal(kept[1][0].text.split("\n").length, 10000, "every table row is kept at the bound");
+  assert.equal(kept[1][0].metadata.text_as_html.split("<tr>").length - 1, 10000);
+  assert.equal(kept[3][0].metadata.link_urls.length, 50000, "link metadata is never cut");
+  assert.equal(kept[3][0].metadata.link_texts.length, 50000);
+
+  // 16. Entity runs: 500,000 `&` without a `;` in HTML text, an HTML attribute and XML text decode in linear time (the `;`
+  // search is bounded to 12 code units), every `&` kept literally; the text splits into 100,000-character elements.
+  const ampersands = "&".repeat(500000);
+  const entityRuns = [
+    [`<p>${ampersands}</p>`, "amp.html", Array(5).fill("UncategorizedText")],
+    [`<p class="${ampersands}">x</p>`, "attr.html", ["UncategorizedText"]],
+    [`<r>${ampersands}</r>`, "amp.xml", Array(5).fill("UncategorizedText")],
+  ];
+  for (const [content, filename, expected] of entityRuns) {
+    const started = Date.now();
+    const result = (await partition([{ filename, content }])).json;
+    assert.ok(Date.now() - started < 3000, `entity run ${filename} took ${Date.now() - started}ms`);
+    assert.deepEqual(types(result), expected, `${filename}: ${JSON.stringify(types(result)).slice(0, 120)}`);
+    if (expected.length === 5) assert.equal(result.reduce((sum, e) => sum + e.text.length, 0), 500000, `${filename}: every & is kept`);
+  }
+  const decoded = (await partition([{ filename: "ent.html", content: "<p>a &amp; b &lt;c&gt; &#65;&#x42; &unknown; &amp</p>" }])).json;
+  assert.equal(decoded[0].text, "a & b <c> AB &unknown; &amp");
+
+  // 17. JSON re-partition returns caller metadata as given (custom keys, scalar arrays, typed keys) — never a silent drop.
+  const given = { custom: "v", tags: [1, "a", null, true], languages: ["eng", "deu"], page_number: 3, note: "n".repeat(10000) };
+  const asGiven = (await partition([{ filename: "given.json", content: JSON.stringify([{ type: "Title", text: "t", metadata: given }]) }])).json;
+  assert.equal(asGiven.length, 1);
+  for (const key of Object.keys(given)) assert.deepEqual(asGiven[0].metadata[key], given[key], `metadata.${key} returned as given`);
+
+  // 18. RFC 2046 multipart e-mail. A mixed-case boundary is matched case-sensitively (CRLF headers, a 5 KB text/plain body kept
+  // whole); a non-text first part is skipped for the following text part; a nested multipart/alternative yields its text part;
+  // a boundary delimiter with no line break after it, a missing close delimiter and a 71-character boundary answer 422 at once.
+  const paragraph = "Quarterly field notes from the harbour survey were filed today.";
+  const body5k = Array.from({ length: 80 }, () => paragraph).join(" ");
+  assert.ok(body5k.length >= 5000, `body is ${body5k.length} characters`);
+  const mixedCase = (await partition([{ filename: "mixed.eml", content: `From: a@example.test\r\nTo: b@example.test\r\nSubject: Survey\r\nContent-Type: Multipart/Mixed;\r\n boundary="----=_Part_123_ABC"\r\n\r\npreamble\r\n------=_Part_123_ABC\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n${body5k}\r\n------=_Part_123_ABC--\r\n` }])).json;
+  assert.deepEqual(types(mixedCase), ["Title", "NarrativeText"]);
+  assert.equal(mixedCase[1].text, body5k, "the whole text part is partitioned");
+  const nonTextFirst = (await partition([{ filename: "attach.eml", content: "From: a@example.test\nSubject: Attachment\nContent-Type: multipart/mixed; boundary=b\n\n--b\nContent-Type: application/octet-stream\n\nAAECAw==\n--b\nContent-Type: text/plain\n\nThe report is attached to this message.\n--b--\n" }])).json;
+  assert.deepEqual(types(nonTextFirst), ["Title", "NarrativeText"]);
+  assert.equal(nonTextFirst[1].text, "The report is attached to this message.");
+  const nestedAlt = (await partition([{ filename: "nested.eml", content: "From: a@example.test\nSubject: Nested\nContent-Type: multipart/mixed; boundary=outer\n\n--outer\nContent-Type: multipart/alternative; boundary=inner\n\n--inner\nContent-Type: text/plain\n\nPlain text version of the message body.\n--inner\nContent-Type: text/html\n\n<p>HTML version</p>\n--inner--\n--outer\nContent-Type: application/pdf\n\nJVBERi0=\n--outer--\n" }])).json;
+  assert.deepEqual(types(nestedAlt), ["Title", "NarrativeText"]);
+  assert.equal(nestedAlt[1].text, "Plain text version of the message body.");
+  const malformed = [
+    ["From: a@b.c\nSubject: s\nContent-Type: multipart/mixed; boundary=b\n\nContent-Type: application/octet-stream\n\n--b", "is not followed by a line break"],
+    ["From: a@b.c\nSubject: s\nContent-Type: multipart/mixed; boundary=b\n\n--b\n\ntext\n", "no closing"],
+    [`From: a@b.c\nSubject: s\nContent-Type: multipart/mixed; boundary=${"b".repeat(71)}\n\n--b\n`, "1-70"],
+  ];
+  for (const [content, fragment] of malformed) {
+    const started = Date.now();
+    const rejected = await partition([{ filename: "bad.eml", content }], {}, { status: 422 });
+    assert.ok(Date.now() - started < 1000, `malformed e-mail took ${Date.now() - started}ms`);
+    assert.ok(JSON.stringify(rejected.json.detail).includes(fragment), rejected.text.slice(0, 300));
+  }
+
+  // 19. A deterministic slice of the hostile-input harness (test/hostile.mjs): 300 cases across every format and the chunker,
+  // each within 250 ms, answering elements or a declared error.
+  const { runHostile } = await import("../hostile.mjs");
+  // Correctness only: no throw, only declared codes, no hang. Wall-clock latency is machine-dependent, so the 250 ms bound
+  // belongs to `node test/hostile.mjs`, not to this determinism check (a slower CI runner exceeded it on correct results).
+  const report = await runHostile({ seed: 20260916, cases: 300, limitMs: Infinity, hangMs: 60000 });
+  assert.deepEqual(report.failures, [], JSON.stringify(report.failures.slice(0, 5)));
+}

package/test/flows/workflows.mjs

@@ -0,0 +1,123 @@
+// Workflow and job flow: listing/sorting/paging, node validation, run, job lifecycle, download, cancel, delete.
+import assert from "node:assert/strict";
+import { ID, api, del, detail, fixtures, get, multipart, partition, post, put } from "../lib.mjs";
+
+const RUNTIME = (files, bytes) => { const s = 10 * files + Math.floor(bytes / 4096); return `PT${Math.floor(s / 60)}M${s % 60}S`; };
+
+export async function workflowsFlow() {
+  const all = (await get("/api/v1/workflows")).json;
+  assert.deepEqual(all.map((w) => w.name), ["policy-ingest", "notes-basic", "legacy-scan"]);
+  assert.deepEqual(all[0].sources, [ID.S1]);
+  assert.deepEqual(all[0].destinations, [ID.D2]);
+  assert.equal(all[0].workflow_nodes.length, 3);
+  assert.deepEqual((await get("/api/v1/workflows?status=inactive")).json.map((w) => w.id), [ID.W3]);
+  assert.deepEqual((await get("/api/v1/workflows?page_size=1&page=2&sort_by=name&sort_direction=desc")).json.map((w) => w.name), ["notes-basic"]);
+  assert.deepEqual((await get(`/api/v1/workflows?source_id=${ID.S2}`)).json.map((w) => w.id), [ID.W2]);
+  assert.deepEqual((await get("/api/v1/workflows?name=legacy-scan")).json.map((w) => w.id), [ID.W3]);
+  assert.deepEqual((await get("/api/v1/workflows?page=4")).json, []);
+  await detail("GET", "/api/v1/workflows?show_only_soft_deleted=true", 422, "not supported by this Tool");
+  await detail("GET", "/api/v1/workflows?page=0", 422, "query.page");
+  await detail("GET", "/api/v1/workflows?page_size=101", 422, "less than or equal to 100");
+  await detail("GET", "/api/v1/workflows?sort_by=colour", 422, "query.sort_by");
+  await detail("GET", `/api/v1/workflows/${ID.W4}`, 404, "Workflow not found");
+
+  const nodes = (partitionSub, chunk) => [{ name: "Partitioner", type: "partition", subtype: partitionSub }, ...(chunk ? [chunk] : [])];
+  await detail("POST", "/api/v1/workflows", 422, "must be the first node", { body: { name: "bad", workflow_type: "custom", workflow_nodes: [{ name: "c", type: "chunk", subtype: "chunk_by_title" }, { name: "p", type: "partition", subtype: "auto" }] } });
+  await detail("POST", "/api/v1/workflows", 422, "at most one chunk node", { body: { name: "bad", workflow_type: "custom", workflow_nodes: [...nodes("auto", { name: "c", type: "chunk", subtype: "chunk_by_title" }), { name: "c2", type: "chunk", subtype: "chunk_by_page" }] } });
+  await detail("POST", "/api/v1/workflows", 422, "by_similarity is not supported", { body: { name: "bad", workflow_type: "custom", workflow_nodes: nodes("auto", { name: "c", type: "chunk", subtype: "chunk_by_similarity" }) } });
+  // The partition node's languages setting is bounded like the partition route's parameter: refused, never cut.
+  await detail("POST", "/api/v1/workflows", 422, "at most 20 items", { body: { name: "bad", workflow_type: "custom", workflow_nodes: [{ name: "p", type: "partition", subtype: "auto", settings: { languages: Array.from({ length: 21 }, (_, i) => `l${i}`) } }] } });
+  await detail("POST", "/api/v1/workflows", 422, "at most 20 characters", { body: { name: "bad", workflow_type: "custom", workflow_nodes: [{ name: "p", type: "partition", subtype: "auto", settings: { languages: "eng,abcdefghijklmnopqrstuvwxyz" } }] } });
+  await detail("POST", "/api/v1/workflows", 422, "body.schedule", { body: { name: "bad", workflow_type: "auto", schedule: "hourly" } });
+  const foreign = await detail("POST", "/api/v1/workflows", 422, "Source connector not found", { body: { name: "bad", workflow_type: "auto", source_id: ID.S4 } });
+  assert.deepEqual(foreign.json.detail[0].loc, ["body", "source_id"]);
+  await detail("POST", "/api/v1/workflows", 422, "template_id is not supported", { body: { name: "bad", workflow_type: "auto", template_id: "t" } });
+  await detail("POST", "/api/v1/workflows", 422, "Field required", { body: { workflow_type: "auto" } });
+  await detail("POST", "/api/v1/workflows", 422, "already exists", { body: { name: "dup", workflow_type: "auto", key: "policy-ingest" } });
+
+  const w5 = (await post("/api/v1/workflows", { name: "notes-chars", workflow_type: "custom", source_id: ID.S2, destination_id: ID.D1, workflow_nodes: nodes("auto", { name: "Chunker", type: "chunk", subtype: "chunk_by_character", settings: { max_characters: 300 } }), key: "notes-chars" })).json;
+  assert.equal(w5.status, "active");
+  assert.equal(w5.workflow_nodes.length, 2);
+  assert.match(w5.workflow_nodes[0].id, /^[0-9a-f-]{36}$/);
+  const auto = (await post("/api/v1/workflows", { name: "auto-flow", workflow_type: "auto", source_id: ID.S1 })).json;
+  assert.deepEqual(auto.workflow_nodes.map((n) => n.subtype), ["auto", "chunk_by_title"]);
+  assert.equal((await get(`/api/v1/workflows/${w5.id}`)).json.name, "notes-chars");
+
+  assert.equal((await put(`/api/v1/workflows/${w5.id}`, { status: "inactive" })).json.status, "inactive");
+  await detail("POST", `/api/v1/workflows/${w5.id}/run`, 422, "Workflow is not active");
+  assert.equal((await put(`/api/v1/workflows/${w5.id}`, { status: "active", schedule: "weekly" })).json.schedule, "weekly");
+  await detail("PUT", `/api/v1/workflows/${w5.id}`, 422, "body.status", { body: { status: "sleeping" } });
+  await detail("PUT", `/api/v1/workflows/${ID.NONE}`, 404, "Workflow not found", { body: { name: "x" } });
+  await detail("POST", `/api/v1/workflows/${ID.W3}/run`, 422, "Workflow is not active");
+  await detail("POST", `/api/v1/workflows/${ID.W4}/run`, 404, "Workflow not found");
+  await detail("POST", `/api/v1/workflows/${w5.id}/run`, 422, "Expected multipart/form-data", { body: { input_files: [] } });
+  const noSource = (await post("/api/v1/workflows", { name: "adhoc", workflow_type: "auto" })).json;
+  await detail("POST", `/api/v1/workflows/${noSource.id}/run`, 422, "body.input_files");
+
+  const job = (await api("POST", `/api/v1/workflows/${w5.id}/run`, { status: 202 })).json;
+  assert.equal(job.status, "SCHEDULED");
+  assert.equal(job.input_file_ids.length, 3);
+  assert.deepEqual(job.output_node_files, []);
+  assert.equal(job.runtime, null);
+  assert.equal((await get(`/api/v1/jobs/${job.id}`)).json.status, "SCHEDULED");
+  const details = (await get(`/api/v1/jobs/${job.id}/details`)).json;
+  assert.equal(details.processing_status, "SCHEDULED");
+  assert.deepEqual(details.node_stats.map((n) => n.ready), [3, 3]);
+  const upload = multipart([{ name: "input_files", filename: "memo.md", value: "# Memo\n\nA short memo body for the runtime upload.", contentType: "text/markdown" }, { name: "input_files", filename: "scan.pdf", value: "%PDF", contentType: "application/pdf" }]);
+  const job2 = (await api("POST", `/api/v1/workflows/${w5.id}/run`, { status: 202, raw: upload.raw, contentType: upload.contentType })).json;
+  assert.equal(job2.input_file_ids.length, 5);
+  assert.deepEqual((await get(`/api/v1/jobs/${job2.id}/failed-files`)).json.failed_files, [{ document: "upload://scan.pdf", error: "application/pdf not currently supported" }]);
+  assert.deepEqual((await get(`/api/v1/jobs/${job.id}/failed-files`)).json.failed_files, []);
+
+  assert.equal((await get(`/api/v1/jobs?workflow_id=${w5.id}`)).json.length, 2);
+  assert.deepEqual((await get("/api/v1/jobs?status=COMPLETED")).json.map((j) => j.id), [ID.J2, ID.J1]);
+  const pages = [];
+  for (let page = 1; page <= 5; page += 1) pages.push((await get(`/api/v1/jobs?page_size=2&page=${page}`)).json);
+  assert.deepEqual(pages.map((p) => p.length), [2, 2, 2, 2, 0]);
+  assert.equal(new Set(pages.flat().map((j) => j.id)).size, 8);
+  await detail("GET", "/api/v1/jobs?page=0", 422, "query.page");
+  await detail("GET", "/api/v1/jobs?status=DONE", 422, "query.status");
+
+  const j1 = (await get(`/api/v1/jobs/${ID.J1}`)).json;
+  assert.equal(j1.status, "COMPLETED");
+  assert.equal(j1.runtime, RUNTIME(7, 1446 + 965 + 754 + 1544 + 826 + 0 + 56014));
+  assert.equal(j1.output_node_files.length, 7);
+  assert.ok(j1.output_node_files.every((f) => f.node_id === ID.W1_EMBED_NODE && f.node_type === "embed"));
+  const fileId = `${ID.S1}:handbook-md`;
+  const download = (await get(`/api/v1/jobs/${ID.J2}/download?file_id=${encodeURIComponent(fileId)}&node_id=${ID.W1_EMBED_NODE}`)).json;
+  const direct = (await partition([{ filename: "handbook.md", content: fixtures().get("handbook.md").content }], { chunking_strategy: "by_title", max_characters: "800", new_after_n_chars: "800", combine_under_n_chars: "200", include_orig_elements: "true" })).json;
+  assert.deepEqual(download.map((c) => [c.type, c.text]), direct.map((c) => [c.type, c.text]));
+  await detail("GET", `/api/v1/jobs/${ID.J2}/download?file_id=${encodeURIComponent(fileId)}&node_id=${ID.NONE}`, 404, "Job output file not found");
+  await detail("GET", `/api/v1/jobs/${ID.J2}/download?node_id=${ID.W1_EMBED_NODE}`, 422, "query.file_id");
+  await detail("GET", `/api/v1/jobs/${ID.J6}/download?file_id=${encodeURIComponent(fileId)}&node_id=${ID.W1_EMBED_NODE}`, 422, "not available yet");
+  await detail("GET", `/api/v1/jobs/${ID.J2}/download?file_id=${encodeURIComponent(`${ID.S1}:ledger-txt`)}&node_id=${ID.W1_EMBED_NODE}`, 413, "exceeds the 921600 byte response limit");
+  await detail("GET", `/api/v1/jobs/${ID.NONE}/download?file_id=x&node_id=y`, 404, "Job not found");
+
+  const j4 = (await get(`/api/v1/jobs/${ID.J4}/details`)).json;
+  assert.equal(j4.processing_status, "FAILED");
+  assert.deepEqual(j4.node_stats.map((n) => n.failure), [2]);
+  assert.equal((await get(`/api/v1/jobs/${ID.J4}`)).json.reason, "All files failed");
+  const failed = (await get(`/api/v1/jobs/${ID.J4}/failed-files`)).json.failed_files;
+  assert.deepEqual(failed.map((f) => f.document), ["az://legacy-scans/scan-001.pdf", "az://legacy-scans/photo.png"]);
+  assert.equal(failed[0].error, "File is encrypted. Please decrypt it with password.");
+  assert.equal((await get(`/api/v1/jobs/${ID.J3}/details`)).json.processing_status, "STOPPED");
+  assert.equal((await get(`/api/v1/jobs/${ID.J3}`)).json.reason, "Cancelled by user");
+  assert.equal((await get(`/api/v1/jobs/${ID.J5}`)).json.status, "IN_PROGRESS");
+  assert.deepEqual((await get(`/api/v1/jobs/${ID.J5}/details`)).json.node_stats.map((n) => n.in_progress), [3, 3]);
+  await detail("GET", `/api/v1/jobs/${ID.NONE}`, 404, "Job not found");
+  await detail("GET", `/api/v1/jobs/${ID.NONE}/details`, 404, "Job not found");
+  await detail("GET", `/api/v1/jobs/${ID.NONE}/failed-files`, 404, "Job not found");
+
+  const cancelled = (await post(`/api/v1/jobs/${ID.J5}/cancel`, undefined)).json;
+  assert.equal(cancelled.status, "STOPPED");
+  assert.equal((await get(`/api/v1/jobs/${ID.J5}`)).json.status, "STOPPED");
+  assert.equal((await get(`/api/v1/jobs/${ID.J5}`)).json.stop_requested, true);
+  await detail("POST", `/api/v1/jobs/${ID.J1}/cancel`, 422, "already finished");
+  await detail("POST", `/api/v1/jobs/${ID.NONE}/cancel`, 404, "Job not found");
+
+  await detail("DELETE", `/api/v1/workflows/${ID.W1}`, 422, "running job");
+  await detail("DELETE", `/api/v1/workflows/${w5.id}`, 422, "running job");
+  await detail("DELETE", `/api/v1/workflows/${ID.NONE}`, 404, "Workflow not found");
+  assert.deepEqual((await del(`/api/v1/workflows/${noSource.id}`)).json, {});
+  await detail("GET", `/api/v1/workflows/${noSource.id}`, 404, "Workflow not found");
+}

package/test/hostile.mjs

@@ -0,0 +1,155 @@
+// Hostile-input harness for the partitioners and the chunker. Node built-ins only.
+//   node test/hostile.mjs [seed=1] [cases=20000]
+// Cases run in a worker thread; the main thread watches a shared case counter and terminates the worker when one case runs
+// longer than the hang bound, so a non-terminating partitioner is reported instead of hanging the harness. A case fails when
+// it takes more than LIMIT_MS (partition plus JSON encoding of the result, as the route does), throws anything, or answers a
+// code that is not one of the package's declared error codes. Exit status 1 on any failure.
+// The latency bound is machine-dependent, so only the command line applies it. Packaged conformance calls runHostile with
+// `limitMs: Infinity` and a long hang bound: a determinism check must not pass on a fast machine and fail on a slow one,
+// while a case that throws, answers an undeclared code or never terminates still fails everywhere.
+// Every MULTIPART_EVERY-th case also decodes a hostile multipart/form-data request envelope through both route decoders
+// (partition and workflow run) and checks that a decoded `languages` list is either accepted whole or refused, never cut.
+import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath } from "node:url";
+import { makeCase, makeMultipartCase } from "./hostile-gen.mjs";
+
+export const LIMIT_MS = 250;
+export const HANG_MS = 5000;
+const RSS_LIMIT = 2 * 1024 * 1024 * 1024;
+const MULTIPART_EVERY = 4;
+const DECLARED = new Set(["INVALID_REQUEST", "UNSUPPORTED_FILE_TYPE", "RESPONSE_TOO_LARGE", "INVALID_FILE", "VALIDATION_ERROR"]);
+
+async function workerMain() {
+  const { seed, cases, from, shared, limitMs = LIMIT_MS } = workerData;
+  const progress = new Int32Array(shared);
+  const { partitionFile } = await import(new URL("../firedrill/tools/unstructured/lib/partition/index.mjs", import.meta.url));
+  const { decodePartition, decodeRun } = await import(new URL("../firedrill/tools/unstructured/lib/wire-multipart.mjs", import.meta.url));
+  const { parseLanguages, MAX_LANGUAGES, MAX_LANGUAGE_LENGTH } = await import(new URL("../firedrill/tools/unstructured/lib/validate.mjs", import.meta.url));
+  const { RESERVED } = await import(new URL("../firedrill/tools/unstructured/lib/wire.mjs", import.meta.url));
+  const multipartOutcome = (m) => {
+    const request = { headers: { "content-type": [m.contentType] }, path: { workflow_id: "w" }, body: { kind: "text", value: m.body } };
+    const args = decodePartition(request).arguments;
+    decodeRun(request);
+    if (Object.hasOwn(args, RESERVED)) return /^(400|422):/.test(args[RESERVED]) ? "refused" : `undeclared ${args[RESERVED].slice(0, 60)}`;
+    if (args.languages === undefined) return "ok";
+    const issues = { items: [], add(loc, message) { this.items.push(`${loc}: ${message}`); } };
+    const list = parseLanguages(args.languages, "body.languages", issues);
+    const flat = Array.isArray(args.languages) ? args.languages : String(args.languages).split(",").map((x) => x.trim()).filter((x) => x.length > 0);
+    const fits = flat.length <= MAX_LANGUAGES && flat.every((x) => typeof x === "string" && x.length <= MAX_LANGUAGE_LENGTH);
+    if (fits) return list !== null && list.length === flat.length && list.every((x, i) => x === flat[i]) ? "ok" : "undeclared languages changed";
+    return list === null && issues.items.length > 0 ? "VALIDATION_ERROR" : "undeclared languages cut";
+  };
+  const formats = new Map();
+  const failures = [];
+  let peakRss = 0;
+  // Warm the partitioners once so JIT compilation is not charged to the first measured case of each format.
+  for (let i = 0; i < 18; i += 1) {
+    const c = makeCase(seed + 7919, i);
+    partitionFile({ filename: c.filename, content: c.content.slice(0, 2048) }, c.options, null);
+  }
+  for (let index = from; index < cases; index += 1) {
+    Atomics.store(progress, 0, index);
+    const c = makeCase(seed, index);
+    const started = performance.now();
+    let outcome;
+    try {
+      const result = partitionFile({ filename: c.filename, content: c.content, bad_transfer: c.badTransfer }, c.options, null);
+      if (result.ok) {
+        JSON.stringify(result.elements);
+        outcome = "ok";
+      } else outcome = DECLARED.has(result.code) && typeof result.message === "string" ? result.code : `undeclared ${result.code}`;
+    } catch (error) {
+      outcome = `threw ${String(error?.stack ?? error).slice(0, 300)}`;
+    }
+    const ms = performance.now() - started;
+    const key = c.options.chunk === null ? c.format : `${c.format}+chunk`;
+    const stat = formats.get(key) ?? { cases: 0, worst: 0, worstCase: -1, totalMs: 0, outcomes: {} };
+    stat.cases += 1;
+    stat.totalMs += ms;
+    stat.outcomes[outcome.split(" ")[0]] = (stat.outcomes[outcome.split(" ")[0]] ?? 0) + 1;
+    if (ms > stat.worst) Object.assign(stat, { worst: ms, worstCase: index, worstShape: c.shape, worstSize: c.content.length });
+    formats.set(key, stat);
+    if (ms > limitMs || outcome.startsWith("threw") || outcome.startsWith("undeclared")) {
+      failures.push({ index, format: key, shape: c.shape, size: c.content.length, ms: Math.round(ms), outcome });
+    }
+    if (index % MULTIPART_EVERY === MULTIPART_EVERY - 1) {
+      const m = makeMultipartCase(seed, index);
+      const mStarted = performance.now();
+      let mOutcome;
+      try {
+        mOutcome = multipartOutcome(m);
+      } catch (error) {
+        mOutcome = `threw ${String(error?.stack ?? error).slice(0, 300)}`;
+      }
+      const mMs = performance.now() - mStarted;
+      const mStat = formats.get("multipart") ?? { cases: 0, worst: 0, worstCase: -1, totalMs: 0, outcomes: {} };
+      mStat.cases += 1;
+      mStat.totalMs += mMs;
+      mStat.outcomes[mOutcome.split(" ")[0]] = (mStat.outcomes[mOutcome.split(" ")[0]] ?? 0) + 1;
+      if (mMs > mStat.worst) Object.assign(mStat, { worst: mMs, worstCase: index, worstShape: m.shape, worstSize: m.body.length });
+      formats.set("multipart", mStat);
+      if (mMs > limitMs || mOutcome.startsWith("threw") || mOutcome.startsWith("undeclared")) failures.push({ index, format: "multipart", shape: m.shape, size: m.body.length, ms: Math.round(mMs), outcome: mOutcome });
+    }
+    if (index % 250 === 0) {
+      const rss = process.memoryUsage().rss;
+      peakRss = Math.max(peakRss, rss);
+      if (rss > RSS_LIMIT) {
+        failures.push({ index, format: key, shape: c.shape, size: c.content.length, ms: Math.round(ms), outcome: `rss ${rss} bytes over ${RSS_LIMIT}` });
+        break;
+      }
+    }
+  }
+  Atomics.store(progress, 0, -1);
+  parentPort.postMessage({ formats: Object.fromEntries(formats), failures, peakRss });
+}
+
+/**
+ * Runs `cases` hostile cases of `seed` and resolves { cases, formats, failures, peakRss, elapsedMs }. A hung case is reported
+ * as a failure (the worker is terminated) rather than blocking the caller.
+ */
+export function runHostile({ seed = 1, cases = 20000, limitMs = LIMIT_MS, hangMs = HANG_MS } = {}) {
+  const shared = new SharedArrayBuffer(4);
+  const progress = new Int32Array(shared);
+  const started = Date.now();
+  return new Promise((resolve) => {
+    const worker = new Worker(fileURLToPath(import.meta.url), { workerData: { seed, cases, from: 0, shared, limitMs }, resourceLimits: { maxOldGenerationSizeMb: 4096 } });
+    let last = -2;
+    let since = Date.now();
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearInterval(timer);
+      resolve({ cases, elapsedMs: Date.now() - started, ...value });
+    };
+    const timer = setInterval(() => {
+      const current = Atomics.load(progress, 0);
+      if (current !== last) {
+        last = current;
+        since = Date.now();
+      } else if (current >= 0 && Date.now() - since > hangMs) {
+        const c = makeCase(seed, current);
+        void worker.terminate();
+        finish({ formats: {}, peakRss: 0, failures: [{ index: current, format: c.format, shape: c.shape, size: c.content.length, ms: Date.now() - since, outcome: "hang (worker terminated)" }] });
+      }
+    }, 100);
+    worker.on("message", (message) => finish(message));
+    worker.on("error", (error) => finish({ formats: {}, peakRss: 0, failures: [{ index: Atomics.load(progress, 0), outcome: `worker error ${String(error?.stack ?? error).slice(0, 300)}` }] }));
+    worker.on("exit", (code) => finish({ formats: {}, peakRss: 0, failures: [{ index: Atomics.load(progress, 0), outcome: `worker exited ${code} without a result` }] }));
+  });
+}
+
+if (!isMainThread && workerData?.shared !== undefined) await workerMain();
+else if (isMainThread && process.argv[1] === fileURLToPath(import.meta.url)) {
+  const seed = Number.parseInt(process.argv[2] ?? "1", 10);
+  const cases = Number.parseInt(process.argv[3] ?? "20000", 10);
+  const report = await runHostile({ seed, cases });
+  const rows = Object.entries(report.formats).sort(([a], [b]) => a.localeCompare(b));
+  for (const [format, stat] of rows) {
+    console.log(`${format.padEnd(15)} cases=${String(stat.cases).padStart(5)} worst=${stat.worst.toFixed(1)}ms (case ${stat.worstCase}, ${stat.worstShape}, ${stat.worstSize} chars) mean=${(stat.totalMs / stat.cases).toFixed(2)}ms ${JSON.stringify(stat.outcomes)}`);
+  }
+  console.log(`seed=${seed} cases=${cases} elapsed=${report.elapsedMs}ms peakRss=${Math.round(report.peakRss / 1048576)}MiB failures=${report.failures.length}`);
+  for (const failure of report.failures.slice(0, 50)) console.log(`FAIL ${JSON.stringify(failure)}`);
+  process.exitCode = report.failures.length > 0 ? 1 : 0;
+}

package/test/lib.mjs

@@ -0,0 +1,113 @@
+// Shared transport helpers, starter ids and fixture access for the conformance flows. Node built-ins only.
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+export const HTTP = process.env.FIREDRILL_HTTP_URL;
+export const TOKEN = process.env.FIREDRILL_HTTP_TOKEN;
+assert.ok(HTTP && TOKEN, "the http binding is required");
+
+export const ID = {
+  S1: "7c1a9e2f-3b4d-4c5e-8f60-a1b2c3d4e501", S2: "7c1a9e2f-3b4d-4c5e-8f60-a1b2c3d4e502", S3: "7c1a9e2f-3b4d-4c5e-8f60-a1b2c3d4e503", S4: "7c1a9e2f-3b4d-4c5e-8f60-a1b2c3d4e504",
+  D1: "9d2b0f3a-4c5e-4d6f-9a71-b2c3d4e5f601", D2: "9d2b0f3a-4c5e-4d6f-9a71-b2c3d4e5f602", D3: "9d2b0f3a-4c5e-4d6f-9a71-b2c3d4e5f603",
+  W1: "b3c4d5e6-5f60-4718-8a92-c3d4e5f60701", W2: "b3c4d5e6-5f60-4718-8a92-c3d4e5f60702", W3: "b3c4d5e6-5f60-4718-8a92-c3d4e5f60703", W4: "b3c4d5e6-5f60-4718-8a92-c3d4e5f60704",
+  J1: "e5f60718-7a92-4b3c-9d4e-f60718293a01", J2: "e5f60718-7a92-4b3c-9d4e-f60718293a02", J3: "e5f60718-7a92-4b3c-9d4e-f60718293a03",
+  J4: "e5f60718-7a92-4b3c-9d4e-f60718293a04", J5: "e5f60718-7a92-4b3c-9d4e-f60718293a05", J6: "e5f60718-7a92-4b3c-9d4e-f60718293a06",
+  W1_EMBED_NODE: "f1a2b3c4-0001-4a01-8000-000000000003", NONE: "00000000-0000-4000-8000-000000000000",
+};
+export const NOW = "2026-09-16T09:00:00.000Z";
+export const ALL_OPERATIONS = [
+  "general.partition", "sources.list", "sources.create", "sources.get", "sources.update", "sources.delete", "sources.check_connection", "sources.get_connection_check",
+  "destinations.list", "destinations.create", "destinations.get", "destinations.update", "destinations.delete",
+  "workflows.list", "workflows.create", "workflows.get", "workflows.update", "workflows.delete", "workflows.run",
+  "jobs.list", "jobs.get", "jobs.cancel", "jobs.get_details", "jobs.get_failed_files", "jobs.download_output",
+];
+
+/** Seeded source files by filename (content computed from the package's own starter.json, never pasted). */
+export function fixtures() {
+  const starter = JSON.parse(readFileSync("starter.json", "utf8"));
+  const out = new Map();
+  for (const entry of starter.state) if (entry.namespace === "source-files") out.set(entry.value.filename, entry.value);
+  return out;
+}
+
+/** Provider-shaped request with the unstructured-api-key header; asserts the status and returns the parsed body. */
+export async function api(method, path, { body, raw, contentType, status = 200, headers = {}, token = TOKEN } = {}) {
+  const hasBody = body !== undefined || raw !== undefined;
+  const response = await fetch(`${HTTP}${path}`, {
+    method,
+    headers: { "unstructured-api-key": token, ...(hasBody ? { "content-type": contentType ?? "application/json" } : {}), ...headers },
+    ...(hasBody ? { body: raw ?? JSON.stringify(body) } : {}),
+  });
+  const text = await response.text();
+  let json;
+  try {
+    json = text.length > 0 ? JSON.parse(text) : undefined;
+  } catch {
+    json = undefined;
+  }
+  assert.equal(response.status, status, `${method} ${path} ${body === undefined ? "" : JSON.stringify(body).slice(0, 160)} -> ${response.status} ${text.slice(0, 400)}`);
+  return { json, text, headers: response.headers, status: response.status };
+}
+export const get = (path, options) => api("GET", path, options);
+export const post = (path, body, options) => api("POST", path, { ...options, body });
+export const put = (path, body, options) => api("PUT", path, { ...options, body });
+export const del = (path, options) => api("DELETE", path, options);
+
+/** Expects the FastAPI `{ detail }` envelope; `fragment` must appear in the message (string) or first msg (array). */
+export async function detail(method, path, status, fragment, options = {}) {
+  const result = await api(method, path, { ...options, status });
+  assert.ok(result.json && typeof result.json === "object" && Object.hasOwn(result.json, "detail"), `${method} ${path}: no detail envelope: ${result.text.slice(0, 300)}`);
+  const d = result.json.detail;
+  if (typeof d === "string") {
+    if (fragment) assert.ok(d.includes(fragment), `${method} ${path}: expected ${JSON.stringify(fragment)} in ${d.slice(0, 300)}`);
+  } else {
+    assert.ok(Array.isArray(d) && d.length > 0 && Array.isArray(d[0].loc) && typeof d[0].msg === "string" && typeof d[0].type === "string", `${method} ${path}: malformed detail array ${result.text.slice(0, 300)}`);
+    if (fragment) assert.ok(d.some((item) => item.msg.includes(fragment) || item.loc.join(".").includes(fragment)), `${method} ${path}: expected ${JSON.stringify(fragment)} in ${JSON.stringify(d).slice(0, 400)}`);
+  }
+  return result;
+}
+
+/** Canonical operation endpoint; `expected` is "ok", "denied", "invalid" or a Tool error code. */
+export async function op(operationId, args, expected = "ok", token = TOKEN) {
+  const response = await fetch(`${HTTP}/v1/operations/unstructured/${operationId}`, { method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify({ arguments: args }) });
+  const json = await response.json();
+  assert.ok(json.outcome, `canonical ${operationId}: ${JSON.stringify(json).slice(0, 300)}`);
+  if (expected === "ok") {
+    assert.equal(json.outcome.status, "ok", `${operationId} ${JSON.stringify(args).slice(0, 200)}: ${JSON.stringify(json.outcome).slice(0, 400)}`);
+    return json.outcome.value;
+  }
+  if (expected === "denied" || expected === "invalid") {
+    assert.equal(json.outcome.status, expected, `${operationId}: ${JSON.stringify(json.outcome).slice(0, 400)}`);
+    return json.outcome;
+  }
+  assert.equal(json.outcome.status, "tool_error", `${operationId}: ${JSON.stringify(json.outcome).slice(0, 400)}`);
+  assert.equal(json.outcome.error.code, `tool.${expected}`, `${operationId}: ${JSON.stringify(json.outcome.error)}`);
+  return json.outcome.error;
+}
+
+/** Hand-built multipart/form-data body. parts: [{ name, value, filename?, contentType?, headers? }]. */
+export function multipart(parts, boundary = "FiredrillBoundary7d2c") {
+  let body = "";
+  for (const part of parts) {
+    body += `--${boundary}\r\nContent-Disposition: form-data; name="${part.name}"${part.filename !== undefined ? `; filename="${part.filename}"` : ""}\r\n`;
+    if (part.contentType) body += `Content-Type: ${part.contentType}\r\n`;
+    for (const [name, value] of Object.entries(part.headers ?? {})) body += `${name}: ${value}\r\n`;
+    body += `\r\n${part.value}\r\n`;
+  }
+  return { raw: `${body}--${boundary}--\r\n`, contentType: `multipart/form-data; boundary=${boundary}` };
+}
+
+/** POST /general/v0/general with files [{ filename, content, contentType? }] and scalar/array fields. */
+export async function partition(files, fields = {}, options = {}) {
+  const parts = files.map((file) => ({ name: "files", filename: file.filename, value: file.content, contentType: file.contentType, headers: file.headers }));
+  for (const [name, value] of Object.entries(fields)) {
+    if (Array.isArray(value)) for (const item of value) parts.push({ name: `${name}[]`, value: item });
+    else parts.push({ name, value: String(value) });
+  }
+  const { raw, contentType } = multipart(parts);
+  return api("POST", "/general/v0/general", { raw, contentType, ...options });
+}
+
+export const HEX32 = /^[0-9a-f]{32}$/;
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+export const types = (elements) => elements.map((element) => element.type);