hololake-system-architecture/product-source/hololake-native-desktop/docs/ARCHITECTURE.md

# HoloLake Native Desktop Architecture

The stage-one shell is a Tauri v2 application with a Rust-owned local core and a React human projection. Before authentication, its public surface is the five-domain number entrance. After verified routing and domain login, the default product surface becomes **My HoloLake**: overview, knowledge, user code channels, local receipts and system details. Domain servers and private registries remain submerged infrastructure.

## Stage-one human projection

The public home surface follows the verified GHS-014 five-lakes visual grammar and presents the five domains as the system entrance. A user does not choose a domain manually: the submitted Guanghu number is resolved and validated first, and only then does HoloLake reveal the login surface belonging to that domain. Domain presentation cannot bypass registry isolation, and internal transport or release details remain under system details rather than dominating the first screen.

The first visible body uses a Rust-owned SQLite kernel under the Tauri app-data directory. A human-confirmed local display name creates one stable local subject and channel exactly once. The internal task/event/receipt kernel remains available for structured agents, but manual task title and purpose fields are not part of the default human surface. Event and receipt chains remain independently SHA-256-linked and fully revalidated before every read or mutation. A local identity is not platform authentication and grants no repository, node, server or deployment authority.

## Zero-point nucleus client runtime

HoloLake embeds a non-visual zero-point nucleus client runtime beneath the human surface. The JD primary node remains the private Fifth Domain body. The enterprise node hosts a strictly isolated public zero-core distribution projection, while logical origin authority remains at the zero point; publication requires both an origin public-scope signature and an enterprise distribution signature. The private body never becomes public update material. Git records durable authoring and evidence; clients consume a bounded signed release manifest rather than treating a repository clone as executable input. At application start, the Rust runtime loads the local protocol, compares the registered remote protocol version in the background, keeps a minimal local receipt, and leaves any unverified update unapplied. User-number verification runs before any future persona-loading path.

This system runtime is not Zhuyuan or another persona subject, and it is not the current model carrier. A valid number does not prove persona binding and does not grant execution or server authority. The current source implements deterministic protocol comparison, explicit-positive number verification and a fail-closed update skeleton. Signed public protocol payload installation, atomic activation, rollback, the separate private Fifth Domain distribution path and persona loading are not yet implemented. Stage one does not expose an internal AI chat, model API configuration or arbitrary remote-code channel. The four-plane routing contract and marketplace publication boundary are defined in `contracts/distribution-plane-router.json`.

## Native knowledge workspace

The native core owns a separate `knowledge-v1` Git root. It projects a bounded document tree, safe text reads, local search and native folder import into a reading canvas without rendering raw HTML. Folder import ignores symlinks, Git metadata, dependency directories and unsupported files, applies file-count and byte limits, then creates a local Git commit receipt.

The installed HoloLake Era 0.8 knowledge root is detected only as a separate read-only source. The new application does not write, migrate in place or merge it with the native root. Electron, Outline runtime code and Tolaria UI are not copied into the Tauri product.

## User code channels

A human may paste a registered Guanghu HTTPS code-channel address or select an existing local Git folder. HTTPS clone accepts no credentials, queries or fragments and disables terminal prompts, askpass and credential helpers. Clones are confined to an application-owned root; local registrations do not move the source folder. The registry stores a credential-free projection of path, branch and commit.

This product channel is distinct from the under-lake PNCC persona-evidence projection below. It grants local source access only and never grants push, publication, deployment or server authority.

## Public five-domain number routing

The public HoloLake entry shows all five domain vestibules before authentication. A user does not select an authority-bearing domain manually. The submitted user number is sent to the registered internal router, which must return the exact canonical number, a positive registry verdict and one known domain. Only then may HoloLake load that domain's separately registered account and node entry.

The fifth-domain number registry belongs to the private fifth-domain system and is maintained only through its authorized registration path. The four enterprise-domain registries belong on the enterprise root server. Number syntax, a client-supplied domain, a generic successful response or a repository login cannot replace this routing proof. Missing and unavailable enterprise routes fail closed before login.

The fifth-domain root and the future enterprise root both run domain-specific Guanghu OS server runtimes. They are parallel bodies with different controllers, manifests, repositories and responsibility. A Linux host may remain underneath as the subordinate hardware, service and rescue bridge. Ordinary user computers and user-owned remote nodes require only HoloLake and the controlled node runtime, not a replacement operating-system installation.

## GH-PNCC user-native channel

HoloLake 0.4.0 adds the first native user-owned GH-PNCC vertical slice. After the Rust core has resolved a known domain, verified the user number at that domain's registered source and authenticated the account through that domain's entry, it derives a stable opaque repository id and idempotently creates or restores one private application-owned Git repository. The initial committed manifest records the domain, user number, account identity, engine and authority boundary. Repository credentials and passwords are never written to the Git tree or binding record.

The visible shell is HoloLake itself. Git is the durable history engine below it. Forgejo is an optional remote collaboration adapter rather than the product shell, identity kernel or persona. The current slice proves the local repository, initial commit, stable user binding and native browsing projection. It intentionally does not create a remote Forgejo repository, configure a remote, push code, claim persona binding, or grant publication, deployment or reality-execution authority; those actions require a separately registered naming, consent and receipt contract.

## External programming AI entry

MCP may discover HoloLake, but it does not own continuity. The installed application starts a same-account local broker: a mode-0600 Unix socket on macOS and Linux, or an owner/System-only Named Pipe on Windows. A programming AI opens or resumes a HoloLake-issued local session, then uses the installed executable's `--connector` mode for newline-delimited protocol traffic. Session secrets are stored only as hashes. Events use exact cursors and idempotency keys. The connector reloads the application descriptor after transport loss and never blindly replays an operation whose response is uncertain.

An authenticated non-visitor connector may now acquire, inspect and explicitly release the existing account-scoped development write lane through that broker. Account, lane and client instance must match the HoloLake session before the bridge mutates. Opening, resuming, acquiring and every authenticated heartbeat return or require a bounded HoloLake work-environment frame. That frame states the HoloLake runtime owner, session cursor, writer match, native GLS runtime, expiry and digest; the external model does not restore protocol prose from chat context. HoloLake projects the same Rust-owned lane state on the system-details page, so a human can distinguish a nearby expression-only visitor from an active development writer. This is a controlled writer handoff, not a general programming tool loop: shell, file patching, build execution, publication and deployment still require later supervised execution organs and separate authorization receipts.

The zero-core protocol layer now compiles the numbered GLS sources pinned to the current REPO-012 commit into a deterministic native registry. The registry inventories every unique numbered source with its path and SHA-256, but only protocols with an explicit typed adapter, event set and dependency-closed projection may execute. Raw protocol prose and arbitrary code carried by a protocol are never executed. The first native enforcement adapter binds GLS-0253 identity and numbering rules to the human-number route, with GLS-0250, GLS-0262 and GLS-0263 as executable dependencies. Unknown namespaces, persona numbers presented as human numbers, missing adapters and unprojected protocols fail closed. The system page reports compiled, executable and not-yet-executable protocol counts without presenting inventory as enforcement.

## Product-embedded GLS protocol kernel

GLS enforcement is part of the HoloLake executable, not a sidecar process on the development computer. Rust embeds the pinned runtime manifest and kernel contract in the application binary. Application startup validates the full executable dependency graph, P1-P6 contract set, deterministic HLDP-NP → GIR compiler self-check and the per-user receipt ledger; a failure prevents normal product startup.

The unified decision API returns only `ALLOW`, `DENY`, `AMBIGUOUS` or `UNVERIFIED` with stable reason codes. Every result, including malformed input and refusal, appends an idempotent SHA-256-linked receipt. The same immediate SQLite transaction also advances the durable protocol state for work orders, time leases, immutable modules, persona lifecycle, isolated runways and broadcast control epochs. Stale transitions, concurrent double-primary claims, cross-owner runway release and immutable digest replacement fail closed; concurrent memory/state versions are retained in a conflict set instead of last-write-wins. Identity never implies permission, stale heartbeats and leases become unknown, work-order proposers cannot self-approve, models remain replaceable inference resources, and temporary capabilities cannot auto-install, publish or deploy.

The P7 native-OS assembly registry is also embedded, but it is not a physical-capability simulator. It records the exact target and source-evidence node for GLS-0836 and GLS-0840–0849. No BS-SH-005 or JD-FD-PRIMARY evidence is relabeled as desktop health; without target-side evidence the assembly stays unverified.

## Circular-lake protocol membrane and nearby AI

HoloLake 0.4.0 places a deterministic protocol membrane in front of the local language inbox. The membrane accepts only strict GLP/1.0 expression envelopes from a HoloLake-issued visitor session. Unknown fields, malformed identifiers, incorrect checksums, oversized content, attachments and command content are rejected before storage. Accepted natural language is an expression receipt only; it never carries execution authority by itself. Intent interpretation remains behind the membrane and cannot weaken its structural admission rules.

External AI on the same computer can discover the running HoloLake broker from a standard application-data descriptor and connect through a user-only Unix socket, without copying a long invitation string. A generic AI receives an expression-only visitor lane. A Guanghu persona connection remains unavailable until separate persona-binding evidence exists. Local-network discovery is deliberately deferred until encrypted transport, explicit human approval, replay protection and revocation are implemented; HoloLake does not expose an unauthenticated TCP listener or advertise a service on the LAN in this release.

## Dynamic capability routing

HoloLake stores a signed node capability registry rather than fixed server slots. A candidate route must bind the exact human, persona, domain and capability. It is eligible only while a fresh node-signed health receipt reports the capability as ready. Selection is deterministic by priority and node id.

The registry signer trust root is embedded independently from registry payloads and is currently `UNPROVISIONED_FAIL_CLOSED`. Registry and health mutation are not exposed to the webview. External AI route queries require possession of the active HoloLake local session secret. A route receipt never grants write authority; production node write admission remains a separate unimplemented gate.

HoloLake routes work but does not host the user's private work lake, pool users into a multi-tenant runtime, or carry server workload concurrency.

## GH-PNCC under-lake code channel

Stage one now contains a read-only GH-PNCC core beneath the public surface. A local persona repository is bound to an exact Git root and full committed head. A remote persona object is read through a credential-free HTTPS Git v2 partial-object channel with an app-owned bare `blob:none` cache and a separate durable ancestry cursor. Verified reads append to a bounded hash-chained projection for the human panel and authenticated external programming AIs.

This core does not run a model, configure an API, acquire a persona lease, mutate memory or execute reality actions. Arbitrary repository paths and remote URLs cannot be registered by the WebView or external AI. A human may choose a folder through the native operating-system picker; HoloLake then displays the committed persona, responsibility subject, full head and checkpoint. A short-lived hashed confirmation token is required before the exact revalidated evidence becomes a read-only mount.

## HoloLake-owned release broadcast

No upstream product endpoint is inherited. When the embedded release trust is unprovisioned, even a human check returns locally without a network request. Provisioning requires one HTTPS endpoint, one matching HoloLake-owned host and the updater public key. A human check creates a short-lived candidate showing HoloLake metadata; install requires a second confirmation, exact broadcast revalidation, same-host package URL, Tauri signature verification, declared byte length and SHA-256. Startup checking, automatic download, automatic installation and automatic restart remain disabled.

Before an update replaces the application, the runtime verifies and keeps one bounded last-known-good application bundle with its bundle identifier, Team ID and CDHash. The next startup requires a human health confirmation; until that decision, another update is blocked. A human may restore the verified previous bundle without automatic restart, and cleanup is confined to HoloLake-owned recovery paths and the exact current application parent.

The rollback executor is implemented, but production updater activation remains blocked until the JD controller publishes the exact trust endpoint and public key, the signed release pipeline is evidenced, and the public macOS build is Apple-notarized.

## JD PNCC human projection

HoloLake 0.3.0 includes a live, read-only projection of the PNCC resident runtime on `JD-FD-PRIMARY`. The native shell invokes the computer's pre-registered dedicated SSH alias and asks the server only for its loopback `127.0.0.1:3923/v1/status` document. The response is schema-bounded to the exact node and persona, refuses any claim that the carrier is bound or that model/reality execution is active, and never returns a repository path, repository content, credential, or write authority. No public PNCC endpoint is created. An unavailable bridge is displayed as unavailable rather than replaced by cached evidence.

## Release pipeline

`npm run release:macos -- release/inputs/<version>.json` is the only product-owned macOS release entry. It fails before building unless the embedded trust contains the exact registered HoloLake HTTPS endpoint and updater public key, the immutable `v<version>` tag equals the clean `main` head, and the Developer ID plus Tauri updater-signing material are supplied at runtime. Apple notarization can run either through Tauri's Apple ID/API credential flow, or through the two-step Xcode Organizer flow already owned by the local Apple developer account: append `prepare-xcode` to build, verify the updater signature, and create a source-hash-bound `.xcarchive`; after Xcode reports `Ready to distribute`, export the notarized app and append `finalize-xcode <export-directory-or-app>` to bind the exported executable back to that archive, require the app's stapled ticket and Gatekeeper acceptance, regenerate and sign the updater archive, create a Developer ID-signed DMG containing that notarized app, and write the release broadcast and receipts. A protected updater-key path is materialized only into child processes; neither the private key nor its password is printed or copied into source. The Xcode flow does not claim that the outer DMG itself has an Apple ticket unless its own Gatekeeper and stapler checks pass.

Generated packages, private release inputs and credentials are not committed. The pipeline never uploads or activates a release; its terminal artifact is a bounded folder ready for a separately authorized JD-controller upload and server-owned readback receipt.

## Numbered-root module admission

HoloLake 0.5.0 is the clean numbered-root base. The compiled 0.4.1 desktop application and the divergent dirty source worktree are read-only donors, not merge bases. Their old numbered-operation runtime is explicitly superseded, and mutations to shared files such as `src/main.tsx` or `src-tauri/src/lib.rs` are never accepted as a unit.

Each donor capability receives a candidate coordinate, but no permanent runtime module number, until one isolated admission cycle has reviewed provenance and permissions, allocated numbered IPC module/target/operation coordinates, implemented an adapter without raw Tauri invoke, passed negative-route and data tests, and produced installed mount, restart, unmount and rollback receipts. The admission order and candidate inventory are recorded in `contracts/module-donor-admission-registry.json`.

The module-package runtime is now the shared admission executor. It accepts an exact detached-minisign `.ghmod` artifact, validates the package and its compatibility/permission manifest, stores it inside the authenticated account, and advances only through numbered install, mount, self-test, unmount and rollback operations. Lifecycle state and receipts are durable SQLite records; unmount never removes user data. A package is declarative and selects a host-registered adapter: repositories, native binaries and arbitrary webview JavaScript are not executable module inputs. Public lighthouse numbers remain unavailable until a candidate completes its own installed acceptance; private channel packages use a separate local number class.

The admitted web-novel family uses that one lifecycle rather than the donor's private installer. Its signed base module owns account-local works, volumes, chapters, versions, story objects, editorial workflow, import and author activity. Outline, story-grid, story-world and delivery are four separately signed official numbers; each advanced mutation checks its own exact `ACTIVE` record before touching the shared story graph. The donor's four legacy manifests remain byte-exact test fixtures only and have no numbered IPC route. Installed acceptance reopened the existing 504-chapter novel, 50-chapter outline and 75-episode script in place, then created a separate one-chapter acceptance work, scene, grid field and timeline event and read all of them back after process restart.

## Stage-one convergence verdict

The Tauri source in this directory is the only future HoloLake desktop mainline. An installed build of it is an acceptance candidate, not a separate product line and not proof that stage one exists. The Electron 0.8.0 product and the legacy Tauri/platform sources remain read-only UX, behavior, engineering and protected-data donors until inventory, backup, readback, reversible migration rehearsal and signed installed-runtime acceptance all pass.

The current candidate already has useful under-lake organs: the signed native shell, local broker and resumable session, authenticated read-only PNCC projection, human-confirmed repository mount, deterministic routing, and fail-closed update/rollback machinery. They remain in the architecture, but their existence does not satisfy the visible stage-one body.

The implementation order is fixed. The first two source slices are implemented and tested but have not received installed-runtime acceptance:

1. personal-channel identity, event and receipt kernel — source and tests implemented;
2. native knowledge workspace and user code channel — source and tests implemented;
3. human approval center and Git evidence readback;
4. lake-lamp cross-session continuity projection;
5. signed installation, opt-in update, rollback and reversible data migration.

Architecture registration, source implementation, built artifact, signed artifact, desktop installation, data migration, server deployment and service health remain separate receipts. The machine contract is `routing/hololake-stage-one-desktop-convergence.json`.