# Zyphon Non-Negotiable Rules

**Scope:** Gateway, dashboard, providers, contributors, and AI agents  
**Enforcement:** Code review, automated tests, and CI (when present)  
**Last updated:** 2026-10-12 (v5 alignment)

Canonical short form for Cursor: [`.cursor/rules/zyphon-core.mdc`](../.cursor/rules/zyphon-core.mdc).

---

## 1. Zero-database architecture

**RULE 1.1:** No external database, Redis, message broker, or queue as a runtime dependency.

- State: declarative YAML under `config/`, encrypted files under `data/state/`, bounded in-memory structures, append-only daily log files under `data/logs/`.
- No drivers or ORMs for SQL, NoSQL, or cache stores in gateway or dashboard.

---
zettai systems pvt ltd 
## 2. Secrets and redaction

**RULE 2.1:** Zero plaintext secrets in git or YAML manifests.

- Use `${ENV_VAR}` placeholders in config; fail fast if required env is missing at load time.
- Provider credentials are stored only in the encrypted vault (AES-256-GCM; master key from `ZYPHON_MASTER_KEY` or Docker secret).
- **Never** return secrets from any API, log line, or error payload. Admin responses use `secret_set: true` only.
- Redact `Authorization`, API keys, tokens, and provider credentials in logs and upstream error handling.
- Mask recipient PII in logs where appropriate.

---

## 3. API boundaries

**RULE 3.1:** Public API (`:8080`) and admin API (`:8081`) are separate listeners.

- Public: application API keys; message send and status; inbound provider webhooks.
- Admin: session-authenticated (and CSRF-protected when implemented) mutations and reads for the console.
- The dashboard calls the **admin API** through a server-side proxy and **never** holds provider secrets in the browser.

---

## 4. Fail-closed channel access

**RULE 4.1:** Applications may send only on channels explicitly enabled for that app in `config/applications.yaml` (field name in code: `channels`).

- No wildcard `*` channel permissions.
- Missing or false channel → immediate `403` with normalized error code (e.g. channel not permitted).

---

## 5. Delivery semantics

**RULE 5.1:** Delivery contract is explicit.

- HTTP success from Zyphon = message accepted for dispatch.
- Provider success = accepted by the upstream vendor.
- Status `delivered` is set only when a provider callback (or verified webhook) confirms delivery.

---

## 6. Logs and retention

**RULE 6.1:** One NDJSON file per UTC day: `data/logs/zyphon-YYYY-MM-DD.log`.

- Append-only; file mode `0640` where supported.
- Retain newest N days (3 / 7 / 14 / 30 configurable); prune on startup, on rollover, and on schedule.
- Audit and delivery events use structured `{ "type": "audit" | "delivery" | ... }` lines as implemented.

---

## 7. UI and observability data

**RULE 7.1:** Every number shown in the dashboard must come from real gateway data.

- No fabricated trends, health, or counts.
- Plain language on primary screens: Sent, Delivered, Failed, Blocked.
- Technical internals (circuit names, HMAC steps) belong in drawers or Settings only.

---

## 8. Provider adapters

**RULE 8.1:** Read the vendor’s **current** official documentation before implementing or changing an adapter.

- Do not guess URLs or field names.
- Export `fieldSchema` (when contract requires) for dashboard forms and gateway validation.
- Classify errors: `PROVIDER_REJECTED`, `PROVIDER_5XX`, `PROVIDER_UNAVAILABLE`, `TIMEOUT`, `CREDENTIAL_ERROR`.
- Use `AbortSignal` timeouts; prefer headers over secrets in URLs.
- India SMS: DLT template ID, matching header, Principal Entity ID — refuse send when invalid.
- Contract tests use recorded fixtures under `tests/contract/fixtures/<provider>/`; no live-account tests in CI.

---

## 9. Implementation quality

**RULE 9.1:** Complete, working code only in merged work.

- No TODOs, stubs, placeholder data, or skipped implementations for user-facing features.
- TypeScript strict; Node 20 LTS; pnpm workspaces.
- Stack: Fastify + Zod + Pino (gateway); Next.js App Router + Tailwind (dashboard); Vitest + Playwright (tests).

---

## 10. Agent and contributor workflow

**RULE 10.1:** Before changing behaviour, read `docs/RULES.md`, `docs/MEMORY.md`, `docs/TASKS.md`, and `docs/GAP_ANALYSIS.md`.

- Record architectural decisions in `docs/MEMORY.md`.
- Tick or update tasks in `docs/TASKS.md`.
- After structural changes, run `node scripts/validate-intelligence.js` when applicable and update `.project/` graphs per `AGENTS.md`.

---

## 11. Idempotency (public API)

**RULE 11.1:** Support `X-Idempotency-Key` (or documented equivalent) for duplicate protection.

- In-memory cache with TTL; replay successful responses with `X-Zyphon-Idempotent-Replay: true` when appropriate.
- In-flight duplicate → `409` where implemented.

---

## 12. Normalized errors (public API)

**RULE 12.1:** Callers receive standardized error objects; never vendor stack traces or raw credentials.

- Use the shared error taxonomy (`PROVIDER_TIMEOUT`, `INVALID_RECIPIENT`, `RATE_LIMITED`, etc.).

---

## 13. Configuration hot-reload

**RULE 13.1:** Invalid config must not take down the process.

- Validate with Zod before swap; keep last-known-good on failure; emit audit/log events on reload success or failure.