@contentrain/types 1.13.1 → 1.15.0

package/dist/index.d.mts

@@ -1,3 +1,9 @@
+//#region src/canonical.d.ts
+/** Recursively sort object keys — respects optional fieldOrder for top-level keys */
+declare function sortKeys(obj: unknown, fieldOrder?: readonly string[]): unknown;
+/** Canonical JSON serialization — deterministic output for stable git diffs */
+declare function canonicalStringify(data: unknown, fieldOrder?: readonly string[]): string;
+//#endregion
 //#region src/migration.d.ts
 /**
  * Version stamped into every migration document (`version` field on each root).
@@ -263,8 +269,30 @@ interface CapabilityManifest {
   site_url: string;
   access: {
     html_status?: number | null;
-    rest_status?: number | null; /** Highest source-access rung actually achieved for this site. */
-    achieved: SourceAccessKind;
+    rest_status?: number | null;
+    /**
+     * Highest source-access rung actually achieved for this site, or `null`
+     * when none was — the site answered nothing a rung describes.
+     *
+     * Nullable rather than optional, and rather than a `'none'` rung. Optional
+     * would let a producer omit the field and call that "not measured", which
+     * is the failure this field exists to prevent: a manifest that reports
+     * `rest_public` for every site makes the access ladder unreadable, and the
+     * ladder is what the coverage figures are computed from. Required-and-
+     * nullable makes "I reached nothing" a thing the producer has to say.
+     *
+     * A `'none'` rung was the other candidate and is worse: `SourceAccessKind`
+     * is also `RawProvenance.kind`, where it answers "how was this data
+     * obtained". A RawIR stamped `kind: 'none'` is a document that exists
+     * without having been obtained — an impossible state made representable in
+     * an unrelated contract. `SOURCE_ACCESS_LADDER` would stop being a ladder
+     * too: it is an ordered array and coverage arithmetic indexes into it.
+     *
+     * `null` reads with `rest_status: null` beside it as its evidence. Coverage
+     * arithmetic should drop these sites from the numerator, not score them
+     * zero — a site behind an access wall was not measured, it did not fail.
+     */
+    achieved: SourceAccessKind | null;
   };
   generator?: string | null;
   theme?: string | null;
@@ -740,6 +768,599 @@ interface MigrationHandoff {
   notes?: string[];
 }
 //#endregion
+//#region src/execution.d.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.
+ */
+declare const EXECUTION_CONTRACT_VERSION = 1;
+/**
+ * Who is acting. `kind` is load-bearing for approval: an agent may never
+ * approve its own work, so the evaluator has to be able to tell an agent
+ * from a person without consulting Studio's user table.
+ */
+interface ActorRef {
+  kind: 'human' | 'agent' | 'system';
+  /** Stable identifier in the issuing system (Studio user id, agent name). */
+  id: string;
+  /** Display name at the time of acting; advisory, never matched against. */
+  name?: string;
+  /** Project role held at the time of acting (e.g. "owner", "admin", "editor"). */
+  role?: string;
+}
+/**
+ * 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.
+ */
+declare const RISK_CLASSES: readonly ["read_only", "low_risk_content", "bulk_content", "destructive_schema", "external_effect", "financially_material", "deployment"];
+type RiskClass = (typeof RISK_CLASSES)[number];
+/** Position on the ladder; higher is more severe. */
+declare function riskRank(risk: RiskClass): number;
+/**
+ * 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.
+ */
+declare function highestRisk(risks: readonly RiskClass[]): RiskClass;
+/**
+ * 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.
+ */
+declare const APPROVAL_GATES: readonly ["plan", "change", "release"];
+type ApprovalGate = (typeof APPROVAL_GATES)[number];
+/**
+ * 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.
+ */
+declare const APPROVAL_MODES: readonly ["auto", "single", "quorum"];
+type ApprovalMode = (typeof APPROVAL_MODES)[number];
+/**
+ * One rule in `.contentrain/approval-policies.json`: for operations at or
+ * above `risk`, this gate is required in this mode.
+ *
+ * Rules are additive. Every matching rule contributes a requirement; nothing a
+ * rule says can remove a requirement another rule created. A policy file can
+ * therefore only ever make a project stricter, which is what makes it safe to
+ * merge one from a template.
+ */
+interface ApprovalRule {
+  /** Applies to this class and — because the classes are a ladder — everything above it. */
+  risk: RiskClass;
+  gate: ApprovalGate;
+  mode: ApprovalMode;
+  /** Quorum only: how many distinct approvers are needed. Ignored otherwise. */
+  min_approvals?: number;
+  /** Roles that may satisfy this rule. Empty/absent = any authorised reviewer. */
+  roles?: string[];
+  /** Narrow the rule to certain models. Absent = every model. */
+  models?: string[];
+  /** Narrow the rule to certain locales. Absent = every locale. */
+  locales?: string[];
+}
+/**
+ * `.contentrain/approval-policies.json`. Lives in git, beside the content it
+ * governs, so that the policy in force is the policy on the branch — a policy
+ * stored only in a database can be changed after a plan is built and before it
+ * is approved.
+ */
+interface ApprovalPolicyFile {
+  version: number;
+  /**
+   * Applied at the `change` gate when no rule matches at all. Absent means no
+   * rule matched and therefore nothing is required — the policy's silence is
+   * taken literally rather than filled in with each consumer's idea of a
+   * sensible default.
+   */
+  default_mode?: ApprovalMode;
+  rules: ApprovalRule[];
+  /**
+   * Whether an actor may approve a plan they themselves created. Defaults to
+   * false; an agent can never self-approve regardless of this setting.
+   */
+  allow_self_approval?: boolean;
+}
+/**
+ * An outstanding or satisfied demand for a decision, derived from a rule.
+ * `because` carries the rule's risk class so a UI can say *why* a gate
+ * appeared without re-running the policy.
+ */
+interface ApprovalRequirement {
+  gate: ApprovalGate;
+  mode: ApprovalMode;
+  /** Distinct approvers still needed; 0 once satisfied. */
+  min_approvals: number;
+  roles?: string[];
+  /** The risk class of the rule that produced this requirement. */
+  because: RiskClass;
+}
+/**
+ * A decision that was actually given.
+ *
+ * A grant is bound to an exact `plan_hash`: if the plan changes, its grants no
+ * longer apply and the gate reopens. That binding is the whole point — an
+ * approval of "publish these 12 posts" must not carry over to a plan that
+ * publishes 400.
+ */
+interface ApprovalGrant {
+  gate: ApprovalGate;
+  /** The plan this decision was given for. */
+  plan_hash: string;
+  /** The branch tip reviewed, for `change` grants on a produced diff. */
+  commit_sha?: string;
+  approver: ActorRef;
+  /** ISO 8601 UTC. */
+  approved_at: string;
+  /** ISO 8601 UTC; a grant past this instant does not count. */
+  expires_at?: string;
+  note?: string;
+}
+/**
+ * What an operation touches. Used twice with the same shape: on a plan it is
+ * the prediction, on a receipt it is what actually happened. Keeping one shape
+ * for both is deliberate — the diff between them is the most useful thing a
+ * receipt can show, and it is only computable if the two are comparable.
+ *
+ * Every field is optional and an absent field means "none", not "unknown": a
+ * plan that cannot enumerate what it will touch is not a plan that should be
+ * approved.
+ */
+interface ExecutionScope {
+  models?: string[];
+  locales?: string[];
+  /** Entry ids, or `model:id` where the model is not implied by `models`. */
+  entries?: string[];
+  /** Routes/URLs affected — cutovers and redirect rewrites report these. */
+  routes?: string[];
+  /** Repository-relative file paths. */
+  files?: string[];
+  /** Asset ids or paths. */
+  assets?: string[];
+  /** Provider identifiers reached (deployment, email, CRM). */
+  providers?: string[];
+  /** Hosts contacted outside the project — the evidence behind `external_effect`. */
+  external_domains?: string[];
+}
+/** One tool invocation inside a plan. */
+interface ExecutionStep {
+  id: string;
+  /** Tool name as the runner knows it (e.g. "contentrain_bulk"). */
+  tool: string;
+  /** One line, written for the person approving, not for the log. */
+  summary: string;
+  risk: RiskClass;
+  /** What this step alone touches; the plan's scope is the union. */
+  scope?: ExecutionScope;
+  /** Opaque tool arguments. Hashed with the rest of the plan. */
+  input?: Record<string, unknown>;
+}
+/**
+ * Predicted cost. Currency is ISO 4217; absent means the cost is not monetary.
+ *
+ * The non-monetary fields exist because cost is metered before it is priced:
+ * a run's bill is assembled from tokens, compute time, bytes stored and bytes
+ * transferred, and those are what a runner can actually measure at the moment
+ * it finishes a step. `cost` is the conversion, and it is often computed later
+ * from these.
+ */
+interface ExecutionEstimate {
+  currency?: string;
+  /** Money, in major units. */
+  cost?: number;
+  /** Model tokens, when the step runs an agent. */
+  tokens?: number;
+  duration_ms?: number;
+  /**
+   * Items the operation expects to write — entries, files, assets. A count,
+   * not a size: use `bytes_stored` for how much was written.
+   */
+  items?: number;
+  /**
+   * Bytes the operation leaves at rest — a built artefact, an uploaded asset.
+   * Object storage bills for this per unit time, so it is the field a storage
+   * line on an invoice traces back to.
+   */
+  bytes_stored?: number;
+  /**
+   * Bytes the operation moves across the network — egress, and fetches made on
+   * the way. Billed separately from storage and by a different rate, which is
+   * why it is a separate field rather than one `bytes`: a run that stores 40 MB
+   * once and serves it a thousand times has one storage figure and a very
+   * different transfer figure.
+   */
+  bytes_out?: number;
+}
+/** Cost as measured. Same shape as the estimate so the two can be subtracted. */
+type ExecutionCost = ExecutionEstimate;
+/**
+ * How to undo the operation. A command, not a promise: if the runner cannot
+ * state the undo, `available` is false and the approver learns that *before*
+ * deciding rather than after failing.
+ */
+interface RollbackPlan {
+  available: boolean;
+  /** Shell command or tool call that reverses the effect. */
+  command?: string;
+  /** Commit to reset the content branch to. */
+  revert_to?: string;
+  /** Why it cannot be undone, when `available` is false. */
+  reason?: string;
+}
+/** The repository state a plan was built against. */
+interface ProjectRef {
+  branch?: string;
+  commit_sha?: string;
+  /** Content branch tip, when it differs from the base branch. */
+  content_commit_sha?: string;
+}
+/**
+ * An operation, fully described, before it runs.
+ *
+ * `plan_hash` is the identity of *what will happen*. It covers the steps,
+ * scope, risk, estimate and rollback, and excludes who built the plan and
+ * when — regenerating the same operation must produce the same hash, or
+ * idempotency and approval binding both break. Compute it with
+ * {@link computePlanHash}; never hand-roll it, because a hash computed two
+ * different ways is a gate that silently opens.
+ */
+interface ExecutionPlan {
+  version: number;
+  id: string;
+  /** SHA-256 of the plan's semantic payload — see {@link computePlanHash}. */
+  plan_hash: string;
+  /** What this achieves, in the requester's words. */
+  intent: string;
+  /** The plan's class: the highest risk among its steps. */
+  risk: RiskClass;
+  steps: ExecutionStep[];
+  /** Union of the steps' scopes, stated once so an approver reads one list. */
+  scope: ExecutionScope;
+  estimate?: ExecutionEstimate;
+  rollback?: RollbackPlan;
+  /** Repository state the plan assumes; re-checked at execution time. */
+  project?: ProjectRef;
+  /** ISO 8601 UTC. Excluded from the hash. */
+  created_at?: string;
+  /** Excluded from the hash, but checked for self-approval. */
+  created_by?: ActorRef;
+  /** ISO 8601 UTC; a plan past this instant must be rebuilt, not run. */
+  expires_at?: string;
+  /**
+   * Caller-supplied key that makes a re-submission a no-op rather than a
+   * second run. Excluded from the hash: two runs of the same work differ by
+   * this key alone and must still share a plan hash.
+   */
+  idempotency_key?: string;
+}
+/**
+ * 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.
+ */
+declare const RUN_STATUSES: readonly ["draft", "planned", "awaiting_approval", "approved", "scheduled", "queued", "running", "verifying", "completed", "paused", "needs_attention", "retrying", "failed", "cancelled", "expired", "rolled_back"];
+type RunStatus = (typeof RUN_STATUSES)[number];
+/** Statuses from which a run will not proceed on its own. */
+declare const TERMINAL_RUN_STATUSES: readonly ["completed", "failed", "cancelled", "expired", "rolled_back"];
+declare function isTerminalRunStatus(status: RunStatus): boolean;
+/**
+ * A step boundary the runner survived. Checkpoints are what make a resumed
+ * run skip work it already did instead of repeating it.
+ */
+interface Checkpoint {
+  step_id: string;
+  status: 'completed' | 'skipped' | 'failed';
+  /** ISO 8601 UTC. */
+  at: string;
+  /** What this step actually touched. */
+  scope?: ExecutionScope;
+  /** Commit written by this step, when it wrote one. */
+  commit_sha?: string;
+  message?: string;
+}
+/** One post-run assertion — a build, a link check, a parity score. */
+interface VerificationCheck {
+  id: string;
+  /** One line naming what was asserted. */
+  name: string;
+  passed: boolean;
+  /** Measured value, when the check produced one. */
+  value?: number | string;
+  /** Threshold the value was compared against. */
+  expected?: number | string;
+  detail?: string;
+}
+/**
+ * What happened, after the fact. The receipt is the durable record: it
+ * survives the run, is exported for audit, and is the only artefact that can
+ * answer "who allowed this and what did it actually change?".
+ *
+ * Release approvers are the entries of `approvals` whose `gate` is `release`
+ * — there is deliberately no separate `release_approved_by` field, because two
+ * places recording the same fact is two places that can disagree. Read them
+ * with {@link approversFor}.
+ */
+interface ExecutionReceipt {
+  version: number;
+  id: string;
+  plan_id: string;
+  /** The plan that ran. Must match the approvals' `plan_hash`. */
+  plan_hash: string;
+  status: RunStatus;
+  actor: ActorRef;
+  /** Every decision that permitted this run, plan/change/release alike. */
+  approvals?: ApprovalGrant[];
+  /** ISO 8601 UTC. */
+  started_at: string;
+  finished_at?: string;
+  /** What was actually touched — compare against the plan's `scope`. */
+  applied: ExecutionScope;
+  checkpoints?: Checkpoint[];
+  verification?: VerificationCheck[];
+  /** Measured cost — compare against the plan's `estimate`. */
+  cost?: ExecutionCost;
+  /** The undo, as it stands now that the run has happened. */
+  rollback?: RollbackPlan;
+  /** Repository state the run left behind. */
+  project?: ProjectRef;
+  /** Set when `status` is `failed` or `needs_attention`. */
+  error?: {
+    code: string;
+    message: string;
+    step_id?: string;
+  };
+}
+/** Approvers recorded on a receipt for one gate, in grant order. */
+declare function approversFor(receipt: ExecutionReceipt, gate: ApprovalGate): ActorRef[];
+/**
+ * Where a build is published. Carries a *reference* to a secret, never a
+ * secret: this document is written to git, and a token in git is a token
+ * leaked. The reference is resolved at execution time by whoever holds the
+ * vault.
+ */
+interface DeploymentTarget {
+  id: string;
+  /** Provider identity (e.g. "netlify", "vercel", "cloudflare-pages"). */
+  provider: string;
+  /** Provider-side site/project identifier. */
+  site_id?: string;
+  branch?: string;
+  /** Key naming the credential in the executing side's secret store. */
+  secret_ref?: string;
+  /** Non-secret provider settings. */
+  config?: Record<string, string>;
+}
+declare const SCHEDULE_KINDS: readonly ["once", "recurring", "content_event", "git_event", "runtime_event", "external_webhook", "manual"];
+type ScheduleKind = (typeof SCHEDULE_KINDS)[number];
+/** What to do with an occurrence that was missed while the runner was down. */
+type MisfirePolicy = 'skip' | 'run_once' | 'run_all';
+interface AutomationSchedule {
+  kind: ScheduleKind;
+  /** ISO 8601 UTC, for `once`. */
+  at?: string;
+  /** Cron expression, for `recurring`. */
+  cron?: string;
+  /** IANA zone (e.g. "Europe/Istanbul"); cron without one is ambiguous twice a year. */
+  timezone?: string;
+  /** Event name, for the event kinds. */
+  event?: string;
+  misfire?: MisfirePolicy;
+}
+interface AutomationDefinition {
+  version: number;
+  id: string;
+  name: string;
+  enabled: boolean;
+  schedule: AutomationSchedule;
+  /** What the run should do, in the requester's words. */
+  intent: string;
+  /** Risk the automation declares; the policy is re-evaluated at fire time. */
+  risk?: RiskClass;
+  /** Budget ceiling per occurrence. */
+  budget?: ExecutionEstimate;
+  /** Deduplication key for the occurrence. */
+  idempotency_key?: string;
+  /** Bounded retry; absent means no retry. */
+  max_retries?: number;
+}
+/** The origin state a delta is measured from. */
+interface SourceCursor {
+  kind: 'rest_modified_after' | 'wxr_export' | 'bridge_inventory';
+  /** ISO 8601 UTC, for `rest_modified_after`. */
+  modified_after?: string;
+  /** Export identifier, for `wxr_export`. */
+  export_id?: string;
+  /** Inventory hash, for `bridge_inventory` — the only kind that can prove deletions. */
+  inventory_hash?: string;
+  /** ISO 8601 UTC time the cursor was taken (T0). */
+  taken_at: string;
+}
+declare const SOURCE_DELTA_OPS: readonly ["created", "updated", "deleted", "moved"];
+type SourceDeltaOp = (typeof SOURCE_DELTA_OPS)[number];
+/**
+ * One record's delta.
+ *
+ * `conflict` is the case that cannot be resolved mechanically: the same record
+ * changed at the origin *and* in the repository since the cursor. Taking
+ * either side silently loses an edit, so the plan reports it and a human
+ * decides.
+ */
+interface SourceDeltaEntry {
+  op: SourceDeltaOp;
+  /** Origin identifier (WordPress post/term/attachment id). */
+  wp_id: number;
+  /** Origin object type (e.g. "post", "page", "attachment", "category"). */
+  wp_type?: string;
+  /** Where it lives in the store, when it is already mapped. */
+  model?: string;
+  entry_id?: string;
+  locale?: string;
+  /** Origin content fingerprint at cursor time and now. */
+  fingerprint_before?: string;
+  fingerprint_after?: string;
+  /** For `moved`: the slugs, in that order. Redirects are generated from these. */
+  slug_before?: string;
+  slug_after?: string;
+  /** True when the repository also changed this record since the cursor. */
+  conflict?: boolean;
+  /** Why this entry is here, for the person reading the plan. */
+  detail?: string;
+}
+/**
+ * A one-way transfer plan from the WordPress origin to the repository.
+ *
+ * Not a sync: there is no path back. The plan is produced, written, and only
+ * then does `contentrain_reconcile` merge the result on the git side.
+ */
+interface SourceDeltaPlan {
+  version: number;
+  /** ISO 8601 UTC. */
+  generated_at: string;
+  /** Origin state this delta is measured from. */
+  cursor: SourceCursor;
+  /** Origin state this delta brings the repository up to. */
+  next_cursor?: SourceCursor;
+  entries: SourceDeltaEntry[];
+  /**
+   * Whether deletions could be determined at all. A `rest_modified_after`
+   * cursor cannot see them; a plan that says `false` must not be read as
+   * "nothing was deleted".
+   */
+  deletions_detectable: boolean;
+  /** Redirects implied by the `moved` entries. */
+  redirects?: {
+    from: string;
+    to: string;
+    status: 301 | 302 | 307 | 308;
+  }[];
+  /** Human-facing notes: truncation, skipped types, coverage limits. */
+  warnings?: string[];
+}
+/**
+ * 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.
+ */
+declare function planHashPayload(plan: ExecutionPlan): string;
+/**
+ * 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.
+ */
+declare function computePlanHash(plan: ExecutionPlan): Promise<string>;
+//#endregion
+//#region src/approval.d.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.
+ */
+declare const DEFAULT_APPROVAL_POLICY: ApprovalPolicyFile;
+/**
+ * Why a grant did not count. Machine-readable because the useful question is
+ * never "is it blocked" but "I approved this, why is it still blocked".
+ */
+type GrantRejection = /** Given for a different plan — the plan changed after the decision. */'plan_hash_mismatch' /** A `change` grant reviewed a different branch tip than the one presented. */ | 'commit_mismatch' /** Past its `expires_at`. */ | 'expired' /** An agent cannot approve. */ | 'agent_approver' /** The approver authored the plan and the policy forbids self-approval. */ | 'self_approval' /** The approver's role is not one the rule accepts. */ | 'role_not_permitted' /** This approver already counted toward the requirement. */ | 'duplicate_approver' /** No requirement at this gate — nothing for the grant to satisfy. */ | 'no_matching_requirement';
+interface RejectedGrant {
+  grant: ApprovalGrant;
+  reason: GrantRejection;
+}
+/** A requirement plus the decisions that have accumulated against it. */
+interface ApprovalStatus extends ApprovalRequirement {
+  /** Distinct approvers counted so far, in grant order. */
+  approvers: ActorRef[];
+  /** Still needed; 0 means satisfied. */
+  remaining: number;
+}
+interface ApprovalDecision {
+  /** Every requirement is satisfied and the plan has not expired. */
+  allowed: boolean;
+  /** The class the plan was evaluated at — its own, or its worst step's. */
+  risk: RiskClass;
+  /** Every requirement the policy produced, satisfied or not. */
+  requirements: ApprovalStatus[];
+  /** The subset still needing approvers, in gate order. */
+  outstanding: ApprovalStatus[];
+  /** Decisions that were supplied but did not count, each with a reason. */
+  rejected_grants: RejectedGrant[];
+  /** One line per reason the plan cannot proceed; empty when it can. */
+  reasons: string[];
+}
+interface ApprovalEvaluation {
+  plan: ExecutionPlan;
+  /** Absent falls back to {@link DEFAULT_APPROVAL_POLICY}. */
+  policy?: ApprovalPolicyFile;
+  /** Decisions collected so far. */
+  grants?: readonly ApprovalGrant[];
+  /**
+   * The branch tip being presented for a `change` decision. When given, a
+   * `change` grant must name this commit: a review of an older tip is not a
+   * review of what is about to merge. When absent, `change` grants are matched
+   * on `plan_hash` alone.
+   */
+  commit_sha?: string;
+  /** ISO 8601 UTC. Passed in, never read from the clock. */
+  now?: string;
+}
+/**
+ * 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.
+ */
+declare function effectiveRisk(plan: ExecutionPlan): RiskClass;
+/**
+ * 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.
+ */
+declare function requiredApprovals(plan: ExecutionPlan, policy?: ApprovalPolicyFile): ApprovalRequirement[];
+/**
+ * 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.
+ */
+declare function evaluateApproval(input: ApprovalEvaluation): ApprovalDecision;
+//#endregion
 //#region src/provider.d.ts
 /**
  * A single file change within a plan.
@@ -1421,7 +2042,11 @@ declare const PATH_PATTERNS: {
   readonly config: ".contentrain/config.json";
   readonly context: ".contentrain/context.json";
   readonly vocabulary: ".contentrain/vocabulary.json";
-  readonly model: ".contentrain/models/{modelId}.json";
+  readonly model: ".contentrain/models/{modelId}.json"; /** Detected source capabilities and the provider chosen for each — `CapabilityManifest`. */
+  readonly capabilities: ".contentrain/capabilities.json"; /** Scheduled and event-driven agent work — `AutomationDefinition[]`. */
+  readonly automations: ".contentrain/automations.json"; /** Which operations need whose approval — `ApprovalPolicyFile`. */
+  readonly approvalPolicies: ".contentrain/approval-policies.json"; /** Source→destination URL map, the output of a migration's `moved` entries. */
+  readonly redirects: ".contentrain/redirects.json";
   readonly content: {
     readonly singleton: ".contentrain/content/{domain}/{modelId}/{locale}.json";
     readonly collection: ".contentrain/content/{domain}/{modelId}/{locale}.json";
@@ -1437,6 +2062,30 @@ declare const PATH_PATTERNS: {
     readonly 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.
+ */
+declare const RESERVED_PATHS: readonly [".contentrain/capabilities.json", ".contentrain/automations.json", ".contentrain/approval-policies.json", ".contentrain/redirects.json"];
+declare function isReservedPath(path: string): boolean;
 /** Slug: lowercase alphanumeric with hyphens */
 declare const SLUG_PATTERN: RegExp;
 /** Entry ID: alphanumeric, 1-40 chars, starts with alphanumeric */
@@ -1734,10 +2383,6 @@ declare function validateAccept(value: string, accept: string): ValidationError[
  * or `maxSize` — byte length is not knowable from a stored path.
  */
 declare function validateFieldValue(value: unknown, fieldDef: FieldDef): ValidationError[];
-/** Recursively sort object keys — respects optional fieldOrder for top-level keys */
-declare function sortKeys(obj: unknown, fieldOrder?: readonly string[]): unknown;
-/** Canonical JSON serialization — deterministic output for stable git diffs */
-declare function canonicalStringify(data: unknown, fieldOrder?: readonly string[]): string;
 /** Generate a 12-character hex entry ID */
 declare function generateEntryId(): string;
 /**
@@ -1766,6 +2411,31 @@ declare function conflictId(conflict: {
   ours?: unknown;
   theirs?: unknown;
 }): string;
+/**
+ * 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.
+ */
+declare function parseFrontmatterScalar(raw: string): unknown;
+/**
+ * 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.
+ */
+declare function parseFrontmatterScalarString(raw: string): string;
+/**
+ * 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.
+ */
+declare function splitFrontmatterList(inner: string): string[];
 /** Parse markdown frontmatter — extracts YAML frontmatter and body from a markdown string */
 declare function parseMarkdownFrontmatter(content: string): {
   frontmatter: Record<string, unknown>;
@@ -1774,5 +2444,5 @@ declare function parseMarkdownFrontmatter(content: string): {
 /** Serialize data + body into markdown frontmatter format */
 declare function serializeMarkdownFrontmatter(data: Record<string, unknown>, body: string): string;
 //#endregion
-export { type ApplyPlanInput, AssetEntry, type BaseAdvance, type Branch, 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, CapabilityDetection, CapabilityDisposition, CapabilityKey, CapabilityManifest, ChromeChunk, CollectionContentFile, CollectionContentOutput, CollectionEntry, CollectionMeta, CollectionRuntimeFormat, CommentsExport, type Commit, type CommitAuthor, ComponentDef, ComponentPlacement, ComponentSource, ComponentType, ComponentVariantDef, type ConflictCode, type ConflictItem, type ConflictResolution, ContentSource, ContentStatus, ContentrainConfig, ContentrainError, ContextJson, ContextSource, CostComparison, CostEstimate, CssStrategy, DICTIONARY_TITLE_FIELD, DesignTokens, DictionaryContentFile, DictionaryMeta, DocumentContentOutput, DocumentEntry, DocumentMeta, DuplicateGroup, ENTRY_ID_PATTERN, EntryMeta, EntrySourceMap, EntrySourceRef, ExcerptSource, FamilyVariant, FieldDef, FieldType, FileCategory, type FileChange, type FileDiff, FileFramework, GraphNode, HandoffCapability, HandoffComments, HandoffOffer, LEGACY_CSS_LAYER, LIST_ITEMS_SLOT, LOCALE_PATTERN, LOCAL_CAPABILITIES, LayoutFamily, LocaleStrategy, MIGRATION_CONTRACT_VERSION, MODEL_EXTENSION_KEYS, MODEL_FIELD_ORDER, type MediaAsset, type MediaIngestInput, type MediaListOptions, type MediaListResult, type MediaProvider, type MediaUpdateInput, type MergeResult, MigrationHandoff, ModelDefinition, ModelKind, ModelSummary, NormalizePlan, NormalizePlanExtraction, NormalizePlanModel, NormalizePlanPatch, OfferProvider, PATH_PATTERNS, PaginationKind, Platform, PolymorphicRelationRef, ProjectGraph, ProjectIR, type ProviderCapabilities, QueryBinding, RAW_MARK_SUFFIX, RawAcfValue, RawAttachment, RawAuthor, RawComment, RawIR, RawLanguagePair, RawMenu, RawMenuItem, RawMenuTarget, RawPost, RawProvenance, RawRedirect, RawSite, RawTerm, RawTermRef, type RemotePush, type RepoProvider, type RepoReader, type RepoWriter, RootAttrs, RouteKind, RouteModel, RouteParamDef, RouteVariantRule, RuntimeBinding, SECRET_PATTERNS, SLUG_PATTERN, SOURCE_ACCESS_LADDER, ScaffoldTemplate, ScanCandidate, ScanCandidatesResult, ScanSummaryResult, SingletonContentFile, SingletonMeta, SlotBinding, SlotKind, SourceAccessKind, StackType, StringContext, SyncResult, TITLE_FIELD_TYPES, ValidationError, ValidationResult, ViewportStrategy, Vocabulary, WorkflowMode, type WriteReadiness, 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, ActorRef, type ApplyPlanInput, ApprovalDecision, ApprovalEvaluation, ApprovalGate, ApprovalGrant, ApprovalMode, ApprovalPolicyFile, ApprovalRequirement, ApprovalRule, ApprovalStatus, AssetEntry, AutomationDefinition, AutomationSchedule, type BaseAdvance, type Branch, 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, CapabilityDetection, CapabilityDisposition, CapabilityKey, CapabilityManifest, Checkpoint, ChromeChunk, CollectionContentFile, CollectionContentOutput, CollectionEntry, CollectionMeta, CollectionRuntimeFormat, CommentsExport, type Commit, type CommitAuthor, ComponentDef, ComponentPlacement, ComponentSource, ComponentType, ComponentVariantDef, type ConflictCode, type ConflictItem, type ConflictResolution, ContentSource, ContentStatus, ContentrainConfig, ContentrainError, ContextJson, ContextSource, CostComparison, CostEstimate, CssStrategy, DEFAULT_APPROVAL_POLICY, DICTIONARY_TITLE_FIELD, DeploymentTarget, DesignTokens, DictionaryContentFile, DictionaryMeta, DocumentContentOutput, DocumentEntry, DocumentMeta, DuplicateGroup, ENTRY_ID_PATTERN, EXECUTION_CONTRACT_VERSION, EntryMeta, EntrySourceMap, EntrySourceRef, ExcerptSource, ExecutionCost, ExecutionEstimate, ExecutionPlan, ExecutionReceipt, ExecutionScope, ExecutionStep, FamilyVariant, FieldDef, FieldType, FileCategory, type FileChange, type FileDiff, FileFramework, GrantRejection, GraphNode, HandoffCapability, HandoffComments, HandoffOffer, LEGACY_CSS_LAYER, LIST_ITEMS_SLOT, LOCALE_PATTERN, LOCAL_CAPABILITIES, LayoutFamily, LocaleStrategy, MIGRATION_CONTRACT_VERSION, MODEL_EXTENSION_KEYS, MODEL_FIELD_ORDER, type MediaAsset, type MediaIngestInput, type MediaListOptions, type MediaListResult, type MediaProvider, type MediaUpdateInput, type MergeResult, MigrationHandoff, MisfirePolicy, ModelDefinition, ModelKind, ModelSummary, NormalizePlan, NormalizePlanExtraction, NormalizePlanModel, NormalizePlanPatch, OfferProvider, PATH_PATTERNS, PaginationKind, Platform, PolymorphicRelationRef, ProjectGraph, ProjectIR, ProjectRef, type ProviderCapabilities, QueryBinding, RAW_MARK_SUFFIX, RESERVED_PATHS, RISK_CLASSES, RUN_STATUSES, RawAcfValue, RawAttachment, RawAuthor, RawComment, RawIR, RawLanguagePair, RawMenu, RawMenuItem, RawMenuTarget, RawPost, RawProvenance, RawRedirect, RawSite, RawTerm, RawTermRef, RejectedGrant, type RemotePush, type RepoProvider, type RepoReader, type RepoWriter, RiskClass, RollbackPlan, RootAttrs, RouteKind, RouteModel, RouteParamDef, RouteVariantRule, RunStatus, RuntimeBinding, SCHEDULE_KINDS, SECRET_PATTERNS, SLUG_PATTERN, SOURCE_ACCESS_LADDER, SOURCE_DELTA_OPS, ScaffoldTemplate, ScanCandidate, ScanCandidatesResult, ScanSummaryResult, ScheduleKind, SingletonContentFile, SingletonMeta, SlotBinding, SlotKind, SourceAccessKind, SourceCursor, SourceDeltaEntry, SourceDeltaOp, SourceDeltaPlan, StackType, StringContext, SyncResult, TERMINAL_RUN_STATUSES, TITLE_FIELD_TYPES, ValidationError, ValidationResult, VerificationCheck, ViewportStrategy, Vocabulary, WorkflowMode, type WriteReadiness, 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.d.mts.map