@tiangong-lca/cli 0.1.9 → 0.1.11

package/README.md

@@ -31,14 +31,18 @@ checkPaths:
   - test/auth-identity*.test.ts
   - test/public-auth-identity-receipt.test.ts
   - test/lca-release*.test.ts
-lastReviewedAt: 2026-09-04
-lastReviewedCommit: b15c074b1f10314e4835fd64cb7079c8aa9fec3d
-lastReviewedNote: 'Reviewed for CLI #272: release-only 0.1.9 after support export #270; runtime, dependencies, lock bytes, public exports and publication mechanics are unchanged.'
+lastReviewedAt: 2026-09-07
+lastReviewedCommit: f766d9192419eafd1313062b4f692797ad1304bb
+lastReviewedNote: 'Reviewed for CLI #280: release-only 0.1.11 publishes managed-host interface #278 from main f766d91. Runtime, dependencies, lock, bootstrap scripts and workflows stay unchanged; release qualification retains exact coverage, native consumers, provenance and integration gates.'
 ---
 
+CLI 0.1.10 is the designated C1 release for `tiangong-lca runtime describe --json` and the explicit `@tiangong-lca/cli/runtime` API for package, asset and Node content inspection. Runtime inspection loads no project `.env`, performs no authentication and downloads nothing. See [the runtime distribution contract](docs/agents/runtime-distribution-contract.md) for exact fields and trust boundaries; verify public availability and provenance before treating the candidate version as released.
+
+Issue #278 adds a managed Node host interface in source, for the subsequent qualified CLI release. A release manifest opts its launch into `tiangong-lca.runtime-host.v1`; the host calls `receiveRuntimeHostContext()` from `@tiangong-lca/cli/runtime` before application work. The immutable result carries the selected full manifest, work/cache directories, entry and actual host. `copyTrustedRuntimeManifestBytes(context.manifest)` supplies original verified bytes for another package instance's compatibility checks. The channel closes before the receiver returns, and ordinary task arguments or environment values cannot supply this context. See the runtime distribution contract for lifecycle and trust requirements.
+
 # TianGong LCA CLI
 
-Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Current package version: `0.1.8` Node: `24.19.0`
+Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Current package version: `0.1.10` Node: `24.19.0`
 
 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.
 
@@ -131,6 +135,7 @@ node ./bin/tiangong-lca.js --help
 
 The package exposes only these supported module APIs in addition to the executable launcher subpath:
 
+- `@tiangong-lca/cli/runtime` (introduced by #274 and designated for C1 0.1.10) describes CLI package, asset and Node content and compares them against independently trusted exact expectations. It also exposes strict manifest loading, ensure/status/prune and manifest-declared execution with component locks, complete file verification and leases. These operations do not authenticate by themselves or attest a complete public production component. The no-Node bootstrap sources are checked in under `scripts/bootstrap/` and consume only an adjacent product-generated lock; C1 package verification belongs to #275; public product component qualification remains downstream.
 - `@tiangong-lca/cli/auth-identity-receipt` parses the exact safe receipt projection offline and exports its schema, Node-safe timeout ceiling, and receipt types. It does not expose session resolution, network execution, or test internals; callers that need a fresh receipt still invoke the CLI command.
 - `@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.
@@ -541,7 +546,7 @@ For `dataset validate`, `--type auto` supports mixed support scopes containing c
 
 For `dataset curation-queue build/next/verify`, the CLI owns entity-level Foundry import queue state. `build` writes `outputs/curation-queue-manifest.json`, `outputs/curation-queue-tasks.jsonl`, `outputs/curation-queue-locks.json`, `outputs/curation-queue-blockers.jsonl`, and per-entity `input.jsonl`, `closure.json`, and `entity-run-plan.json`. `next` returns one runnable support/flow/process task based on checkpoint state. `verify` passes only when scoped checkpoints are complete and build blockers are absent. AI authoring must return structured patches or build plans, and remote writes remain gated by deterministic apply, schema/QA, prewrite verify, and readback.
 
-For `dataset import-lca convert`, the CLI delegates all format detection, conversion, validation, bounded spooling, cancellation, and atomic publication to unified Rust `tidas import`; it does not reproduce import logic in TypeScript. Binary selection is `--tidas-bin`, then `TIDAS_BIN`, then `tidas` on PATH. Optional `--tidas-config` maps to native `--config`. Every run first requires a successful `tidas version --format json --progress never` handshake with `tidas.operation-report.v1` and a stable `0.2.x` binary version, then validates the native `tidas.import-execution-report.v1` summary and exact exit-class/code mapping. Native controls include explicit or automatic source format, target, mapping output, process-bundle disablement, warning failure, maximum entry size, memory budget, and queue capacity. The supported release matrix is Linux x86_64/ARM64, macOS Intel/Apple Silicon, and Windows x86_64; Windows ARM64 is unsupported. The npm package includes `assets/import-smoke/simapro.csv` for clean-machine proof but does not bundle a platform binary or require Python.
+For `dataset import-lca convert`, the CLI delegates all format detection, conversion, validation, bounded spooling, cancellation, and atomic publication to unified Rust `tidas import`; it does not reproduce import logic in TypeScript. Binary selection is `--tidas-bin`, then `TIDAS_BIN`, then `tidas` on PATH. Optional `--tidas-config` maps to native `--config`. Every run first requires a successful `tidas version --format json --progress never` handshake with `tidas.operation-report.v1` and a stable `0.2.x` binary version, then validates the native `tidas.import-execution-report.v1` summary and exact exit-class/code mapping. Native controls include explicit or automatic source format, target, mapping output, process-bundle disablement, warning failure, maximum entry size, memory budget, and queue capacity. The supported release matrix is Linux x86_64/ARM64, macOS Apple Silicon (arm64), and Windows x86_64; Windows ARM64 is unsupported. The npm package includes `assets/import-smoke/simapro.csv` for clean-machine proof but does not bundle a platform binary or require Python.
 
 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.
 

package/assets/runtime/cli-runtime-descriptor.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:tiangong-lca:cli-runtime-descriptor:v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "scope",
+    "package",
+    "platform",
+    "node",
+    "command",
+    "assets",
+    "files",
+    "content_sha256"
+  ],
+  "properties": {
+    "schema": {
+      "const": "tiangong-lca.cli-runtime-descriptor.v1"
+    },
+    "scope": {
+      "const": "cli-package"
+    },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "root", "manifest_sha256"],
+      "properties": {
+        "name": {
+          "const": "@tiangong-lca/cli"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$"
+        },
+        "root": {
+          "type": "string",
+          "minLength": 1
+        },
+        "manifest_sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        }
+      }
+    },
+    "platform": {
+      "enum": ["darwin-arm64", "linux-x64", "linux-arm64", "win32-x64"]
+    },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "executable", "bytes", "sha256"],
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^24\\.(?:19|[2-9][0-9]|[1-9][0-9]{2,})\\.(?:0|[1-9][0-9]*)$"
+        },
+        "executable": {
+          "type": "string",
+          "minLength": 1
+        },
+        "bytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 536870912
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        }
+      }
+    },
+    "command": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["executable", "argv"],
+      "properties": {
+        "executable": {
+          "type": "string",
+          "minLength": 1
+        },
+        "argv": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "assets": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tidas_schema_root", "sha256"],
+      "properties": {
+        "tidas_schema_root": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        }
+      }
+    },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50000,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "bytes", "sha256"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "bytes": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 536870912
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          }
+        }
+      }
+    },
+    "content_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    }
+  }
+}

package/assets/runtime/cli-runtime-expectation.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:tiangong-lca:cli-runtime-expectation:v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "package_version",
+    "platform",
+    "content_sha256",
+    "node_version",
+    "node_sha256"
+  ],
+  "properties": {
+    "schema": {
+      "const": "tiangong-lca.cli-runtime-expectation.v1"
+    },
+    "package_version": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$"
+    },
+    "platform": {
+      "enum": ["darwin-arm64", "linux-x64", "linux-arm64", "win32-x64"]
+    },
+    "content_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "node_version": {
+      "type": "string",
+      "pattern": "^24\\.(?:19|[2-9][0-9]|[1-9][0-9]{2,})\\.(?:0|[1-9][0-9]*)$"
+    },
+    "node_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    }
+  }
+}

package/assets/runtime/runtime-bootstrap-lock.schema.json

@@ -0,0 +1,254 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:tiangong-lca:runtime-bootstrap-lock:v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "bootstrap_protocol",
+    "posix_script_sha256",
+    "powershell_script_sha256",
+    "manifest_url",
+    "manifest_bytes",
+    "manifest_sha256",
+    "app_entry",
+    "darwin_arm64_component_key",
+    "darwin_arm64_archive_url",
+    "darwin_arm64_archive_bytes",
+    "darwin_arm64_archive_sha256",
+    "darwin_arm64_integrity_path",
+    "darwin_arm64_integrity_sha256",
+    "darwin_arm64_file_count",
+    "darwin_arm64_node_path",
+    "darwin_arm64_cli_path",
+    "linux_x64_component_key",
+    "linux_x64_archive_url",
+    "linux_x64_archive_bytes",
+    "linux_x64_archive_sha256",
+    "linux_x64_integrity_path",
+    "linux_x64_integrity_sha256",
+    "linux_x64_file_count",
+    "linux_x64_node_path",
+    "linux_x64_cli_path",
+    "linux_arm64_component_key",
+    "linux_arm64_archive_url",
+    "linux_arm64_archive_bytes",
+    "linux_arm64_archive_sha256",
+    "linux_arm64_integrity_path",
+    "linux_arm64_integrity_sha256",
+    "linux_arm64_file_count",
+    "linux_arm64_node_path",
+    "linux_arm64_cli_path",
+    "win32_x64_component_key",
+    "win32_x64_archive_url",
+    "win32_x64_archive_bytes",
+    "win32_x64_archive_sha256",
+    "win32_x64_integrity_path",
+    "win32_x64_integrity_sha256",
+    "win32_x64_file_count",
+    "win32_x64_node_path",
+    "win32_x64_cli_path"
+  ],
+  "properties": {
+    "schema": {
+      "const": "tiangong-lca.runtime-bootstrap-lock.v1"
+    },
+    "bootstrap_protocol": {
+      "const": "tiangong-lca.runtime-bootstrap.v1"
+    },
+    "posix_script_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "powershell_script_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "manifest_url": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://"
+    },
+    "manifest_bytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 33554432
+    },
+    "manifest_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "app_entry": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]{0,63}$"
+    },
+    "darwin_arm64_component_key": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "darwin_arm64_archive_url": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://"
+    },
+    "darwin_arm64_archive_bytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 536870912
+    },
+    "darwin_arm64_archive_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "darwin_arm64_integrity_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "darwin_arm64_integrity_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "darwin_arm64_file_count": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 50000
+    },
+    "darwin_arm64_node_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "darwin_arm64_cli_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "linux_x64_component_key": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "linux_x64_archive_url": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://"
+    },
+    "linux_x64_archive_bytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 536870912
+    },
+    "linux_x64_archive_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "linux_x64_integrity_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "linux_x64_integrity_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "linux_x64_file_count": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 50000
+    },
+    "linux_x64_node_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "linux_x64_cli_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "linux_arm64_component_key": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "linux_arm64_archive_url": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://"
+    },
+    "linux_arm64_archive_bytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 536870912
+    },
+    "linux_arm64_archive_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "linux_arm64_integrity_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "linux_arm64_integrity_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "linux_arm64_file_count": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 50000
+    },
+    "linux_arm64_node_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "linux_arm64_cli_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "win32_x64_component_key": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "win32_x64_archive_url": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://"
+    },
+    "win32_x64_archive_bytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 536870912
+    },
+    "win32_x64_archive_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "win32_x64_integrity_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "win32_x64_integrity_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "win32_x64_file_count": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 50000
+    },
+    "win32_x64_node_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    },
+    "win32_x64_cli_path": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 255
+    }
+  }
+}

package/assets/runtime/runtime-command-result.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:tiangong-lca:runtime-command-result:v1",
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "manifest_sha256", "platform", "status", "components"],
+      "properties": {
+        "schema": {
+          "const": "tiangong-lca.runtime-status.v1"
+        },
+        "manifest_sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "platform": {
+          "enum": ["darwin-arm64", "linux-x64", "linux-arm64", "win32-x64"]
+        },
+        "status": {
+          "enum": ["ready", "missing", "blocked"]
+        },
+        "components": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "version", "key", "status", "root", "reason"],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "version": {
+                "type": "string"
+              },
+              "key": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$"
+              },
+              "status": {
+                "enum": ["ready", "missing", "unverified", "corrupt"]
+              },
+              "root": {
+                "type": "string"
+              },
+              "reason": {
+                "type": ["string", "null"]
+              }
+            }
+          },
+          "maxItems": 128
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "removed", "retained"],
+      "properties": {
+        "schema": {
+          "const": "tiangong-lca.runtime-prune.v1"
+        },
+        "removed": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "maxItems": 128
+        },
+        "retained": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "maxItems": 128
+        }
+      }
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schema", "released"],
+      "properties": {
+        "schema": {
+          "const": "tiangong-lca.runtime-lease-release.v1"
+        },
+        "released": {
+          "type": "boolean"
+        }
+      }
+    }
+  ]
+}