QelomaShift — Semantic Change-Intelligence Engine

Not what changed — what it means, how much it matters, and what to do about it.

QelomaShift is a standalone, embeddable, domain-agnostic semantic change-intelligence engine. Given two (or more) versions of any input (contracts, policies, Kubernetes infrastructure drift, Terms of Service, datasheets), it tells a product what materially changed, how much it matters, and what to do — ranked, explained, actionable change intelligence.

It is the third engine in the Qeloma suite (after QelomaLens and QelomaVerdict) and reuses the family DNA: the same Input Envelope, the same capability-plugin architecture, and the same OpenAI-SDK-compatible model layer. See the in-app Brand page for the shared color/type tokens and the rest of the suite (Qeloma Cover Studio included).

---

🗺️ Pages

Route	Purpose
/	Marketing home — pipeline overview, Qeloma Suite cross-links, changelog
/brand	Brand & logo suite — mark customizer, SVG/PNG export, color/type tokens, voice
/docs	In-app documentation — setup, auth, theming, full API reference
/app	The product — Change-Report, Materiality Board, Stream Timeline, Compare, API Inspect

---

🚀 Key Capabilities & Pipeline

1. Semantic Alignment (ALIGN): Matches sections, clauses, and fields across versions even when reordered, renumbered, or reworded, with alignment confidence.
2. Meaning-level Diff (DIFF): Identifies structural and semantic deltas rather than character noise.
3. Policy-based Ranking (MATERIALITY): Scores every change against host-authored change policy dimensions and severity bands (HIGH, MEDIUM, LOW).
4. Practical Consequence (IMPACT): Translates diffs into plain-language exposure and operational impact statements.
5. Action Recommendation (NEXT_ACTIONS): Recommends concrete follow-up workflow chips.
6. Executive Synthesis (DIGEST): Generates summary digests and peak severity metrics.
7. Deterministic Fallback (structural-diff): When AI is offline or low confidence, degrades gracefully to structural diff while setting materiality to 'undetermined' rather than guessing.
8. Monitored Streams: Proactively watches evolving documents over time, auto-comparing new version bumps to the current stream head.
9. HMAC Webhooks: Fires signed webhooks (X-Qeloma-Signature) when threshold conditions (fireWhen) are met.

---

🎨 Four UI Surfaces (inside /app)

1. Change-Report Surface (Reviewers, Embeddable): Summary band first, followed by ranked material changes (HIGH → LOW) with impact headlines, action chips, and unit-level diff expander. Low/formatting noise collapsed by default.
2. Materiality Board (Triage Cockpit): Kanban board across severity bands (HIGH, MED, LOW, HANDLED) aggregating material changes across reports.
3. Stream Timeline (Proactive Monitor): Horizontal timeline tracking an evolving document over time. Node colors represent peak severity at each version bump.
4. Comparison Setup (Run Engine): Drop zones for Version A & B, preset selectors, change policy picker, and AI vs offline fallback mode toggle.
5. Developer API Explorer: cURL smoke test generator and self-describing capability registry.

---

🛠️ API Surface (/v1)

Endpoint	Method	Description
/v1/changes	POST	Core compare endpoint: versions A+B + policyRef → ranked ChangeReport
/v1/changes	GET	List past change reports
/v1/changes/:id	GET	Fetch report by ID
/v1/changes/:id/actions/:changeId/handled	POST	Mark action item handled
/v1/streams	POST	Create a monitored stream
/v1/streams	GET	List streams
/v1/streams/:id	GET	Fetch stream details and timeline versions
/v1/streams/:id/versions	POST	Submit new version to stream, run auto-compare against head
/v1/subscriptions	POST	Register webhook subscription with HMAC signing
/v1/subscriptions	GET	List subscriptions and dispatch logs
/v1/policies	GET	List versioned change policies
/v1/capabilities	GET	Discover engine capability plugins & confidence gates

---

🧪 cURL Smoke Test

curl -X POST "http://localhost:3000/v1/changes" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_tenant_demo" \
  -d '{
    "policyRef": { "id": "contract-review", "version": 3 },
    "a": { "content": "9.2 Liability Cap is $100k.", "label": "MSA v6" },
    "b": { "content": "9.2 Liability Cap is $300k.", "label": "MSA v7" }
  }'

---

🔐 Authentication (Supabase)

Sign-in, sign-up, and magic-link auth run on Supabase via src/lib/supabase.ts. Two ways to configure it:

• Env vars — set VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY (see .env.example).
• Runtime, no redeploy — the app also reads/writes these from localStorage, so a Supabase project can be plugged in from the running app itself.

Without a configured project, the app falls back to a local guest/demo session — every surface stays usable.

🎨 Theming

The header's Light / Dark / System control drives a single dark class on <html>, persisted to localStorage (qs_theme). "System" tracks the OS prefers-color-scheme media query live. Every color, font, and severity band is a CSS custom property in src/index.css — see /brand for the full token reference.

☁️ Deployment (Vercel)

vercel.json builds the Vite frontend to dist/ and rewrites /v1/* to a Vercel Node function at api/v1/[...slug].ts, which wraps the exact same Express app (server/app.ts) used by the local dev server — one set of routes, two runtimes. Report/stream/policy/webhook state is currently in-memory, so it does not persist across serverless cold starts on Vercel; that's fine for a demo, but Supabase Postgres is the natural next home for that data if this needs to run for real.

vercel link
vercel deploy        # preview
vercel deploy --prod # production, once you're ready

---

📦 Run & Deployment

# Start full-stack development server (Express API + Vite React UI on port 3000)
npm run dev

# Type-check
npm run lint

# Build for production
npm run build

# Start production server
npm run start