@tiangong-lca/cli 0.0.21 → 0.0.23

package/README.md

@@ -17,14 +17,18 @@ checkPaths:
   - bin/**
   - src/cli.ts
   - src/main.ts
-lastReviewedAt: 2026-06-29
-lastReviewedCommit: 695e6d6fe718cb92d499f3ce8be2dc24c3f6ce29
+lastReviewedAt: 2026-07-13
+lastReviewedCommit: 4c79df4623e3cf296bc8d1baeea688d78351570a
 ---
 
 # TianGong LCA CLI
 
 Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Node: `24.x`
 
+Review note, 2026-07-12: `dataset maintenance plan/apply/verify` provides current-user RLS-scoped exact-row maintenance with immutable plans, explicit approval, per-action logs, platform audit correlation, and independent readback. `merge-support-aliases` now runs only in `target_mode=owner_draft`: source/target support and all changed rows stay private `state_code=0`; publication is a separate future workflow.
+
+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.
+
 ## Run
 
 One-off published run:
@@ -273,7 +277,9 @@ tiangong-lca dataset curation-queue verify --queue-dir /abs/path/to/curation-que
 tiangong-lca dataset evidence-search plan --query "中国2026年电力结构数据" --out-dir /abs/path/to/evidence-search --json
 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
+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 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 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
@@ -316,7 +322,58 @@ For `dataset curation-queue build/next/verify`, the CLI owns entity-level Foundr
 
 For `dataset references rewrite`, `--commit` executes the state-aware save-draft path for patched process and lifecyclemodel rows; without `--commit`, the command only writes local rewrite artifacts.
 
-For `dataset maintenance plan/apply/verify`, the planned command family owns RLS-scoped delete/redo workflows for bad imports. The contract requires a frozen scope manifest, current-user visible snapshot, protected rows list, reference impact report, dry-run report, explicit commit report, and readback verification. Foundry and skills may orchestrate it, but they must not add private Supabase delete logic.
+## 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.
+
+```bash
+tiangong-lca dataset maintenance plan \
+  --scope ./maintenance-scope.json \
+  --operation merge-support-aliases \
+  --out-dir ./dataset-maintenance \
+  --page-size 1000 \
+  --timeout-ms 10000 \
+  --json
+
+tiangong-lca dataset maintenance apply \
+  --plan ./dataset-maintenance/maintenance-plan.json \
+  --commit \
+  --approve-plan <sha256> \
+  --confirm <current-account-email> \
+  --timeout-ms 10000 \
+  --json
+
+tiangong-lca dataset maintenance verify \
+  --plan ./dataset-maintenance/maintenance-plan.json \
+  --out-dir ./dataset-maintenance/verify \
+  --page-size 1000 \
+  --timeout-ms 10000 \
+  --json
+```
+
+`--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.
+
+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.
+- 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.
+- 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.
+
+`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.
+
+`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`.
+
+`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.
+
+Foundry and skills may prepare the scope, invoke these commands, and retain their artifacts. They must not replace the CLI with direct SQL, service-role access, raw REST mutation, or private Supabase delete/update code.
 
 ## More Docs
 

package/dist/src/cli.js

@@ -54,6 +54,9 @@ import { runDatasetPatchApply, } from './lib/dataset-patch.js';
 import { runDatasetSaveDraft, } from './lib/dataset-save-draft-run.js';
 import { runDatasetClassificationApply, runDatasetClassificationAudit, runDatasetClassificationChildren, runDatasetClassificationPath, } from './lib/dataset-classification.js';
 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 { runDatasetMaintenanceVerify } from './lib/dataset-maintenance-verify.js';
 import { runDatasetSourceUploadAttachments, } from './lib/dataset-source-upload-attachments.js';
 function renderMainHelp(dotEnvStatus) {
     return `TianGong LCA CLI
@@ -74,7 +77,7 @@ Implemented Commands:
   doctor     show environment diagnostics
   search     flow | process | lifecyclemodel
   process    get | list | identity-preflight | build-plan | scope-statistics | dedup-review | auto-build | resume-build | publish-build | complete-required-fields | save-draft | batch-build | refresh-references | verify-rows
-  dataset    contract get | context-pack | classification children/path/audit/apply | curation-queue build/next/verify | import-lca convert | author | patch apply | save-draft | source upload-attachments | validate | verify-remote | bilingual extract/apply/validate | evidence-search plan/run | references rewrite/refresh-remote | maintenance clear-account
+  dataset    contract get | context-pack | classification children/path/audit/apply | curation-queue build/next/verify | import-lca convert | author | patch apply | save-draft | source upload-attachments | validate | verify-remote | bilingual extract/apply/validate | evidence-search plan/run | references rewrite/refresh-remote | maintenance clear-account/plan/apply/verify
   flow       get | list | identity-preflight | build-plan | fetch-rows | materialize-decisions | remediate | publish-version | publish-reviewed-data | build-alias-map | scan-process-flow-refs | plan-process-flow-repairs | apply-process-flow-repairs | regen-product | validate-processes
   lifecyclemodel auto-build | validate-build | publish-build | save-draft | graph | build-resulting-process | publish-resulting-process | orchestrate
   qa         process | flow | lifecyclemodel
@@ -85,7 +88,6 @@ Implemented Commands:
 Planned Surface (not implemented yet):
   auth       whoami | doctor-auth
   job        get | wait | logs
-  dataset maintenance plan | apply | verify
 
 Planned commands currently print an explicit "not implemented yet" message and exit with code 2.
 
@@ -128,7 +130,7 @@ Examples:
   tiangong-lca dataset evidence-search run --input ./evidence-search.request.json --results ./search-results.json --out-dir ./evidence-search
   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 redo-import --out-dir /abs/path/to/dataset-maintenance
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir /abs/path/to/dataset-maintenance
   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
@@ -279,9 +281,9 @@ Implemented Subcommands:
   references rewrite   Rewrite flow references in local process and lifecyclemodel rows
   references refresh-remote Refresh local TIDAS reference versions to latest reachable remote rows
   maintenance clear-account Dry-run or clear current authenticated account-owned dataset rows through RLS
-
-Planned Subcommands:
-  maintenance plan/apply/verify Plan, execute, and verify RLS-scoped dataset delete/redo maintenance
+  maintenance plan    Build an immutable, RLS-visible row-level maintenance plan
+  maintenance apply   Execute an explicitly approved maintenance plan through current-user RLS
+  maintenance verify  Read back affected rows and references against the immutable plan
 
 Examples:
   tiangong-lca dataset contract get --type process --include schema,methodology,ruleset --out-dir ./contract --help
@@ -307,25 +309,23 @@ Examples:
   tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id>@<old-version> --to flow:<new-id>@<new-version> --out-dir ./dataset-rewrite --help
   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 redo-import --out-dir ./dataset-maintenance --help
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance --help
 `.trim();
 }
 function renderDatasetMaintenanceHelp() {
     return `Usage:
   tiangong-lca dataset maintenance <clear-account|plan|apply|verify> [options]
 
-Status:
-  clear-account is implemented for current authenticated account cleanup.
-  plan/apply/verify remain reserved for row-level RLS-scoped cleanup and redo workflows and currently exit with code 2 for executable actions.
-
-Implemented Actions:
+Actions:
   clear-account Dry-run or delete current authenticated account-owned lifecyclemodels, processes, flows, sources, and contacts.
-
-Planned Actions:
   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.
 
+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.
+
 Required Artifact Contract:
   - maintenance-plan.json
   - rls-visible-snapshot.json
@@ -338,11 +338,66 @@ Required Artifact Contract:
 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 redo-import --out-dir ./dataset-maintenance
-  tiangong-lca dataset maintenance apply --plan ./dataset-maintenance/maintenance-plan.json --commit
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance
+  tiangong-lca dataset maintenance apply --plan ./dataset-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm user@example.com
   tiangong-lca dataset maintenance verify --plan ./dataset-maintenance/maintenance-plan.json --out-dir ./dataset-maintenance/verify
 `.trim();
 }
+function renderDatasetMaintenancePlanHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance plan --scope <file> --operation <operation> --out-dir <dir> [options]
+
+Operations:
+  delete | retire | redo-import | repair-references | merge-support-aliases
+
+Options:
+  --scope <file>       Maintenance scope manifest
+  --operation <value> Intended row-level maintenance operation
+  --out-dir <dir>      Artifact directory
+  --page-size <n>      Requested snapshot page size, 1-5000 (default: 1000); server caps are followed using exact counts
+  --timeout-ms <n>     Request timeout in milliseconds
+  --json               Print compact JSON
+  -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.
+`.trim();
+}
+function renderDatasetMaintenanceApplyHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance apply --plan <file> --commit --approve-plan <sha256> --confirm <email> [options]
+
+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.
+
+Options:
+  --plan <file>          Immutable maintenance-plan.json
+  --commit               Execute the approved plan
+  --approve-plan <sha256> Exact SHA-256 recorded for the plan
+  --confirm <email>      Current authenticated account email
+  --timeout-ms <n>       Request timeout in milliseconds
+  --json                 Print compact JSON
+  -h, --help
+
+Outputs include approval-record.json and commit-report.json alongside an append-only action ledger.
+`.trim();
+}
+function renderDatasetMaintenanceVerifyHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance verify --plan <file> [options]
+
+Options:
+  --plan <file>       Immutable maintenance-plan.json
+  --out-dir <dir>     Optional verification artifact directory
+  --page-size <n>     Requested readback page size, 1-5000 (default: 1000); server caps are followed using exact counts
+  --timeout-ms <n>    Request timeout in milliseconds
+  --json              Print compact JSON
+  -h, --help
+
+Outputs include readback-verify-report.json with affected-row and reference checks.
+`.trim();
+}
 function renderDatasetMaintenanceClearAccountHelp() {
     return `Usage:
   tiangong-lca dataset maintenance clear-account [options]
@@ -355,7 +410,7 @@ Behavior:
 Options:
   --state-code <n>    Optional repeatable state_code filter. Omit to clear all state codes for the current account.
   --out-dir <dir>     Artifact directory (default: ./dataset-maintenance/clear-account)
-  --page-size <n>     Snapshot page size, 1-5000 (default: 1000)
+  --page-size <n>     Requested snapshot page size, 1-5000 (default: 1000); server caps are followed using exact counts
   --timeout-ms <n>    Request timeout in milliseconds (default: 10000)
   --commit            Execute deletion. Without this flag the command only writes a dry-run report.
   --dry-run           Explicit dry-run mode
@@ -369,6 +424,8 @@ Outputs written under --out-dir:
   - approval-record.json       (commit only)
   - commit-report.json         (commit only)
   - readback-verify-report.json (commit only)
+
+Every snapshot/readback must prove complete exact-count pagination before an artifact or delete is accepted.
 `.trim();
 }
 function renderDatasetContractHelp() {
@@ -2966,6 +3023,130 @@ function parseDatasetMaintenanceClearAccountFlags(args) {
         confirm: typeof values.confirm === 'string' ? values.confirm : null,
     };
 }
+function parseDatasetMaintenancePositiveInteger(value, flagName) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    if (!/^\d+$/u.test(value.trim()) || Number.parseInt(value.trim(), 10) <= 0) {
+        throw new CliError(`${flagName} must be a positive integer.`, {
+            code: 'DATASET_MAINTENANCE_INTEGER_INVALID',
+            exitCode: 2,
+            details: { flag: flagName, value },
+        });
+    }
+    return Number.parseInt(value.trim(), 10);
+}
+function parseDatasetMaintenancePlanFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                scope: { type: 'string' },
+                operation: { type: 'string' },
+                'out-dir': { type: 'string' },
+                'page-size': { type: 'string' },
+                'timeout-ms': { type: 'string' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    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'.", {
+            code: 'DATASET_MAINTENANCE_OPERATION_INVALID',
+            exitCode: 2,
+            details: rawOperation,
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        scopePath: typeof values.scope === 'string' ? values.scope : '',
+        operation: rawOperation,
+        outDir: typeof values['out-dir'] === 'string' ? values['out-dir'] : '',
+        pageSize: parseDatasetMaintenancePositiveInteger(values['page-size'], '--page-size'),
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+    };
+}
+function parseDatasetMaintenanceApplyFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                plan: { type: 'string' },
+                commit: { type: 'boolean' },
+                'approve-plan': { type: 'string' },
+                confirm: { type: 'string' },
+                'timeout-ms': { type: 'string' },
+                'dry-run': { type: 'boolean' },
+            },
+        }));
+    }
+    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 : '',
+        commit: Boolean(values.commit),
+        approvePlan: typeof values['approve-plan'] === 'string' ? values['approve-plan'] : '',
+        confirm: typeof values.confirm === 'string' ? values.confirm : '',
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+        dryRun: Boolean(values['dry-run']),
+    };
+}
+function parseDatasetMaintenanceVerifyFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                plan: { type: 'string' },
+                'out-dir': { 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 : '',
+        outDir: typeof values['out-dir'] === 'string' ? values['out-dir'] : undefined,
+        pageSize: parseDatasetMaintenancePositiveInteger(values['page-size'], '--page-size'),
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+    };
+}
 function parseIdentityPreflightFlags(args) {
     let values;
     try {
@@ -4711,6 +4892,9 @@ export async function executeCli(argv, deps) {
         const datasetClassificationAuditImpl = deps.runDatasetClassificationAuditImpl ?? runDatasetClassificationAudit;
         const datasetClassificationApplyImpl = deps.runDatasetClassificationApplyImpl ?? runDatasetClassificationApply;
         const datasetMaintenanceClearAccountImpl = deps.runDatasetMaintenanceClearAccountImpl ?? runDatasetMaintenanceClearAccount;
+        const datasetMaintenancePlanImpl = deps.runDatasetMaintenancePlanImpl ?? runDatasetMaintenancePlan;
+        const datasetMaintenanceApplyImpl = deps.runDatasetMaintenanceApplyImpl ?? runDatasetMaintenanceApply;
+        const datasetMaintenanceVerifyImpl = deps.runDatasetMaintenanceVerifyImpl ?? runDatasetMaintenanceVerify;
         const datasetSourceUploadAttachmentsImpl = deps.runDatasetSourceUploadAttachmentsImpl ?? runDatasetSourceUploadAttachments;
         if (flags.version) {
             return { exitCode: 0, stdout: `${loadCliPackageVersion(import.meta.url)}\n`, stderr: '' };
@@ -5320,13 +5504,141 @@ export async function executeCli(argv, deps) {
                     stderr: '',
                 };
             }
-            if (!['plan', 'apply', 'verify'].includes(action)) {
-                throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', or 'verify'.", {
-                    code: 'DATASET_MAINTENANCE_ACTION_INVALID',
-                    exitCode: 2,
+            if (action === 'plan') {
+                const datasetFlags = parseDatasetMaintenancePlanFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenancePlanHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.scopePath) {
+                    throw new CliError('dataset maintenance plan requires --scope.', {
+                        code: 'DATASET_MAINTENANCE_SCOPE_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.operation) {
+                    throw new CliError('dataset maintenance plan requires --operation.', {
+                        code: 'DATASET_MAINTENANCE_OPERATION_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.outDir) {
+                    throw new CliError('dataset maintenance plan requires --out-dir.', {
+                        code: 'DATASET_MAINTENANCE_OUT_DIR_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenancePlanImpl({
+                    scopePath: datasetFlags.scopePath,
+                    operation: datasetFlags.operation,
+                    outDir: datasetFlags.outDir,
+                    pageSize: datasetFlags.pageSize,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
                 });
+                return {
+                    exitCode: report.status === 'blocked' ? 1 : 0,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
             }
-            return plannedCommand('dataset', `maintenance ${action}`);
+            if (action === 'apply') {
+                const datasetFlags = parseDatasetMaintenanceApplyFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenanceApplyHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.planPath) {
+                    throw new CliError('dataset maintenance apply requires --plan.', {
+                        code: 'DATASET_MAINTENANCE_PLAN_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.commit && datasetFlags.dryRun) {
+                    throw new CliError('Cannot pass both --commit and --dry-run.', {
+                        code: 'DATASET_MAINTENANCE_APPLY_MODE_CONFLICT',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.dryRun) {
+                    throw new CliError('dataset maintenance apply is commit-only; use dataset maintenance plan for a dry run.', {
+                        code: 'DATASET_MAINTENANCE_APPLY_COMMIT_ONLY',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.commit) {
+                    throw new CliError('dataset maintenance apply requires --commit.', {
+                        code: 'DATASET_MAINTENANCE_APPLY_COMMIT_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.approvePlan) {
+                    throw new CliError('dataset maintenance apply requires --approve-plan <sha256>.', {
+                        code: 'DATASET_MAINTENANCE_APPROVAL_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.confirm) {
+                    throw new CliError('dataset maintenance apply requires --confirm <email>.', {
+                        code: 'DATASET_MAINTENANCE_CONFIRM_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenanceApplyImpl({
+                    planPath: datasetFlags.planPath,
+                    commit: datasetFlags.commit,
+                    approvePlan: datasetFlags.approvePlan,
+                    confirm: datasetFlags.confirm,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
+                });
+                return {
+                    exitCode: report.status === 'completed_with_failures' ? 1 : 0,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
+            }
+            if (action === 'verify') {
+                const datasetFlags = parseDatasetMaintenanceVerifyFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenanceVerifyHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.planPath) {
+                    throw new CliError('dataset maintenance verify requires --plan.', {
+                        code: 'DATASET_MAINTENANCE_PLAN_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenanceVerifyImpl({
+                    planPath: datasetFlags.planPath,
+                    outDir: datasetFlags.outDir,
+                    pageSize: datasetFlags.pageSize,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
+                });
+                return {
+                    exitCode: report.status === 'failed' ? 1 : 0,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
+            }
+            throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', or 'verify'.", {
+                code: 'DATASET_MAINTENANCE_ACTION_INVALID',
+                exitCode: 2,
+            });
         }
         if (command === 'lifecyclemodel' && !subcommand) {
             return { exitCode: 0, stdout: `${renderLifecyclemodelHelp()}\n`, stderr: '' };