Build and release SOP

Mandatory use: Follow this SOP before changing dependencies, lockfiles, build launchers, generated-manifest formats, machine bundles, signing, packaging mechanics, continuous integration, or release automation. Routine application development that only consumes the existing tools follows development-lifecycle.md and does not become release work.

Required outcome

An Arcane build must be reproducible from a fresh checkout, use only approved public dependency sources, preserve canonical inputs on every supported operating system, stop at the first failed command, keep local verification distinct from signed production publication, and avoid multiplying invariant work across apps, models, assets, targets, or platforms.

Current development profile

ARCANE currently has no staging or production environment. Normal development uses focused checks and npm run check; internal app demonstrations use npm run demo:check -- <app-id> or an explicitly unsigned/development-signed native command.

• Do not require full package regeneration or a clean full-platform build for every feature edit.
• Do not call development or demo output a release candidate.
• Keep production generation dormant. A production artifact may be generated only after an explicit production request and a preflight that proves an authorized trusted signing identity; otherwise stop before producing build output.
• Apply the complete clean-build, publication, signing, and evidence requirements below when changing the build/release mechanism itself or explicitly preparing promotion evidence.

Procedure

1. Preserve and identify the build boundary

• Record the exact command, platform, Node/npm versions, signing mode, and first error.
• Preserve the relevant npm or build log before clearing caches or dependencies.
• Identify whether the failure occurs during dependency installation, source generation, compilation, signing, packaging, publication, or final verification.
• Follow docs/debugging.md for any failing or unexpected build.
• Resolve repairable checkout prerequisites centrally before dependency installation, signer initialization, compilation, or packaging. This includes the Microsoft NT path budget, upgraded-checkout migration, required tool availability, and exact Git LFS asset hydration.
• Do not let a lower-level compiler or app packager become the first component to discover a repairable prerequisite. Every interactive Microsoft NT first-run or missing-build path must converge on the repository-root developer setup; if setup cannot repair a prerequisite, it fails at preflight and preserves the exact error in the setup log.
• Treat a Microsoft NT WebView2 virtual-host change as a persistent browser-origin boundary, not a URL-only edit. The current transition to https://os.arcane intentionally does not migrate https://arcane.local storage: preserve the legacy profile untouched, validate the new origin as a separate scope without clearing existing target-origin state, and do not claim an in-place data-preserving upgrade. Record migration as deferred in the handoff. Any future migration must satisfy the acceptance criteria in application-data-isolation.md before the changed host is distributed as a storage-preserving upgrade.

2. Complete the work-amplification review

Before implementing or materially changing any setup, build, package, test, model, app, or runtime path, including model acquisition, app installation, runtime initialization, and release:

1. State every cardinality and loop multiplier, including platforms, architectures, applications, models, assets, targets, test cases, retries, and nested products of those sets.
2. Enumerate expensive operations: network downloads, archive extraction, dependency installation, compilation/linking, hashing and integrity scans, signing, package generation, model pulls, service setup, and tests. Estimate the representative cold-path invocation count, bytes transferred or processed, and elapsed time.
3. Classify each operation as invariant, identity-bound per item, or batchable. Hoist invariant work and execute it once at the narrowest correct shared boundary. Batch compatible work to avoid repeated process startup, traversal, and validation costs.
4. Reuse or cache output only when a verified key cryptographically and semantically binds every relevant source hash, toolchain, platform, architecture, configuration, policy, signing identity, and destination identity. A stale, ambiguous, or partially bound cache is invalid; never trade integrity or isolation for speed.
5. Enforce one check per trust fact per artifact state. If the bytes, policy, identity, location, and toolchain are unchanged, reuse immutable hash-bound evidence and do not rerun the same validation. If final assembly changes only placement or inventory, verify that changed boundary only; carry forward the already-bound payload evidence.
6. Classify the expected value before calling a digest check security. A hash authenticates payload bytes only when the expected digest is independently authenticated and outside the authority that can replace the payload—for example through a trusted publisher signature, signed host-embedded binding, or authenticated retained-handle receipt. An adjacent or self-generated manifest, catalog, checksum sidecar, recovery record, same-origin checksum, or digest returned by the same publication authority is consistency evidence only. It may detect corruption or transfer/transaction drift, but it must not authorize execution, activation, restoration, publisher identity, privilege, capability, or a verified/trusted claim.
7. Measure a representative clean cold path and compare actual operation counts, bytes, and elapsed time with the estimate. Add focused count, cache-key, evidence-reuse, or work-graph regressions when the multiplier could silently return.
8. Eliminate redundant scans and operations before improving progress display. For necessary long work, stream the phase, current item, completed/total count or bytes, elapsed time, throughput when meaningful, and an honest ETA when calculable. Do not make users infer activity from network or Task Manager behavior.

OS-owned artifacts are built, downloaded, extracted, hashed, signed, and smoke-tested once per compatible OS build or installation, never once per application. Shared hosts and runtimes, PipeGuard and other security tools, WebView/media/speech tooling, model services, dependency trees, signing preflights, and OS integrity scans remain outside application loops. Applications publish their own prebuilt, independently versioned output; OS setup performs only generic admission, installation, and runtime registration. Models are selected once from explicit hardware and product policy, and are pulled once per unique content identity rather than once per consuming app.

Document every intentionally repeated expensive operation or check with proof that its underlying artifact state changed or that independent verification is explicitly mandated. Record the exact changing item-specific input or identity, the mandate when applicable, why batching or safe reuse is impossible, the multiplier, and its measured cost. Generic "defense in depth" is not a reason to recheck identical bytes, policy, identity, location, or toolchain. Existing loop placement is not a justification.

Verification receipt lifecycle

Every expensive integrity, signature, publisher, package, catalog, or installed-tree decision has one verification owner for one exact artifact state. The owner retains the verified file and directory handles or an equally strong immutability boundary and issues an immutable receipt binding canonical location and filesystem identity, content and inventory hashes, policy, toolchain, platform and architecture, signing identity and trust result, and a receipt generation. Status, catalog, install, update, activation, rollback, launch, and packaging consumers authenticate and reuse that receipt; generic defense in depth never justifies rechecking unchanged state.

The receipt must identify the authenticity anchor separately from informational digests. It may carry a same-authority hash for cache or transfer consistency, but that field cannot elevate the receipt's trust result. Never issue a trusted receipt by hashing the current artifact and writing the resulting expectation beside it. Legacy migration and recovery may preserve unknown bytes, but they must remain explicitly unverified until an independent anchor admits them.

Invalidate the receipt before any bound byte, identity, location, policy, toolchain, signer, inventory, or transaction generation can change. Stop new consumers, drain or cancel active consumers, close retained handles only at the documented mutation boundary, perform the write, rename, activation, repair, rollback, or replacement, and verify the resulting state into a new generation. A path, timestamp, size, time-to-live, or process-local cache key alone is not artifact-state identity.

Cross-process reuse on Microsoft NT requires a shared Arcane host, broker, or service that retains verified handles, authenticates pipe peers through kernel process identity, and binds each delegation to the consumer process and receipt generation. Environment variables, command-line claims, unauthenticated pipes, and an administrator-protected receipt file alone are insufficient authority. The UI or CLI acknowledges before receipt acquisition or cache-miss verification, while the owner emits progress, heartbeat, and surfaced failure.

3. Preserve the responsiveness invariant

Every setup, build, package, test, model, app-install, and runtime front end must acknowledge immediately before starting potentially blocking work. A graphical launcher creates or activates its visible status surface first. A command-line interface (CLI) prints a start record, current phase, and durable log location when available before its first network, disk, hash, compiler, child-process, model, or integrity wait.

• Keep network, disk, hashing, compilation, child-process, model, and integrity work off the UI-creation and foreground thread. Use event-driven background workers or genuine asynchronous I/O. async/await is allowed for genuinely asynchronous operations, but marking a wrapper async and awaiting synchronous blocking code is not compliant.
• Bound parallel downloads, workers, compilers, child processes, hashing streams, queue depth, memory, and disk pressure. Apply backpressure instead of unbounded fan-out.
• Emit progress events with phase, item, count or bytes, and elapsed time. Emit heartbeat events during necessary opaque waits, and coalesce high-frequency updates without making activity disappear.
• Support cancellation and safe retry or resume when integrity and transaction semantics permit it. Cleanly preserve or discard partial output according to a documented policy.
• Give every task an owner that awaits, joins, or supervises completion. Surface every failure through visible status, a durable log, and nonzero CLI or launcher result. Unobserved fire-and-forget work is prohibited.
• Serialize only a true signing, trust, atomic-install, shared-state, or external-protocol boundary. Show visible status before entering it, keep it narrow, and document why parallel or asynchronous execution would violate the boundary.

Focused launcher and work-graph tests must prove acknowledgement order, foreground responsiveness during a slow representative operation, concurrency limits and backpressure, progress or heartbeat delivery, safe cancellation state, retry/resume identity, worker-error propagation, and the exact serialized boundary.

4. Keep dependency resolution public and reproducible

• For every setup, build, package, test, or verification path that prepares JavaScript dependencies, create a fresh npm-managed dependency tree rather than copying or reusing an installed directory. Commit every required lockfile and use npm ci when that lockfile exists; use npm install only when intentionally creating or updating dependency resolution. Do not substitute an unlocked install in verification or continuous integration.
• While the approved public registry is reachable, never copy node_modules or another installed dependency directory as an installation shortcut. When internet access is unavailable, first attempt a fresh npm ci --offline from a verified npm cache. Only if the offline cache cannot satisfy the current lock may a process copy an existing dependency tree as an explicit last-resort offline fallback, and only after binding it to the exact current lockfile, platform, architecture, Node/npm toolchain, and a filesystem-safe inventory. Surface and label the build as non-fresh/offline; do not silently use this fallback for registry rejection, authentication, integrity, lockfile, lifecycle-script, permission, disk, or other installation failures. This dependency-acquisition rule does not prohibit copying explicitly allowlisted runtime dependencies into a package or materializing an immutable verified toolchain tree for isolated staging after acquisition.
• Every HTTP(S) resolved dependency in a committed npm lockfile must use an explicitly approved public registry. The current approved host is registry.npmjs.org over HTTPS.
• Never commit workstation, proxy, mirror, credentialed, private, OpenAI-internal, or organization-internal registry URLs.
• Run npm run verify:package-locks before installing dependencies and after regenerating any lockfile.
• Regenerate a contaminated lockfile against an approved registry, preserve integrity hashes, and verify it from an empty dependency directory and fresh npm cache.
• Do not commit npm caches, node_modules, credentials, tokens, certificates, or private registry configuration.

5. Preserve canonical files across platforms

• Any source file whose exact bytes are hashed, signed, embedded, or compared canonically must have an explicit .gitattributes rule.
• Machine-bundle arcane-bundle.json files must remain LF-only through machine_bundles/*/arcane-bundle.json text eol=lf.
• Microsoft NT batch launchers remain CRLF; shell scripts remain LF.
• Treat installed third-party dependencies as opaque integrity-checked content. Do not rewrite them or apply dependency-specific repository format and source-byte checks; validate their behavior through deployment and quality-assurance functionality testing. Generic release integrity still covers every distributed file.
• Verify canonical content from a Microsoft NT checkout with core.autocrlf=true, not only from the Git blob or a Unix checkout.

6. Keep application releases application-owned

• During rapid development, do not regenerate every checked-in public package merely because shared source changed. Generate only a selected demo package when required.
• Before releasing an application, run that application's complete owned behavior suite and map its application files, shared-runtime dependencies, publication policies, adapters, and reviewed document sources to that selected package.
• Regenerate the selected checked-in package with npm run app:package -- <app-id>. Do not use --all or run unrelated application suites as part of an Arcane OS release.
• Do not edit generated catalog, release, content, or inventory manifests by hand. Commit the packager-generated dist/<app-id> output, including updated manifests and published source snapshots, in the same change as its inputs.
• Review the source and generated diffs together. Confirm that changed manifest versions, byte counts, hashes, and inventories correspond only to intended source changes and that no private or unapproved material entered the package.
• Run npm run app:check -- <app-id> for the regenerated package before its app release. app:release packages and verifies bytes but does not replace the application's owned behavior suite. The development pre-push hook intentionally runs only npm run check:dev.
• An Arcane OS build consumes only the app-published dist/<app-id>/ARCANE_APP_RELEASE.json contract and the exact files in that inventory. It may validate identity, declared capabilities, entry point, exact inventory, byte sizes, hashes, safe file topology, and catalog admission because those are OS distribution boundaries.
• An app whose native registry entry sets ownership: "external" publishes from its own canonical repository. That repository must use the Arcane SDK version supported by the current importer to create one deterministic .arcane-app.tar.gz; the app owns source checks, adapter execution, licensing, behavior evidence, and the numeric Git tag/release title. Arcane executes no app-owned source, workflow, adapter, or test while admitting the result.
• Authenticate the exact bundle digest independently before parsing it. For GitHub authority, require the Arcane-pinned repository and immutable IDs, source commit/ref, signer repository/workflow/commit, GitHub Actions OIDC issuer, GitHub-hosted runner, and detached proof bundle. If private-repository attestations are unavailable, use the separately governed Ed25519 authorization projection and protect its signing key outside both repositories. For either authority kind, query the locked GitHub repository/release IDs and require the exact numeric tag/title and artifact/proof asset identities before parsing. A checksum, release manifest, adjacent proof claim, publisher-supplied digest, or GitHub release record is consistency evidence, not cryptographic authority.
• Review and edit machine_bundles/arcane-os-machine-bundle/arcane-external-apps.lock.json deliberately; never regenerate it from a release. Run npm run app:external:inspect -- <app-id> --artifact <bundle> --proof <proof>, then the corresponding app:external:admit command for the same locked bytes. Admission stages and hashes each input once, authenticates and verifies the GitHub release identity before decompression, streams one bounded exact archive into a private release stage, and atomically replaces only dist/<app-id> after all descriptor, permission, method, Core-requirement, target, security, release, inventory, and encoding bindings pass. A later OS build revalidates those compatibility fields and any locked public-document count from the installed release.
• Keep the Arcane source mirror until the admitted release passes a source-free browser check and every supported native-target check. Remove only that app's mirror in a later reviewable change; do not use a duplicate clone, worktree, or archive as an active fallback. A new artifact, proof, key, signer, workflow, repository identity, commit, version, policy, permission, security grant, or installed-tree mutation invalidates the corresponding receipt and requires a new reviewed lock entry and admission.
• For local AI, that release manifest carries the app's sole authored localAIModelPolicy and exact app-owned Modelfiles as native admission inputs. dist/<app-id>/ARCANE_APP_RELEASE.json physically retains the generated policy; any public browser inventory and the native renderer payload exclude that record, and browser runtime/manifests/catalogs/generic metadata APIs must not consume or project its policy. The native packager must require policy/capability parity and an exact Modelfile set and inject the declaration only into the compiled app-scoped Core descriptor. A directly hosted release root needs a verified server/CDN exclusion before anyone claims the release record is not fetchable. Platform Arcane definitions come only from arcane/models/ and project only to native app/shared/; the admitted catalog returned by Core is a runtime result, not a browser projection of the declaration.
• Arcane OS must never import or execute an app adapter, generator, source verifier, or content/business-behavior suite, and it must not substitute apps/<app-id> source for the app-published payload. Missing, stale, or invalid published output fails immediately at generic OS admission and returns ownership to that app's release process.
• Arcane OS setup must not compile application executables or rebuild app-owned packages. If an app needs an app-specific native host, the app's own release produces and tests that prebuilt host; the OS verifies and installs it through the generic admission contract.
• An Arcane OS release runs only npm run release:check:arcane-os. Each application runs its own complete suite only for that application's explicit release. A passing development or OS gate does not prove that an application's behavior is ready for its own release.

7. Fail closed at every build step

• A launcher must stop after every nonzero subprocess exit code, including negative Microsoft NT process-status values.
• Do not use a positive-only if errorlevel 1 check where a tool can return a negative status. Compare the captured status explicitly against zero.
• Never continue from a failed dependency install into compilation, signing, packaging, or publication.
• Do not suppress, overwrite, or reinterpret a failing exit code merely to complete a build.

8. Keep verification and publication modes separate

• Unsigned output is allowed only through the explicit unsigned-local-test command and must remain labeled and verified as such.
• Development-signed builds use the documented per-developer certificate bootstrap.
• Production builds must fail closed unless the required production signing identity and publisher continuity checks are present.
• Never weaken production signing requirements to make local verification pass.
• Production is not a default build flavor or a fallback. Without both an explicit production request and a successful trusted-signer preflight, produce no production tree, archive, installer, or release manifest.

The Microsoft NT production wrapper supports two explicit signer providers. certificate-store requires the independently configured signing and expected-publisher thumbprints to identify the same private-key-backed certificate. artifact-signing requires the x64 Microsoft Artifact Signing DLib, credential-free metadata outside the repository, an authorized Azure principal, a live Public Trust probe, the Microsoft Public Trust and durable subscriber-identity EKUs, and the active derived leaf thumbprint. Tokens and private-key material are never Arcane inputs. Every distributed executable, including retained local tools, must share the exact active signer and RFC 3161 timestamp before final inventories are written.

Artifact Signing's durable subscriber EKU and its short-lived leaf serve different purposes. The current runtime still pins the exact leaf; do not claim transparent publisher continuity across cloud certificate renewal. Exercise the protected predecessor-rotation policy with two actually different issued leaves before promotion.

The deployable ZIP workflow is a transport boundary, not a replacement for executable signing. It accepts only an already-current production tree, enumerates every physical executable, creates canonical inventory and SHA-256 sidecars, extracts the archive, and verifies the changed archive, placement, and extracted-inventory boundary. When the extracted executable bytes, policy, identity, and toolchain match the immutable signed evidence, reuse that evidence instead of rerunning Authenticode checks. The signed Provisioner inside the extracted complete tree is the installer entry point; never add an unsigned launcher or local-test override.

9. Verify promotion output from a clean state

For dependency, cross-platform build-mechanism, or an explicit Arcane OS release, verify in this order:

1. node tools/verify-package-lock-registries.mjs
2. npm ci from an empty node_modules directory and fresh npm cache
3. the focused source or launcher contract check
4. the explicit unsigned-local platform build when production credentials are unavailable
5. final manifest, content-binding, executable-binding, and distribution verification
6. npm run release:check:arcane-os from a fresh checkout for an Arcane OS release

For the current Microsoft NT machine bundle, use:

npm ci --prefix machine_bundles/arcane-os-machine-bundle
npm run build:distribution:windows:unsigned-local-test --prefix machine_bundles/arcane-os-machine-bundle

Use the signed production command only with authorized production signing material.

Versioning the machine bundle

The active source directory is permanently machine_bundles/arcane-os-machine-bundle. Its name must never contain a release number, and advancing the bundle version must never create, copy, or select a version-suffixed source directory. arcane-bundle.json is the authoritative runtime version; package metadata, generated runtime declarations, and platform manifests must agree with it. Versioned names belong only to generated artifacts such as archives, installers, and evidence tied to an exact build.

Git is the release history; the current tree is not an archive. Advance the canonical manifests, validation record, documentation, and generated outputs in place, and remove superseded copies in the same change. Do not retain prior version directories, old validation documents, rollback copies, or obsolete archives merely for historical reference. Exact historical bytes may remain only for a documented current runtime, test, legal, or active audit dependency. A changelog entry and Git history are the default record of replaced release state.

Every explicit Arcane OS or app release includes a cleanup review. Run npm run cleanup:preview, review ignored build/cache output, remove only exact obsolete paths, and prove that no current consumer references tracked material being deleted. A tracked generated or dependency path that setup can rewrite requires normal-pull regressions from every supported checkout. If a dormant checkout can skip an intermediate change and conflict with a later deletion, retain the smallest documented compatibility shim instead; a release-number advance does not prove migration uptake. Optional Git-metadata cleanup must preserve every object ID and staged entry and must never block pull, setup, validation, or build. Users must never need to stash, reset, or manually merge generated output to receive routine cleanup. Then run npm run maintenance:gc for safe local Git object maintenance. Never automate git clean -fdx, aggressive object pruning, history rewriting, or remote LFS deletion as part of setup, routine checks, or a release build; those operations can destroy user work or shared recovery state and require separate explicit authorization.

Microsoft NT developer preflight never retires an existing canonical dist/nt release. It classifies bounded current or historical publication metadata under the publication lock and preserves the prior working tree until a newly built stage has passed its own exact verification and the transactional replacement boundary commits. Unsupported, newer, production-signed, malformed, external, installed, reparse, active, or transaction-owned state fails closed without deleting the prior target.

Application versions are independent of the machine-bundle version. An in-repository app derives its version from apps/<id>/arcane-package.json; a source-free external app derives it from the independently authorized normalized descriptor in arcane-external-apps.lock.json, and its admitted ARCANE_APP_RELEASE.json must agree. arcane-apps.json remains a version-free native admission and capability registry. Build tools preserve both bundleVersion and app.version; a bundle-version change must never implicitly bump or relabel an application.

Prepare an upgraded checkout before strict verification

The supported source-migration command is npm run machine:checkout:prepare from the repository root, or npm run prepare:checkout from the permanent machine-bundle directory. It considers only retired version-suffixed machine-bundle siblings whose suffix is a canonical three-component version. Similar backup names and every directory outside that exact pattern are left alone.

Preparation is Git-backed and fail-closed. The repository root, machine_bundles, canonical source directory, candidate directories, and every descendant must resolve as real in-tree entries. Before removing anything, the migration verifies every candidate and refuses the entire operation when it finds a tracked path, nonignored untracked work, a symbolic link, junction, reparse point, special entry, or an ignored file outside the recognized generated directories. Only empty directories and ignored residue inside known build/cache directories are disposable. A refusal preserves the legacy directories for the developer to inspect, move, commit, or remove manually.

setup-developer.bat, npm run setup:developer, and npm run check:dev run this preparation centrally before dependency work or the strict machine-bundle invariant. The direct Microsoft NT build-windows.bat launcher runs it before npm ci, development-signer initialization, or compilation. This migration never selects a source by folder version: the canonical source directory remains machine_bundles/arcane-os-machine-bundle, and arcane-bundle.json remains the sole machine-version authority.

Until every generated-tree operation is long-path-safe, the resolved Microsoft NT checkout root must be at most 46 UTF-16 code units. The current exact all-build ceiling is 47; the supported limit reserves one unit of headroom for legacy Windows PowerShell 5.1 copy and cleanup operations. Unified setup rejects a deeper root before asset hydration or dependency installation, the direct Windows launcher runs the verifier before checkout cleanup or npm ci, and every supported native app, iteration, signed, or distribution build entry point runs it before mutation. Use a real short directory such as C:\ArcaneOS; do not substitute a junction or weaken host path protections.

When advancing the machine-bundle version:

• add the new CHANGELOG.md section, then run npm run machine:version -- <major>.<minor>.<patch> so the central arcane-bundle.json authority and its required npm/README mirrors change together;
• run the normal machine build so runtime and platform declarations are generated from the central manifest, then run npm run machine:version:check and the repository invariant;
• derive versioned artifact, archive, and installer names from the authoritative manifest instead of the source-directory name;
• keep all root scripts, workflows, tests, and documentation pointed at the permanent source directory;
• confirm the wildcard .gitattributes rules apply and include the stable lockfile path in CI cache inputs;
• run the repository-wide package-lock registry verifier, a clean dependency install, and npm run release:check:arcane-os without application behavior suites;
• verify that no version-suffixed machine-bundle source path, generated output, cache, secret, or signing material is tracked.

Unified developer setup

• setup-developer.bat and tools/setup-developer.ps1 are the authoritative Microsoft NT developer bootstrap. The interactive batch launcher opens the freshly built Provisioner after success; the PowerShell and npm forms remain build-only for scripted callers.
• machine_bundles/arcane-os-machine-bundle/build-windows.bat is a compatibility entry point that delegates to the repository-root setup. A missing-output start-provisioner.bat invokes that same setup before the original launcher retries the Provisioner. Nested launch ownership prevents duplicate windows. Interactive launchers must not implement an alternate dependency, hydration, signing, or build sequence.
• Arcane - Rebuild Windows and Open Provisioner.bat is the prepared-checkout rebuild path. It verifies the Microsoft NT checkout path and public lock sources before dependency mutation, freshly installs the root and machine-bundle dependency trees once each, runs the canonical Microsoft NT development build exactly once, and launches only the newly verified output. Its explicit optional --offline mode applies npm ci --offline to both trees and fails on an incomplete cache; online failures never silently select it. The launcher never retries a failed rebuild through full setup.
• The bootstrap must reject an over-budget Microsoft NT build root before network, asset, dependency, signer, or build work, including when optional test execution is skipped.
• Before exact-asset hydration, dependency installation, signing, or compilation, the bootstrap must run its dependency-free source and current-state preflight: synchronized machine version, public lock registries, all four Windows host/source contracts, required SDK/.NET host paths and portable-executable identities, pinned WebView2 metadata and cache-path shape, bounded generated-release JSON, and an exact link-only filesystem-topology walk that reads no payload bytes. A coherent older generated release is replaceable state, not a version error. Because setup and the later builder are separate processes and no unauthenticated file can delegate a verification receipt, the builder reclassifies the target once under its own publication lock before recovery or compilation; that state-bound repetition is required, not a payload hash replay. The WebView2 package owner verifies and extracts one retained read-only stream at its consumption boundary instead of hashing the same cache path twice. Only functional checks that require newly created inputs or outputs may first run at the later creation boundary.
• Standalone and provider-started target-app build children also authenticate and extract the exact WebView2 package from one retained read-only stream. Until the native provider delegates an authenticated broker-held extraction receipt to each child, each independently isolated target build owns one 9,258,495-byte package hash; a command-line prepared-toolchain assertion is not authority to skip that check.
• The bootstrap must use canonical/default OsSetup and inspect or hydrate exactly 169 active paths before either dependency tree is installed, a development signer is initialized, or compilation starts: 116 speech assets plus 53 published application-owned originals (1,129,144,553 bytes). It must never select AppDevelopment, whose explicit scope handles all 222 entries. Classification before hydration must not hash exact-size candidates. After the last hydration mutation, one persistent filter process streams and hashes the 169 selected files once, holds their filesystem identities and the manifest/filter/published-release policy inputs immutable, updates only an isolated index, and reuses that generation for the unchanged 116-file speech subset. Scope, file n/N, bytes, elapsed time, rate, ETA, and a five-second heartbeat remain visible in the setup transcript. The fallback transfer uses 81 parts and 1,352,830,332 bytes; the combined archive authenticates all 106 selected central-directory members, while the 53 source members remain metadata/transport-only and are never opened, decompressed, individually hashed, or written. An asset mismatch discovered later is a setup-order defect, not a reason to repeat the same check.
• The default workflow must safely prepare an upgraded checkout before strict verification, install or verify public prerequisites, validate dependency sources before npm ci, install both dependency trees, configure hooks, run only the fast development invariants, initialize only the per-user development signer, and build the development-signed distribution.
• System packages installed by the bootstrap must use exact public WinGet identifiers. Pin major toolchains when Arcane's build contract depends on them.
• Optional skip switches may shorten an intentional rerun, but must never silently weaken production signing or convert a failed step into success.
• On Microsoft NT, preserve an existing pnpm hardlinked dependency tree under ignored tmp/ before switching that checkout to npm ci; npm may return a negative EPERM status while unlinking pnpm hardlinks.
• Use an ignored repository-local npm cache for unified setup so corrupted or permission-restricted user-global cache state cannot affect the build.
• Keep a focused source-contract test for step order, package identifiers, exit-code propagation, and the prohibition on production signing material.
• Keep focused work-graph tests that prove shared prerequisites and OS-owned artifacts execute once, selected apps/models are the only per-item work, unchanged artifact states reuse immutable hash-bound evidence, and cache identity changes invalidate reuse.
• Keep focused responsiveness tests that prove immediate acknowledgement, foreground event flow, bounded concurrency/backpressure, progress/heartbeat delivery, safe cancellation or resume, and observed worker errors.
• Follow docs/developer-reference-sop.md: every new or changed system tool, developer launcher, root npm command, or machine-bundle npm command must update docs/developer-commands.md in the same change.

Repository Microsoft NT launchers must acknowledge work before it begins, preserve a nonzero build or launch status, and never fall through to stale or missing output. The clearly named first-setup, rebuild-and-open, and open-current launchers provide the supported double-click choices; failures remain visible with the applicable setup log or recovery path.

Required handoff

Report:

• dependency source and lockfile verification;
• canonical line-ending and byte-contract verification;
• affected public packages regenerated, reviewed, and manifest-verified before push;
• launcher exit-code behavior;
• local, development-signed, or production signing mode used;
• exact clean-state build and verification commands;
• the recorded cardinality and loop multiplier, estimated versus measured cold-path operation count/bytes/time, invariant work hoisted or cached, and every justified repeated operation;
• the trust facts checked, artifact-state identity, immutable evidence reused, and changed boundary that required any new validation;
• the attacker model and independent authenticity anchor for every trust claim, plus any digest intentionally limited to consistency diagnostics;
• the verification receipt owner, exact binding and generation, downstream consumers, authenticated cross-process delegation, and invalidation and mutation-drain boundary;
• how necessary long-running work reports live progress;
• the immediate UI/CLI acknowledgement point, background-task owner, concurrency/backpressure limits, heartbeat, cancellation/retry/resume behavior, and any required serialized trust or transaction boundary;
• generated release location and final exit code;
• any production-only check not run and why.