@tiangong-lca/cli 0.0.28 → 0.0.30

package/README.md

@@ -17,8 +17,10 @@ checkPaths:
   - bin/**
   - src/cli.ts
   - src/main.ts
-lastReviewedAt: 2026-07-15
-lastReviewedCommit: bd145f692b3fd11e398302dd6a1d2831e058883a
+  - src/lib/lca-release.ts
+  - test/lca-release*.test.ts
+lastReviewedAt: 2026-07-23
+lastReviewedCommit: 5c90ddd60328748ab6d8d89717e59dcaeca8cde7
 ---
 
 # TianGong LCA CLI
@@ -35,6 +37,12 @@ Review note, 2026-07-15: `dataset maintenance run-protected` adds a production-o
 
 Review note, 2026-07-15: `dataset maintenance freeze-protected` and `seal-protected-approval` close the preparation gap without adding a second execution path. Freeze preparation authenticates directly to the explicitly confirmed production project, performs only complete account/support reads plus the 50 derivative snapshot RPCs, and writes an unapproved canonical request. Approval sealing is entirely local and requires the exact human-returned UTF-8 bytes plus explicit freeze/request/text hashes and account confirmation. Only the later `run-protected` command can preflight or admit work.
 
+Review note, 2026-07-16: `release ...` is the LCI/LCIA data-release command family, not the npm package release workflow. It uses the normal user-session bootstrap, requires the server to authorize `data_product_manager` for private and mutating operations, never accepts a service-role key, and keeps large Calculation Bundle or ZIP payloads in hash-verified files instead of stdout.
+
+Review note, 2026-07-17: `dataset maintenance flow-identity capture|plan|freeze|seal-approval|run|freeze-recovery|seal-recovery-approval|run-recovery|verify` is the dedicated Step 3 workflow for approved BAFU elementary-flow identity mappings. Capture performs one complete authenticated census and one database-attestation POST; plan rejects historical authorities and binds the exact 305-source request to its immutable receipt. The write path uses a database-minted one-wrapper permit that rotates after each successful process/finalize write and is never stored in proof artifacts; a create-only local approval claim is defense in depth. A lost permit or preflight response cannot be replayed: the operator must freeze and approve an exact recovery baseline, while status/recovery may locate only the same actor-owned scope through the exact read-only lookup. Terminal verification independently proves unchanged source/public/support rows, exact desired owner-draft processes, zero approved-source residue, unchanged pending/blocker/orphan closure, and causal derivative completion. Failed/stale derivatives still require a separate derivative-only plan, freeze, and approval and never replay the process mutation. Production use remains gated on merge, Preview validation, and coordinated database/CLI release.
+
+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.
+
 ## Run
 
 One-off published run:
@@ -87,6 +95,83 @@ TIANGONG_LCA_DISABLE_SESSION_CACHE=false
 TIANGONG_LCA_FORCE_REAUTH=false
 ```
 
+## LCI/LCIA Data Release
+
+The `release` command family is the authenticated transport used by the standalone release control plane. It does not introduce a TIDAS schema variant: result packages reuse the existing Process exchange structure for LCI and the existing Process LCIA result fields, with a LifecycleModel referencing the resulting Process.
+
+The canonical publication set contains four self-contained ZIPs:
+
+- Unit Process full closure in TIDAS and ILCD.
+- Standalone LifecycleModel + Result full closure in TIDAS and ILCD. This package repeats the required canonical Unit Process and support closure, so it has no dependency on another ZIP.
+
+Workflow:
+
+```bash
+tiangong-lca release prepare --input ./release-prepare.json --json
+tiangong-lca release upload --input ./release-upload.json --output ./upload-receipt.json
+tiangong-lca release finalize --input ./release-finalize.json --json
+tiangong-lca release approve --input ./release-approval.json --json
+tiangong-lca release publish --input ./release-publish.json --json
+tiangong-lca release readback-verify --input ./release-readback.json --json
+tiangong-lca release status --release-run-id <release-run-id> --json
+```
+
+`release-upload.json` contains the immutable plan identity plus exactly one artifact for each profile/format pair. Paths are resolved relative to the request file:
+
+```json
+{
+  "releaseRunId": "11111111-1111-4111-8111-111111111111",
+  "publishPlanHash": "<64 lowercase hex characters>",
+  "artifacts": [
+    {
+      "profileId": "unit-process-full-closure.v1",
+      "format": "tidas",
+      "path": "./packages/unit-process.tidas.zip",
+      "sha256": "<64 lowercase hex characters>",
+      "byteSize": 1234,
+      "mediaType": "application/zip"
+    },
+    {
+      "profileId": "unit-process-full-closure.v1",
+      "format": "ilcd",
+      "path": "./packages/unit-process.ilcd.zip",
+      "sha256": "<64 lowercase hex characters>",
+      "byteSize": 1234,
+      "mediaType": "application/zip"
+    },
+    {
+      "profileId": "standalone-lifecyclemodel-result-full-closure.v1",
+      "format": "tidas",
+      "path": "./packages/result.tidas.zip",
+      "sha256": "<64 lowercase hex characters>",
+      "byteSize": 1234,
+      "mediaType": "application/zip"
+    },
+    {
+      "profileId": "standalone-lifecyclemodel-result-full-closure.v1",
+      "format": "ilcd",
+      "path": "./packages/result.ilcd.zip",
+      "sha256": "<64 lowercase hex characters>",
+      "byteSize": 1234,
+      "mediaType": "application/zip"
+    }
+  ]
+}
+```
+
+The CLI verifies every local upload against its declared byte size, SHA-256, media type, and required pair before requesting signed URLs. Upload receipts and downloads are written atomically with private file permissions. Existing outputs are preserved unless `--force` is explicit. The publish credential fingerprint is derived locally from `TIANGONG_LCA_API_KEY`; callers cannot inject it through the request file.
+
+Calculation results and published artifacts remain file-first:
+
+```bash
+tiangong-lca release calculation-bundle --package-id <package-id> --output ./calculation-bundle.json
+tiangong-lca release calculation-artifact --package-id <package-id> --artifact-path chunks/lci-00000.jsonl.gz --output ./lci-00000.jsonl.gz
+tiangong-lca release current --json
+tiangong-lca release artifact-download --artifact-id <artifact-id> --output ./release.zip
+```
+
+`calculation-bundle` writes a verified manifest projection with short-lived URLs for its declared artifacts. Artifact downloads are accepted only when their exact path is present in that manifest, and downloaded bytes must match the durable size and SHA-256 before the output is exposed. Use `--dry-run` to validate inputs and inspect a credential-masked request without network writes.
+
 Optional LLM review env, only for `qa process --enable-llm` or `qa flow --enable-llm`:
 
 ```bash
@@ -280,6 +365,7 @@ 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 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
@@ -314,6 +400,8 @@ 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 `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`.