@tiangong-lca/cli 0.0.32 → 0.0.33

package/README.md

@@ -45,6 +45,8 @@ Review note, 2026-07-23: `dataset save-draft --execution-contract` adds an opt-i
 
 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:
@@ -374,6 +376,7 @@ tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id
 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
@@ -404,6 +407,8 @@ For `process save-draft`, canonical process payloads are validated locally with
 
 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.
 
 For `process publish-build`, canonical process payloads are validated locally with `ProcessSchema` before publish handoff artifacts are written. The gate report is `reports/process-publish-schema-gate.json`.

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
 
@@ -3459,6 +3460,7 @@ function parseDatasetMaintenanceApplyFlags(args) {
                 confirm: { type: 'string' },
                 'timeout-ms': { type: 'string' },
                 'dry-run': { type: 'boolean' },
+                'max-parallel': { type: 'string' },
             },
         }));
     }
@@ -3468,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),
@@ -3477,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) {
@@ -6401,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: '',
                 };