@event4u/agent-config 14.9.0 → 14.11.0

package/src/scripts/_lib/ui_authority.test.ts

@@ -0,0 +1,251 @@
+/**
+ * A1.1-A1.5 behaviour, pinned against the frontend corpus fixtures.
+ *
+ * Every case name here is a real directory under `tests/eval/frontend-corpus/`,
+ * authored and hashed BEFORE this resolver existed (`34f7dc400`). That ordering
+ * is the point: the fixtures state what the right answer is, and the resolver is
+ * scored against them rather than the reverse.
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+    DEFAULTS,
+    OPERATIONS,
+    PRESERVE_DELTA_DIMENSIONS,
+    degrade,
+    operationConflicts,
+    preserveViolations,
+    resolveUiAuthority,
+    type Signals,
+} from './ui_authority.js';
+
+describe('A1.1 — one object, fully populated', () => {
+    it('always emits every required field', () => {
+        const a = resolveUiAuthority();
+        for (const k of [
+            'surface_mode',
+            'register',
+            'change_intent',
+            'reference_maturity',
+            'primary_source',
+            'constraints',
+            'conflicts',
+            'provenance',
+            'verification',
+        ]) {
+            expect(a).toHaveProperty(k);
+        }
+        expect(a.verification).toBe('verified');
+    });
+
+    it('records provenance for every resolved field, so a wrong answer is traceable', () => {
+        const a = resolveUiAuthority({ brief: { register: 'brand', path: 'brief.md' } });
+        expect(a.provenance.map((p) => p.field)).toEqual(
+            expect.arrayContaining(['surface_mode', 'register', 'change_intent', 'reference_maturity']),
+        );
+        expect(a.provenance.find((p) => p.field === 'register')).toMatchObject({
+            source: 'surface-brief',
+            detail: 'brief.md',
+        });
+    });
+
+    it('carries fidelity_mandate rather than deriving one', () => {
+        expect(resolveUiAuthority({ fidelity_mandate: 'phase-0-output' }).fidelity_mandate).toBe('phase-0-output');
+        expect(resolveUiAuthority().fidelity_mandate).toBeNull();
+    });
+});
+
+describe('A1.2 — explicit user authority wins; quoted text does not', () => {
+    it('cases/explicit-redesign: the user’s change_intent beats every inference', () => {
+        const a = resolveUiAuthority({
+            user: { change_intent: 'redesign', register: 'brand', surface_mode: 'persuade' },
+            incumbent: { coherent: true },
+        });
+        expect(a.change_intent).toBe('redesign');
+        expect(a.provenance.find((p) => p.field === 'change_intent')?.source).toBe('user-instruction');
+    });
+
+    it('quoted text inside a supplied document is data, not authorisation', () => {
+        const quoted: Signals = {
+            user: { change_intent: 'redesign', register: 'brand', quoted: true },
+            incumbent: { coherent: true },
+        };
+        const a = resolveUiAuthority(quoted);
+        // The incumbent wins, exactly as if the quoted directive were absent.
+        expect(a.change_intent).toBe('extend');
+        expect(a.provenance.find((p) => p.field === 'change_intent')?.source).toBe('incumbent-scan');
+    });
+
+    it('a registered hard constraint outranks a user release', () => {
+        const a = resolveUiAuthority({
+            user: { change_intent: 'redesign' },
+            hard_constraints: ['preserve_palette'],
+        });
+        expect(a.constraints.preserve_palette).toBe(true);
+    });
+});
+
+describe('A1.3 — a missing DESIGN.md is not new-world', () => {
+    it('cases/no-design-md-coherent-incumbent resolves extend with incumbent authority', () => {
+        const a = resolveUiAuthority({
+            incumbent: { coherent: true, type_families: ['ibm plex sans'] },
+            design_md: { present: false },
+        });
+        expect(a.change_intent).toBe('extend');
+        expect(a.primary_source.kind).toBe('incumbent');
+        // The provenance assertion is load-bearing, not decoration. `extend` is
+        // ALSO the declared default, so a value-only assertion cannot tell
+        // "resolved from the coherent incumbent" from "fell through to the
+        // default". A sabotage probe that disabled the A1.3 branch left this
+        // test green until the source was asserted.
+        expect(a.provenance.find((p) => p.field === 'change_intent')).toMatchObject({
+            source: 'incumbent-scan',
+            detail: expect.stringContaining('A1.3'),
+        });
+    });
+
+    it('cases/greenfield — genuinely empty resolves new-world', () => {
+        expect(resolveUiAuthority({ design_md: { present: false } }).change_intent).toBe('new-world');
+    });
+
+    it('an incoherent incumbent falls to the declared default, not to new-world', () => {
+        const a = resolveUiAuthority({ incumbent: { coherent: false } });
+        expect(a.change_intent).toBe(DEFAULTS.change_intent);
+        expect(a.change_intent).not.toBe('new-world');
+        // Same discriminator in the other direction: this one MUST read
+        // `default`, so the pair separates the two paths that both yield
+        // `extend`.
+        expect(a.provenance.find((p) => p.field === 'change_intent')?.source).toBe('default');
+    });
+});
+
+describe('A1.4 / A2.1 — surface-local stays local', () => {
+    it('near-miss/surface-mode-not-product-mode: the brief outranks PRODUCT.md', () => {
+        const a = resolveUiAuthority({
+            brief: { surface_mode: 'persuade', register: 'brand', path: 'brief.md' },
+            product_md: { present: true, register: 'product' },
+            incumbent: { coherent: true },
+        });
+        expect(a.surface_mode).toBe('persuade');
+        expect(a.register).toBe('brand');
+        expect(a.provenance.find((p) => p.field === 'register')?.source).toBe('surface-brief');
+    });
+
+    it('PRODUCT.md never supplies surface_mode — only the brief or the user does', () => {
+        const a = resolveUiAuthority({ product_md: { present: true, register: 'product' } });
+        expect(a.provenance.find((p) => p.field === 'surface_mode')?.source).toBe('default');
+    });
+});
+
+describe('A1.5 — the intent-aware gate, against the pre-registered threshold', () => {
+    const incumbent = {
+        palette: ['#16181d', '#ffffff', '#5b616b', '#e3e5e9'],
+        type_families: ['newsreader', 'inter'],
+    };
+
+    it('near-miss/refine-preserves-world: a palette delta under preserve blocks', () => {
+        const a = resolveUiAuthority({ user: { change_intent: 'preserve' }, incumbent: { coherent: true } });
+        const v = preserveViolations(a, incumbent, { palette: ['#16181d', '#ff6a3d'], type_families: ['newsreader'] });
+        expect(v).toHaveLength(1);
+        expect(v[0]).toContain('palette');
+        expect(v[0]).toContain('#ff6a3d');
+    });
+
+    it('a type-family delta under preserve blocks', () => {
+        const a = resolveUiAuthority({ user: { change_intent: 'preserve' } });
+        const v = preserveViolations(a, incumbent, { palette: [], type_families: ['fraunces'] });
+        expect(v).toHaveLength(1);
+        expect(v[0]).toContain('type_family');
+    });
+
+    it('near-miss/refine-preserves-world: spacing-only refinement does NOT block', () => {
+        // The whole point of the verb. Spacing, rhythm, weight and size are
+        // outside the threshold, so a refine that touches only those passes.
+        const a = resolveUiAuthority({ user: { change_intent: 'preserve' }, incumbent: { coherent: true } });
+        expect(preserveViolations(a, incumbent, incumbent)).toEqual([]);
+    });
+
+    it('cases/explicit-redesign: the same delta under redesign does NOT block', () => {
+        const a = resolveUiAuthority({ user: { change_intent: 'redesign' } });
+        expect(preserveViolations(a, incumbent, { palette: ['#ff6a3d'], type_families: ['fraunces'] })).toEqual([]);
+    });
+
+    it('transparent / currentColor / inherit are never a palette delta', () => {
+        const a = resolveUiAuthority({ user: { change_intent: 'preserve' } });
+        expect(
+            preserveViolations(a, incumbent, {
+                palette: ['transparent', 'currentColor', 'inherit'],
+                type_families: [],
+            }),
+        ).toEqual([]);
+    });
+
+    it('the threshold covers exactly the two pre-registered dimensions', () => {
+        expect([...PRESERVE_DELTA_DIMENSIONS]).toEqual(['palette', 'type_family']);
+    });
+});
+
+describe('A4.1 — six operations as one field, with a conflict path', () => {
+    it('exposes exactly the six the step names', () => {
+        expect(Object.keys(OPERATIONS).sort()).toEqual([
+            'bolder',
+            'clarify',
+            'distill',
+            'harden',
+            'polish',
+            'quieter',
+        ]);
+    });
+
+    it('bolder under preserve surfaces a conflict instead of mutating', () => {
+        const a = resolveUiAuthority({ user: { change_intent: 'preserve' } });
+        const c = operationConflicts(a, 'bolder');
+        expect(c.length).toBeGreaterThan(0);
+        expect(c.map((x) => x.dimension).sort()).toEqual(['palette', 'type_family']);
+        expect(c[0]!.blocked_by).toMatch(/^preserve_/);
+    });
+
+    it('polish under preserve is clean — it touches no locked dimension', () => {
+        const a = resolveUiAuthority({ user: { change_intent: 'preserve' } });
+        expect(operationConflicts(a, 'polish')).toEqual([]);
+    });
+
+    it('bolder under redesign is clean', () => {
+        expect(operationConflicts(resolveUiAuthority({ user: { change_intent: 'redesign' } }), 'bolder')).toEqual([]);
+    });
+});
+
+describe('graft 2 — a pass that could not run says so', () => {
+    it('degrade carries a reason', () => {
+        const d = degrade(resolveUiAuthority(), 'render artefact absent');
+        expect(d.verification).toBe('degraded');
+        expect(d.degradation_reason).toBe('render artefact absent');
+    });
+
+    it('refuses a reason-free degrade by construction', () => {
+        expect(() => degrade(resolveUiAuthority(), '   ')).toThrow(/non-empty degradation_reason/);
+    });
+
+    it('supports unverified as a distinct state', () => {
+        expect(degrade(resolveUiAuthority(), 'no host capability', 'unverified').verification).toBe('unverified');
+    });
+});
+
+describe('reference maturity — the wireframe trap', () => {
+    it('cases/wireframe: a wireframe is recorded as structure, never as a pixel mandate', () => {
+        const a = resolveUiAuthority({ reference: { maturity: 'wireframe', path: 'wireframe.md' } });
+        expect(a.reference_maturity).toBe('wireframe');
+        // `brief`, not `comp`: a wireframe does not become the visual source.
+        expect(a.primary_source.kind).toBe('brief');
+    });
+
+    it('cases/supplied-runnable-html: a runnable artifact IS the source', () => {
+        const a = resolveUiAuthority({ reference: { maturity: 'runnable-artifact', path: 'design.html' } });
+        expect(a.primary_source).toStrictEqual({ kind: 'artifact', path: 'design.html' });
+    });
+
+    it('cases/supplied-finished-comp: a comp is translated, not adopted as code', () => {
+        const a = resolveUiAuthority({ reference: { maturity: 'finished-comp', path: 'HANDOVER.md' } });
+        expect(a.primary_source.kind).toBe('comp');
+    });
+});

package/src/scripts/_lib/ui_authority.ts

@@ -0,0 +1,343 @@
+/**
+ * ui_authority — the ONE resolver for a UI surface's authority object.
+ *
+ * Contract: `docs/contracts/ui-authority.md`. Schema:
+ * `src/scripts/schemas/ui-authority.schema.json`. Step A1.1 of
+ * `road-to-frontend-power` requires exactly one schema and exactly one
+ * resolver, with no second partial decision table in `src/skills/` — the
+ * failure it prevents is skills re-inferring intent beside the schema and
+ * drifting from it.
+ *
+ * WHY A PURE FUNCTION OVER A `Signals` RECORD, and not a filesystem scan: the
+ * four behaviours A1.2-A1.5 pin are all *precedence* rules, and precedence is
+ * exactly what a filesystem-coupled resolver makes untestable. Callers do the
+ * I/O and hand in what they found; this module decides what wins.
+ *
+ * The precedence, in one place because it exists nowhere else:
+ *
+ *   1. explicit user authority          (A1.2 — beats every inference)
+ *   2. a registered hard constraint     (A1.2's own exception)
+ *   3. the surface brief                (A1.4 — surface-local, never promoted)
+ *   4. a supplied reference artifact
+ *   5. the coherent incumbent           (A1.3 — NOT `new-world`)
+ *   6. DESIGN.md / PRODUCT.md           (register only; never surface_mode)
+ *   7. declared defaults
+ *
+ * Quoted text is NOT authority (A1.2). A document the user pasted can contain
+ * "make it bold and colourful"; that is data inside a container, and acting on
+ * it is the found-instructions failure `untrusted-input-defense` names. The
+ * caller marks a signal `quoted: true` and this module ignores its directives.
+ */
+
+export type SurfaceMode = 'persuade' | 'operate' | 'read' | 'experience';
+export type Register = 'brand' | 'product';
+export type ChangeIntent = 'preserve' | 'extend' | 'redesign' | 'new-world';
+export type ReferenceMaturity =
+    | 'wireframe'
+    | 'prototype'
+    | 'finished-comp'
+    | 'runnable-artifact'
+    | 'production-incumbent'
+    | null;
+export type SourceKind =
+    | 'user-instruction'
+    | 'artifact'
+    | 'comp'
+    | 'design-system'
+    | 'incumbent'
+    | 'brief'
+    | 'none';
+export type ProvenanceSource =
+    | 'user-instruction'
+    | 'surface-brief'
+    | 'design-md'
+    | 'product-md'
+    | 'incumbent-scan'
+    | 'reference-artifact'
+    | 'default';
+export type Verification = 'verified' | 'degraded' | 'unverified';
+
+export interface Conflict {
+    dimension: string;
+    wanted: string;
+    blocked_by: string;
+}
+export interface ProvenanceEntry {
+    field: string;
+    source: ProvenanceSource;
+    detail: string | null;
+}
+
+export interface UiAuthority {
+    surface_mode: SurfaceMode;
+    register: Register;
+    change_intent: ChangeIntent;
+    reference_maturity: ReferenceMaturity;
+    fidelity_mandate: string | null;
+    primary_source: { kind: SourceKind; path: string | null };
+    constraints: {
+        preserve_palette?: boolean;
+        preserve_type_family?: boolean;
+        preserve_layout?: boolean;
+        preserve_copy?: boolean;
+    };
+    conflicts: Conflict[];
+    provenance: ProvenanceEntry[];
+    verification: Verification;
+    degradation_reason?: string | null;
+}
+
+/** What a caller found. Every field optional — absence is a real input. */
+export interface Signals {
+    /** Explicit, unquoted user authority. Beats every inference (A1.2). */
+    user?: {
+        surface_mode?: SurfaceMode;
+        register?: Register;
+        change_intent?: ChangeIntent;
+        /** True when the text came from INSIDE a supplied document (A1.2). */
+        quoted?: boolean;
+    };
+    /** A surface-local brief. Never mutates DESIGN.md / PRODUCT.md (A1.4). */
+    brief?: { surface_mode?: SurfaceMode; register?: Register; path?: string };
+    /** A supplied reference and how finished it is. */
+    reference?: { maturity: Exclude<ReferenceMaturity, null>; path?: string };
+    /** Result of an incumbent scan — typically from `ui:audit`. */
+    incumbent?: { coherent: boolean; palette?: string[]; type_families?: string[] };
+    /** Presence and register of the repo-level documents. */
+    design_md?: { present: boolean; register?: Register };
+    product_md?: { present: boolean; register?: Register };
+    /** Carried from the fidelity roadmap's Phase 0, never derived here. */
+    fidelity_mandate?: string | null;
+    /** A registered hard constraint outranks even explicit user authority. */
+    hard_constraints?: Array<keyof UiAuthority['constraints']>;
+}
+
+/** Declared defaults, in one place so "where did this come from" has an answer. */
+export const DEFAULTS = {
+    surface_mode: 'operate' as SurfaceMode,
+    register: 'product' as Register,
+    change_intent: 'extend' as ChangeIntent,
+} as const;
+
+/**
+ * A1.5's threshold, pre-registered in `internal/bench/frontend-power-PREREG.md`
+ * § A1.5's delta threshold and NOT chosen here. Palette and type family only —
+ * spacing, radius, weight, size and layout are deliberately excluded so
+ * `polish` and `refine` can move them under `preserve`, which is the whole
+ * point of those verbs.
+ */
+export const PRESERVE_DELTA_DIMENSIONS = ['palette', 'type_family'] as const;
+/** Colour keywords that are never a palette delta. */
+const PALETTE_NEUTRALS = new Set(['transparent', 'currentcolor', 'inherit', 'unset', 'initial']);
+
+export function resolveUiAuthority(signals: Signals = {}): UiAuthority {
+    const provenance: ProvenanceEntry[] = [];
+    const conflicts: Conflict[] = [];
+    const note = (field: string, source: ProvenanceSource, detail: string | null = null): void => {
+        provenance.push({ field, source, detail });
+    };
+
+    // A1.2 — quoted text inside a supplied document is data, not authorisation.
+    const user = signals.user?.quoted ? undefined : signals.user;
+
+    // surface_mode: user → brief → default. DESIGN.md/PRODUCT.md never supply
+    // it (A2.1: the surface job is per-surface, persisted in the brief).
+    let surface_mode: SurfaceMode;
+    if (user?.surface_mode) {
+        surface_mode = user.surface_mode;
+        note('surface_mode', 'user-instruction');
+    } else if (signals.brief?.surface_mode) {
+        surface_mode = signals.brief.surface_mode;
+        note('surface_mode', 'surface-brief', signals.brief.path ?? null);
+    } else {
+        surface_mode = DEFAULTS.surface_mode;
+        note('surface_mode', 'default', 'no user or brief signal');
+    }
+
+    // register: user → brief → DESIGN.md → PRODUCT.md → default. The brief
+    // outranks PRODUCT.md, which is the `surface-mode-not-product-mode` case:
+    // a brand surface inside a product repo must not inherit `product`.
+    let register: Register;
+    if (user?.register) {
+        register = user.register;
+        note('register', 'user-instruction');
+    } else if (signals.brief?.register) {
+        register = signals.brief.register;
+        note('register', 'surface-brief', signals.brief.path ?? null);
+    } else if (signals.design_md?.present && signals.design_md.register) {
+        register = signals.design_md.register;
+        note('register', 'design-md');
+    } else if (signals.product_md?.present && signals.product_md.register) {
+        register = signals.product_md.register;
+        note('register', 'product-md');
+    } else {
+        register = DEFAULTS.register;
+        note('register', 'default', 'no register signal');
+    }
+
+    // change_intent: user → (incumbent coherence) → default.
+    //
+    // A1.3 is the load-bearing branch: a MISSING DESIGN.md is not `new-world`.
+    // A coherent incumbent resolves to `extend` with incumbent authority, and
+    // only a genuinely empty surface — no incumbent, no reference — is
+    // `new-world`.
+    let change_intent: ChangeIntent;
+    if (user?.change_intent) {
+        change_intent = user.change_intent;
+        note('change_intent', 'user-instruction');
+    } else if (signals.incumbent?.coherent) {
+        change_intent = 'extend';
+        note('change_intent', 'incumbent-scan', 'coherent incumbent — not new-world (A1.3)');
+    } else if (!signals.incumbent && !signals.reference && !signals.design_md?.present) {
+        change_intent = 'new-world';
+        note('change_intent', 'default', 'no incumbent, no reference, no DESIGN.md');
+    } else {
+        change_intent = DEFAULTS.change_intent;
+        note('change_intent', 'default', 'incumbent present but incoherent');
+    }
+
+    const reference_maturity: ReferenceMaturity = signals.reference?.maturity ?? null;
+    note(
+        'reference_maturity',
+        signals.reference ? 'reference-artifact' : 'default',
+        signals.reference?.path ?? 'no reference supplied',
+    );
+
+    // primary_source — which authority the run builds FROM.
+    let kind: SourceKind = 'none';
+    let sourcePath: string | null = null;
+    if (signals.reference) {
+        kind =
+            signals.reference.maturity === 'runnable-artifact'
+                ? 'artifact'
+                : signals.reference.maturity === 'finished-comp'
+                  ? 'comp'
+                  : signals.reference.maturity === 'production-incumbent'
+                    ? 'incumbent'
+                    : 'brief';
+        sourcePath = signals.reference.path ?? null;
+    } else if (signals.incumbent?.coherent) {
+        kind = 'incumbent';
+    } else if (signals.design_md?.present) {
+        kind = 'design-system';
+    } else if (signals.brief) {
+        kind = 'brief';
+        sourcePath = signals.brief.path ?? null;
+    } else if (user) {
+        kind = 'user-instruction';
+    }
+    note('primary_source', signals.reference ? 'reference-artifact' : 'incumbent-scan', kind);
+
+    // constraints — `preserve` implies the visual world is locked. A hard
+    // constraint is additive and, per A1.2, outranks explicit user authority.
+    const constraints: UiAuthority['constraints'] = {};
+    if (change_intent === 'preserve') {
+        constraints.preserve_palette = true;
+        constraints.preserve_type_family = true;
+    }
+    for (const c of signals.hard_constraints ?? []) {
+        if (constraints[c] === false) {
+            conflicts.push({
+                dimension: c,
+                wanted: 'released by user instruction',
+                blocked_by: 'registered hard constraint',
+            });
+        }
+        constraints[c] = true;
+    }
+
+    return {
+        surface_mode,
+        register,
+        change_intent,
+        reference_maturity,
+        fidelity_mandate: signals.fidelity_mandate ?? null,
+        primary_source: { kind, path: sourcePath },
+        constraints,
+        conflicts,
+        provenance,
+        verification: 'verified',
+    };
+}
+
+/** Mark an object degraded. Refuses a reason-free degrade by construction. */
+export function degrade(a: UiAuthority, reason: string, state: Exclude<Verification, 'verified'> = 'degraded'): UiAuthority {
+    if (!reason.trim()) throw new Error('degrade() requires a non-empty degradation_reason');
+    return { ...a, verification: state, degradation_reason: reason };
+}
+
+export interface WorldSnapshot {
+    palette: readonly string[];
+    type_families: readonly string[];
+}
+
+const norm = (s: string): string => s.trim().toLowerCase();
+
+/**
+ * A1.5 — the intent-aware gate. Returns the dimensions that changed and are
+ * NOT authorised by `change_intent`. Empty array = the write may proceed.
+ *
+ * Under `preserve` a palette or type-family delta blocks; under `redesign` and
+ * `new-world` nothing here blocks. `extend` sits in between and is treated as
+ * permissive on this axis deliberately: extending a surface routinely adds a
+ * semantic colour, and blocking that would make the verb unusable.
+ */
+export function preserveViolations(
+    authority: UiAuthority,
+    incumbent: WorldSnapshot,
+    proposed: WorldSnapshot,
+): string[] {
+    if (authority.change_intent !== 'preserve') return [];
+    const out: string[] = [];
+
+    if (authority.constraints.preserve_palette) {
+        const known = new Set(incumbent.palette.map(norm));
+        const added = proposed.palette.map(norm).filter((c) => !known.has(c) && !PALETTE_NEUTRALS.has(c));
+        if (added.length) out.push(`palette: ${[...new Set(added)].sort().join(', ')}`);
+    }
+    if (authority.constraints.preserve_type_family) {
+        const known = new Set(incumbent.type_families.map(norm));
+        const added = proposed.type_families.map(norm).filter((f) => !known.has(f));
+        if (added.length) out.push(`type_family: ${[...new Set(added)].sort().join(', ')}`);
+    }
+    return out;
+}
+
+/**
+ * A4.1 — the six intervention operations as values of ONE field rather than as
+ * six commands. Each declares the dimensions it may touch, so a collision with
+ * a constraint is decidable instead of a judgement call.
+ */
+export const OPERATIONS = {
+    polish: ['spacing', 'rhythm', 'alignment'],
+    quieter: ['spacing', 'weight', 'contrast_within_palette'],
+    bolder: ['palette', 'type_family', 'weight', 'scale'],
+    distill: ['content_density', 'spacing'],
+    harden: ['a11y', 'focus', 'contrast_within_palette'],
+    clarify: ['hierarchy', 'copy', 'labels'],
+} as const;
+export type Operation = keyof typeof OPERATIONS;
+
+/** Maps an operation dimension onto the constraint that would forbid it. */
+const DIMENSION_CONSTRAINT: Readonly<Record<string, keyof UiAuthority['constraints']>> = {
+    palette: 'preserve_palette',
+    type_family: 'preserve_type_family',
+    hierarchy: 'preserve_layout',
+    copy: 'preserve_copy',
+    labels: 'preserve_copy',
+};
+
+/**
+ * A4.1 — does `op` collide with the authority's constraints? A collision is
+ * returned as conflicts to APPEND; the caller performs no write. `bolder`
+ * under `preserve` is the pinned case.
+ */
+export function operationConflicts(authority: UiAuthority, op: Operation): Conflict[] {
+    const out: Conflict[] = [];
+    for (const dim of OPERATIONS[op] as readonly string[]) {
+        const c = DIMENSION_CONSTRAINT[dim];
+        if (!c || authority.constraints[c] !== true) continue;
+        out.push({ dimension: dim, wanted: `${op} may move ${dim}`, blocked_by: c });
+    }
+    return out;
+}

package/src/scripts/ai-video/adapters/fal.sh

@@ -288,9 +288,14 @@ aiv_fal_capability() {
     jq -e --arg m "${model}" '.models[$m]' "${FAL_MANIFEST}" >/dev/null 2>&1 \
       || aiv_die 7 "${ADAPTER_ID}: model not in manifest: ${model}"
     _fal_warn_unverified "${model}"
-    jq --arg m "${model}" \
-      '.models[$m] | {audio: (if .audio_sync then "native" else "none" end), model: $m} + .' \
-      "${FAL_MANIFEST}"
+    # Emission goes through the shared helper so the decay markers
+    # (`verified_at` / `recheck_by`, derived from the trace index) appear here
+    # too. fal is the adapter that actually CARRIES smoke_trace ids, so a
+    # capability path that skipped them would leave the only traced adapter as
+    # the one place the dates are invisible. Model validation, the
+    # manifest-missing check and the unverified warning stay above — this
+    # replaces the JSON emission only.
+    aiv_capability_recheck "${ADAPTER_ID}" "${model}" "${FAL_MANIFEST}"
     return 0
   fi
   if [ -f "${FAL_MANIFEST}" ] && command -v jq >/dev/null 2>&1; then

package/src/scripts/ai-video/adapters/gemini-veo.sh

@@ -243,4 +243,14 @@ aiv_cmd_fetch() {
   jq -n --arg p "${out}" '{video_path:$p, audio_embedded:true}'
 }
 
+# Capability: `capability --model <id>` answers from
+# lib/model-capabilities/gemini-veo.json (schema v2 — durations, modeled cost,
+# and the start_frame/end_frame continuity answers). A bare `capability`
+# keeps the adapter-level audio flag byte-identical to before the manifest.
+sub="${1:-}"
+if [ "${sub}" = "capability" ]; then
+  shift
+  aiv_manifest_capability "${ADAPTER_ID}" "native" "$@"
+  exit 0
+fi
 aiv_dispatch "${ADAPTER_ID}" "native" "$@"

package/src/scripts/ai-video/adapters/higgsfield.sh

@@ -41,15 +41,23 @@ higgsfield_audio_for_preset() {
 }
 
 # Override capability handling so `capability --preset <name>` answers
-# per-preset before falling through to the generic helper.
+# per-preset, and `capability --model <id>` answers from
+# lib/model-capabilities/higgsfield.json (schema v2), before falling through
+# to the generic helper. Presets and models are different axes: a preset is a
+# motion profile, a model is the DoP endpoint's checkpoint.
 aiv_higgsfield_capability() {
-  local preset=""
+  local preset="" model=""
   while [ "$#" -gt 0 ]; do
     case "$1" in
       --preset) preset="${2:-}"; shift 2 ;;
+      --model) model="${2:-}"; shift 2 ;;
       *) shift ;;
     esac
   done
+  if [ -n "${model}" ]; then
+    aiv_manifest_capability "${ADAPTER_ID}" "per-model" --model "${model}"
+    return 0
+  fi
   if [ -n "${preset}" ]; then
     printf '{"audio":"%s","preset":"%s"}\n' \
       "$(higgsfield_audio_for_preset "${preset}")" "${preset}"

package/src/scripts/ai-video/adapters/kling.sh

@@ -245,4 +245,14 @@ aiv_cmd_fetch() {
   jq -n --arg p "${out}" '{video_path:$p, audio_embedded:false}'
 }
 
+# Capability: `capability --model <id>` answers from
+# lib/model-capabilities/kling.json (schema v2 — durations, modeled cost,
+# and the start_frame/end_frame continuity answers). A bare `capability`
+# keeps the adapter-level audio flag byte-identical to before the manifest.
+sub="${1:-}"
+if [ "${sub}" = "capability" ]; then
+  shift
+  aiv_manifest_capability "${ADAPTER_ID}" "none" "$@"
+  exit 0
+fi
 aiv_dispatch "${ADAPTER_ID}" "none" "$@"