@amboras-dev/capability-kit 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1036 @@
+import { z } from "zod/v4";
+//#region src/canonical-json.ts
+function serialize(value, seen) {
+	if (value !== null && typeof value === "object" && typeof value.toJSON === "function") value = value.toJSON();
+	if (value === null) return "null";
+	switch (typeof value) {
+		case "string": return JSON.stringify(value);
+		case "number": return Number.isFinite(value) ? JSON.stringify(value) : "null";
+		case "boolean": return value ? "true" : "false";
+		case "bigint": throw new TypeError("canonicalJson: BigInt is not JSON");
+		case "object": break;
+		default: return;
+	}
+	const obj = value;
+	if (seen.has(obj)) throw new TypeError("canonicalJson: circular structure");
+	seen.add(obj);
+	let out;
+	if (Array.isArray(obj)) out = `[${obj.map((item) => serialize(item, seen) ?? "null").join(",")}]`;
+	else {
+		const record = obj;
+		const parts = [];
+		for (const key of Object.keys(record).sort()) {
+			const item = serialize(record[key], seen);
+			if (item !== void 0) parts.push(`${JSON.stringify(key)}:${item}`);
+		}
+		out = `{${parts.join(",")}}`;
+	}
+	seen.delete(obj);
+	return out;
+}
+/** Sorted keys, no whitespace. Throws on BigInt and circular values; `undefined` at the top serializes as `null`. */
+function canonicalJson(v) {
+	return serialize(v, /* @__PURE__ */ new Set()) ?? "null";
+}
+//#endregion
+//#region src/errors.ts
+const STATUS = {
+	invalid_input: 400,
+	forbidden: 403,
+	not_found: 404,
+	conflict: 409,
+	confirmation_required: 409,
+	rate_limited: 429,
+	idempotency_conflict: 409,
+	unavailable: 503,
+	internal: 500
+};
+function httpStatusFor(code) {
+	return STATUS[code];
+}
+/** Retrying the same request can succeed later only for these. */
+const RETRYABLE_BY_DEFAULT = /* @__PURE__ */ new Set(["rate_limited", "unavailable"]);
+var CapabilityError = class extends Error {
+	/** `retryable` defaults to true for `rate_limited` and `unavailable`, else false. */
+	constructor(init) {
+		super(init.message);
+		this.name = "CapabilityError";
+		this.body = {
+			...init,
+			retryable: init.retryable ?? RETRYABLE_BY_DEFAULT.has(init.code)
+		};
+		this.status = httpStatusFor(init.code);
+	}
+};
+/** A definition that breaks a kit rule. Thrown at boot, never per request. */
+var CapabilityDefinitionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CapabilityDefinitionError";
+	}
+};
+/** A manifest that fails its shape or hash check. */
+var CapabilityManifestError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CapabilityManifestError";
+	}
+};
+const dotted = (path) => path.map((p) => String(p)).join(".");
+const hasOwn = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+function issueRule(issue) {
+	const params = issue.params;
+	if (issue.code !== "custom" || typeof params !== "object" || params === null) return void 0;
+	const rule = params.rule;
+	return typeof rule === "string" ? rule : void 0;
+}
+function plain(issue) {
+	const field = dotted(issue.path);
+	const rule = issueRule(issue);
+	return {
+		field,
+		message: issue.message,
+		headline: field ? `${field}: ${issue.message}` : issue.message,
+		...rule ? { rule } : {}
+	};
+}
+/** One entry per renamed key (steering message first), then the issue itself for any other unknown keys. */
+/**
+* A plain union reports only "Invalid input" at its own path. Report the branch
+* that came closest instead (fewest issues, then fewest literal mismatches; the
+* first on a tie), with full paths.
+*/
+function unionEntries(issue, renamed) {
+	const branches = issue.errors.filter((b) => b.length > 0);
+	if (branches.length === 0) return void 0;
+	const rank = (branch) => branch.length * 1e3 + branch.filter((i) => i.code === "invalid_value").length;
+	return branches.reduce((best, branch) => rank(branch) < rank(best) ? branch : best).flatMap((sub) => entriesFor({
+		...sub,
+		path: [...issue.path, ...sub.path]
+	}, renamed));
+}
+function entriesFor(issue, renamed) {
+	if (issue.code === "invalid_union") return unionEntries(issue, renamed) ?? [plain(issue)];
+	if (issue.code !== "unrecognized_keys" || !Array.isArray(issue.keys)) return [plain(issue)];
+	const keys = issue.keys.map(String);
+	const known = keys.filter((key) => hasOwn(renamed, key));
+	if (known.length === 0) return [plain(issue)];
+	const out = known.map((key) => {
+		const message = `"${key}" was removed: use ${renamed[key]}.`;
+		return {
+			field: dotted([...issue.path, key]),
+			message,
+			headline: message,
+			rule: "field_renamed"
+		};
+	});
+	const rest = keys.filter((key) => !hasOwn(renamed, key));
+	if (rest.length > 0) {
+		const message = `Unrecognized key${rest.length > 1 ? "s" : ""}: ${rest.map((k) => `"${k}"`).join(", ")}`;
+		out.push(plain({
+			...issue,
+			keys: rest,
+			message
+		}));
+	}
+	return out;
+}
+/**
+* `invalid_input`: `field` is the dotted path of the first issue, `issues` lists
+* all of them. Renamed-field issues (`options.renamed`) come first and make the headline. A custom issue's `params.rule` becomes `body.rule`; see
+* `options.renamed` for steering removed field names.
+*/
+function fromZodError(err, options = {}) {
+	const renamed = options.renamed ?? {};
+	const all = err.issues.flatMap((issue) => entriesFor(issue, renamed));
+	const entries = [...all.filter((e) => e.rule === "field_renamed"), ...all.filter((e) => e.rule !== "field_renamed")];
+	const issues = entries.map(({ field, message }) => ({
+		field,
+		message
+	}));
+	const first = entries[0];
+	if (!first) return new CapabilityError({
+		code: "invalid_input",
+		message: "Invalid input",
+		issues: []
+	});
+	return new CapabilityError({
+		code: "invalid_input",
+		message: first.headline,
+		...first.field ? { field: first.field } : {},
+		...first.rule ? { rule: first.rule } : {},
+		issues
+	});
+}
+//#endregion
+//#region src/ids.ts
+const AREAS = [
+	"promotions",
+	"catalog",
+	"inventory",
+	"setup",
+	"content",
+	"orders",
+	"payments",
+	"domains",
+	"publish"
+];
+/** Higher rank includes every lower one: an owner can do what a manager can. */
+const ROLE_RANK = Object.freeze({
+	owner: 3,
+	manager: 2,
+	staff: 1
+});
+const ID_PATTERN = new RegExp(`^(${AREAS.join("|")})(\\.[a-z][a-z_]*){1,2}$`);
+/** True for a well-formed id in a known area. */
+function isCapabilityId(value) {
+	return typeof value === "string" && ID_PATTERN.test(value);
+}
+/** The area an id belongs to (`promotions.create` → `promotions`). */
+function areaOf(id) {
+	return id.slice(0, id.indexOf("."));
+}
+/** True for `owner`, `manager` or `staff`. */
+function isRole(value) {
+	return value === "owner" || value === "manager" || value === "staff";
+}
+//#endregion
+//#region src/money.ts
+const ZERO_DECIMAL = /* @__PURE__ */ new Set([
+	"JPY",
+	"KRW",
+	"VND",
+	"CLP",
+	"PYG",
+	"XAF",
+	"XOF",
+	"BIF",
+	"DJF",
+	"GNF",
+	"ISK",
+	"KMF",
+	"MGA",
+	"RWF",
+	"UGX",
+	"VUV",
+	"XPF"
+]);
+const THREE_DECIMAL = /* @__PURE__ */ new Set([
+	"KWD",
+	"BHD",
+	"OMR",
+	"TND",
+	"JOD",
+	"IQD",
+	"LYD"
+]);
+/** The one unit sentence every money field carries, for the model and for people. */
+const MONEY_UNIT_SENTENCE = "Amount in normal currency units as the merchant says it (99 means 99.00; 1.5 means 1.50). Never cents or minor units.";
+/** JSON Schema keyword marking a money field. */
+const MONEY_META_KEY = "x-amboras-money";
+/**
+* A bad amount or currency code. It is an `invalid_input` CapabilityError, so an
+* adapter that maps CapabilityError answers 400 with the rule (and the field,
+* when the caller passed one) instead of a 500.
+*/
+var MoneyError = class extends CapabilityError {
+	constructor(message, rule, field) {
+		super({
+			code: "invalid_input",
+			message: field ? `${field}: ${message}` : message,
+			rule,
+			...field ? { field } : {}
+		});
+		this.name = "MoneyError";
+	}
+};
+const isBound = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+const BRANDS = /* @__PURE__ */ new WeakMap();
+const alwaysValid = () => true;
+/** The money brand a schema carries, if it was built by money() (through any chain). */
+function moneyBrandOf(schema) {
+	const checks = schema?._zod?.def?.checks;
+	if (!checks) return void 0;
+	for (const check of checks) {
+		const brand = BRANDS.get(check);
+		if (brand) return brand;
+	}
+}
+/**
+* A major-unit amount: finite, ≥ 0 (or > `exclusiveMinimum`), at most `max`,
+* described with MONEY_UNIT_SENTENCE and marked `x-amboras-money` in JSON Schema.
+*
+* Chained checks (`.positive()`, `.max()`, `.int()`) and `.optional()`,
+* `.nullable()`, `.nullish()` are safe: the kit's JSON Schema keeps the sentence
+* and the marker. `.describe()` replaces the sentence, which `defineCapability`
+* rejects: pass `describe` here instead.
+*/
+function money(opts) {
+	let marker;
+	if ("currencyField" in opts) {
+		if (typeof opts.currencyField !== "string" || opts.currencyField.trim() === "") throw new CapabilityDefinitionError("money(): currencyField must be a non-empty field name");
+		marker = { currencyField: opts.currencyField };
+	} else if (opts.currency === "store") marker = { currency: "store" };
+	else throw new CapabilityDefinitionError("money(): pass { currencyField } or { currency: 'store' }");
+	const { exclusiveMinimum, max } = opts;
+	if (exclusiveMinimum !== void 0 && !isBound(exclusiveMinimum)) throw new CapabilityDefinitionError("money(): exclusiveMinimum must be a finite number ≥ 0");
+	if (max !== void 0 && (!isBound(max) || max <= (exclusiveMinimum ?? -1))) throw new CapabilityDefinitionError("money(): max must be a finite number ≥ 0 and above exclusiveMinimum");
+	const description = opts.describe ? `${opts.describe.trim()} ${MONEY_UNIT_SENTENCE}` : MONEY_UNIT_SENTENCE;
+	let schema = exclusiveMinimum === void 0 ? z.number().min(0) : z.number().gt(exclusiveMinimum);
+	if (max !== void 0) schema = schema.max(max);
+	schema = schema.refine(alwaysValid);
+	const { checks } = schema._zod.def;
+	BRANDS.set(checks[checks.length - 1], {
+		description,
+		marker
+	});
+	return schema.meta({
+		description,
+		[MONEY_META_KEY]: marker
+	});
+}
+function normalizeCode(currency) {
+	if (typeof currency !== "string" || !/^[A-Za-z]{3}$/.test(currency)) throw new MoneyError(`Invalid currency code: ${JSON.stringify(currency)}`, "currency_invalid");
+	return currency.toUpperCase();
+}
+/** ISO 4217 minor-unit digits: 0 for JPY/KRW/VND…, 3 for KWD/BHD/OMR/TND/JOD/IQD/LYD, else 2 (also for unknown codes). */
+function fractionDigits(currency) {
+	const code = normalizeCode(currency);
+	if (ZERO_DECIMAL.has(code)) return 0;
+	if (THREE_DECIMAL.has(code)) return 3;
+	return 2;
+}
+/**
+* Amboras storage rule: ×1000 for the seven three-decimal codes, ×100 for every
+* other code INCLUDING zero-decimal ones (¥5 is stored as 500). By design; see
+* Medusa `divisorFor`.
+*/
+function storageScale(currency) {
+	return THREE_DECIMAL.has(normalizeCode(currency)) ? 1e3 : 100;
+}
+const MAX_UNITS = 2 ** 46;
+/** Decimal places in the shortest text form of `n` (what JSON carries): 19.99 → 2, 1e-7 → 7, 1.5e+21 → 0. */
+function decimalPlaces(n) {
+	const [mantissa, exponent = "0"] = String(Math.abs(n)).split("e");
+	const fraction = mantissa.split(".")[1] ?? "";
+	return Math.max(0, fraction.length - Number(exponent));
+}
+/**
+* Major → stored minor integer. Throws MoneyError (`invalid_input`) when the
+* amount has more fraction digits than the currency allows (19.999 USD, 5.5 JPY),
+* is not finite, or does not fit a safe integer. Pass `field` to name the input
+* field in the error.
+*
+* An amount is accepted when its decimal text has at most the allowed digits
+* (exact at any magnitude), or when it is within float noise of such an amount
+* (0.1 + 0.2 → 0.30). Noise is bounded absolutely, so a real extra digit is never
+* rounded away, however large the amount.
+*/
+function toStorageAmount(major, currency, field) {
+	const digits = fractionDigits(currency);
+	const scale = storageScale(currency);
+	const code = currency.toUpperCase();
+	if (typeof major !== "number" || !Number.isFinite(major)) throw new MoneyError(`Amount must be a finite number, got ${String(major)}`, "money_invalid", field);
+	const inDigits = major * 10 ** digits;
+	const whole = Math.round(inDigits);
+	const noise = Math.abs(inDigits - whole);
+	if (!(decimalPlaces(major) <= digits) && noise > Math.min(8 * Number.EPSILON * Math.max(1, Math.abs(inDigits)), 1e-6)) throw new MoneyError(`${major} has more than ${digits} decimal places, the most ${code} allows`, "money_precision", field);
+	const stored = whole * (scale / 10 ** digits);
+	if (Math.abs(whole) > MAX_UNITS || !Number.isSafeInteger(stored)) throw new MoneyError(`${major} ${code} is too large to store`, "money_invalid", field);
+	return stored === 0 ? 0 : stored;
+}
+/** Stored minor amount → major units. */
+function fromStorageAmount(minor, currency) {
+	const scale = storageScale(currency);
+	if (typeof minor !== "number" || !Number.isFinite(minor)) throw new MoneyError(`Stored amount must be a finite number, got ${String(minor)}`, "money_invalid");
+	return minor / scale;
+}
+/** Output schema for a MoneyView (what `moneyView` returns), for capability outputs. */
+const moneyViewSchema = z.object({
+	amount: z.number().describe("Amount in normal currency units (major units)."),
+	currency: z.string().length(3).describe("ISO 4217 code, upper case."),
+	display: z.string().describe("Formatted for people, e.g. \"$19.99\".")
+});
+/**
+* A stored amount as the merchant reads it. Fraction digits are pinned (not left
+* to the runtime's ICU data): ISO digits, widened only to show a stored value
+* that is not a whole minor unit (¥5.5 stays visible).
+*/
+function moneyView(minor, currency) {
+	const code = normalizeCode(currency);
+	const amount = fromStorageAmount(minor, code);
+	const digits = fractionDigits(code);
+	const scaleDigits = storageScale(code) === 1e3 ? 3 : 2;
+	return {
+		amount,
+		currency: code,
+		display: new Intl.NumberFormat("en", {
+			style: "currency",
+			currency: code,
+			minimumFractionDigits: digits,
+			maximumFractionDigits: Math.max(digits, scaleDigits)
+		}).format(amount)
+	};
+}
+//#endregion
+//#region src/json-schema.ts
+/**
+* The exact conversion every manifest uses. Throws for types JSON Schema cannot
+* express. Every money() field gets its marker back, and its unit sentence when
+* a chained check dropped the description (zod 3.25's zod/v4, zod 4.0–4.2). A
+* description that REPLACED the sentence is left alone for defineCapability to reject.
+*/
+function toJsonSchema(schema, io) {
+	return z.toJSONSchema(schema, {
+		target: "draft-2020-12",
+		io,
+		override: (ctx) => {
+			const brand = moneyBrandOf(ctx.zodSchema);
+			if (!brand) return;
+			const node = ctx.jsonSchema;
+			node[MONEY_META_KEY] = { ...brand.marker };
+			if (typeof node.description !== "string") node.description = brand.description;
+		}
+	});
+}
+function isRecord$1(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Object schemas reachable from `node` without entering a property: itself, its combinator branches and $ref targets. */
+function objectBranches(node, root, seen) {
+	if (seen.has(node)) return [];
+	seen.add(node);
+	const out = [node];
+	for (const key of [
+		"anyOf",
+		"oneOf",
+		"allOf"
+	]) {
+		const branches = node[key];
+		if (Array.isArray(branches)) {
+			for (const branch of branches) if (isRecord$1(branch)) out.push(...objectBranches(branch, root, seen));
+		}
+	}
+	const ref = node.$ref;
+	if (typeof ref === "string" && ref.startsWith("#/$defs/")) {
+		const defs = root.$defs;
+		const target = isRecord$1(defs) ? defs[ref.slice(8)] : void 0;
+		if (isRecord$1(target)) out.push(...objectBranches(target, root, seen));
+	}
+	return out;
+}
+/**
+* The property schemas a dotted path (`discount.amount_off`) names, across union
+* branches. Empty when no branch has it.
+*/
+function resolveField(root, path) {
+	let level = [root];
+	let found = [];
+	for (const name of path.split(".")) {
+		found = [];
+		for (const node of level) for (const branch of objectBranches(node, root, /* @__PURE__ */ new Set())) {
+			const props = branch.properties;
+			if (isRecord$1(props) && Object.prototype.hasOwnProperty.call(props, name) && isRecord$1(props[name])) found.push({
+				parent: branch,
+				name
+			});
+		}
+		level = found.map(({ parent, name: n }) => parent.properties[n]);
+	}
+	return found;
+}
+/**
+* A copy of `schema` without the hidden fields (`agent.hideFields`), also
+* dropped from `required`. Adapters build the model-facing input with this.
+*/
+function omitFields(schema, fields) {
+	const copy = JSON.parse(JSON.stringify(schema));
+	for (const field of fields) for (const { parent, name } of resolveField(copy, field)) {
+		delete parent.properties[name];
+		if (Array.isArray(parent.required)) parent.required = parent.required.filter((r) => r !== name);
+	}
+	return copy;
+}
+//#endregion
+//#region src/guards.ts
+/**
+* Tenant and actor ids come from the call context, never from input. A name is
+* refused when, lower-cased with separators removed, it ends in one of these
+* (`store_id`, `storeId`, `store-environment-id`, `shop_id`, `env_id` …).
+*/
+const FORBIDDEN_SUFFIXES = [
+	"storeid",
+	"tenantid",
+	"profileid",
+	"environmentid",
+	"envid",
+	"shopid",
+	"merchantid"
+];
+/** An object field with one of these names and an `id` inside (`store: { id }`) is the same thing spelt differently. */
+const FORBIDDEN_CONTAINERS = /* @__PURE__ */ new Set([
+	"store",
+	"tenant",
+	"profile",
+	"environment",
+	"env",
+	"shop",
+	"merchant"
+]);
+const normalizeName = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
+const isForbiddenName = (name) => {
+	const n = normalizeName(name);
+	return FORBIDDEN_SUFFIXES.some((suffix) => n.endsWith(suffix));
+};
+const TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+const isPositiveInt = (n) => typeof n === "number" && Number.isInteger(n) && n >= 1;
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** Keywords whose value is a map of schemas, a schema, or a list of schemas. */
+const SCHEMA_MAPS = [
+	"properties",
+	"patternProperties",
+	"$defs",
+	"definitions",
+	"dependentSchemas"
+];
+const SCHEMA_VALUES = [
+	"items",
+	"additionalProperties",
+	"propertyNames",
+	"contains",
+	"if",
+	"then",
+	"else",
+	"unevaluatedProperties",
+	"unevaluatedItems"
+];
+const SCHEMA_LISTS = [
+	"anyOf",
+	"oneOf",
+	"allOf",
+	"prefixItems"
+];
+/** A schema with none of these accepts any value (`z.any()`, `z.unknown()`). */
+const CONSTRAINING = [
+	"type",
+	"enum",
+	"const",
+	"$ref",
+	"not",
+	...SCHEMA_LISTS
+];
+/** Visits every subschema (not `not`: what it forbids is not input). `true` is visited as `{}`. */
+function visitSchemas(schema, visit) {
+	if (schema === true) {
+		visit({});
+		return;
+	}
+	if (!isRecord(schema)) return;
+	visit(schema);
+	for (const key of SCHEMA_MAPS) {
+		const map = schema[key];
+		if (isRecord(map)) for (const name of Object.keys(map)) visitSchemas(map[name], visit);
+	}
+	for (const key of SCHEMA_VALUES) if (key in schema) visitSchemas(schema[key], visit);
+	for (const key of SCHEMA_LISTS) {
+		const list = schema[key];
+		if (Array.isArray(list)) for (const item of list) visitSchemas(item, visit);
+	}
+}
+function finiteKeys(node) {
+	const names = node.propertyNames;
+	if (!isRecord(names) || !Array.isArray(names.enum)) return void 0;
+	return names.enum.filter((v) => typeof v === "string");
+}
+function fail(id, message) {
+	throw new CapabilityDefinitionError(`${id}: ${message}`);
+}
+function checkFieldName(id, name, schema) {
+	if (isForbiddenName(name)) fail(id, `input must not contain "${name}"; store, tenant, profile and environment ids come from the call context`);
+	if (FORBIDDEN_CONTAINERS.has(normalizeName(name)) && isRecord(schema) && isRecord(schema.properties) && "id" in schema.properties) fail(id, `input must not contain "${name}.id"; store, tenant, profile and environment ids come from the call context`);
+}
+function checkMoneyNode(id, input, node) {
+	const description = node.description;
+	if (typeof description !== "string" || !description.includes("Amount in normal currency units as the merchant says it (99 means 99.00; 1.5 means 1.50). Never cents or minor units.")) fail(id, "a money() field lost its unit sentence; pass money({ ..., describe }) instead of .describe()/.meta()");
+	const marker = node[MONEY_META_KEY];
+	const field = isRecord(marker) ? marker.currencyField : void 0;
+	if (isRecord(marker) && marker.currency === "store" && field === void 0) return;
+	if (typeof field !== "string") fail(id, `a money() field has a malformed ${MONEY_META_KEY} marker`);
+	const found = resolveField(input, field);
+	if (found.length === 0) fail(id, `money() currencyField "${field}" is not a field at the input root`);
+	for (const { parent, name } of found) {
+		const target = parent.properties[name];
+		if (!(target.type === "string" || Array.isArray(target.enum) && target.enum.every((v) => typeof v === "string"))) fail(id, `money() currencyField "${field}" must be a string field (an ISO 4217 code)`);
+	}
+}
+/**
+* The input must be a plain object (every tool-calling API needs one), every key
+* it accepts must be declared, and no declared key may carry a tenant or actor
+* id at any depth (records, unions, intersections, arrays and tuples included).
+*/
+function checkInputSchema(id, input) {
+	if (input.type !== "object") fail(id, "input must be an object schema (z.object / z.strictObject)");
+	visitSchemas(input, (node) => {
+		if (!CONSTRAINING.some((key) => key in node)) fail(id, "input contains a field that accepts any value (z.any / z.unknown); declare its shape");
+		const props = node.properties;
+		if (isRecord(props)) for (const name of Object.keys(props)) checkFieldName(id, name, props[name]);
+		const keys = finiteKeys(node);
+		if (keys) for (const name of keys) checkFieldName(id, name, node.additionalProperties);
+		if (node.additionalProperties !== void 0 && node.additionalProperties !== false && !keys || "patternProperties" in node || "propertyNames" in node && !keys) fail(id, "input objects must declare their keys (no z.record with open keys, z.looseObject or .passthrough())");
+		if ("x-amboras-money" in node) checkMoneyNode(id, input, node);
+	});
+}
+function checkHideFields(id, input, hideFields) {
+	for (const field of hideFields) {
+		const found = resolveField(input, field);
+		if (found.length === 0) fail(id, `hideFields names "${field}", which is not an input field`);
+		for (const { parent, name } of found) if (Array.isArray(parent.required) && parent.required.includes(name)) fail(id, `hidden field "${field}" is required, so the model could never send a valid call; make it optional or give it a default`);
+	}
+}
+function checkPolicy(id, policy) {
+	if (!isRole(policy.minRole)) fail(id, "policy.minRole must be owner, manager or staff");
+	if (typeof policy.confirm === "object" && !isPositiveInt(policy.confirm.when.recordsAtLeast)) fail(id, "policy.confirm.when.recordsAtLeast must be an integer ≥ 1");
+	if (policy.rateLimit && !isPositiveInt(policy.rateLimit.perMinute)) fail(id, "policy.rateLimit.perMinute must be an integer ≥ 1");
+}
+/** Every rule that does not need zod or the run function. Throws CapabilityDefinitionError. */
+function checkEntry(entry) {
+	const { id } = entry;
+	if (!isCapabilityId(id)) throw new CapabilityDefinitionError(`Invalid capability id "${id}": use <area>.<verb> or <area>.<entity>.<verb>, lowercase a-z and _`);
+	if (!isPositiveInt(entry.version)) fail(id, "version must be an integer ≥ 1");
+	if (entry.owner !== "medusa" && entry.owner !== "orchestrator") fail(id, "owner must be medusa or orchestrator");
+	if (typeof entry.http.path !== "string" || !entry.http.path.startsWith("/")) fail(id, "http.path must start with /");
+	checkInputSchema(id, entry.input);
+	checkHideFields(id, entry.input, entry.agent.hideFields ?? []);
+	checkPolicy(id, entry.policy);
+	if (typeof entry.agent.description !== "string" || entry.agent.description.trim() === "") fail(id, "agent.description is required");
+	if (entry.agent.toolName !== void 0 && !TOOL_NAME.test(entry.agent.toolName)) fail(id, `agent.toolName must match ${TOOL_NAME}`);
+}
+//#endregion
+//#region src/define.ts
+function convert(schema, io, id) {
+	try {
+		return toJsonSchema(schema, io);
+	} catch (err) {
+		throw new CapabilityDefinitionError(`${id}: ${io} schema cannot be expressed as JSON Schema (${String(err)})`);
+	}
+}
+function freezeCopy(value) {
+	return Object.freeze({ ...value });
+}
+/**
+* Runs every definition rule and returns the input and output JSON Schemas.
+* emitManifest calls it again, so a definition that skipped defineCapability
+* still cannot reach a manifest.
+*/
+function checkDefinition(def) {
+	const id = def.id;
+	if (!isCapabilityId(id)) throw new CapabilityDefinitionError(`Invalid capability id "${id}": use <area>.<verb> or <area>.<entity>.<verb>, lowercase a-z and _`);
+	if (def.http.runsOn === "custom" && typeof def.run !== "function") throw new CapabilityDefinitionError(`${id}: runsOn 'custom' needs a run function`);
+	const input = convert(def.input, "input", id);
+	const output = convert(def.output, "output", id);
+	checkEntry({
+		...def,
+		input
+	});
+	return {
+		input,
+		output
+	};
+}
+/**
+* Checks a definition and returns a frozen copy. Throws CapabilityDefinitionError
+* on: a bad id or unknown area; a version that is not a positive integer; an
+* input that is not an object, accepts undeclared keys or any value, or names a
+* store / tenant / profile / environment id at any depth; runsOn 'custom'
+* without run; hideFields naming a missing (or required) field; a schema JSON
+* Schema cannot express; a money() field without its unit sentence or with a
+* currencyField that is not a string field at the input root; an invalid
+* minRole, confirm threshold, rate limit or toolName.
+*/
+function defineCapability(def) {
+	checkDefinition(def);
+	return Object.freeze({
+		...def,
+		http: freezeCopy(def.http),
+		policy: freezeCopy(def.policy),
+		agent: freezeCopy(def.agent)
+	});
+}
+//#endregion
+//#region src/sha256.ts
+const K = new Uint32Array([
+	1116352408,
+	1899447441,
+	3049323471,
+	3921009573,
+	961987163,
+	1508970993,
+	2453635748,
+	2870763221,
+	3624381080,
+	310598401,
+	607225278,
+	1426881987,
+	1925078388,
+	2162078206,
+	2614888103,
+	3248222580,
+	3835390401,
+	4022224774,
+	264347078,
+	604807628,
+	770255983,
+	1249150122,
+	1555081692,
+	1996064986,
+	2554220882,
+	2821834349,
+	2952996808,
+	3210313671,
+	3336571891,
+	3584528711,
+	113926993,
+	338241895,
+	666307205,
+	773529912,
+	1294757372,
+	1396182291,
+	1695183700,
+	1986661051,
+	2177026350,
+	2456956037,
+	2730485921,
+	2820302411,
+	3259730800,
+	3345764771,
+	3516065817,
+	3600352804,
+	4094571909,
+	275423344,
+	430227734,
+	506948616,
+	659060556,
+	883997877,
+	958139571,
+	1322822218,
+	1537002063,
+	1747873779,
+	1955562222,
+	2024104815,
+	2227730452,
+	2361852424,
+	2428436474,
+	2756734187,
+	3204031479,
+	3329325298
+]);
+/** UTF-8 bytes of `text`; a lone surrogate becomes U+FFFD, as `TextEncoder` and Node do. */
+function utf8(text) {
+	const out = [];
+	for (let i = 0; i < text.length; i++) {
+		let c = text.charCodeAt(i);
+		if (c >= 55296 && c <= 56319 && i + 1 < text.length) {
+			const next = text.charCodeAt(i + 1);
+			if (next >= 56320 && next <= 57343) {
+				c = 65536 + (c - 55296 << 10) + (next - 56320);
+				i++;
+			}
+		}
+		if (c >= 55296 && c <= 57343) c = 65533;
+		if (c < 128) out.push(c);
+		else if (c < 2048) out.push(192 | c >> 6, 128 | c & 63);
+		else if (c < 65536) out.push(224 | c >> 12, 128 | c >> 6 & 63, 128 | c & 63);
+		else out.push(240 | c >> 18, 128 | c >> 12 & 63, 128 | c >> 6 & 63, 128 | c & 63);
+	}
+	return out;
+}
+const rotr = (x, n) => x >>> n | x << 32 - n;
+function sha256Hex(text) {
+	const bytes = utf8(text);
+	const bitLength = bytes.length * 8;
+	bytes.push(128);
+	while (bytes.length % 64 !== 56) bytes.push(0);
+	const high = Math.floor(bitLength / 4294967296);
+	bytes.push(high >>> 24 & 255, high >>> 16 & 255, high >>> 8 & 255, high & 255);
+	bytes.push(bitLength >>> 24 & 255, bitLength >>> 16 & 255, bitLength >>> 8 & 255, bitLength & 255);
+	const h = new Uint32Array([
+		1779033703,
+		3144134277,
+		1013904242,
+		2773480762,
+		1359893119,
+		2600822924,
+		528734635,
+		1541459225
+	]);
+	const w = /* @__PURE__ */ new Uint32Array(64);
+	for (let offset = 0; offset < bytes.length; offset += 64) {
+		for (let t = 0; t < 16; t++) {
+			const j = offset + t * 4;
+			w[t] = bytes[j] << 24 | bytes[j + 1] << 16 | bytes[j + 2] << 8 | bytes[j + 3];
+		}
+		for (let t = 16; t < 64; t++) {
+			const s0 = rotr(w[t - 15], 7) ^ rotr(w[t - 15], 18) ^ w[t - 15] >>> 3;
+			const s1 = rotr(w[t - 2], 17) ^ rotr(w[t - 2], 19) ^ w[t - 2] >>> 10;
+			w[t] = w[t - 16] + s0 + w[t - 7] + s1;
+		}
+		let [a, b, c, d, e, f, g, hh] = h;
+		for (let t = 0; t < 64; t++) {
+			const t1 = hh + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + (e & f ^ ~e & g) + K[t] + w[t] >>> 0;
+			const t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + (a & b ^ a & c ^ b & c) >>> 0;
+			hh = g;
+			g = f;
+			f = e;
+			e = d + t1 >>> 0;
+			d = c;
+			c = b;
+			b = a;
+			a = t1 + t2 >>> 0;
+		}
+		h[0] += a;
+		h[1] += b;
+		h[2] += c;
+		h[3] += d;
+		h[4] += e;
+		h[5] += f;
+		h[6] += g;
+		h[7] += hh;
+	}
+	let hex = "";
+	for (const word of h) hex += word.toString(16).padStart(8, "0");
+	return hex;
+}
+//#endregion
+//#region src/idempotency.ts
+/**
+* 8–100 of `A-Z a-z 0-9 . _ : -`. The underscore is there because the
+* orchestrator's key is `cap.{runId}.{toolCallId}` and model tool call ids
+* contain one (`toolu_…`, `call_…`).
+*/
+const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9_.:-]{8,100}$/;
+/** A non-read capability that is not naturally idempotent needs an `Idempotency-Key`. */
+function requiresIdempotencyKey(policy) {
+	return policy.effect !== "read" && !policy.idempotent;
+}
+/** sha256 hex of canonicalJson({ id, input }): same key + different fingerprint = a different request. */
+function requestFingerprint(id, input) {
+	return sha256Hex(canonicalJson({
+		id,
+		input
+	}));
+}
+//#endregion
+//#region src/manifest.ts
+const hashOf = (capabilities) => sha256Hex(canonicalJson(capabilities));
+/** Plain JSON with keys sorted at every level, so the committed file is stable text. */
+const sortedJson = (value) => JSON.parse(canonicalJson(value));
+/**
+* Deterministic: entries sorted by id, schemas converted with
+* `{ target: 'draft-2020-12', io }`, no timestamps. Every definition is checked
+* again (the defineCapability rules). Throws on a duplicate id.
+*
+* The JSON Schema text depends on the zod version that emits it (zod 3.25 writes
+* a discriminated union as anyOf, 4.3 as oneOf), so the hash is only comparable
+* between emits on the SAME zod version. Consumers verify a received manifest
+* with parseManifest; they never re-emit it to compare.
+*/
+function emitManifest(defs, source) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const def of defs) {
+		if (seen.has(def.id)) throw new CapabilityDefinitionError(`Duplicate capability id ${def.id}`);
+		seen.add(def.id);
+	}
+	const capabilities = [...defs].sort((a, b) => a.id < b.id ? -1 : 1).map((def) => {
+		const { input, output } = checkDefinition(def);
+		return sortedJson({
+			id: def.id,
+			version: def.version,
+			owner: def.owner,
+			http: def.http,
+			input,
+			output,
+			policy: def.policy,
+			agent: def.agent
+		});
+	});
+	return {
+		schemaVersion: 1,
+		source,
+		hash: hashOf(capabilities),
+		capabilities
+	};
+}
+const positiveInt = z.number().int().min(1);
+const jsonSchemaObject = z.record(z.string(), z.unknown());
+const entrySchema = z.looseObject({
+	id: z.string().refine(isCapabilityId, "not a valid capability id"),
+	version: positiveInt,
+	owner: z.enum(["medusa", "orchestrator"]),
+	http: z.looseObject({
+		method: z.enum([
+			"GET",
+			"POST",
+			"DELETE"
+		]),
+		path: z.string(),
+		runsOn: z.enum(["custom", "core"])
+	}),
+	input: jsonSchemaObject,
+	output: jsonSchemaObject,
+	policy: z.looseObject({
+		minRole: z.enum([
+			"owner",
+			"manager",
+			"staff"
+		]),
+		planFeature: z.string().optional(),
+		effect: z.enum([
+			"read",
+			"write",
+			"destructive"
+		]),
+		idempotent: z.boolean(),
+		money: z.boolean().optional(),
+		confirm: z.union([z.enum(["never", "always"]), z.looseObject({ when: z.looseObject({ recordsAtLeast: positiveInt }) })]),
+		rateLimit: z.looseObject({ perMinute: positiveInt }).optional()
+	}),
+	agent: z.looseObject({
+		description: z.string(),
+		rules: z.array(z.string()).optional(),
+		examples: z.array(z.looseObject({
+			input: z.unknown(),
+			note: z.string()
+		})).optional(),
+		hideFields: z.array(z.string()).optional(),
+		exposure: z.enum([
+			"task-tool",
+			"long-tail",
+			"hidden"
+		]),
+		toolName: z.string().optional()
+	})
+});
+const manifestSchema = z.object({
+	schemaVersion: z.literal(1),
+	source: z.enum(["medusa", "orchestrator"]),
+	hash: z.string().regex(/^[0-9a-f]{64}$/),
+	capabilities: z.array(entrySchema)
+});
+/**
+* Validates the shape, re-runs the definition rules on every entry (tenant ids,
+* open inputs, money sentence …) and recomputes the hash from the JSON as
+* received, never from schemas. Throws CapabilityManifestError on any failure.
+* The hash proves the file is intact, not who wrote it: trust comes from where
+* the file is read (the committed copy), not from the hash.
+*/
+function parseManifest(json) {
+	const parsed = manifestSchema.safeParse(json);
+	if (!parsed.success) {
+		const first = parsed.error.issues[0];
+		throw new CapabilityManifestError(`Invalid capability manifest at ${first.path.join(".") || "(root)"}: ${first.message}`);
+	}
+	const manifest = parsed.data;
+	const ids = /* @__PURE__ */ new Set();
+	for (const entry of manifest.capabilities) {
+		if (ids.has(entry.id)) throw new CapabilityManifestError(`Duplicate capability id ${entry.id} in manifest`);
+		ids.add(entry.id);
+		try {
+			checkEntry(entry);
+		} catch (err) {
+			throw new CapabilityManifestError(`Invalid capability manifest entry: ${err.message}`);
+		}
+	}
+	const actual = hashOf(json.capabilities);
+	if (actual !== manifest.hash) throw new CapabilityManifestError(`Capability manifest hash mismatch: header ${manifest.hash}, content ${actual}`);
+	return manifest;
+}
+//#endregion
+//#region src/policy.ts
+function roleCheck(policy, ctx) {
+	const { actor } = ctx;
+	if (actor.kind === "internal") return null;
+	if (actor.role === null) return {
+		rule: "role_unknown",
+		error: new CapabilityError({
+			code: "forbidden",
+			rule: "role_unknown",
+			message: "Your role in this store could not be read."
+		})
+	};
+	if (ROLE_RANK[actor.role] >= ROLE_RANK[policy.minRole]) return null;
+	return {
+		rule: "role_insufficient",
+		error: new CapabilityError({
+			code: "forbidden",
+			rule: "role_insufficient",
+			message: `This needs the ${policy.minRole} role or higher; you are ${actor.role}.`
+		})
+	};
+}
+function planCheck(policy, facts) {
+	const feature = policy.planFeature;
+	if (feature === void 0) return null;
+	if (facts.planFeatures === void 0) return {
+		rule: "plan_unknown",
+		error: new CapabilityError({
+			code: "unavailable",
+			rule: "plan_unknown",
+			message: "The store's plan could not be read."
+		})
+	};
+	if (facts.planFeatures.includes(feature)) return null;
+	return {
+		rule: "plan_feature_required",
+		error: new CapabilityError({
+			code: "forbidden",
+			rule: "plan_feature_required",
+			message: `The store's plan does not include ${feature}.`
+		})
+	};
+}
+function evaluatePolicy(policy, ctx, facts, enforcement) {
+	if (typeof ctx.tenantId !== "string" || ctx.tenantId.trim() === "") return {
+		allow: false,
+		error: new CapabilityError({
+			code: "forbidden",
+			rule: "tenant_required",
+			message: "No store was resolved for this call."
+		})
+	};
+	for (const mode of [enforcement.role, enforcement.plan]) if (mode !== "enforce" && mode !== "observe") return {
+		allow: false,
+		error: new CapabilityError({
+			code: "internal",
+			rule: "policy_mode_invalid",
+			message: `Invalid policy enforcement mode ${JSON.stringify(mode)}.`
+		})
+	};
+	const observed = [];
+	const steps = [[roleCheck(policy, ctx), enforcement.role], [planCheck(policy, facts), enforcement.plan]];
+	for (const [check, mode] of steps) {
+		if (check === null) continue;
+		if (mode === "enforce") return {
+			allow: false,
+			error: check.error
+		};
+		observed.push(check.rule);
+	}
+	return {
+		allow: true,
+		observed
+	};
+}
+/**
+* True when the call needs an explicit confirmation before it runs. `records` is
+* how many records it touches. A threshold policy with no count, or a count that
+* is not a non-negative integer, requires confirmation (the adapter could not count).
+*/
+function confirmationRequired(policy, records) {
+	const { confirm } = policy;
+	if (confirm === "never") return false;
+	if (confirm === "always") return true;
+	if (typeof records !== "number" || !Number.isInteger(records) || records < 0) return true;
+	return records >= confirm.when.recordsAtLeast;
+}
+//#endregion
+export { AREAS, CapabilityDefinitionError, CapabilityError, CapabilityManifestError, IDEMPOTENCY_KEY_PATTERN, MONEY_META_KEY, MONEY_UNIT_SENTENCE, MoneyError, ROLE_RANK, areaOf, canonicalJson, confirmationRequired, defineCapability, emitManifest, evaluatePolicy, fractionDigits, fromStorageAmount, fromZodError, httpStatusFor, isCapabilityId, money, moneyView, moneyViewSchema, omitFields, parseManifest, requestFingerprint, requiresIdempotencyKey, storageScale, toStorageAmount };