hololake-system-architecture/product-source/hololake-platform/guanghu-os

Guanghu OS cognitive-control and native research runtimes

Production target: Guanghu cognitive control with a constrained Linux execution substrate on JD-FD-PRIMARY.

Bare-metal GOSK/GHAL remains a parallel research and recovery lane. It no longer blocks the first production cognitive-control delivery.

Current final topology (ADR-0175): Guanghu OS starts and remains the master; a full Linux environment is preserved but normally dormant, awakened only as bounded subcontrol or as an independent rescue path. Linux deletion and a Linux-free boot are not completion predicates. The current JD deployment is still a Linux-hosted language-primary transition, not the final topology.

Protected bare-metal residency, recovery control, and native anchor HTTP are PASS_100 on the physical JD node. Bare-metal production cutover remains 0, because that research kernel does not yet provide code-channel and public-front-door service equivalence. This no longer blocks the accepted production path: Guanghu is the language-primary control system, while Linux remains the cooperative execution and rescue substrate.

This directory implements the handoff from the registered HLDP language world to deterministic real-world execution. crates/execution-bridge is the first production adapter: it accepts typed protocol requests, compiles them into allowlisted Linux systemd actions, and requires target-state readback before a passing receipt. The existing native kernel remains preserved below native/ as a hardware-sovereignty research backend.

See GUANGHU-OS-COGNITIVE-CONTROL-EXECUTION-ARCHITECTURE.md and ADR-0172.

Authority boundary

• world-seed/ is the authoritative HLDP world package.
• guanghu-hldp-runtime validates the package without guessing missing state.
• ghctl wake is the fixed continuity entrypoint for a human or a later agent.
• ghctl authorize checks every consequential action against the exact node-scoped standing authorization before it runs.
• GLS-0844 / GHNQG is the code channel's own quality authority. Every required gate is either 0 or 100; only an all-100 run may publish a passing receipt. External analysis products are non-authoritative observers.
• GLS-0845 / GHCIP governs historical runtime ingestion. Source registration, server-resident review, historical time catch-up, and online residency are independent from persona-subject existence.
• Rust is a bootstrap implementation language for the validator and control executable. It does not replace HLDP as the world-programming language.
• Ubuntu and the Forgejo Linux binary are current transition assets. Final production acceptance requires Guanghu master control, on-demand Linux subcontrol, a preserved Linux rescue path, and current target-side receipts; it never requires deleting Linux. Bare-metal GOSK/GHAL acceptance remains a separate research predicate.

The registered translation chain is:

TCS -> HLDP -> GLC -> GIR -> BTCP -> GOSK -> GHAL -> hardware

Guanghu supervisor and Linux subcontrol lifecycle

crates/supervisor implements the first fail-closed source contract for ADR-0175. A typed, policy-bound capability request can advance only through:

DORMANT -> STARTING -> READY -> EXECUTING -> VERIFYING -> RECLAIMING -> DORMANT

The request must bind the exact node, subject, capability, authorization, rollback checkpoint, backend, required protocol chain, and preserved rescue slot. Every failure after a wake attempt enters reclaim. A receipt can report PASS_100 only after target-side readback and a second observation proving the Linux subcontrol returned to DORMANT; a failed reclaim is FAIL_0_LOCKED.

The deterministic contract and isolation harness are implemented and covered at 100% of declared source lines and functions. No production Linux subcontrol backend, independent Guanghu boot supervisor, JD boot change, or physical cutover is implied by that source result.

scripts/linux-subcontrol-docker-backend.sh is the first executable shadow backend for the Linux-hosted transition. It binds the exact JD instance, backend id, immutable Ubuntu image digest, and preserved GRUB rescue slot. It accepts only the direct Ubuntu repository or the explicitly approved docker.m.daocloud.io/library/ubuntu proxy needed by the JD route; arbitrary registry paths fail closed. A wake starts a networkless, read-only, capability-free container with explicit CPU, memory, and PID limits. Only the registered runtime-identity readback is accepted; reclaim removes the container and verifies DORMANT. Environment path overrides are rejected outside the isolated test harness.

This backend can prove the bounded Linux lifecycle while Ubuntu is still the host. It cannot prove Guanghu-first boot control or the final topology. Those remain 0 until the same lifecycle is owned by an independently booted Guanghu supervisor and has a current JD server receipt.

Pre-root Guanghu supervisor source slice

scripts/guanghu-first-boot-supervisor.sh and the matching initramfs-tools hook move the first deterministic Guanghu control state ahead of the complete Ubuntu root filesystem. The pre-root step binds the exact JD DMI instance, root UUID, boot ID, explicit guanghu.first_boot=1 kernel marker, preserved Linux rescue entry, and repository bridge. It then writes one boot-scoped handoff under /run/guanghu/first-boot while the complete Linux userspace is still classified as dormant.

scripts/build-guanghu-first-boot-initramfs.sh builds a candidate without changing the installed initramfs, GRUB, disk, or boot default. Path overrides are accepted only inside the isolated test harness. The JD-hosted QEMU receipt now proves both pre-root execution and a hard stop when authority binding is missing. It did not attach the live disk, change physical boot files, or reboot the node. A Guanghu supervisor still has not been shown to remain alive across switch_root; independent first-boot control, physical deployment, and full on-demand Linux subcontrol therefore remain 0. See ADR-0176 and deployments/JD-FD-PRIMARY/PRE-ROOT-SUPERVISOR-QEMU-RECEIPT-20260815.hldp.

Cross-root Guanghu supervisor source slice

scripts/guanghu-root-supervisor.sh revalidates the live machine and the boot-scoped pre-root handoff after /run moves into the mounted root. It then stays resident with ROOT_SUPERVISOR_ACTIVE; the systemd projection starts it before sysinit.target. scripts/build-guanghu-cross-root-fixture.sh creates a read-only minimal root image for QEMU proof without mounting or modifying a host disk. The JD-hosted QEMU receipt now proves the move into the new root, live-binding revalidation, and a resident root-supervisor process. It does not prove physical boot or bounded wake/reclaim of the real repository bridge, so those predicates and final master control remain 0. See ADR-0177 and deployments/JD-FD-PRIMARY/CROSS-ROOT-SUPERVISOR-QEMU-RECEIPT-20260815.hldp.

Bounded repository bridge lifecycle

scripts/guanghu-repository-bridge-lifecycle.sh requires a live root-supervisor state and one allowlisted repository readback request. It wakes a registered backend, verifies the pinned main, and reclaims the backend on both success and failure. scripts/forgejo-repository-shadow-backend.sh provides a separate loopback-only Forgejo data plane for physical-node isolation tests; it never targets the public repository process. JD request REQ-JD-REPO-003 now proves the real Forgejo shadow lifecycle from DORMANT through verified readback and back to DORMANT, including fail-closed cleanup. This raises only the isolated repository lifecycle predicate to 100; physical Guanghu boot, full Linux on-demand subcontrol, and final master control remain 0. See ADR-0178 and deployments/JD-FD-PRIMARY/REPOSITORY-BRIDGE-LIFECYCLE-RECEIPT-20260816.hldp.

The cross-root fixture can additionally carry the same portable lifecycle controller and a loopback repository-service-equivalence backend. After the root supervisor becomes resident, it must wake the service, read the pinned main, verify the receipt, reclaim the listener, and only then power off the fixture. This QEMU gate complements rather than replaces the real Forgejo shadow proof. See ADR-0182.

JD-hosted QEMU request REQ-QEMU-CROSS-ROOT-001 now proves this cross-root service-equivalence gate at 100 and leaves no listener or QEMU process. The physical node was not rebooted, so physical first boot and complete Linux on-demand subcontrol remain 0. See deployments/JD-FD-PRIMARY/CROSS-ROOT-REPOSITORY-SERVICE-QEMU-RECEIPT-20260816.hldp.

Language-primary boot target

guanghu-language-primary.target makes the accepted cognitive-control model an explicit boot contract instead of leaving the controller as an unrelated Linux service. The target:

1. validates the exact JD machine, /guanghu/current five-domain world, standing authorization, and read-only execution policy;
2. requires the Zhuyuan controller, public navigation, authorization, architecture provision, and deployment-event services;
3. accepts the boot only after the controller reports RUNNING_COMPANION, the execution substrate reports PASS_100, and both public entrypoints return HTTP 200; and
4. writes a server-owned receipt without changing the kernel, bootloader, or preserved bare-metal candidate.

scripts/install-jd-language-primary-target.sh starts and verifies the target before changing the systemd default. Any failed installation restores the previous default target and removes only the newly installed boot-contract files.

JD-FD-PRIMARY completed the physical installation and controlled reboot on 2026-08-07 from source commit d430811e77765109e7f2e44de4abc37251fb36c5. The new boot reached the language-primary target in 36.146 seconds with all required services and public anchors at PASS_100. Linux remains the cooperative execution and rescue substrate; the preserved bare-metal candidate was not changed.

World contents

WORLD-MANIFEST.hldp registers exactly five domains, one logical broadcast tower, the continuity chain, the native handoff protocols, and the Guanghu Code Channel.

The code channel starts from the verified Forgejo 16.0.1 offline baseline at commit b3d7e4ac3cbccc220703097a51fa4c16bf302579. Forgejo is the temporary data plane and compatibility reference. CHANNEL.hldp is the authority for channel identity, intents, receipts, and the migration ladder:

1. verified source baseline;
2. hosted Forgejo data plane;
3. HLDP-native control plane;
4. GOSK-native object store and network data plane;
5. Guanghu-master boot with Linux preserved as on-demand subcontrol and rescue.

This migration ladder is capability-specific. The historical Linux-free step is superseded by ADR-0175 and must not be revived as a production gate.

Local verification

cargo fmt --all --manifest-path guanghu-os/Cargo.toml -- --check
cargo test --manifest-path guanghu-os/Cargo.toml
cargo clippy --manifest-path guanghu-os/Cargo.toml --all-targets -- -D warnings
cargo run --manifest-path guanghu-os/Cargo.toml -p ghctl -- \
  wake guanghu-os/world-seed
guanghu-os/world-seed/scripts/run-guanghu-native-quality-gate.sh \
  /tmp/guanghu-native-quality-receipt.hldp

ghctl wake validates the manifest, all five domain entries, the code-channel contract, standing authorization, dedicated-access receipt, continuity files, and exact repository digests before printing the recovery evidence.

Server recovery contract

The hosted construction path will install immutable versions under /guanghu/versions/<version> and point /guanghu/current at the active version. A future session must execute this chain before any change:

login
-> /guanghu/bin/ghctl wake /guanghu/current
-> WORLD-MANIFEST.hldp
-> CURRENT.hldp
-> last phase receipt
-> dedicated-access receipt
-> standing authorization
-> active workorder
-> code-channel entry and receipt
-> live broadcast epoch
-> act or fail closed

The current production classification is LANGUAGE_PRIMARY_ON_LINUX_HOSTED_TRANSITION. Running its toolchain or services on Ubuntu proves only the exact validated layer; it does not prove final Guanghu-first boot or on-demand Linux lifecycle control.

JD access uses strict host-key verification and a dedicated operations key. The world records only public fingerprints; it never contains an address, private key, password, or token.

JD Cloud native layout

The Shanghai GPT layout at LBA 34-71 is historical evidence and must not be copied to JD. JD-FD-PRIMARY is a legacy-BIOS, DOS/MBR, virtio node. Live read-only discovery proved existing GRUB content at LBA 0-104 and an empty pre-partition range from LBA 105 through 2047. The current HLDP layout owns only LBA 105-142 and fails closed if any byte there is unknown or nonzero.

Native build scripts derive their NASM addresses from WORLD-MANIFEST.hldp; the traditional bootstrap code no longer owns fixed Shanghai sector numbers.

The first JD one-time physical probe reached the native kernel and returned to Linux with a sealed FAIL_0 diagnostic: the cloud virtio-net RX queue exposes 4096 entries, while the inherited GHAL allocation accepted at most 1024. The JD adapter therefore assigns a non-overlapping 128 KiB region to each legacy queue and accepts the observed 4096-entry maximum. A failed probe remains a failure; its LBA 134 proof must be sealed and cleared with clear-jd-native-probe-proof.sh before an exact-hardware retry.

The exact-hardware retry passed with net RX/TX queues of 4096 and a block queue of 128. The next binary gate is a one-time resident boot. Its JD-specific prepare, arm, external ICMP peer, and return verifier must prove native network login, code commit, branch movement, world and gestational storage, and the HLDP-RECOVER-OS! return to Linux before any native default is selected.

Hosted Stage 1 installation

scripts/install-hosted-stage1.sh is the repeatable Ubuntu construction handoff. It requires a full implementation Git SHA and the SHA-256 of the transferred source archive. It uses the official stable Rust toolchain rooted at /opt/guanghu/{rustup,cargo}; Ubuntu's Cargo 1.75 is intentionally rejected because it cannot read this repository's v4 lock file. On the exact x86_64 /dev/vda lab shape, it:

1. runs the workspace tests and builds a release ghctl;
2. assembles and validates a temporary five-domain world;
3. writes a server-observed HLDP phase receipt;
4. makes the version immutable; and
5. atomically moves /guanghu/current.

An existing version is never overwritten. A failed assembly is retained with a .failed.<UTC time> suffix for diagnosis, while the previous current version remains active.

Hosted services Stage 1B

guanghu-broadcast-tower is the first continuously running executor for the logical singleton registered by HLDP. Its hosted surface is deliberately loopback-only (127.0.0.1:8077), exposes the validated five-domain world, and writes a live HLDP epoch. It always reports linux_exited: false.

scripts/install-hosted-stage1b-services.sh creates a new immutable world version, starts the tower, and installs the hash-verified Forgejo 16.0.1 package as the temporary code-channel data plane on 127.0.0.1:3080. Registration and Forgejo's SSH server stay disabled. The exact guanghu/main bundle is restored as a bootstrap bare repository, while HLDP remains the channel authority.

Both services are reachable from the local Mac through the dedicated SSH route; neither is published directly to the Internet. A failed service activation restores the Stage 1 world symlink and stops both hosted services.

The first successful hosted activation exposed a recovery inconsistency: CURRENT.hldp advanced while WORLD-MANIFEST.hldp retained the Stage 1 version. The immutable correction is 0.1.2-stage1b-r1; it rebuilds the world from the repository seed and advances both records together.