Turn document • 2026-05-19 18:56 ET

# Reconcile PR Conflicts

Merged `forgejo/main` into `nextjs-upgrade`, resolved the checked-in Beads and README conflicts, kept the native deployment work from main, and updated the JetStream tests for the merged nanosecond retention behavior.

## Summary

The PR branch now incorporates the current mainline deployment changes while preserving the Next.js upgrade branch. The only hand-edited conflict resolution was in `.beads/issues.jsonl` and `README.md`; the rest of the mainline merge applied cleanly.

## Changes Made

- Resolved `.beads/issues.jsonl` by keeping issue records from both sides of the merge.
- Resolved the README deployment workflow section by combining the branch’s command-oriented guidance with main’s newer worker-only, local-server, and native edge cutover notes.
- Accepted mainline native deployment assets, Docker deployment refinements, API host binding support, deploy timing output, and worker-only deployment scope.
- Adjusted `packages/bus/tests/jetstream.test.ts` so retention assertions expect NATS nanoseconds after the merged runtime change.

## Context

The branch was clean before the merge, but Forgejo reported PR conflicts against `main`. Reproducing the merge locally showed conflicts in the Beads export file and the README deployment section. The automatic merge also brought in mainline native deployment work that touched deploy scripts, Docker deployment files, native systemd templates, public edge documentation, the API host setting, and JetStream retention units.

## Important Implementation Details

README resolution

Kept Docker as the recommended VPS path, preserved explicit deploy commands, and added `--workers-only`, local server execution, and native worker iteration guidance.

Beads resolution

Removed conflict markers without dropping either branch’s issue records, so Beads history remains complete.

Test repair

Main now stores JetStream `max_age` in nanoseconds via NATS helpers. Tests now assert against `nanos(...)` instead of raw millisecond values.

## Relevant Diff Snippets

Diff snippets are presented in the style of diffs.com, using structured additions and deletions for quick review.

    diff --git a/README.md b/README.md
    - Partial deploys are supported with `--web-only`, `--api-only`, `--services-only`, `--fast`, `--no-build`, and `--force-recreate`.
    + Partial deploys are supported with `--web-only`, `--api-only`, `--services-only`, `--workers-only`, `--fast`, `--no-build`, and `--force-recreate`.
    + When run from `/home/delta/islandflow` on the VPS itself, `./deploy` can execute locally instead of SSHing back into the same server.
    - Native deployment expects Bun, systemd units, host-reachable infra, and deliberate reverse-proxy changes. The open follow-up is to add native unit templates and rollback helpers.
    + Native deployment expects Bun, systemd units, host-reachable infra, and deliberate reverse-proxy changes. Native deploys are intended primarily for worker-only fast iteration until the public edge is cut over deliberately.

    diff --git a/packages/bus/tests/jetstream.test.ts b/packages/bus/tests/jetstream.test.ts
    - import type { JetStreamManager, StreamConfig } from "nats";
    + import { nanos, type JetStreamManager, type StreamConfig } from "nats";
    -       max_age: 3_600_000,
    +       max_age: nanos(3_600_000),
    -       max_age: 43_200_000,
    +       max_age: nanos(43_200_000),

## Expected Impact for End-Users

The PR should no longer show merge conflicts against main. Users and operators get the Next.js upgrade branch plus the newer deployment safety work from main, including worker-only native deploy guidance and current Docker deployment notes.

## Validation

- `git diff --check` passed.
- `bun run scripts/deploy.ts --help` passed.
- `bun run check:docker-workspace` passed.
- `bun test services/api/tests packages/bus/tests` passed with 45 tests.
- `bun --cwd=apps/web run build` passed on Next.js 16.2.6.

## Issues, Limitations, and Mitigations

The first focused test run failed because the merged JetStream implementation correctly returned nanosecond retention values while the existing tests still expected milliseconds. The tests were updated to use the same NATS `nanos` helper as the runtime behavior, then the suite passed.

## Follow-up Work

- No new follow-up was created from this reconciliation.
- Existing deployment follow-ups remain in Beads, including native public edge posture and cutover decisions.