@tiangong-lca/cli 0.0.23 → 0.0.25

package/README.md

@@ -17,8 +17,8 @@ checkPaths:
   - bin/**
   - src/cli.ts
   - src/main.ts
-lastReviewedAt: 2026-07-13
-lastReviewedCommit: 4c79df4623e3cf296bc8d1baeea688d78351570a
+lastReviewedAt: 2026-07-15
+lastReviewedCommit: ca0cdd7549cad9003d08fb338223ba74682955ae
 ---
 
 # TianGong LCA CLI
@@ -29,6 +29,10 @@ Review note, 2026-07-12: `dataset maintenance plan/apply/verify` provides curren
 
 Review note, 2026-07-13: maintenance scans now prove exact-count pagination even when PostgREST returns fewer rows than the requested `--page-size`. An incomplete or inconsistent scan fails before artifacts, approval, or mutation; under stable filtered membership/order the proof represents a complete ordered multi-request traversal, not one transaction-level/MVCC snapshot.
 
+Review note, 2026-07-14: maintenance now includes the protected derivative-only `rebuild-derivatives` operation. V1 plans exactly one current-owner state-0 process with `action=rebuild_derivatives`, `target_mode=owner_draft`, and components `extracted_md` plus `embedding_ft`. Apply only proves guarded-RPC admission (`accepted`/`queued`); independent verify reports `pending`, `passed`, or `failed`.
+
+Review note, 2026-07-15: `dataset maintenance run-protected` adds a production-only path for one sealed private alias execution and its exact 50-target derivative closure. The protected executor is server-dispatched and fenced by the authenticated owner plus exact actor/user_id/state_code=0 and plan-closure checks; RLS remains a defense on public and independent-read surfaces. It performs one server preflight, writes an immutable local attempt marker before one admission POST, and requires status-only recovery after any marker or ambiguous response. It has no dev, legacy-alias, publication, or state-code fallback.
+
 ## Run
 
 One-off published run:
@@ -278,8 +282,10 @@ tiangong-lca dataset evidence-search plan --query "中国2026年电力结构数
 tiangong-lca dataset evidence-search run --input ./evidence-search.request.json --results ./search-results.json --out-dir /abs/path/to/evidence-search --json
 tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id>@<old-version> --to flow:<new-id>@<new-version> --out-dir /abs/path/to/dataset-rewrite --json
 tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation redo-import --out-dir /abs/path/to/dataset-maintenance --page-size 1000 --timeout-ms 10000 --json
+tiangong-lca dataset maintenance plan --scope ./derivative-rebuild-scope.json --operation rebuild-derivatives --out-dir /abs/path/to/derivative-rebuild --json
 tiangong-lca dataset maintenance apply --plan /abs/path/to/dataset-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm <current-account-email> --timeout-ms 10000 --json
 tiangong-lca dataset maintenance verify --plan /abs/path/to/dataset-maintenance/maintenance-plan.json --out-dir /abs/path/to/dataset-maintenance/verify --page-size 1000 --timeout-ms 10000 --json
+tiangong-lca dataset maintenance run-protected --plan /abs/path/to/maintenance-plan.json --freeze /abs/path/to/protected-execution-seal.json --approval /abs/path/to/protected-approval.json --out-dir /abs/path/to/protected-run --status-only --json
 tiangong-lca lifecyclemodel auto-build --input ./examples/lifecyclemodel-auto-build.request.json --out-dir /abs/path/to/lifecyclemodel-run --json
 tiangong-lca lifecyclemodel validate-build --run-dir /abs/path/to/lifecyclemodel-run --json
 tiangong-lca lifecyclemodel publish-build --run-dir /abs/path/to/lifecyclemodel-run --json
@@ -324,12 +330,12 @@ For `dataset references rewrite`, `--commit` executes the state-aware save-draft
 
 ## Dataset Maintenance
 
-`dataset maintenance plan/apply/verify` is the row-level cleanup surface for bad imports and the fixed BAFU private alias rewrite. It runs as the currently authenticated user and relies on RLS for visibility and ownership enforcement.
+`dataset maintenance plan/apply/run-protected/verify` is the row-level cleanup surface for bad imports, the fixed BAFU private alias rewrite, and protected derivative rebuilds. Ordinary planning, apply, and independent verification use the authenticated account and RLS. The protected executor is server-dispatched and additionally enforces the sealed actor, user_id, state_code=0, exact target set, and closure hashes on every write.
 
 ```bash
 tiangong-lca dataset maintenance plan \
   --scope ./maintenance-scope.json \
-  --operation merge-support-aliases \
+  --operation repair-references \
   --out-dir ./dataset-maintenance \
   --page-size 1000 \
   --timeout-ms 10000 \
@@ -349,8 +355,39 @@ tiangong-lca dataset maintenance verify \
   --page-size 1000 \
   --timeout-ms 10000 \
   --json
+
+tiangong-lca dataset maintenance run-protected \
+  --plan ./protected-step2/maintenance-plan.json \
+  --freeze ./protected-step2/protected-execution-seal.json \
+  --approval ./protected-step2/protected-approval.json \
+  --out-dir ./protected-step2/run \
+  --commit \
+  --approve-execution <approved-execution-sha256> \
+  --confirm <current-account-email> \
+  --wait-seconds 60 \
+  --poll-ms 10000 \
+  --page-size 1000 \
+  --timeout-ms 10000 \
+  --json
+
+tiangong-lca dataset maintenance run-protected \
+  --plan ./protected-step2/maintenance-plan.json \
+  --freeze ./protected-step2/protected-execution-seal.json \
+  --approval ./protected-step2/protected-approval.json \
+  --out-dir ./protected-step2/run \
+  --status-only \
+  --wait-seconds 60 \
+  --json
 ```
 
+`run-protected` is a separate one-shot path for an already reviewed and sealed production execution; it does not replace ordinary planning. Both modes require the exact plan, freeze/seal, approval artifact, and private output directory. Commit mode additionally requires `--commit`, the exact approved execution identity through `--approve-execution`, and the authenticated account email through `--confirm`. `--status-only` is mutually exclusive with `--commit` and performs no preflight or admission.
+
+Before requesting preflight, the command validates the sealed production project, full current-user RLS before-state, support closure, and exact derivative baseline. The server then returns the three expected gate digests and a token valid for at most 180 seconds; the CLI captures and compares the live gate receipts before admission. The server-dispatched write remains fenced to the authenticated actor's exact `user_id`, `state_code=0` rows and sealed plan/closure; independent readback still uses RLS. The CLI writes an immutable local submission marker and sends at most one admission POST. A marker, admission timeout, connection loss, or ambiguous admission response permanently switches that local run to status-only recovery; status-read failures may be polled only within the configured wait window and never cause a second admission or fallback to dev or the legacy whole-plan RPC. The default status polling interval is 10 seconds.
+
+Success requires the terminal database proof and independent RLS readback to agree on the approved execution, exact row/exchange/audit closure, and exactly 50 derivative targets split into 23 flows and 27 processes. `pending`, `failed`, and `indeterminate` all return a non-zero exit status. The protected operation keeps all affected rows private to their owner, changes no `state_code`, and does not publish data.
+
+For the derivative-only profile, use the same three commands with `--operation rebuild-derivatives`. Its scope must contain exactly one `processes` action with `action: "rebuild_derivatives"`, `target_mode: "owner_draft"`, expected current owner, expected `state_code: 0`, and the exact component set `extracted_md` plus `embedding_ft`.
+
 `--page-size` accepts `1-5000` and is only the requested maximum. PostgREST may enforce a lower server-side cap. The CLI requests `Prefer: count=exact`, validates the exact total and returned range from each `Content-Range`, advances the next offset by the number of rows actually returned, and requires strict `id`/`version` ordering without missing or duplicate identities. Each accepted scan records per-table requested/effective page size, page count, rows fetched, exact total, and aggregate entity counts.
 
 This completeness proof means the CLI traversed the filtered result while that table's membership and ordering keys remained stable. Because the tables are read through multiple HTTP requests, it is not a transaction-level or MVCC snapshot of one instant; same-cardinality delete/insert churn can evade total and ordering checks. Plan hashes and apply-time drift checks provide the later mutation guard, and operators must avoid concurrent maintenance of the same account while planning or clearing it.
@@ -358,18 +395,21 @@ This completeness proof means the CLI traversed the filtered result while that t
 The scope is intentionally narrow:
 
 - Each requested row must name its table, exact `id`, exact `version`, expected current owner, and draft `state_code=0` state.
-- `--operation` accepts `delete`, `retire`, `redo-import`, `repair-references`, or `merge-support-aliases`; it records the operator's maintenance intent and does not broaden the eligible row actions.
+- `--operation` accepts `delete`, `retire`, `redo-import`, `repair-references`, `merge-support-aliases`, or `rebuild-derivatives`; it records the operator's maintenance intent and does not broaden the eligible row actions.
 - Only current-user `contacts`, `sources`, `flows`, and `processes` can become `save_draft` or `delete` actions.
 - `merge-support-aliases` requires top-level `target_mode: "owner_draft"` and accepts only two named batches, `time` and `length_time`. The scope must bind reviewed current-owner draft source and target FP/UG exact ids/versions to 52 `update_json_ordered` actions: 25 time rows (1 FP, 10 flows, 14 processes) and 27 length-time rows (1 FP, 13 flows, 13 processes). Process actions freeze every selected exchange index, internal id, flow id/version, direction, before hash, and both amount strings.
 - The alias factors are exact decimal strings: `0.00011415525114155251` for time and `1000` for length-time. Planning requires exactly 20 and 39 selected exchanges, preserves exactly 309 other exchanges in the affected processes, and proves the fixed source-zero/target-reference postconditions. The transformation changes references and the selected `meanAmount`/`resultingAmount`; it does not delete the source FP/UG rows.
 - Source alias support, target FP/UG, and every changed flow/process must all belong to the authenticated account at `state_code=0`. Public/shared, foreign-owner, mixed-visibility, non-draft, lifecyclemodel, and unsupported action/table rows remain protected.
+- `rebuild-derivatives` accepts exactly one exact-version `processes` row and is bidirectionally bound to `action=rebuild_derivatives`, `target_mode=owner_draft`, and components `extracted_md` plus `embedding_ft`. It cannot target a public/shared row, a foreign owner, a non-draft row, another table, multiple actions, or a partial/different component set. It rebuilds derivatives only; the primary process payload, owner/state, and `modified_at` remain unchanged.
 - The CLI classifies and executes an operator-authored scope; it does not decide whether rows are semantically duplicates, canonical replacements, or safe business-level cleanup targets.
 
-`plan` accepts the account scan only after its exact-count proof is complete, then writes the frozen `maintenance-scope.json`, `rls-visible-snapshot.json`, `protected-rows.jsonl`, `reference-impact-report.json`, `maintenance-plan.json`, and `dry-run-report.json`. The snapshot, dry-run report, and newly generated plan carry the aggregate completeness proof, so it is bound into the plan SHA-256. Alias plans additionally write `exchange-rewrite-plan.jsonl`, freeze current-owner state-0 target FP, target UG, and source UG snapshots for each batch, derive schema-valid desired payloads with matching embedded UUID/version, and include the exact closure, `modified_at`, hashes, conversion evidence, and postconditions in the approved plan. The plan SHA-256 is the approval identity; do not edit or recompute the plan after review.
+`plan` accepts the account scan only after its exact-count proof is complete, then writes the frozen `maintenance-scope.json`, `rls-visible-snapshot.json`, `protected-rows.jsonl`, `reference-impact-report.json`, `maintenance-plan.json`, and `dry-run-report.json`. The snapshot, dry-run report, and newly generated plan carry the aggregate completeness proof, so it is bound into the plan SHA-256. Alias plans additionally write `exchange-rewrite-plan.jsonl`, freeze current-owner state-0 target FP, target UG, and source UG snapshots for each batch, derive schema-valid desired payloads with matching embedded UUID/version, and include the exact closure, `modified_at`, hashes, conversion evidence, and postconditions in the approved plan. A derivative rebuild plan additionally obtains a database-produced snapshot for only the exact target action and binds its primary and derivative preconditions into the plan; large markdown/vector fields are not added to the account-wide scan. The plan SHA-256 is the approval identity; do not edit or recompute the plan after review.
+
+`apply` is write-disabled unless all three commit guards are present: `--commit`, `--approve-plan <sha256>`, and `--confirm <current-account-email>`. Before approval is persisted or any write runs, it requires a fresh complete exact-count account scan and re-checks the whole plan for drift; the current completeness proof is recorded in `approval-record.json`. Ordinary draft updates/deletes use their platform paths. The original V1 alias adapter retains its frozen request and artifact contract for compatibility, but it is not an authorized execution or recovery fallback for a sealed production `merge-support-aliases` plan. That plan must use `run-protected`, whose database contract replaces replay with one durable attempt/admission identity.
 
-`apply` is write-disabled unless all three commit guards are present: `--commit`, `--approve-plan <sha256>`, and `--confirm <current-account-email>`. Before approval is persisted or any write runs, it requires a fresh complete exact-count account scan and re-checks the whole plan for drift; the current completeness proof is recorded in `approval-record.json`. Ordinary draft updates/deletes use their platform paths. The ordered `time` plus `length_time` alias request is sent once to `cmd_dataset_alias_plan_guarded` with `target_visibility=owner_draft`; the CLI has neither a per-dimension fallback nor a 52-write sequential fallback. The RPC locks and validates the complete 52-row/59-exchange closure before both dimensions commit, so a second-dimension failure rolls back the first. It checks actor ownership, state 0, exact payload/timestamp locks and embedded UUID/version, rejects missing or phantom flow/exchange references, and returns one plan summary audit id plus both batch and per-row audit proofs. The CLI writes `alias-plan-progress.jsonl` together with plan-bound per-batch, per-row, and per-exchange ledgers. A lost response or incomplete derived ledger is repaired only by replaying the same whole plan and matching every returned plan and batch proof.
+For `rebuild-derivatives`, apply submits the frozen single-action plan only to the authenticated guarded RPC. The database admission envelope must report `queued`; the CLI records that durable admission as an `accepted` action with queued proof. It does not mean markdown or embedding generation has completed. Replay must return the same durable request/proof rather than enqueueing a second rebuild. There is no fallback to a direct Edge call, `admin embedding-run`, a raw queue, SQL, service-role credentials, or raw REST mutation.
 
-`verify` requires another complete exact-count account readback rather than trusting the apply report, records its completeness proof, and writes `readback-verify-report.json` in its own output directory. For alias plans it also requires both successful batch records, all 52 correlated row records, all 59 unique exchange records, unchanged support snapshots, and exact desired row payloads. It validates the RPC-returned audit ids against the local proof chain; it does not independently query `public.command_audit_log`.
+`verify` requires another complete exact-count account readback rather than trusting the apply report, records its completeness proof, and writes `readback-verify-report.json` in its own output directory. For alias plans it also requires both successful batch records, all 52 correlated row records, all 59 unique exchange records, unchanged support snapshots, and exact desired row payloads. It validates the RPC-returned audit ids against the local proof chain; it does not independently query `public.command_audit_log`. For derivative rebuild plans, verify reads the durable request plus a fresh action-scoped process snapshot and reports only `pending`, `passed`, or `failed`. Database statuses `queued`, `dispatching`, `markdown_pending`, and `embedding_pending` map to `pending`; `completed` maps to `passed` only when both requested derivatives are current and every frozen primary-field precondition remains unchanged; `stale` and `failed` map to `failed`. The raw status proof, including `phase` and `fence_active`, is preserved in the report. A failed rebuild does not by itself prove that the primary-row write fence has been released.
 
 `dataset maintenance clear-account` uses the same exact-count rule for its initial five-table snapshot, per-table commit checks, and a final fresh scan of all five tables. It reports `cleared_account` only when that final aggregate proof exists with `row_count=0`; if the final proof fails after deletions begin, it still writes a `completed_with_failures` audit report. If the initial scan cannot prove completeness, it writes no snapshot or approval artifact and performs zero deletes.
 

package/dist/src/cli.js

@@ -56,6 +56,7 @@ import { runDatasetClassificationApply, runDatasetClassificationAudit, runDatase
 import { runDatasetMaintenanceClearAccount, } from './lib/dataset-maintenance-clear-account.js';
 import { runDatasetMaintenancePlan } from './lib/dataset-maintenance-plan.js';
 import { runDatasetMaintenanceApply } from './lib/dataset-maintenance-apply.js';
+import { runDatasetMaintenanceProtected } from './lib/dataset-maintenance-protected-run.js';
 import { runDatasetMaintenanceVerify } from './lib/dataset-maintenance-verify.js';
 import { runDatasetSourceUploadAttachments, } from './lib/dataset-source-upload-attachments.js';
 function renderMainHelp(dotEnvStatus) {
@@ -131,6 +132,7 @@ Examples:
   tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id>@<old-version> --to flow:<new-id>@<new-version> --out-dir /abs/path/to/dataset-rewrite
   tiangong-lca dataset maintenance clear-account --out-dir /abs/path/to/account-clear --json
   tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir /abs/path/to/dataset-maintenance
+  tiangong-lca dataset maintenance run-protected --plan ./maintenance-plan.json --freeze ./protected-execution-seal.json --approval ./protected-approval.json --out-dir /abs/path/to/protected-run --status-only
   tiangong-lca lifecyclemodel auto-build --input ./lifecyclemodel-auto-build.request.json --out-dir /abs/path/to/lifecyclemodel-run
   tiangong-lca lifecyclemodel validate-build --run-dir /abs/path/to/lifecyclemodel-run
   tiangong-lca lifecyclemodel publish-build --run-dir /abs/path/to/lifecyclemodel-run
@@ -283,6 +285,7 @@ Implemented Subcommands:
   maintenance clear-account Dry-run or clear current authenticated account-owned dataset rows through RLS
   maintenance plan    Build an immutable, RLS-visible row-level maintenance plan
   maintenance apply   Execute an explicitly approved maintenance plan through current-user RLS
+  maintenance run-protected Run or inspect one sealed, one-shot production maintenance execution
   maintenance verify  Read back affected rows and references against the immutable plan
 
 Examples:
@@ -310,21 +313,25 @@ Examples:
   tiangong-lca dataset references refresh-remote --input ./rows.jsonl --out ./rows.refreshed.jsonl --out-dir ./dataset-reference-refresh --help
   tiangong-lca dataset maintenance clear-account --out-dir ./account-clear --json --help
   tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance --help
+  tiangong-lca dataset maintenance run-protected --help
 `.trim();
 }
 function renderDatasetMaintenanceHelp() {
     return `Usage:
-  tiangong-lca dataset maintenance <clear-account|plan|apply|verify> [options]
+  tiangong-lca dataset maintenance <clear-account|plan|apply|run-protected|verify> [options]
 
 Actions:
   clear-account Dry-run or delete current authenticated account-owned lifecyclemodels, processes, flows, sources, and contacts.
   plan    Build an immutable maintenance plan from a scope manifest, visible remote snapshot, dependency impact report, and intended operation.
-  apply   Execute an approved plan through current-user RLS and platform dataset command paths; never bypass RLS or delete rows outside the visible scope.
-  verify  Re-fetch affected rows and references, then prove that deleted, updated, skipped, protected, and redone rows match the plan.
+  apply   Execute or durably admit an ordinary approved plan through current-user RLS and platform dataset command paths.
+  run-protected Run or inspect one sealed production execution with one-shot admission and terminal derivative proof.
+  verify  Re-fetch rows, references, or derivative request state and report passed, pending, or failed independently of apply.
 
 Safety:
   plan and verify are read-only.
   apply is commit-only and requires --commit, the exact plan SHA-256 via --approve-plan, and the current account email via --confirm.
+  A sealed production merge-support-aliases execution must use run-protected; apply is not its fallback.
+  run-protected is production-only: authenticated owner context plus server-side actor/user_id/state_code=0 and exact-plan closure fences protect writes; RLS remains a defense on public and independent-read surfaces. It never falls back to dev, a legacy alias RPC, or a second admission POST.
 
 Required Artifact Contract:
   - maintenance-plan.json
@@ -334,12 +341,15 @@ Required Artifact Contract:
   - dry-run-report.json
   - commit-report.json
   - readback-verify-report.json
+  run-protected uses a separate immutable protected-execution seal, submission marker, append-only status ledger, and terminal report.
 
 Examples:
   tiangong-lca dataset maintenance clear-account --out-dir ./account-clear --json
   tiangong-lca dataset maintenance clear-account --commit --confirm user@example.com --out-dir ./account-clear
-  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation repair-references --out-dir ./dataset-maintenance
+  tiangong-lca dataset maintenance plan --scope ./derivative-rebuild-scope.json --operation rebuild-derivatives --out-dir ./derivative-rebuild
   tiangong-lca dataset maintenance apply --plan ./dataset-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm user@example.com
+  tiangong-lca dataset maintenance run-protected --plan ./maintenance-plan.json --freeze ./protected-execution-seal.json --approval ./protected-approval.json --out-dir ./protected-run --status-only
   tiangong-lca dataset maintenance verify --plan ./dataset-maintenance/maintenance-plan.json --out-dir ./dataset-maintenance/verify
 `.trim();
 }
@@ -348,7 +358,7 @@ function renderDatasetMaintenancePlanHelp() {
   tiangong-lca dataset maintenance plan --scope <file> --operation <operation> --out-dir <dir> [options]
 
 Operations:
-  delete | retire | redo-import | repair-references | merge-support-aliases
+  delete | retire | redo-import | repair-references | merge-support-aliases | rebuild-derivatives
 
 Options:
   --scope <file>       Maintenance scope manifest
@@ -360,7 +370,8 @@ Options:
   -h, --help
 
 Outputs written under --out-dir include the immutable maintenance-plan.json, visible snapshot,
-protected-row ledger, reference-impact report, and dry-run report.
+protected-row ledger, reference-impact report, and dry-run report. rebuild-derivatives additionally
+freezes one action-scoped database snapshot without expanding the account scan with vector data.
 `.trim();
 }
 function renderDatasetMaintenanceApplyHelp() {
@@ -370,6 +381,8 @@ function renderDatasetMaintenanceApplyHelp() {
 Behavior:
   Commit-only. The command rejects dry-run mode, a missing --commit flag, a plan hash mismatch,
   or a confirmation email that does not match the current authenticated account.
+  For rebuild-derivatives, success means guarded admission is queued; it never means derivatives completed.
+  Sealed production merge-support-aliases executions must use run-protected; this command is not a fallback.
 
 Options:
   --plan <file>          Immutable maintenance-plan.json
@@ -380,7 +393,46 @@ Options:
   --json                 Print compact JSON
   -h, --help
 
-Outputs include approval-record.json and commit-report.json alongside an append-only action ledger.
+Outputs include approval-record.json and commit-report.json alongside an append-only action or admission ledger.
+`.trim();
+}
+function renderDatasetMaintenanceRunProtectedHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance run-protected --plan <file> --freeze <file> --approval <file> --out-dir <dir> --commit --approve-execution <sha256> --confirm <email> [options]
+  tiangong-lca dataset maintenance run-protected --plan <file> --freeze <file> --approval <file> --out-dir <dir> --status-only [options]
+
+Behavior:
+  Runs one sealed, server-dispatched production maintenance execution fenced to the authenticated actor's
+  exact owner-draft target set, or reads durable status through an auth.uid-, actor-, and plan-fenced RPC
+  without admitting work; only the independent table readback uses RLS.
+  Commit and status-only modes are mutually exclusive. The commit path validates the full private
+  before-state, accepts only server-derived gates within the 180-second preflight window, writes an immutable
+  local submission marker, and sends at most one admission POST. After a marker or ambiguous response,
+  use --status-only; the command never retries admission or falls back to dev or the legacy alias RPC.
+
+Required in both modes:
+  --plan <file>             Immutable maintenance-plan.json
+  --freeze <file>           Protected production execution seal/freeze artifact
+  --approval <file>         Exact human-approval binding artifact
+  --out-dir <dir>           Private protected-run artifact directory
+
+Commit-only guards:
+  --commit                  Submit the sealed execution exactly once
+  --approve-execution <sha256> Exact approved execution identity SHA-256
+  --confirm <email>         Current authenticated account email
+
+Recovery:
+  --status-only             Read/poll and independently verify the sealed request; never preflight or admit
+
+Options:
+  --wait-seconds <n>        Maximum terminal-status wait in seconds; 0 performs one status read
+  --poll-ms <n>             Positive polling interval in milliseconds; default 10000
+  --page-size <n>           Requested RLS readback page size, 1-5000
+  --timeout-ms <n>          Positive request timeout in milliseconds
+  --json                    Print compact JSON
+  -h, --help
+
+Only a terminal passed proof exits successfully. pending, failed, and indeterminate return non-zero.
 `.trim();
 }
 function renderDatasetMaintenanceVerifyHelp() {
@@ -395,7 +447,8 @@ Options:
   --json              Print compact JSON
   -h, --help
 
-Outputs include readback-verify-report.json with affected-row and reference checks.
+Outputs include readback-verify-report.json. rebuild-derivatives reports pending, passed, or failed;
+pending and failed both return a non-zero exit status.
 `.trim();
 }
 function renderDatasetMaintenanceClearAccountHelp() {
@@ -3036,6 +3089,19 @@ function parseDatasetMaintenancePositiveInteger(value, flagName) {
     }
     return Number.parseInt(value.trim(), 10);
 }
+function parseDatasetMaintenanceNonNegativeInteger(value, flagName) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    if (!/^\d+$/u.test(value.trim())) {
+        throw new CliError(`${flagName} must be a non-negative integer.`, {
+            code: 'DATASET_MAINTENANCE_INTEGER_INVALID',
+            exitCode: 2,
+            details: { flag: flagName, value },
+        });
+    }
+    return Number.parseInt(value.trim(), 10);
+}
 function parseDatasetMaintenancePlanFlags(args) {
     let values;
     try {
@@ -3062,8 +3128,15 @@ function parseDatasetMaintenancePlanFlags(args) {
     }
     const rawOperation = typeof values.operation === 'string' ? values.operation : null;
     if (rawOperation !== null &&
-        !['delete', 'retire', 'redo-import', 'repair-references', 'merge-support-aliases'].includes(rawOperation)) {
-        throw new CliError("--operation must be 'delete', 'retire', 'redo-import', 'repair-references', or 'merge-support-aliases'.", {
+        ![
+            'delete',
+            'retire',
+            'redo-import',
+            'repair-references',
+            'merge-support-aliases',
+            'rebuild-derivatives',
+        ].includes(rawOperation)) {
+        throw new CliError("--operation must be 'delete', 'retire', 'redo-import', 'repair-references', 'merge-support-aliases', or 'rebuild-derivatives'.", {
             code: 'DATASET_MAINTENANCE_OPERATION_INVALID',
             exitCode: 2,
             details: rawOperation,
@@ -3115,6 +3188,54 @@ function parseDatasetMaintenanceApplyFlags(args) {
         dryRun: Boolean(values['dry-run']),
     };
 }
+function parseDatasetMaintenanceProtectedFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                plan: { type: 'string' },
+                freeze: { type: 'string' },
+                approval: { type: 'string' },
+                'out-dir': { type: 'string' },
+                commit: { type: 'boolean' },
+                'status-only': { type: 'boolean' },
+                'approve-execution': { type: 'string' },
+                confirm: { type: 'string' },
+                'wait-seconds': { type: 'string' },
+                'poll-ms': { type: 'string' },
+                'page-size': { type: 'string' },
+                'timeout-ms': { type: 'string' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        planPath: typeof values.plan === 'string' ? values.plan : '',
+        freezePath: typeof values.freeze === 'string' ? values.freeze : '',
+        approvalPath: typeof values.approval === 'string' ? values.approval : '',
+        outDir: typeof values['out-dir'] === 'string' ? values['out-dir'] : '',
+        commit: Boolean(values.commit),
+        statusOnly: Boolean(values['status-only']),
+        approveExecution: typeof values['approve-execution'] === 'string' ? values['approve-execution'] : undefined,
+        confirm: typeof values.confirm === 'string' ? values.confirm : undefined,
+        waitSeconds: parseDatasetMaintenanceNonNegativeInteger(values['wait-seconds'], '--wait-seconds'),
+        pollMs: parseDatasetMaintenancePositiveInteger(values['poll-ms'], '--poll-ms'),
+        pageSize: parseDatasetMaintenancePositiveInteger(values['page-size'], '--page-size'),
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+    };
+}
 function parseDatasetMaintenanceVerifyFlags(args) {
     let values;
     try {
@@ -4894,6 +5015,7 @@ export async function executeCli(argv, deps) {
         const datasetMaintenanceClearAccountImpl = deps.runDatasetMaintenanceClearAccountImpl ?? runDatasetMaintenanceClearAccount;
         const datasetMaintenancePlanImpl = deps.runDatasetMaintenancePlanImpl ?? runDatasetMaintenancePlan;
         const datasetMaintenanceApplyImpl = deps.runDatasetMaintenanceApplyImpl ?? runDatasetMaintenanceApply;
+        const datasetMaintenanceProtectedImpl = deps.runDatasetMaintenanceProtectedImpl ?? runDatasetMaintenanceProtected;
         const datasetMaintenanceVerifyImpl = deps.runDatasetMaintenanceVerifyImpl ?? runDatasetMaintenanceVerify;
         const datasetSourceUploadAttachmentsImpl = deps.runDatasetSourceUploadAttachmentsImpl ?? runDatasetSourceUploadAttachments;
         if (flags.version) {
@@ -5606,6 +5728,85 @@ export async function executeCli(argv, deps) {
                     stderr: '',
                 };
             }
+            if (action === 'run-protected') {
+                const datasetFlags = parseDatasetMaintenanceProtectedFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenanceRunProtectedHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.planPath) {
+                    throw new CliError('dataset maintenance run-protected requires --plan.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_PLAN_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.freezePath) {
+                    throw new CliError('dataset maintenance run-protected requires --freeze.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_FREEZE_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.approvalPath) {
+                    throw new CliError('dataset maintenance run-protected requires --approval.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_APPROVAL_FILE_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.outDir) {
+                    throw new CliError('dataset maintenance run-protected requires --out-dir.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_OUT_DIR_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.commit && datasetFlags.statusOnly) {
+                    throw new CliError('Cannot pass both --commit and --status-only.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_MODE_CONFLICT',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.commit && !datasetFlags.statusOnly) {
+                    throw new CliError('dataset maintenance run-protected requires either --commit or --status-only.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_MODE_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.commit && !datasetFlags.approveExecution) {
+                    throw new CliError('dataset maintenance run-protected requires --approve-execution <sha256> with --commit.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_APPROVAL_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.commit && !datasetFlags.confirm) {
+                    throw new CliError('dataset maintenance run-protected requires --confirm <email> with --commit.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_CONFIRM_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenanceProtectedImpl({
+                    planPath: datasetFlags.planPath,
+                    freezePath: datasetFlags.freezePath,
+                    approvalPath: datasetFlags.approvalPath,
+                    outDir: datasetFlags.outDir,
+                    commit: datasetFlags.commit,
+                    statusOnly: datasetFlags.statusOnly,
+                    approveExecution: datasetFlags.approveExecution,
+                    confirm: datasetFlags.confirm,
+                    waitSeconds: datasetFlags.waitSeconds,
+                    pollMs: datasetFlags.pollMs,
+                    pageSize: datasetFlags.pageSize,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
+                });
+                return {
+                    exitCode: report.status === 'passed' ? 0 : 1,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
+            }
             if (action === 'verify') {
                 const datasetFlags = parseDatasetMaintenanceVerifyFlags(commandArgs.slice(1));
                 if (datasetFlags.help) {
@@ -5630,12 +5831,12 @@ export async function executeCli(argv, deps) {
                     fetchImpl: deps.fetchImpl,
                 });
                 return {
-                    exitCode: report.status === 'failed' ? 1 : 0,
+                    exitCode: report.status === 'passed' ? 0 : 1,
                     stdout: stringifyJson(report, datasetFlags.json),
                     stderr: '',
                 };
             }
-            throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', or 'verify'.", {
+            throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', 'run-protected', or 'verify'.", {
                 code: 'DATASET_MAINTENANCE_ACTION_INVALID',
                 exitCode: 2,
             });