@contentrain/types 1.13.0 → 1.14.0

package/dist/index.mjs

@@ -1,3 +1,26 @@
+//#region src/canonical.ts
+/** Recursively sort object keys — respects optional fieldOrder for top-level keys */
+function sortKeys(obj, fieldOrder) {
+	if (obj === null || obj === void 0) return void 0;
+	if (Array.isArray(obj)) return obj.map((item) => sortKeys(item, fieldOrder));
+	if (typeof obj !== "object") return obj;
+	const record = obj;
+	const sorted = {};
+	const keys = fieldOrder ? [...new Set([...fieldOrder, ...Object.keys(record).toSorted()])] : Object.keys(record).toSorted();
+	for (const key of keys) {
+		if (!(key in record)) continue;
+		const val = record[key];
+		if (val === null || val === void 0) continue;
+		sorted[key] = sortKeys(val);
+	}
+	return sorted;
+}
+/** Canonical JSON serialization — deterministic output for stable git diffs */
+function canonicalStringify(data, fieldOrder) {
+	const sorted = sortKeys(data, fieldOrder);
+	return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+//#endregion
 //#region src/migration.ts
 /**
 * Version stamped into every migration document (`version` field on each root).
@@ -127,6 +150,338 @@ const COMPONENT_TYPES = [
 ];
 const COMMENTS_EXPORT_FORMAT = "contentrain-comments@1";
 //#endregion
+//#region src/execution.ts
+/**
+* Version stamped into every execution document (`version` field on each root).
+* A reader that sees a higher version than it knows should refuse rather than
+* guess — a misread plan is a plan executed with the wrong scope.
+*/
+const EXECUTION_CONTRACT_VERSION = 1;
+/**
+* What is at stake in an operation, in ascending severity.
+*
+* The order is the contract, not a convenience: `RISK_CLASSES` is a ladder and
+* a policy written for `bulk_content` is expected to also cover everything
+* above it. The seven rungs come from the approval model — read-only work is
+* automatic, content edits follow project policy, and anything that leaves the
+* repository (money, third parties, production) is a separate decision from
+* whether the content is correct.
+*/
+const RISK_CLASSES = [
+	"read_only",
+	"low_risk_content",
+	"bulk_content",
+	"destructive_schema",
+	"external_effect",
+	"financially_material",
+	"deployment"
+];
+/** Position on the ladder; higher is more severe. */
+function riskRank(risk) {
+	return RISK_CLASSES.indexOf(risk);
+}
+/**
+* The most severe of the given classes — the class a multi-step plan is
+* evaluated against. A plan is exactly as safe as its worst step, so a
+* read-only survey that ends in a deploy is a deploy.
+*/
+function highestRisk(risks) {
+	let worst = "read_only";
+	for (const risk of risks) if (riskRank(risk) > riskRank(worst)) worst = risk;
+	return worst;
+}
+/**
+* The three moments at which a decision is asked for. They are distinct
+* questions and collapsing them is the mistake this type exists to prevent:
+* approving *what will be done* is not approving *what was produced*, and
+* neither is permission to put it in front of the public.
+*/
+const APPROVAL_GATES = [
+	"plan",
+	"change",
+	"release"
+];
+/**
+* How many people, and which, must say yes. Deliberately three modes: a
+* generic workflow canvas was considered and rejected — policy-based approval
+* covers every case the product actually has.
+*/
+const APPROVAL_MODES = [
+	"auto",
+	"single",
+	"quorum"
+];
+/**
+* Run lifecycle. The main line is `draft → planned → awaiting_approval →
+* approved → scheduled → queued → running → verifying → completed`; the rest
+* are the states a run can sit in when something interrupts it.
+*/
+const RUN_STATUSES = [
+	"draft",
+	"planned",
+	"awaiting_approval",
+	"approved",
+	"scheduled",
+	"queued",
+	"running",
+	"verifying",
+	"completed",
+	"paused",
+	"needs_attention",
+	"retrying",
+	"failed",
+	"cancelled",
+	"expired",
+	"rolled_back"
+];
+/** Statuses from which a run will not proceed on its own. */
+const TERMINAL_RUN_STATUSES = [
+	"completed",
+	"failed",
+	"cancelled",
+	"expired",
+	"rolled_back"
+];
+function isTerminalRunStatus(status) {
+	return TERMINAL_RUN_STATUSES.includes(status);
+}
+/** Approvers recorded on a receipt for one gate, in grant order. */
+function approversFor(receipt, gate) {
+	return (receipt.approvals ?? []).filter((grant) => grant.gate === gate).map((grant) => grant.approver);
+}
+const SCHEDULE_KINDS = [
+	"once",
+	"recurring",
+	"content_event",
+	"git_event",
+	"runtime_event",
+	"external_webhook",
+	"manual"
+];
+const SOURCE_DELTA_OPS = [
+	"created",
+	"updated",
+	"deleted",
+	"moved"
+];
+/**
+* The exact bytes `plan_hash` is computed over. Exposed because a hash is only
+* useful if a disagreement can be investigated: when two sides compute
+* different hashes for the same plan, comparing payloads shows which field
+* differs, and comparing hashes shows nothing.
+*
+* Excluded: `plan_hash` itself (it cannot cover itself), and `id`,
+* `created_at`, `created_by` and `idempotency_key` — who built a plan, when,
+* under which run id, and with which deduplication key do not change what the
+* plan will do. Everything else is covered, so a changed step, a widened
+* scope, a raised estimate or a withdrawn rollback all invalidate every
+* approval the plan had collected.
+*/
+function planHashPayload(plan) {
+	const { plan_hash: _hash, id: _id, created_at: _at, created_by: _by, idempotency_key: _key, ...semantic } = plan;
+	return canonicalStringify(semantic);
+}
+/**
+* SHA-256 of {@link planHashPayload}, lowercase hex.
+*
+* Async because it uses Web Crypto (`globalThis.crypto.subtle`), which is
+* available in Node 18+, Deno, Bun, workers and browsers alike — this package
+* is consumed in all of them and must not reach for `node:crypto`. A non-
+* cryptographic hash was considered and rejected: approvals are pinned to this
+* value, so a collision is an approval bypass, not a cache miss.
+*/
+async function computePlanHash(plan) {
+	const bytes = new TextEncoder().encode(planHashPayload(plan));
+	const digest = await crypto.subtle.digest("SHA-256", bytes);
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
+//#region src/approval.ts
+/**
+* Used when a project has no `.contentrain/approval-policies.json`.
+*
+* Read-only work proceeds; everything else wants one reviewer on the produced
+* diff. Deliberately stated as a value rather than buried in the evaluator so
+* a project can inspect it, extend it, or reject it — and so "what happens
+* without a policy file" has one answer instead of one per caller.
+*
+* Note this is a *default*, not the only gate in the system: whether a project
+* consults the evaluator at all is still governed by its `workflow` setting.
+*/
+const DEFAULT_APPROVAL_POLICY = {
+	version: 1,
+	rules: [{
+		risk: "low_risk_content",
+		gate: "change",
+		mode: "single"
+	}]
+};
+/** Ascending strictness — used to keep the stricter of two modes. */
+const MODE_RANK = {
+	auto: 0,
+	single: 1,
+	quorum: 2
+};
+/** How many distinct approvers a mode asks for. */
+function approvalsNeeded(rule) {
+	if (rule.mode === "auto") return 0;
+	if (rule.mode === "single") return 1;
+	return Math.max(1, rule.min_approvals ?? 2);
+}
+/** Whether a rule's narrowing clauses match what the plan touches. */
+function ruleMatchesScope(rule, plan) {
+	if (rule.models && rule.models.length > 0) {
+		const touched = plan.scope.models ?? [];
+		if (!rule.models.some((model) => touched.includes(model))) return false;
+	}
+	if (rule.locales && rule.locales.length > 0) {
+		const touched = plan.scope.locales ?? [];
+		if (!rule.locales.some((locale) => touched.includes(locale))) return false;
+	}
+	return true;
+}
+/**
+* The class a plan is judged at: its declared risk, or its worst step's if
+* that is higher. A plan cannot understate itself — declaring `read_only`
+* while carrying a deploy step would otherwise walk straight past the policy.
+*/
+function effectiveRisk(plan) {
+	return highestRisk([plan.risk, ...plan.steps.map((step) => step.risk)]);
+}
+/**
+* The requirements a policy produces for a plan, before any decision is
+* collected. This is what a plan card renders: "this needs one reviewer on the
+* diff and two on release, because it deploys".
+*
+* Each matching rule contributes its own requirement and all of them must be
+* met. Merging two rules into one would need a rule for combining their modes,
+* roles and counts — and every such rule has a case where the result is
+* *looser* than one of its inputs. Keeping them separate is what makes the
+* policy additive in fact and not just in intent.
+*
+* `auto` rules are dropped rather than kept as zero-approver requirements: a
+* requirement nobody has to satisfy is noise on the card, and a stricter rule
+* matching the same gate still stands on its own.
+*/
+function requiredApprovals(plan, policy = DEFAULT_APPROVAL_POLICY) {
+	const risk = effectiveRisk(plan);
+	const requirements = [];
+	let matched = false;
+	for (const rule of policy.rules) {
+		if (!ruleMatchesScope(rule, plan)) continue;
+		if (!(rule.mode !== "auto" ? riskRank(risk) >= riskRank(rule.risk) : risk === rule.risk)) continue;
+		matched = true;
+		const min_approvals = approvalsNeeded(rule);
+		if (min_approvals === 0) continue;
+		requirements.push({
+			gate: rule.gate,
+			mode: rule.mode,
+			min_approvals,
+			...rule.roles && rule.roles.length > 0 ? { roles: [...rule.roles] } : {},
+			because: rule.risk
+		});
+	}
+	if (!matched && policy.default_mode && policy.default_mode !== "auto") requirements.push({
+		gate: "change",
+		mode: policy.default_mode,
+		min_approvals: approvalsNeeded({
+			risk,
+			gate: "change",
+			mode: policy.default_mode
+		}),
+		because: risk
+	});
+	return requirements.toSorted((a, b) => APPROVAL_GATES.indexOf(a.gate) - APPROVAL_GATES.indexOf(b.gate) || MODE_RANK[b.mode] - MODE_RANK[a.mode] || b.min_approvals - a.min_approvals);
+}
+/** Whether a grant may be counted at all, independent of any requirement. */
+function grantDisqualification(grant, plan, policy, commit_sha, now) {
+	if (grant.plan_hash !== plan.plan_hash) return "plan_hash_mismatch";
+	if (grant.expires_at && grant.expires_at <= now) return "expired";
+	if (grant.approver.kind === "agent") return "agent_approver";
+	if (!policy.allow_self_approval && plan.created_by && grant.approver.id === plan.created_by.id && grant.approver.kind === plan.created_by.kind) return "self_approval";
+	if (grant.gate === "change" && commit_sha && grant.commit_sha !== commit_sha) return "commit_mismatch";
+}
+/**
+* May this plan proceed?
+*
+* Answers with the full picture rather than a boolean: which requirements
+* exist, which are met, who met them, and — for every decision that was
+* supplied but did not count — why it did not. The last part is what makes
+* "I approved this, why is it still blocked?" answerable without reading the
+* evaluator's source.
+*/
+function evaluateApproval(input) {
+	const { plan, commit_sha } = input;
+	const policy = input.policy ?? DEFAULT_APPROVAL_POLICY;
+	const grants = input.grants ?? [];
+	const now = input.now ?? (/* @__PURE__ */ new Date()).toISOString();
+	const risk = effectiveRisk(plan);
+	const requirements = requiredApprovals(plan, policy).map((requirement) => Object.assign(requirement, {
+		approvers: [],
+		remaining: requirement.min_approvals
+	}));
+	const rejected_grants = [];
+	for (const grant of grants) {
+		const disqualified = grantDisqualification(grant, plan, policy, commit_sha, now);
+		if (disqualified) {
+			rejected_grants.push({
+				grant,
+				reason: disqualified
+			});
+			continue;
+		}
+		let counted = false;
+		let sawGate = false;
+		let roleBlocked = false;
+		let duplicate = false;
+		for (const requirement of requirements) {
+			if (requirement.gate !== grant.gate) continue;
+			sawGate = true;
+			if (requirement.roles && !requirement.roles.includes(grant.approver.role ?? "")) {
+				roleBlocked = true;
+				continue;
+			}
+			if (requirement.approvers.some((approver) => approver.id === grant.approver.id)) {
+				duplicate = true;
+				continue;
+			}
+			requirement.approvers.push(grant.approver);
+			requirement.remaining = Math.max(0, requirement.min_approvals - requirement.approvers.length);
+			counted = true;
+		}
+		if (counted) continue;
+		if (!sawGate) rejected_grants.push({
+			grant,
+			reason: "no_matching_requirement"
+		});
+		else if (duplicate) rejected_grants.push({
+			grant,
+			reason: "duplicate_approver"
+		});
+		else if (roleBlocked) rejected_grants.push({
+			grant,
+			reason: "role_not_permitted"
+		});
+	}
+	const outstanding = requirements.filter((requirement) => requirement.remaining > 0);
+	const reasons = [];
+	const expired = Boolean(plan.expires_at && plan.expires_at <= now);
+	if (expired) reasons.push(`The plan expired at ${plan.expires_at}; rebuild it rather than running it.`);
+	for (const requirement of outstanding) {
+		const who = requirement.roles ? ` from ${requirement.roles.join(" or ")}` : "";
+		const have = requirement.approvers.length;
+		reasons.push(`${requirement.gate} approval: ${requirement.remaining} more${who} needed (${have}/${requirement.min_approvals}), because the plan is ${requirement.because}.`);
+	}
+	return {
+		allowed: !expired && outstanding.length === 0,
+		risk,
+		requirements,
+		outstanding,
+		rejected_grants,
+		reasons
+	};
+}
+//#endregion
 //#region src/provider.ts
 /** Capability set for the LocalProvider (simple-git + worktree). */
 const LOCAL_CAPABILITIES = {
@@ -153,17 +508,35 @@ const CONTENTRAIN_DIR = ".contentrain";
 * `{projectRoot}/{content_path}/` instead — but meta files always
 * remain under `.contentrain/meta/`.
 */
+/**
+* Where each kind of file lives. These are the paths a reader can rely on and
+* a writer must produce; `@contentrain/mcp` resolves exactly these, and a
+* parity test there holds the two together.
+*
+* They show the default `locale_strategy: 'file'`. The `suffix`, `directory`
+* and `none` strategies move the locale within the same directory — see
+* `LocaleStrategy` — and `content_path` replaces the
+* `.contentrain/content/{domain}/{modelId}` prefix entirely.
+*
+* Meta always carries a locale in its file name: a non-i18n model keeps one
+* meta record, pinned to the project's default locale.
+*/
 const PATH_PATTERNS = {
 	config: ".contentrain/config.json",
 	context: ".contentrain/context.json",
 	vocabulary: ".contentrain/vocabulary.json",
 	model: ".contentrain/models/{modelId}.json",
+	capabilities: ".contentrain/capabilities.json",
+	automations: ".contentrain/automations.json",
+	approvalPolicies: ".contentrain/approval-policies.json",
+	redirects: ".contentrain/redirects.json",
 	content: {
 		singleton: ".contentrain/content/{domain}/{modelId}/{locale}.json",
 		collection: ".contentrain/content/{domain}/{modelId}/{locale}.json",
-		document: ".contentrain/content/{domain}/{slug}/{locale}.md",
+		document: ".contentrain/content/{domain}/{modelId}/{slug}/{locale}.md",
 		dictionary: ".contentrain/content/{domain}/{modelId}/{locale}.json",
-		noLocale: ".contentrain/content/{domain}/{modelId}/data.json"
+		noLocale: ".contentrain/content/{domain}/{modelId}/data.json",
+		noLocaleDocument: ".contentrain/content/{domain}/{modelId}/{slug}.md"
 	},
 	meta: {
 		singleton: ".contentrain/meta/{modelId}/{locale}.json",
@@ -172,6 +545,37 @@ const PATH_PATTERNS = {
 		dictionary: ".contentrain/meta/{modelId}/{locale}.json"
 	}
 };
+/**
+* Paths this repository reserves but does not yet write.
+*
+* Reserving them is the point. `.contentrain/` is a shared namespace: the
+* migration engine, Studio and a customer's own tooling all write into it. A
+* name claimed here cannot later be taken for something else, and — more
+* usefully — the tools that walk the directory know these four are *expected*
+* rather than stray.
+*
+* The contract for them is deliberately narrow and must stay that way until a
+* tool actually owns one:
+*
+* - `contentrain_doctor` and `contentrain_validate` ignore them. They are not
+*   orphans, not broken content, and not the validator's business.
+* - `contentrain_reconcile` treats each as one opaque file: it takes the side
+*   that changed, and reports `file_conflict` when both sides did. It never
+*   merges their interiors, because it does not know their interiors.
+*
+* Both behaviours are pinned by tests in `@contentrain/mcp`, so a future
+* change to directory walking cannot quietly start flagging or auto-merging
+* these files.
+*/
+const RESERVED_PATHS = [
+	PATH_PATTERNS.capabilities,
+	PATH_PATTERNS.automations,
+	PATH_PATTERNS.approvalPolicies,
+	PATH_PATTERNS.redirects
+];
+function isReservedPath(path) {
+	return RESERVED_PATHS.includes(path);
+}
 /** Slug: lowercase alphanumeric with hyphens */
 const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** Entry ID: alphanumeric, 1-40 chars, starts with alphanumeric */
@@ -589,27 +993,6 @@ function validateFieldValue(value, fieldDef) {
 	}
 	return issues;
 }
-/** Recursively sort object keys — respects optional fieldOrder for top-level keys */
-function sortKeys(obj, fieldOrder) {
-	if (obj === null || obj === void 0) return void 0;
-	if (Array.isArray(obj)) return obj.map((item) => sortKeys(item, fieldOrder));
-	if (typeof obj !== "object") return obj;
-	const record = obj;
-	const sorted = {};
-	const keys = fieldOrder ? [...new Set([...fieldOrder, ...Object.keys(record).toSorted()])] : Object.keys(record).toSorted();
-	for (const key of keys) {
-		if (!(key in record)) continue;
-		const val = record[key];
-		if (val === null || val === void 0) continue;
-		sorted[key] = sortKeys(val);
-	}
-	return sorted;
-}
-/** Canonical JSON serialization — deterministic output for stable git diffs */
-function canonicalStringify(data, fieldOrder) {
-	const sorted = sortKeys(data, fieldOrder);
-	return `${JSON.stringify(sorted, null, 2)}\n`;
-}
 /** Generate a 12-character hex entry ID */
 function generateEntryId() {
 	const hex = "0123456789abcdef";
@@ -655,18 +1038,128 @@ function conflictId(conflict) {
 		sortKeys(conflict.theirs) ?? null
 	]));
 }
-function parseYamlValue(raw) {
+/**
+* Decode the interior of a double-quoted scalar, or `undefined` when the text
+* is not one scalar after all — an unescaped `"` inside it, or a backslash with
+* nothing after it.
+*
+* Returning `undefined` rather than guessing matters: `"a" and "b"` starts and
+* ends with a quote without being a quoted scalar, and slicing the ends off it
+* would silently corrupt the value.
+*
+* An unrecognised escape keeps its backslash instead of erroring. Our own
+* serializer only ever emits `\\`, `\"`, `\n`, `\r` and `\t`, so round-tripping is
+* unaffected either way — but hand-written frontmatter says `"C:\Users"` and
+* losing that to strictness would be a worse trade than keeping the bytes.
+*/
+function decodeDoubleQuoted(inner) {
+	let out = "";
+	for (let i = 0; i < inner.length; i += 1) {
+		const char = inner[i];
+		if (char === "\"") return void 0;
+		if (char !== "\\") {
+			out += char;
+			continue;
+		}
+		const next = inner[i + 1];
+		if (next === void 0) return void 0;
+		i += 1;
+		if (next === "n") out += "\n";
+		else if (next === "r") out += "\r";
+		else if (next === "t") out += "	";
+		else if (next === "\\" || next === "\"" || next === "/") out += next;
+		else if (next === "u" && /^[0-9a-fA-F]{4}$/.test(inner.slice(i + 1, i + 5))) {
+			out += String.fromCharCode(parseInt(inner.slice(i + 1, i + 5), 16));
+			i += 4;
+		} else out += `\\${next}`;
+	}
+	return out;
+}
+/** Decode a single-quoted scalar, where YAML escapes a quote by doubling it. */
+function decodeSingleQuoted(inner) {
+	let out = "";
+	for (let i = 0; i < inner.length; i += 1) {
+		const char = inner[i];
+		if (char !== "'") {
+			out += char;
+			continue;
+		}
+		if (inner[i + 1] !== "'") return void 0;
+		out += "'";
+		i += 1;
+	}
+	return out;
+}
+/**
+* Read one frontmatter scalar: booleans, null, numbers, quoted strings with
+* their escapes decoded, or the text as written.
+*
+* Exported because it is a **contract**, not a utility. Two readers open these
+* documents — this package (through `parseMarkdownFrontmatter`, which
+* `@contentrain/mcp` re-exports) and `@contentrain/query`'s generator and Astro
+* loader. When each had its own copy they disagreed about what `"He said
+* \"Hi\""` says, which means the generated client and the content engine
+* disagreed about the same file. One implementation, imported by both.
+*/
+function parseFrontmatterScalar(raw) {
 	if (raw === "true") return true;
 	if (raw === "false") return false;
 	if (raw === "null") return null;
 	if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
 	if (/^-?\d+\.\d+$/.test(raw)) return parseFloat(raw);
-	if (raw.startsWith("\"") && raw.endsWith("\"") || raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
+	if (raw.length >= 2 && raw.startsWith("\"") && raw.endsWith("\"")) return decodeDoubleQuoted(raw.slice(1, -1)) ?? raw;
+	if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")) return decodeSingleQuoted(raw.slice(1, -1)) ?? raw;
 	return raw;
 }
+/**
+* A scalar read as a string: quoting and escapes are resolved, but a value that
+* merely looks like a number or a boolean stays the text it was. Array items
+* use this, and so does any reader that knows from the model that a field is
+* string-typed — a SKU of `"007"` must not become the number 7.
+*/
+function parseFrontmatterScalarString(raw) {
+	const value = parseFrontmatterScalar(raw);
+	return typeof value === "string" ? value : raw;
+}
+/**
+* Split an inline array's interior on commas that are not inside a quoted
+* item — `["a, b", c]` is two items, not three. Exported for the same reason
+* as {@link parseFrontmatterScalar}: both readers must split it the same way.
+*/
+function splitFrontmatterList(inner) {
+	const items = [];
+	let current = "";
+	let quote;
+	for (let i = 0; i < inner.length; i += 1) {
+		const char = inner[i];
+		if (quote) {
+			if (char === "\\" && quote === "\"" && i + 1 < inner.length) {
+				current += char + inner[i + 1];
+				i += 1;
+				continue;
+			}
+			current += char;
+			if (char === quote) quote = void 0;
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			quote = char;
+			current += char;
+			continue;
+		}
+		if (char === ",") {
+			items.push(current);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	items.push(current);
+	return items;
+}
 function yamlScalar(value) {
 	const str = String(value);
-	if (str.includes(":") || str.includes("#") || str.includes("{") || str.includes("}") || str.includes("[") || str.includes("]") || str.includes("*") || str.includes("&") || str.includes("!") || str.includes("|") || str.includes(">") || str.includes("'") || str.includes("\"") || str.includes("%") || str.includes("@") || str.includes("`") || str.startsWith("-") || str.startsWith("?") || str === "true" || str === "false" || str === "null" || str === "yes" || str === "no" || str === "") return `"${str.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+	if (str.includes(":") || str.includes("#") || str.includes("{") || str.includes("}") || str.includes("[") || str.includes("]") || str.includes("*") || str.includes("&") || str.includes("!") || str.includes("|") || str.includes(">") || str.includes("'") || str.includes("\"") || str.includes("%") || str.includes("@") || str.includes("`") || str.includes("\\") || str.includes("\n") || str.includes("\r") || str.includes("	") || str.startsWith("-") || str.startsWith("?") || str !== str.trim() || str === "" || typeof value === "string" && (parseFrontmatterScalar(str) !== str || str === "yes" || str === "no")) return `"${str.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}"`;
 	return str;
 }
 function serializeYamlValue(value, indent) {
@@ -714,6 +1207,10 @@ function serializeYamlFields(data) {
 			lines.push(`${key}:`);
 			lines.push(...serializeYamlValue(value, 1));
 		} else if (Array.isArray(value)) {
+			if (value.length === 0) {
+				lines.push(`${key}: []`);
+				continue;
+			}
 			lines.push(`${key}:`);
 			for (const item of value) if (typeof item === "object" && item !== null && !Array.isArray(item)) {
 				const nested = serializeYamlValue(item, 2);
@@ -741,7 +1238,7 @@ function parseMarkdownFrontmatter(content) {
 	let currentArray = null;
 	for (const line of frontmatterStr.split("\n")) {
 		if (/^\s+-\s+/.test(line) && currentKey) {
-			const value = line.replace(/^\s+-\s+/, "").trim();
+			const value = parseFrontmatterScalarString(line.replace(/^\s+-\s+/, "").trim());
 			if (!currentArray) currentArray = [];
 			currentArray.push(value);
 			continue;
@@ -761,10 +1258,11 @@ function parseMarkdownFrontmatter(content) {
 			continue;
 		}
 		if (rawValue.startsWith("[") && rawValue.endsWith("]")) {
-			frontmatter[key] = rawValue.slice(1, -1).split(",").map((s) => s.trim()).filter(Boolean);
+			const inner = rawValue.slice(1, -1).trim();
+			frontmatter[key] = inner === "" ? [] : splitFrontmatterList(inner).map((item) => parseFrontmatterScalarString(item.trim()));
 			continue;
 		}
-		frontmatter[key] = parseYamlValue(rawValue);
+		frontmatter[key] = parseFrontmatterScalar(rawValue);
 	}
 	if (currentKey && currentArray) frontmatter[currentKey] = currentArray;
 	return {
@@ -810,6 +1308,6 @@ function serializeMarkdownFrontmatter(data, body) {
 	return lines.join("\n");
 }
 //#endregion
-export { CANONICAL_JSON, CAPABILITY_KEYS, CHROME_BODY_SLOT, CHROME_COMPONENT_CLOSE, CHROME_COMPONENT_OPEN, CHROME_IF_CLOSE, CHROME_IF_OPEN, CHROME_REPEAT_CLOSE, CHROME_REPEAT_OPEN, COMMENTS_EXPORT_FORMAT, COMPONENT_TYPES, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, DICTIONARY_TITLE_FIELD, ENTRY_ID_PATTERN, LEGACY_CSS_LAYER, LIST_ITEMS_SLOT, LOCALE_PATTERN, LOCAL_CAPABILITIES, MIGRATION_CONTRACT_VERSION, MODEL_EXTENSION_KEYS, MODEL_FIELD_ORDER, PATH_PATTERNS, RAW_MARK_SUFFIX, SECRET_PATTERNS, SLUG_PATTERN, SOURCE_ACCESS_LADDER, TITLE_FIELD_TYPES, canonicalStringify, componentSlot, conflictId, detectSecrets, generateEntryId, isMediaType, isTitleFieldType, looksLikeCredential, orderedFieldNames, parseMarkdownFrontmatter, resolveFieldLabel, serializeMarkdownFrontmatter, sortKeys, stableHash, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateSemanticType, validateSlug };
+export { APPROVAL_GATES, APPROVAL_MODES, CANONICAL_JSON, CAPABILITY_KEYS, CHROME_BODY_SLOT, CHROME_COMPONENT_CLOSE, CHROME_COMPONENT_OPEN, CHROME_IF_CLOSE, CHROME_IF_OPEN, CHROME_REPEAT_CLOSE, CHROME_REPEAT_OPEN, COMMENTS_EXPORT_FORMAT, COMPONENT_TYPES, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, DEFAULT_APPROVAL_POLICY, DICTIONARY_TITLE_FIELD, ENTRY_ID_PATTERN, EXECUTION_CONTRACT_VERSION, LEGACY_CSS_LAYER, LIST_ITEMS_SLOT, LOCALE_PATTERN, LOCAL_CAPABILITIES, MIGRATION_CONTRACT_VERSION, MODEL_EXTENSION_KEYS, MODEL_FIELD_ORDER, PATH_PATTERNS, RAW_MARK_SUFFIX, RESERVED_PATHS, RISK_CLASSES, RUN_STATUSES, SCHEDULE_KINDS, SECRET_PATTERNS, SLUG_PATTERN, SOURCE_ACCESS_LADDER, SOURCE_DELTA_OPS, TERMINAL_RUN_STATUSES, TITLE_FIELD_TYPES, approversFor, canonicalStringify, componentSlot, computePlanHash, conflictId, detectSecrets, effectiveRisk, evaluateApproval, generateEntryId, highestRisk, isMediaType, isReservedPath, isTerminalRunStatus, isTitleFieldType, looksLikeCredential, orderedFieldNames, parseFrontmatterScalar, parseFrontmatterScalarString, parseMarkdownFrontmatter, planHashPayload, requiredApprovals, resolveFieldLabel, riskRank, serializeMarkdownFrontmatter, sortKeys, splitFrontmatterList, stableHash, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateSemanticType, validateSlug };
 
 //# sourceMappingURL=index.mjs.map