@copilotkit/aimock 1.42.1 → 1.44.0

package/dist/fine-tuning.cjs

@@ -0,0 +1,1033 @@
+const require_helpers = require('./helpers.cjs');
+const require_chaos = require('./chaos.cjs');
+
+//#region src/fine-tuning.ts
+/**
+* The statuses a job never leaves. Single source of truth: both `advance()`
+* (which refuses to move a terminal job) and the cancel handler (which rejects
+* a terminal job) read this set, so the two cannot drift apart again.
+*/
+const TERMINAL_STATUSES = new Set([
+	"succeeded",
+	"cancelled",
+	"failed"
+]);
+function isTerminal(status) {
+	return TERMINAL_STATUSES.has(status);
+}
+/** Stable stand-in for the owning org; the vendor requires the field, not a value. */
+const ORGANIZATION_ID = "org-aimock";
+const jobs = /* @__PURE__ */ new Map();
+const polls = /* @__PURE__ */ new Map();
+/**
+* The append-only event log per job id, kept beside the job rather than on it
+* so it never leaks into the `fine_tuning.job` payload. `appendEvent` is the
+* only writer of entries, and only by pushing, so an event's index — and
+* therefore its id — is fixed the moment it is recorded. The one other writer
+* is `clearFineTuningStore`, which empties the whole map: a reset drops every
+* log wholesale and never renumbers a surviving one.
+*/
+const eventLogs = /* @__PURE__ */ new Map();
+/**
+* The last second this module stamped, which is what `stamp()` reads and
+* writes. Module-wide rather than per job: a per-job clamp says nothing about
+* two different jobs, and ordering ACROSS jobs is what the list endpoint's
+* newest-first page rests on.
+*/
+let lastStamp = 0;
+/**
+* The one clock the whole surface stamps from.
+*
+* The invariant: every timestamp this module ever exposes - every job's
+* `created_at`, every event's `created_at`, and every `finished_at` - is
+* non-decreasing in the order the module produced it, whichever way the wall
+* clock moves between two stamps, and across all jobs rather than within one.
+* The per-job reading is a consequence: a job's own stamps are a subsequence
+* of the module's, so they are non-decreasing too.
+*
+* Wall clock is the source, so a forward-running clock shows through
+* unchanged; a backwards step (NTP correction, a resumed VM, a test driving
+* `Date.now`) is absorbed by holding the previous value rather than emitting a
+* history that reads out of order. That makes this the only place a
+* fine-tuning timestamp may come from - a second clamp somewhere downstream is
+* exactly what used to be able to undo this one.
+*/
+function stamp() {
+	lastStamp = Math.max(Math.floor(Date.now() / 1e3), lastStamp);
+	return lastStamp;
+}
+/**
+* The `suffix` the create body asked for, per job id. Kept beside the job
+* because `suffix` is a member of `CreateFineTuningJobRequest` and NOT of
+* `fine_tuning.job`: storing it on the job would put a field on the wire that
+* the vendor never sends. It is read once, when the job succeeds and takes its
+* `fine_tuned_model` name.
+*/
+const suffixes = /* @__PURE__ */ new Map();
+function clearFineTuningStore() {
+	jobs.clear();
+	polls.clear();
+	eventLogs.clear();
+	lastStamp = 0;
+	suffixes.clear();
+}
+/**
+* Journal one fine-tuning request.
+*
+* `body` is the request body the handler actually parsed (create), and is null
+* in three cases: the bodyless GET/cancel routes, a create whose body never
+* parsed into a JSON object, and any request the chaos gate faulted — `chaosHit`
+* journals through `applyChaosAsync` with `body: null` because it rolls before
+* the body is read at all. Recording it otherwise is what makes "inspect the
+* request you sent" work against this surface: every create that got as far as
+* a parsed JSON object carries it, every rejection included, because those are
+* exactly the 400s whose offending payload a caller needs to read back.
+*
+* `path` is the raw request URL, query string INCLUDED. That is not cosmetic:
+* `entry.path` is the only place an untagged-by-header `?testId=` survives into
+* the journal, and `journalEntryTestId` (server.ts) parses it back out of
+* `entry.path` to serve `GET /__aimock/journal?testId=…`. Stripping the query
+* here — as `fal.ts` does with its `pathname` — silently drops every
+* query-tagged fine-tuning request out of its own test's slice. It also matches
+* the repo majority (images, responses, messages, moderation, embeddings,
+* rerank, cohere, gemini, search and vector all journal `req.url`). A caller
+* that wants route-level grouping should match on `service` or on a prefix,
+* not on string equality against a bare path.
+*
+* One route reaches a response without reaching this function: a
+* `POST /v1/fine_tuning/jobs` whose body read throws (over the size cap, or a
+* socket error) is caught in `server.ts` and answered 500 before
+* `handleFineTuningCreate` runs, so it is never journaled. That is deliberate
+* consistency, not an oversight — every sibling route's body-read catch in
+* `server.ts` (responses, messages, cohere, moderation, embeddings, rerank,
+* the video surfaces) writes the same unjournaled 500. Journaling it here alone
+* would make fine-tuning the one surface whose journal disagrees with the rest.
+*
+* `source: "internal"` marks the entry as served by aimock's own synthetic job
+* logic rather than a fixture or a proxy, which is the same value this file's
+* own chaos gate passes for a faulted request. It is a rare value elsewhere:
+* `grep -rn 'source: "internal"' src/*.ts` finds it on exactly two other
+* writers, `images.ts`'s removed-endpoint 404 and `openrouter-video.ts`'s
+* models listing synthesized after a failed proxy attempt — every other
+* service's synthesized journal writes `source: "proxy"`. Fine-tuning is the
+* one surface where every entry carries it, success and error alike, because
+* no fixture or proxy ever serves this store.
+*/
+function journalFt(journal, method, path, headers, status, body = null) {
+	journal.add({
+		method,
+		path,
+		headers,
+		body,
+		service: "fine-tuning",
+		response: {
+			status,
+			fixture: null,
+			source: "internal"
+		}
+	});
+}
+function writeJson(res, status, payload, setCorsHeaders) {
+	setCorsHeaders(res);
+	res.writeHead(status, { "Content-Type": "application/json" });
+	res.end(JSON.stringify(payload));
+}
+function invalid(message) {
+	return { error: {
+		message,
+		type: "invalid_request_error"
+	} };
+}
+/**
+* Roll the chaos dice for one fine-tuning request. Returns true when a fault
+* fired and the response is already written, so the caller returns early.
+*
+* CORS headers go on BEFORE the roll, because a fault writes the response
+* itself and never reaches `writeJson` (the only other place this file sets
+* them). Without this a browser client under chaos reads an opaque CORS
+* failure instead of the 429/500/malformed body the chaos config asked for —
+* exactly the fault it is trying to exercise, hidden. `setCorsHeaders` uses
+* `res.setHeader`, so the later `writeHead` on the non-fault path merges with
+* it rather than replacing it, and setting them twice is a no-op.
+* `src/images.ts` orders it the same way (CORS at the top of the handler,
+* chaos gate after).
+*/
+async function chaosHit(req, journal, defaults, method, path, res, setCorsHeaders) {
+	setCorsHeaders(res);
+	return await require_chaos.applyChaosAsync(res, null, defaults.chaos, req.headers, req.url, journal, {
+		method,
+		path,
+		headers: require_helpers.flattenHeaders(req.headers),
+		body: null,
+		service: "fine-tuning"
+	}, "internal", defaults.registry, defaults.logger);
+}
+/**
+* Record one thing that just happened to `job`. Call sites append only at the
+* moment of the transition they describe, so the log is the job's real
+* history rather than a reconstruction from its current status.
+*
+* `created_at` comes from `stamp()`, so a log that reads out of order is not
+* representable. Returns the second it stamped, which is what a terminal
+* transition assigns to `finished_at` so that nothing can follow the finish.
+*/
+function appendEvent(job, message) {
+	const log = eventLogs.get(job.id) ?? [];
+	const createdAt = stamp();
+	log.push({
+		id: `ftevent-${job.id.replace(/^ftjob-/, "")}-${log.length}`,
+		object: "fine_tuning.job.event",
+		created_at: createdAt,
+		level: "info",
+		message,
+		type: "message"
+	});
+	eventLogs.set(job.id, log);
+	return createdAt;
+}
+function advance(job) {
+	if (isTerminal(job.status)) return job;
+	const n = (polls.get(job.id) ?? 0) + 1;
+	polls.set(job.id, n);
+	if (n === 1) {
+		job.status = "queued";
+		appendEvent(job, "Training file validated, job queued");
+	} else if (n === 2) {
+		job.status = "running";
+		appendEvent(job, "Training started");
+	} else {
+		job.status = "succeeded";
+		const suffix = suffixes.get(job.id);
+		const tail = suffix === void 0 ? "" : `${suffix}:`;
+		job.fine_tuned_model = `ft:${job.model}:aimock:${tail}${job.id.slice(-6)}`;
+		job.result_files = [`file-${job.id.replace(/^ftjob-/, "")}`];
+		job.trained_tokens = job.seed % 1e5;
+		job.finished_at = appendEvent(job, `Training complete, model ${job.fine_tuned_model}`);
+	}
+	return job;
+}
+function eventsFor(job) {
+	return [...eventLogs.get(job.id) ?? []];
+}
+/** `limit` default for both fine-tuning list endpoints (openai-openapi v2.3.0). */
+const DEFAULT_PAGE_LIMIT = 20;
+/** Upper bound we enforce on `limit`. Ours, not the vendor's — see `paginate`. */
+const MAX_PAGE_LIMIT = 100;
+/**
+* The query parameters of a request target.
+*
+* The query is everything after the FIRST `?`, per RFC 3986 section 3.4
+* ("The query component ... is terminated by a number sign (#) character or by
+* the end of the URI") read together with RFC 9112 section 3.2: a request
+* target is an origin-form `absolute-path [ "?" query ]` and carries no
+* fragment component at all. Both halves of that matter here:
+*
+*   - `split("?")[1]` truncates at a SECOND `?`, which is a legal literal
+*     inside a query, so `?a=1?b=2&limit=5` used to lose `limit` entirely.
+*     Slicing from the first `?` keeps it.
+*   - `new URL(target, base).searchParams` — what the router and the other
+*     query-reading mocks use — truncates at a `#` instead, because `URL`
+*     implements the fragment rule that a request target does not have. A
+*     caller that sends `?after=abc#def` on the wire means the cursor
+*     `abc#def`; reading it as `abc` is the same silent truncation one `?`
+*     along, and it turns a bad cursor into a plausible-looking one. An origin
+*     server sees no fragment, so neither does this.
+*
+* `new URLSearchParams(string)` cannot throw, so there is no parse failure to
+* swallow and no defaults-fallback to hide one: every byte of the target after
+* the first `?` is query data by definition. (A target malformed enough to
+* break `new URL` never reaches this module — `src/server.ts` builds a `URL`
+* to route on and fails there first.)
+*/
+function queryParams(url) {
+	const target = url ?? "/";
+	const start = target.indexOf("?");
+	return new URLSearchParams(start === -1 ? "" : target.slice(start + 1));
+}
+/**
+* The RAW query text a parameter was sent with - what the caller typed, before
+* percent- and `+`-decoding - or null when it was not sent at all.
+*
+* The unknown-`after` 400 below quotes the offending cursor, and the docs
+* promise it quotes "what you sent". `URLSearchParams` hands back the DECODED
+* value, so `?after=a%2Bb` was refused as `'a+b'` and `?after=a+b` as `'a b'` -
+* neither of which appears anywhere in the request the caller is staring at,
+* which is the one thing an error quoting a value is for.
+*
+* Pair splitting mirrors `URLSearchParams` itself, which splits on `&` alone
+* (`;` has not been a separator since the URL spec absorbed it), and the NAME
+* is matched through the platform's own decoder - one `URLSearchParams` per
+* pair - so an encoded spelling of the name still matches and nothing here
+* hand-rolls the percent codec. Only the VALUE is kept as raw text.
+*/
+function rawParam(url, name) {
+	const target = url ?? "/";
+	const start = target.indexOf("?");
+	if (start === -1) return null;
+	for (const pair of target.slice(start + 1).split("&")) {
+		if (pair.length === 0) continue;
+		const [decodedName] = new URLSearchParams(pair).keys();
+		if (decodedName !== name) continue;
+		const eq = pair.indexOf("=");
+		return eq === -1 ? "" : pair.slice(eq + 1);
+	}
+	return null;
+}
+/**
+* The single value of a query parameter, or the 400 a repeated one earns.
+*
+* `URLSearchParams.get` answers with the FIRST of a repeated parameter, which
+* launders the rest: `?limit=1&limit=abc` used to page at 1 and never look at
+* `abc`, so a caller building a URL twice over got a silent success where the
+* value it actually meant was invalid. The spec declares each of `limit` and
+* `after` as a single scalar (`listPaginatedFineTuningJobs`,
+* `listFineTuningEvents`) and gives no combining rule for a repeat, so a repeat
+* is a caller error here. That the 400 (rather than last-wins, or first-wins)
+* is ours, not the vendor's, is recorded in this module's header.
+*/
+function singleParam(params, name) {
+	const all = params.getAll(name);
+	if (all.length > 1) return {
+		ok: false,
+		message: `Invalid parameter: '${name}' was given ${all.length} times; it takes a single value`
+	};
+	return {
+		ok: true,
+		value: all.length === 0 ? null : all[0]
+	};
+}
+/**
+* Cursor page over an array already ordered newest-first, mirroring the
+* `after`/`limit` params both fine-tuning list endpoints accept. `has_more`
+* reports whether anything was left behind, so it is never a constant.
+*
+* Sourced 2026-09-15 from openai/openai-openapi `openapi.yaml` v2.3.0
+* (`listPaginatedFineTuningJobs`, `listFineTuningEvents`) and the vendored
+* `openai` SDK 4.104.0 `pagination.d.ts`/`pagination.js` `CursorPage`:
+*   - `after` is a free-form string id; `CursorPage.nextPageInfo()` feeds the
+*     LAST id of the page back as `after`, and `hasNextPage()` stops on
+*     `has_more: false`. Confirmed by the spec.
+*   - `limit` is `type: integer, default: 20` on both endpoints. Confirmed by
+*     the spec; the default is the vendor's.
+*
+* Three rules the spec does NOT state, chosen here and flagged as ours:
+*   - Upper bound 100 on `limit`. The spec declares no `maximum`. We enforce
+*     one so an oversized page fails loudly instead of being silently clamped,
+*     and 100 is the number our own docs page already advertises.
+*   - An `after` that matches no item is a 400 rather than a silent page 1.
+*     Returning page 1 makes the SDK's `CursorPage` auto-paginator restart from
+*     the top forever on a stale cursor; failing loudly is the whole point of a
+*     mock. Not observed against api.openai.com.
+*   - Newest-first ordering. Neither list endpoint accepts an `order` param and
+*     the spec never states a direction; the `listFineTuningEvents` example
+*     response lists the completion event ahead of the earlier
+*     model-created event, which reads as reverse-chronological.
+*/
+function paginate(items, url) {
+	const params = queryParams(url);
+	const readLimit = singleParam(params, "limit");
+	if (!readLimit.ok) return {
+		ok: false,
+		message: readLimit.message
+	};
+	const rawLimit = readLimit.value;
+	let limit = DEFAULT_PAGE_LIMIT;
+	if (rawLimit !== null) {
+		const n = require_helpers.parseStrictIntegerText(rawLimit);
+		if (n === null || n < 1 || n > MAX_PAGE_LIMIT) return {
+			ok: false,
+			message: `Invalid parameter: 'limit' must be an integer between 1 and ${MAX_PAGE_LIMIT}, got '${rawParam(url, "limit") ?? rawLimit}'`
+		};
+		limit = n;
+	}
+	const readAfter = singleParam(params, "after");
+	if (!readAfter.ok) return {
+		ok: false,
+		message: readAfter.message
+	};
+	const after = readAfter.value;
+	let start = 0;
+	if (after !== null) {
+		const idx = items.findIndex((it) => it.id === after);
+		if (idx === -1) return {
+			ok: false,
+			message: `Invalid parameter: 'after' is not a known cursor: '${rawParam(url, "after") ?? after}'`
+		};
+		start = idx + 1;
+	}
+	const rest = items.slice(start);
+	return {
+		ok: true,
+		page: {
+			object: "list",
+			data: rest.slice(0, limit),
+			has_more: rest.length > limit
+		}
+	};
+}
+/** Write a paginated list, or the 400 its `after`/`limit` params earned. */
+function writePage(res, journal, req, method, path, items, setCorsHeaders) {
+	const result = paginate(items, req.url);
+	const status = result.ok ? 200 : 400;
+	journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), status);
+	writeJson(res, status, result.ok ? result.page : invalid(result.message), setCorsHeaders);
+}
+/**
+* Deterministic seed in the spec's `[0, 2147483647]` range, derived from the
+* job id so repeated reads of the same job report the same seed.
+*/
+function seedFor(id) {
+	let h = 2166136261;
+	for (let i = 0; i < id.length; i++) h = Math.imul(h ^ id.charCodeAt(i), 16777619);
+	return (h >>> 0) % 2147483648;
+}
+/**
+* The three members `CreateFineTuningJobRequest.hyperparameters` and
+* `FineTuneSupervisedHyperparameters` both declare, quoted from
+* openai/openai-openapi `openapi.yaml` v2.3.0 (`master`):
+*   - `n_epochs`: `type: integer, minimum: 1, maximum: 50`
+*   - `batch_size`: `type: integer, minimum: 1, maximum: 256`
+*   - `learning_rate_multiplier`: `type: number, minimum: 0,
+*     exclusiveMinimum: true` — strictly greater than zero, hence no `max`.
+*
+* The vendored SDK's `JobCreateParams.Hyperparameters` types each member as
+* `"auto" | number`, which is as much as TypeScript can say; the bounds only
+* exist in the spec, so they are enforced here from it.
+*/
+const SUPERVISED_HYPER_RULES = {
+	n_epochs: {
+		kind: "integer",
+		min: 1,
+		max: 50
+	},
+	batch_size: {
+		kind: "integer",
+		min: 1,
+		max: 256
+	},
+	learning_rate_multiplier: {
+		kind: "number",
+		exclusiveMin: 0,
+		max: null
+	}
+};
+/**
+* The deprecated top-level `hyperparameters` object. The spec declares exactly
+* the three supervised members on it — `beta` and the reinforcement knobs live
+* only under `method`, and the description says this whole object "is now
+* deprecated in favor of `method`".
+*/
+const LEGACY_HYPER_RULES = SUPERVISED_HYPER_RULES;
+/**
+* `FineTuneDPOHyperparameters`: the supervised three plus `beta`, declared
+* `type: number, minimum: 0, exclusiveMinimum: true, maximum: 2`.
+*/
+const DPO_HYPER_RULES = {
+	...SUPERVISED_HYPER_RULES,
+	beta: {
+		kind: "number",
+		exclusiveMin: 0,
+		max: 2
+	}
+};
+/**
+* `FineTuneReinforcementHyperparameters`: the supervised three plus
+* `reasoning_effort` (`enum: [default, low, medium, high]`, no `"auto"`),
+* `compute_multiplier` (`minimum: 0.00001, exclusiveMinimum: true,
+* maximum: 10`), and `eval_interval`/`eval_samples` (`type: integer,
+* minimum: 1`, no declared maximum).
+*/
+const REINFORCEMENT_HYPER_RULES = {
+	...SUPERVISED_HYPER_RULES,
+	reasoning_effort: {
+		kind: "enum",
+		values: [
+			"default",
+			"low",
+			"medium",
+			"high"
+		]
+	},
+	compute_multiplier: {
+		kind: "number",
+		exclusiveMin: 1e-5,
+		max: 10
+	},
+	eval_interval: {
+		kind: "integer",
+		min: 1,
+		max: null
+	},
+	eval_samples: {
+		kind: "integer",
+		min: 1,
+		max: null
+	}
+};
+/** How a rule reads in an error message, so the caller learns the domain. */
+function describeRule(rule) {
+	if (rule.kind === "enum") return `one of ${rule.values.map((v) => `"${v}"`).join(", ")}`;
+	const upper = rule.max === null ? "" : ` and at most ${rule.max}`;
+	return `${rule.kind === "integer" ? `an integer at least ${rule.min}` : `a number greater than ${rule.exclusiveMin}`}${upper}, or the string "auto"`;
+}
+/**
+* Reads one hyperparameter against its rule. Anything outside the rule is a
+* caller error, never a silent drop — a mock that accepted `n_epochs: 0` would
+* let a bug reach the real API instead of failing where it is cheap to see.
+*
+* `path` names the object the member came from (`hyperparameters`,
+* `method.dpo.hyperparameters`, …) so the message points at the thing the
+* caller actually wrote.
+*/
+function readHyper(table, path, key, value) {
+	const rule = Object.hasOwn(table, key) ? table[key] : void 0;
+	if (rule === void 0) return {
+		ok: false,
+		message: unknownMemberMessage(table, path, key)
+	};
+	const bad = {
+		ok: false,
+		message: `Invalid parameter: '${path}.${key}' must be ${describeRule(rule)}`
+	};
+	if (rule.kind === "enum") return typeof value === "string" && rule.values.includes(value) ? {
+		ok: true,
+		value
+	} : bad;
+	if (value === "auto") return {
+		ok: true,
+		value: "auto"
+	};
+	if (typeof value !== "number" || !Number.isFinite(value)) return bad;
+	if (rule.max !== null && value > rule.max) return bad;
+	if (rule.kind === "integer") return value >= rule.min && Number.isInteger(value) ? {
+		ok: true,
+		value
+	} : bad;
+	return value > rule.exclusiveMin ? {
+		ok: true,
+		value
+	} : bad;
+}
+/** The 400 an unrecognised member of a rule-table-backed object earns. */
+function unknownMemberMessage(table, path, key) {
+	return `Invalid parameter: '${path}.${key}' is not a recognized member of '${path}'; it accepts ${Object.keys(table).join(", ")}`;
+}
+/**
+* Reads a whole hyperparameters object against its rule table.
+*
+* An unrecognised member is a 400 rather than a silent drop. The spec does not
+* mark these objects `additionalProperties: false`, so this rule is ours, not
+* the vendor's — and it is the point of the surface: `{n_epochs: 3, beta: 0.5}`
+* used to answer 200 echoing only `n_epochs`, so a caller who put a real DPO
+* hyperparameter (`FineTuneDPOHyperparameters.beta`) in the deprecated
+* top-level object instead of under `method.dpo.hyperparameters` was told it
+* had been accepted. Naming the members the object does take is what turns
+* that into a fixable message.
+*/
+function readHyperObject(table, path, raw) {
+	const out = {};
+	for (const [key, value] of Object.entries(raw)) {
+		if (value === void 0) continue;
+		if (!Object.hasOwn(table, key)) return {
+			ok: false,
+			message: unknownMemberMessage(table, path, key)
+		};
+		const read = readHyper(table, path, key, value);
+		if (!read.ok) return read;
+		out[key] = read.value;
+	}
+	return {
+		ok: true,
+		value: out
+	};
+}
+/**
+* Every property `CreateFineTuningJobRequest` declares (openai-openapi v2.3.0).
+*
+* Each one is read below; nothing on this list is accepted and dropped, and
+* anything NOT on it is a 400. The spec does not mark the request object
+* `additionalProperties: false`, so rejecting an unknown key is this mock's
+* rule, not the vendor's: a create body is written once and reused for months,
+* and a typo that answers 200 having ignored the field is exactly the bug a
+* mock exists to catch.
+*/
+const CREATE_KEYS = [
+	"model",
+	"training_file",
+	"hyperparameters",
+	"suffix",
+	"validation_file",
+	"integrations",
+	"seed",
+	"method",
+	"metadata"
+];
+/** The members of the deprecated top-level `hyperparameters`, as the job echoes them. */
+const LEGACY_HYPER_KEYS = [
+	"n_epochs",
+	"batch_size",
+	"learning_rate_multiplier"
+];
+/** `Metadata` in the spec: at most 16 pairs, keys <= 64 chars, values <= 512. */
+const METADATA_MAX_PAIRS = 16;
+const METADATA_MAX_KEY = 64;
+const METADATA_MAX_VALUE = 512;
+/** `CreateFineTuningJobRequest.suffix`: `minLength: 1, maxLength: 64`. */
+const SUFFIX_MAX_LENGTH = 64;
+/** `CreateFineTuningJobRequest.seed`: `minimum: 0, maximum: 2147483647`. */
+const SEED_MAX = 2147483647;
+/** `FineTuningJob.integrations`: `maxItems: 5`. */
+const MAX_INTEGRATIONS = 5;
+/**
+* Length in Unicode CODE POINTS, which is the unit the spec's limits are in.
+*
+* Every `maxLength` quoted in this module is a pydantic `max_length` on the
+* vendor's side, and pydantic counts code points; `String.prototype.length`
+* counts UTF-16 code units, which is the same number only while the string
+* stays inside the BMP. One astral character - an emoji, a rarer CJK
+* ideograph, a musical symbol - counts two there, so a `suffix` of exactly 64
+* characters holding one used to earn a 400 the real API would not send, and a
+* caller that trusted the mock would have shortened a name that was legal.
+*/
+function codePointLength(value) {
+	return [...value].length;
+}
+/**
+* `suffix`, per its spec description: "A string of up to 64 characters that
+* will be added to your fine-tuned model name. For example, a `suffix` of
+* "custom-model-name" would produce a model name like
+* `ft:gpt-4o-mini:openai:custom-model-name:7p4lURel`." It is declared
+* `type: string, minLength: 1, maxLength: 64, nullable: true, default: null`,
+* so `null` means "no suffix" and `""` is a 400.
+*/
+function readSuffix(value) {
+	if (value === void 0 || value === null) return {
+		ok: true,
+		value: null
+	};
+	if (typeof value !== "string" || value.length === 0 || codePointLength(value) > SUFFIX_MAX_LENGTH) return {
+		ok: false,
+		message: `Invalid parameter: 'suffix' must be a string of 1 to ${SUFFIX_MAX_LENGTH} characters or null`
+	};
+	return {
+		ok: true,
+		value
+	};
+}
+/**
+* `seed`, per its spec description: "The seed controls the reproducibility of
+* the job ... If a seed is not specified, one will be generated for you", and
+* declared `type: integer, nullable: true, minimum: 0, maximum: 2147483647`.
+* `null` and absence both mean "generate one", which is what `seedFor` does.
+*/
+function readSeed(value) {
+	if (value === void 0 || value === null) return {
+		ok: true,
+		value: null
+	};
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > SEED_MAX) return {
+		ok: false,
+		message: `Invalid parameter: 'seed' must be an integer between 0 and ${SEED_MAX} or null`
+	};
+	return {
+		ok: true,
+		value
+	};
+}
+/**
+* `metadata`, per the shared `Metadata` schema: an object of string values, at
+* most 16 pairs, keys at most 64 characters and values at most 512, or `null`.
+* `FineTuningJob` declares `metadata` too, so what is accepted is echoed back.
+*/
+function readMetadata(value) {
+	if (value === void 0 || value === null) return {
+		ok: true,
+		value: null
+	};
+	if (!require_helpers.isJsonObject(value)) return {
+		ok: false,
+		message: "Invalid parameter: 'metadata' must be a JSON object or null"
+	};
+	const entries = Object.entries(value);
+	if (entries.length > METADATA_MAX_PAIRS) return {
+		ok: false,
+		message: `Invalid parameter: 'metadata' accepts at most ${METADATA_MAX_PAIRS} key-value pairs, got ${entries.length}`
+	};
+	const out = Object.create(null);
+	for (const [key, entry] of entries) {
+		const keyLength = codePointLength(key);
+		if (keyLength > METADATA_MAX_KEY) return {
+			ok: false,
+			message: `Invalid parameter: 'metadata' keys are at most ${METADATA_MAX_KEY} characters, got ${keyLength}`
+		};
+		if (typeof entry !== "string" || codePointLength(entry) > METADATA_MAX_VALUE) return {
+			ok: false,
+			message: `Invalid parameter: 'metadata.${key}' must be a string of at most ${METADATA_MAX_VALUE} characters`
+		};
+		out[key] = entry;
+	}
+	return {
+		ok: true,
+		value: out
+	};
+}
+/**
+* One `integrations` entry. The spec requires both `type` and `wandb`, types
+* `type` as the single-member enum `wandb`, and requires `project` inside
+* `wandb`; `name` and `entity` are nullable strings and `tags` an array of
+* strings. `FineTuningJob.integrations` caps the list at `maxItems: 5` — the
+* request schema declares no cap, so enforcing the response's here is ours.
+*/
+function readIntegration(index, raw) {
+	const at = `integrations[${index}]`;
+	if (!require_helpers.isJsonObject(raw)) return {
+		ok: false,
+		message: `Invalid parameter: '${at}' must be a JSON object`
+	};
+	for (const key of Object.keys(raw)) if (key !== "type" && key !== "wandb") return {
+		ok: false,
+		message: `Invalid parameter: '${at}.${key}' is not a recognized member of '${at}'; it accepts type, wandb`
+	};
+	if (raw["type"] !== "wandb") return {
+		ok: false,
+		message: `Invalid parameter: '${at}.type' must be the string "wandb"`
+	};
+	const wandb = raw["wandb"];
+	if (!require_helpers.isJsonObject(wandb)) return {
+		ok: false,
+		message: `Invalid parameter: '${at}.wandb' must be a JSON object`
+	};
+	for (const key of Object.keys(wandb)) if (key !== "project" && key !== "name" && key !== "entity" && key !== "tags") return {
+		ok: false,
+		message: `Invalid parameter: '${at}.wandb.${key}' is not a recognized member of '${at}.wandb'; it accepts project, name, entity, tags`
+	};
+	const project = wandb["project"];
+	if (typeof project !== "string" || project.length === 0) return {
+		ok: false,
+		message: `Invalid parameter: '${at}.wandb.project' must be a non-empty string`
+	};
+	const value = {
+		type: "wandb",
+		wandb: { project }
+	};
+	for (const key of ["name", "entity"]) {
+		const member = wandb[key];
+		if (member === void 0) continue;
+		if (member !== null && typeof member !== "string") return {
+			ok: false,
+			message: `Invalid parameter: '${at}.wandb.${key}' must be a string or null`
+		};
+		value.wandb[key] = member;
+	}
+	const tags = wandb["tags"];
+	if (tags !== void 0) {
+		if (!Array.isArray(tags) || tags.some((tag) => typeof tag !== "string")) return {
+			ok: false,
+			message: `Invalid parameter: '${at}.wandb.tags' must be an array of strings`
+		};
+		value.wandb.tags = tags.filter((tag) => typeof tag === "string");
+	}
+	return {
+		ok: true,
+		value
+	};
+}
+/** `integrations`: a nullable array of the entries above. */
+function readIntegrations(value) {
+	if (value === void 0 || value === null) return {
+		ok: true,
+		value: null
+	};
+	if (!Array.isArray(value)) return {
+		ok: false,
+		message: "Invalid parameter: 'integrations' must be an array or null"
+	};
+	if (value.length > MAX_INTEGRATIONS) return {
+		ok: false,
+		message: `Invalid parameter: 'integrations' accepts at most ${MAX_INTEGRATIONS} entries, got ${value.length}`
+	};
+	const out = [];
+	for (const [index, entry] of value.entries()) {
+		const read = readIntegration(index, entry);
+		if (!read.ok) return read;
+		out.push(read.value);
+	}
+	return {
+		ok: true,
+		value: out
+	};
+}
+/** The rule table each `method` variant's `hyperparameters` is read against. */
+const METHOD_HYPER_RULES = {
+	supervised: SUPERVISED_HYPER_RULES,
+	dpo: DPO_HYPER_RULES,
+	reinforcement: REINFORCEMENT_HYPER_RULES
+};
+const METHOD_TYPES = [
+	"supervised",
+	"dpo",
+	"reinforcement"
+];
+/**
+* `method`, per `FineTuneMethod`: `type` is required and is one of
+* `supervised`, `dpo`, `reinforcement`, and each of those names an optional
+* sub-object carrying that method's `hyperparameters`. `FineTuneReinforcementMethod`
+* additionally requires a `grader`, so `type: "reinforcement"` requires one
+* whether or not the `reinforcement` sub-object is present at all — the
+* requirement is keyed on the chosen `type`, not on the sub-object happening
+* to be there.
+*
+* Only the chosen type's sub-object is accepted. `FineTuneMethod` leaves all
+* three optional and says nothing about a configuration for a type that was
+* not chosen, and neither does SDK 4.104.0's `JobCreateParams.Method`; every
+* example in the spec pairs a `type` with that type's own configuration and
+* no other (`createFineTuningJob`, the "Reinforcement" example). With the real
+* API's behaviour uncitable, a stray configuration is rejected rather than
+* accepted-and-ignored: this mock never takes a member it then drops.
+*
+* The grader itself (`GraderStringCheck` | `GraderTextSimilarity` |
+* `GraderPython` | `GraderScoreModel` | `GraderMulti`) is a schema tree of its
+* own that this mock does not model: it is required to be a JSON object and is
+* then echoed back verbatim on the job. That is a deliberate pass-through, not
+* a drop — what the caller sent is what the caller reads back.
+*
+* `FineTuningJob` declares `method`, so an accepted method is echoed.
+*/
+function readMethod(value) {
+	if (value === void 0 || value === null) return {
+		ok: true,
+		value: null
+	};
+	if (!require_helpers.isJsonObject(value)) return {
+		ok: false,
+		message: "Invalid parameter: 'method' must be a JSON object or null"
+	};
+	for (const key of Object.keys(value)) if (key !== "type" && !METHOD_TYPES.some((t) => t === key)) return {
+		ok: false,
+		message: `Invalid parameter: 'method.${key}' is not a recognized member of 'method'; it accepts type, ${METHOD_TYPES.join(", ")}`
+	};
+	const type = METHOD_TYPES.find((t) => t === value["type"]);
+	if (type === void 0) return {
+		ok: false,
+		message: `Invalid parameter: 'method.type' must be one of ${METHOD_TYPES.map((t) => `"${t}"`).join(", ")}`
+	};
+	const method = { type };
+	for (const variant of METHOD_TYPES) if (variant !== type && value[variant] !== void 0) return {
+		ok: false,
+		message: `Invalid parameter: 'method.${variant}' configures the "${variant}" method, but 'method.type' is "${type}"; a method carries only its own configuration`
+	};
+	const supplied = value[type];
+	const raw = supplied === void 0 && type === "reinforcement" ? {} : supplied;
+	if (raw !== void 0) {
+		if (!require_helpers.isJsonObject(raw)) return {
+			ok: false,
+			message: `Invalid parameter: 'method.${type}' must be a JSON object`
+		};
+		const allowed = type === "reinforcement" ? ["grader", "hyperparameters"] : ["hyperparameters"];
+		for (const key of Object.keys(raw)) if (!allowed.includes(key)) return {
+			ok: false,
+			message: `Invalid parameter: 'method.${type}.${key}' is not a recognized member of 'method.${type}'; it accepts ${allowed.join(", ")}`
+		};
+		const config = {};
+		if (type === "reinforcement") {
+			const grader = raw["grader"];
+			if (!require_helpers.isJsonObject(grader)) return {
+				ok: false,
+				message: "Invalid parameter: 'method.reinforcement.grader' is required and must be a JSON object"
+			};
+			config.grader = grader;
+		}
+		const hyper = raw["hyperparameters"];
+		if (hyper !== void 0) {
+			if (!require_helpers.isJsonObject(hyper)) return {
+				ok: false,
+				message: `Invalid parameter: 'method.${type}.hyperparameters' must be a JSON object`
+			};
+			const read = readHyperObject(METHOD_HYPER_RULES[type], `method.${type}.hyperparameters`, hyper);
+			if (!read.ok) return read;
+			config.hyperparameters = read.value;
+		}
+		method[type] = config;
+	}
+	return {
+		ok: true,
+		value: method
+	};
+}
+async function handleFineTuningCreate(req, res, raw, journal, defaults, setCorsHeaders) {
+	const path = req.url ?? "/v1/fine_tuning/jobs";
+	const method = req.method ?? "POST";
+	if (await chaosHit(req, journal, defaults, method, path, res, setCorsHeaders)) return;
+	let body;
+	try {
+		body = JSON.parse(raw);
+	} catch (err) {
+		journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 400);
+		writeJson(res, 400, invalid(`Malformed JSON: ${err instanceof Error ? err.message : "unknown"}`), setCorsHeaders);
+		return;
+	}
+	if (!require_helpers.isJsonObject(body)) {
+		journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 400);
+		writeJson(res, 400, invalid("Request body must be a JSON object"), setCorsHeaders);
+		return;
+	}
+	const journaledBody = body;
+	/**
+	* Every rejection below journals the parsed body before answering: these are
+	* exactly the 400s whose offending payload a caller needs to read back.
+	*/
+	const reject = (message) => {
+		journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 400, journaledBody);
+		writeJson(res, 400, invalid(message), setCorsHeaders);
+	};
+	for (const key of Object.keys(body)) if (!CREATE_KEYS.some((known) => known === key)) {
+		reject(`Invalid parameter: '${key}' is not a recognized request parameter; this endpoint accepts ${CREATE_KEYS.join(", ")}`);
+		return;
+	}
+	const trainingFile = body["training_file"];
+	const model = body["model"];
+	if (typeof trainingFile !== "string" || trainingFile.length === 0) {
+		reject("Invalid parameter: 'training_file' must be a non-empty string");
+		return;
+	}
+	if (typeof model !== "string" || model.length === 0) {
+		reject("Invalid parameter: 'model' must be a non-empty string");
+		return;
+	}
+	const validationFile = body["validation_file"];
+	if (validationFile !== void 0 && validationFile !== null && (typeof validationFile !== "string" || validationFile.length === 0)) {
+		reject("Invalid parameter: 'validation_file' must be a non-empty string or null");
+		return;
+	}
+	const hyper = body["hyperparameters"];
+	if (hyper !== void 0 && !require_helpers.isJsonObject(hyper)) {
+		reject("Invalid parameter: 'hyperparameters' must be a JSON object");
+		return;
+	}
+	const hyperparameters = {};
+	if (require_helpers.isJsonObject(hyper)) {
+		const read = readHyperObject(LEGACY_HYPER_RULES, "hyperparameters", hyper);
+		if (!read.ok) {
+			reject(read.message);
+			return;
+		}
+		for (const key of LEGACY_HYPER_KEYS) {
+			const value = read.value[key];
+			if (typeof value === "number" || value === "auto") hyperparameters[key] = value;
+		}
+	}
+	const suffix = readSuffix(body["suffix"]);
+	if (!suffix.ok) {
+		reject(suffix.message);
+		return;
+	}
+	const seed = readSeed(body["seed"]);
+	if (!seed.ok) {
+		reject(seed.message);
+		return;
+	}
+	const integrations = readIntegrations(body["integrations"]);
+	if (!integrations.ok) {
+		reject(integrations.message);
+		return;
+	}
+	const jobMethod = readMethod(body["method"]);
+	if (!jobMethod.ok) {
+		reject(jobMethod.message);
+		return;
+	}
+	const metadata = readMetadata(body["metadata"]);
+	if (!metadata.ok) {
+		reject(metadata.message);
+		return;
+	}
+	const id = require_helpers.generateId("ftjob");
+	const job = {
+		id,
+		object: "fine_tuning.job",
+		model,
+		training_file: trainingFile,
+		validation_file: typeof validationFile === "string" ? validationFile : null,
+		status: "validating_files",
+		created_at: stamp(),
+		finished_at: null,
+		fine_tuned_model: null,
+		hyperparameters,
+		error: null,
+		organization_id: ORGANIZATION_ID,
+		result_files: [],
+		seed: seed.value ?? seedFor(id),
+		trained_tokens: null
+	};
+	if (integrations.value !== null) job.integrations = integrations.value;
+	if (jobMethod.value !== null) job.method = jobMethod.value;
+	if (metadata.value !== null) job.metadata = metadata.value;
+	if (suffix.value !== null) suffixes.set(job.id, suffix.value);
+	jobs.set(job.id, job);
+	polls.set(job.id, 0);
+	appendEvent(job, "Job created, validating training file");
+	journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 200, journaledBody);
+	writeJson(res, 200, job, setCorsHeaders);
+}
+async function handleFineTuningList(req, res, journal, defaults, setCorsHeaders) {
+	const path = req.url ?? "/v1/fine_tuning/jobs";
+	const method = req.method ?? "GET";
+	if (await chaosHit(req, journal, defaults, method, path, res, setCorsHeaders)) return;
+	writePage(res, journal, req, method, path, [...jobs.values()].reverse(), setCorsHeaders);
+}
+async function handleFineTuningRetrieve(req, res, id, journal, defaults, setCorsHeaders) {
+	const path = req.url ?? `/v1/fine_tuning/jobs/${id}`;
+	const method = req.method ?? "GET";
+	if (await chaosHit(req, journal, defaults, method, path, res, setCorsHeaders)) return;
+	const job = jobs.get(id);
+	if (!job) {
+		journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 404);
+		writeJson(res, 404, invalid(`No such fine-tuning job: ${id}`), setCorsHeaders);
+		return;
+	}
+	journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 200);
+	writeJson(res, 200, advance(job), setCorsHeaders);
+}
+async function handleFineTuningCancel(req, res, id, journal, defaults, setCorsHeaders) {
+	const path = req.url ?? `/v1/fine_tuning/jobs/${id}/cancel`;
+	const method = req.method ?? "POST";
+	if (await chaosHit(req, journal, defaults, method, path, res, setCorsHeaders)) return;
+	const job = jobs.get(id);
+	if (!job) {
+		journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 404);
+		writeJson(res, 404, invalid(`No such fine-tuning job: ${id}`), setCorsHeaders);
+		return;
+	}
+	if (isTerminal(job.status)) {
+		journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 400);
+		writeJson(res, 400, invalid(`Job ${id} is already terminal (${job.status})`), setCorsHeaders);
+		return;
+	}
+	job.status = "cancelled";
+	job.finished_at = appendEvent(job, "Job cancelled by user");
+	journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 200);
+	writeJson(res, 200, job, setCorsHeaders);
+}
+async function handleFineTuningEvents(req, res, id, journal, defaults, setCorsHeaders) {
+	const path = req.url ?? `/v1/fine_tuning/jobs/${id}/events`;
+	const method = req.method ?? "GET";
+	if (await chaosHit(req, journal, defaults, method, path, res, setCorsHeaders)) return;
+	const job = jobs.get(id);
+	if (!job) {
+		journalFt(journal, method, path, require_helpers.flattenHeaders(req.headers), 404);
+		writeJson(res, 404, invalid(`No such fine-tuning job: ${id}`), setCorsHeaders);
+		return;
+	}
+	writePage(res, journal, req, method, path, eventsFor(job).reverse(), setCorsHeaders);
+}
+
+//#endregion
+exports.clearFineTuningStore = clearFineTuningStore;
+exports.handleFineTuningCancel = handleFineTuningCancel;
+exports.handleFineTuningCreate = handleFineTuningCreate;
+exports.handleFineTuningEvents = handleFineTuningEvents;
+exports.handleFineTuningList = handleFineTuningList;
+exports.handleFineTuningRetrieve = handleFineTuningRetrieve;
+exports.paginate = paginate;
+exports.readMetadata = readMetadata;
+//# sourceMappingURL=fine-tuning.cjs.map