# Reconstruction boundary

> Compiled source/ runtimes, checksum-pinned shipped renderer, reconstructed bundle id com.anysphere.sand.reconstructed, and ignored src/app/dist hydration.

- Repository: sashimikun/grok-bot-0.18-reconstructed
- GitHub: https://github.com/sashimikun/grok-bot-0.18-reconstructed
- Human docs: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15
- Complete Markdown: https://grok-wiki.com/public/docs/sashimikun-grok-bot-0-18-reconstructed-c774cc9a5c15/llms-full.txt

## Source Files

- `docs/ARCHITECTURE.md`
- `PROVENANCE.md`
- `scripts/lib/config.mjs`
- `scripts/package-macos.mjs`
- `scripts/lib/build-asar.mjs`
- `src/app/package.json`

---

---
title: "Reconstruction boundary"
description: "Compiled source/ runtimes, checksum-pinned shipped renderer, reconstructed bundle id com.anysphere.sand.reconstructed, and ignored src/app/dist hydration."
---

`npm run package` assembles a **fidelity hybrid** macOS app: reviewed TypeScript under `source/` is compiled into ASAR executables, the UI stays the checksum-pinned 0.18.0 renderer from ignored `src/app/dist/renderer` plus a recorded Settings Router patch, and the finished bundle is identified as `com.anysphere.sand.reconstructed` with an ad-hoc signature. The official 0.18.0 app is a reference-only, SHA-256-pinned input; packaging copies its Electron shell and ABI-matched natives, then replaces `app.asar` so the reconstructed package never ships the official archive or Developer ID signature.

<Warning>
Do not treat reconstructed material as original source or an official Grok Bot build. Upstream bundle ID is `com.anysphere.sand`. Reconstructed builds use `com.anysphere.sand.reconstructed`, ad-hoc signing only, and must not overwrite a machine-installed official app.
</Warning>

## Ownership map

```mermaid
flowchart TB
  subgraph tracked["Git-tracked reconstruction"]
    SRC["source/ Electron main, host, coordinator, daemons, preloads"]
    FE["frontend/ Vite design workspace"]
    PKG["src/app/package.json name sand version 0.18.0"]
    SCRIPTS["scripts/ bootstrap, compile, patch, package, verify"]
  end

  subgraph ignored["Ignored hydration"]
    DIST["src/app/dist from app.asar SHA-256 66654081…"]
    CACHE[".cache/runtime/Grok Bot.app"]
  end

  subgraph packaged["dist/Grok Bot 0.18 Reconstructed.app"]
    SHELL["Electron 42.1.0 shell CFBundleName Grok Bot"]
    ASAR["replaced app.asar hybrid runtimes"]
    ID["CFBundleIdentifier com.anysphere.sand.reconstructed"]
  end

  DMG["Pinned 0.18.0 DMG a253ccd8…"] --> CACHE
  CACHE --> DIST
  DIST --> ASAR
  SRC --> ASAR
  FE -.->|"not the packaged UI unless GROK_BOT_RENDERER_SOURCE"| ASAR
  PKG --> ASAR
  SCRIPTS --> packaged
  SHELL --> ID
  ASAR --> ID
```

Tracked `src/app/package.json` is the app metadata seed (`name`: `sand`, `productName`: `Grok Bot`, `version`: `0.18.0`, `main`: `dist/electron-main/main.cjs`). Generated `src/app/dist/` is gitignored and must be hydrated before compile or package.

## Hybrid runtime split

Default packaging calls `buildFidelityReconstructedAsar()`. Build kind in `dist/reconstruction-build.json` is `fidelity-hybrid-reconstruction`. Renderer mode is `checksum-pinned-artifact-runtime` with artifact root `src/app/dist/renderer`.

| Runtime | Packaged path | Default mode | Source of bytes |
| --- | --- | --- | --- |
| `renderer` | `dist/renderer` | `checksum-pinned-artifact-runtime` | Hydrated shipped UI; Settings Router patch only |
| `electron-main` | `dist/electron-main/main.cjs` | `clean-source` when `manifests/reconstruction/electron-main-production-bindings-manifest.json` validates; else `artifact-fallback` | `source/electron-main/main.ts` or hydrated `main.cjs` plus updater/dev seams |
| `host` | `dist/host/host-main.cjs` | `artifact-fallback` unless `GROK_BOT_HOST_BINDINGS_MANIFEST` binds every required slot into `source/` | `source/host/main.ts` or hydrated `host-main.cjs` |
| `node-agent-coordinator` | `dist/node-agent-coordinator/main.cjs` | `clean-source` | `source/node-agent-coordinator/main.ts` |
| `primary-preload` | `dist/electron-preload/preload.cjs` | `clean-source` | `source/electron-preload/runtime/primary.ts` |
| `dev-controls-preload` / `webview-preload` / `vnc-preload` | matching `preload-*.cjs` | `clean-source` | `source/electron-preload/runtime/` |
| `electron-dev-controls` | `dist/electron-dev-controls/main.cjs` | `clean-source` | `source/electron-dev-controls/main.ts` |
| Host workers | `agent-store-worker.cjs`, `transcript-mirror-worker.cjs`, `box-store-vacuum-worker.cjs`, `search-index-worker.cjs` | `clean-source` | matching `source/host/**` entries |
| `box-exec-daemon` | `dist/box-exec-daemon/main.cjs` | `clean-source` | `source/box-exec-daemon/cli.ts` |
| `local-exec-daemon` | `dist/local-exec-daemon/main.cjs` | `clean-source` | `source/local-exec-daemon/main.ts` |
| `electron-runtime-dependencies` | `dist/deps` | `artifact-runtime` | Unpacked 0.18.0 `app.asar.unpacked/dist/deps` |
| `native-runtime-tools` | `dist/native` | `artifact-runtime` | Unpacked 0.18.0 `dist/native` |
| `node-runtime-dependencies` | `dist/node-deps` | `generated-runtime` | Local Node ABI tree-sitter rebuild |
| `electron-shell` | `Contents/Frameworks/Electron Framework.framework` | `artifact-runtime` | Pinned 0.18.0 `.app` via `ditto` |

Clean overlays replace coordinator, daemons, preloads, workers, and `dist/node-deps`. Fidelity packaging **does not** overlay `dist/renderer` from `frontend/`. Artifact-fallback copies of recovered source land at `dist/recovered-source/electron-main/main.cjs` and `dist/recovered-source/host/host-main.cjs` only while those runtimes stay in fallback mode; a clean activation **removes** that recovered-source entry.

A separate source-aware path (`buildReconstructedAsar`) can classify the renderer as `clean-source` from `frontend/src/main.tsx`. `npm run package` does not use that path; `tests/publication-packaging.test.mjs` asserts the default packager imports `buildFidelityReconstructedAsar`.

## Ignored `src/app/dist` hydration

`npm run bootstrap` (`scripts/bootstrap-runtime.mjs`) is the only supported way to populate the compile input.

<ParamField body="GROK_BOT_018_APP" type="string">
Absolute path to an existing Grok Bot 0.18.0 `.app`. Takes precedence over cache and DMG.
</ParamField>

Resolution order:

1. `GROK_BOT_018_APP` → cache with `ditto` to `.cache/runtime/Grok Bot.app`
2. Existing `.cache/runtime/Grok Bot.app` if `CFBundleShortVersionString` is `0.18.0`
3. Git LFS DMG `research-archives/original/0.18.0/macos-arm64/Grok_Bot_0.18.0.dmg`
4. Public URL `https://downloads.cursor.com/grokbot/stable/darwin-arm64/0.18.0/Grok_Bot_0.18.0.dmg`

Required identities:

| Input | Expected SHA-256 |
| --- | --- |
| DMG | `a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb` |
| `Contents/Resources/app.asar` | `6665408168466f9cacc6087e917890c17f59d2e2e9c2404a5c4a59ad79c1de58` |

Hydration extracts the ASAR into a temp dir, requires these files, then replaces **only** `src/app/dist`:

- `dist/electron-main/main.cjs`
- `dist/host/host-main.cjs`
- `dist/renderer/index.html`

`.gitignore` lists `/src/app/dist/`. Do not commit hydrated payloads, `.cache/`, `.build/`, or `dist/`.

<RequestExample>
```sh title="Hydrate the pinned 0.18.0 payload"
git lfs pull
npm run bootstrap
```
</RequestExample>

<ResponseExample>
```text title="Expected bootstrap signal"
Runtime ready: …/.cache/runtime/Grok Bot.app
Checksum-pinned source payload ready: …/src/app/dist (<asar sha256>)
The checksum-pinned app supplies only the Electron shell, ABI-matched native dependencies, and explicitly documented build fallbacks.
```
</ResponseExample>

## Checksum-pinned renderer

The 0.18.0 ASAR shipped optimized production chunks, not authored frontend source or source maps. Packaged UI authority is that inventory, recorded as `dist/renderer-artifact-provenance.json` (`schemaVersion` 1, `mode` `checksum-pinned-artifact-runtime`, `upstreamAppAsarSha256` equal to the pinned ASAR digest, per-file SHA-256 list).

The only default UI transform is `applyOriginalRendererRouterPatch`:

- Finds exactly one Settings registry chunk and one panel chunk under staged `dist/renderer/assets/*.js`
- Inserts Settings tab `router` / label `Router`
- Records `dist/renderer-router-extension.json` (`mode` `original-renderer-settings-extension`, features `settings-router-provider`, `settings-local-docker-vm`, `usage-current-provider`)
- Stores original and patched byte counts and SHA-256 for those chunks

Evidence-only rule: recovered UI may express only behavior with an inspectable artifact anchor. Do not invent screens, routes, controls, or labels to fill gaps. `frontend/` is a readable Vite workspace and typecheck/build target; it is not the packaged renderer.

<ParamField body="GROK_BOT_RENDERER_SOURCE" type="string">
Optional path (resolved from the repo root) whose `index.html` replaces staged `dist/renderer` inside `buildAsar` **before** the fidelity overlay. Overlay still leaves the renderer as artifact-runtime, then the Settings patch runs. The override must still contain the original registry and panel anchors or packaging throws `Expected one original Settings registry and panel chunk`.
</ParamField>

## Reconstructed macOS identity

`scripts/package-macos.mjs` aborts unless `process.platform === "darwin"`. It `ditto`s the cached 0.18.0 app, clears quarantine with `xattr -cr`, swaps `app.asar` / `app.asar.unpacked`, then rewrites Info.plist.

| Key | Reconstructed value | Constraint |
| --- | --- | --- |
| `CFBundleIdentifier` | `com.anysphere.sand.reconstructed` | `npm run verify` fails on any other ID |
| `CFBundleDisplayName` | `Grok Bot 0.18 Reconstructed` | Fork display name |
| `CFBundleName` / `CFBundleExecutable` | `Grok Bot` | Electron helper names stay ABI-matched to 0.18 |
| `CFBundleURLTypes` | scheme `sand` only | Inherited aliases such as `grokbot` are removed |
| `ElectronAsarIntegrity` | removed | Stale official integrity metadata is a verify failure |
| Signature | ad-hoc, `--deep --strict` | Official Developer ID / notarization is not retained |
| Default output | `dist/Grok Bot 0.18 Reconstructed.app` | Override with `GROK_BOT_OUTPUT_APP_NAME` |

Packaging also proves the official reference (`verifyOfficialMacReference`) still hashes to the pinned shell and ASAR, then proves the reconstructed package **does not** copy that official `app.asar` or signed Mach-O shell.

Related identity constants in `scripts/lib/config.mjs`: `fidelityBundleId` `com.anysphere.sand.reconstructed.fidelity` (fidelity app) and diagnostic IDs `com.anysphere.sand.reconstructed.fidelity.diagnostic.build*`. Those are not the default package ID.

## Production bindings must resolve into `source/`

Clean host and Electron-main activation is fail-closed. Binding modules must live under reviewed `source/`. Forbidden roots:

- `src/app/`
- `recovered/source-capsules/`
- `dist/deps/`
- `.build/app/`

Overrides:

<ParamField body="GROK_BOT_ELECTRON_MAIN_BINDINGS_MANIFEST" type="string">
Binding manifest path. Default, when present: `manifests/reconstruction/electron-main-production-bindings-manifest.json`.
</ParamField>

<ParamField body="GROK_BOT_HOST_BINDINGS_MANIFEST" type="string">
Host binding manifest. Unset leaves host in `artifact-fallback` until every required slot binds and runner-turn evidence is `supported`.
</ParamField>

Packaged clean activations embed `dist/electron-main-production-bindings.json` / `dist/host-production-bindings.json` with status `validated-clean-source` and empty forbidden input/output graphs. `dist/runtime-composition-audit.json` must match `runtimeComposition` in `dist/reconstruction-build.json`. Clean runtimes must not reach immutable `src/app` evidence.

## Packaging-only safety seams

When Electron main stays on the hydrated artifact, packaging prepends a reconstructed updater guard (idempotent) and enables explicit runtime seams:

```js
process.env.SAND_DISABLE_UPDATES ??= "1";
process.env.SAND_DISABLE_SENTRY ??= "1";
process.env.SAND_DISABLE_TELEMETRY ??= "1";
```

`??=` keeps caller-supplied values. `GROK_BOT_RECONSTRUCTED_DEV=1` (and `GROK_BOT_BUILD_DEV_APP=1` for the dev product name / `sandLab`) can open packaged DevTools and skip the single-instance lock; those seams require exact upstream string anchors or the build throws.

## Commands and verification

```sh
npm run bootstrap   # hydrate ignored src/app/dist
npm run check       # frontend + source typecheck and tests
npm run package     # darwin-only fidelity hybrid app
npm run verify      # required ASAR entries, renderer inventory, bundle ID, codesign
```

`npm run verify` additionally requires at least 1,000 surviving `// src/` evidence markers in hydrated `electron-main` + `host` mains, forbids renderer `.map` files, and requires ASAR paths including `/dist/renderer/index.html`, `/dist/reconstruction-build.json`, and `/dist/runtime-composition-audit.json`. For `checksum-pinned-artifact-runtime`, every packaged `dist/renderer/**` file must match the embedded SHA-256 inventory except the hash-recorded Router patch chunks.

<AccordionGroup>
  <Accordion title="Common boundary failures">
    - Missing runtime: `Missing 0.18.0 runtime. Run npm run bootstrap first.`
    - Version mismatch on `GROK_BOT_018_APP`: `Expected Grok Bot 0.18.0`
    - DMG or `app.asar` digest mismatch (including LFS pointer-sized archives)
    - Hydration missing `dist/electron-main/main.cjs`, `dist/host/host-main.cjs`, or `dist/renderer/index.html`
    - `npm run package` on non-darwin
    - Settings patch anchors missing or duplicated after a renderer override
    - Verify: unexpected `CFBundleIdentifier`, leftover `ElectronAsarIntegrity`, missing `sand` URL scheme, official ASAR copied into the reconstructed app
  </Accordion>
</AccordionGroup>

## Next

<CardGroup>
  <Card title="Bootstrap the pinned runtime" href="/bootstrap-pinned-runtime">
    GROK_BOT_018_APP, cache, LFS DMG, public URL, and src/app/dist hydration checks.
  </Card>
  <Card title="Package the macOS app" href="/package-macos-app">
    Compile runtimes, patch Settings Router, replace app.asar, ad-hoc sign, verify.
  </Card>
  <Card title="Work on the frontend reconstruction" href="/edit-frontend-workspace">
    frontend/ is a Vite workspace; packaged UI stays the patched shipped renderer unless GROK_BOT_RENDERER_SOURCE is set.
  </Card>
  <Card title="Evidence and provenance" href="/evidence-and-provenance">
    Pinned DMG and app.asar identities, evidence-only UI rule, production bindings into source/.
  </Card>
</CardGroup>