Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
chore(gfs): keep internal rollout artifacts out of public PR
Alfredo Lopezf92d8e730c72
diff --git a/docs/architecture/gfs-upload-v2.md b/docs/architecture/gfs-upload-v2.mddeleted file mode 100644index a9fbd2aea..000000000--- a/docs/architecture/gfs-upload-v2.md+++ /dev/null@@ -1,235 +0,0 @@-# GFS Upload v2 architecture--Status: contract for the additive 200 MiB rollout. v2 remains disabled until-the T0–T3 gates in [the testing contract](../testing/gfs-upload-v2.md) pass.--## Decision--The packaged Desktop app and Control UI use a custom indexed resumable upload-protocol. A small metadata request creates a server-owned session; each binary-part is sent in its own authenticated request; the GFS writer stages parts on-the existing PVC and streams them in order into the immutable blob writer at-finalization.--This is deliberately not a one-request 200 MiB upload and is not a claim of-tus 1.0 compatibility. It does not raise the legacy JSON/base64 body limit.--| Contract | Frozen value |-| --------------------------- | --------------------------------------------------------------------------------------------: |-| Product maximum | `209715200` bytes (200 MiB binary) |-| Oversize boundary | `209715201` is rejected before session/payload allocation |-| Preferred part | `8388608` bytes (8 MiB) |-| Hard part/request maximum | `16777216` bytes (16 MiB) |-| Default session concurrency | 4 parts |-| Instability fallback | 2 parts after the advertised threshold (default 3) of consecutive retryable failures/timeouts |-| Legacy raw-file limit | `16777216` bytes (16 MiB), unchanged during rollout |-| Legacy GFSC body cap | `25165824` bytes (24 MiB), unchanged during rollout |-| Protocol arithmetic ceiling | `1073741824` bytes (1 GiB); not an enabled product value |--Cloudflare evaluates the body of each HTTP request. The aggregate file limit-is therefore independent of the request limit: every v2 data-bearing request-is at most 16 MiB, and the verified zone setting can force a lower negotiated-`maxChunkBytes`. No client may send a single 100 MB or 200 MiB body.--The capability response owns the instability threshold. It is an integer from-1 through 100; omitted legacy responses mean `3`. Both clients use the-advertised value when deciding when to reduce concurrency and reject a malformed-value rather than guessing. The retryable HTTP status allowlist is deliberately-finite and identical in Desktop and Control UI: `408`, `425`, `429`, `500`,-`502`, `503`, and `504`. `507 Insufficient Storage` and every other `5xx` are-terminal until an explicit server-side recovery/retry is requested. A server-may return `Retry-After`; clients honor it within their bounded retry budget.-For binary part writes only, a transport failure or `502/503/504` receives a-separate six-attempt service-recovery budget; ordinary lifecycle requests and-other retryable statuses retain the three-attempt budget. This covers a bounded-writer deployment restart without replaying a part blindly: each ambiguous-attempt still reconciles the durable status and checksum first.-The branch-owned Playwright gate can enable the negative journeys by setting-`GFS_UPLOAD_V2_NEGATIVE_E2E=1`; they remain opt-in because they mutate HCC,-restart the writer, and revoke only the seeded grant. The gate still requires-an explicit non-production context and profile-owned random URLs.--## Edge admission limits--Upload-v2 has a transport-abuse admission layer before Control API forwards a-body to GFSC. These budgets do not change the 200 MiB product/file limit, the-8 MiB preferred part, the 16 MiB hard part limit, or GFSC's upload-session-authority.--| Admission budget | Default | Authority |-| ------------------------------------ | ----------------------------------: | ------------------------------------------- |-| Public edge coarse requests | 120/minute per user + source-IP key | external-rest-api process-local fast reject |-| Requests per authenticated principal | 120/minute | Control API PostgreSQL fixed-window bucket |-| Requests per source IP | 600/minute | Control API PostgreSQL fixed-window bucket |-| Declared part bytes per principal | 512 MiB/minute | Control API PostgreSQL weighted bucket |-| Declared part bytes per source IP | 2048 MiB/minute | Control API PostgreSQL weighted bucket |-| Active relay requests per principal | 8 | Control API PostgreSQL advisory-lock slots |-| Active relay requests per source IP | 16 | Control API PostgreSQL advisory-lock slots |-| Active relay requests globally | 32 | Control API PostgreSQL advisory-lock slots |-| Part request maximum | 16777216 bytes | Both relays, then GFSC |-| GFSC part streams | 4/session, 16/global | GFSC session/stream authority |--Byte budgets are charged in fixed 1 MiB units, rounded up from the declared-`Content-Length`. A part requires matching decimal `Content-Length` and-`Upload-Chunk-Length` headers. Control API counts observed bytes while piping-the stream and rejects short, long, or over-limit bodies without buffering the-whole part. The authoritative PostgreSQL admission fails closed if its backend-is unavailable. A denied budget returns stable-`429 { error: "gfs_upload_rate_limited", limit, retryAfterSeconds }` plus-`Retry-After`; both relays preserve that contract.--The source-IP bucket is trusted only across the authenticated-`external-rest-api` service boundary. Control API ignores a client-supplied-`x-gfs-upload-source-ip` from any other caller and falls back to the socket or-trusted proxy address, so a valid internal token cannot rotate the IP key to-evade the per-IP budget.--## End-to-end shape--The PR-level architecture complement is available as an editable source plus-SVG/PNG exports. It separates the client, edge/authority, writer/persistence,-storage, and recovery paths so the Cloudflare per-request boundary and the-`outcome_unknown` reconciliation rule are visible without implying a single-200 MiB request:----- [Editable diagram source](diagrams/gfs-upload-v2-pr311.json)-- [SVG export](diagrams/gfs-upload-v2-pr311.svg)-- [PNG export](diagrams/gfs-upload-v2-pr311.png)--```text-Control UI / Desktop- -> authenticated capabilities + small JSON session create- -> indexed binary PUT parts (4 in flight, then 2 on instability)- -> UI/HTTP relays with backpressure and no whole-file buffering- -> gfsc writer- -> staged part files on <GFS root>/.uploads/<server-upload-uuid>/parts- -> ordered stream into immutable blob writer- -> resource + manifest + audit + completed receipt transaction-```--The browser renderer never receives a GFSC bearer token. Desktop main reads-one bounded part per request; file paths and metadata cross the preload bridge,-not a whole-file IPC value. Legacy agent/host JSON callers remain separate.--## Protocol surface--The public relays expose the same contract to the authenticated user:--- `GET /v1/capabilities` (`Cache-Control: no-store`);-- `POST /v1/uploads` with at most 64 KiB JSON metadata;-- `HEAD /v1/uploads/:uploadId` for the contiguous prefix;-- `GET /v1/uploads/:uploadId/status` for a bounded committed-part map,- including part number, offset, length, and SHA-256;-- `PUT /v1/uploads/:uploadId/parts/:partNumber` with raw- `application/offset+octet-stream` bytes;-- `POST /v1/uploads/:uploadId/pause` and `/resume`;-- `POST /v1/uploads/:uploadId/complete` with an empty or at most 16 KiB body;-- `DELETE /v1/uploads/:uploadId` as terminal cancel.--The writer selects one deterministic `partBytes` for a session. Part number,-offset, and length are derived from that geometry; parallel PUTs are-independently idempotent. A committed repeat with the same length and checksum-is successful without rewriting; a conflicting repeat is a stable conflict.-The database has unique `(upload_id, part_number)` and `(upload_id,-offset_bytes)` keys, so a scalar append offset can never masquerade as a-parallel protocol.--### Session state--`initiated → uploading ↔ paused → finalizing → completed` is the successful-path. `aborted`, `expired`, and `failed` are terminal. Pause drains reserved-parts before becoming `paused`; cancel advances `session_epoch`, aborts in-flight-streams, releases the reservation, and removes staging. Cancel is not resume.--`complete` first locks the session row and changes it to `finalizing`. DELETE-observing that state returns `409 upload_finalizing`; it does not report a-false cancellation. The publication transaction re-checks state and epoch-before writing the resource, so a canceled response can never accompany a-published resource.--Client progress is monotonic for stale `uploading` snapshots that arrive out-of order. A failed part retry is different: its in-flight contribution is-removed so the next aggregate may move downward to the truthful committed-plus in-flight value. Completion is the only state that may expose the exact-file size; the browser and Desktop tests cover both the stale-snapshot guard-and this failure correction.--## Persistence and safety--Desktop upload persistence is a version-2 envelope. Every resumable record is-bound to `ownerId`, team/tenant id, normalized environment key, normalized API-base URL, canonical drive, and local `authEpoch`; it stores no bearer or-session token. Pre-v2 unscoped arrays are quarantined as `legacy_unscoped` and-are never listed or resumed. Invalid/unsupported records are inert. A logout,-deliberate team switch, or runtime/API-base switch blocks new dispatch, advances-the epoch, aborts and awaits active v2 and legacy fallback work, clears-credentials, and persists the old records as local `suspended_auth`. A finite-internal team-context hop temporarily blocks only new GFS dispatches while it-borrows the other team's token; read-only listing/snapshot and controls for an-existing job remain available, existing uploads keep their captured token and-scope, and the original team scope is restored before the gate opens. A-deliberate switch fences the old uploads after the replacement session-succeeds; if that local fence cannot be persisted, the app fails closed by-clearing the replacement session and credentials rather than leaving an-ambiguous team/token pairing. Resume is user-explicit and succeeds only when-owner, team, environment, base URL, and drive match exactly; the new auth epoch-is bound only after the server session is revalidated.--The legacy compatibility fallback still accepts at most 16 MiB. It opens one-descriptor with no-follow semantics where available, validates the descriptor-with `fstat`, rejects symlinks/path swaps, reads that same descriptor with a-bounded loop, and rechecks its identity/size before encoding. It never performs-a pathname `stat` followed by a separate pathname `readFile`.--`gfs_upload_sessions` stores owner, operation/target, an immutable request-fingerprint, expected bytes, selected geometry, checksum, counters, state,-epochs, expiry, and the completion receipt. `gfs_upload_parts` stores only-part metadata, checksum, lease state, and a server-generated staging path; it-never stores the chunk bytes in Postgres. The writer role alone may mutate both-tables. `control_api_runtime`, `gfs_controller_reader`, and `PUBLIC` have no-table privileges on either relation: Control API is a streaming/auth relay,-not a second upload-session store client. Even `HEAD` is routed to the writer.--Before accepting a part the writer re-authorizes the current principal,-reserves the indexed part and a global/session stream slot, and validates the-declared and observed lengths. The stream is checksumed incrementally into a-server-generated path, fsynced, atomically renamed, then committed with the-matching `session_epoch` and `lease_epoch`. Disconnect, timeout, checksum, or-process failure removes only the uncommitted file and releases its lease.--Create idempotency compares owner, drive, operation, normalized target/name,-size, `ifMatch`, whole-file digest, and geometry. Reusing a key with any-different fingerprint returns `409 idempotency_conflict` without exposing the-old session. Finalization verifies complete ordered coverage, current auth and-replace preconditions, streams the staged parts, verifies byte count/digest,-and commits resource, manifest, audit, and receipt atomically.--Disk admission reserves remaining staging plus the full immutable destination;-active sessions, per-session parts, global streams, and finalizers are bounded.-Metrics and logs are low-cardinality and never contain file contents, names,-tokens, full paths, or upload IDs as labels.--## Rollout boundary--The public base owns the protocol, schema, relays, and generated-workload-inputs. Private infrastructure owns only explicit overlays and image pins.-`GFS_UPLOAD_V2_ENABLED=false` is the default and is the rollback switch. No-production enablement follows from this document. Any change to the protocol,-limits, state machine, ownership, or gates is an architecture/plan change and-requires a fresh GPT-5.6 Sol design review plus explicit user approval.--## Issue mapping--- **#282** — route-scoped metadata parsing and raw binary relay; do not raise- the global JSON parser cap.-- **#285** — resumable upload behavior, retry/resume, response-loss and- failure coverage; the indexed protocol replaces one-request streaming.-- **#286** — update the issue contract to describe resumable indexed parts, not- a single streaming request.-- **#300** — Desktop IPC/memory boundary: v2 uses disk-backed, bounded parts- and runtime capabilities instead of whole-file encoded content.--The live issue state and ownership are rechecked at PR0; this mapping is not a-substitute for current GitHub issue truth.diff --git a/docs/testing/gfs-upload-v2.md b/docs/testing/gfs-upload-v2.mddeleted file mode 100644index 5aace3009..000000000--- a/docs/testing/gfs-upload-v2.md+++ /dev/null@@ -1,157 +0,0 @@-# GFS Upload v2 testing contract--This document is the executable test contract for the 200 MiB GFS Upload v2-rollout. It is intentionally separate from the legacy small-file GFS suites.-The feature flag remains false until T0, T1, T2, and T3 are green.--## Test fixtures--Generate deterministic files in a run-unique temporary directory, not in the-repository and not in memory:--| Fixture | Exact size |-| ----------------- | ----------------------------------: |-| below boundary | `209715199` bytes |-| exact boundary | `209715200` bytes |-| oversize | `209715201` bytes |-| legacy regression | `16777216` bytes and one byte above |--Record SHA-256 for every fixture and verify the downloaded result matches the-source. A fixture may be sparse only when the target filesystem and the-checksum step prove the bytes; the default fixture is deterministic, ordinary-file data. No test uses `Buffer`, `arrayBuffer()`, base64, browser storage, or-an API shortcut for a whole file.--## T0 — static and unit--T0 must execute real tests and fail loudly if zero tests run. It covers:--- exact binary boundary and oversize rejection before session allocation;-- strict part geometry, min/max part sizes, zero-byte geometry, gap/overlap- rejection, checksums, indexed idempotent replay and fingerprint conflicts;-- owner isolation, current authorization, leases, expiry, pause/resume,- terminal cancel, finalization fencing, storage admission and bounded quotas;-- route recognition and writer selection for capabilities, `HEAD`, status,- part PUT, pause/resume, complete, and DELETE;-- no v2 whole-file `Buffer`/`ArrayBuffer`/base64/JSON/IPC value;-- retry classification, response-loss reconciliation, contiguous-vs-committed- progress, four-to-two fallback using the advertised instability threshold,- the identical finite retry-status allowlist (including terminal `507`), and- Desktop IPC byte isolation;-- proxy invariants: exact v2 prefix bypasses the broad JSON parser, declared- and observed 16 MiB caps are enforced, `Expect` is stripped, upload headers- survive, and disconnect aborts upstream.-- canonical-drive propagation for a non-`main` drive through capabilities,- create, HEAD, status, part, pause, resume, complete, and cancel; missing or- create-body-mismatched drive is rejected before GFSC token minting;-- replica-safe request limits, weighted 1 MiB byte charging, stable 429 plus- `Retry-After`, active principal/IP/global concurrency release, and fail-closed- admission-backend failure;-- Desktop state-v2 migration and legacy quarantine, exact owner/team/env/base/- drive resume matching, A → logout → B isolation, epoch-stale dispatch- rejection, and `suspended_auth` requiring explicit same-scope resume;-- active-part recovery after an unknown commit must decrement- `active_part_count` exactly once, including when the reconciliation read also- fails; the durable row state, not the transport outcome, is authoritative;-- legacy fallback symlink/path-swap rejection and proof that logout aborts and- awaits a pending fallback before clearing the captured credential.--The T0 red fixtures are contract tests: before the implementation seam exists,-they must be marked as planned/disabled in the test harness rather than hidden-behind a passing assertion. Once PR1/PR2 land, each fixture is enabled and a-zero-executed-test result is a failure.--## T1 — integration and real Postgres--T1 uses real Postgres for migration and role checks. It proves:--- additive migration order, exact writer-only session-table privileges, and- complete denial for `control_api_runtime`, the reader role, and `PUBLIC`;-- session/part uniqueness, offset geometry, idempotency, status map and- response-loss replay;-- restart recovery, orphan reconciliation, lease release, disk reservation,- bounded per-subject/global concurrency and finalization limits;-- external-rest-api → profile funnel → control-api → GFSC streaming with- backpressure, auth re-check, header/status preservation and no broad-parser- buffering;-- atomic resource/manifest/audit/session completion with no duplicate on crash- or replay, create-name race, replace `ifMatch` conflict, or checksum error;-- cancel-versus-part-commit and cancel-versus-finalize hold-before-commit- races. The latter must deterministically return `409 upload_finalizing` and- yield either one committed publication or a cleaned failure, never a- canceled response with a published resource;-- same name/size/mtime with different bytes cannot adopt a committed part or- complete a resumed session.--The dedicated real-Postgres lane is fail-loud: it must report at least one-executed test file and one passed test. A successful job with zero executed or-zero passed tests is a failure, not a skipped/green result.--The 512 MiB/1 GiB arithmetic ceiling is tested only under an explicit protocol-test configuration. It must not become an enabled 200 MiB product capability.--## Control UI and Desktop E2E Guardian gate--New large-upload projects must enter through real visible user actions (file-picker or drag/drop from the product surface), observe a visible intermediate-progress state at least twice before completion, and verify the final visible-state plus a business signal: resource identity/version and SHA-256. The tests-must use stable accessible labels or `data-testid` selectors, wait on critical-responses/state transitions, retain traces on failure, and clean up by-run-unique owner/session identifiers.--Required journeys:--1. create and replace at `209715199` and `209715200` bytes;-2. connection drop/timeout, writer restart, response loss, resume after app- restart, and exact committed-part adoption;-3. visible pause then resume, and separate terminal cancel with no resource;-4. retryable failures that show four parts in flight before the threshold and- no more than two afterward, with one correct progress bar;-5. oversize `209715201` rejection before any session/part/complete request;-6. permission revocation while paused, with visible denial and no publication;-7. v2-disabled legacy fallback at 16 MiB and rejection above the legacy cap;-8. foreign/missing session and direct terminal/deep-link guards never show- `Completed` without the server receipt.--The E2E Guardian adversarial gate must fail if an intermediate page disappears,-submit does nothing, the API succeeds but the UI does not transition, or a-direct terminal URL makes the happy path look complete. Do not use fixed-sleeps, direct terminal navigation in a happy path, storage/session mutation,-global core-route mocks, or `{ force: true }` to bypass the product journey.--## T2 — owned Minikube and Cloudflare-backed dev host--Before cluster work record worktree, branch, exact HEAD, `origin/dev`, profile,-explicit Kubernetes context, pre-gate marker, random profile-owned ports, and-active processes. Every `kubectl` invocation carries that context. Use four-subjects or a documented test-only quota override for concurrent maximum-size-uploads. Prove no OOMKill/restart/corruption, peak RSS below 80% of limits,-bounded finalization, expected disk growth, unrelated small-request latency-within baseline, and no more than four per-session/sixteen global part streams-unless capability negotiation advertises lower.--The browser and packaged Desktop journeys run through the Cloudflare-backed-dev hostname. A local green suite is not T2 evidence.--## T3 — packaged Desktop--Use the packaged Electron artifact, not only renderer tests. Select and-drag/drop exact-boundary arbitrary binary files (including `.parquet`), verify-responsive progress, pause/resume, terminal cancel, persisted resume after-restart, source-file mutation failure, no giant IPC message, bounded large-download-to-disk, and legacy fallback against a v2-disabled server.--## Static E2E audit and evidence--Before accepting new E2E files add `tools/e2e_static_audit.py` and run it on-changed specs. It rejects fixed sleeps, storage/session mutation, core-route-success mocks, fragile selectors, direct terminal happy paths, and missing-critical-response waits. Configure large-upload projects with-`trace: 'retain-on-failure'`; retries may not hide a failed journey.--Every gate records command, exact commit SHA, fixture size/hash, route and-hostname, pass/fail, executed/skipped counts, peak RSS, restarts, PVC free-space, and unresolved blockers. T0/T1 evidence must pass before commit/push/PR;-the exact-head `review-pr` audit must pass before T2. The review is read-only-and cannot be replaced by a green unit suite or a documentation screenshot.diff --git a/scripts/e2e/gfs-upload-v2-gate.sh b/scripts/e2e/gfs-upload-v2-gate.shdeleted file mode 100755index 769bd38b6..000000000--- a/scripts/e2e/gfs-upload-v2-gate.sh+++ /dev/null@@ -1,70 +0,0 @@-#!/usr/bin/env bash-set -euo pipefail--# GFS Upload v2 gate. This wrapper is intentionally opt-in: the large-upload-# journeys must run only against a branch-owned, non-production dev host with-# profile-scoped random URLs. It never treats a shell/API run as UI evidence.--repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"-cd "$repo_root"--: "${E2E_K8S_CONTEXT:?Set E2E_K8S_CONTEXT to the owned non-production context}"-: "${CONTROL_UI_BASE_URL:?Set CONTROL_UI_BASE_URL to the profile-owned random URL}"-: "${EXTERNAL_REST_API_BASE_URL:?Set EXTERNAL_REST_API_BASE_URL to the profile-owned random URL}"--case "$E2E_K8S_CONTEXT" in- *prod*|*production*)- echo "Refusing GFS Upload v2 E2E against production context: $E2E_K8S_CONTEXT" >&2- exit 2- ;;-esac--python3 tools/e2e_static_audit.py \- control-ui/e2e/gfs-upload-v2.spec.ts \- desktop-app/test/e2e-playwright/gfs-upload-v2.test.ts--run_ui="${GFS_UPLOAD_V2_RUN_UI:-0}"-run_desktop="${GFS_UPLOAD_V2_RUN_DESKTOP:-0}"-run_integration="${GFS_UPLOAD_V2_RUN_INTEGRATION:-0}"-# Negative journeys mutate HCC, restart the writer, and revoke only the seeded-# grant. Keep them explicit so a caller cannot turn an arbitrary context into-# a destructive default by selecting a UI lane alone.-run_negative="${GFS_UPLOAD_V2_NEGATIVE_E2E:-0}"--if [[ "$run_ui" == "1" ]]; then- GFS_UPLOAD_V2_E2E=1 GFS_UPLOAD_V2_NEGATIVE_E2E="$run_negative" npm --prefix control-ui exec playwright test \- --config=playwright.config.ts --project=large-upload e2e/gfs-upload-v2.spec.ts-fi--if [[ "$run_desktop" == "1" ]]; then- GFS_UPLOAD_V2_E2E=1 GFS_UPLOAD_V2_NEGATIVE_E2E="$run_negative" npm --prefix desktop-app exec playwright test \- --config=test/e2e-playwright/playwright.config.ts \- --project=packaged-gfs-upload-v2 test/e2e-playwright/gfs-upload-v2.test.ts-fi--if [[ "$run_integration" == "1" ]]; then- : "${CONTROL_API_REAL_PG_ADMIN_URL:?Set CONTROL_API_REAL_PG_ADMIN_URL for the real-Postgres integration lane}"- real_pg_log="$(mktemp)"- real_pg_normalized="$(mktemp)"- trap 'rm -f "$real_pg_log" "$real_pg_normalized"' EXIT- npm --prefix control-api test -- --run realPostgres 2>&1 | tee "$real_pg_log"- sed $'s/\033\\[[0-9;]*m//g' "$real_pg_log" >"$real_pg_normalized"- grep -Eq 'Test Files[[:space:]]+[1-9][0-9]* passed' "$real_pg_normalized" || {- echo 'real-Postgres E2E lane executed zero passing test files' >&2- exit 1- }- grep -Eq 'Tests[[:space:]]+[1-9][0-9]* passed' "$real_pg_normalized" || {- echo 'real-Postgres E2E lane executed zero passing tests' >&2- exit 1- }- # Runtime restart/chaos/load is caller-owned because it must be bound to the- # exact branch profile and Cloudflare-backed dev hostname. Do not silently- # substitute an older RED gate or report integration-only evidence as T2.- : "${GFS_UPLOAD_V2_RUNTIME_GATE_COMMAND:?Set GFS_UPLOAD_V2_RUNTIME_GATE_COMMAND to the exact-head restart/chaos/load command}"- bash -lc "$GFS_UPLOAD_V2_RUNTIME_GATE_COMMAND"-fi--if [[ "$run_ui$run_desktop$run_integration" == "000" ]]; then- echo "No runtime lane selected. Static audit passed; set one or more GFS_UPLOAD_V2_RUN_* flags." >&2- exit 2-fi