hololake-system-architecture/product-source/hololake-platform/guanghu-os/README.md

# 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`](../docs/GUANGHU-OS-COGNITIVE-CONTROL-EXECUTION-ARCHITECTURE.md)
and [ADR-0172](../docs/adr/0172-guanghu-cognitive-control-with-linux-execution-substrate.md).

## 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:

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

## 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

```bash
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:

```text
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.