Version development history

ADMINISTRATOR ::: danger Restricted

This page is gated behind Cloudflare Access. Do not paste content elsewhere. :::

This is the chronological development log of RAPAX PMS, distilled from the client/src/App.tsx changelog block, the per-version audit notes under audits/, and the CADENCE.md ledger.

v2.31.x — Source-of-truth grounding & UCS Foundation cascades

v2.31.0.35 (2026-04-28) — A4 cascade APPLY (writes)

Headline. Migration 0104 adds audit_log. New src/master-revision-cascade.js applyCascade() writer (atomic D1 batch, quarantine guard, dryRun mode). Admin endpoint POST /api/admin/ucs-foundation/cascade-apply with three-way safety:

• dryRun defaults true
• dryRun:false requires confirmApply:true
• toVersionId must be is_active=1

Pairs with v2.31.0.34 cascade-preview to give the operator a recommended two-step preview-then-apply UX.

v2.31.0.34 (2026-04-28) — A4 cascade preview (reads)

POST /api/admin/ucs-foundation/cascade-preview runs read-only diff between the active Master version and a target version, classifying each code as kept | renamed | moved | split | merged | deleted | new. Output feeds the apply step.

v2.31.0.33 (2026-04-28) — Atlas-driven dept lookup

Master List validator now resolves dept from L3 in the Hierarchy Atlas; new POST /api/admin/recompute-atlas-tree endpoint.

v2.31.0.32 — Component breadcrumbs & missing-component picker

Atlas-driven breadcrumbs (L1 → L2 → L3 → component) on the component card; new picker for adding components missing from a vessel CL.

v2.31.0.30 (2026-04-28) — Phantom column hotfix

Live probe of /api/cl-skeleton/vessels/15/wizard returned HTTP 500 with D1_ERROR: no such column: classification. Root cause: source_documents.classification was a phantom column declared in deriveMandatoryPresence JSDoc (v2.31.0.7) but never created by migration. Three SELECT sites bound it; all four references dropped. Side effect: /status bucket arrays now populate from real source-doc evidence (HELPFUL / RUN 2 PENDING / NEEDS REVIEW dashboard cards may start showing entries that were silently empty for ~3 weeks).

v2.31.0.29 — BI_01 UI cleanups

CL Remap tab + New Component kebab + Source Docs Wizard renamed to Class and Flag Documents + Quick upload removed. /cl-remap* retained because Component List flow depends on it.

v2.31.0.21 (2026-04-28) — Clean-system pass

Closed N-1 (docTypeToMandatoryClass map mismatch in src/rag-retrieval.js) and N-2 (vessel_particulars.source_doc_ids missing column, fixed by migrations/0100).

v2.31.0.19 — Source-of-truth grounding + observable AI

Five-bundle release.

Bundle	Scope
B1 RAG-grounding	New mandatory_class column on rag_chunks; retrieveHybrid({mandatoryOnly, classFilter}); token-budget cap on few-shot context; winner_path trace tags
B2 source-doc trace	New vessel_particulars_provenance(vessel_id, field_path, source_document_id, provenance_quality) table; provenance writes wired at general_particulars and general_arrangement extractor sites
B3 KB orphan heal	src/kb-orphan-heal.js re-maps the 2,419 quarantined cl_knowledge_base rows against the active Master at Jaccard ≥ 0.72; admin endpoints POST /api/admin/kb-orphan-heal + GET /api/admin/kb-orphan-count
B4 wizard supersede + archive	Migration 0099 adds superseded_by_source_document_id; new archiveOnSupersede helper; wizard upload route archives prior evidence BEFORE the priority-1 idempotent UPDATE; rollback on UPDATE failure
B5 messenger AI-status	createSystemNotification('ai-status', …) calls fire on heal completion, supersede event (Sofia 23-08 quiet-hours guard), RAG eval recall@5 ≥5pp regression (sentinel-deduped per UTC day)

Two backfill admin endpoints: POST /api/admin/backfill/rag-chunks-mandatory-class (chunked at 5000 rows/call) and POST /api/admin/backfill/vessel-particulars-provenance.

v2.31.0.16 — GLOBAL UCS Manifest Master bridge

Production /api/cl-skeleton/master-lists returned {items:[]} even though EGOR LETOV had every six-blocker satisfied and the GLOBAL UCS Manifest Master was already imported. Root cause: cl-skeleton endpoints only consulted the legacy master_lists table; the active GLOBAL UCS Manifest Master lives in ucs_foundation_versions(is_active=1). Fix: new resolver src/cl-skeleton/active-master-resolver.js prefers ucs_foundation_versions and falls back to master_lists. UI: ClBuildsTab gained a "GLOBAL UCS Manifest Master" pill.

v2.31.0.12 — Mandatory-source register correction

The full A/B/D source-document register is a named register; only true CL skeleton prerequisites are blocking. Vessel Component List and Loading Manual are now non-blocking helpful / Run 2 inputs. CL Build mandatory gate count derived dynamically from the central blocking-slot list — currently 6 blocking slots: Particulars, Capacity Plan, GA Plan, Form E / Form Ser, GMDSS Radio Installation Record, ECDIS Certificate.

v2.31.0 — CL Skeleton Builder Phase 1 of 6

Windows-installer-style 12-step wizard (Steps 0–11). New module src/cl-skeleton/ (~1,810 LOC core + 11 REST endpoints). 5 new D1 tables (cl_skeleton_audit, cl_skeleton_runs, cl_skeleton_wizard_state, master_lists, vessel_particulars) via migrations 0090–0095. doc-types.js extended 17 → 23. Tests: 14 matcher test files (171 tests) + 3 routes test files (56 tests).

v2.30.x — Audit batch & critical fixes

v2.30.0 — System-audit-driven critical-fixes batch

Closed 4 critical + 8 addressable findings. Highlights:

• AUD-002: swap deprecated sonar-small-online → sonar-pro for Perplexity
• AUD-007: per-provider AbortSignal.timeout in src/gemini.js + Promise.race wrapper in src/ai-router.js (60s chat / 120s PDF). Workers AI binding can't take a signal so we race the .run() against a setTimeout reject
• AUD-014: self-learning.js now mirrors non-REJECTED corrections into cl_knowledge_base (seeded_by='auto', learning_weight=1.0) with admin-priority guard
• KB cleanup: migration 0089_kb_orphan_quarantine.sql adds cl_knowledge_base.quarantined column + flags 2,419/2,952 orphan target codes

v2.29.x — 3-tier role model

v2.29.0 — supervisor role tier

NEW: supervisor tier between superintendent and administrator. Legacy 'admin' rows renamed to 'administrator' via migration 0084; backwards-compat alias preserved for one release. New module src/role-helpers.js (10 capability gates) + TS port at client/src/lib/roles.ts. /api/staff/* middleware admits supervisor + admin (Teach Model, KB rebuild/backfill, RAG graph, draft approve/reject moved here; old /api/admin/* paths 308-redirect for one release).

v2.29.4.1 — CRITICAL HOTFIX

swarm-overlay.tsx referenced isAdministrator() (added in v2.29.3) without an import { isAdministrator } from "@/lib/roles" statement. The v2.29.4 production bundle threw ReferenceError: isAdministrator is not defined on every page load — the entire SPA white-screened for all users. Fixed. Vite shipped the broken bundle because tsc isn't run as part of the build pipeline; tsc --noEmit gate added in v2.29.5.

v2.28 — Admin menu grouped dropdowns

Replaced flat strip of 18 sibling tab buttons with 5 topic-grouped dropdowns (Drafts & Approvals · Components · Fleet · Knowledge · System).

v2.27 — RAG Knowledge Graph

New admin page /admin/rag-graph renders LightRAG-style force-directed graph of the RAG corpus (components + makers + models + source documents + UCS codes). Pure SVG + self-contained Verlet spring simulation, no new runtime deps. Capped at 1,000 nodes (sorted by degree desc).

v2.26 — DM (Documents Missing) status

Populated components without a backing source document show a blue DM badge. Proof-bearing fields (maker / model / serial_number / location / install_date) blink in orange when missing. Attaching a document logs a diff into field_overrides_log (document contents prevail → component flips to draft so admin re-approves). New field_overrides_log table (migration 0083) for the learning-curve loop.

v2.25 — KB component ingestion

Synthetic RAG chunks (doc_type='component_kb') emitted for every active component. Plus a deduped fleet-wide maker/model dictionary (doc_type='maker_model_kb'). Both layers write source_document_id=0 sentinel and vessel_id=NULL so retrieveHybrid finds them on any vessel.

v2.24 — Verification pass

Hardened POST /api/vessels/:id/components/import with row-level schema validation, structured rejected[] reasons, partial-success 207 Multi-Status. New POST /api/admin/knowledge-query wires retrieveHybrid → auditLongContext (Kimi K2.6) → validateCitations → corrective-retry. New GET /api/health public probe.

v2.23 — Particulars priority + Ship's Documents in RAG

Particulars priority rule: IMO + DWT (Summer Salt Water) become authoritative on Particulars approval. Knowledge Base library doc-type taxonomy expanded 7 → 22.

v2.21 — Bundle-size lazy-load

Admin and Components pages (6,210 and 2,489 LOC respectively) lazy-loaded.

v2.20 — In-app messenger + email mirror

Replaced WhatsApp at v2.15.5. migrations/0069_messages.sql: message_threads, messages, message_recipients. Domains: notification, upload-request, audit, general, ai-status. Postmark for email mirror (verified SPF + DKIM + Return-Path on pmsplanner.com).

v2.15 — WhatsApp removal

v2.15.5, migration 0064_drop_wa_tables.sql. All Z-API / Meta WhatsApp Cloud API code, tables (deploy_notifications, pending_digest), and users.notify_on_deploy column dropped. Pre-deploy snapshots saved to audits/v2.15.5-deploy_notifications.archive.json and audits/v2.15.5-pending_digest.archive.json.

v2.12 — Login gate

v2.12.16 introduced a temporary login gate for non-admin users. Rationale: system not yet "dumb-proof on inputs and procedures." Stays active until owner says "unblock."

v2.12.18 — anti-misuse hardening: Workers AI (Llama-4-Scout) filename classifier + magic-byte sniff. Catches .jpeg→.pdf spoof and CERT→GA rename.

How to read this log

• vX.Y.Z is a feature; vX.Y.Z.N is a hotfix or audit-followup on that feature
• Every entry corresponds to a single deploy — the version string is bumped in client/src/App.tsx:216, the only canonical version pin
• Audit notes for each version live in audits/v<version>-audit.md and audits/v<version>-system-audit.md
• The CADENCE.md ledger records the 15-minute checkpoints from each long deploy session