RustBox/docs/UPSTREAM.md

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:

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:

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:

git init
git add .
git commit -m "RustBox 0.1.1 baseline"
./scripts/setup-upstream.sh

The script adds:

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

and fetches Oxi history/tags.

Inspect a newer Oxi state

./scripts/oxi-status.sh

or inspect a specific Oxi ref:

./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

./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:

./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:

./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:

./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.