@tiangong-lca/cli 0.0.31 → 0.0.33

package/README.md

@@ -43,6 +43,10 @@ Review note, 2026-07-17: `dataset maintenance flow-identity capture|plan|freeze|
 
 Review note, 2026-07-23: `dataset save-draft --execution-contract` adds an opt-in crash-safe ordered owner-draft batch. The contract binds the authenticated project/owner, state 0, exact input order and payloads, before hashes, expected insert/update operations, and dependencies. A stable per-owner/project `action_id@desired_sha256` ledger prevents replay even if the contract or output directory is copied; ambiguous attempts are recovered only by exact owner/state/payload readback. The ordinary save-draft mode is unchanged.
 
+Review note, 2026-07-24: CLI 0.0.32 adds bounded execution-contract concurrency without changing the sealed payload or replay model. `--max-parallel 1..8` keeps the complete dependency prefix serial and exact-read-back, then overlaps only the unique-target suffix. The current owner token is renewed and revalidated before each DML dispatch so long batches do not turn token expiry into an avoidable UNKNOWN.
+
+Review note, 2026-07-24: CLI 0.0.33 adds an explicit `dataset maintenance apply --max-parallel 1..8` profile for large owner-draft flow convergence. It accepts only unique flow delete-only plans with zero frozen and fresh visible-process inbound references, persists `PREPARED` and `DISPATCHED` before each protected RPC, requires exact absent readback for `COMMITTED`, never automatically replays success or UNKNOWN, and continues independent rows.
+
 ## Run
 
 One-off published run:
@@ -365,13 +369,14 @@ tiangong-lca dataset classification apply --type location --input ./rows/process
 tiangong-lca dataset curation-queue build --processes ./rows/processes.jsonl --flows ./rows/flows.jsonl --support ./rows/sources.jsonl --out-dir /abs/path/to/curation-queue --json
 tiangong-lca dataset curation-queue next --queue-dir /abs/path/to/curation-queue --type support --json
 tiangong-lca dataset curation-queue verify --queue-dir /abs/path/to/curation-queue --type process --json
-tiangong-lca dataset save-draft --input ./rows.jsonl --type auto --execution-contract ./execution-contract.json --out-dir /abs/path/to/dataset-save-draft --commit --json
+tiangong-lca dataset save-draft --input ./rows.jsonl --type auto --execution-contract ./execution-contract.json --max-parallel 8 --out-dir /abs/path/to/dataset-save-draft --commit --json
 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 --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 apply --plan /abs/path/to/flow-delete-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm <current-account-email> --max-parallel 8 --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-freeze.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
@@ -400,7 +405,9 @@ For `process build-plan` and `flow build-plan`, canonical payloads embedded in t
 
 For `process save-draft`, canonical process payloads are validated locally with `ProcessSchema` before any `--commit` write. Schema-invalid rows remain in `outputs/save-draft-rpc/failures.jsonl` instead of being persisted. Batch import callers should pass `--target-user-id`; the CLI then verifies the current auth session and any visible draft owner before writing, while downstream readback verification still proves the final owner and payload.
 
-For `dataset save-draft --execution-contract`, the JSON contract uses schema `dataset-save-draft-execution-contract.v1` and supplies `execution_id`, `project_ref`, an exact owner (`user_id`, lowercase `email`, `state_code: 0`), and ordered actions. Each action binds `action_id`, `desired_sha256`, `expected_operation` (`insert` or `save_draft`), table/id/version, `before_sha256`, and earlier `dependency_action_ids`. Contract mode requires `--commit`; account-local Unit Group or Flow Property support rows additionally require `--allow-account-local-support`. Attempts and outcomes are stored under the platform user-state directory (`$XDG_STATE_HOME/tiangong-lca-cli` when configured), not beside the contract or report. Any prior terminal or unresolved attempt is read back or retained without re-dispatch; exit status is nonzero unless every action has exact terminal success.
+For `dataset save-draft --execution-contract`, the JSON contract uses schema `dataset-save-draft-execution-contract.v1` and supplies `execution_id`, `project_ref`, an exact owner (`user_id`, lowercase `email`, `state_code: 0`), and ordered actions. Each action binds `action_id`, `desired_sha256`, `expected_operation` (`insert` or `save_draft`), table/id/version, `before_sha256`, and earlier `dependency_action_ids`. Contract mode requires `--commit`; account-local Unit Group or Flow Property support rows additionally require `--allow-account-local-support`. `--max-parallel` defaults to 1 and is capped at 8. When it is greater than 1, every action through the highest referenced dependency remains serial; only the later table/id/version-unique suffix may overlap. The exact owner token is renewed and checked before each DML dispatch. Attempts and outcomes are stored under the platform user-state directory (`$XDG_STATE_HOME/tiangong-lca-cli` when configured), not beside the contract or report. Any prior terminal or unresolved attempt is read back or retained without re-dispatch; exit status is nonzero unless every action has exact terminal success.
+
+For `dataset maintenance apply`, explicitly passing `--max-parallel 1..8` opts into the destructive flow-convergence profile. It accepts only a non-empty, unique-target, flow delete-only plan whose current and projected reference impacts are both zero. Before dispatch it also completes a fresh SELECT-only scan of every process visible to the owner session and rejects any inbound edge. Each action writes append-only `PREPARED` and `DISPATCHED` evidence before its protected owner-session RPC, then records `COMMITTED` only after exact absent readback. An ambiguous action is read back, marked `UNKNOWN`, and never replayed automatically; independent actions continue. Omit the flag to retain ordinary maintenance apply behavior.
 
 For `flow publish-version`, canonical flow payloads are validated locally with `FlowSchema` before remote visibility planning or writes. The command always writes `flow-publish-version-gate-report.json`; blocked rows are written to the remote-failure JSONL without calling the remote service.
 

package/dist/src/cli.js

@@ -536,6 +536,7 @@ Options:
   --approve-plan <sha256> Exact SHA-256 recorded for the plan
   --confirm <email>      Current authenticated account email
   --timeout-ms <n>       Request timeout in milliseconds
+  --max-parallel <1-8>   Opt into bounded flow delete-only execution with durable dispatch ledger
   --json                 Print compact JSON
   -h, --help
 
@@ -947,6 +948,8 @@ Options:
   --dry-run        Validate and plan without remote writes (default)
   --execution-contract <file>
                    Execute a content-bound ordered owner-draft batch with append-only attempt/readback evidence (requires --commit)
+  --max-parallel <1-8>
+                   Keep the dependency prefix serial, then run only the target-unique suffix with this concurrency (default: 1)
   --allow-account-local-support
                    Explicitly permit account-local Unit Group / Flow Property rows in the execution contract
   --json           Print compact JSON
@@ -2484,6 +2487,7 @@ function parseDatasetSaveDraftFlags(args) {
                 'dry-run': { type: 'boolean' },
                 'allow-account-local-support': { type: 'boolean' },
                 'execution-contract': { type: 'string' },
+                'max-parallel': { type: 'string' },
             },
         }));
     }
@@ -2499,6 +2503,18 @@ function parseDatasetSaveDraftFlags(args) {
             exitCode: 2,
         });
     }
+    const maxParallelValue = values['max-parallel'];
+    const maxParallel = typeof maxParallelValue === 'string' && /^\d+$/u.test(maxParallelValue)
+        ? Number.parseInt(maxParallelValue, 10)
+        : maxParallelValue === undefined
+            ? 1
+            : Number.NaN;
+    if (!Number.isInteger(maxParallel) || maxParallel < 1 || maxParallel > 8) {
+        throw new CliError('--max-parallel must be an integer from 1 to 8.', {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
     return {
         help: Boolean(values.help),
         json: Boolean(values.json),
@@ -2508,6 +2524,7 @@ function parseDatasetSaveDraftFlags(args) {
         commit: Boolean(values.commit),
         allowReferenceOnlySupport: Boolean(values['allow-account-local-support']),
         executionContractPath: typeof values['execution-contract'] === 'string' ? values['execution-contract'] : null,
+        maxParallel,
     };
 }
 function parseDatasetSourceUploadAttachmentsFlags(args) {
@@ -3443,6 +3460,7 @@ function parseDatasetMaintenanceApplyFlags(args) {
                 confirm: { type: 'string' },
                 'timeout-ms': { type: 'string' },
                 'dry-run': { type: 'boolean' },
+                'max-parallel': { type: 'string' },
             },
         }));
     }
@@ -3452,6 +3470,19 @@ function parseDatasetMaintenanceApplyFlags(args) {
             exitCode: 2,
         });
     }
+    const maxParallelValue = values['max-parallel'];
+    const maxParallel = typeof maxParallelValue === 'string' && /^\d+$/u.test(maxParallelValue)
+        ? Number.parseInt(maxParallelValue, 10)
+        : maxParallelValue === undefined
+            ? undefined
+            : Number.NaN;
+    if (maxParallel !== undefined &&
+        (!Number.isInteger(maxParallel) || maxParallel < 1 || maxParallel > 8)) {
+        throw new CliError('--max-parallel must be an integer from 1 to 8.', {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
     return {
         help: Boolean(values.help),
         json: Boolean(values.json),
@@ -3461,6 +3492,7 @@ function parseDatasetMaintenanceApplyFlags(args) {
         confirm: typeof values.confirm === 'string' ? values.confirm : '',
         timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
         dryRun: Boolean(values['dry-run']),
+        maxParallel,
     };
 }
 function parseDatasetMaintenanceFreezeProtectedFlags(args) {
@@ -5858,6 +5890,7 @@ export async function executeCli(argv, deps) {
                 commit: datasetFlags.commit,
                 allowReferenceOnlySupport: datasetFlags.allowReferenceOnlySupport,
                 executionContractPath: datasetFlags.executionContractPath,
+                maxParallel: datasetFlags.maxParallel,
                 env: deps.env,
                 fetchImpl: deps.fetchImpl,
             });
@@ -6384,11 +6417,14 @@ export async function executeCli(argv, deps) {
                     approvePlan: datasetFlags.approvePlan,
                     confirm: datasetFlags.confirm,
                     timeoutMs: datasetFlags.timeoutMs,
+                    maxParallel: datasetFlags.maxParallel,
                     env: deps.env,
                     fetchImpl: deps.fetchImpl,
                 });
                 return {
-                    exitCode: report.status === 'completed_with_failures' ? 1 : 0,
+                    exitCode: ['completed_with_failures', 'completed_with_unknowns'].includes(report.status)
+                        ? 1
+                        : 0,
                     stdout: stringifyJson(report, datasetFlags.json),
                     stderr: '',
                 };