@tiangong-lca/cli 0.1.1 → 0.1.2

package/README.md

@@ -19,21 +19,23 @@ checkPaths:
   - bin/**
   - src/cli.ts
   - src/main.ts
+  - src/batch.ts
+  - src/command-spec.ts
   - src/lib/auth-identity-receipt.ts
   - src/lib/lca-release.ts
   - scripts/run-auth-identity-production-case.ts
   - test/auth-identity*.test.ts
   - test/lca-release*.test.ts
-lastReviewedAt: 2026-08-25
-lastReviewedCommit: 47b44c65cf4bf27070fa1057e672c6ef2b2e54f3
-lastReviewedNote: 'Reviewed for Issue #230: identifies 0.1.1 as the public auth-receipt release on exact Node 24.19.0 with cryptographic Sigstore and isolated pnpm verification.'
+lastReviewedAt: 2026-08-26
+lastReviewedCommit: b9a99011fcc1d7388355e66649113ac5d4a7a9c8
+lastReviewedNote: 'Reviewed for Issue #237: identifies 0.1.2 as the release-only package identity for the bounded pnpm 11.24 public API while runtime, exports, dependencies, and release behavior stay fixed.'
 ---
 
 # TianGong LCA CLI
 
-Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Current package version: `0.1.1` Node: `24.19.0`
+Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Current package version: `0.1.2` Node: `24.19.0`
 
-Repository development is single-track on pnpm `11.23.0` and TypeScript `7.0.2`. The published package remains a clean, package-manager-neutral consumer artifact: it contains runtime files only, not pnpm, TypeScript, Oxlint, tests, source-only tooling, or repository lockfiles.
+Repository development is single-track on pnpm `11.24.0` and TypeScript `7.0.2`. The published package remains a clean, package-manager-neutral consumer artifact: it contains runtime files only, not pnpm, TypeScript, Oxlint, tests, source-only tooling, or repository lockfiles.
 
 Review note, 2026-08-25: Issue #224 migrates repository development and release automation to the sole root `pnpm-workspace.yaml` / `pnpm-lock.yaml`, TypeScript 7.0.2, and type-aware Oxlint on Node 24. The feature change deliberately keeps version 0.0.33. A separate release-only PR should prepare 0.1.0 after the toolchain change merges and its full package/coverage/release gates pass.
 
@@ -43,6 +45,14 @@ Review note, 2026-08-25: Issue #228 implements `auth identity-receipt` as a boun
 
 Review note, 2026-08-25: Issue #230 publishes the merged identity receipt as `@tiangong-lca/cli@0.1.1`. Runtime logic and published dependencies remain unchanged; the sole pnpm lock changes only for exact dev-only `sigstore@5.0.0`. Local metadata, engines, and every workflow converge on Node 24.19.0. Release automation asserts actual platform/architecture across the reusable four-platform pre-tag matrix and provides `pnpm release:verify-published` for cryptographic Fulcio/CT/Rekor provenance, registry signatures, actual tarball integrity, isolated user/global package-manager configuration, exact pnpm 11.23.0, and credential-free bin/ESM/CJS consumer proof.
 
+Review note, 2026-08-26: Issue #232 adds two supported typed library subpaths without changing version `0.1.1`: `@tiangong-lca/cli/command-spec` owns the byte-compatible `tiangong-foundry.command-spec.v1` authority and shell-free execution adapters, while `@tiangong-lca/cli/batch` owns identity/content/policy-bound scheduling, resource-aware exclusive keys, explicit mutation readback recovery, and host-safe run-directory locks. Claim-time identity drift—including a throwing identity getter—is a stable item failure/event and every already-started worker is drained before return. Any escaping infrastructure callback error records one fatal cause, immediately closes new claims, drains only already-claimed workers, and rejects after all worker promises settle. A blocked resource stays unclaimed and consumes no worker while a later free resource may run; per-resource FIFO cursors and a private minimum-ready heap keep ordinary scheduling near `O(n log k)` rather than repeatedly scanning all pending items. Run-lock PID/host/timestamp ownership is derived internally and cannot be supplied by callers. Every public timer-backed timeout, poll, or retry delay is bounded by Node's `2_147_483_647ms` maximum. The package root remains unsupported and publication requires a later release-only delivery.
+
+Review note, 2026-08-26: Issue #233 changes only the internal shape of the batch subpath. `src/batch.ts` is now a 62-line facade over bounded, acyclic modules for types, errors/contracts, locking, projection, scheduler runtime, attempts/recovery, and the engine. Executable budgets keep the facade below 400 lines and every internal module below 800 while locking exact public export identities, declarations, errors, event/result bytes, packed consumers, and dataset dogfood. Package version, dependencies, pnpm-only TypeScript 7 development, and runtime behavior are unchanged.
+
+Review note, 2026-08-26: Issue #236 changes only the repository and clean-consumer package-manager requirement from exact pnpm 11.23.0 to 11.24.0. The sole root lock requires no byte change under pnpm 11.24.0; Node 24.19.0, TypeScript 7.0.2, package version 0.1.1, public commands and exports, dependencies, tags, provenance, and publication remain unchanged, with no npm/Yarn fallback.
+
+Review note, 2026-08-26: Issue #237 releases the already reviewed bounded CommandSpec/batch runtime and pnpm 11.24 toolchain as `@tiangong-lca/cli@0.1.2`. The release changes only package metadata and four live CLI-version fixtures; runtime files, public subpaths and object identities, dependencies, the sole lock, Node 24.19.0, TypeScript 7.0.2, package-manager-neutral consumers, and automated provenance path remain unchanged.
+
 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.
@@ -94,6 +104,16 @@ pnpm build
 node ./bin/tiangong-lca.js --help
 ```
 
+## Typed library subpaths
+
+The package exposes only these supported module APIs in addition to the executable launcher subpath:
+
+- `@tiangong-lca/cli/command-spec` parses, creates, artifact-binds, and executes exact `tiangong-foundry.command-spec.v1` objects. `display` is diagnostic only; executable plus argv and binding bytes/SHA-256 form the canonical authority. Sync and async execution always use `shell:false`; async callers may inject resolver, clock, sleep, spawn, timeout, and abort adapters. `timeoutMs` must fit Node's maximum timer delay.
+- `@tiangong-lca/cli/batch` runs bounded generic work with an overall run contract and a required per-item `{ item_id, content_sha256, policy_sha256 }` contract. Every identity/content/policy/resource projection is validated before work starts and rechecked before resumed acceptance or a fresh claim. Identity changes or getter failures emit `item_identity_drift` with `BatchItemIdentityDriftError`, execute zero attempts, and do not let the batch return before other in-flight items drain. An escaping scheduler/event/stop callback records the first infrastructure error, closes further claims, awaits all worker settlements, then rejects. Input order, truthful resource-aware claim order, completion order, pause/stop behavior, awaited monotonic events, and exception isolation are explicit. Optional exclusive keys serialize only matching resources; a blocked key remains unclaimed and consumes no worker while later free keys may use the public ceiling of 64 workers. Per-resource FIFO queues expose only their head through an ordered binary min-heap, giving near `O(n log k)` ready scheduling for `k` resources.
+- Mutation batches reject automatic retry. A consumed or ambiguous mutation can continue only through an explicitly supplied readback-recovery callback; resume requires exact run and item contracts, and each resumed or rejected result participates in stop decisions before fresh claims. Retry/backoff values must be non-negative safe integers within Node's timer limit. Exclusive keys must be runtime strings. `withBatchRunLock` gives one canonical run directory one cross-process lock domain, permits reentrancy only from a still-live scope owned by the current holder, keeps the top-level promise pending until detached nested scopes drain, rejects completed-context reentry into a later owner, preserves live or foreign-host locks, and stale-recovers only a same-host dead PID. Public lock callers cannot set PID, host, or ownership time; timeout/poll values are non-negative safe integers within Node's timer limit.
+
+The packed ESM, CJS dynamic-import, and TypeScript consumers exercise both public subpaths and generated declarations. Deep imports and `import '@tiangong-lca/cli'` remain unsupported.
+
 ## Env
 
 Remote commands require:
@@ -451,7 +471,7 @@ 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`. `--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 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. Every action through the highest referenced dependency remains on the existing serial path; only the later table/id/version-unique suffix delegates claims and fatal-stop coordination to the public batch engine. `executeAction` still exclusively owns PREPARED evidence, exact before-state checks, token renewal, dispatch, durable attempts, readback, and no-replay decisions, so report bytes and input ordering do not change. 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 completes a fresh SELECT-only scan of every process visible to the owner session and rejects any inbound edge. For a separately governed all-process check, pair `--global-inbound-proof /absolute/proof.json` with `--approve-global-inbound-proof <sha256>`; the proof must be fresh, SELECT-only, complete, zero-inbound, and bound to the exact project, actor, plan, and ordered target set, and it is validated before the live scan is skipped. The CLI never runs raw SQL. 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 `--max-parallel` to retain ordinary maintenance apply behavior.
 

package/dist/src/batch.d.ts

@@ -0,0 +1,6 @@
+export { assertBatchContractMatches, assertBatchItemContractMatches, canonicalBatchJson, createBatchContract, createBatchItemContract, parseBatchContract, parseBatchItemContract, sha256BatchBytes, sha256BatchJson, } from './lib/batch/canonical-contracts.js';
+export { runBoundedBatch } from './lib/batch/engine.js';
+export { BatchContractError, BatchItemIdentityDriftError, BatchItemProjectionDriftError, BatchItemResourceDriftError, BatchItemResumeContractError, BatchMutationReplayError, BatchMutationRetryError, BatchRunLockIdentityConflictError, BatchRunLockTimeoutError, } from './lib/batch/errors.js';
+export { batchRunLockPath, batchRunLockStatePath, withBatchRunLock } from './lib/batch/run-lock.js';
+export { MAX_BATCH_CONCURRENCY } from './lib/batch/types.js';
+export type { BatchAttemptedResumeItem, BatchClock, BatchCompletedResumeItem, BatchContract, BatchEvent, BatchEventType, BatchExclusiveKeyContext, BatchExecutionContext, BatchItemContract, BatchItemFailedResult, BatchItemResult, BatchItemResultStatus, BatchItemSucceededResult, BatchItemSuccessStatus, BatchJsonObject, BatchJsonPrimitive, BatchJsonValue, BatchMode, BatchMutationRecoveryContext, BatchMutationRecoveryResult, BatchPauseContext, BatchRecoverySource, BatchResumeItem, BatchResumeState, BatchRetryContext, BatchRetryPolicy, BatchRunLockOptions, BatchRunLockReceipt, BatchRunResult, BatchSleep, BatchStatus, BatchStopContext, CreateBatchContractOptions, CreateBatchItemContractOptions, RunBoundedBatchOptions, } from './lib/batch/types.js';

package/dist/src/batch.js

@@ -0,0 +1,6 @@
+export { assertBatchContractMatches, assertBatchItemContractMatches, canonicalBatchJson, createBatchContract, createBatchItemContract, parseBatchContract, parseBatchItemContract, sha256BatchBytes, sha256BatchJson, } from './lib/batch/canonical-contracts.js';
+export { runBoundedBatch } from './lib/batch/engine.js';
+export { BatchContractError, BatchItemIdentityDriftError, BatchItemProjectionDriftError, BatchItemResourceDriftError, BatchItemResumeContractError, BatchMutationReplayError, BatchMutationRetryError, BatchRunLockIdentityConflictError, BatchRunLockTimeoutError, } from './lib/batch/errors.js';
+export { batchRunLockPath, batchRunLockStatePath, withBatchRunLock } from './lib/batch/run-lock.js';
+export { MAX_BATCH_CONCURRENCY } from './lib/batch/types.js';
+//# sourceMappingURL=batch.js.map

package/dist/src/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../src/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,8BAA8B,EAC9B,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,GAChB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACL,kBAAkB,EAClB,2BAA2B,EAC3B,6BAA6B,EAC7B,2BAA2B,EAC3B,4BAA4B,EAC5B,wBAAwB,EACxB,uBAAuB,EACvB,iCAAiC,EACjC,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACpG,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC","sourcesContent":["export {\n  assertBatchContractMatches,\n  assertBatchItemContractMatches,\n  canonicalBatchJson,\n  createBatchContract,\n  createBatchItemContract,\n  parseBatchContract,\n  parseBatchItemContract,\n  sha256BatchBytes,\n  sha256BatchJson,\n} from './lib/batch/canonical-contracts.js';\nexport { runBoundedBatch } from './lib/batch/engine.js';\nexport {\n  BatchContractError,\n  BatchItemIdentityDriftError,\n  BatchItemProjectionDriftError,\n  BatchItemResourceDriftError,\n  BatchItemResumeContractError,\n  BatchMutationReplayError,\n  BatchMutationRetryError,\n  BatchRunLockIdentityConflictError,\n  BatchRunLockTimeoutError,\n} from './lib/batch/errors.js';\nexport { batchRunLockPath, batchRunLockStatePath, withBatchRunLock } from './lib/batch/run-lock.js';\nexport { MAX_BATCH_CONCURRENCY } from './lib/batch/types.js';\nexport type {\n  BatchAttemptedResumeItem,\n  BatchClock,\n  BatchCompletedResumeItem,\n  BatchContract,\n  BatchEvent,\n  BatchEventType,\n  BatchExclusiveKeyContext,\n  BatchExecutionContext,\n  BatchItemContract,\n  BatchItemFailedResult,\n  BatchItemResult,\n  BatchItemResultStatus,\n  BatchItemSucceededResult,\n  BatchItemSuccessStatus,\n  BatchJsonObject,\n  BatchJsonPrimitive,\n  BatchJsonValue,\n  BatchMode,\n  BatchMutationRecoveryContext,\n  BatchMutationRecoveryResult,\n  BatchPauseContext,\n  BatchRecoverySource,\n  BatchResumeItem,\n  BatchResumeState,\n  BatchRetryContext,\n  BatchRetryPolicy,\n  BatchRunLockOptions,\n  BatchRunLockReceipt,\n  BatchRunResult,\n  BatchSleep,\n  BatchStatus,\n  BatchStopContext,\n  CreateBatchContractOptions,\n  CreateBatchItemContractOptions,\n  RunBoundedBatchOptions,\n} from './lib/batch/types.js';\n"]}

package/dist/src/cli.d.ts

@@ -0,0 +1,161 @@
+import type { DotEnvLoadResult } from './lib/dotenv.js';
+import type { FetchLike } from './lib/http.js';
+import { type AuthIdentityReceipt, type RunAuthIdentityReceiptOptions } from './lib/auth-identity-receipt.js';
+import { type LifecyclemodelAutoBuildReport, type RunLifecyclemodelAutoBuildOptions } from './lib/lifecyclemodel-auto-build.js';
+import { type LifecyclemodelResultingProcessReport, type RunLifecyclemodelResultingProcessOptions } from './lib/lifecyclemodel-resulting-process.js';
+import { type LifecyclemodelPublishResultingProcessReport, type RunLifecyclemodelPublishResultingProcessOptions } from './lib/lifecyclemodel-publish-resulting-process.js';
+import { type LifecyclemodelValidateBuildReport, type RunLifecyclemodelValidateBuildOptions } from './lib/lifecyclemodel-validate-build.js';
+import { type LifecyclemodelPublishBuildReport, type RunLifecyclemodelPublishBuildOptions } from './lib/lifecyclemodel-publish-build.js';
+import { type LifecyclemodelSaveDraftReport, type RunLifecyclemodelSaveDraftOptions } from './lib/lifecyclemodel-save-draft-run.js';
+import { type LifecyclemodelGraphReport, type RunLifecyclemodelGraphOptions } from './lib/lifecyclemodel-graph.js';
+import { type LifecyclemodelOrchestrateReport, type RunLifecyclemodelOrchestrateOptions } from './lib/lifecyclemodel-orchestrate.js';
+import { type ProcessAutoBuildReport, type RunProcessAutoBuildOptions } from './lib/process-auto-build.js';
+import { type ProcessGetReport, type RunProcessGetOptions } from './lib/process-get.js';
+import { type ProcessListReport, type RunProcessListOptions } from './lib/process-list.js';
+import { type ProcessBatchBuildReport, type RunProcessBatchBuildOptions } from './lib/process-batch-build.js';
+import { type ProcessScopeStatisticsReport, type RunProcessScopeStatisticsOptions } from './lib/process-scope-statistics.js';
+import { type ProcessRefreshReferencesReport, type RunProcessRefreshReferencesOptions } from './lib/process-refresh-references.js';
+import { type ProcessDedupReviewReport, type RunProcessDedupReviewOptions } from './lib/process-dedup-review.js';
+import { type ProcessResumeBuildReport, type RunProcessResumeBuildOptions } from './lib/process-resume-build.js';
+import { type ProcessPublishBuildReport, type RunProcessPublishBuildOptions } from './lib/process-publish-build.js';
+import { type ProcessSaveDraftReport, type RunProcessSaveDraftOptions } from './lib/process-save-draft-run.js';
+import { type ProcessRequiredFieldsReport, type RunProcessRequiredFieldsCompleteOptions } from './lib/process-required-fields.js';
+import { type ProcessVerifyRowsReport, type RunProcessVerifyRowsOptions } from './lib/process-verify-rows.js';
+import { type FlowBuildPlanGateReport, type ProcessBuildPlanGateReport, type RunFlowBuildPlanMaterializeOptions, type RunFlowBuildPlanValidateOptions, type RunProcessBuildPlanMaterializeOptions, type RunProcessBuildPlanValidateOptions } from './lib/process-flow-build-plan.js';
+import { type FlowIdentityPreflightReport, type ProcessIdentityPreflightReport, type RunFlowIdentityPreflightOptions, type RunProcessIdentityPreflightOptions } from './lib/identity-preflight.js';
+import { type PublishReport, type RunPublishOptions } from './lib/publish.js';
+import { type ProcessQaReport, type RunProcessQaOptions } from './lib/process-qa.js';
+import { type FlowQaReport, type RunFlowQaOptions } from './lib/flow-qa.js';
+import { type LifecyclemodelQaReport, type RunLifecyclemodelQaOptions } from './lib/lifecyclemodel-qa.js';
+import { type FlowRemediationReport, type RunFlowRemediateOptions } from './lib/flow-remediate.js';
+import { type FlowFetchRowsReport, type RunFlowFetchRowsOptions } from './lib/flow-fetch-rows.js';
+import { type FlowMaterializeDecisionsReport, type RunFlowMaterializeDecisionsOptions } from './lib/flow-materialize-decisions.js';
+import { type FlowGetReport, type RunFlowGetOptions } from './lib/flow-get.js';
+import { type FlowListReport, type RunFlowListOptions } from './lib/flow-list.js';
+import { type FlowPublishVersionReport, type RunFlowPublishVersionOptions } from './lib/flow-publish-version.js';
+import { type FlowReviewedPublishDataReport, type RunFlowReviewedPublishDataOptions } from './lib/flow-publish-reviewed-data.js';
+import { type FlowBuildAliasMapReport, type RunFlowBuildAliasMapOptions } from './lib/flow-build-alias-map.js';
+import { type FlowApplyProcessFlowRepairsReport, type FlowPlanProcessFlowRepairsReport, type FlowRegenProductReport, type FlowScanProcessFlowRefsReport, type FlowValidateProcessesReport, type RunFlowApplyProcessFlowRepairsOptions, type RunFlowPlanProcessFlowRepairsOptions, type RunFlowRegenProductOptions, type RunFlowScanProcessFlowRefsOptions, type RunFlowValidateProcessesOptions } from './lib/flow-regen-product.js';
+import { type LcaReleaseReport, type RunLcaReleaseOptions } from './lib/lca-release.js';
+import { type RunValidationOptions, type ValidationRunReport } from './lib/validation.js';
+import { type DatasetValidateReport, type RunDatasetValidateOptions } from './lib/dataset-validate.js';
+import { type DatasetCurationQueueBuildReport, type DatasetCurationQueueNextReport, type DatasetCurationQueueVerifyReport, type RunDatasetCurationQueueBuildOptions, type RunDatasetCurationQueueNextOptions, type RunDatasetCurationQueueVerifyOptions } from './lib/dataset-curation-queue.js';
+import { type DatasetReferencesRewriteReport, type RunDatasetReferencesRewriteOptions } from './lib/dataset-references-rewrite.js';
+import { type DatasetRemoteRefreshReport, type RunDatasetRemoteRefreshOptions } from './lib/dataset-remote-refresh.js';
+import { type DatasetRemoteVerificationReport, type RunDatasetRemoteVerifyOptions } from './lib/dataset-remote-verify.js';
+import { type DatasetBilingualApplyReport, type DatasetBilingualExtractReport, type DatasetBilingualValidateReport, type RunDatasetBilingualApplyOptions, type RunDatasetBilingualExtractOptions, type RunDatasetBilingualValidateOptions } from './lib/dataset-bilingual.js';
+import { type EvidenceSearchReport, type RunDatasetEvidenceSearchOptions } from './lib/dataset-evidence-search.js';
+import { type DatasetContractReport, type RunDatasetContractOptions } from './lib/dataset-contract.js';
+import { type DatasetImportLcaReport, type RunDatasetImportLcaConvertOptions } from './lib/dataset-import-lca.js';
+import { type DatasetAuthorReport, type RunDatasetAuthorOptions } from './lib/dataset-author.js';
+import { type DatasetPatchApplyReport, type RunDatasetPatchApplyOptions } from './lib/dataset-patch.js';
+import { type DatasetSaveDraftReport, type RunDatasetSaveDraftOptions } from './lib/dataset-save-draft-run.js';
+import { type DatasetClassificationApplyReport, type DatasetClassificationAuditReport, type DatasetClassificationChildrenReport, type DatasetClassificationPathReport, type RunDatasetClassificationApplyOptions, type RunDatasetClassificationAuditOptions, type RunDatasetClassificationChildrenOptions, type RunDatasetClassificationPathOptions } from './lib/dataset-classification.js';
+import { type DatasetMaintenanceClearAccountReport, type RunDatasetMaintenanceClearAccountOptions } from './lib/dataset-maintenance-clear-account.js';
+import { runDatasetMaintenancePlan } from './lib/dataset-maintenance-plan.js';
+import { runDatasetMaintenanceApply } from './lib/dataset-maintenance-apply.js';
+import { freezeDatasetMaintenanceProtected } from './lib/dataset-maintenance-protected-freeze.js';
+import { runDatasetMaintenanceProtected } from './lib/dataset-maintenance-protected-run.js';
+import { sealDatasetMaintenanceProtectedApproval } from './lib/dataset-maintenance-protected-seal.js';
+import { runDatasetMaintenanceVerify } from './lib/dataset-maintenance-verify.js';
+import { runFlowIdentityPlanFromFiles } from './lib/dataset-maintenance-flow-identity-command.js';
+import { captureFlowIdentity } from './lib/dataset-maintenance-flow-identity-capture.js';
+import { freezeFlowIdentity } from './lib/dataset-maintenance-flow-identity-freeze.js';
+import { sealFlowIdentityApproval } from './lib/dataset-maintenance-flow-identity-seal.js';
+import { freezeFlowIdentityRecovery, sealFlowIdentityRecoveryApproval } from './lib/dataset-maintenance-flow-identity-recovery.js';
+import { runFlowIdentity } from './lib/dataset-maintenance-flow-identity-run.js';
+import { verifyFlowIdentity } from './lib/dataset-maintenance-flow-identity-verify.js';
+import { type DatasetSourceUploadAttachmentsReport, type RunDatasetSourceUploadAttachmentsOptions } from './lib/dataset-source-upload-attachments.js';
+export type CliDeps = {
+    env: NodeJS.ProcessEnv;
+    dotEnvStatus: DotEnvLoadResult;
+    fetchImpl: FetchLike;
+    runAuthIdentityReceiptImpl?: (options: RunAuthIdentityReceiptOptions) => Promise<AuthIdentityReceipt>;
+    runPublishImpl?: (options: RunPublishOptions) => Promise<PublishReport>;
+    runValidationImpl?: (options: RunValidationOptions) => Promise<ValidationRunReport>;
+    runLcaReleaseImpl?: (options: RunLcaReleaseOptions) => Promise<LcaReleaseReport>;
+    runLifecyclemodelAutoBuildImpl?: (options: RunLifecyclemodelAutoBuildOptions) => Promise<LifecyclemodelAutoBuildReport>;
+    runLifecyclemodelBuildResultingProcessImpl?: (options: RunLifecyclemodelResultingProcessOptions) => Promise<LifecyclemodelResultingProcessReport>;
+    runLifecyclemodelPublishResultingProcessImpl?: (options: RunLifecyclemodelPublishResultingProcessOptions) => Promise<LifecyclemodelPublishResultingProcessReport>;
+    runLifecyclemodelValidateBuildImpl?: (options: RunLifecyclemodelValidateBuildOptions) => Promise<LifecyclemodelValidateBuildReport>;
+    runLifecyclemodelPublishBuildImpl?: (options: RunLifecyclemodelPublishBuildOptions) => Promise<LifecyclemodelPublishBuildReport>;
+    runLifecyclemodelSaveDraftImpl?: (options: RunLifecyclemodelSaveDraftOptions) => Promise<LifecyclemodelSaveDraftReport>;
+    runLifecyclemodelGraphImpl?: (options: RunLifecyclemodelGraphOptions) => Promise<LifecyclemodelGraphReport>;
+    runLifecyclemodelOrchestrateImpl?: (options: RunLifecyclemodelOrchestrateOptions) => Promise<LifecyclemodelOrchestrateReport>;
+    runProcessGetImpl?: (options: RunProcessGetOptions) => Promise<ProcessGetReport>;
+    runProcessListImpl?: (options: RunProcessListOptions) => Promise<ProcessListReport>;
+    runProcessAutoBuildImpl?: (options: RunProcessAutoBuildOptions) => Promise<ProcessAutoBuildReport>;
+    runProcessBatchBuildImpl?: (options: RunProcessBatchBuildOptions) => Promise<ProcessBatchBuildReport>;
+    runProcessScopeStatisticsImpl?: (options: RunProcessScopeStatisticsOptions) => Promise<ProcessScopeStatisticsReport>;
+    runProcessRefreshReferencesImpl?: (options: RunProcessRefreshReferencesOptions) => Promise<ProcessRefreshReferencesReport>;
+    runProcessDedupReviewImpl?: (options: RunProcessDedupReviewOptions) => Promise<ProcessDedupReviewReport>;
+    runProcessResumeBuildImpl?: (options: RunProcessResumeBuildOptions) => Promise<ProcessResumeBuildReport>;
+    runProcessPublishBuildImpl?: (options: RunProcessPublishBuildOptions) => Promise<ProcessPublishBuildReport>;
+    runProcessSaveDraftImpl?: (options: RunProcessSaveDraftOptions) => Promise<ProcessSaveDraftReport>;
+    runProcessRequiredFieldsCompleteImpl?: (options: RunProcessRequiredFieldsCompleteOptions) => Promise<ProcessRequiredFieldsReport>;
+    runProcessVerifyRowsImpl?: (options: RunProcessVerifyRowsOptions) => Promise<ProcessVerifyRowsReport>;
+    runProcessIdentityPreflightImpl?: (options: RunProcessIdentityPreflightOptions) => Promise<ProcessIdentityPreflightReport>;
+    runProcessBuildPlanValidateImpl?: (options: RunProcessBuildPlanValidateOptions) => Promise<ProcessBuildPlanGateReport>;
+    runProcessBuildPlanMaterializeImpl?: (options: RunProcessBuildPlanMaterializeOptions) => Promise<ProcessBuildPlanGateReport>;
+    runProcessQaImpl?: (options: RunProcessQaOptions) => Promise<ProcessQaReport>;
+    runFlowQaImpl?: (options: RunFlowQaOptions) => Promise<FlowQaReport>;
+    runLifecyclemodelQaImpl?: (options: RunLifecyclemodelQaOptions) => Promise<LifecyclemodelQaReport>;
+    runFlowRemediateImpl?: (options: RunFlowRemediateOptions) => Promise<FlowRemediationReport>;
+    runFlowFetchRowsImpl?: (options: RunFlowFetchRowsOptions) => Promise<FlowFetchRowsReport>;
+    runFlowMaterializeDecisionsImpl?: (options: RunFlowMaterializeDecisionsOptions) => Promise<FlowMaterializeDecisionsReport>;
+    runFlowGetImpl?: (options: RunFlowGetOptions) => Promise<FlowGetReport>;
+    runFlowListImpl?: (options: RunFlowListOptions) => Promise<FlowListReport>;
+    runFlowPublishVersionImpl?: (options: RunFlowPublishVersionOptions) => Promise<FlowPublishVersionReport>;
+    runFlowReviewedPublishDataImpl?: (options: RunFlowReviewedPublishDataOptions) => Promise<FlowReviewedPublishDataReport>;
+    runFlowBuildAliasMapImpl?: (options: RunFlowBuildAliasMapOptions) => Promise<FlowBuildAliasMapReport>;
+    runFlowScanProcessFlowRefsImpl?: (options: RunFlowScanProcessFlowRefsOptions) => Promise<FlowScanProcessFlowRefsReport>;
+    runFlowPlanProcessFlowRepairsImpl?: (options: RunFlowPlanProcessFlowRepairsOptions) => Promise<FlowPlanProcessFlowRepairsReport>;
+    runFlowApplyProcessFlowRepairsImpl?: (options: RunFlowApplyProcessFlowRepairsOptions) => Promise<FlowApplyProcessFlowRepairsReport>;
+    runFlowRegenProductImpl?: (options: RunFlowRegenProductOptions) => Promise<FlowRegenProductReport>;
+    runFlowValidateProcessesImpl?: (options: RunFlowValidateProcessesOptions) => Promise<FlowValidateProcessesReport>;
+    runFlowIdentityPreflightImpl?: (options: RunFlowIdentityPreflightOptions) => Promise<FlowIdentityPreflightReport>;
+    runFlowBuildPlanValidateImpl?: (options: RunFlowBuildPlanValidateOptions) => Promise<FlowBuildPlanGateReport>;
+    runFlowBuildPlanMaterializeImpl?: (options: RunFlowBuildPlanMaterializeOptions) => Promise<FlowBuildPlanGateReport>;
+    runDatasetValidateImpl?: (options: RunDatasetValidateOptions) => Promise<DatasetValidateReport>;
+    runDatasetCurationQueueBuildImpl?: (options: RunDatasetCurationQueueBuildOptions) => Promise<DatasetCurationQueueBuildReport>;
+    runDatasetCurationQueueNextImpl?: (options: RunDatasetCurationQueueNextOptions) => Promise<DatasetCurationQueueNextReport>;
+    runDatasetCurationQueueVerifyImpl?: (options: RunDatasetCurationQueueVerifyOptions) => Promise<DatasetCurationQueueVerifyReport>;
+    runDatasetReferencesRewriteImpl?: (options: RunDatasetReferencesRewriteOptions) => Promise<DatasetReferencesRewriteReport>;
+    runDatasetRemoteRefreshImpl?: (options: RunDatasetRemoteRefreshOptions) => Promise<DatasetRemoteRefreshReport>;
+    runDatasetRemoteVerifyImpl?: (options: RunDatasetRemoteVerifyOptions) => Promise<DatasetRemoteVerificationReport>;
+    runDatasetBilingualExtractImpl?: (options: RunDatasetBilingualExtractOptions) => Promise<DatasetBilingualExtractReport>;
+    runDatasetBilingualApplyImpl?: (options: RunDatasetBilingualApplyOptions) => Promise<DatasetBilingualApplyReport>;
+    runDatasetBilingualValidateImpl?: (options: RunDatasetBilingualValidateOptions) => Promise<DatasetBilingualValidateReport>;
+    runDatasetEvidenceSearchImpl?: (options: RunDatasetEvidenceSearchOptions) => Promise<EvidenceSearchReport>;
+    runDatasetContractImpl?: (options: RunDatasetContractOptions) => Promise<DatasetContractReport>;
+    runDatasetImportLcaConvertImpl?: (options: RunDatasetImportLcaConvertOptions) => Promise<DatasetImportLcaReport> | DatasetImportLcaReport;
+    runDatasetAuthorImpl?: (options: RunDatasetAuthorOptions) => Promise<DatasetAuthorReport>;
+    runDatasetPatchApplyImpl?: (options: RunDatasetPatchApplyOptions) => Promise<DatasetPatchApplyReport>;
+    runDatasetSaveDraftImpl?: (options: RunDatasetSaveDraftOptions) => Promise<DatasetSaveDraftReport>;
+    runDatasetClassificationChildrenImpl?: (options: RunDatasetClassificationChildrenOptions) => Promise<DatasetClassificationChildrenReport>;
+    runDatasetClassificationPathImpl?: (options: RunDatasetClassificationPathOptions) => Promise<DatasetClassificationPathReport>;
+    runDatasetClassificationAuditImpl?: (options: RunDatasetClassificationAuditOptions) => Promise<DatasetClassificationAuditReport>;
+    runDatasetClassificationApplyImpl?: (options: RunDatasetClassificationApplyOptions) => Promise<DatasetClassificationApplyReport>;
+    runDatasetMaintenanceClearAccountImpl?: (options: RunDatasetMaintenanceClearAccountOptions) => Promise<DatasetMaintenanceClearAccountReport>;
+    runDatasetMaintenancePlanImpl?: typeof runDatasetMaintenancePlan;
+    runDatasetMaintenanceApplyImpl?: typeof runDatasetMaintenanceApply;
+    freezeDatasetMaintenanceProtectedImpl?: typeof freezeDatasetMaintenanceProtected;
+    runDatasetMaintenanceProtectedImpl?: typeof runDatasetMaintenanceProtected;
+    sealDatasetMaintenanceProtectedApprovalImpl?: typeof sealDatasetMaintenanceProtectedApproval;
+    runDatasetMaintenanceVerifyImpl?: typeof runDatasetMaintenanceVerify;
+    runFlowIdentityPlanFromFilesImpl?: typeof runFlowIdentityPlanFromFiles;
+    captureFlowIdentityImpl?: typeof captureFlowIdentity;
+    freezeFlowIdentityImpl?: typeof freezeFlowIdentity;
+    sealFlowIdentityApprovalImpl?: typeof sealFlowIdentityApproval;
+    freezeFlowIdentityRecoveryImpl?: typeof freezeFlowIdentityRecovery;
+    sealFlowIdentityRecoveryApprovalImpl?: typeof sealFlowIdentityRecoveryApproval;
+    runFlowIdentityImpl?: typeof runFlowIdentity;
+    verifyFlowIdentityImpl?: typeof verifyFlowIdentity;
+    runDatasetSourceUploadAttachmentsImpl?: (options: RunDatasetSourceUploadAttachmentsOptions) => Promise<DatasetSourceUploadAttachmentsReport>;
+};
+export type CliResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function executeCli(argv: string[], deps: CliDeps): Promise<CliResult>;

package/dist/src/command-spec.d.ts

@@ -0,0 +1,90 @@
+export declare const FOUNDRY_COMMAND_SPEC_SCHEMA: 'tiangong-foundry.command-spec.v1';
+export type FoundryArtifactFact = {
+    role: string;
+    path: string;
+    bytes: number;
+    sha256: string;
+};
+export type FoundryCommandSpecBinding = {
+    artifacts: FoundryArtifactFact[];
+};
+export type FoundryCommandSpec = {
+    schema: typeof FOUNDRY_COMMAND_SPEC_SCHEMA;
+    executable: string;
+    argv: string[];
+    display: string;
+    binding: FoundryCommandSpecBinding;
+    sha256: string;
+};
+export type CreateFoundryCommandSpecOptions = {
+    executable: string;
+    argv: readonly string[];
+    binding?: FoundryCommandSpecBinding;
+};
+export type CreateFileArtifactFactOptions = {
+    role: string;
+    path: string;
+    filePath: string;
+};
+export type FoundryCommandSpecEnvironment = Record<string, string | undefined>;
+export type FoundryCommandSpecSpawnOptions = {
+    cwd?: string;
+    env?: FoundryCommandSpecEnvironment;
+    encoding: 'utf8';
+    maxBuffer?: number;
+    shell: false;
+    windowsHide: true;
+};
+export type FoundryCommandSpecAsyncSpawnOptions = FoundryCommandSpecSpawnOptions & {
+    signal: AbortSignal;
+};
+export type FoundryCommandSpecSpawnResult = {
+    pid?: number;
+    output?: unknown[];
+    stdout: string;
+    stderr: string;
+    status: number | null;
+    signal: string | null;
+    error?: Error;
+};
+export type ExecuteFoundryCommandSpecSyncOptions = {
+    resolveArtifactPath: (artifactPath: string) => string | null;
+    cwd?: string;
+    env?: FoundryCommandSpecEnvironment;
+    maxBuffer?: number;
+    spawnImpl?: (executable: string, argv: readonly string[], options: FoundryCommandSpecSpawnOptions) => FoundryCommandSpecSpawnResult;
+};
+export type FoundryCommandSpecClock = {
+    now: () => number;
+};
+export type FoundryCommandSpecSleep = (milliseconds: number, signal: AbortSignal) => Promise<void>;
+export type ExecuteFoundryCommandSpecOptions = {
+    resolveArtifactPath: (artifactPath: string) => string | null;
+    cwd?: string;
+    env?: FoundryCommandSpecEnvironment;
+    maxBuffer?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    clock?: FoundryCommandSpecClock;
+    sleep?: FoundryCommandSpecSleep;
+    spawnImpl?: (executable: string, argv: readonly string[], options: FoundryCommandSpecAsyncSpawnOptions) => Promise<FoundryCommandSpecSpawnResult>;
+};
+export declare class FoundryCommandSpecTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly startedAtMs: number;
+    readonly deadlineMs: number;
+    constructor(timeoutMs: number, startedAtMs: number);
+}
+export declare class FoundryCommandSpecAbortError extends Error {
+    readonly reason: unknown;
+    constructor(reason: unknown);
+}
+export declare function renderFoundryCommandDisplay(executable: string, argv: readonly string[]): string;
+export declare function parseFoundryCommandSpec(value: unknown): FoundryCommandSpec;
+export declare function createFoundryCommandSpec(options: CreateFoundryCommandSpecOptions): FoundryCommandSpec;
+export declare function createFileArtifactFact(options: CreateFileArtifactFactOptions): FoundryArtifactFact;
+export declare function commandSpecOptionValue(value: unknown, optionName: string): string | null;
+export declare function assertFoundryCommandSpecArtifactsCurrent(value: unknown, resolveArtifactPath: (artifactPath: string) => string | null): FoundryCommandSpec;
+export declare function assertFoundryCommandSpecBindsArtifact(value: unknown, requiredArtifact: FoundryArtifactFact): FoundryCommandSpec;
+export declare function executeFoundryCommandSpecSync(value: unknown, options: ExecuteFoundryCommandSpecSyncOptions): FoundryCommandSpecSpawnResult;
+export declare function executeFoundryCommandSpec(value: unknown, options: ExecuteFoundryCommandSpecOptions): Promise<FoundryCommandSpecSpawnResult>;