yam-flow 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.7.0 - 2026-08-24
+
+### Added
+
+- Added immutable final-scope verification closure receipts that bind declared work to the current Git dirty, staged, and untracked path set, promote release-sensitive changes, and separate selected checks from operator-declared execution evidence.
+- Added optional demand-gated media provider receipts with exact call/execution/dry-run/submit state plus confined, identity-bound local asset provenance.
+
+### Improved
+
+- Skill installation and removal now use no-follow regular-file access where available, verify descriptor and path identity, and revalidate parent-directory identity around read, copy, move, rollback, and mutation boundaries.
+- Verification closure and media receipt reads and immutable writes apply confined path, non-symlink parent, descriptor identity, size, and digest checks; media asset hashing is sequential and bounded.
+
+### Security
+
+- Symlinked install source/destination segments, raced path identities, rollback or cleanup targets whose recorded type/device/inode no longer match, unplanned final Git paths, unavailable Git scope, receipt path escapes, local asset symlinks, and incoherent provider-execution claims fail closed.
+- Node does not expose descriptor-relative `openat` traversal, and arbitrary Windows reparse-point coverage remains unverified; these limits are documented instead of overstated.
+
+### Verification
+
+- Focused install-transaction and phase-adoption smokes cover source/destination race handling, rollback preservation, Git-scope drift, immutable/tampered receipts, bounded media assets, and packaged CLI compatibility.
+- Release checks include typecheck, clean build/self-verification, distribution freshness, package boundary/secrets, registry version availability, and CLI smoke.
+
 ## v2.6.0 - 2026-08-07
 
 ### Added

package/COMMANDS.md

@@ -174,6 +174,36 @@ yam ueye production phase verify --receipt-path .yam/ueye/design-production/camp
 
 Canvas artifact specs use `{ "id", "role", "file_path" }`; gallery specs include `{ "id", "role", "provenance", "revision_ref", "dimensions", "sha256", "completion_state", "final_path" }`. A revision reference also carries the archive receipt's exact `archived_at`, which must match its Ueye manifest entry. All project paths are relative and confined; Canvas session/render paths and the single revision state are fixed under the session-specific `.yam/ueye/design-production/` directory. Revision init binds that state to the closed `request_changes` Canvas path and digest; record/show/finalize reject alternate state files, and record immediately checks the source Canvas comment plus the current archive-time boundary. Demand is operator-asserted but must be recorded before Canvas creation and match at finalize. Canvas source hashes and exact anchors are rechecked before comment/close/finalize. Every phase round names its source Canvas comment and supplies at least one newly archived Ueye revision created within that round's review window; gallery artifacts bind to the final round. Ueye asset/revision hashes are rechecked, a protected `do_not_replace` asset requires `intent: "preserve"`, and `edit_copy` requires `allowed_for_edit: true`. The phase receipt stores upstream and canonical receipt digests, and `phase verify` re-reads their semantics as well as detecting later byte changes. Overall phase truth remains `partial`, and gallery visual, license, and implementation claims always remain `not_verified`.
 
+## Verification Closure And Media Provider Receipts
+
+These are explicit, immutable artifacts. They do not run verification commands or contact media providers.
+
+Prepare one JSON file per selected/executed/skipped/truncated command record, then repeat the corresponding flag:
+
+```json
+{"id":"typecheck","command":"npm run typecheck","scope":"affected","required":true}
+```
+
+```json
+{"id":"typecheck","command":"npm run typecheck","exit_code":0,"evidence":"exit 0 observed in the final worktree"}
+```
+
+```bash
+yam verification closure create --root /path/to/project --receipt-path .yam/verification/final.json --planned-scope affected --changed-file src/example.ts --selected-spec ./selected.json --executed-spec ./executed.json --json
+yam verification closure verify --root /path/to/project --receipt-path .yam/verification/final.json --json
+```
+
+`create` snapshots the Git top-level dirty, staged, and untracked path set. Every observed path must be declared; unplanned paths, missing declared paths, unavailable Git scope, missing required execution, and release-sensitive paths without a required release-scope check fail closed. `verify` re-reads the current Git path set as well as the receipt digest. A later path-set change returns `current_git_scope_drift`; rerun checks against the final state and create a new receipt path because receipts are non-overwriting. Content-only changes to an already-dirty path do not alter the Git path set, and command results remain operator-asserted `partial` evidence.
+
+Media provider receipts are optional and should be used only after real execution-tracking demand exists. Each asset spec contains `{ "id", "role", "file_path", "provenance": { "kind", "source_ref", "recorded_at" } }`.
+
+```bash
+yam media provider create --root /path/to/project --receipt-path .yam/media/dry-run.json --demand-kind media_generation --demand-evidence "coordinated asset work needs an execution boundary" --provider example --model example-v1 --provider-calls 0 --dry-run --asset-spec ./input-asset.json --json
+yam media provider verify --root /path/to/project --receipt-path .yam/media/dry-run.json --json
+```
+
+A dry run requires zero calls, no execution, and no submit. Explicit execution requires `--provider-execution --submit`, at least one call, and a provider-provenance output asset. Local asset and receipt integrity is verified, but provider execution, visual quality, and implementation correctness are not independently proven.
+
 ## Bounded Promotion
 
 ```bash

package/README.md

@@ -112,7 +112,9 @@ cd ~/Documents/Codex/tools/yam
 yam install
 ```
 
-`yam install` first checks ownership of every existing active skill. A skill is replaced automatically only when the previous yam receipt names it and its complete regular-file inventory and content hashes still match the receipt. The installer then stages every managed skill plus the shared `references/` directory, verifies the complete staged file manifest with SHA-256, and replaces the verified active set in `~/.agents/skills/`. If any commit or post-install verification step fails, yam restores the previous managed skill set and receipt.
+`yam install` first checks ownership of every existing active skill. A skill is replaced automatically only when the previous yam receipt names it and its complete regular-file inventory and content hashes still match the receipt. The installer then stages every managed skill plus the shared `references/` directory, verifies the complete staged file manifest with SHA-256, and replaces the verified active set in `~/.agents/skills/`. If any commit or post-install verification step fails, yam restores the previous managed skill set and receipt. Rollback and cleanup remove newly installed skills, receipts, locks, and transaction roots only while their recorded type and device/inode identity still match; an identity-swapped path is preserved and reported instead of being treated as yam-owned.
+
+Install source, destination, receipt, and managed-tree paths must use canonical physical directories. A symlink alias used as the package source or `YAM_SKILLS_HOME`, or a symlinked parent segment inside either boundary, fails closed; resolve the alias to its real path before retrying. Regular-file reads use descriptor identity checks and `O_NOFOLLOW` where the platform exposes it, while mutation boundaries revalidate parent directory identities. This narrows symlink-swap risk but is not `openat`-grade proof because Node does not expose descriptor-relative traversal here. Arbitrary Windows reparse-point handling is also unverified, so Windows receives the portable identity checks without a claim of complete reparse coverage.
 
 If an existing active directory is user-owned, locally modified, or cannot be proven yam-owned, installation stops before staging and preserves it. After reviewing the files, replace only the intended conflicting name explicitly:
 
@@ -335,6 +337,8 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Bounded promotion receipt: `yam benchmark report` can compare paired candidate/baseline measurements under explicit sample, mean-delta, and win-rate thresholds. Arithmetic is verified, while measurement provenance remains `operator_asserted` and overall truth stays `partial`.
 - Honest capability matrix: `yam tools doctor --json` reports feature maturity separately from observed runtime readiness; instruction-only or unprobed capabilities are not reported as executed.
 - Strict gate result: release, update, benchmark-promotion, and Mission completion boundaries emit a digest-bound `yam.gate-result.v1` and fail closed on missing or inconsistent required evidence.
+- Final-scope verification closure: `yam verification closure create|verify` binds the planned boundary, current Git dirty/staged/untracked paths, release-sensitive escalation, selected versus operator-declared executed commands, skipped/truncated reasons, and an immutable digest. Missing required execution, unknown results, unplanned files, unavailable Git scope, and later receipt tampering fail closed; yam does not execute the recorded commands or upgrade their truth beyond `partial`.
+- Optional media provider receipt: `yam media provider create|verify` records an explicit demand trigger, exact `provider_calls`/`provider_execution`/`dry_run`/`submit` state, and identity-bound local asset provenance. It never calls a provider, and integrity verification never proves visual or implementation correctness.
 
 ## Ueye Capture And Compare
 
@@ -366,4 +370,8 @@ Generated media can guide visual direction, but it cannot prove the implemented
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 ```
 
+When real repeated media work needs an execution boundary, prepare bounded JSON asset specs and opt in explicitly. Dry-run receipts require zero calls/no submit; execution receipts require a submitted call plus a provider-provenance output. Both the receipt and local asset paths are confined below the project root and can be re-read with `yam media provider verify`. The existing `yam media proof` command remains the lightweight default.
+
+For completion evidence, `yam verification closure create` consumes small selected/executed/skipped/truncated JSON specs. It snapshots actual Git status before writing under `.yam/verification/`; declare every expected changed path with repeated `--changed-file`, then use `verify` to detect semantic, digest, or current Git path-set drift. `current_git_scope_drift` means checks must be rerun against the final state and a new immutable receipt must be created. This remains an explicit artifact, not an always-on hook or command runner.
+
 For agent-driven visual QA, prefer the Codex in-app Browser plugin. Use the user's Chrome browser only when explicitly requested or when Chrome-only session/profile state is required.

package/ROADMAP.md

@@ -53,6 +53,7 @@ Tasks:
 - Detect common commands: typecheck, lint, test, build. Done.
 - Map changed files to likely checks. Done: dirty, staged, and untracked paths now map to focused rules with confidence, reason, fallback, and available commands.
 - Keep this advisory, not mandatory. Done.
+- Add an explicit final-scope closure artifact without turning the detector into an auto-runner. Done: immutable receipts bind current Git scope, release escalation, selected/executed command separation, skipped/truncated reasons, and partial operator-asserted truth.
 
 ### 4. Token Budget Reporter
 
@@ -76,6 +77,7 @@ Tasks:
 - Add local reference asset provenance/protection manifest and non-overwriting revision history. Done.
 - Add optional browser/screenshot capture notes.
 - Keep image generation optional, never a gate.
+- Add an optional provider-execution boundary only when real media demand exists. Done: exact fail-closed execution fields, confined hash-bound local assets/provenance, and verify/tamper detection without provider calls or correctness claims.
 
 ### 6. Deep Runtime Workflow
 
@@ -94,7 +96,7 @@ Goal: make install/update simpler.
 
 Tasks:
 
-- Add symlink-friendly local install.
+- Reconsider symlink-friendly local install only if Node exposes a safe descriptor-relative traversal boundary or an equivalent proven design. Deferred: current package source, `YAM_SKILLS_HOME`, and managed-tree paths intentionally reject symlink aliases and symlinked parent segments.
 - Add version command. Done.
 - Add staged transactional install, rollback, receipt, and drift-aware status. Done.
 - Add checked component updates for yam, Scrapling, and Insane Search with explicit authorization, receipts, and rollback guidance. Done.

package/dist/bin/yam.js

@@ -15,6 +15,8 @@ import { inspectSkillInstallation, installSkillSetTransactional, uninstallSkillS
 import { EXTERNAL_UPDATE_COMPONENTS, applyExternalUpdates, checkExternalUpdates } from '../lib/external-updates.js';
 import { buildBoundedPromotionReport, parsePromotionSample } from '../lib/benchmark-promotion.js';
 import { buildStrictGateResult, verifyStrictGateResult } from '../lib/gate-result.js';
+import { createVerificationClosureReceipt, verifyVerificationClosureReceiptFile } from '../lib/verification-closure.js';
+import { createMediaProviderReceipt, verifyMediaProviderReceipt } from '../lib/media-provider-receipt.js';
 import { BoundedInputError, GENERAL_STDIN_MAX_BYTES, HOOK_STDIN_MAX_BYTES, readBoundedStdinJson, readBoundedStdinText } from '../lib/bounded-input.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -152,6 +154,7 @@ Usage:
   yam mission queue [--agent-id id] [--scope text] [--changed file] [--verification-hint text] [--json]
   yam mission receipt [--thread-id id] [--role reviewer] [--lifecycle stopped] [--outcome passed] [--evidence text] [--json]
   yam mission gate [--expected-thread id] [--receipt file] [--json]
+  yam verification closure <create|verify> [options]
   yam update check [--json]
   yam update apply --component yam|scrapling|insane-search [--json]
   yam update apply --all [--json]
@@ -1364,6 +1367,8 @@ function buildCapabilityMatrix(readinessRows = [], liteHook = {}, studyNoteHook
         capabilityRow('bounded_design_revisions', 'beta', 'ready', 'maximum two reviewer-finding-backed revision rounds', 'round state does not replace Ueye artifact hash verification'),
         capabilityRow('final_gallery_manifest', 'beta', 'ready', 'path-confined hash-verified packaging manifest', 'gallery completeness does not prove visual or license correctness'),
         capabilityRow('demand_gated_design_production', 'beta', 'ready', 'pre-recorded operator trigger, Canvas, chronological bounded revisions, gallery, and digest-verifiable phase receipt', 'demand evidence is operator-asserted and overall phase truth remains partial'),
+        capabilityRow('final_scope_verification_closure', 'beta', 'ready', 'explicit Git-scope and selected/executed command receipt with digest verification', 'does not execute checks; unavailable or unplanned Git scope blocks and successful operator evidence remains partial'),
+        capabilityRow('media_provider_execution_receipt', 'beta', 'ready', 'optional demand-gated exact execution boundary plus identity-bound local assets', 'never contacts providers and does not prove visual or implementation correctness'),
         capabilityRow('yam_lite_hook', 'beta', String(liteHook.state || readiness.get('yam-lite hook') || 'unknown'), 'optional hook health inspection', 'advisory only; disabled unless explicitly enabled'),
         capabilityRow('study_note_hook', 'beta', String(studyNoteHook.state || readiness.get('yam-study-note hook') || 'unknown'), 'optional prompt and bounded Stop check', 'does not generate the Study Note or run verification')
     ];
@@ -3141,17 +3146,57 @@ async function readProductionSpecs(value, label) {
         specs.push(await readBoundedJsonSpec(path.resolve(expandHome(file)), label));
     return specs;
 }
+async function readOptionalSpecs(value, label) {
+    const files = arrayFlag(value);
+    const specs = [];
+    for (const file of files)
+        specs.push(await readBoundedJsonSpec(path.resolve(expandHome(file)), label));
+    return specs;
+}
 async function readBoundedJsonSpec(file, label) {
-    const stat = await fsp.stat(file);
-    if (!stat.isFile())
-        throw new Error(`${label} must be a regular file: ${file}`);
-    if (stat.size > 256 * 1024)
+    const before = await fsp.lstat(file);
+    if (before.isSymbolicLink() || !before.isFile())
+        throw new Error(`${label} must be a regular non-symlink file: ${file}`);
+    if (before.size > 256 * 1024)
         throw new Error(`${label} exceeds the 256 KiB limit: ${file}`);
-    const value = JSON.parse(await fsp.readFile(file, 'utf8'));
+    const noFollow = process.platform !== 'win32' && typeof fs.constants.O_NOFOLLOW === 'number'
+        ? fs.constants.O_NOFOLLOW
+        : 0;
+    const handle = await fsp.open(file, fs.constants.O_RDONLY | noFollow);
+    let text = '';
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || !sameSpecFileIdentity(before, opened))
+            throw new Error(`${label} identity changed before open: ${file}`);
+        if (opened.size > 256 * 1024)
+            throw new Error(`${label} exceeds the 256 KiB limit: ${file}`);
+        const bytes = Buffer.alloc(opened.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, offset);
+            if (!bytesRead)
+                throw new Error(`${label} became shorter while reading: ${file}`);
+            offset += bytesRead;
+        }
+        const openedAfter = await handle.stat();
+        const after = await fsp.lstat(file);
+        if (!sameSpecFileIdentity(opened, openedAfter) || openedAfter.size !== opened.size
+            || after.isSymbolicLink() || !after.isFile() || !sameSpecFileIdentity(opened, after)) {
+            throw new Error(`${label} changed size or identity while reading: ${file}`);
+        }
+        text = bytes.toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+    const value = JSON.parse(text);
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error(`${label} must contain one JSON object: ${file}`);
     return value;
 }
+function sameSpecFileIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
 async function existingProductionPath(root, value, label) {
     if (!value || path.isAbsolute(value) || value.includes('\0'))
         throw new Error(`${label} must be a non-empty project-relative path`);
@@ -3707,12 +3752,83 @@ function normalizeUeyeComparisonResult(value = '') {
         return text;
     return 'not-verified';
 }
+async function verification(args = []) {
+    const surface = String(args[0] || 'help');
+    const action = String(args[1] || 'help');
+    if (surface === 'help' || action === 'help' || surface === '--help' || surface === '-h')
+        return verificationUsage();
+    if (surface !== 'closure') {
+        console.error(`unknown verification command: ${surface}`);
+        return verificationUsage();
+    }
+    const flags = parseSimpleFlags(args.slice(2), new Set([
+        'root', 'receipt-path', 'planned-scope', 'changed-file', 'selected-spec',
+        'executed-spec', 'skipped-spec', 'truncated-spec', 'json'
+    ]));
+    const root = path.resolve(expandHome(flags.root || process.cwd()));
+    try {
+        let result;
+        if (action === 'create') {
+            requireProductionFlags(flags, ['receipt_path', 'planned_scope', 'changed_file', 'selected_spec']);
+            result = await createVerificationClosureReceipt({
+                root,
+                receipt_path: String(flags.receipt_path),
+                planned_scope: String(flags.planned_scope),
+                changed_files: arrayFlag(flags.changed_file),
+                selected_commands: await readProductionSpecs(flags.selected_spec, 'selected command spec'),
+                executed_commands: await readOptionalSpecs(flags.executed_spec, 'executed command spec'),
+                skipped: await readOptionalSpecs(flags.skipped_spec, 'skipped command spec'),
+                truncated: await readOptionalSpecs(flags.truncated_spec, 'truncated output spec')
+            });
+        }
+        else if (action === 'verify') {
+            requireProductionFlags(flags, ['receipt_path']);
+            result = await verifyVerificationClosureReceiptFile({ root, receipt_path: String(flags.receipt_path) });
+        }
+        else {
+            throw new Error(`unknown verification closure command: ${action}`);
+        }
+        printJsonOrHuman(result, Boolean(flags.json), 'Verification closure');
+        if (result.truth_status === 'blocked')
+            process.exitCode = 1;
+    }
+    catch (error) {
+        const result = {
+            schema: 'yam.verification-closure-error.v1',
+            action,
+            status: 'blocked',
+            reason: summarizeCheckOutput(errorMessage(error)),
+            next_action: 'repair changed-file scope, selected/executed command evidence, skipped/truncated reasons, or receipt integrity before retrying',
+            truth_status: 'blocked'
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Verification closure');
+        process.exitCode = 1;
+    }
+}
+function verificationUsage() {
+    console.log(`yam verification closure
+
+Explicit, immutable completion receipts. Create records operator-supplied results; it does not execute commands or replace advisory yam detect output.
+
+Usage:
+  yam verification closure create [--root dir] --receipt-path .yam/verification/closure.json --planned-scope affected|release --changed-file file --selected-spec file [--executed-spec file] [--skipped-spec file] [--truncated-spec file] [--json]
+  yam verification closure verify [--root dir] --receipt-path .yam/verification/closure.json [--json]
+
+Selected spec: {"id":"typecheck","command":"npm run typecheck","scope":"affected","required":true}
+Executed spec: {"id":"typecheck","command":"npm run typecheck","exit_code":0,"evidence":"exit 0 observed"}
+Skipped/truncated spec: {"check_id":"browser","reason":"no UI surface changed"}
+
+Repeat spec and changed-file flags as needed. Release-sensitive paths promote affected to release and require an executed required release-scope command. Required selected commands cannot be skipped. Digest verification does not upgrade operator-declared execution results beyond partial truth.
+`);
+}
 async function media(args = []) {
     const subcommand = args[0] || 'help';
     if (subcommand === 'help' || subcommand === '--help' || subcommand === '-h')
         return mediaUsage();
     if (subcommand === 'proof')
         return mediaProof(args.slice(1));
+    if (subcommand === 'provider')
+        return mediaProvider(args.slice(1));
     console.error(`unknown media command: ${subcommand}`);
     return mediaUsage();
 }
@@ -3723,8 +3839,66 @@ Opt-in media generation proof helpers. Generated media can support visual direct
 
 Usage:
   yam media proof [--tool name] [--requested] [--attempted] [--output file] [--wait-loop] [--blocked-reason text] [--json]
+  yam media provider create [--root dir] --receipt-path .yam/media/run.json --demand-kind media_generation|media_transformation --demand-evidence text --provider name --model name --provider-calls n [--provider-execution] [--dry-run] [--submit] --asset-spec file [--json]
+  yam media provider verify [--root dir] --receipt-path .yam/media/run.json [--json]
+
+Provider receipts are optional and demand-gated. This command hashes local assets and records an operator-asserted boundary; it never contacts a provider. Dry runs require zero calls and no submit. Explicit execution requires at least one call, submit, and a provider-provenance output asset.
 `);
 }
+async function mediaProvider(args = []) {
+    const action = String(args[0] || 'help');
+    if (action === 'help' || action === '--help' || action === '-h')
+        return mediaUsage();
+    const flags = parseSimpleFlags(args.slice(1), new Set([
+        'root', 'receipt-path', 'demand-kind', 'demand-evidence', 'provider', 'model',
+        'provider-calls', 'provider-execution', 'dry-run', 'submit', 'asset-spec', 'json'
+    ]));
+    const root = path.resolve(expandHome(flags.root || process.cwd()));
+    try {
+        let result;
+        if (action === 'create') {
+            requireProductionFlags(flags, [
+                'receipt_path', 'demand_kind', 'demand_evidence', 'provider', 'model', 'provider_calls', 'asset_spec'
+            ]);
+            result = await createMediaProviderReceipt({
+                root,
+                receipt_path: String(flags.receipt_path),
+                demand_trigger: {
+                    kind: String(flags.demand_kind),
+                    evidence: String(flags.demand_evidence)
+                },
+                provider: { name: String(flags.provider), model: String(flags.model) },
+                provider_calls: Number(flags.provider_calls),
+                provider_execution: Boolean(flags.provider_execution),
+                dry_run: Boolean(flags.dry_run),
+                submit: Boolean(flags.submit),
+                assets: await readProductionSpecs(flags.asset_spec, 'media asset spec')
+            });
+        }
+        else if (action === 'verify') {
+            requireProductionFlags(flags, ['receipt_path']);
+            result = await verifyMediaProviderReceipt({ root, receipt_path: String(flags.receipt_path) });
+        }
+        else {
+            throw new Error(`unknown media provider command: ${action}`);
+        }
+        printJsonOrHuman(result, Boolean(flags.json), 'Media provider receipt');
+        if (result.truth_status === 'blocked')
+            process.exitCode = 1;
+    }
+    catch (error) {
+        const result = {
+            schema: 'yam.media-provider-receipt-error.v1',
+            action,
+            status: 'blocked',
+            reason: summarizeCheckOutput(errorMessage(error)),
+            next_action: 'repair the demand, exact execution fields, confined asset provenance, or receipt integrity before retrying',
+            truth_status: 'blocked'
+        };
+        printJsonOrHuman(result, Boolean(flags.json), 'Media provider receipt');
+        process.exitCode = 1;
+    }
+}
 async function mediaProof(args = []) {
     if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h')
         return mediaUsage();
@@ -4250,7 +4424,7 @@ function parseSimpleFlags(args = [], allowed = new Set()) {
         if (allowed.size && !allowed.has(key))
             continue;
         const normalizedKey = key.replace(/-/g, '_');
-        if (['json', 'full-page', 'requested', 'attempted', 'available', 'wait-loop', 'cleanup-checked', 'cleanup-observed', 'left-running-intentionally', 'strict', 'preserved-state', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read', 'invented-metric', 'placeholder-copy', 'generic-visual', 'operator-provided', 'do-not-replace', 'allowed-for-edit', 'replace'].includes(key)) {
+        if (['json', 'full-page', 'requested', 'attempted', 'available', 'wait-loop', 'cleanup-checked', 'cleanup-observed', 'left-running-intentionally', 'strict', 'preserved-state', 'states-checked', 'mobile-checked', 'responsive-checked', 'contrast-checked', 'accessibility-checked', 'cta-checked', 'direction-locked', 'reference-read', 'invented-metric', 'placeholder-copy', 'generic-visual', 'operator-provided', 'do-not-replace', 'allowed-for-edit', 'replace', 'provider-execution', 'dry-run', 'submit'].includes(key)) {
             flags[normalizedKey] = true;
             continue;
         }
@@ -5778,6 +5952,7 @@ function showRequestedHelp(args) {
         loop: loopUsage,
         ueye: ueyeUsage,
         media: mediaUsage,
+        verification: verificationUsage,
         runtime: runtimeUsage,
         mission: missionUsage,
         update: updateUsage,
@@ -5824,6 +5999,8 @@ async function main() {
         return ueye(process.argv.slice(3));
     if (command === 'media')
         return media(process.argv.slice(3));
+    if (command === 'verification')
+        return verification(process.argv.slice(3));
     if (command === 'runtime')
         return runtime(process.argv.slice(3));
     if (command === 'mission')

package/dist/lib/media-provider-receipt.d.ts

@@ -0,0 +1,79 @@
+export interface MediaProviderAssetInput {
+    id: string;
+    role: 'input' | 'output';
+    file_path: string;
+    provenance: {
+        kind: 'operator' | 'provider';
+        source_ref: string;
+        recorded_at: string;
+    };
+}
+export interface MediaProviderReceipt {
+    schema: 'yam.media-provider-receipt.v1';
+    created_at: string;
+    demand_trigger: {
+        kind: 'media_generation' | 'media_transformation';
+        evidence: string;
+        evidence_truth: 'operator_asserted';
+    };
+    provider: {
+        name: string;
+        model: string;
+    };
+    provider_calls: number;
+    provider_execution: boolean;
+    dry_run: boolean;
+    submit: boolean;
+    assets: Array<MediaProviderAssetInput & {
+        sha256: string;
+        bytes: number;
+    }>;
+    execution_boundary: {
+        provider_calls_by_yam: false;
+        provider_claim_source: 'operator_asserted';
+        optional: true;
+    };
+    claims: {
+        asset_integrity: 'digest_bound';
+        provider_execution: 'operator_asserted';
+        visual_correctness: 'not_verified';
+        implementation_correctness: 'not_verified';
+    };
+    truth_status: 'partial';
+    digest: string;
+}
+export declare function createMediaProviderReceipt(input: {
+    root: string;
+    receipt_path: string;
+    demand_trigger: {
+        kind: 'media_generation' | 'media_transformation';
+        evidence: string;
+    };
+    provider: {
+        name: string;
+        model: string;
+    };
+    provider_calls: number;
+    provider_execution: boolean;
+    dry_run: boolean;
+    submit: boolean;
+    assets: MediaProviderAssetInput[];
+}): Promise<{
+    schema: "yam.media-provider-receipt-write.v1";
+    receipt_path: string;
+    receipt: MediaProviderReceipt;
+    truth_status: "partial";
+    next_action: string;
+}>;
+export declare function verifyMediaProviderReceipt(input: {
+    root: string;
+    receipt_path: string;
+}): Promise<{
+    schema: "yam.media-provider-receipt-verification.v1";
+    receipt_path: string;
+    valid: boolean;
+    errors: string[];
+    receipt_truth_status: "partial";
+    truth_status: "verified" | "blocked";
+    next_action: string;
+}>;