> **Scope Rule**: Maintain this file accurately across VS Code, Google Antigravity, Cursor, and any other IDE after every modification, feature update, or bug fix (see `.ai-rules` and `AGENTS.md`).
- **Partitioned CSV Storage (`/storage/data/{clientId}/{YYYY-MM-DD}.csv`)**: All ingested telemetry events flush in batches to daily partitioned CSV files with cooperative file locking, configurable size rotation (`fileRotationMb`, e.g., `-part2.csv`), and retention pruning (`autoPruneDays`).
- **Redis (`ioredis`)**: Shared cross-process buffer queue (`datastack:buffer:events`), recent event cache (`datastack:recent:events`), and distributed flush lock (`datastack:flush:lock`). Persisted in Docker via `--appendonly yes` (`redisdata:/data`). Falls back gracefully to local RAM when `REDIS_URL` is omitted.
- **Persistence & Caching**: `pg``8.23.1` (PostgreSQL 16 in Docker), `ioredis``6.0.0` (Redis 7 AOF in Docker), `csv-parse``7.0.3`, `json2csv``6.0.0-alpha.2`.
- **Auth & Security**: `jsonwebtoken``9.0.3`, Node `crypto.scrypt` password hashing, WebCrypto HMAC-SHA256 admin session cookies (`middleware.ts`), CSRF `Origin`/`Referer` vs `Host`/`X-Forwarded-Host` checks, `DATASTACK_INTERNAL_SECRET` timing-safe bridge auth between Port `3000` ↔ `4000`.
- **Client SDKs**: Official pip-installable Python SDK in `sdk/python/datastack/` (`datastack`) + backward-compatible wrapper `sdk-python/` (`datastack-sdk`).
### Environment & Setup Commands
1.**Configure Environment**: Copy `.env.example` to `.env` (in production `NODE_ENV=production`, all 4 secrets MUST be 32+ chars: `DATASTACK_ADMIN_SESSION_SECRET`, `DATASTACK_JWT_SECRET`, `DATASTACK_ADMIN_SETUP_KEY`, `DATASTACK_INTERNAL_SECRET`; optional `DATABASE_URL` and `REDIS_URL`).
- Supports single events (`send()`/`sync()`), auto-splitting/rate-limit-paced batches (`send_batch()`/`batch_sync()`), and direct file ingestion (`send_file()` for `.csv`, `.json`, `.jsonl`, `.ndjson` with SHA-256 deterministic `eventId`).
- Prevented transient DB errors from triggering false `/vcon/setup` redirects and prevented swallowed `NEXT_REDIRECT` errors on `/`, `/vcon/login`, and `/vcon/setup`.
- Standardized `SDKManager.normalizeClientId`, blocked deleted/unregistered clients on `/api/health` and Admin `POST /api/events`, hardened `POST /api/clients` & `PATCH /api/clients/[id]` input validation, and excluded `/vcon/*` from Service Worker caching with `CLEAR_AUTH_CACHE` on sign-out.
- Enforced fail-closed client verification in `server/index.js` (`verifyClientInDb`) backed by PG, deletion tombstones, Redis `datastack:clients:*` mirrors, and normalized `clientId` keys across both runtimes.
- Added cross-runtime Redis idempotency (`datastack:idem:*`) and fixed-window rate limiting (`datastack:rl:*`) in `core/Security/security.ts` (`validateEventAsync`) and `server/socket/handlers.js` (`validateSingleEventAsync`) with automatic local RAM fallback.
- Fixed Socket `sync_data` flat payload preservation (`extractSingleEventData`), reconciled `PORT_SOCKET`/`PORT` precedence and live `/internal/metrics` ports, and added concurrent production `scripts/start-all.js` for `npm start`.
- Extracted pure UI synchronization helpers in `lib/vconUiHelpers.ts` (`SETTINGS_LIMITS`, `normalizeEditableSettings`, `describeSettingsBridgeSync`, `mapBridgeStatusToSocketUiState`, `parseEventTimestamp`, `formatEventTimeLabel`, `getUtcDateRangeForPreset`, `matchesSelectedClientFolder`, `extractContentDispositionFilename`).
- Updated `components/sections/SettingsWorkspace.tsx` (`BUG-D01`) to probe `/api/metrics` honestly (removing false `/api/health` fallback), surface `bridgeSync` warning/error toasts on save, align integer bounds with `/api/settings` (`1..100000`, `1..10240`, `0..3650`), and eliminate the startup `serverPort` double-fetch.
- Updated `app/vcon/storage/page.tsx` (`BUG-D02`) and `components/sections/ExportWorkspace.tsx` (`BUG-D03`) with `cache: 'no-store'`, `401` redirects, UTC preset ranges, normalized client folder filters, and fetch+Blob downloads with `502`/JSON error surfacing.
- Updated `components/sections/DashboardOverview.tsx` (`BUG-D04`) and `components/sections/DataBrowser.tsx` (`BUG-D05`) with `ingestionBridgeStatus` display, `auth_error` alert banner, safe ISO/epoch-ms timestamp formatting, invalid date-range guard, and Enter-key filter submission.
- Updated `components/sections/NewClientModal.tsx`, `components/sections/ClientsTable.tsx`, `app/vcon/simulator/page.tsx`, `app/vcon/sdk/page.tsx`, `components/sections/ProfileWorkspace.tsx`, and `components/layout/Sidebar.tsx` (`BUG-D06`, `BUG-D07`) with `1..100000` rate limit parity, live `runtime.serverPort` sync, real HTTP batch ingestion in Simulator, password bounds check, and `datastack:profile-updated` live Sidebar sync.
- Verified: `37/37` TS tests (`tests/phase04-ui-sync.test.ts`), `3/3` Python tests, `npm run build` clean, `eslint .` clean, Playwright browser check across all Admin Console routes clean with `0` console errors.
- Hardened canonical Python SDK (`sdk/python/datastack/datastack/*`): normalized `CLIENT_ID` comparison (`_normalize_client_id`), sanitized ragged CSV extra columns (`restkey="_extra"`), accurate `send_file()``success` + `unprocessedItems`, partial-batch `rateLimitedEventIds` retry exception fallback, `DataStackConfigError` wrapping for malformed numeric env/config values (`config.py`), concurrent `stop()` vs `set_idle_connected()` race fix + clean thread join (`heartbeat.py`), `os.fsync` + orphan `.tmp` unlink + warning logs (`spool.py`), and PEP 561 `py.typed` marker.
- Aligned packaging metadata across `sdk/python/datastack/pyproject.toml`, `sdk/python/datastack/setup.py`, and `sdk-python/setup.py`, coordinated child-exit shutdown in `scripts/start-all.js`, and added `engines.node >=20.0.0` in `package.json`.
- Verified: `39/39` TS tests (`tests/phase05-packaging.test.ts`), `6/6` Python tests (`tests/phase05_sdk_test.py`), `py_compile`, `npm run build`, and `eslint .` clean.
- Blocked volatile RAM admin creation in production without `DATABASE_URL` (`AdminDatabaseRequiredError`), surfaced production DB warning on `/vcon/setup`, and mapped pre-setup login to `409 SETUP_REQUIRED`.
- Added brute-force attempt throttling (`429` + `Retry-After`) and completion-first ordering to `POST /api/auth/setup`.
- Added server-side `token_version` revocation (`revokeAdminSessions()`) on `POST /api/auth/logout`, removed client `Origin` trust from cookie `Secure` flag, and added `sec-fetch-site: same-origin` CSRF fallback.
- Prevented empty production `jwt_secret` persistence in PG and replaced silent DB write `catch {}` swallows in `SettingsManager` and `SDKManager` with `DATABASE_WRITE_FAILED` propagation and safe RAM rollback.
- Verified: `43/43` TS tests, `6/6` Python tests, `npm run build`, `eslint .`, and Playwright login/logout revocation check clean.
- Protected Port 4000's `inMemoryClientRegistry` from empty Port 3000 `bulk_sync` wipes (`!forceReplace`), exposed `inMemoryClients` on `/internal/metrics`, added non-destructive hydration in `SDKManager` (`listClientsAsync`, `getClientAsync`, `syncAllClientsToIngestionAsync`), and auto-reconciled Port 4000 cold starts in `ApiEngine.getDashboardMetrics()`.
- Ordered `SettingsManager.updateSettingsAsync()` JWT rotation to sync Port 4000 *before* committing Port 3000 RAM/PG/re-sign, aborting fail-closed (`JWT_ROTATION_BRIDGE_FAILED`) on bridge rejection/prod unreachable, rolling back Port 4000 on PG/re-sign error, and adding a 60s dual-secret grace window in `server/index.js``requireInternalAuth()`.
- Added authenticated `POST /internal/security-check` on Port 4000 (backed by zero-copy `validateSingleEventLocal`) so Port 3000 HTTP `SecurityEngine.validateEventAsync()` shares rate limits & idempotency with Port 4000 WS even without Redis, and exposed explicit `securityMode` (`redis_shared` | `bridge_coordinated` | `degraded_local`) in `/api/metrics`.
- Replaced per-event PG `UPDATE client_sdks` queries on both Port 3000 (`SDKManager`) and Port 4000 (`server/index.js`) with 1s coalescing in-memory deltas flushed via batched `UNNEST` SQL updates (flushed on reads and graceful shutdown).
- Verified: `47/47` TS tests, `6/6` Python tests, `npm run build`, and `eslint .` clean.
- Added bounded Redis flush lock wait/retry, periodic Lua `PEXPIRE` TTL renewal with ownership fencing before `LTRIM`, and explicit `FLUSH_LOCK_TIMEOUT` (`503` on `/internal/flush`) across both `core/data/buffer.ts` and `server/index.js`.
- Added full deleted-client buffer purge (`DataBufferEngine.purgeClientEventsAsync`, Port 4000 `purgeClientFromLocalBuffer`) plus flush-time and recent-read tombstone filtering so deleted client directories never resurrect on subsequent flushes; ordered `SDKManager.deleteClientAsync()` to purge buffers and sync Port 4000 before deleting disk files.
- Converted `server/index.js``onBufferPush` to `async` and awaited it before firing Socket.IO ACK callbacks in `server/socket/handlers.js` (`sync_data` and `batch_sync`), returning `BUFFER_PERSIST_FAILED` on persistence error.
- Unified canonical CSV storage root resolution via `DATASTACK_STORAGE_DIR` (`resolveDefaultStorageDir()`) across `core/Storage/csvStorage.ts`, `server/workers/csvWriter.js`, `core/sdk/sdkManager.ts`, and `.env.example`.
- Verified: `51/51` TS tests, `6/6` Python tests, `npm run build`, and `eslint .` clean.
- Aligned HTTP `POST /api/events` single-event envelope stripping 1:1 with Port 4000 WS `sync_data` and eliminated fabricated `{ sample, rand }` telemetry on empty `{}`.
- Converted `GET /api/data` directory/stat scans to non-blocking async `node:fs/promises` with newest-first date-partition pruning, and scaled `REDIS_RECENT_LIMIT` boundedly (`500..5000`) via `resolveRedisRecentLimit()` / `DATASTACK_RECENT_LIMIT` across Port 3000 & Port 4000.
- Replaced all `Math.random()` client secrets (`crypto.randomBytes(16)`) and fallback `eventId`s (`crypto.randomBytes(6)`) with CSPRNG across `core/sdk/sdkManager.ts`, `app/api/events/route.ts`, and `server/socket/handlers.js`.
- Unified canonical PostgreSQL metadata DDL (`CORE_SCHEMA_TABLE_DDLS` + `CORE_SCHEMA_ALTER_DDLS` + `ensureCoreSchemaOnPool()`) in `core/Database/database.ts`, delegated `core/auth/adminUsers.ts` to it, mirrored all 5 tables + 3 additive `ALTER TABLE` guards 1:1 in standalone `server/index.js`, and documented canonical `pg` ownership in `prisma/schema.prisma`.
- Verified: `55/55` TS tests (`tests/phase04-ingestion-hygiene.test.ts` added), `6/6` Python tests, `npm run build`, and `eslint .` clean.
- Fixed Simulator HTTP `Burst 10` to send canonical `{ clientId, batch }` (with `events` batch alias & explicit `accepted` count in `POST /api/events`) and summarize exact server-confirmed counts via `summarizeHttpBatchResult()` without `res.ok ? count : 0` falsification.
- Fixed `parseEventTimestamp()` & added `getEventUtcDate()` in `lib/vconUiHelpers.ts` for integer and fractional epoch-seconds (`< 1e11 * 1000`) 1:1 with backend CSV parsers.
- Added pending-queue-only `getPendingBufferedSummary()` (`?bufferedOnly=true` / `?includeBufferedSummary=true`) and fair multi-client partition scanning (`selectRecentPartitionFiles()`, lifting the global 5-file cap) in `GET /api/events`.
- Updated `ExportWorkspace.tsx` to match buffered events strictly against active client/date filters via `countMatchingBufferedEvents()` (preventing empty filtered header downloads) and refresh `/api/storage`, `/api/metrics`, and `vconCache` immediately post-export; updated `DashboardOverview.tsx` to attribute strictly UTC-today buffered events to `Events today` and call `await refresh()` after Quick Export.
- Returned explicit `SESSION_EXPIRED` / `AUTH_UNAVAILABLE` vs `INVALID_PASSWORD` codes in `/api/auth/profile`, replaced dead `401 && !currentPassword` redirect with `shouldRedirectProfileUnauthorized()`, and formatted `Session Expires` with calendar date + 24h time (`formatSessionExpiryLabel()`).
- Added opt-in `?purgeFiles=true` checkbox in `ClientsTable.tsx` client deletion modal and removed the misleading unused `Secret key` row from `CredentialsDisplay`.
- Refactored `SettingsWorkspace.tsx` numeric inputs to string drafts (`NumericSettingDrafts`) validated inline via `validateEditableSettingsDraft()` (`noValidate` submit + tab jump to first invalid field, zero snap-to-`0`, zero silent clamping) and clarified `Socket port (PORT_SOCKET)` as read-only runtime config.
- Unified public endpoint resolution (`resolvePublicEndpoints()`) across `SettingsWorkspace`, `/vcon/sdk`, and `/vcon/simulator` (consistent on port-80 `localhost` proxies) and updated `SdkSection.tsx` + `/vcon/sdk` with external path/wheel `pip install` guidance.
- Added pre-hydration `datastack-theme` bootstrap script + `suppressHydrationWarning` in `app/layout.tsx` (zero light-mode FOUC) and theme restoration/toggle in `AdminSetup.tsx`.
- Upgraded `public/sw.js` (`datastack-cache-v3`) with an uncached `503` HTML offline navigation fallback shell (`buildOfflineShellResponse()`, `Cache-Control: no-store`) for `/vcon/dashboard` and public navigations.
- Frozen baseline (`BASELINE-2026-11-19-R2`) and created the complete 7-document governance & Scope-Lock suite in `notes/` (`README.md`, `BASELINE_FREEZE.md`, `PRODUCTION_READINESS_SCOPE_LOCK.md`, `PRODUCTION_ROADMAP.md`, `PHASE_EXECUTION_LOG.md`, `ERROR_HANDLING_MATRIX.md`, `ACTUAL_IMPLEMENTATION_STATUS.md`).
- Moved same-origin CSRF enforcement in `middleware.ts` ahead of the public-route early return so `POST /api/auth/login` and `POST /api/auth/setup` reject cross-origin/missing-origin requests with `403` while preserving same-origin browser submissions, `sec-fetch-site: same-origin` fallback, safe `GET` routes, and Bearer `POST /api/events`.
- Extracted shared reverse-proxy-safe `extractClientIp()` in `lib/adminAuth.ts` (trusting `x-real-ip` first, then rightmost non-empty `x-forwarded-for` hop) and wired it into both `app/api/auth/login/route.ts` and `app/api/auth/setup/route.ts` to block spoofed-XFF brute-force lockout bypasses.
- Verified: `14/14``tests/phase01-auth.test.ts` pass, `npm run build`, `npm run lint`, live HTTP `403`/`401` CSRF probes, and Chromium `/vcon/login` → `/vcon/dashboard` E2E (`0` errors).
- Attached `.on('error', ...)` listeners to `DatabaseEngine.getPool()` (`max: 10`) and `server/index.js``dbPool`, and consolidated `core/auth/adminUsers.ts` onto the shared `DatabaseEngine.getPool()`.
- Replaced non-atomic Redis `LTRIM`+`LPUSH` client deletion purging in `core/data/buffer.ts` with atomic Lua script `PURGE_CLIENT_LIST_LUA_SCRIPT` (`cjson.decode` + chunked `RPUSH`), and replaced non-atomic Redis `INCR`+`PEXPIRE` rate limiting with atomic Lua script `REDIS_RATE_LIMIT_LUA_SCRIPT` across both `core/Security/security.ts` and `server/socket/handlers.js`.
- Enforced `throwOnLockTimeout: true` locally and remotely on `POST /internal/flush` in `GET /api/export` and `POST /api/storage`, surfacing explicit `503 FLUSH_LOCK_TIMEOUT`.
- Added `DataBufferEngine.registerShutdownHook()` and registered `SDKManager.flushPendingClientActivityAsync()` so Port `3000` flushes coalesced `total_events` deltas on `SIGTERM`/`SIGINT`.
- Wrapped `GET`, `PATCH` (`regenerate_token` & update), and `DELETE` in `app/api/clients/[id]/route.ts` with structured JSON `try/catch` error responses.
- Verified: `14/14``tests/phase02-sync.test.ts` pass, `3/3``R2 PHASE-02` buffer/storage tests pass, `npm run build` pass, `npm run lint` pass (`0` errors).
- Unified `SettingsBridgeSyncStatus` & `POST /api/settings``bridgeSync` response (`attempted`, `ok`, `synced`, `status`, `error`, `checkedAt`) and updated `describeSettingsBridgeSync()` + `SettingsWorkspace.tsx` so Port `4000` warnings/online state work reliably.
- Counted regular non-symlink `.csv` files in `SDKManager.purgeClientStorageDir()` (`deleteClientWithStatsAsync()`) and returned exact `purgedFiles` from `DELETE /api/clients/[id]?purgeFiles=true`.
- Aligned flat batch item metadata stripping (`eventId`, `timestamp`, `clientId`) 1:1 with single-event stripping across HTTP `POST /api/events`, WS `batch_sync`, and Python SDK `send_batch()`/`send_file()`.
- Exposed `DataBufferEngine.getLocalBufferSnapshot()` for exact Port `3000` RAM pending summary in `getPendingBufferedSummary()`.
- Added non-blocking `pruneExpiredPartitionsAsync()` off live event loops in `core/Storage/csvStorage.ts` & `server/workers/csvWriter.js` (wired into `settingsManager.ts` & `server/index.js`) and deduplicated `GET /api/storage` to a single `listAllFilesAsync()` scan with accurate client-scoped `stats`.
- Cleared `selectedClientToken` on `/vcon/sdk` client switch (with loading placeholder + disabled `Copy Config`), added `400 INVALID_DATE_RANGE` for `from > to` in `GET /api/export`, and normalized `clientId` filtering in `ApiEngine.getExportFiles*` & Port `4000``/internal/recent`.
- Added `from __future__ import annotations`, imported `Tuple`, and replaced PEP 585 `tuple[int, Dict[str, Any]]` with Python `3.8`-safe `Tuple[int, Dict[str, Any]]` in `sdk/python/datastack/datastack/client.py`, verified by a full-package Python `3.8` AST scan test in `tests/phase05_sdk_test.py`.
- Added unbuffered streaming `location = /api/export` (`proxy_buffering off;`, `proxy_read_timeout 300s;`) targeting `http://nextjs_upstream` in both `nginx/default.conf` and `docker/coolify-nginx.conf`.
- Removed `eslint: { ignoreDuringBuilds: true }` from `next.config.ts`, set `package.json``"name": "datastack"`, pruned unused template packages (`@google/genai`, `firebase-tools`), and synchronized `package-lock.json`.
- Isolated `DATASTACK_DISABLE_LISTEN=1` and live Port `4000` coupling across `tests/phase01-auth.test.ts`, `tests/phase02-sync.test.ts`, `tests/phase03-storage-buffer.test.ts`, `tests/phase04-ingestion-hygiene.test.ts`, and `tests/phase07-deployment.test.ts`.
- Verified: `83/83` full TS suite pass (with live Port `4000` running, without manual env flags), `10/10` Python SDK tests + `py_compile` pass, `npm run build` (with ESLint active) pass, `npm run lint` (`0` errors, `0` warnings).
- **`DEPLOY-BUG-01`**: Replaced static `upstream` blocks in `docker/coolify-nginx.conf` with Docker embedded DNS `resolver 127.0.0.11 valid=10s ipv6=off;` and variable `proxy_pass` targets (`$nextjs_upstream` = `http://web:3000`, `$socketio_upstream` = `http://ingestion:4000`), preventing `502 Bad Gateway` stale container IP outages after container restarts/redeploys.
- **`DEPLOY-BUG-02`**: Refactored Port `4000` startup in `server/index.js` into `startIngestionServer()` awaiting bounded `syncSettingsFromDatabase()` before `server.listen(PORT)` so rotated PG `jwt_secret` and rate-limit settings hydrate prior to `/health: 200` and `/internal/*` bridge traffic.
- **`DEPLOY-BUG-03`**: Memoized `ensureDatabaseSchema()` per active `dbPool` instance in `server/index.js` (resetting only on pool swap or DDL failure) so 3-second `syncSettingsFromDatabase()` ticks no longer issue 8 `CREATE/ALTER TABLE` DDLs repeatedly.
- **`DEPLOY-BUG-04`**: Reordered `gracefulShutdown()` in `server/index.js` to close Socket.IO/HTTP ingress first (`closeServerGracefully()`), drain `pendingRedisWrites` and `flushBuffer()`/`flushPendingClientActivity()` with bounded timeouts (`2000ms`/`6000ms`), and close Redis (`quit()` with `2000ms` timeout + `.disconnect()` fallback) and PostgreSQL (`dbPool.end()` bounded `2000ms`); added `stop_grace_period: 20s` to both `web` and `ingestion` in `docker/docker-compose.yml`.
- **`DEPLOY-BUG-05`**: Clarified Coolify `Base Directory: /` and `Docker Compose Location: /docker/docker-compose.yml` in `docs/users/installation.md` and `README.md`.
- Verified: `85/85` full TS suite pass (`11/11` in `tests/phase07-deployment.test.ts`), `10/10` Python SDK tests pass, `npm run build` clean, `npm run lint` (`0` errors, `0` warnings).
- **AES-256-GCM Secret Vault (`core/Security/secretVault.ts`)**: Deterministic HKDF-SHA256 key derivation (`encryptSecret`, `decryptSecret`, `getMaskedHintFromEncrypted`, `SecretVaultError`) so `s3_secret_access_key_enc` is encrypted at rest in PostgreSQL and never leaked in plaintext by `GET /api/settings` (`hasS3SecretKey` + `s3SecretKeyMask: "••••xxxx"`).
- **S3 / Cloudflare R2 / MinIO SigV4 Client (`core/Storage/s3Archive.ts`)**: Pure Node `node:crypto` + `fetch` AWS Signature v4 client (`testS3Connection`, `uploadFileToS3`, `buildS3ObjectKey`, `normalizeS3EndpointUrl`) with `POST /api/storage/s3-test` and `POST /api/storage/archive`.
- **Transparent `.csv.gz` Auto-Compression & Safe Archive-Before-Prune (`core/Storage/csvStorage.ts`, `server/workers/csvWriter.js`)**: Cooperatively locked atomic `.csv` → `.csv.gz` compression (`compressOldPartitionsAsync` / `compressOldPartitions`) excluding today's active UTC partition; transparent `.csv` + `.csv.gz` reading/streaming across `GET /api/data` (surfacing `500 Corrupt .csv.gz partition` on corrupt gzip — `V2-E03`), `GET /api/events`, and `GET /api/export` (`application/gzip` for raw single `.csv.gz` download); fail-safe `beforeDeleteFile` S3 upload hook (`V2-E02`) that never deletes local partitions if S3 upload fails (`502 S3_ARCHIVE_FAILED`).
- **Per-Client Storage Quota (`storageQuotaMb`) & VPS Disk Pause Guard (`diskPauseThresholdPct`)**: Additive PostgreSQL columns (`client_sdks.storage_quota_mb` + 9 `admin_settings` columns in `core/Database/database.ts`, synced in `server/index.js` while preserving `ddlCount === 8`), `30s` TTL cached `statfs` + directory byte counters, and HTTP `507 Insufficient Storage` (`DISK_SPACE_LOW` / `STORAGE_QUOTA_EXCEEDED` — `V2-E04`, `V2-E05`) on `POST /api/events` and Port `4000``sync_data`/`batch_sync` while keeping all Admin read/export/settings routes online.
- **Admin UI Controls (`SettingsWorkspace.tsx`, `NewClientModal.tsx`, `ClientsTable.tsx`, `lib/vconUiHelpers.ts`)**: Added live VPS disk usage bar, `Auto-compress (.csv → .csv.gz)`, `Disk pause threshold (0 or 50–99%)`, full `S3 / R2 off-site archive` configuration with `Test S3 Connection` & `Archive Now`, and per-client `Storage quota (MB, 0 = unlimited)` in modal and table.
- **Verified**: `89/89` TS tests (`4/4` in `tests/v2-phase01-storage-quotas.test.ts`), `10/10` Python SDK tests, `npm run build` clean, `npm run lint` (`0` errors / `0` warnings), and Chromium E2E across `/vcon/settings` (Storage tab) and `/vcon/clients` (`0` console errors).
- **Per-Client IP / CIDR Allowlist & Token Expiration (`core/Security/ipAllowlist.ts`, `core/sdk/sdkManager.ts`, `app/api/clients/**`, `app/api/events/route.ts`, `server/index.js`, `server/socket/handlers.js`)**: Validates and normalizes comma-separated IPv4, IPv4 CIDR (`/0..32`), IPv6, IPv6 CIDR (`/0..128`), IPv4-mapped IPv6 (`::ffff:`), loopback equivalence (`127.0.0.1` ↔ `::1`), and wildcard `*`; validates ISO `expiresAt` timestamps. Enforced across both Port `3000``POST /api/events` and Port `4000` Socket.IO handshakes/events (`403 CLIENT_IP_FORBIDDEN` — `V2-E07`; `401 CLIENT_TOKEN_EXPIRED` — `V2-E08`), synced live via `/internal/client-sync` and additive PostgreSQL columns (`client_sdks.allowed_ips`, `client_sdks.expires_at`).
- **Outbound Webhook Alerting (`core/alerts/webhookNotifier.ts`, `core/adminSettings/settingsManager.ts`, `app/api/settings/webhook-test/route.ts`)**: Sends Slack (`text`), Discord (`content`), and structured JSON webhook payloads signed with optional HMAC-SHA256 (`X-DataStack-Signature: sha256=<hex>`) and deduplicated per `event:clientId` via configurable `webhookCooldownSec` (`10..86400s`, default `300s`). Triggers non-blocking alerts on `DISK_SPACE_LOW`, `STORAGE_QUOTA_EXCEEDED`, `S3_ARCHIVE_FAILED`, `CLIENT_IP_FORBIDDEN`, and `CLIENT_TOKEN_EXPIRED`, plus on-demand `POST /api/settings/webhook-test` (`200` on delivery, `502 WEBHOOK_DELIVERY_FAILED` on upstream error — `V2-E06`). `webhook_secret_enc` is encrypted via AES-256-GCM Secret Vault and masked in `GET /api/settings` (`hasWebhookSecret`, `webhookSecretMask`).
- **Prometheus Scrape Endpoint (`app/api/prometheus/route.ts`)**: `GET /api/prometheus` outputs Prometheus 0.0.4 text exposition format (`datastack_up`, `datastack_ingestion_bridge_up`, `datastack_active_sockets`, `datastack_events_total`, `datastack_buffer_events_total`, `datastack_storage_files_total`, `datastack_storage_bytes_total`, `datastack_storage_rows_total`, `datastack_disk_used_percent`, `datastack_disk_free_bytes`, `datastack_disk_total_bytes`, `datastack_clients_total`, `datastack_client_events_total`, `datastack_client_storage_bytes`). Protected by constant-time SHA-256 Bearer token comparison (`prometheus_metrics_token_enc` encrypted at rest) or active Admin Console session cookie (`401 PROMETHEUS_UNAUTHORIZED` — `V2-E09`).
- **Streaming `.ndjson` Export (`app/api/export/route.ts`, `components/sections/ExportWorkspace.tsx`)**: Added `format=ndjson` (`Content-Type: application/x-ndjson; charset=utf-8`, `.ndjson` extension) streaming newline-delimited JSON objects across both `.csv` and `.csv.gz` partitions, with `NDJSON` format radio selector in `/vcon/export`.
- **Admin UI Controls (`SettingsWorkspace.tsx`, `NewClientModal.tsx`, `ClientsTable.tsx`, `lib/vconUiHelpers.ts`)**: Added `Outbound webhook alerts` and `Prometheus metrics (/api/prometheus)` groups under `/vcon/settings` → **Security** tab, and `Allowed IPs / CIDR` + `Token expiration` controls in `/vcon/clients` New/Edit modals and table badges.
- **Verified**: `93/93` TS tests (`4/4` in `tests/v2-phase02-alerts-ip-prometheus.test.ts`), `10/10` Python SDK tests, `npm run build` clean, `npm run lint` (`0` errors / `0` warnings), and Chromium E2E across `/vcon/settings` (`0` console errors).
- **`BUG-V2-AUDIT-04`**: Updated `revokeAdminSessions(target)` in `core/auth/adminUsers.ts` to accept explicit `{ memberId, email }` and passed `{ memberId: check.session.memberId, email: check.session.email }` from `POST /api/auth/logout` (`app/api/auth/logout/route.ts`), eliminating the multi-admin logout global race condition (`globals.__dataStackLastVerifiedMemberId`).
- **`BUG-V2-AUDIT-03` (`ERR-V2-AUDIT-01`)**: Enforced cross-table (`admin_users` ↔ `admin_team_members`) and in-memory peer duplicate email checks in `updateAdminAccount()` (`core/auth/adminUsers.ts`) returning `code: 'ADMIN_EMAIL_CONFLICT'`, mapped to HTTP `409 Conflict` in `PUT /api/auth/profile` (`app/api/auth/profile/route.ts`).
- **`BUG-V2-AUDIT-02`**: Wired all 4 missing audit actions (`ADMIN_LOGOUT` in `POST /api/auth/logout`, `ADMIN_SETUP` in `POST /api/auth/setup`, `STORAGE_FLUSH_TRIGGERED` in `POST /api/storage`, and `CLIENT_REVOKED` when `updates.status === 'revoked'` in `PATCH /api/clients/[id]`) and synchronized `ACTION_FILTER_OPTIONS` in `components/sections/AuditLogViewer.tsx` 1:1 with `AuditActionType` in `core/auth/auditLog.ts` (all 18/18 governance actions active).
- **Verified**: `103/103` TS tests (`5/5` in `tests/v2-phase03-rbac-audit.test.ts`), `10/10` Python SDK tests, `npm run build` clean, and `npm run lint` (`0` errors / `0` warnings).
- **`BUG-V2-AUDIT-05` (`ERR-V2-AUDIT-02`)**: Wired outbound HMAC-SHA256 webhook alert dispatching (`triggerWebhookAlert` + `dispatchRejectionWebhook`) on Port 4000 Socket.IO (`server/index.js`, `server/socket/handlers.js`) for `CLIENT_TOKEN_EXPIRED`, `CLIENT_IP_FORBIDDEN`, `DISK_SPACE_LOW`, and `STORAGE_QUOTA_EXCEEDED` across handshake, `sync_data`, `batch_sync`, and `ping_verify`, with AES-256-GCM `decryptVaultSecret` in `syncSettingsFromDatabase()` and live `webhookSecret` propagation in `core/adminSettings/settingsManager.ts`.
- **`BUG-V2-AUDIT-06` (`ERR-V2-AUDIT-03`)**: Upgraded `isClientIpAllowed()` and `stripIpv6MappedPrefix()` in both `core/Security/ipAllowlist.ts` and `server/index.js` to use Node's built-in `net.BlockList` (`addSubnet`) for all IPv4 (`/0..32`) and IPv6 (`/0..128`) CIDR subnets and normalize `[ipv6]:port`, `ipv4:port`, `%zone`, and `::ffff:`.
- **`BUG-V2-AUDIT-08` (`ERR-V2-AUDIT-04`)**: Enforced `isClientTokenExpired(registeredClient.expiresAt)` (`401 CLIENT_TOKEN_EXPIRED`) and `isClientIpAllowed(extractClientIp(req), registeredClient.allowedIps)` (`403 CLIENT_IP_FORBIDDEN`) in `GET /api/health` (`app/api/health/route.ts`).
- **`BUG-V2-AUDIT-09` (`ERR-V2-AUDIT-05`)**: Added `"CLIENT_TOKEN_EXPIRED"` and `"CLIENT_IP_FORBIDDEN"` to `_is_non_retryable_auth_error()` and `_extract_auth_error_code()` in `sdk/python/datastack/datastack/client.py`, immediately raising `DataStackAuthError(msg, code=...)` matching the Node.js SDK 1:1.
- **Verified**: `104/104` TS tests (`5/5` in `tests/v2-phase02-alerts-ip-prometheus.test.ts`), `11/11` Python SDK tests (`tests/phase05_sdk_test.py`), `npm run build` clean, and `npm run lint` (`0` errors / `0` warnings).
- **`BUG-V2-AUDIT-01`**: Aligned `DiskUsageSnapshot` (`core/Storage/csvStorage.ts`), `GET /api/storage` (`app/api/storage/route.ts`), and `SettingsWorkspace.tsx` (`components/sections/SettingsWorkspace.tsx`) with `available: boolean` (`totalBytes > 0`) and `freeBytes: number` (`availableBytes`) so `/vcon/settings` -> Storage -> "VPS disk usage" renders real disk utilization percentage, progress bar, and free/total GiB instead of `"Statfs unavailable"`.
- **`BUG-V2-AUDIT-07`**: Added `isClientExpired(expiresAt, nowMs)` in `app/vcon/clients/page.tsx` and excluded expired tokens from `onlineCount`, `pendingCount`, and `"online"`/`"pending"` filter tabs (classifying non-revoked expired clients under `"offline"`), matching `ClientsTable.tsx``"expired"` badges 1:1.
- **`BUG-V2-AUDIT-10`**: Updated `components/sections/ExportWorkspace.tsx` and `app/vcon/storage/page.tsx` to render a `CSV.GZ` format badge whenever `file.compressed || file.filename.toLowerCase().endsWith('.csv.gz')` is true (`CSV` otherwise).
- **Verified**: `105/105` TS tests (`4/4` in `tests/v2-phase01-storage-quotas.test.ts`), `11/11` Python SDK tests (`tests/phase05_sdk_test.py`), `npm run build` clean, and `npm run lint` (`0` errors / `0` warnings). All `3 / 3` phases (`10 / 10` bugs) resolved.
- **R3 Full-Stack Production Remediation (`BASELINE-2026-11-20-R3` — `16` Verified Bugs across `4` Scope-Locked Phases)**:
- **`BUG-01`**: Aligned Port 4000 `decryptVaultSecret()` (`server/index.js`) 1:1 with `core/Security/secretVault.ts` (`v1:` prefix, `DATASTACK_ADMIN_SESSION_SECRET`, `base64url` decoding, fail-closed `""` + warning) and injected `DATASTACK_ADMIN_SESSION_SECRET` (`SERVICE_REALBASE64_64_ADMINSESSION`) into `docker/docker-compose.yml``services.ingestion.environment`.
- **`BUG-03`**: Updated `AuthService.generateClientToken(payload, expiresIn?)` (`core/auth/jwt.ts`) to omit JWT `exp` when `expiresIn` is `null`/`undefined`/`""`, and passed `null` across all 6 minting sites in `core/sdk/sdkManager.ts` so DB `client_sdks.expires_at` (`Never expires`, `>30d`, live extension) is authoritative.
- **`BUG-04`**: Enforced `requireAdminApiSession(req, { minRole: 'operator' })` on admin-session calls to `POST /api/events` (`app/api/events/route.ts`), returning `403 INSUFFICIENT_ROLE_PERMISSION` for read-only `viewer` accounts.
- **`BUG-06`**: Wrapped `decryptSecret(settings.webhookSecretEnc)` in `SettingsManager.notifyIngestionSettingsSync()` (`core/adminSettings/settingsManager.ts`) in `try/catch` (`""` fallback + warning) and deferred `decryptSecret` in `POST /api/settings/webhook-test` (`app/api/settings/webhook-test/route.ts`) until neither draft `webhookSecret` nor `clearWebhookSecret` is provided.
- **`BUG-10`**: Wired non-blocking `ADMIN_LOGIN_LOCKOUT` webhook alert dispatch inside the `429 TOO_MANY_ATTEMPTS` lockout branch of `POST /api/auth/login` (`app/api/auth/login/route.ts`).
- **`BUG-13`**: Unified Port 4000 `formatOutboundWebhookBody()` (`server/index.js`) with Port 3000 `core/alerts/webhookNotifier.ts` (`instance`, `event`, `severity`, `title`, `message`, `clientId`, `details`, `timestamp`, `text`, `content`).
- **`BUG-15`**: Tightened `POST /api/storage/s3-test` (`app/api/storage/s3-test/route.ts`) from `operator` to `owner`-only RBAC.
- **Verified**: `6/6` in `tests/r3-phase01-security-vault-webhooks.test.ts`, `15/15` in `tests/v2-phase01..03`, `40/40` in `tests/phase01/02/07`, `npm run build` clean, `npm run lint` (`0` errors). `0` UI/SDK/CSV files modified.
- **`BUG-05`**: Added singleton unref'd periodic maintenance scheduler (`ensureMaintenanceScheduler`, `runScheduledMaintenanceTick`, `stopMaintenanceScheduler`, `stopMaintenanceSchedulerForTests`, `isMaintenanceSchedulerActive`) in `core/adminSettings/settingsManager.ts` with overlap locks (`__dataStackMaintenanceRunning`, `__dataStackArchivePruneInFlight`, `__dataStackCompressInFlight`), cooldown guards, and unhydrated-DB protection so S3 off-site archival + retention pruning and partition compression run unattended on schedule when `enableS3Backup === true`.
- **`BUG-09`**: Updated `extractDateFromFilename()` in both `core/Storage/csvStorage.ts` and `server/workers/csvWriter.js` to strip `.csv(.gz)` and trailing `-(?:part|gz)\d+` suffixes so `-gzN.csv.gz` and `-partN-gzM.csv.gz` collision files work identically across Port 3000/4000 pruning, S3 archiving, `/api/data`, and `/api/export`.
- **Verified**: `3/3` in `tests/r3-phase02-storage-scheduler-gzn.test.ts`, `40/40` in `tests/phase03/v2-phase01/phase07/r3-phase01`, `npm run build` clean, `npm run lint` (`0` errors). `0` UI/SDK/Auth/Docker files modified.
- **`BUG-02`**: Fixed Node.js SDK (`sdk/node/datastack/index.ts`) WS `batch_sync` to emit a raw `Array` directly (1:1 with Port 4000 `server/socket/handlers.js:595`), parse `ack.processed ?? ack.processedCount ?? ack.accepted` and `ack.duplicates ?? 0` across WS & HTTP batch responses, and propagate `duplicates` through `sendBatch()`, `batchSync()`, and `sendFile()`.
- **`BUG-07` (`ERR-R3-05`)**: Implemented real `heartbeatIntervalMs` monitor in Node.js SDK (`startHeartbeatMonitor` with `.unref?.()`, zero-CPU `IDLE_WS` pause, automatic `ping_verify` recovery & spool drain, clean timer teardown, `status().heartbeatActive`); fixed single HTTP/WS `DUPLICATE_DROPPED` reporting (`accepted: 0, duplicates: 1`); wired `TOKEN_ROTATED` (`401`) and `CLIENT_REVOKED` (`403`) fast-fail `DataStackAuthError` across WS `connect_error`, `ping_verify`, `sync_data`, `batch_sync`, and HTTP fallback; compiled CommonJS `sdk/node/datastack/dist/{index,types,spool}.{js,d.ts}` via `tsconfig.json` and pointed `package.json``main`/`types`/`exports` to `./dist/index.js` & `./dist/index.d.ts`.
- **`BUG-08` (`ERR-R3-06`)**: Added non-retryable `DataStackQuotaExceededError(DataStackError, retryable=False)` in `sdk/python/datastack/datastack/exceptions.py`, re-exported it in both `datastack` and `datastack_sdk`, and wired immediate fail-fast handling for HTTP `507` and WS `STORAGE_QUOTA_EXCEEDED` / `DISK_SPACE_LOW` in `sdk/python/datastack/datastack/client.py` with `0` retries, `0` HTTP fallback after WS quota rejection, and `0` offline spooling.
- **Verified**: `13/13` Node SDK/packaging tests (`5/5``tests/r3-phase03-sdk-parity.test.ts` against live Socket.IO handlers + `4/4``v2-phase04-node-sdk.test.ts` + `4/4``phase05-packaging.test.ts`), `14/14` Python SDK tests (`3/3``tests/r3_phase03_python_sdk_test.py` + `11/11``phase05_sdk_test.py`), `py_compile`, `tsc`, `npm run build` clean, `npm run lint` (`0` errors, `0` warnings). `0` Port 3000/4000/UI/Docker files modified.
- **`BUG-11` (`ERR-R3-07`)**: Added `shouldRedirectSimulatorUnauthorized(status, body)` in `lib/vconUiHelpers.ts` and wired it post-JSON-parse across both single & batch HTTP sends in `app/vcon/simulator/page.tsx` so expired/rotated/revoked client `401` responses display inline without logging out the authenticated admin.
- **`BUG-12`**: Added browser-local `formatDateForLocalInput(iso)` in `lib/vconUiHelpers.ts` and replaced UTC `.toISOString().slice(0, 16)` inside `ClientsTable.tsx``openEditModal()`, eliminating local timezone drift on client edits.
- **`BUG-14`**: Added `isUiClientExpired()`, `classifyUiClientStatus()`, and `summarizeUiClientCounts()` in `lib/vconUiHelpers.ts`; excluded expired clients from `activeClients` and exposed `expiredClients` in `core/apiEngine/apiService.ts` and `DashboardOverview.tsx`; emitted `datastack_clients_total{status="expired"}` and excluded expired clients from `status="active"` in `app/api/prometheus/route.ts`; expanded `/vcon/clients` with a 6-column `StatStrip` + 6-pill status filter (`Total`, `Online`, `Offline`, `Pending`, `Expired`, `Revoked`).
- **`BUG-16`**: Propagated verified session role from `app/vcon/layout.tsx` through `components/layout/VconShell.tsx` (`VconRoleContext` / `useVconRole()`) + `getVconRoleCapabilities()` (`lib/vconUiHelpers.ts`) to gate all role-restricted UI controls across `SettingsWorkspace`, `ClientsTable`, `/vcon/clients`, `DashboardOverview`, `/vcon/storage`, and `/vcon/simulator`.
- **Verified**: `29/29` TS unit/integration tests (`4/4``r3-phase04-ui-metrics-rbac.test.ts` + `15/15``phase04-ui-sync.test.ts` + `5/5``v2-phase02-alerts-ip-prometheus.test.ts` + `5/5``v2-phase03-rbac-audit.test.ts`), live headless Chromium (`playwright-cli`, `1440x900`) verification across `/vcon/dashboard`, `/vcon/clients`, `/vcon/simulator`, `/vcon/storage`, and `/vcon/settings` (`0` JS/React pageerrors), `npm run build` clean, `npm run lint` (`0` errors, `0` warnings). `0` Port 4000/SDK/Auth/Storage/Docker files modified. **All `4 / 4` R3 phases (`16 / 16` bugs) complete.**
- **Full-Project Production Forensic Audit & `R4` Baseline Freeze (`BASELINE-2026-11-20-R4`)**:
- Cleaned all 8 prior Files Manager files from `notes/` and created the 100% raw-source-verified `notes/FULL_PROJECT_FORENSIC_AUDIT.md` (**20** verified findings: `3` Critical, `6` High, `7` Medium, `4` Low — `19` actionable + `1` verified intentional preview `AUDIT-17`).
- Froze the untouched codebase as `BASELINE-2026-11-20-R4` and created the complete 8-file `R4` governance & Scope-Lock suite in `notes/` (`README.md`, `FULL_PROJECT_FORENSIC_AUDIT.md`, `BASELINE_FREEZE.md`, `PRODUCTION_READINESS_SCOPE_LOCK.md`, `PRODUCTION_ROADMAP.md`, `PHASE_EXECUTION_LOG.md`, `ERROR_HANDLING_MATRIX.md`, `ACTUAL_IMPLEMENTATION_STATUS.md`) across `4` Scope-Locked phases (`R4-Phase-01`..`R4-Phase-04`).
- **`AUDIT-01` (`ERR-R4-01`)**: Created shared SSRF validator `core/Security/ssrfGuard.ts` blocking non-HTTP(S) schemes, embedded credentials, loopback, RFC1918/CGNAT/ULA, `0.0.0.0/8`, cloud metadata (`169.254.0.0/16`, `fe80::/10`, `metadata.google.internal`), bare internal hostnames, and DNS-rebinding targets, plus `redirect: "manual"` 3xx rejection; enforced uniformly across `core/alerts/webhookNotifier.ts`, `core/Storage/s3Archive.ts`, `app/api/settings/route.ts`, `app/api/settings/webhook-test/route.ts`, `app/api/storage/s3-test/route.ts`, and `server/index.js``triggerWebhookAlert`, with `DATASTACK_ALLOW_PRIVATE_URLS=true` documented in `.env.example` (metadata still unconditionally blocked).
- **`AUDIT-03` (`ERR-R4-02`)**: Mirrored `admin_team_members` and `admin_audit_logs` DDL 1:1 into `server/index.js``ensureDatabaseSchema()` for full 7-table parity across Port `3000` and Port `4000` on fresh PostgreSQL boots.
- **`AUDIT-04` (`ERR-R4-03`)**: Added Next.js `instrumentation.ts` (`register()` on `NEXT_RUNTIME === "nodejs"`) invoking `SettingsManager.bootstrapMaintenanceSchedulerOnBoot()` to hydrate settings and start the periodic storage maintenance scheduler automatically on Port `3000` startup.
- **`AUDIT-09` (`ERR-R4-04`, `ERR-R4-05`)**: Added `console.warn` + `storageMode`, `degraded: true`, `code: "AUDIT_STORAGE_DEGRADED"`, `warning`, and `X-DataStack-Audit-Degraded: 1` header in `core/auth/auditLog.ts` & `GET /api/audit`; wired `POST /internal/admin-session-sync` in `server/index.js`, `syncInMemoryAdminSessionState` / `checkInMemorySessionRevocation` in `server/filesManager.js`, and `notifyIngestionAdminSessionSync` in `core/auth/adminUsers.ts` so `!dbPool` Files Manager sessions revoke immediately on logout/disable/delete/credential rotation.
- **`AUDIT-05` (`ERR-R4-06`)**: Enforced `DATASTACK_MAX_BATCH_ITEMS` (default `1000`, clamped `1..10000`, documented in `.env.example`) across `POST /api/events` (`400 BATCH_LIMIT_EXCEEDED`, evaluated before storage admission scan) and Socket.IO `batch_sync` (`server/socket/handlers.js`).
- **`AUDIT-06`**: Added `FILES_MANAGER_MUTATION` and `DATA_EXPORT_DOWNLOADED` to `core/auth/auditLog.ts` and `ACTION_FILTER_OPTIONS` in `components/sections/AuditLogViewer.tsx`; wired export download audit logs in `app/api/export/route.ts` and CloudCmd HTTP/Socket mutation audit logs (`admin_audit_logs` PG + RAM fallback) in `server/filesManager.js`.
- **`AUDIT-10`**: Added `serializeClientResponse()` in `app/api/clients/[id]/route.ts` stripping `secret` and non-rotation `token` from `PATCH /api/clients/[id]` responses while exposing `tokenPreview` (and full `token` only on `action === "regenerate_token"`).
- **`AUDIT-11`**: Made `POST /internal/client-sync` (`action === "updated"`) in `server/index.js` disconnect live sockets only on security-relevant updates (`status === "revoked"`, expired `expiresAt`, token rotation, `allowedIps` change, or live socket credential mismatch), keeping metadata-only updates (`name`, `rateLimit`, `storageQuotaMb`) connected without disruption.
- **`AUDIT-12` (`ERR-R4-08`)**: Converted `uploadFileToS3` (`core/Storage/s3Archive.ts`) to streaming SHA-256 pre-pass + `Readable.toWeb(fs.createReadStream(...))` (`duplex: "half"`) with `.destroy()` teardown, and hardened `CSVStorageManager.openPartitionTextStream` + `countCsvDataRowsStreamAsync` (`public static`) with `for await` + `.destroy()` cleanup.
- **Verified**: `5/5``tests/r4-phase02-ingestion-audit-streaming.test.ts` PASS, regression suites (`r4-phase01`, `files-manager`, `phase02-04`, `v2-phase02-03`, `r3-phase02`, `r3-phase04`) PASS, Playwright `/vcon/audit` (`0` console errors, new action filter options visible), `npm run build`, and `npm run lint` (`0` errors). `0` forbidden SDK/Docker/Nginx/middleware/auth/unrelated UI files touched.
- **`AUDIT-02`**: Added `"prepare": "npm run build"` and `"devDependencies": { "typescript": "^5.9.3" }` to `sdk/node/datastack/package.json` and compiled `sdk/node/datastack/dist/{index,spool,types}.{js,d.ts}` so CommonJS `require('./sdk/node/datastack')` works cleanly out of the box.
- **`AUDIT-20`**: Added atomic `DiskSpooler.ackAndRequeueFront(ackedCount, unprocessed)` in `sdk/node/datastack/spool.ts` and wired `deliverChunkWithSplitAndRetry()` + `flushSpool()` in `sdk/node/datastack/index.ts` (with `dist/` rebuilt) so partial-batch rate-limit recoveries commit acknowledged events without dropping or reordering unprocessed envelopes ahead of tail items.
- **`AUDIT-08` (`ERR-R4-09`)**: Added `DATASTACK_ADMIN_EMAIL: "${DATASTACK_ADMIN_EMAIL:-admin@datastack.dev}"` to `services.ingestion.environment` in `docker/docker-compose.yml`; added `proxyMode`/`wsSupported`/`wsHint` detection in `GET /api/files/status` (`app/api/files/status/route.ts`) and rendered a non-blocking `[data-testid="files-manager-proxy-hint"]` strip in `components/sections/FilesManagerWorkspace.tsx` when running standalone without Nginx WebSocket proxying.
- **`AUDIT-13`**: Removed dead `/api/auth/setup/status` whitelist line from `middleware.ts` and passed explicit `role: "owner"`, `memberId: "owner-1"` arguments to `createAdminSessionToken()` in `app/api/auth/setup/route.ts`.
- **Verified**: `4/4``tests/r4-phase03-sdk-deploy-auth.test.ts` + `43/43` regression checks (`47/47` total PASS across `v2-phase04-node-sdk`, `r3-phase03-sdk-parity`, `phase05-packaging`, `phase07-deployment`, `phase01-auth`, `files-manager`), `node -e "require('./sdk/node/datastack')"` PASS (`2.2.0`), Playwright `/vcon/files` (`0` console errors), `npm run build`, and `npm run lint` (`0` errors). `0` forbidden Storage/Webhook/Client/Team/Profile/Landing files modified.
- **`AUDIT-14`**: Updated `components/sections/TeamWorkspace.tsx` to initialize role from `useVconRole()` (`shellRole || 'viewer'`), preserve distinct `operator` and `admin``<Select>` options and row values without coercing `operator` to `admin`, label StatStrip `'Operators / Admins'`, and require an explicit `<Modal>` (`"Confirm Team Member Removal"`, `[data-testid="confirm-remove-member"]`) before `DELETE /api/team/${id}`.
- **`AUDIT-15` (`ERR-R4-10`)**: Wired `useVconRole()` + `getVconRoleCapabilities(shellRole)` (`canOperate`) in `app/vcon/sdk/page.tsx` so `viewer` sessions skip `?includeToken=true` requests cleanly (`0` HTTP `403`s) and display inline `[data-testid="sdk-viewer-rbac-banner"]` RBAC guidance while preserving existing `loadingToken` disabled guards.
- **`AUDIT-16`**: Seeded `components/layout/Sidebar.tsx` role badge from `useVconRole()` (`formatShellRoleLabel()`), renamed `'Python SDK'` to `'Client SDKs'`, and added `components/layout/Navbar.tsx` mobile `VCON_LABELS` for `'/vcon/files'` (`'Files Manager'`), `'/vcon/sdk'` (`'Client SDKs'`), `'/vcon/team'` (`'Team & RBAC'`), and `'/vcon/audit'` (`'Audit Log'`).
- **`AUDIT-19`**: Replaced fake Demo fallback constants in `components/sections/ProfileWorkspace.tsx` with neutral `EMPTY_PROFILE` placeholders (`'Loading...'` / `'—'`) until `/api/auth/profile` resolves.
- **`DEPLOY-BLK-01`**: Resynchronized `package-lock.json` (`lockfileVersion: 3`) with `package.json` (`cloudcmd ^19.23.2` + full dependency tree) and verified `npm ci --include=dev --dry-run` (`Dockerfile.web`) and `npm ci --omit=dev --dry-run` (`Dockerfile.server`) both exit `0`.
- **`DEPLOY-BUG-02`**: Hardened `docker/coolify-nginx.conf` and `nginx/default.conf` with `ngx_http_realip_module` (`set_real_ip_from` loopback/RFC1918/Docker bridges + IPv6 ULA, `real_ip_header X-Forwarded-For`, `real_ip_recursive on`) so `proxy_set_header X-Real-IP $remote_addr` preserves real external client IPs behind Coolify Traefik without permitting untrusted public IP spoofing.
- **`DEPLOY-BUG-03` & `DEPLOY-BUG-04`**: Added `ARG INGESTION_INTERNAL_URL=http://ingestion:4000` + `ENV INGESTION_INTERNAL_URL` in `docker/Dockerfile.web``builder` stage for standalone Next.js rewrites, and forwarded optional `DATASTACK_ALLOW_PRIVATE_URLS`, `DATASTACK_MAX_BATCH_ITEMS`, `DATASTACK_RECENT_LIMIT`, `DATASTACK_MAINTENANCE_INTERVAL_MS`, and `DATASTACK_PROXY_MODE` env vars in `docker/docker-compose.yml`.
- **`DEPLOY-BUG-05`**: Updated `sdk/node/datastack/index.ts` (`emitSocketSingle` and `sendBatchChunkInternal`) to call `this.disconnect()` on terminal `DataStackAuthError` rejections (`TOKEN_ROTATED`, `CLIENT_REVOKED`, etc.) and recompiled `sdk/node/datastack/dist/*` so subsequent `client.connect()` performs a fresh handshake (`tests/r3-phase03-sdk-parity.test.ts``5/5` PASS).
- **`R5-MCP` Planning, Foundation & Server Track (`BASELINE-2026-11-21-R5-MCP`)**:
- Froze post-`R4` / post-`PREPUSH-FIX-01` codebase and documented the full 8-item raw-source-verified MCP forensic audit (`MCP-AUDIT-01`–`MCP-AUDIT-08`), Scope Locks, A–Z 3-phase roadmap (`R5-Phase-01`–`03`), Phase Execution Log, `ERR-R5-01`–`09` error contracts, and Actual Status Ledger across `/notes/`.
- Added 8th PostgreSQL table `mcp_settings` identically in `core/Database/database.ts` and `server/index.js` (`ensureDatabaseSchema()`).
- Created TS (`core/logs/runtimeLogCapture.ts`) and CJS (`server/runtimeLogCapture.js`) bounded rotating runtime/build log writers & readers (`.runtime-logs/{web,ingestion}.log`, max 2MB + `.1` backup, secret redaction for Bearer/`dsmcp_`/JWT/JSON keys, graceful `LOG_CAPTURE_UNAVAILABLE` fallback), wired into `instrumentation.ts`, `server/index.js`, `scripts/start-all.js`, and `scripts/dev-all.js` (`DATASTACK_LOG_CAPTURED_BY_RUNNER=1` prevents duplicate tee writes).
- Created `scripts/capture-build-log.js` (`package.json``"build"`) and updated `docker/Dockerfile.web` so standalone Next.js builds emit `.next/standalone/build.log`, `.next/standalone/build-meta.json`, and `.runtime-logs/last-build*`.
- Created `core/mcp/mcpSettings.ts` (`McpSettingsManager` with default `enabled: false`, `17` permission definitions across 4 categories, `dsmcp_` token generation + SHA-256 digest + AES-256-GCM vault encryption, IP CIDR validation, SSRF-guarded `coolifyUrl`, PG/RAM roundtrip, and `POST /internal/mcp-sync` notifier) and added `MCP_*` action types + secret redactions in `core/auth/auditLog.ts`.
- Created Owner-only Admin MCP REST API (`app/api/mcp/route.ts`: `GET` masked status + 17 permission definitions; `POST` strict allowlist supporting `enabled`, `allowedIps`, `permissions`, `rotateToken`, `revokeToken`, and SSRF-guarded `coolifyUrl`/`coolifyToken`/`coolifyAppUuid`, with `MCP_TOKEN_ROTATED` & `MCP_SETTINGS_UPDATED` audit logging and live `/internal/mcp-sync`).
- Created Port 4000 Streamable HTTP MCP Engine (`server/mcp/mcpEngine.js`) using official `McpServer` + stateless `StreamableHTTPServerTransport`, enforcing disabled gate (`503 MCP_DISABLED`), CIDR allowlist (`403 MCP_IP_FORBIDDEN`), timing-safe SHA-256 `dsmcp_...` Bearer auth (`401 MCP_UNAUTHORIZED`), per-tool permission gate (`MCP_PERMISSION_DENIED`), symlink/`..`/`*.lock`/`.runtime-logs` write-protected storage sandbox, SSRF-guarded optional Coolify log proxy, `admin_audit_logs` telemetry (`MCP_TOOL_CALLED` / `MCP_TOOL_DENIED`), and all **17** registered `datastack_*` tools.
- Wired `POST /internal/mcp-sync`, `app.all('/mcp')`, and DB `mcp_settings` hydration (`syncSettingsFromDatabase()`) in `server/index.js`; added `/mcp` reverse proxy blocks in `docker/coolify-nginx.conf`, `nginx/default.conf`, and `next.config.ts`; added `WEB_INTERNAL_URL` in `docker/docker-compose.yml` & `.env.example`.
- **Verified**: `3/3``tests/r5-phase02-mcp-server.test.ts` + `50/50` regression checks across 8 suites (`53/53` PASS), live Port 3000 & Port 4000 `@modelcontextprotocol/sdk` E2E test (login -> `/api/mcp` -> `/mcp` direct + rewritten `tools/list` [17] & `datastack_metrics_health` -> revoke `503`), `npm ci --include=dev --dry-run` / `--omit=dev --dry-run` exit `0`, `compile_applet` clean, and `lint_applet` clean. Ready for `Proceed to R5-Phase-03`.
- **`ISSUE-02`**: Removed stale `/bun.lock` so `/package-lock.json` (`lockfileVersion: 3`) is the sole lockfile across Coolify/Docker `npm ci` builds.
- **`BUG-03`**: Added PostgreSQL `SettingsManager.getSettingsAsync()` hydration guards prior to reading `resolveInternalIngestionSecret()` / `getInternalIngestionHeaders()` in `app/api/internal/mcp/route.ts` (`POST`) and `core/mcp/mcpSettings.ts` (`notifyIngestionMcpSync`), preventing cold-boot bridge secret desyncs when `DATASTACK_INTERNAL_SECRET` is empty and `jwt_secret` was rotated in DB.
- **`ISSUE-04` & `ISSUE-05`**: Pre-created `/app/storage/.runtime-logs` and enforced `chown -R node:node /app/storage/.runtime-logs` on boot in both `docker/Dockerfile.web` and `docker/Dockerfile.server` without recursing `/app/storage/data` when UID/GID already matches; synchronized `prisma/schema.prisma` (`model McpSettings @@map("mcp_settings")`) with all 8 canonical runtime PostgreSQL tables.
- Removed `/bun.lock` to standardize package management exclusively on `npm` (`package-lock.json`).
- Expanded `.env.example` to document all 20 runtime environment variables used across the Next.js web app (port `3000`) and Express/Socket.IO ingestion engine (port `4000`), preserving built-in in-memory fallbacks when `DATABASE_URL` and `REDIS_URL` are omitted.
## 5. Known Constraints & Operational Notes for Future Contributors
- Never add per-row telemetry `INSERT` queries to PostgreSQL or add `DROP`/`TRUNCATE` auto-migrations.
- Never move Socket.IO handlers into Next.js `app/api/*` routes.
- When deploying updates to an existing Coolify VPS, always preserve existing `SERVICE_*` environment variables and avoid `docker compose down -v` so `pgdata`, `datastack-data`, and `redisdata` volumes remain intact.