# 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

Automatically mapped 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/examples/...        -> RustBox examples/...
Oxi backend/docs/...            -> RustBox docs/...
```

Review-only boundaries, never mapped automatically:

```text
Oxi backend/migrations/...      -> review against RustBox migrations/...
Oxi backend/tests/...           -> review/port as native Rust tests when useful
```

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.1.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 automatically;
2. Oxi backend migrations/tests that require manual review;
3. Oxi frontend changes that require a manual UI port;
4. other Oxi root-level changes that require manual review;
5. 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, excluding `backend/migrations/` and `backend/tests/`;
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, migrations, or tests;
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, root-level files, or the RustBox-owned upstream migration/test areas, the finish step refuses to advance the baseline until those reviews are explicitly acknowledged:

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

`--rustbox-owned-reviewed` confirms that changes under Oxi `backend/migrations/` and `backend/tests/` were inspected and any relevant behavior was manually ported. Those files are never copied into RustBox automatically.

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:

- `migrations/` (RustBox owns the squashed baseline and future migration numbering);
- `tests/` (RustBox keeps native Rust/runtime fixtures rather than importing upstream Python contracts);
- `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.