Development
View Markdown

Managed runtime resource production

The candidate producer supplies the fixed resources consumed by managed installation. It produces a complete Server interpreter/package tree and a separate Ops bundle. Users of those artifacts need no system Python, uv, Git, or compiler. This is the resource-production part of #2112; Desktop assembly and public distribution remain separate.

Every output is an unqualified candidate. The scripts cannot promote a build by accepting a qualification flag. Successful builds and CI smoke results do not establish signing, notarization, clean-machine operation, or native Task Scheduler/LaunchAgent lifecycle acceptance. They do not publish artifacts or infer a production download URL.

Fixed inputs and supported build hosts

Build natively on Windows x86_64, macOS arm64, or macOS x86_64. Linux is not a prerequisite and cross-compilation is not supported. The build host needs Git, curl, uv 0.13.5, and the locked resource-build dependency group. This bootstrap group imports the Ops resource/model contracts without Server transports, cryptography, jieba, or maturin. Installing the full server/ops extras first would attempt an ambient Intel cryptography source build before the pinned builder. Build-host tools are not copied from that environment into either resource.

scripts/managed_resource_interpreters.json pins CPython 3.12.16, Astral python-build-standalone tag 20261026, and the exact install-only archive URL/SHA-256 for each target:

TargetUpstream artifact suffixSHA-256
windows-x86_64x86_64-pc-windows-msvc-install_only.tar.gz590dfcbe3a34c07301e6332e13e2188b98655cd072b08afa45a7998dc4c22bc5
macos-arm64aarch64-apple-darwin-install_only.tar.gzfbf4afef53c2a6b72bb741bc06d5671a9dfaf87bd84e5aa73ac9b3d0d589f14e
macos-x86_64x86_64-apple-darwin-install_only.tar.gza962e47df522889eaa7ff0d6a56203f1079f68aabb65ffdbe8455f362bc769f3

These are the upstream 20261026 release artifacts, using its documented install tree. The producer preserves in-tree interpreter and dependency notices and emits resource-licenses.json in both trees. That index binds retained notices and wheel license metadata to the actual package hashes; it is not legal clearance.

The preparation script takes an exact 40-character Git source commit and an explicit canonical package version. It builds from git archive, so uncommitted files, editable installs, and the developer environment cannot enter the project wheel. The supplied version is embedded with setuptools-scm's explicit version override and verified from the resulting wheel and installed metadata. The source commit, archive, uv.lock, pyproject.toml, project wheel, interpreter, build-tool closure, and all downloaded/built wheel identities are recorded in inputs.json. The executing producer's Git revision and script digests are recorded separately from the packaged Server source. matches_committed_files=false identifies a working-tree producer; it must not be described as a committed release builder.

Runtime dependencies are exported from that source's locked ops and cli extras (ops includes server). Preparation selects compatible wheels using the pinned interpreter's actual tags and environment markers, then verifies the original uv.lock sizes and hashes. Only jieba==0.42.1 may use a locked sdist: it has no upstream wheel. Its source hash is checked before building with the exact hash-pinned tools in scripts/managed_resource_build_tools.json, without build isolation or backend dependency downloads. The project wheel is the other explicit source build. On Intel macOS, the exact locked cryptography==50.0.0 is an additional source-build exception described below. Other source-only dependencies fail clearly instead of enabling an implicit build. The resulting target wheel closure is frozen as exact versions and individual wheel hashes in requirements.lock.

Preparation may access the network. Final resource production uses only that verified wheelhouse, offline mode, binary-only installation, and --require-hashes. Source builds are not claimed to be reproducible across arbitrary toolchain/host changes: retain their actual wheel bytes and hashes. Repeated production from the same frozen inputs must produce identical archives and manifests.

Intel cryptography source build

Upstream cryptography removed x86_64 macOS support in 49.0.0. The producer preserves the source lock's 50.0.0, rather than downgrading to an older wheel. Its separate build_intel_managed_wheel.py path builds the exact hashed sdist with these fixed native inputs:

InputFixed identity
Rust1.95.0, x86_64-apple-darwin distribution SHA-256 998af750fe2c28f0dbf193edc496c9a7407850486968f40ac11a8c8adfb7cfa6
OpenSSL4.0.3 source SHA-256 325b5c806167c13b40b1ffeadfe0248197c00eccc4cf123ec1e28d2d2fd216d9
Backendmaturin==1.14.1, pinned Intel wheel; existing pinned setuptools plus native locked cffi/pycparser wheels
Compiler/SDKXcode 16.4 build 16F6, macOS SDK 15.5, deployment target 10.13

All download URLs and hashes are in scripts/managed_resource_intel_build.json. Rust is installed only into a disposable build directory. OpenSSL is built statically there; no Homebrew library is shipped or referenced. Every external Cargo crate must have a crates.io checksum in the source's fixed Cargo.lock; cargo vendor --locked verifies acquisition, then the build uses vendored dependencies and offline Cargo. Backend installation is hash-locked, offline, and binary-only. Its bare maturin command resolves to the exact binary from the verified wheel in the task-local build environment. Inherited target-prefixed OpenSSL settings and Python/backend/compiler overrides cannot redirect the pinned inputs. The finished wheel retains OpenSSL and vendored Rust license notices. otool rejects non-system dynamic dependencies and runtime search paths. Installed candidate probes perform AES-GCM roundtrip and Ed25519 signing/verification on all targets. The source/tool/SDK identities and linkage results enter inputs.json before its digest is frozen.

Intel build hosts must have that Xcode installed and select it for this process with DEVELOPER_DIR=/Applications/Xcode_16.4.app/Contents/Developer; CI sets this variable without changing global Xcode selection. This native build is a candidate for a platform upstream no longer supports. Compilation and smoke checks do not restore upstream support or establish production maintenance/security qualification. The Intel CI leg must actually pass; it is not skipped when a wheel is unavailable. No bit-for-bit source-build claim is made across different compiler/SDK identities.

Produce a candidate

Use the current committed producer checkout, then choose the exact package-source commit and version. This executable macOS arm64 recipe freezes the current commit and assigns an explicit candidate version:

uv sync --locked --no-dev --group resource-build --python 3.12 --no-build-package cryptography --no-build-package jieba
package_source_sha="$(git rev-parse HEAD)"
uv run --no-sync python scripts/prepare_managed_resources.py \
  --target macos-arm64 \
  --source-ref "$package_source_sha" \
  --server-version "0.0.0+candidate.$package_source_sha" \
  --output build/resource-inputs \
  --download-cache build/resource-downloads

The supplied source commit must exist in this checkout and contain a compatible uv.lock and package build contract. Use macos-x86_64 on Intel macOS. The equivalent Windows PowerShell preparation is:

uv sync --locked --no-dev --group resource-build --python 3.12 --no-build-package cryptography --no-build-package jieba
$packageSourceSha = (git rev-parse HEAD).Trim()
uv run --no-sync python scripts/prepare_managed_resources.py --target windows-x86_64 --source-ref $packageSourceSha --server-version "0.0.0+candidate.$packageSourceSha" --output build/resource-inputs --download-cache build/resource-downloads

--runtime-archive can select an already downloaded interpreter archive; the same fixed hash is still mandatory. The optional task-local download cache is digest-addressed, and every cache hit is rehashed. An existing corrupt or incomplete input must be inspected before retrying; it is never silently adopted.

Retain the exact inputs_sha256 printed by preparation, then pass it to the offline producer:

uv run --no-sync python scripts/produce_managed_resources.py \
  --inputs build/resource-inputs \
  --inputs-sha256 <printed-inputs-sha256> \
  --server-url https://candidate.invalid/server.tar.gz \
  --output build/resource-candidate
uv run --no-sync python scripts/ci_managed_resource_smoke.py \
  --candidate build/resource-candidate --serve --evidence-dir build/resource-evidence

candidate.invalid is a reserved test origin, not a usable download location. Supply an operator-controlled fixed HTTPS candidate URL when testing real HTTP delivery; the producer neither uploads to it nor discovers one. The smoke tool seeds the integrity-checked local cache with the exact archive, then uses real ResourceCatalog and ResourceStore readback. It does not claim that an HTTP download occurred.

If smoke fails, bounded fixture stdout/stderr and an exception-class summary are saved under the explicit evidence directory before temporary cleanup. Each log is limited to its last 64 KiB; raw exception/child stdout is not printed inline. Without --evidence-dir, the durable default is the candidate's sibling <candidate-name>-evidence directory.

Input and output directories must not contain one another. Existing outputs are never overwritten. Keep a failed or partial build for inspection and retry at a fresh path. Keep large input/output/cache directories out of source control.

Output and launch contract

OutputPurpose
server/server.tar.gzDeterministic, link-free Server tree, including its own Python and complete installed wheel closure.
server/catalog.json, server/catalog.sha256Exact ResourceCatalog/ResourceSpec bytes and their digest. Each file has path, size, SHA-256, and executable mode.
server/resource.jsonComplete source/input provenance plus the produced resource specification.
ops/Independent runtime/, packages/, entry.py, and compatible bundle.json, built through build_ops_bundle.py.
ops.tar.gz, ops-resource.jsonDeterministic Ops archive and complete file size/hash/executable inventory, including bundle.json.
ops-provision.jsonDesktop distribution input pinning exact ops/bundle.json and server/catalog.json digests, with binding_mode=managed_catalog.
candidate.jsonUnqualified status, source/package/output bindings, producer identities, and actual Windows path measurements when run on Windows.

The qualification reference starts with unqualified-candidate:sha256: and binds the frozen source/package inputs and actual outputs. It provides no evidence of platform qualification. A checksum beside an untrusted artifact is not a trust anchor. Desktop's packager must pin the descriptor in its trusted distribution and provision the independent helper at the protected per-user PowerContext/Ops/bundle location, outside both the Desktop and managed Server trees. Its catalog is packaged at resource_dir/server/catalog.json. Merely generating this directory does not install Desktop or provision a helper.

The Server runs the exact bundled interpreter with -I -B -m powercontext.service.launcher. Windows catalogs select pythonw.exe and also inventory the paired python.exe; Ops uses the console interpreter. Ops retains the existing -I -S -B entry.py launch contract and manifest format. Installer-generated console wrappers are removed because their absolute build-path shebangs/launchers do not relocate. Mutable uv installer-cache records containing build-input timestamps are also removed; distribution RECORD rows are repaired accordingly. Modules, native libraries, wheel data, and license notices remain. Human CLI use can invoke the bundled callback with <bundled-python> -I -B -c 'from powercontext.cli.app import main; main()' --help.

Interpreter archive links are never extracted as links. Safe relative aliases resolving to an internal regular file are materialized as independent regular files and recorded in provenance. Directory aliases, external/absolute links, cycles, special files, ambiguous paths, and reparse points are rejected. Gzip/tar metadata, ordering, timestamps, permissions, and ownership are normalized; bytecode generation is disabled while probing sealed output trees.

Windows production checks the actual current user's managed final directory, staging/resource-<32 hex> directory, and independent Ops final directory against ordinary Win32 UTF-16 file/directory limits. It also invokes the consumer's actual destination validator for Server paths. No system-wide long-path setting is enabled. Results on a short build path do not qualify a different user profile; unsupported destination paths remain rejected by the consumer.

CI and evidence boundary

.github/workflows/managed-resource-candidates.yml performs real native production on windows-2025, macos-15 (arm64), and macos-15-intel. Each matrix leg acquires pinned inputs from its exact commit, builds twice, compares archive/manifest bytes after relocating the same hashed inputs, rejects mutation/version mismatches, consumes the real catalog/archive, and runs isolated installed Server imports plus the exact service launcher against disposable SQLite data. The independent Ops smoke starts with poisoned Python variables, audits module origins, and inspects a missing Server runtime with native service-manager read-only commands. It never registers a service. Successful jobs retain explicitly unqualified candidates. Bounded diagnostics, input identities and test evidence are retained on failure; partial runtimes and download caches are not uploaded as failure diagnostics. A failed job is not a qualified resource.

Run focused local checks with:

uv run --no-sync pytest -q tests/test_managed_resource_producer.py tests/test_ops_resources.py

Without explicitly prepared native inputs, the expensive native producer tests skip. To enable the same native path, set POWERCONTEXT_RESOURCE_TEST_INPUTS to the prepared directory and POWERCONTEXT_RESOURCE_TEST_INPUTS_SHA256 to its trusted inputs.json digest before running that command. POWERCONTEXT_RESOURCE_TEST_OUTPUT optionally selects the first retained candidate directory; it must not exist. Synthetic Windows archive/path tests verify rejection and layout logic, not actual Windows execution.

Formal assembly/publication must still validate Windows signatures, macOS signing and notarization, clean standard-user Windows 11/macOS operation without developer tools, login/reboot/service lifecycle, and preservation through repair and removal. Signing can change interpreter/native-library bytes. Perform actual signing before freezing the hashes in any qualified file inventory, archive, catalog, bundle manifest, or provision descriptor; regenerate and reverify the complete identity chain afterward. Candidate digests must never be reused as proof of different signed artifacts.

On this page