# Oxi upstream policy

RustBox is derived from `c0h1b4/oxi`. `UPSTREAM_BASE` contains the exact Oxi commit whose backend changes have been consumed by RustBox.

RustBox uses a flat Cargo layout, while Oxi uses a `backend/` subtree. The sync tooling therefore treats Oxi as a source upstream and maps its backend paths into RustBox rather than reintroducing the Oxi directory layout.

## Path mapping

Examples:

```text
Oxi backend/Cargo.toml          -> RustBox Cargo.toml
Oxi backend/Cargo.lock          -> RustBox Cargo.lock
Oxi backend/rust-toolchain.toml -> RustBox rust-toolchain.toml
Oxi backend/src/...             -> RustBox src/...
Oxi backend/migrations/...      -> RustBox migrations/...
Oxi backend/tests/...           -> RustBox tests/...
Oxi backend/examples/...        -> RustBox examples/...
Oxi backend/docs/...            -> RustBox docs/...
```

RustBox-owned `src/web/` has no automatic mapping from the Oxi frontend.

## Configure the upstream

A release archive does not contain `.git`. Initialize the RustBox repository once:

```bash
git init
git add .
git commit -m "RustBox 0.0.1 baseline"
./scripts/setup-upstream.sh
```

The script adds:

```text
upstream-oxi -> https://github.com/c0h1b4/oxi.git
```

and fetches Oxi history/tags.

## Inspect a newer Oxi state

```bash
./scripts/oxi-status.sh
```

or inspect a specific Oxi ref:

```bash
./scripts/oxi-status.sh upstream-oxi/main
./scripts/oxi-status.sh <tag-or-commit>
```

The report separates:

1. Oxi `backend/` changes that can be mapped into RustBox;
2. Oxi `frontend/` changes that require a manual UI port;
3. other Oxi root-level changes that require manual review;
4. upstream commits since `UPSTREAM_BASE`.

## Advance the consumed Oxi backend state

```bash
./scripts/sync-upstream.sh
```

The operation:

1. requires a clean RustBox Git worktree;
2. fetches `upstream-oxi`;
3. verifies that the target descends from the recorded `UPSTREAM_BASE`;
4. creates a `sync/oxi-*` review branch;
5. generates the Oxi backend delta from `UPSTREAM_BASE` to the target;
6. rewrites only patch metadata so `backend/<path>` becomes `<path>`;
7. applies the mapped delta with Git three-way merge support;
8. does not import Oxi frontend sources;
9. records the target as a pending sync inside Git metadata;
10. deliberately leaves `UPSTREAM_BASE` unchanged until the maintainer finishes review.

Conflicts are expected when Oxi and RustBox changed the same functionality. Resolve them in the flat RustBox paths, keeping RustBox-specific behavior where required.

After resolving backend conflicts and porting any relevant UI behavior, finish the sync:

```bash
./scripts/finish-upstream.sh
```

If Oxi changed its frontend or root-level files, the finish step refuses to advance the baseline until you explicitly acknowledge those reviews:

```bash
./scripts/finish-upstream.sh --ui-reviewed --root-reviewed
```

The finish step runs the RustBox release build gate and only then stages the new `UPSTREAM_BASE`. Review `git status` and commit the sync. `--skip-build` exists for exceptional local workflows, but CI should still run the full gate before merge.

If the sync is rejected, discard the review branch; the main branch and its `UPSTREAM_BASE` remain unchanged.

## Port one Oxi feature

For a useful Oxi commit that should be brought in before a full baseline update:

```bash
./scripts/oxi-port-commit.sh <oxi-commit>
```

This creates `port/oxi-<sha>` and maps only the backend portion of that single commit. It intentionally does not change `UPSTREAM_BASE`, because RustBox has not consumed the complete Oxi history up to that revision.

When a later full sync includes a previously ported feature, Git may report that some hunks are already present; review those conflicts instead of duplicating the code.

## UI policy

Oxi frontend source is never copied into RustBox. For a new Oxi feature that includes frontend work:

- consume or port the backend/API changes;
- inspect the corresponding Oxi frontend diff to understand behavior;
- implement that behavior in RustBox `src/web/`;
- keep the same-origin RustBox API/UI model;
- do not add `.ts` or `.tsx` sources.

## RustBox-owned boundaries

These areas require explicit review and should not be replaced blindly by upstream changes:

- `src/web/`;
- `src/ui.rs`;
- RustBox UI routing and same-origin behavior;
- RustBox ManageSieve integration;
- `dev.sh`;
- native packaging/release scripts;
- RustBox branding and documentation.

The goal is to keep following Oxi protocol/backend improvements without restoring its split frontend/backend repository structure.