@jevitate/cli 0.10.0 → 0.11.0

package/dist/catalog-bundle.d.ts

@@ -18,23 +18,30 @@ import { CatalogInputError, type Catalog } from "./catalog.js";
  *  - checks: one per check item that ran, keyed (target.id, commit, runId); a baseline only from a
  *    clean run whose `journeyHash` is the exported Journey's approved hash.
  *  - findings: whatever the d464c source hands in (`CatalogBundleFinding`), guarded; none by default.
- *  - demos and media: NONE in 0.10 — a demo must carry the jz-mask-v1 + synthetic-data attestation,
- *    which jevitate cannot make yet, and the contract says a producer that cannot meet it exports no
- *    media. So no `demos`, no `files`.
+ *  - demos and media (#471): one `demos[]` entry per exported, APPROVED Journey that has an
+ *    approved-demo record (approved-demo.ts: written by `demo approve` only on a `synthetic: true`
+ *    environment, from a jz-mask-v1 render), whose `renderedFrom` is the Journey's current approved
+ *    hash. Its `privacy` is the record's attestation. Media is only what the record proved masked
+ *    and the API re-verified (present, same sha256, the right file type): `media/<id>/step-NN.png`,
+ *    `media/<id>/demo.webm` and `demo.vtt` (subtitles only with the video), each listed in `files[]`.
+ *    Over a §10 limit (2 MiB / 50 MiB / 256 KiB per file, 512 MiB and 4,000 files per bundle), a
+ *    file is left out with a warning, never sent. A demo whose caption breaks §7's text rules is
+ *    left out whole (its subtitles carry the same text). A draft demo has no record: never exported.
  *  - `generatedAt` is left out on purpose: the same catalog gives the same bytes, so the upload's
  *    `Idempotency-Key` (sha256 of bundle.json) dedupes a re-publish.
  *
  * Failure policy: personal data or a credential typed in clear anywhere, or a job the bundle cannot
  * carry (a structural reference problem, text that is not one line), REFUSES the export
- * (`CatalogBundleInputError`, exit 64) — nothing is guessed or silently rewritten. A Journey or a
- * check the bundle cannot carry is LEFT OUT with a warning (nothing else references it in a way the
+ * (`CatalogBundleInputError`, exit 64) — nothing is guessed or silently rewritten. So does a
+ * PROMOTED Journey the bundle cannot carry (#478: never a silent omission). A draft Journey, or a
+ * check the bundle cannot carry, is LEFT OUT with a warning (nothing else references it in a way the
  * reader would refuse). A persona key the bundle cannot carry drops that key and the persona's
  * approval (its hash could not recompute) with a warning.
  */
 export declare const BUNDLE_KIND: "journeeze.catalog-bundle";
 export declare const BUNDLE_VERSION: 1;
-/** The schema minor this producer is built against (contract 61f8c92). */
-export declare const BUNDLE_MINOR: 0;
+/** The schema minor this producer is built against (minor 1, journeeze-saas #173: optional `finding.locator` and `check.appVersion`). */
+export declare const BUNDLE_MINOR: 1;
 export interface BundleApproval {
     readonly contentHash: string;
     readonly at: string;
@@ -90,6 +97,8 @@ export interface BundleCheck {
         readonly kind?: BundleCheckTargetKind;
     };
     readonly commit: string;
+    /** #479 (spec minor 1 §2): the app's release/version label the check ran against; `commit` stays the build identity. */
+    readonly appVersion?: string;
     readonly at: string;
     readonly runId?: string;
     readonly journey?: string;
@@ -101,6 +110,18 @@ export interface BundleCheck {
     readonly durationMs?: number;
     readonly baseline?: BundleBaseline;
 }
+export interface BundleLocator {
+    /** The element in words, e.g. `the "Save" button`. One printable line, 1-200, no URL or personal data. */
+    readonly element: string;
+    /** The attribute the fix adds (the convention's first). */
+    readonly attribute: string;
+    /** The suggested test id. */
+    readonly testId: string;
+    /** The fix, e.g. `add data-testid="save-contact" to the "Save" button on /contacts/new`. One line, 1-300. */
+    readonly fix: string;
+    /** The steps (across Journeys) that use the element. */
+    readonly steps: number;
+}
 /**
  * d464c HOOK: one machine finding as the contract's `findings[]` carries it (§4.4) — UX claims with
  * the derived fingerprint, defects and hangs with jevitate's. 0.10 exports no media, so no
@@ -127,11 +148,47 @@ export interface CatalogBundleFinding {
     readonly observation: string;
     readonly userImpact?: string;
     readonly recommendation?: string;
+    /** Minor 1 (§1): the brittle-element fix; only on kind `ux` + claim `other` + producerClaim `locator-brittle`, required there. */
+    readonly locator?: BundleLocator;
     readonly citation?: {
         readonly source: string;
         readonly ref: string;
     };
 }
+/** #471: one guide step of a demo (contract §4.2). */
+export interface BundleDemoStep {
+    readonly number: number;
+    readonly caption: string;
+    readonly expected?: string;
+    /** `media/<journey>/step-NN.png`. */
+    readonly screenshot?: string;
+}
+/** #471: the jz-mask-v1 + synthetic-data attestation every demo carries (contract §7). */
+export interface BundlePrivacy {
+    readonly mask: "jz-mask-v1";
+    readonly data: "synthetic";
+    readonly method: "dom-before-capture" | "pixels-after-capture";
+    readonly regions: number;
+}
+/** #471: one approved demo's media manifest (contract §4.2). */
+export interface BundleDemo {
+    readonly journey: string;
+    readonly renderedFrom: string;
+    readonly status: "approved";
+    readonly title?: string;
+    readonly steps: readonly BundleDemoStep[];
+    readonly video?: string;
+    readonly subtitles?: string;
+    readonly privacy: BundlePrivacy;
+}
+export type BundleFileType = "image/png" | "image/webp" | "video/webm" | "text/vtt";
+/** #471: one media file of the bundle (contract §2): listed ⇔ present ⇔ referenced. */
+export interface BundleFile {
+    readonly path: string;
+    readonly sha256: string;
+    readonly bytes: number;
+    readonly type: BundleFileType;
+}
 export interface CatalogBundleV1 {
     readonly kind: typeof BUNDLE_KIND;
     readonly version: typeof BUNDLE_VERSION;
@@ -149,8 +206,40 @@ export interface CatalogBundleV1 {
         readonly jobs: readonly BundleJob[];
         readonly journeys: readonly BundleJourneyEntry[];
     };
+    /** #471: present (with `files`) only when at least one approved demo is exported. */
+    readonly demos?: readonly BundleDemo[];
     readonly checks: readonly BundleCheck[];
     readonly findings: readonly CatalogBundleFinding[];
+    readonly files?: readonly BundleFile[];
+}
+/**
+ * #471: an approved demo as the API hands it in: the record's manifest, and the media files the API
+ * re-verified on disk (present, sha256 and size as recorded, the right file type), by record name.
+ */
+export interface CatalogBundleDemoInput {
+    readonly journey: string;
+    readonly renderedFrom: string;
+    readonly title?: string;
+    readonly steps: ReadonlyArray<{
+        readonly number: number;
+        readonly caption: string;
+        readonly expected?: string;
+        readonly screenshot?: string;
+    }>;
+    readonly video?: string;
+    readonly subtitles?: string;
+    readonly privacy: BundlePrivacy;
+    /** Verified media by record file name (`step-01.png`, `demo.webm`, `demo.vtt`): `source` is the file on disk. */
+    readonly media: Readonly<Record<string, {
+        readonly source: string;
+        readonly sha256: string;
+        readonly bytes: number;
+    }>>;
+}
+/** #471: a media file to place in the bundle: `source` on disk → `path` under the bundle root. */
+export interface BundleMediaCopy {
+    readonly path: string;
+    readonly source: string;
 }
 /** One `jevitate check` record (`check.json`'s `data`, or the bare result) and where it came from. */
 export interface CheckRecordInput {
@@ -170,9 +259,13 @@ export interface CatalogBundleInput {
     readonly checks: readonly CheckRecordInput[];
     /** d464c: the machine findings to export (default none). */
     readonly findings?: readonly CatalogBundleFinding[];
+    /** #471: approved demos with their verified media (default none). */
+    readonly demos?: readonly CatalogBundleDemoInput[];
 }
 export interface CatalogBundleBuild {
     readonly bundle: CatalogBundleV1;
+    /** #471: the media files to place beside bundle.json (exactly `bundle.files`, with their sources). */
+    readonly media: readonly BundleMediaCopy[];
     /** Items left out or degraded, each with why. */
     readonly warnings: readonly string[];
 }
@@ -182,10 +275,21 @@ export declare class CatalogBundleInputError extends CatalogInputError {
     readonly code: string;
     constructor(issues: readonly string[]);
 }
+/** #471: contract §10's media limits. */
+export declare const MEDIA_LIMITS: {
+    readonly screenshotBytes: number;
+    readonly videoBytes: number;
+    readonly subtitlesBytes: number;
+    readonly totalBytes: number;
+    readonly files: 4000;
+    readonly demoSteps: 200;
+};
 /** Looks like personal data (an email, or 9+ digits) — the contract's `noPersonalData`. */
 export declare function looksPersonal(s: string): boolean;
 /** The contract's `routeTemplate`: a path template — no query string, fragment, host or record id. */
 export declare function isRouteTemplate(route: string): boolean;
+/** Why a subtitles file's text breaks §7 (a cue line that is not machine text, a DRAFT note), or null. */
+export declare function subtitlesTextProblem(vtt: string): string | null;
 /** Why a finding handed in by the d464c source breaks the contract's privacy rules (§7), or []. */
 export declare function findingIssues(f: CatalogBundleFinding): string[];
 /** Builds the bundle (pure). Throws `CatalogBundleInputError` when the catalog cannot be exported. */

package/dist/catalog-bundle.js

@@ -20,24 +20,31 @@ import { describeRefIssue, jobRefIssues, journeyRefIssues, RESERVED_ANCHORS } fr
  *  - checks: one per check item that ran, keyed (target.id, commit, runId); a baseline only from a
  *    clean run whose `journeyHash` is the exported Journey's approved hash.
  *  - findings: whatever the d464c source hands in (`CatalogBundleFinding`), guarded; none by default.
- *  - demos and media: NONE in 0.10 — a demo must carry the jz-mask-v1 + synthetic-data attestation,
- *    which jevitate cannot make yet, and the contract says a producer that cannot meet it exports no
- *    media. So no `demos`, no `files`.
+ *  - demos and media (#471): one `demos[]` entry per exported, APPROVED Journey that has an
+ *    approved-demo record (approved-demo.ts: written by `demo approve` only on a `synthetic: true`
+ *    environment, from a jz-mask-v1 render), whose `renderedFrom` is the Journey's current approved
+ *    hash. Its `privacy` is the record's attestation. Media is only what the record proved masked
+ *    and the API re-verified (present, same sha256, the right file type): `media/<id>/step-NN.png`,
+ *    `media/<id>/demo.webm` and `demo.vtt` (subtitles only with the video), each listed in `files[]`.
+ *    Over a §10 limit (2 MiB / 50 MiB / 256 KiB per file, 512 MiB and 4,000 files per bundle), a
+ *    file is left out with a warning, never sent. A demo whose caption breaks §7's text rules is
+ *    left out whole (its subtitles carry the same text). A draft demo has no record: never exported.
  *  - `generatedAt` is left out on purpose: the same catalog gives the same bytes, so the upload's
  *    `Idempotency-Key` (sha256 of bundle.json) dedupes a re-publish.
  *
  * Failure policy: personal data or a credential typed in clear anywhere, or a job the bundle cannot
  * carry (a structural reference problem, text that is not one line), REFUSES the export
- * (`CatalogBundleInputError`, exit 64) — nothing is guessed or silently rewritten. A Journey or a
- * check the bundle cannot carry is LEFT OUT with a warning (nothing else references it in a way the
+ * (`CatalogBundleInputError`, exit 64) — nothing is guessed or silently rewritten. So does a
+ * PROMOTED Journey the bundle cannot carry (#478: never a silent omission). A draft Journey, or a
+ * check the bundle cannot carry, is LEFT OUT with a warning (nothing else references it in a way the
  * reader would refuse). A persona key the bundle cannot carry drops that key and the persona's
  * approval (its hash could not recompute) with a warning.
  */
 // ── The bundle (catalog-bundle.v1.json), as jevitate produces it ─────────────────────────────
 export const BUNDLE_KIND = "journeeze.catalog-bundle";
 export const BUNDLE_VERSION = 1;
-/** The schema minor this producer is built against (contract 61f8c92). */
-export const BUNDLE_MINOR = 0;
+/** The schema minor this producer is built against (minor 1, journeeze-saas #173: optional `finding.locator` and `check.appVersion`). */
+export const BUNDLE_MINOR = 1;
 export const CHECK_TARGET_KINDS = ["journey", "goal", "mission", "invariant", "verify_fix", "regression"];
 /** The catalog cannot be exported as it is (personal data, a credential typed in clear, a job the bundle cannot carry) — exit 64. */
 export class CatalogBundleInputError extends CatalogInputError {
@@ -56,6 +63,7 @@ const COMMIT_RE = /^[0-9a-f]{7,40}$/;
 const SEMVER_RE = /^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]{1,40})?$/;
 const DATE_TIME_RE = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$/;
 const RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const APP_VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
 const FAILURE_KIND_RE = /^[a-z][a-z0-9-]{0,63}$/;
 const OTHER_FIELD_KEY_RE = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
 const ONE_LINE_RE = /^(?=.*\S)[^\u0000-\u001f\u007f]+$/u;
@@ -69,13 +77,25 @@ const RECORD_ID_RES = [
 const ROUTE_TEMPLATE_RE = /^(\/(\{[A-Za-z][A-Za-z0-9_]{0,63}\}|[A-Za-z0-9._~-]+))*\/?$/u;
 const TFLOW_ID_RE = /^[a-z0-9._:-]{1,96}$/u;
 const FINGERPRINT_RE = /^[0-9a-f]{16}$/u;
+const LOCATOR_ATTRIBUTE_RE = /^[a-z][a-z0-9-]{0,39}$/u;
+const LOCATOR_TEST_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,99}$/u;
+const LOCATOR_MAX_STEPS = 10_000;
 const APPROVAL_CHANNELS = new Set(["tty", "mcp", "ci", "non-interactive", "pr-review", "other"]);
 const RESERVED = new Set(RESERVED_ANCHORS);
 const SESSION_KEYS = new Set(["storageState", "login"]);
 const PERSONA_NAMED_KEYS = new Set(["id", "name", "description", "role", "approval", "storageState", "login"]);
 const MAX_MS = 86_400_000;
 const MAX_STEP = 200;
-const LIMITS = { personas: 200, jobs: 500, journeys: 1000, checks: 5000, findings: 5000 };
+const LIMITS = { personas: 200, jobs: 500, journeys: 1000, checks: 5000, findings: 5000, demos: 1000 };
+/** #471: contract §10's media limits. */
+export const MEDIA_LIMITS = {
+    screenshotBytes: 2 * 1024 * 1024,
+    videoBytes: 50 * 1024 * 1024,
+    subtitlesBytes: 256 * 1024,
+    totalBytes: 512 * 1024 * 1024,
+    files: 4000,
+    demoSteps: 200,
+};
 /** Looks like personal data (an email, or 9+ digits) — the contract's `noPersonalData`. */
 export function looksPersonal(s) {
     return PERSONAL_DATA_RES.some((re) => re.test(s));
@@ -329,8 +349,9 @@ function bundleJourneys(catalog, refuse, warn) {
                 refuse.push(`journey ${cj.id}: ${c.path.slice(1)} types personal data in clear (an email or 9+ digits) — use a parameter or a synthetic value`);
         }
         const linked = journeyLink(catalog, cj);
+        // #478: a promoted Journey the bundle cannot carry refuses the export — never a silent omission.
         if ("omit" in linked) {
-            warn.push(`journey ${cj.id}: ${linked.omit} — left out`);
+            refuse.push(`journey ${cj.id}: ${linked.omit} — fix it (the bundle cannot carry it), or demote it`);
             continue;
         }
         const file = asJson(cj.journey);
@@ -446,6 +467,16 @@ function bundleChecks(input, journeys, warn) {
             warn.push(`${source}: the check names no commit (run it with --target-build <commit sha>) — its items are left out`);
             continue;
         }
+        // #479 (spec minor 1 §2): the app's release label travels beside the commit; an invalid one is
+        // left out with a warning (the check itself still exports).
+        const rawAppVersion = typeof data.appVersion === "string" ? data.appVersion : undefined;
+        let appVersion;
+        if (rawAppVersion !== undefined) {
+            if (APP_VERSION_RE.test(rawAppVersion))
+                appVersion = rawAppVersion;
+            else
+                warn.push(`${source}: the check's appVersion is not a release label (1-64 of [A-Za-z0-9._+-], starting alphanumeric) — left out`);
+        }
         const at = typeof data.startedAt === "string" ? data.startedAt : "";
         if (!DATE_TIME_RE.test(at)) {
             warn.push(`${source}: the check's start time is not an ISO date-time — its items are left out`);
@@ -493,6 +524,7 @@ function bundleChecks(input, journeys, warn) {
             const check = {
                 target: { id, ...(kind === undefined ? {} : { kind }) },
                 commit,
+                ...(appVersion === undefined ? {} : { appVersion }),
                 at,
                 runId,
                 ...(journeyId === undefined ? {} : { journey: journeyId }),
@@ -509,6 +541,147 @@ function bundleChecks(input, journeys, warn) {
     }
     return [...out.values()].sort((a, b) => a.at.localeCompare(b.at) || a.target.id.localeCompare(b.target.id) || (a.runId ?? "").localeCompare(b.runId ?? ""));
 }
+// ── Demos and media (#471) ─────────────────────────────────────────────────────────────────
+/** Why a subtitles file's text breaks §7 (a cue line that is not machine text, a DRAFT note), or null. */
+export function subtitlesTextProblem(vtt) {
+    const lines = vtt.split(/\r?\n/u);
+    if (lines[0]?.trim() !== "WEBVTT")
+        return "it does not start with WEBVTT";
+    for (const [i, raw] of lines.entries()) {
+        const line = raw.trim();
+        if (i === 0 || line === "" || /^step-[0-9]{1,3}$/u.test(line) || /^[0-9:.]+ --> [0-9:.]+$/u.test(line))
+            continue;
+        if (/^NOTE\b/u.test(line))
+            return "it carries a NOTE block";
+        const p = machineTextProblem(line, 600);
+        if (p !== null)
+            return `a cue ${p}`;
+    }
+    return null;
+}
+function bundleDemos(input, journeys, warn) {
+    const demos = [];
+    const files = [];
+    const media = [];
+    let total = 0;
+    const byId = new Map(journeys.map((j) => [j.cj.id, j]));
+    const sorted = [...(input.demos ?? [])].sort((a, b) => (a.journey < b.journey ? -1 : a.journey > b.journey ? 1 : 0));
+    for (const d of sorted) {
+        const where = `demo ${d.journey}`;
+        const ex = byId.get(d.journey);
+        if (ex === undefined) {
+            warn.push(`${where}: its Journey is not in the bundle (not promoted, or left out) — the demo is left out`);
+            continue;
+        }
+        const approved = ex.cj.approval !== undefined && ex.cj.approval.contentHash === ex.cj.contentHash;
+        if (!approved) {
+            warn.push(`${where}: its Journey changed since it was approved — the demo is left out (approve the Journey and its demo again)`);
+            continue;
+        }
+        if (d.renderedFrom !== ex.cj.contentHash) {
+            warn.push(`${where}: rendered from another version of its Journey (${d.renderedFrom.slice(0, 12)}, approved ${ex.cj.contentHash.slice(0, 12)}) — the demo is left out (run \`jevitate demo approve\` again)`);
+            continue;
+        }
+        if (d.steps.length === 0 || d.steps.length > MEDIA_LIMITS.demoSteps) {
+            warn.push(`${where}: ${d.steps.length} steps (a demo has 1-${MEDIA_LIMITS.demoSteps}) — the demo is left out`);
+            continue;
+        }
+        const captionIssues = d.steps.flatMap((s) => {
+            const p = machineTextProblem(s.caption, 200);
+            return p === null ? [] : [`step ${s.number} caption ${p}`];
+        });
+        if (captionIssues.length > 0) {
+            warn.push(`${where}: ${captionIssues.join("; ")} — the demo is left out (captions are producer text: one line, no personal data, URL or record id)`);
+            continue;
+        }
+        let title;
+        if (d.title !== undefined) {
+            const p = machineTextProblem(d.title, 200);
+            if (p !== null)
+                warn.push(`${where}: title ${p} — sent without a title`);
+            else if (/^DRAFT/u.test(d.title))
+                warn.push(`${where}: title starts with DRAFT — sent without a title`);
+            else
+                title = d.title;
+        }
+        // Media, each within its per-file and the bundle's limits; a left-out file is never referenced.
+        const dir = `media/${d.journey}`;
+        const take = (name, type, max, what) => {
+            if (name === undefined)
+                return undefined;
+            const f = d.media[name];
+            if (f === undefined)
+                return undefined; // the API already warned why
+            if (f.bytes > max) {
+                warn.push(`${where}: ${what} ${name} is ${f.bytes} bytes, over the contract's ${max} — left out`);
+                return undefined;
+            }
+            if (files.length + 1 > MEDIA_LIMITS.files || total + f.bytes > MEDIA_LIMITS.totalBytes) {
+                warn.push(`${where}: ${what} ${name} would take the bundle over ${MEDIA_LIMITS.files} files or ${MEDIA_LIMITS.totalBytes} bytes of media — left out`);
+                return undefined;
+            }
+            const path = `${dir}/${name}`;
+            files.push({ path, sha256: f.sha256, bytes: f.bytes, type });
+            media.push({ path, source: f.source });
+            total += f.bytes;
+            return path;
+        };
+        const steps = d.steps.map((s) => {
+            let expected;
+            if (s.expected !== undefined) {
+                const p = machineTextProblem(s.expected, 500);
+                if (p !== null)
+                    warn.push(`${where}: step ${s.number} expected result ${p} — sent without it`);
+                else
+                    expected = s.expected;
+            }
+            const shot = s.screenshot !== undefined && /^step-[0-9]{2,3}\.png$/u.test(s.screenshot) ? take(s.screenshot, "image/png", MEDIA_LIMITS.screenshotBytes, "screenshot") : undefined;
+            return { number: s.number, caption: s.caption, ...(expected === undefined ? {} : { expected }), ...(shot === undefined ? {} : { screenshot: shot }) };
+        });
+        // Subtitles only with their video: reserve both or neither.
+        let video;
+        let subtitles;
+        const v = d.video === undefined ? undefined : d.media[d.video];
+        const t = d.subtitles === undefined ? undefined : d.media[d.subtitles];
+        if (v !== undefined) {
+            if (d.subtitles !== undefined && t === undefined)
+                warn.push(`${where}: its subtitles could not be verified — the video is left out with them`);
+            else if (t !== undefined && t.bytes > MEDIA_LIMITS.subtitlesBytes)
+                warn.push(`${where}: subtitles ${d.subtitles} are ${t.bytes} bytes, over the contract's ${MEDIA_LIMITS.subtitlesBytes} — the video is left out with them`);
+            else {
+                video = take(d.video, "video/webm", MEDIA_LIMITS.videoBytes, "video");
+                if (video !== undefined && t !== undefined) {
+                    subtitles = take(d.subtitles, "text/vtt", MEDIA_LIMITS.subtitlesBytes, "subtitles");
+                    if (subtitles === undefined) {
+                        // Never a video without its captions file: un-take the video.
+                        const at = files.findIndex((f) => f.path === video);
+                        total -= files[at].bytes;
+                        files.splice(at, 1);
+                        media.splice(media.findIndex((m) => m.path === video), 1);
+                        video = undefined;
+                    }
+                }
+            }
+        }
+        demos.push({
+            journey: d.journey,
+            renderedFrom: d.renderedFrom,
+            status: "approved",
+            ...(title === undefined ? {} : { title }),
+            steps,
+            ...(video === undefined ? {} : { video }),
+            ...(subtitles === undefined ? {} : { subtitles }),
+            privacy: { mask: d.privacy.mask, data: d.privacy.data, method: d.privacy.method, regions: d.privacy.regions },
+        });
+    }
+    if (demos.length > LIMITS.demos) {
+        warn.push(`${demos.length} demos: only the first ${LIMITS.demos} are exported`);
+        const kept = new Set(demos.slice(0, LIMITS.demos).map((d) => `media/${d.journey}/`));
+        const keep = (p) => [...kept].some((k) => p.startsWith(k));
+        return { demos: demos.slice(0, LIMITS.demos), files: files.filter((f) => keep(f.path)), media: media.filter((m) => keep(m.path)) };
+    }
+    return { demos, files, media };
+}
 // ── Findings (the d464c hook's guard) ────────────────────────────────────────────────────────
 /** Why a finding handed in by the d464c source breaks the contract's privacy rules (§7), or []. */
 export function findingIssues(f) {
@@ -531,6 +704,28 @@ export function findingIssues(f) {
     text("userImpact", f.userImpact, 600);
     text("recommendation", f.recommendation, 600);
     (f.controls ?? []).forEach((c, i) => text(`controls[${i}]`, c, 120));
+    // Minor 1 §1: `locator` belongs only to a locator claim, and a locator claim must carry it.
+    const locatorClaim = f.kind === "ux" && f.claim === "other" && f.producerClaim === "locator-brittle";
+    if (locatorClaim && f.locator === undefined)
+        out.push(`${where}: a locator finding needs its locator`);
+    if (f.locator !== undefined) {
+        if (!locatorClaim)
+            out.push(`${where}: locator is only for kind ux + claim other + producerClaim locator-brittle`);
+        const loc = f.locator;
+        const locText = (k, max) => {
+            const p = machineTextProblem(loc[k], max);
+            if (p !== null)
+                out.push(`${where}: locator.${k} ${p}`);
+        };
+        locText("element", 200);
+        locText("fix", 300);
+        if (!LOCATOR_ATTRIBUTE_RE.test(loc.attribute))
+            out.push(`${where}: locator.attribute is not a test-id attribute name`);
+        if (!LOCATOR_TEST_ID_RE.test(loc.testId))
+            out.push(`${where}: locator.testId is not a test id`);
+        if (!Number.isInteger(loc.steps) || loc.steps < 1 || loc.steps > LOCATOR_MAX_STEPS)
+            out.push(`${where}: locator.steps is not an integer 1-${LOCATOR_MAX_STEPS}`);
+    }
     return out;
 }
 // ── The bundle ───────────────────────────────────────────────────────────────────────────────
@@ -561,7 +756,9 @@ export function buildCatalogBundle(input) {
         checks = checks.slice(-LIMITS.checks);
     }
     const commit = input.producer.commit !== undefined && COMMIT_RE.test(input.producer.commit) ? input.producer.commit : undefined;
+    const shown = bundleDemos(input, journeys, warn);
     return {
+        media: shown.media,
         bundle: {
             kind: BUNDLE_KIND,
             version: BUNDLE_VERSION,
@@ -569,8 +766,10 @@ export function buildCatalogBundle(input) {
             producer: { tool: "jevitate", version: input.producer.version, ...(commit === undefined ? {} : { commit }) },
             product: { name: input.productName },
             catalog: { personas, jobs, journeys: journeys.map((j) => j.entry) },
+            ...(shown.demos.length === 0 ? {} : { demos: shown.demos }),
             checks,
             findings: [...findings],
+            ...(shown.demos.length === 0 ? {} : { files: shown.files }),
         },
         warnings: warn,
     };