Fork octopus as thin staging ground; upstream the EMBEDDING_DIM patch

Date: 2026-06-06 Status: Accepted Decision: hl-78b Deciders: Sean Brandt

Context

Octopus hard-codes VECTOR_SIZE=3072 in apps/web/lib/qdrant.ts, incompatible with bge-m3 (1024-dim). The cluster needs a deployable image immediately. Two structural paths exist: carry a permanent fork, or treat the fork as a temporary staging ground with an upstream PR as the exit condition.

Decision

Fork octopusreview/octopus → seanb4t/octopus, apply a minimal env-gated patch (EMBEDDING_DIM, default 3072; optional QDRANT_API_KEY; a migrator image stage + db:deploy running prisma migrate deploy), build ghcr.io/seanb4t/octopus multi-arch, and open an upstream PR. Revert the cluster Deployment to the upstream stock image once the PR merges.

Rationale

• The patch is intentionally upstream-mergeable: env-gated and backward-compatible (no behaviour change for users who do not set EMBEDDING_DIM), so upstream acceptance is likely.
• The existing cluster GHCR pull-secret (seanb4t account-scoped PAT, read:packages) covers ghcr.io/seanb4t/* with no new credential.
• The exit condition is explicit: on merge, the Deployment image reference switches to upstream and the fork becomes a read-only upstream-PR record — maintenance tax asymptotes to zero.

Alternatives Considered

• Permanent fork with a custom image — full control, no upstream dependency, but ongoing rebase cost per upstream release and growing divergence; defeats the minimal-change goal.
• Runtime patch via init-container / config-map overlay (no fork) — no fork to maintain, but patching a TypeScript constant compiled into the Next.js bundle is fragile and unsupported.

Consequences

• Positive: maintenance tax → zero after upstream merge; the PR benefits the broader Octopus self-hosting community (any non-OpenAI embedder needs the same configurable dimension).
• Negative: until merge, the cluster runs a fork image that must track upstream releases manually; the multi-arch (arm64) Next.js standalone build is an unvalidated path and the primary P1 go/no-go gate.
• Neutral: ADR hl-pvn (pin self-owned images by short-SHA/digest) applies — the Deployment image pin updates on each fork build.