@event4u/agent-config 16.0.0 → 16.1.0

package/src/scripts/_lib/council_transport.ts

@@ -0,0 +1,129 @@
+/**
+ * Council transport and cost — `road-to-adversarial-verification-and-long-runs`
+ * 10.1.
+ *
+ * The posture is CLI → CLI quota exhausted → API within the ceiling → API over
+ * the ceiling → **pause and report**. The last rung is the step's whole point:
+ * over the ceiling the run does not ask whether to buy more technical API usage.
+ * It reports.
+ *
+ * ```
+ * AN OVER-CEILING COUNCIL REQUIREMENT PRODUCES A REPORT, NEVER A QUESTION.
+ * TECHNICAL API SPEND IS NOT A DECISION THE OWNER IS ASKED FOR MID-RUN.
+ * BUSINESS SPEND IS A TYPED OP AND A DIFFERENT CATEGORY ENTIRELY.
+ * ```
+ *
+ * **Why a report rather than an ask, when both interrupt.** They do not
+ * interrupt the same way. An ask BLOCKS: the run stops until an answer arrives,
+ * and the thing being asked about — a few dollars of inference — is worth less
+ * than the run's remaining work. A report does not block: it says what needed the
+ * council, why the cheaper route was unavailable, what it would cost, and — the
+ * load-bearing field — **what can still proceed without it**. Most of a mission
+ * can.
+ *
+ * Pure.
+ */
+
+/** The routes, cheapest first. */
+export type Route = 'cli' | 'api' | 'paused';
+
+export interface TransportInput {
+    /** Is the CLI route configured and within quota? */
+    readonly cliAvailable: boolean;
+    /** Why the CLI is unavailable, when it is not. */
+    readonly cliUnavailableReason: string | null;
+    /** Estimated USD for the API route. */
+    readonly estimateUsd: number;
+    /** The run's remaining technical-spend ceiling in USD. */
+    readonly ceilingUsd: number;
+}
+
+export interface PauseReport {
+    readonly needed: string;
+    readonly cliUnavailableBecause: string;
+    readonly estimateUsd: number;
+    readonly ceilingUsd: number;
+    readonly missionState: string;
+    /** What the run continues with meanwhile. Empty is a real, reportable answer. */
+    readonly canStillProceed: readonly string[];
+}
+
+export interface TransportDecision {
+    readonly route: Route;
+    readonly reason: string;
+    /** Present only on `paused`. */
+    readonly report: PauseReport | null;
+}
+
+export interface PauseContext {
+    readonly needed: string;
+    readonly missionState: string;
+    readonly canStillProceed: readonly string[];
+}
+
+/**
+ * Route one council requirement.
+ *
+ * A ceiling of zero pauses rather than dividing by it, and an estimate exactly
+ * AT the ceiling is within it — the ceiling is a limit, not an exclusive bound,
+ * and reading it the other way would pause a run that had budgeted exactly.
+ */
+export function routeCouncil(input: TransportInput, ctx: PauseContext): TransportDecision {
+    if (input.cliAvailable) {
+        return { route: 'cli', reason: 'the CLI route is available and within quota', report: null };
+    }
+    const why = input.cliUnavailableReason ?? 'unstated';
+    if (input.estimateUsd <= input.ceilingUsd) {
+        return {
+            route: 'api',
+            reason: `CLI unavailable (${why}); the API estimate $${input.estimateUsd.toFixed(2)} is within the $${input.ceilingUsd.toFixed(2)} ceiling`,
+            report: null,
+        };
+    }
+    return {
+        route: 'paused',
+        reason: `the API estimate $${input.estimateUsd.toFixed(2)} exceeds the $${input.ceilingUsd.toFixed(2)} ceiling`,
+        report: {
+            needed: ctx.needed,
+            cliUnavailableBecause: why,
+            estimateUsd: input.estimateUsd,
+            ceilingUsd: input.ceilingUsd,
+            missionState: ctx.missionState,
+            canStillProceed: ctx.canStillProceed,
+        },
+    };
+}
+
+/** The six fields a pause report must carry. */
+export const REPORT_FIELDS: readonly (keyof PauseReport)[] = [
+    'needed',
+    'cliUnavailableBecause',
+    'estimateUsd',
+    'ceilingUsd',
+    'missionState',
+    'canStillProceed',
+];
+
+/**
+ * Render the report.
+ *
+ * It ends on what can still proceed, and that placement is deliberate: a reader
+ * who stops after the cost has read a complaint, and a reader who reaches the
+ * last line has read a status. Nothing here is phrased as a question, and the
+ * renderer emits no `?` — asserted by a test, because the failure mode is a
+ * report that drifts into an ask one helpful sentence at a time.
+ */
+export function renderReport(r: PauseReport): string {
+    const proceeding =
+        r.canStillProceed.length > 0
+            ? r.canStillProceed.map((x) => `  - ${x}`).join('\n')
+            : '  - nothing; the mission is blocked on this council pass alone';
+    return [
+        `Council paused: ${r.needed}`,
+        `CLI route unavailable: ${r.cliUnavailableBecause}`,
+        `API estimate $${r.estimateUsd.toFixed(2)} over the $${r.ceilingUsd.toFixed(2)} technical ceiling`,
+        `Mission state: ${r.missionState}`,
+        'Proceeding meanwhile with:',
+        proceeding,
+    ].join('\n');
+}

package/src/scripts/_lib/delivery_ready.ts

@@ -0,0 +1,112 @@
+/**
+ * Is a PR delivery-ready? — `road-to-adversarial-verification-and-long-runs` 3.1.
+ *
+ * The step's acceptance clause is that *a fixture PR with a disabled required
+ * check cannot reach delivery-ready*, and that is the one case a naive reader
+ * gets wrong: a PR whose required context was SKIPPED has a green rollup. GitHub
+ * reports `SKIPPED` as a non-failure, so a predicate that asks "did anything
+ * fail" answers no, and the gate the context was supposed to enforce did not run.
+ *
+ * So this asks two questions rather than one: did every required context report,
+ * and did each of those reports actually pass. A context that is missing from
+ * the rollup entirely fails the first; a context present but skipped, cancelled
+ * or neutral fails the second.
+ *
+ * Pure — the caller supplies the rollup and the required set, so both polarities
+ * are testable without a forge.
+ */
+
+/** One check as a forge rollup reports it. */
+export interface CheckRun {
+    readonly name: string;
+    /** `SUCCESS` · `FAILURE` · `SKIPPED` · `CANCELLED` · `NEUTRAL` · `null` while running. */
+    readonly conclusion: string | null;
+    /** `COMPLETED` · `IN_PROGRESS` · `QUEUED`. */
+    readonly status: string;
+}
+
+/** Why a PR is not delivery-ready. Empty means it is. */
+export type DeliveryBlock =
+    | { readonly kind: 'required-context-absent'; readonly context: string }
+    | { readonly kind: 'required-context-not-passing'; readonly context: string; readonly conclusion: string }
+    | { readonly kind: 'still-running'; readonly context: string }
+    | { readonly kind: 'stale-head'; readonly observed: string; readonly head: string };
+
+/**
+ * The only conclusion that counts as a required check having done its job.
+ *
+ * `SKIPPED` is deliberately NOT here, and it is the reason this module exists:
+ * a skipped required check is an unenforced gate wearing a green rollup.
+ * `NEUTRAL` and `CANCELLED` are excluded on the same ground — a check that
+ * reached no verdict enforced nothing, whatever colour it rendered.
+ */
+const PASSING = 'SUCCESS';
+
+export interface DeliveryInput {
+    /** Contexts the forge requires, from `forge_protection`'s ruleset read. */
+    readonly requiredContexts: readonly string[];
+    /** The rollup on the head under test. */
+    readonly checks: readonly CheckRun[];
+    /** The head CI actually observed. */
+    readonly observedHead: string;
+    /** The branch head right now. */
+    readonly head: string;
+}
+
+/**
+ * Every reason this PR is not delivery-ready, in report order.
+ *
+ * Returns ALL blocks rather than the first: a run that fixes one and re-pushes
+ * to discover the next has spent a CI cycle per block, which is the cost layer 1
+ * of the delivery contract exists to avoid paying at layer 4.
+ */
+export function deliveryBlocks(input: DeliveryInput): DeliveryBlock[] {
+    const out: DeliveryBlock[] = [];
+    const byName = new Map(input.checks.map((c) => [c.name, c]));
+
+    for (const context of input.requiredContexts) {
+        const run = byName.get(context);
+        if (run === undefined) {
+            out.push({ kind: 'required-context-absent', context });
+            continue;
+        }
+        if (run.status !== 'COMPLETED') {
+            out.push({ kind: 'still-running', context });
+            continue;
+        }
+        if (run.conclusion !== PASSING) {
+            out.push({
+                kind: 'required-context-not-passing',
+                context,
+                conclusion: run.conclusion ?? 'null',
+            });
+        }
+    }
+
+    // Checked LAST and always: a green rollup on a head that is no longer the
+    // branch head is a verdict about a different tree. `ci_settle` names the head
+    // its verdict is about precisely so this comparison is possible.
+    if (input.observedHead !== input.head) {
+        out.push({ kind: 'stale-head', observed: input.observedHead, head: input.head });
+    }
+    return out;
+}
+
+/** True only when nothing blocks. */
+export function isDeliveryReady(input: DeliveryInput): boolean {
+    return deliveryBlocks(input).length === 0;
+}
+
+/** One human-readable line per block. */
+export function renderBlock(b: DeliveryBlock): string {
+    switch (b.kind) {
+        case 'required-context-absent':
+            return `required check "${b.context}" did not report at all`;
+        case 'required-context-not-passing':
+            return `required check "${b.context}" concluded ${b.conclusion}, not SUCCESS — a skipped or cancelled required check is an unenforced gate, not a pass`;
+        case 'still-running':
+            return `required check "${b.context}" has not completed`;
+        case 'stale-head':
+            return `CI was observed on ${b.observed} but the branch head is ${b.head} — the verdict describes a different tree`;
+    }
+}

package/src/scripts/_lib/forge_protection.ts

@@ -0,0 +1,267 @@
+/**
+ * The five `forge_protection` rows, read from the forge rather than guessed.
+ *
+ * `road-to-adversarial-verification-and-long-runs` Phase 3.2. ADR-268 § 3 trades
+ * the owner's confirmation for a mechanical check, and branch protection is the
+ * check it trades for — so a run that cannot say whether protection exists has
+ * not established the thing the trade depends on.
+ *
+ * **Every row carries the API call its value came from, and a row that was not
+ * read says so.** That is the whole shape: the step's word is *read, never
+ * guessed*, and the only way a reader can tell one from the other is if the
+ * provenance travels with the value. A row is `satisfied` / `unsatisfied` only
+ * when a named call produced it; otherwise it is `unread`, which is a third
+ * state and never a false.
+ *
+ * **Rulesets, not the classic branch-protection endpoint.** On this repository
+ * `repos/<owner>/<repo>/branches/main/protection` returns `404 {"message":"Branch
+ * not protected"}` while an active ruleset protects the default branch — so a
+ * checker reading the classic endpoint reports "unprotected" for a repository
+ * that is protected. The `forge-protection-settings` blocker was re-scoped for
+ * exactly this reason on 2026-09-10, and the re-scope forbids treating that 404
+ * as absence of protection. No ruleset ID is pinned: rulesets can be replaced or
+ * split, and pinning one would break on the first change.
+ *
+ * Pure. The network lives in the caller, so both polarities are testable offline.
+ */
+
+import type { BypassActor, RulesetDetail } from './platform_anchor.js';
+
+/** Whether a row was established, refuted, or never read. */
+export type RowState = 'satisfied' | 'unsatisfied' | 'unread';
+
+/** One `forge_protection` row. */
+export interface ProtectionRow {
+    /** Stable key. Rows are addressed by this, never by position. */
+    readonly id: string;
+    readonly state: RowState;
+    /**
+     * The forge API call this value came from — or would come from, when the row
+     * is `unread`. Never empty: a value whose provenance is unstated is the
+     * guess this block exists to refuse.
+     */
+    readonly source: string;
+    /** One line a human can act on when the row is not satisfied. */
+    readonly detail: string;
+}
+
+/** The five rows, in the order the blocker's own table lists them. */
+export const PROTECTION_ROW_IDS: readonly string[] = [
+    'default_branch_protected',
+    'required_checks_present',
+    'force_push_disabled',
+    'auto_merge_available',
+    'deploy_via_pipeline_only',
+] as const;
+
+/** What a caller must supply for a row to be readable. `null` = not read. */
+export interface ForgeReading {
+    /** `repos/<repo>/rulesets` + `/rulesets/<id>`, or `null` when unread. */
+    readonly rulesets: readonly RulesetDetail[] | null;
+    /** The repository's default branch, or `null` when unread. */
+    readonly defaultBranch: string | null;
+    /** `repos/<repo>` → `allow_auto_merge`, or `null` when unread. */
+    readonly allowAutoMerge: boolean | null;
+    /**
+     * `repos/<repo>/environments` → whether every environment with deployment
+     * branch policies restricts them, or `null` when unread.
+     *
+     * Deliberately a boolean the caller derives rather than a raw payload: what
+     * the row asserts is a property of the SET of environments, and handing this
+     * module the raw list would put that judgement in two places.
+     */
+    readonly deployRestricted: boolean | null;
+}
+
+const SOURCE = {
+    rulesets: 'GET repos/{owner}/{repo}/rulesets + GET .../rulesets/{id}',
+    repo: 'GET repos/{owner}/{repo} (allow_auto_merge)',
+    environments: 'GET repos/{owner}/{repo}/environments (deployment_branch_policy)',
+} as const;
+
+/** `true` when this ruleset is active and targets branches. */
+function isActiveBranchRuleset(rs: RulesetDetail): boolean {
+    return rs.enforcement === 'active' && rs.target === 'branch';
+}
+
+/** `true` when the ruleset's ref conditions reach the default branch. */
+function reachesDefaultBranch(rs: RulesetDetail, defaultBranch: string): boolean {
+    const include = rs.conditions?.ref_name?.include ?? [];
+    return include.some(
+        (p) => p === '~DEFAULT_BRANCH' || p === '~ALL' || p === `refs/heads/${defaultBranch}`,
+    );
+}
+
+function hasRule(rs: RulesetDetail, type: string): boolean {
+    return (rs.rules ?? []).some((r) => r.type === type);
+}
+
+function requiredContexts(rs: RulesetDetail): string[] {
+    for (const r of rs.rules ?? []) {
+        if (r.type !== 'required_status_checks') continue;
+        const p = r.parameters;
+        if (p === null || typeof p !== 'object') continue;
+        const list = (p as Record<string, unknown>)['required_status_checks'];
+        if (!Array.isArray(list)) continue;
+        return list
+            .map((e) =>
+                e !== null && typeof e === 'object'
+                    ? (e as Record<string, unknown>)['context']
+                    : null,
+            )
+            .filter((c): c is string => typeof c === 'string');
+    }
+    return [];
+}
+
+/**
+ * Map a forge reading onto the five rows.
+ *
+ * Never throws and never invents: an input of `null` produces `unread`, which is
+ * why the return type has three states rather than two. A gate that reports
+ * `false` for something it did not look at is the failure this separation exists
+ * to prevent — and it is the failure the `forge-protection-settings` re-scope
+ * names, one layer up.
+ */
+export function forgeProtectionRows(reading: ForgeReading): ProtectionRow[] {
+    const rows: ProtectionRow[] = [];
+    const rulesets = reading.rulesets;
+    const branch = reading.defaultBranch;
+
+    const covering =
+        rulesets === null || branch === null
+            ? null
+            : rulesets.filter((rs) => isActiveBranchRuleset(rs) && reachesDefaultBranch(rs, branch));
+
+    rows.push(
+        covering === null
+            ? {
+                  id: 'default_branch_protected',
+                  state: 'unread',
+                  source: SOURCE.rulesets,
+                  detail: 'the rulesets were not queried',
+              }
+            : covering.length > 0
+              ? {
+                    id: 'default_branch_protected',
+                    state: 'satisfied',
+                    source: SOURCE.rulesets,
+                    detail: `${String(covering.length)} active branch ruleset(s) cover the default branch`,
+                }
+              : {
+                    id: 'default_branch_protected',
+                    state: 'unsatisfied',
+                    source: SOURCE.rulesets,
+                    detail:
+                        'no active branch ruleset covers the default branch. NOTE: the classic ' +
+                        'branches/<b>/protection endpoint 404s on a ruleset-protected repository, ' +
+                        'so a 404 there is not evidence for this row.',
+                },
+    );
+
+    const contexts = covering === null ? null : covering.flatMap(requiredContexts);
+    rows.push(
+        contexts === null
+            ? {
+                  id: 'required_checks_present',
+                  state: 'unread',
+                  source: SOURCE.rulesets,
+                  detail: 'the rulesets were not queried',
+              }
+            : contexts.length > 0
+              ? {
+                    id: 'required_checks_present',
+                    state: 'satisfied',
+                    source: SOURCE.rulesets,
+                    detail: `${String(contexts.length)} required context(s): ${contexts.join(', ')}`,
+                }
+              : {
+                    id: 'required_checks_present',
+                    state: 'unsatisfied',
+                    source: SOURCE.rulesets,
+                    detail: 'no required status check context is configured',
+                },
+    );
+
+    const noFastForward = covering === null ? null : covering.some((rs) => hasRule(rs, 'non_fast_forward'));
+    rows.push(
+        noFastForward === null
+            ? {
+                  id: 'force_push_disabled',
+                  state: 'unread',
+                  source: SOURCE.rulesets,
+                  detail: 'the rulesets were not queried',
+              }
+            : {
+                  id: 'force_push_disabled',
+                  state: noFastForward ? 'satisfied' : 'unsatisfied',
+                  source: SOURCE.rulesets,
+                  detail: noFastForward
+                      ? 'a non_fast_forward rule is active on the default branch'
+                      : 'no non_fast_forward rule covers the default branch',
+              },
+    );
+
+    rows.push(
+        reading.allowAutoMerge === null
+            ? {
+                  id: 'auto_merge_available',
+                  state: 'unread',
+                  source: SOURCE.repo,
+                  detail: 'the repository record was not queried',
+              }
+            : {
+                  id: 'auto_merge_available',
+                  state: reading.allowAutoMerge ? 'satisfied' : 'unsatisfied',
+                  source: SOURCE.repo,
+                  detail: reading.allowAutoMerge
+                      ? 'allow_auto_merge is enabled'
+                      : 'allow_auto_merge is disabled — merge delivery cannot queue behind checks',
+              },
+    );
+
+    rows.push(
+        reading.deployRestricted === null
+            ? {
+                  id: 'deploy_via_pipeline_only',
+                  state: 'unread',
+                  source: SOURCE.environments,
+                  detail: 'the environments were not queried',
+              }
+            : {
+                  id: 'deploy_via_pipeline_only',
+                  state: reading.deployRestricted ? 'satisfied' : 'unsatisfied',
+                  source: SOURCE.environments,
+                  detail: reading.deployRestricted
+                      ? 'every environment restricts its deployment branches'
+                      : 'at least one environment accepts a deployment from any branch',
+              },
+    );
+
+    return rows;
+}
+
+/**
+ * The human ACTION lines for rows that are not satisfied.
+ *
+ * **Not a halt, and the step says so explicitly**: `doctor` LISTS what is
+ * missing and the run continues. An `unread` row produces an action too — "go
+ * and read it" is a real instruction, and silently omitting it would make an
+ * unmeasured row indistinguishable from a satisfied one, which is the same
+ * conflation the three-state row type exists to prevent.
+ */
+export function protectionActions(rows: readonly ProtectionRow[]): string[] {
+    return rows
+        .filter((r) => r.state !== 'satisfied')
+        .map((r) => `${r.id}: ${r.state} — ${r.detail} (source: ${r.source})`);
+}
+
+/** Unconditional bypass actors across the covering rulesets, for reporting. */
+export function unconditionalBypasses(
+    rulesets: readonly RulesetDetail[],
+    defaultBranch: string,
+): BypassActor[] {
+    return rulesets
+        .filter((rs) => isActiveBranchRuleset(rs) && reachesDefaultBranch(rs, defaultBranch))
+        .flatMap((rs) => (rs.bypass_actors ?? []).filter((a) => a.bypass_mode === 'always'));
+}

package/src/scripts/_lib/hook_platform_keys.ts

@@ -0,0 +1,27 @@
+/**
+ * Keys under a `hook_manifest.yaml` platform block that are NOT lifecycle slots.
+ *
+ * One definition, because three consumers had grown their own literal and a
+ * fourth key would have had to be added to each of them independently: the
+ * manifest lint (which reads an unknown key as an unknown EVENT), the
+ * injection-effect report (which counts slots per host), and the install
+ * snapshot's drift guard (which asserts every manifest event is bound). Each
+ * of those is a different question about the same block, and none of them is
+ * asking about metadata.
+ *
+ *   `fallback_only`  this package binds nothing on the host; counting it made
+ *                    copilot read one slot against the zero the host table
+ *                    records.
+ *   `ask`            the shape of the host's user-facing question primitive,
+ *                    `native` or `text`. It binds no event, so counting it
+ *                    would add one phantom slot to every host at once.
+ *
+ * A key added here is a key excluded from every event-shaped reading of the
+ * manifest, so add one only when it genuinely carries no binding.
+ */
+export const PLATFORM_METADATA_KEYS: ReadonlySet<string> = new Set(['fallback_only', 'ask']);
+
+/** True when a platform-block key describes the host rather than binding an event. */
+export function isPlatformMetadataKey(key: string): boolean {
+    return PLATFORM_METADATA_KEYS.has(key);
+}

package/src/scripts/_lib/json_python_parity.ts

@@ -0,0 +1,127 @@
+/**
+ * `json.dumps` byte-parity helpers — the emit half of the ADR-200 port.
+ *
+ * The retired Python installer wrote every JSON artefact through
+ * `json.dumps(..., ensure_ascii=False)`, and the port's contract is
+ * byte-identical output, not merely equivalent JSON. `JSON.stringify` does not
+ * satisfy it: it escapes nothing above `\u001f` the same way, renders `NaN` /
+ * `Infinity` as `null` rather than as Python's bare tokens, and offers no
+ * separator control for the compact NDJSON form. So the three dump shapes the
+ * installer needs are written out here, mirroring CPython's encoder:
+ *
+ * - {@link jsonDumpsIndent} — `json.dumps(data, indent=N, ensure_ascii=False)`
+ *   with `sort_keys=False` (insertion order preserved, as JS object key order
+ *   already matches Python dict order for our string keys);
+ * - {@link jsonDumpsCompact} — `json.dumps(obj, separators=(",", ":"))`;
+ * - {@link jsonStrNoAscii} — the string encoder both build on.
+ *
+ * Sibling of `src/scripts/install.ts`, which is its only caller. It lives here
+ * rather than inline because the dump shapes are pure, total functions of their
+ * input with no installer state — and because `install.ts` is far over the
+ * 1,500-line source ceiling (`check_source_size_budget`), so a self-contained
+ * unit belongs outside it.
+ *
+ * This module is in the installer's bundled import closure
+ * (`npm run build:install-bundle`), so it carries no module-level side effect
+ * and no `process.exit` — see `check_installer_import_purity`.
+ */
+
+export function jsonStrNoAscii(s: string): string {
+    // json.dumps(ensure_ascii=False): escape control chars + " + \, keep >=0x20
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0) as number;
+        switch (ch) {
+            case '"':
+                out += '\\"';
+                break;
+            case '\\':
+                out += '\\\\';
+                break;
+            case '\n':
+                out += '\\n';
+                break;
+            case '\r':
+                out += '\\r';
+                break;
+            case '\t':
+                out += '\\t';
+                break;
+            case '\b':
+                out += '\\b';
+                break;
+            case '\f':
+                out += '\\f';
+                break;
+            default:
+                if (code < 0x20) {
+                    out += '\\u' + code.toString(16).padStart(4, '0');
+                } else {
+                    out += ch;
+                }
+        }
+    }
+    return out + '"';
+}
+
+function _jsonScalar(value: unknown): string | null {
+    if (value === null || value === undefined) return 'null';
+    if (typeof value === 'boolean') return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            if (Number.isNaN(value)) return 'NaN';
+            return value > 0 ? 'Infinity' : '-Infinity';
+        }
+        // Our payloads carry only integers; render as-is.
+        return String(value);
+    }
+    if (typeof value === 'string') return jsonStrNoAscii(value);
+    return null;
+}
+
+function _dumpIndent(value: unknown, indent: number, depth: number): string {
+    const scalar = _jsonScalar(value);
+    if (scalar !== null) return scalar;
+    const pad = ' '.repeat(indent * (depth + 1));
+    const closePad = ' '.repeat(indent * depth);
+    if (Array.isArray(value)) {
+        if (value.length === 0) return '[]';
+        const items = value.map((v) => pad + _dumpIndent(v, indent, depth + 1));
+        return `[\n${items.join(',\n')}\n${closePad}]`;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const obj = value as Record<string, unknown>;
+        const keys = Object.keys(obj);
+        if (keys.length === 0) return '{}';
+        const items = keys.map(
+            (k) => `${pad}${jsonStrNoAscii(k)}: ${_dumpIndent(obj[k], indent, depth + 1)}`,
+        );
+        return `{\n${items.join(',\n')}\n${closePad}}`;
+    }
+    return jsonStrNoAscii(String(value));
+}
+
+/** `json.dumps(data, indent=N, ensure_ascii=False)` (sort_keys=False). */
+export function jsonDumpsIndent(value: unknown, indent: number): string {
+    return _dumpIndent(value, indent, 0);
+}
+
+/** `json.dumps(obj, separators=(",", ":"))` — compact, ensure_ascii=False here. */
+export function jsonDumpsCompact(value: unknown): string {
+    const scalar = _jsonScalar(value);
+    if (scalar !== null) return scalar;
+    if (Array.isArray(value)) {
+        return '[' + value.map((v) => jsonDumpsCompact(v)).join(',') + ']';
+    }
+    if (typeof value === 'object' && value !== null) {
+        const obj = value as Record<string, unknown>;
+        return (
+            '{' +
+            Object.keys(obj)
+                .map((k) => `${jsonStrNoAscii(k)}:${jsonDumpsCompact(obj[k])}`)
+                .join(',') +
+            '}'
+        );
+    }
+    return jsonStrNoAscii(String(value));
+}