Development lifecycle | Arcane OS Docs

Current operating profile

ARCANE is currently a development-only project.

There is no staging environment.
There is no production environment.
There are no staging or production branch protections.
main, feature branches, and work branches are development branches.
No build, package, workflow result, screenshot, demonstration, or checked-in dist/ tree is a release candidate or production claim.

This profile is intentionally optimized for rapid implementation, experimentation, and internal demonstrations. It does not waive the development safety invariants below.

Default development loop

Use the smallest check that answers the current engineering question:

make the focused change;
run the closest focused test while iterating;
run npm run check before pushing or handing off; it combines the fast development invariants with the managed portable OS unit profile, not the complete Arcane OS or application suite;
package only the selected application when an actual package or demonstration is needed;
run an application's full suite only for that application's release;
use the Arcane OS integration, native-host, or release command only for an explicit Arcane OS release moment or when the work affects that boundary.

The current command profiles are:

Profile	Command	Purpose
Rapid development invariants	`npm run check:dev`	Default checkout, dependency-source, setup, version, path, catalog, badge, and release-profile invariants for ordinary iteration, pre-push, and CI prerequisites.
Development handoff	`npm run check`	Runs `check:dev`, then executes every canonical portable OS unit case once.
Application demo	`npm run demo:check -- <app-id>`	Rebuild and verify only the selected browser-context application package.
Application release	App-owned full suite, followed by `npm run app:release -- <app-id>`	Tests and releases only the selected application; never part of an Arcane OS gate.
Arcane OS integration	`npm run check:integration`	Full portable Arcane OS runtime, host, isolation, and package-boundary gate; excludes application behavior suites.
Microsoft NT iteration	`npm run check:windows:fast`	Explicit fast native-host iteration build; not release evidence.
Arcane OS release	`npm run release:check:arcane-os`	Explicit Arcane-OS-only portable and Microsoft NT gate. It retains app admission and payload-integrity checks but does not run app-owned behavior suites.

npm test, npm run check:dev, the Git pre-push hook, and ordinary continuous integration use the rapid invariant profile. Root npm run check adds the complete managed portable OS unit profile for handoff without selecting functional, coverage, UI, system, native, or application behavior suites. Unified developer setup is deliberately separate: it validates prerequisites and build safety, then performs the requested build without running tests. These paths do not collect formal release evidence. npm run release:check remains a compatibility alias for npm run release:check:arcane-os; neither command selects production signing.

The complete Arcane OS suite runs only for an explicit Arcane OS release. An application release does not select that suite, and an Arcane OS release does not select any application's complete suite. These are separate release decisions owned by separate products.

Mandatory work-amplification review

Before implementing or materially changing setup, build, package, test, model, app, or runtime work, complete the work-amplification review in app-building.md and build-release.md. State the cardinality and loop multiplier, classify expensive operations as invariant, identity-bound per item, or batchable, and estimate the representative cold-path operation count, bytes, and time. Hoist or safely cache invariant work, batch compatible work, and document every justified repetition before implementation begins.

Use one check per trust fact per artifact state. If bytes, policy, identity, location, and toolchain remain unchanged, reuse immutable hash-bound evidence and do not rerun the check. If assembly changes only placement or inventory, verify only that changed boundary. Repetition requires proof that the underlying state changed or an explicit independent-verification mandate, with its multiplier and measured cost documented; generic defense in depth does not justify identical repeated work.

A digest proves only that bytes match a reference; it proves authenticity only when the expected value is independently authenticated and outside the authority that can replace the bytes. Accepted anchors include a trusted publisher signature, a signed host-embedded binding, an authenticated retained-handle receipt, or an equivalently independent protected policy. A checksum, manifest, sidecar, catalog, or recovery record stored beside the payload, generated from that payload, downloaded from the same publication authority, or writable by the same principal is a consistency record—not a trust anchor. It must never by itself authorize execution, activation, restoration, privilege, capability, publisher identity, or a verified/trusted claim.

Use same-authority hashes only where corruption, incomplete transfer, stale cache, or transaction drift is a real product concern. Label that purpose accurately, warn on a difference without taking down the containing UI, and refuse only the affected bytes when execution or authorization still requires trust. Never regenerate an expected digest from untrusted current bytes and then treat those bytes as verified. Do not add a hash merely to appear secure; record the attacker and independent anchor first, or omit the check.

This applies to ordinary development as well as release automation. Setup and OS builds must not compile apps or repeat OS-owned downloads, extraction, dependency installation, compilation, hashing, signing, integrity scans, smoke tests, model service setup, or runtime preparation once per app. Apps own their independently released prebuilt output; Arcane OS owns one generic admission and installation boundary. Select models from explicit hardware and product policy, and acquire each unique model identity once rather than once per consumer.

Measure a representative cold path after implementation. Eliminate redundant work before adding progress UI, then preserve streaming phase/item/count-or-bytes/elapsed visibility for necessary long-running work. A faster-looking progress bar does not make repeated work acceptable.

The responsiveness invariant applies in every lifecycle profile. A UI or CLI acknowledges immediately before potentially blocking work; network, disk, hashing, compilation, process, model, and integrity waits never delay UI creation or block its foreground thread. Use event-driven background workers or genuine asynchronous I/O. async/await is allowed for genuinely asynchronous operations but must not wrap synchronous blocking work. Bound concurrency and apply backpressure; emit progress and heartbeat events; support cancellation and safe retry/resume where practical; and give every task an owner that surfaces failures. Unobserved fire-and-forget work is prohibited. Serialize only a true trust or transaction boundary and only after visible status exists.

The approved OS test taxonomy, no-residue contract, and migration inventory are documented in os-testing.md and os-test-inventory.md. The managed unit, functional, UI-integration, portable-system, smoke, and combined c8 profiles are active and report numeric set results. Native-system profiles remain explicitly marked not run until their target-specific migrations produce current evidence.

Verification receipt lifecycle

One expensive trust decision has one verification owner for one exact artifact state. The owner holds the file and directory handles or another equally strong immutability boundary, performs the integrity and publisher work once, and creates an immutable verification receipt. The receipt binds canonical location and filesystem identity, content and inventory hashes, policy, toolchain, platform and architecture, signing identity and trust result, and a monotonic transaction or installation generation. Downstream status, catalog, install, update, launch, and package consumers reuse the authenticated receipt while those facts remain unchanged; they do not rerun the same hashes, signature checks, or catalog walk for generic defense in depth.

Receipt reuse ends before a bound byte, identity, location, policy, toolchain, signer, inventory, or generation changes. The owner stops issuing delegations, drains or cancels active consumers, closes retained handles only when the mutation boundary is ready, performs the write, rename, activation, repair, rollback, or replacement, and verifies the resulting state into a new generation. Placement- or inventory-only assembly carries forward unchanged payload evidence and checks only the changed boundary. A path, timestamp, size, time-to-live, or process-local cache or memo alone does not prove unchanged state.

Cross-process reuse requires an authenticated shared owner. On Microsoft NT, Shell, Provisioner, applications, Core, and privileged workers must obtain delegated receipts from a shared Arcane host, broker, or service that retains the verified handles, authenticates named-pipe peers through kernel process identity, and binds each delegation to the consumer process and receipt generation. Environment variables, command-line claims, unauthenticated interprocess communication, and an administrator-protected receipt file by itself are not sufficient authority. The foreground acknowledges before receipt acquisition or a cache-miss verification; the owner reports phase, count or bytes, elapsed time, progress or heartbeat, and failure to every waiting consumer.

Development safety invariants

The project can move quickly without turning off its architectural safety boundaries:

do not commit credentials, signing keys, tokens, private registry configuration, protected user data, or unnecessary personal information;
use synthetic or disposable data for development and demonstrations;
do not use production identities, production endpoints, production signing material, or production trust claims;
keep capability checks, input validation, app isolation, renderer boundaries, and privilege separation enabled;
do not add a development bypass that silently grants authority or changes production-policy code paths;
label unsigned and development-signed artifacts accurately;
keep destructive experiments bounded to disposable data or a disposable machine;
preserve a focused regression test when a defect would otherwise be easy to repeat;
stop and use the applicable security, accessibility, or release process when work crosses the escalation boundary below.

These are implementation constraints, not formal security approval. Formal security/privacy and accessibility assurance belongs to promotion, pilot, and production review.

Internal demonstration boundary

An internal demonstration may use:

source-hosted applications;
the selected app's verified dist/<app-id> package;
an explicitly unsigned-local-test or development-signed native build;
synthetic content and development-only providers;
a developer workstation or disposable test machine.

An internal demonstration must not:

be described as staging, production, release-candidate, certified, approved, hardened, or ready for deployment;
use production credentials, protected operational data, or real participant records;
silently weaken capability, isolation, validation, or privilege controls;
be distributed as a trusted publisher release;
be used as evidence that the complete release, security, privacy, accessibility, update, recovery, or rollback journey passed.

If a demonstration needs real protected data, real users, production credentials, unattended elevated operations, or deployment outside the controlled development group, it has crossed the development boundary and needs an explicit promotion decision.

Generated packages during development

Checked-in generated packages are not required to be refreshed for every source edit during rapid development. Generate only the package needed for the current demonstration or package-specific investigation.

Review generated output before intentionally committing it.
Do not hand-edit generated manifests.
A stale development dist/ tree is not evidence that its source is broken or release-ready.
A demo handoff must identify the exact generated directory and the command used to build it.
Full regeneration of affected public packages is deferred to an explicit integration or promotion change.

Application behavior and publication belong to the application that owns them. The only application payload an Arcane OS build consumes is the app-published dist/<app-id> release rooted in ARCANE_APP_RELEASE.json. The OS may validate its identity, declared capabilities, entry point, exact inventory, byte sizes, hashes, safe file topology, and admission into the OS distribution because those are operating-system boundaries.

The OS must not use apps/<app-id> source as its payload, import or execute an app adapter, generator, or source verifier, rebuild an app, or run an app's content or business-behavior suite. A missing, stale, or invalid ARCANE_APP_RELEASE.json fails immediately at the generic OS admission boundary and is repaired through the app's own release process; it never causes the OS to take ownership of app verification. Each application runs its complete suite and advances its independent version only when that application is explicitly released.

This policy keeps high-fan-out generated files out of ordinary feature decisions while retaining deterministic package tools for the point at which an artifact is actually needed.

Keep the current tree current

Git is Arcane's version history. The working tree contains the current canonical source, documentation, contracts, and intentionally published artifacts—not duplicate historical copies.

Update the canonical file or directory in place and remove its superseded copy in the same change.
Do not retain old version-numbered source directories, prior validation records, renamed backups, superseded generated artifacts, or obsolete release archives merely as history or evidence; Git already preserves them.
Record a concise compatibility or migration note in the changelog when current users need it instead of keeping the replaced implementation beside the new one.
Keep historical bytes in the current tree only when a current runtime, automated test, legal obligation, or active audit contract explicitly requires them. Document their current purpose and dependency beside the retained material and keep the scope minimal.
Review generated and binary artifacts for continued current use. Remove them when the supported generator, dependency snapshot, or release no longer consumes them.
Before deleting tracked material that setup or a package manager can rewrite, prove a normal pull from every supported previously set-up checkout. If a dormant checkout could skip an intermediate migration and conflict with a later deletion, retain only the smallest documented compatibility shim; a version increment by itself is not proof that users absorbed an intermediate commit. Optional Git-metadata cleanup must never change object IDs or staged content and must never block pull, setup, validation, or build. Never make ordinary users stash, reset, or resolve generated-file conflicts to receive routine cleanup.

This rule applies equally to code, docs, machine bundles, applications, examples, evidence, and generated output. “For reference” by itself is not a reason to keep a superseded copy.

Run repository cleanup before an Arcane OS or app release and whenever checkout size grows unexpectedly:

run npm run cleanup:preview to list ignored files Git would consider removable;
review the list and remove only exact generated/cache paths that are no longer needed—never use a broad cleanup command against unreviewed user data, credentials, evidence, or hydrated development dependencies;
remove superseded tracked material only after proving no current consumer references it and a normal pull from every supported prior checkout remains conflict-free;
run npm run maintenance:gc for safe local Git object maintenance;
recheck git status, current-tree invariants, and the release's focused verification profile.

maintenance:gc uses git gc --auto. It does not rewrite shared history, delete remote refs, or purge Git LFS storage. History rewrites, aggressive pruning, and remote LFS deletion are separate destructive maintenance operations requiring explicit authorization, verified backups, and remote-owner coordination.

Lightweight security and accessibility deltas

During development, record only the decision that materially affects the design:

Security delta: Does this change introduce or alter identity, authority, privilege, a trust boundary, sensitive-data movement, a production credential, or an externally reachable endpoint?
Accessibility delta: Does this change introduce a new interaction model, block keyboard operation, remove semantic information, depend on one sense, or change a protected confirmation/recovery path?

If the answer is no, focused development tests and ordinary design review are enough. If the answer is yes, keep the change bounded, document the affected contract, add focused checks, and invoke the full review only when the change is being promoted or when the risk cannot safely remain inside a synthetic development environment.

Escalation boundary

Leave the development profile and apply the applicable full SOP before:

calling any artifact a release candidate, staging build, pilot build, or production build;
using production signing material or asserting publisher continuity;
deploying to real participants or operational users;
processing protected or operational data outside a deliberately synthetic test;
introducing or materially changing an actual privilege, identity, authorization, update, recovery, or cross-user boundary that cannot be safely stubbed;
asking an independent authority to accept security, privacy, accessibility, or operational risk.

Future promotion plan

The repository retains the release, security/privacy, accessibility, traceability, signing, clean-machine, rollback, and pilot SOPs as the target for future maturity. They are not active default gates today.

When ARCANE is ready for promotion:

define the supported product and deployment claim;
choose and protect staging and release branch patterns;
add staging-only integration workflows and production-only signed workflows;
create separate staging and production credentials, environments, approvals, and artifact retention;
freeze an immutable candidate;
run npm run release:check:arcane-os for the Arcane OS candidate and obtain separate release evidence from every application included in the supported product claim;
complete security/privacy and accessibility review against that candidate;
update traceability, threat, rollback, operational, and pilot evidence;
require accountable human go/no-go authority.

Suggested future branch roles, which are intentionally not configured yet:

Future branch	Intended role
`main`	Integrated development baseline until a staging branch exists.
`stage`	Protected candidate-integration branch with full portable/native gates and a non-production environment.
`release/*`	Frozen release-candidate branch with production signing, review evidence, and change control.
production tag	Immutable approved artifact identity after go/no-go.

Adding those branches alone must not activate deployment. Their workflows, credentials, environments, protections, and authority rules must be reviewed and enabled together.

Repository and reviewed source access