@quonfig/cli 0.0.74 → 0.2.0

package/dist/util/bootstrap-target.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What `qfg workspace bootstrap` tells the user about the workspace it is
+ * about to push to, and the one check that stops it landing content in the
+ * wrong place.
+ *
+ * The target is resolved the same way `qfg push` / `qfg pull` / `qfg sync`
+ * resolve theirs: `QUONFIG_WORKSPACE`, then the directory's `quonfig.json`
+ * pin, then the active profile. The prompt must name whichever of those won;
+ * naming the profile when the env var chose another workspace is how a
+ * customer confirms a push to the wrong place (qfg-8p8i).
+ */
+import type { WorkspacePin } from './quonfig-json.js';
+export interface BootstrapProfile {
+    organizationSlug?: string;
+    workspace: string;
+    workspaceName?: string;
+    workspaceSlug?: string;
+}
+export interface BootstrapTargetInput {
+    /** `QUONFIG_WORKSPACE`, when set: it outranks everything else. */
+    envOverride: string | undefined;
+    /** The `--dir` directory's `quonfig.json` pin, when readable. */
+    pin: WorkspacePin | undefined;
+    /** The active profile, if any. Only trusted when it IS the resolved workspace. */
+    profile: BootstrapProfile | undefined;
+    /** What the resolver actually returned. */
+    workspaceId: string;
+}
+/**
+ * The name to show for the resolved workspace, from whichever source chose
+ * it. Falls back to the id rather than to a profile that points elsewhere.
+ */
+export declare const describeBootstrapTarget: (input: BootstrapTargetInput) => string;
+/**
+ * `qfg push`'s Guard 1 for bootstrap: a directory pinned to one workspace is
+ * not pushed to another. Compares the workspace component only, as push does
+ * (backend responses do not carry the org slug yet). Returns the refusal
+ * message, or nothing when there is no pin or it matches.
+ */
+export declare const bootstrapPinMismatch: (pin: WorkspacePin | undefined, backendWorkspaceSlug: string) => string | undefined;

package/dist/util/bootstrap-target.js

@@ -0,0 +1,46 @@
+/**
+ * What `qfg workspace bootstrap` tells the user about the workspace it is
+ * about to push to, and the one check that stops it landing content in the
+ * wrong place.
+ *
+ * The target is resolved the same way `qfg push` / `qfg pull` / `qfg sync`
+ * resolve theirs: `QUONFIG_WORKSPACE`, then the directory's `quonfig.json`
+ * pin, then the active profile. The prompt must name whichever of those won;
+ * naming the profile when the env var chose another workspace is how a
+ * customer confirms a push to the wrong place (qfg-8p8i).
+ */
+/** The pin form of a workspace, `<org>/<workspace>`. */
+const pinForm = (pin) => `${pin.orgSlug}/${pin.workspaceSlug}`;
+/**
+ * The name to show for the resolved workspace, from whichever source chose
+ * it. Falls back to the id rather than to a profile that points elsewhere.
+ */
+export const describeBootstrapTarget = (input) => {
+    if (input.envOverride)
+        return input.envOverride;
+    if (input.pin)
+        return pinForm(input.pin);
+    const { profile } = input;
+    if (profile && profile.workspace === input.workspaceId) {
+        if (profile.workspaceSlug) {
+            return profile.organizationSlug ? `${profile.organizationSlug}/${profile.workspaceSlug}` : profile.workspaceSlug;
+        }
+        if (profile.workspaceName)
+            return profile.workspaceName;
+    }
+    return input.workspaceId;
+};
+/**
+ * `qfg push`'s Guard 1 for bootstrap: a directory pinned to one workspace is
+ * not pushed to another. Compares the workspace component only, as push does
+ * (backend responses do not carry the org slug yet). Returns the refusal
+ * message, or nothing when there is no pin or it matches.
+ */
+export const bootstrapPinMismatch = (pin, backendWorkspaceSlug) => {
+    if (!pin || pin.workspaceSlug === backendWorkspaceSlug)
+        return undefined;
+    return (`This directory's quonfig.json is pinned to workspace "${pinForm(pin)}", ` +
+        `but the target workspace is "${backendWorkspaceSlug}".\n` +
+        `Nothing was pushed. Unset QUONFIG_WORKSPACE to bootstrap the pinned workspace, ` +
+        `or change the pin in quonfig.json if "${backendWorkspaceSlug}" is really the target.`);
+};

package/dist/util/clone-and-stack-push.d.ts

@@ -1,7 +1,4 @@
-export declare const MIGRATOR_IDENTITY: {
-    readonly name: "quonfig migrator";
-    readonly email: "migrator@quonfig.com";
-};
+export { MIGRATOR_IDENTITY } from './git-ops.js';
 export interface PushIdentity {
     email: string;
     name: string;

package/dist/util/clone-and-stack-push.js

@@ -1,10 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { runGit as runGitSafe, spawnGit } from './git-ops.js';
-export const MIGRATOR_IDENTITY = {
-    name: 'quonfig migrator',
-    email: 'migrator@quonfig.com',
-};
+import { MIGRATOR_IDENTITY, runGit as runGitSafe, spawnGit } from './git-ops.js';
+export { MIGRATOR_IDENTITY } from './git-ops.js';
 const redactToken = (s) => s.replaceAll(/:([^\s/@]+)@/g, ':***@');
 export class PushConflictError extends Error {
     constructor(message) {

package/dist/util/git-ops.d.ts

@@ -142,8 +142,66 @@ export declare const gitMergeFfOnly: (dir: string) => Promise<string[]>;
  * Adds or updates the origin remote for a repo.
  */
 export declare const gitSetRemote: (dir: string, url: string) => Promise<void>;
-export declare const gitPushForceLease: (dir: string) => Promise<void>;
-export declare const gitPushForce: (dir: string) => Promise<void>;
+/**
+ * Every file the validator owns at `ref` — config documents (`configs/`,
+ * `feature-flags/`, `segments/`, `log-levels/`) AND schemas (`schemas/`,
+ * `schemas-protected/`) — sorted.
+ *
+ * A workspace repo is FRESH exactly when this list is empty. It is NOT "the
+ * remote holds only the auto-init commit": provisioning commits `README.md`
+ * AND `quonfig.json`, so a commit-count test refuses every real workspace
+ * (plan project/plans/2026-09-17-tree-derived-cache.md 5.6, 13.2 risk 5).
+ * Schemas count because a UI-authored schema is content a local-wins rebase
+ * would silently overwrite, exactly like a flag.
+ *
+ * FAILS CLOSED: if the ref cannot be listed this throws. "I could not look"
+ * must never read as "the workspace is empty".
+ */
+export declare const workspaceDocumentsAtRef: (dir: string, ref: string) => Promise<string[]>;
+export interface RebaseOntoOriginResult {
+    /** How many of the customer's commits were replayed onto the remote head. */
+    commitsRebased: number;
+    /** The sha now at `origin/main`. */
+    pushedSha: string;
+    /** Subject of the extra commit that put the tree right, or null if none was needed. */
+    reconcileSubject: null | string;
+}
+/**
+ * The identity the CLI commits as when nothing better is known: `qfg push`
+ * and `qfg migrate` stack their commits under it, and bootstrap's replayed
+ * commits get it as COMMITTER when the machine has no git identity at all.
+ */
+export declare const MIGRATOR_IDENTITY: {
+    readonly name: "quonfig migrator";
+    readonly email: "migrator@quonfig.com";
+};
+/**
+ * Land the local repo's history on `origin/main` WITHOUT ever force-pushing
+ * (plan 5.6 "Bootstrap keeps its history without force"; `main` is
+ * append-only, so a rewrite is not just forbidden, it silently wedges config
+ * delivery).
+ *
+ * `git fetch origin` is the caller's job. Then:
+ *
+ *   1. Replay the whole local history onto the remote head on a TEMPORARY
+ *      worktree — never on the customer's branch. Whatever happens, their
+ *      local refs and working tree are untouched.
+ *   2. Require the replayed tip's tree to equal the local tip's tree, ignoring
+ *      files the workspace seeded that the local repo does not have. Rebasing
+ *      linearises merges and `-X theirs` silently picks a side, so a
+ *      hand-resolved merge conflict can otherwise ship the wrong content with
+ *      exit 0 (13.2 risk 4).
+ *   3. If it differs, add ONE commit that sets the tree to the local tip's
+ *      tree, keeping the seeded files and the workspace's `quonfig.json`. If
+ *      that cannot be done cleanly, abort with nothing pushed.
+ *   4. Validate the tree that is ACTUALLY about to be pushed (unless
+ *      `validate: false`), so content the workspace would reject fails here
+ *      instead of at the server hook.
+ *   5. Plain `git push` of the result to `main`.
+ */
+export declare const rebaseOntoOriginAndPush: (dir: string, opts?: {
+    validate?: boolean;
+}) => Promise<RebaseOntoOriginResult>;
 export declare const hasAtLeastOneCommit: (dir: string) => Promise<boolean>;
 /**
  * Get the URL stripped of credentials for display purposes.

package/dist/util/git-ops.js

@@ -1,4 +1,4 @@
-import { execFile as execFileCb, spawn } from 'node:child_process';
+import { execFile as execFileCb, execFileSync, spawn } from 'node:child_process';
 import * as util from 'node:util';
 const execFile = util.promisify(execFileCb);
 /**
@@ -365,11 +365,309 @@ export const gitSetRemote = async (dir, url) => {
         await runGit(['-C', dir, 'remote', 'set-url', 'origin', url]);
     }
 };
-export const gitPushForceLease = async (dir) => {
-    await runGit(['-C', dir, 'push', 'origin', 'main', '--force-with-lease']);
+const revParse = async (dir, rev) => {
+    try {
+        const { stdout } = await runGit(['-C', dir, 'rev-parse', '--verify', '--quiet', rev]);
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+};
+const treePaths = async (dir, rev) => {
+    const { stdout } = await runGit(['-C', dir, 'ls-tree', '-r', '--name-only', rev]);
+    return stdout
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean);
+};
+const countCommits = async (dir, rev) => {
+    const { stdout } = await runGit(['-C', dir, 'rev-list', '--count', rev]);
+    return Number.parseInt(stdout.trim(), 10) || 0;
+};
+/**
+ * Every file the validator owns at `ref` — config documents (`configs/`,
+ * `feature-flags/`, `segments/`, `log-levels/`) AND schemas (`schemas/`,
+ * `schemas-protected/`) — sorted.
+ *
+ * A workspace repo is FRESH exactly when this list is empty. It is NOT "the
+ * remote holds only the auto-init commit": provisioning commits `README.md`
+ * AND `quonfig.json`, so a commit-count test refuses every real workspace
+ * (plan project/plans/2026-09-17-tree-derived-cache.md 5.6, 13.2 risk 5).
+ * Schemas count because a UI-authored schema is content a local-wins rebase
+ * would silently overwrite, exactly like a flag.
+ *
+ * FAILS CLOSED: if the ref cannot be listed this throws. "I could not look"
+ * must never read as "the workspace is empty".
+ */
+export const workspaceDocumentsAtRef = async (dir, ref) => {
+    // Dynamic import: `src/verify/` is copied on its own into the standalone
+    // pre-receive-hook build, so it must stay self-contained — and pulling the
+    // validator in statically would load it for every command that touches git.
+    const { KNOWN_DIRS } = await import('../verify/validate.js');
+    const paths = await treePaths(dir, ref);
+    return paths.filter((p) => KNOWN_DIRS.has(p.split('/')[0])).sort();
+};
+/** Subject of the one commit that puts the tree back to the customer's. */
+const RECONCILE_SUBJECT = 'reconcile merge resolutions';
+/** Subject when the only thing put back is the workspace's own pin file. */
+const PIN_SUBJECT = "use the hosted workspace's quonfig.json";
+/**
+ * `-c` args that keep the CUSTOMER's git config out of the commits bootstrap
+ * makes in the temporary worktree. A worktree shares the repo's config, so
+ * `commit.gpgsign=true` with an unusable `gpg.program` fails the rebase and a
+ * failing `pre-commit` under `core.hooksPath` fails the reconcile commit (both
+ * verified). Neither commit is the customer's to sign or to gate: the rebase
+ * replays commits they already made, and the reconcile commit only restores
+ * their own tree.
+ */
+const GIT_UNCONFIGURED_ARGS = [
+    '-c',
+    'commit.gpgsign=false',
+    '-c',
+    'tag.gpgsign=false',
+    '-c',
+    'core.hooksPath=/dev/null',
+    '-c',
+    'rebase.autosquash=false',
+    '-c',
+    'rerere.enabled=false',
+];
+/**
+ * The identity the CLI commits as when nothing better is known: `qfg push`
+ * and `qfg migrate` stack their commits under it, and bootstrap's replayed
+ * commits get it as COMMITTER when the machine has no git identity at all.
+ */
+export const MIGRATOR_IDENTITY = {
+    name: 'quonfig migrator',
+    email: 'migrator@quonfig.com',
+};
+/**
+ * Env that gives git a committer when it cannot find one itself, and nothing
+ * otherwise. A rebase writes a committer on every replayed commit, and git
+ * refuses ("empty ident name ... not allowed") on a machine with no
+ * `user.name` / `user.email` and no guessable one — every GitHub runner, and
+ * a fresh laptop. `git var GIT_COMMITTER_IDENT` is git's own check, so a
+ * customer whose identity works keeps it, guessed or configured.
+ */
+const committerFallbackEnv = async (dir) => {
+    try {
+        await runGit(['-C', dir, 'var', 'GIT_COMMITTER_IDENT']);
+        return {};
+    }
+    catch {
+        return {
+            GIT_AUTHOR_EMAIL: MIGRATOR_IDENTITY.email,
+            GIT_AUTHOR_NAME: MIGRATOR_IDENTITY.name,
+            GIT_COMMITTER_EMAIL: MIGRATOR_IDENTITY.email,
+            GIT_COMMITTER_NAME: MIGRATOR_IDENTITY.name,
+        };
+    }
+};
+const hasMismatch = (m) => m.pinLost || m.content.length > 0;
+const describeMismatch = (m) => [...m.content, ...(m.pinLost ? ["quonfig.json (the workspace's pin was lost)"] : [])].join(', ');
+const treeMismatch = async (dir, opts) => {
+    const { stdout } = await runGit(['-C', dir, 'diff', '--no-renames', '--name-status', opts.local, opts.candidate]);
+    const content = [];
+    for (const line of stdout.split('\n').filter(Boolean)) {
+        const [status, ...rest] = line.split('\t');
+        const file = rest.join('\t');
+        // A file only the workspace had is expected to appear.
+        if (status === 'A' && opts.seededOnly.has(file))
+            continue;
+        // The workspace's own quonfig.json wins over a local one: it is the pin
+        // that names the hosted workspace. Checked separately, below.
+        if (file === 'quonfig.json' && opts.remoteQuonfigJson !== null)
+            continue;
+        content.push(`${status} ${file}`);
+    }
+    let pinLost = false;
+    if (opts.remoteQuonfigJson !== null) {
+        const candidatePin = await revParse(dir, `${opts.candidate}:quonfig.json`);
+        pinLost = candidatePin !== opts.remoteQuonfigJson;
+    }
+    return { content, pinLost };
 };
-export const gitPushForce = async (dir) => {
-    await runGit(['-C', dir, 'push', 'origin', 'main', '--force']);
+const removeWorktree = async (dir, worktree) => {
+    try {
+        await runGit(['-C', dir, 'worktree', 'remove', '--force', worktree]);
+    }
+    catch {
+        /* already gone, or never created */
+    }
+    try {
+        await runGit(['-C', dir, 'worktree', 'prune']);
+    }
+    catch {
+        /* best effort */
+    }
+};
+/**
+ * Run the workspace validator — the same one the server's pre-receive hook
+ * runs — over a checked-out tree, and throw with its errors if it would be
+ * rejected.
+ */
+const requireWorkspaceValidates = async (tree) => {
+    const { validateWorkspace } = await import('../verify/validate.js');
+    const errors = validateWorkspace(tree, { validateValues: true }).issues.filter((i) => i.severity === 'error');
+    if (errors.length === 0)
+        return;
+    const shown = errors.slice(0, 10).map((i) => `  ${i.file}: ${i.message}`);
+    if (errors.length > shown.length)
+        shown.push(`  ...and ${errors.length - shown.length} more`);
+    const envHint = errors.some((i) => i.message.includes('not declared in quonfig.json'))
+        ? "\nThe workspace's own quonfig.json replaces yours, so an environment that exists only in your local file is not declared on the workspace. Create it in the Quonfig app (or drop the override), then run bootstrap again."
+        : '';
+    throw new Error(`Refusing to push: the workspace would reject this content.\n${shown.join('\n')}${envHint}\nNothing was pushed and your local repository is unchanged.`);
+};
+/**
+ * Land the local repo's history on `origin/main` WITHOUT ever force-pushing
+ * (plan 5.6 "Bootstrap keeps its history without force"; `main` is
+ * append-only, so a rewrite is not just forbidden, it silently wedges config
+ * delivery).
+ *
+ * `git fetch origin` is the caller's job. Then:
+ *
+ *   1. Replay the whole local history onto the remote head on a TEMPORARY
+ *      worktree — never on the customer's branch. Whatever happens, their
+ *      local refs and working tree are untouched.
+ *   2. Require the replayed tip's tree to equal the local tip's tree, ignoring
+ *      files the workspace seeded that the local repo does not have. Rebasing
+ *      linearises merges and `-X theirs` silently picks a side, so a
+ *      hand-resolved merge conflict can otherwise ship the wrong content with
+ *      exit 0 (13.2 risk 4).
+ *   3. If it differs, add ONE commit that sets the tree to the local tip's
+ *      tree, keeping the seeded files and the workspace's `quonfig.json`. If
+ *      that cannot be done cleanly, abort with nothing pushed.
+ *   4. Validate the tree that is ACTUALLY about to be pushed (unless
+ *      `validate: false`), so content the workspace would reject fails here
+ *      instead of at the server hook.
+ *   5. Plain `git push` of the result to `main`.
+ */
+export const rebaseOntoOriginAndPush = async (dir, opts) => {
+    const localHead = await revParse(dir, 'HEAD');
+    if (localHead === null)
+        throw new Error('The local repository has no commits to push.');
+    const remoteHead = await revParse(dir, 'origin/main');
+    if (remoteHead === null) {
+        // Provisioning always creates `main` with auto_init, and the pre-receive
+        // hook rejects a zero-oid create (plan 5.6 item 1), so pushing the branch
+        // into existence is a dead end, not a fallback.
+        throw new Error('The workspace repository is not provisioned (it has no `main` branch).\nFinish creating the workspace in the Quonfig app, then run bootstrap again.');
+    }
+    const remotePaths = await treePaths(dir, remoteHead);
+    const localPaths = new Set(await treePaths(dir, localHead));
+    const seededOnly = new Set(remotePaths.filter((p) => !localPaths.has(p)));
+    const remoteQuonfigJson = remotePaths.includes('quonfig.json')
+        ? await revParse(dir, `${remoteHead}:quonfig.json`)
+        : null;
+    const { tmpdir } = await import('node:os');
+    const { join } = await import('node:path');
+    const worktree = join(tmpdir(), `qfg-bootstrap-${process.pid}-${Date.now()}`);
+    // The rebase keeps each commit's AUTHOR; this only decides the committer
+    // (and the author of the reconcile commit, which is the CLI's own).
+    const identityEnv = await committerFallbackEnv(dir);
+    // Ctrl-C between `worktree add` and the `finally` would leave the temp
+    // worktree registered in the customer's repo; drop it synchronously.
+    const onInterrupt = () => {
+        try {
+            execFileSync('git', [...GIT_SAFE_ARGS, '-C', dir, 'worktree', 'remove', '--force', worktree], { stdio: 'ignore' });
+        }
+        catch {
+            /* best effort — `git worktree prune` also clears it later */
+        }
+        // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+        process.exit(130);
+    };
+    process.once('SIGINT', onInterrupt);
+    try {
+        await runGit(['-C', dir, 'worktree', 'add', '--detach', worktree, localHead]);
+        try {
+            await runGit([
+                '-C',
+                worktree,
+                ...GIT_UNCONFIGURED_ARGS,
+                'rebase',
+                '--root',
+                '--onto',
+                remoteHead,
+                '-X',
+                'theirs',
+                '--committer-date-is-author-date',
+            ], { env: identityEnv });
+        }
+        catch (error) {
+            try {
+                await runGit(['-C', worktree, 'rebase', '--abort']);
+            }
+            catch {
+                /* nothing to abort */
+            }
+            throw new Error([
+                'Could not replay your history onto the workspace repository.',
+                'Nothing was pushed and your local repository is unchanged.',
+                '',
+                'To land the files you have now WITHOUT their history, run:',
+                `  qfg push --dir ${dir}`,
+                '',
+                String(error),
+            ].join('\n'));
+        }
+        let candidate = await revParse(worktree, 'HEAD');
+        if (candidate === null)
+            throw new Error('The rebase produced no commit. Nothing was pushed.');
+        let reconcileSubject = null;
+        let mismatch = await treeMismatch(dir, { candidate, local: localHead, remoteQuonfigJson, seededOnly });
+        if (hasMismatch(mismatch)) {
+            // Honest subject: when the ONLY thing being put back is the workspace's
+            // own pin file, nothing was "reconciled" and saying so would be a lie.
+            reconcileSubject = mismatch.content.length > 0 ? RECONCILE_SUBJECT : PIN_SUBJECT;
+            const body = reconcileSubject === RECONCILE_SUBJECT
+                ? 'Sets the tree to the state of the local repository, keeping the files this workspace already had. Replaying merge commits one by one can otherwise resolve a conflict differently than you did.'
+                : 'The hosted workspace seeds its own quonfig.json, which carries the workspace pin and its environment list, so it wins over the one in the local repository.';
+            const keepFromRemote = [...seededOnly];
+            if (remoteQuonfigJson !== null && !seededOnly.has('quonfig.json'))
+                keepFromRemote.push('quonfig.json');
+            try {
+                await runGit(['-C', worktree, 'restore', `--source=${localHead}`, '--staged', '--worktree', '--', '.']);
+                if (keepFromRemote.length > 0) {
+                    await runGit([
+                        '-C',
+                        worktree,
+                        'restore',
+                        `--source=${remoteHead}`,
+                        '--staged',
+                        '--worktree',
+                        '--',
+                        ...keepFromRemote,
+                    ]);
+                }
+                await runGit(['-C', worktree, ...GIT_UNCONFIGURED_ARGS, 'commit', '--no-verify', '-m', reconcileSubject, '-m', body], { env: identityEnv });
+            }
+            catch (error) {
+                throw new Error(`Could not reconcile your local content with the workspace repository: ${String(error)}\nNothing was pushed and your local repository is unchanged.`);
+            }
+            candidate = await revParse(worktree, 'HEAD');
+            if (candidate === null)
+                throw new Error('The reconcile commit produced no commit. Nothing was pushed.');
+            mismatch = await treeMismatch(dir, { candidate, local: localHead, remoteQuonfigJson, seededOnly });
+            if (hasMismatch(mismatch)) {
+                throw new Error(`Refusing to push: the result would not match your local files (${describeMismatch(mismatch)}).\nNothing was pushed and your local repository is unchanged.`);
+            }
+        }
+        // Validate what is ACTUALLY going to be pushed. The worktree holds exactly
+        // the candidate's tree, which is the local content plus the workspace's own
+        // quonfig.json — so an environment that exists only in the local pin file
+        // fails HERE, with a readable message, instead of at the server hook.
+        if (opts?.validate !== false)
+            await requireWorkspaceValidates(worktree);
+        await runGit(['-C', dir, 'push', 'origin', `${candidate}:refs/heads/main`]);
+        return { commitsRebased: await countCommits(dir, localHead), pushedSha: candidate, reconcileSubject };
+    }
+    finally {
+        process.off('SIGINT', onInterrupt);
+        await removeWorktree(dir, worktree);
+    }
 };
 export const hasAtLeastOneCommit = async (dir) => {
     try {

package/dist/verify/schema-error-reshape.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Ajv errors -> readable `{ path, message }` violations (qfg-q5f6.1).
+ *
+ * SELF-CONTAINED ON PURPOSE. This file has no imports: it is copied verbatim
+ * into `cli/src/verify/` so `qfg verify`, the app server and the browser
+ * (list badge, view page) word every violation the same way. Change it here
+ * first and re-copy; do not let the two drift.
+ *
+ * It works on any error object shaped like Ajv's `ErrorObject` (keyword,
+ * instancePath, schemaPath, params, message), from Ajv run with
+ * `allErrors: true`.
+ *
+ * Tagged `oneOf` (plan 2026-09-25-advanced-schema-for-jev.md, W1): Ajv
+ * reports every branch's failures, which for a three-way union is mostly
+ * noise. When every branch is an object with the same `const` (or one-value
+ * `enum`) property, that property is the tag:
+ * - the value's tag picks a branch -> only that branch's errors are kept;
+ * - the tag is missing or unknown -> ONE error:
+ *   "`type` must be one of noul, score, choice".
+ * A `oneOf` without a tag is left as Ajv reported it.
+ */
+/** The subset of Ajv's `ErrorObject` this module reads. */
+export interface SchemaErrorLike {
+    keyword: string;
+    instancePath: string;
+    schemaPath: string;
+    params: object;
+    message?: string;
+    propertyName?: string;
+}
+export interface SchemaViolation {
+    /** Dotted path inside the value (`criteria[1]`, `a.b`); "" for the root. */
+    path: string;
+    message: string;
+}
+/** Keyword of the single error that replaces a missing/unknown-tag `oneOf`. */
+export declare const ONE_OF_TAG_KEYWORD = "oneOfTag";
+/**
+ * Ajv `instancePath` (JSON pointer) -> dotted path:
+ * `/questions/tone/criteria/1` -> `questions.tone.criteria[1]`.
+ * Walks the value so only real array indexes become `[n]`.
+ */
+export declare function instancePathToDotted(instancePath: string, value: unknown): string;
+export interface OneOfTag {
+    /** The tag property name, e.g. `type`. */
+    name: string;
+    /** Tag value of each branch, in branch order. */
+    values: unknown[];
+}
+/**
+ * Find the tag of a `oneOf`: the ONE property that is a `const` (or a
+ * one-value `enum`) in every branch, with distinct values. Undefined when
+ * there is none, or more than one candidate.
+ */
+export declare function findOneOfTag(branches: unknown[], root: unknown): OneOfTag | undefined;
+/**
+ * Collapse tagged `oneOf` noise. Returns a new list in Ajv's order: errors
+ * from non-selected branches are dropped, and a missing/unknown tag becomes
+ * a single `oneOfTag` error at the union's position.
+ */
+export declare function reshapeOneOfErrors<E extends SchemaErrorLike>(errors: readonly E[], rootSchema: unknown, value: unknown): (E | SchemaErrorLike)[];
+/** One error -> message. Undefined means "skip it, a nested error says why". */
+export declare function describeSchemaError(error: SchemaErrorLike): string | undefined;
+/**
+ * Ajv errors for `value` against `rootSchema` -> violations, with tagged
+ * `oneOf` noise collapsed. Call it only when validation failed: it never
+ * returns an empty list.
+ */
+export declare function schemaErrorsToViolations(errors: readonly SchemaErrorLike[], rootSchema: unknown, value: unknown): SchemaViolation[];