@quonfig/cli 0.0.74 → 0.2.0

package/dist/verify/schema-error-reshape.js

@@ -0,0 +1,257 @@
+/* eslint-disable perfectionist/sort-interfaces, unicorn/prefer-string-replace-all, unicorn/no-array-callback-reference, unicorn/no-lonely-if --
+ * Copied from app-quonfig src/lib/domain/schema-error-reshape.ts (qfg-phcv).
+ * Only prettier's formatting differs; keep the logic identical to the app's
+ * copy rather than restyling it for this repo's lint rules. */
+/**
+ * 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.
+ */
+/** Keyword of the single error that replaces a missing/unknown-tag `oneOf`. */
+export const ONE_OF_TAG_KEYWORD = 'oneOfTag';
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function unescapeToken(token) {
+    return token.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+function pointerTokens(pointer) {
+    const body = pointer.startsWith('#') ? pointer.slice(1) : pointer;
+    if (!body)
+        return [];
+    return body.slice(1).split('/').map(unescapeToken);
+}
+function resolvePointer(root, pointer) {
+    let node = root;
+    for (const token of pointerTokens(pointer)) {
+        if (Array.isArray(node))
+            node = node[Number(token)];
+        else if (isObject(node))
+            node = node[token];
+        else
+            return undefined;
+    }
+    return node;
+}
+/**
+ * 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 function instancePathToDotted(instancePath, value) {
+    if (!instancePath)
+        return '';
+    let path = '';
+    let node = value;
+    for (const token of pointerTokens(instancePath)) {
+        if (Array.isArray(node)) {
+            path += `[${token}]`;
+            node = node[Number(token)];
+        }
+        else {
+            path += path ? `.${token}` : token;
+            node = isObject(node) ? node[token] : undefined;
+        }
+    }
+    return path;
+}
+/** Follow local `$ref`s (`#/...`) a few hops; anything else is returned as is. */
+function derefLocal(schema, root) {
+    let node = schema;
+    for (let hops = 0; hops < 8; hops += 1) {
+        if (!isObject(node) || typeof node.$ref !== 'string')
+            return node;
+        if (!node.$ref.startsWith('#'))
+            return node;
+        node = resolvePointer(root, node.$ref);
+    }
+    return node;
+}
+function tagValueOf(property) {
+    if (!isObject(property))
+        return undefined;
+    if ('const' in property)
+        return { value: property.const };
+    if (Array.isArray(property.enum) && property.enum.length === 1) {
+        return { value: property.enum[0] };
+    }
+    return undefined;
+}
+/**
+ * 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 function findOneOfTag(branches, root) {
+    if (branches.length < 2)
+        return undefined;
+    const resolved = branches.map((branch) => derefLocal(branch, root));
+    const propertiesOf = resolved.map((branch) => isObject(branch) && isObject(branch.properties) ? branch.properties : undefined);
+    const first = propertiesOf[0];
+    if (!first || propertiesOf.some((props) => !props))
+        return undefined;
+    const candidates = [];
+    for (const name of Object.keys(first)) {
+        const values = [];
+        for (const props of propertiesOf) {
+            const tag = tagValueOf(derefLocal(props[name], root));
+            if (!tag)
+                break;
+            values.push(tag.value);
+        }
+        if (values.length !== branches.length)
+            continue;
+        const distinct = new Set(values.map((v) => JSON.stringify(v)));
+        if (distinct.size !== values.length)
+            continue;
+        candidates.push({ name, values });
+    }
+    return candidates.length === 1 ? candidates[0] : undefined;
+}
+function formatTagValue(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+function isUnderInstance(error, instancePath) {
+    return error.instancePath === instancePath || error.instancePath.startsWith(`${instancePath}/`);
+}
+/** Schema-path prefixes that identify errors raised inside branch `index`. */
+function branchPrefixes(oneOfPath, branch, index) {
+    const prefixes = [`${oneOfPath}/${index}/`];
+    // A `{ "$ref": "#/$defs/x" }` branch reports its errors under the ref.
+    if (isObject(branch) && typeof branch.$ref === 'string') {
+        if (branch.$ref.startsWith('#'))
+            prefixes.push(`${branch.$ref}/`);
+    }
+    return prefixes;
+}
+/**
+ * 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 function reshapeOneOfErrors(errors, rootSchema, value) {
+    const dropped = new Set();
+    const replaced = new Map();
+    errors.forEach((error, index) => {
+        if (error.keyword !== 'oneOf')
+            return;
+        // More than one branch passed: that is not a tagging problem.
+        const passing = error.params.passingSchemas;
+        if (passing !== null && passing !== undefined)
+            return;
+        const branches = resolvePointer(rootSchema, error.schemaPath);
+        if (!Array.isArray(branches))
+            return;
+        const tag = findOneOfTag(branches, rootSchema);
+        if (!tag)
+            return;
+        const members = [];
+        const prefixes = branches.map((branch, i) => branchPrefixes(error.schemaPath, branch, i));
+        errors.forEach((other, otherIndex) => {
+            if (otherIndex === index)
+                return;
+            if (!isUnderInstance(other, error.instancePath))
+                return;
+            const branch = prefixes.findIndex((list) => list.some((prefix) => other.schemaPath.startsWith(prefix)));
+            if (branch >= 0)
+                members.push({ index: otherIndex, branch });
+        });
+        const instance = resolvePointer(value, error.instancePath);
+        const selected = isObject(instance) && tag.name in instance
+            ? tag.values.findIndex((v) => JSON.stringify(v) === JSON.stringify(instance[tag.name]))
+            : -1;
+        if (selected < 0) {
+            for (const member of members)
+                dropped.add(member.index);
+            const allowed = tag.values.map(formatTagValue).join(', ');
+            replaced.set(index, {
+                keyword: ONE_OF_TAG_KEYWORD,
+                instancePath: error.instancePath,
+                schemaPath: error.schemaPath,
+                params: { tag: tag.name, allowedValues: tag.values },
+                message: isObject(instance) ? `\`${tag.name}\` must be one of ${allowed}` : 'must be object',
+            });
+            return;
+        }
+        const kept = members.filter((member) => member.branch === selected);
+        for (const member of members) {
+            if (member.branch !== selected)
+                dropped.add(member.index);
+        }
+        // Keep Ajv's "must match exactly one schema" only if the selected branch
+        // reported nothing we could attribute to it (e.g. a remote `$ref`).
+        if (kept.length > 0)
+            dropped.add(index);
+    });
+    const result = [];
+    errors.forEach((error, index) => {
+        if (dropped.has(index))
+            return;
+        result.push(replaced.get(index) ?? error);
+    });
+    return result;
+}
+function stringifyAllowed(entry) {
+    return typeof entry === 'string' ? entry : JSON.stringify(entry);
+}
+/** One error -> message. Undefined means "skip it, a nested error says why". */
+export function describeSchemaError(error) {
+    const params = error.params;
+    const message = error.message ?? `failed ${error.keyword}`;
+    switch (error.keyword) {
+        case 'additionalProperties':
+            return `must NOT have additional property '${String(params.additionalProperty)}'`;
+        case 'unevaluatedProperties':
+            return `must NOT have unevaluated property '${String(params.unevaluatedProperty)}'`;
+        case 'enum':
+            return Array.isArray(params.allowedValues)
+                ? `${message}: ${params.allowedValues.map(stringifyAllowed).join(', ')}`
+                : message;
+        case 'propertyNames':
+            // The nested keyword error (which carries `propertyName`) says why.
+            return undefined;
+        default:
+            break;
+    }
+    if (error.propertyName !== undefined) {
+        return `property name '${error.propertyName}': ${message}`;
+    }
+    return message;
+}
+/**
+ * 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 function schemaErrorsToViolations(errors, rootSchema, value) {
+    const violations = [];
+    for (const error of reshapeOneOfErrors(errors, rootSchema, value)) {
+        const message = describeSchemaError(error);
+        if (message === undefined)
+            continue;
+        violations.push({
+            path: instancePathToDotted(error.instancePath, value),
+            message,
+        });
+    }
+    if (violations.length === 0) {
+        violations.push({ path: '', message: 'does not match the schema' });
+    }
+    return violations;
+}

package/dist/verify/schema-validator.d.ts

@@ -0,0 +1,29 @@
+import { type SchemaViolation } from './schema-error-reshape.js';
+export type { SchemaViolation } from './schema-error-reshape.js';
+/** Formats the app treats as editor hints; they accept any string. */
+export declare const ALWAYS_VALID_FORMATS: string[];
+type ValidateFn = ((value: unknown) => boolean) & {
+    errors?: null | unknown[];
+};
+export type CompiledSchema = {
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    validate: ValidateFn;
+};
+/** Compile (cached per schema object) a validator. Never throws. */
+export declare function compileSchema(schema: Record<string, unknown>): CompiledSchema;
+export type SchemaValidationResult = {
+    kind: 'invalid-schema';
+    ok: false;
+    reason: string;
+} | {
+    kind: 'violations';
+    ok: false;
+    violations: SchemaViolation[];
+} | {
+    ok: true;
+};
+/** Validate `value` against `schema`. Never throws. */
+export declare function validateAgainstSchema(schema: Record<string, unknown>, value: unknown): SchemaValidationResult;

package/dist/verify/schema-validator.js

@@ -0,0 +1,108 @@
+/**
+ * JSON Schema validation for schema-bound config values (qfg-phcv).
+ *
+ * Mirrors app-quonfig src/lib/domain/schema-validator.ts so `qfg verify` and
+ * the app give the same verdict on the same value. Rules (decided in
+ * project/plans/2026-09-25-advanced-schema-for-jev.md W1/W6):
+ * - Draft 2020-12 by default. A `$schema` naming draft-07 (http or https,
+ *   with or without `#`) uses a separate draft-07 Ajv instance, because
+ *   draft-07 tuple `items: [...]` does not compile on Ajv2020. Draft-06 and
+ *   older are a compile error.
+ * - A schema that does not compile is an error, never a skipped validation.
+ * - `format` is enforced through ajv-formats. The app's long-text editor
+ *   hints (`textarea`, `multiline`, `multi-line`) are always-valid formats.
+ * - `addUsedSchema: false`: two schemas declaring the same `$id` must not
+ *   collide in the shared Ajv instance.
+ *
+ * Lives inside cli/src/verify/ because the app-gitea hook build only copies
+ * this directory (see validate.ts). The hook does not run value validation
+ * yet (phase 1b), but it compiles this file, so app-gitea/Dockerfile must
+ * install `ajv` and `ajv-formats`.
+ *
+ * Imports: the CLI is ESM with nodenext resolution and Ajv ships CommonJS, so
+ * the default import may be the class or the module object depending on the
+ * runtime (node vs bun). `ajv/dist/2020.js` is imported by explicit path; a
+ * bare `ajv` must resolve to the direct v8 dependency, not the v6 eslint
+ * hoists.
+ */
+import AjvDraft07Import from 'ajv';
+import Ajv2020Import from 'ajv/dist/2020.js';
+import addFormatsImport from 'ajv-formats';
+import { schemaErrorsToViolations } from './schema-error-reshape.js';
+/** Formats the app treats as editor hints; they accept any string. */
+export const ALWAYS_VALID_FORMATS = ['textarea', 'multiline', 'multi-line'];
+const DRAFT_07_SCHEMA_URL = /^https?:\/\/json-schema\.org\/draft-07\/schema#?$/;
+const DRAFT_07_CANONICAL_URL = 'http://json-schema.org/draft-07/schema#';
+const PRE_DRAFT_07_SCHEMA_URL = /^https?:\/\/json-schema\.org\/(draft-0[0-6]\/)?schema#?$/;
+const AJV_OPTIONS = {
+    addUsedSchema: false,
+    allErrors: true,
+    strict: false,
+};
+function interop(imported) {
+    const mod = imported;
+    return (typeof mod === 'function' ? mod : (mod.default ?? mod));
+}
+const AjvDraft07 = interop(AjvDraft07Import);
+const Ajv2020 = interop(Ajv2020Import);
+const addFormats = interop(addFormatsImport);
+function configure(ajv) {
+    addFormats(ajv);
+    for (const format of ALWAYS_VALID_FORMATS)
+        ajv.addFormat(format, true);
+    return ajv;
+}
+let ajv2020;
+let ajvDraft07;
+function getAjv2020() {
+    ajv2020 ??= configure(new Ajv2020(AJV_OPTIONS));
+    return ajv2020;
+}
+function getAjvDraft07() {
+    ajvDraft07 ??= configure(new AjvDraft07(AJV_OPTIONS));
+    return ajvDraft07;
+}
+const compiledByObject = new WeakMap();
+function compileUncached(schema) {
+    const declared = schema.$schema;
+    let ajv = getAjv2020();
+    let toCompile = schema;
+    if (typeof declared === 'string') {
+        if (DRAFT_07_SCHEMA_URL.test(declared)) {
+            ajv = getAjvDraft07();
+            // Ajv only knows the draft-07 meta-schema by its canonical id; the
+            // https and no-`#` spellings name the same draft.
+            toCompile = { ...schema, $schema: DRAFT_07_CANONICAL_URL };
+        }
+        else if (PRE_DRAFT_07_SCHEMA_URL.test(declared)) {
+            return { ok: false, reason: `unsupported $schema ${declared}; use draft 2020-12 or draft-07` };
+        }
+    }
+    try {
+        return { ok: true, validate: ajv.compile(toCompile) };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // Ajv's meta-schema failure already starts with "schema is invalid: ".
+        return { ok: false, reason: message.replace(/^schema is invalid: /, '') };
+    }
+}
+/** Compile (cached per schema object) a validator. Never throws. */
+export function compileSchema(schema) {
+    let compiled = compiledByObject.get(schema);
+    if (!compiled) {
+        compiled = compileUncached(schema);
+        compiledByObject.set(schema, compiled);
+    }
+    return compiled;
+}
+/** Validate `value` against `schema`. Never throws. */
+export function validateAgainstSchema(schema, value) {
+    const compiled = compileSchema(schema);
+    if (!compiled.ok)
+        return { kind: 'invalid-schema', ok: false, reason: compiled.reason };
+    if (compiled.validate(value))
+        return { ok: true };
+    const errors = (compiled.validate.errors ?? []);
+    return { kind: 'violations', ok: false, violations: schemaErrorsToViolations(errors, schema, value) };
+}

package/dist/verify/standalone.d.ts

@@ -10,6 +10,37 @@
  *   0  All checks pass
  *   1  Validation errors found
  */
+export type RefUpdate = {
+    newOid: string;
+    oldOid: string;
+    refName: string;
+};
+export type HookEnv = Record<string, string | undefined>;
+export type HookOptions = {
+    cwd?: string;
+    env: HookEnv;
+    log: (line: string) => void;
+    logErr: (line: string) => void;
+};
+/**
+ * The whole pre-receive decision, as a function: returns the process exit code
+ * (0 accept, 1 reject). Split out of runGitHook so tests can drive it against
+ * real bare repos without a subprocess.
+ */
+export declare function runHookChecks(refs: readonly RefUpdate[], opts: HookOptions): number;
+/** The `cli` sha this binary was built from; `dev` for an unstamped build. */
+export declare function hookVersion(env?: HookEnv): string;
+/**
+ * `main` is append-only: every update to refs/heads/main must have a non-zero
+ * old oid that is an ancestor of the new oid. A delete and a create are both
+ * rejected (provisioning creates `main` with auto_init; no writer creates it by
+ * push, and the zero-oid door is the only way to delete-then-recreate).
+ * Other refs are untouched. See plan 2026-09-17-tree-derived-cache 5.6.
+ */
+export declare function checkAppendOnlyMain(refs: readonly RefUpdate[], env: HookEnv, cwd?: string): {
+    bypassReason?: string;
+    errors: string[];
+};
 /**
  * Read all JSON config files from a git commit using `git show`.
  * Works in bare repos (no working tree needed).

package/dist/verify/standalone.js

@@ -10,7 +10,7 @@
  *   0  All checks pass
  *   1  Validation errors found
  */
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import * as readline from 'node:readline';
 import { formatResult, validateFileMap, validateWorkspace } from './validate.js';
 async function main() {
@@ -57,36 +57,181 @@ async function runGitHook() {
         rl.on('line', (line) => {
             const parts = line.trim().split(' ');
             if (parts.length >= 3) {
-                refs.push({ oldOid: parts[0], newOid: parts[1], refName: parts[2] });
+                refs.push({ newOid: parts[1], oldOid: parts[0], refName: parts[2] });
             }
         });
         rl.on('close', resolve);
     });
+    process.exit(runHookChecks(refs, { env: process.env, log: console.log, logErr: console.error }));
+}
+/**
+ * The whole pre-receive decision, as a function: returns the process exit code
+ * (0 accept, 1 reject). Split out of runGitHook so tests can drive it against
+ * real bare repos without a subprocess.
+ */
+export function runHookChecks(refs, opts) {
+    const { cwd, env, log, logErr } = opts;
+    // Always the first line, so a rollout or rollback can be confirmed by
+    // something other than behaviour (plan 5.6 item 5).
+    log(`qfg-verify ${hookVersion(env)}`);
     if (refs.length === 0) {
-        console.log('qfg-verify: no refs received');
-        process.exit(0);
+        log('qfg-verify: no refs received');
+        return 0;
     }
-    // Validate the latest pushed commit for each ref
     let hasErrors = false;
+    // Append-only `main` (qfg-jxml.21). Runs BEFORE content validation, but does
+    // not short-circuit it: an operator repair is still validated for content.
+    const appendOnly = checkAppendOnlyMain(refs, env, cwd);
+    if (appendOnly.bypassReason) {
+        logErr(`qfg-verify: operator rewrite bypass by ${env.GITEA_PUSHER_NAME ?? '?'}: ${appendOnly.bypassReason}`);
+    }
+    for (const message of appendOnly.errors) {
+        logErr(message);
+        hasErrors = true;
+    }
+    // Content validation: the latest pushed commit for each ref.
     for (const ref of refs) {
         // Skip deletions
-        if (ref.newOid === '0000000000000000000000000000000000000000')
+        if (isZeroOid(ref.newOid))
             continue;
-        console.log(`qfg-verify: validating ${ref.refName} (${ref.newOid.slice(0, 8)})`);
+        log(`qfg-verify: validating ${ref.refName} (${ref.newOid.slice(0, 8)})`);
         try {
-            const files = readFilesFromCommit(ref.newOid);
+            const files = readFilesFromCommit(ref.newOid, cwd);
             const result = validateFileMap(files);
-            console.log(formatResult(result));
+            log(formatResult(result));
             if (!result.valid) {
                 hasErrors = true;
             }
         }
         catch (error) {
-            console.error(`qfg-verify: error reading commit ${ref.newOid}: ${error.message}`);
+            logErr(`qfg-verify: error reading commit ${ref.newOid}: ${error.message}`);
             hasErrors = true;
         }
     }
-    process.exit(hasErrors ? 1 : 0);
+    return hasErrors ? 1 : 0;
+}
+function isZeroOid(oid) {
+    return /^0+$/.test(oid);
+}
+/** The `cli` sha this binary was built from; `dev` for an unstamped build. */
+export function hookVersion(env = process.env) {
+    return env.QFG_VERIFY_SHA?.trim() || 'dev';
+}
+const MAIN_REF = 'refs/heads/main';
+const REWRITE_OPTION = 'quonfig-rewrite=';
+/**
+ * `main` is append-only: every update to refs/heads/main must have a non-zero
+ * old oid that is an ancestor of the new oid. A delete and a create are both
+ * rejected (provisioning creates `main` with auto_init; no writer creates it by
+ * push, and the zero-oid door is the only way to delete-then-recreate).
+ * Other refs are untouched. See plan 2026-09-17-tree-derived-cache 5.6.
+ */
+export function checkAppendOnlyMain(refs, env, cwd) {
+    const mainUpdates = refs.filter((ref) => ref.refName === MAIN_REF);
+    if (mainUpdates.length === 0 || !ffEnforcedForRepo(env))
+        return { errors: [] };
+    const bypassReason = operatorBypassReason(env);
+    if (bypassReason)
+        return { bypassReason, errors: [] };
+    const errors = [];
+    for (const ref of mainUpdates) {
+        try {
+            if (isZeroOid(ref.newOid)) {
+                errors.push(rejection('deleting main is not allowed'));
+            }
+            else if (isZeroOid(ref.oldOid)) {
+                errors.push(rejection('creating main by push is not allowed'));
+            }
+            else if (!isAncestor(ref.oldOid, ref.newOid, cwd)) {
+                errors.push(rejection(`${ref.newOid.slice(0, 8)} is not a descendant of the current tip ${ref.oldOid.slice(0, 8)}`));
+            }
+        }
+        catch (error) {
+            // The ancestry check itself failed: git exited 128 (old oid missing from
+            // the repo), git could not be spawned, ... Fail CLOSED, but as the normal
+            // rejection with the recovery recipe — an escaped throw reaches the
+            // pusher as an opaque `qfg-verify: fatal: ...` (qfg-jxml.21 review).
+            errors.push(rejection(`could not check that ${ref.newOid.slice(0, 8)} descends from the current tip ${ref.oldOid.slice(0, 8)}: ${error.message}`));
+        }
+    }
+    return { errors };
+}
+/** Rollout switch: enforce only for repos named in the allowlist; `*` = all. */
+function ffEnforcedForRepo(env) {
+    const allowlist = (env.QUONFIG_HOOK_FF_ENFORCE ?? '')
+        .split(',')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter(Boolean);
+    if (allowlist.length === 0)
+        return false;
+    if (allowlist.includes('*'))
+        return true;
+    // Gitea 1.25 hands the hook its repo via these (modules/repository/env.go).
+    const owner = (env.GITEA_REPO_USER_NAME ?? '').trim().toLowerCase();
+    const name = (env.GITEA_REPO_NAME ?? '').trim().toLowerCase();
+    if (!owner || !name)
+        return false;
+    return allowlist.includes(`${owner}/${name}`);
+}
+/**
+ * Operator bypass, two keys, BOTH required: the pusher is the operator admin
+ * account (the app pushes as admin too, so identity only excludes customers)
+ * AND the push declares a reason with `-o quonfig-rewrite=<reason>` (which is
+ * what excludes accidents). No flag-file fallback.
+ */
+function operatorBypassReason(env) {
+    const operator = (env.QUONFIG_HOOK_OPERATOR ?? '').trim();
+    const pusher = (env.GITEA_PUSHER_NAME ?? '').trim();
+    if (!operator || !pusher || pusher.toLowerCase() !== operator.toLowerCase())
+        return undefined;
+    const count = Number.parseInt(env.GIT_PUSH_OPTION_COUNT ?? '', 10);
+    if (!Number.isInteger(count))
+        return undefined;
+    for (let index = 0; index < count; index++) {
+        const option = env[`GIT_PUSH_OPTION_${index}`] ?? '';
+        if (option.startsWith(REWRITE_OPTION)) {
+            const reason = option.slice(REWRITE_OPTION.length).trim();
+            if (reason)
+                return reason;
+        }
+    }
+    return undefined;
+}
+/**
+ * `git merge-base --is-ancestor` via spawnSync, never simple-git: simple-git
+ * swallows a non-zero exit with no stderr, so a diverged pair would RESOLVE as
+ * "ancestor" and the rule would be vacuous (plan 12.2 S2). Exit 1 = not an
+ * ancestor; any other non-zero is an error and the push is rejected.
+ * The env is inherited as-is so Gitea's quarantine (GIT_QUARANTINE_PATH,
+ * GIT_OBJECT_DIRECTORY, GIT_ALTERNATE_OBJECT_DIRECTORIES) still resolves the
+ * incoming objects.
+ */
+function isAncestor(oldOid, newOid, cwd) {
+    const result = spawnSync('git', ['merge-base', '--is-ancestor', oldOid, newOid], { cwd, encoding: 'utf8' });
+    if (result.error)
+        throw result.error;
+    if (result.status === 0)
+        return true;
+    if (result.status === 1)
+        return false;
+    throw new Error(`git merge-base --is-ancestor exited ${result.status}: ${(result.stderr || '').trim()}`);
+}
+function rejection(what) {
+    return `qfg-verify: REJECTED ${MAIN_REF}: ${what}.
+
+main is append-only: every push must fast-forward from the current tip. What to do:
+
+  * Lost a race with another writer -- pull and rebase, then push again:
+      qfg pull && qfg push        (or: git pull --rebase origin main && git push origin main)
+
+  * Want the content from an earlier commit -- restore it as a FORWARD commit:
+      git restore --source=<sha> --staged --worktree -- .
+      git commit -m "restore <sha>"
+      qfg push
+
+  * This came from \`qfg workspace bootstrap\` on an older CLI, which force-pushes --
+    upgrade the CLI and run it again:
+      npm install -g @quonfig/cli@latest`;
 }
 /**
  * Read all JSON config files from a git commit using `git show`.

package/dist/verify/validate.d.ts

@@ -16,6 +16,8 @@
  *  - Log level constraints (valueType=log_level)
  *  - Referential integrity (IN_SEG/NOT_IN_SEG reference existing segments)
  *  - schemaKey references existing schemas
+ *  - Schema-bound JSON values match their schema (Ajv, opt-in via
+ *    `validateValues`; see validateBoundJsonValues)
  *  - Rule structure (criteria + value present)
  *  - Value type consistency
  *  - Weighted values non-empty and consistent
@@ -41,20 +43,32 @@ export interface ValidationStats {
     segments: number;
     uniqueKeysVerified: number;
 }
+export interface ValidateOptions {
+    /**
+     * Validate every schema-bound JSON value against its schema with Ajv
+     * (qfg-phcv). The CLI callers (`qfg verify`, `qfg push`, `qfg workspace
+     * bootstrap`, `qfg migrate --push`) turn it on. The pre-receive hook
+     * (standalone.ts) leaves it OFF until phase 1b (plan
+     * 2026-09-25-advanced-schema-for-jev.md W1b).
+     */
+    validateValues?: boolean;
+}
 export interface ValidationResult {
     filesChecked: number;
     issues: ValidationIssue[];
     stats: ValidationStats;
     valid: boolean;
 }
+/** Every directory this validator owns: config documents plus schemas. */
+export declare const KNOWN_DIRS: Set<string>;
 /**
  * Validate an entire workspace directory on disk.
  */
-export declare function validateWorkspace(workspaceDir: string): ValidationResult;
+export declare function validateWorkspace(workspaceDir: string, options?: ValidateOptions): ValidationResult;
 /**
  * Validate configs provided as a map of { "dir/file.json": jsonString }.
  * Used by the pre-receive hook which reads files from git objects.
  */
-export declare function validateFileMap(files: Map<string, string>): ValidationResult;
+export declare function validateFileMap(files: Map<string, string>, options?: ValidateOptions): ValidationResult;
 export declare function validateKey(key: string, file: string, issues: ValidationIssue[]): void;
 export declare function formatResult(result: ValidationResult): string;