Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ jobs:
- run: python -m pip install -e ".[dev,web]"
- run: python -m normal_forms.catalog
- run: python -m pytest tests web/test_api_smoke.py -q
- run: node tests/test_frontend.cjs

distribution:
runs-on: ubuntu-latest
Expand Down
8 changes: 4 additions & 4 deletions IMPORT_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -573,7 +573,7 @@ def check_strict_auditing_nf(schema: RelationalSchema) -> Tuple[bool, Optional[s

## 5. Deployment Guide: Companion Web Interface

The repository includes a companion web application, **Simplex-NF Studio ("The Normal Form Workbench")**, configured for production deployment at `smplxnf.anomalon.com` on Render (`onrender.com`).
The repository includes a companion web application, **Simplex-NF Studio ("The Normal Form Workbench")**, with a Render blueprint targeting `smplxnf.anomalon.com`. Configuration is not deployment evidence: see [current status](docs/PROJECT_STATUS.md) and the [deployment runbook](docs/DEPLOYMENT.md).

### 5.1 Local Development Server

Expand Down Expand Up @@ -621,9 +621,9 @@ services:
2. Select **New > Blueprint** and link the repository. Render will automatically parse `render.yaml`.
3. Configure the custom domain in your DNS provider:
- Record Type: `CNAME`
- Host: `smplxnf.anomalon.com`
- Value: `smplxnf-studio.onrender.com`
4. Render provisions and renews TLS/SSL certificates automatically via Let's Encrypt.
- Host: `smplxnf` within the `anomalon.com` zone
- Value: the actual assigned Render hostname (do not infer it from the service name)
4. Verify the custom domain and certificate in Render, then run `python scripts/http_smoke.py https://smplxnf.anomalon.com`. The [runbook](docs/DEPLOYMENT.md) covers the user-operated DNS handoff and browser checks.

---

Expand Down
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
**Boundary-Certified Data Architecture, Relational Normalization, Cochain Retraction & Representation Transport (`CODA_MUR`)**
**Epistemic Standard:** Landau Rigor / Claim Discipline Compliant (`AuthorityEffect: None`, `certified_implies_authorized: false`)

[![Live Demo: smplxnf.anomalon.com](https://img.shields.io/badge/Live_Demo-smplxnf.anomalon.com-0284c7)](https://smplxnf.anomalon.com)
[![Deployment status](https://img.shields.io/badge/Deployment-verification_pending-amber)](docs/PROJECT_STATUS.md)
[![Deployment: Render](https://img.shields.io/badge/Deploy-onrender.com-46e3b7)](https://render.com)
[![Adoption Guide: IMPORT_GUIDE.md](https://img.shields.io/badge/Adoption_Guide-IMPORT__GUIDE.md-10b981)](IMPORT_GUIDE.md)
[![Architecture Spec: MVP_SELECTION.md](https://img.shields.io/badge/Architecture-MVP__SELECTION.md-8b5cf6)](docs/MVP_SELECTION.md)
Expand All @@ -19,12 +19,15 @@

Experience the core theoretical and engineering capabilities of `simplex-normal-forms` in real time:

👉 **[Launch Simplex-NF Studio at smplxnf.anomalon.com](https://smplxnf.anomalon.com)** (Hosted on Render via `onrender.com`)
**Target URL:** [smplxnf.anomalon.com](https://smplxnf.anomalon.com). As of 2026-11-02,
the application is merged and locally tested; public DNS/HTTPS verification is
pending. See [project status](docs/PROJECT_STATUS.md) and the
[Render deployment and smoke-test runbook](docs/DEPLOYMENT.md).

### Four Flagship Engineering Workbenches
1. **Relational Synthesis & Tableau Chase Studio (Flagship Landing View):** Interactive attribute closure, candidate key derivation, prime/non-prime attribute partitioning, minimal canonical cover, Bernstein (1976) dependency-preserving 3NF synthesis, Tsou-Fischer BCNF decomposition trees, and step-by-step Tableau Chase verification with spurious tuple counterexample witnesses.
2. **Streaming BQNF Delta Repair Simulator:** Incremental Change Data Capture (CDC) boundary maintenance, signed coboundary delta calculation, priority-queue extremum cochain tracking in $O(\log K)$ without base table scans, and dynamic dyadic-bucket $\epsilon$-quantile sketch rebalancing under skewed streams.
3. **4-Layer NF-IR Compiler Explorer:** Godbolt-style intermediate representation inspector demonstrating multi-pass lowering: Declarative Contract $\to$ Layer 1 Micro-Kernel $\to$ Layer 2 Poset Subsumption & Dead-Check Elimination (DCE) $\to$ Layer 3 Operadic DAG Wiring $\to$ Layer 4 Codegen for SQLite Triggers (`BEFORE INSERT/UPDATE`) and Python `@nf_kernel_guard` decorators.
3. **NF-IR Compiler Explorer:** Functional-dependency lowering into SQLite triggers (`BEFORE INSERT/UPDATE`), Python guards, and counterexample fixtures, with a constructed subsumption comparison. The four-layer library architecture includes operadic wiring; this endpoint does not execute arbitrary wiring DAGs or compile the full contract catalog.
4. **AI Agent LossLedger Gateway:** Context projection and token budget truncation for RAG and Model Context Protocol (MCP) tool pipelines with cryptographic SHA-256 Merkle `LossLedger` generation, exact additive token conservation ($\text{retained} + \text{truncated} == \text{source}$), and strict authority firewall gating (`certified_implies_authorized: false`).

📖 **Read the Full Architectural Specification:** [`docs/MVP_SELECTION.md`](docs/MVP_SELECTION.md)
Expand Down
102 changes: 102 additions & 0 deletions docs/DEPLOYMENT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# Render deployment and Phase 3 verification

The application and blueprint are implemented. Public deployment remains a
separate gate; see [the dated status](PROJECT_STATUS.md). PRs #17–19 are already
merged. Use the current reviewed `main`, not the old MVP feature branch.

## Render service

Inspect the existing [Render project](https://dashboard.render.com/project/prj-dbj5ei942hec73c30pu0)
before creating or syncing `smplxnf-studio` from [render.yaml](../render.yaml).

| Setting | Blueprint value |
| --- | --- |
| Repository / branch | `https://github.com/dbccpage/simplex-normal-forms` / `main` |
| Runtime / region / plan | Python / Oregon / Starter |
| Build | `pip install -e . && pip install -r web/requirements.txt` |
| Start | `uvicorn web.app:app --host 0.0.0.0 --port $PORT` |
| Health check | `/healthz` |
| Environment | `PYTHONUNBUFFERED=1`, `APP_ENVIRONMENT=production` |
| Custom domain | `smplxnf.anomalon.com` |

Record the selected Python version and successful deploy's Git SHA. The blueprint
does not pin a Python version; Render's default depends on service creation date
([Render Python version documentation](https://render.com/docs/python-version)).
Record the actual instance plan and associated account commitment before provisioning.

Run the check below against the **assigned** `https://…onrender.com` origin
first. A service name alone does not establish its assigned hostname.

## DNS handoff

The supplied handoff assigns the GoDaddy update to the user. Report the verified
Render hostname, then wait for their confirmation that the record is updated:

**2026-11-02 update:** The user has already created the canonical CNAME pointing
`smplxnf` to `smplxnf-live.onrender.com`; resolver `1.1.1.1` returned it with TTL
3600. This target returned HTTP 404 on `/healthz`. Confirm the new service's
assigned hostname before requesting another DNS change. The service still needs
`smplxnf.anomalon.com` added in **Settings → Custom Domains**.

**Latest check, 22:25 UTC:** The certificate is valid, but the custom domain
serves **SmplCache Live** (`service: smplcache-live`, commit `810fc7cf0d99`).
The user's Render screenshot lists `smplcache-live.onrender.com` as the target.
Create/verify the separate Simplex service first, then move this custom-domain
association to it and align DNS with that service's actual hostname. Do not
replace or rename the existing SmplCache application to perform this migration.
See the [application-identity receipt](verification/2026-11-02-domain-service-mismatch.json).

| GoDaddy field | Value |
| --- | --- |
| Type | `CNAME` |
| Name / Host | `smplxnf` (within the `anomalon.com` zone) |
| Value / Target | Actual assigned Render hostname, without `https://` or a path |
| TTL | 600 seconds if available, otherwise provider default |

Inspect any existing record for this name before replacing it. Leave unrelated
zone records unchanged. Verify the custom domain in Render and wait for its
certificate to become valid. Do not bypass certificate errors.
Provider references: [Render custom domains](https://render.com/docs/custom-domains),
[Render DNS configuration](https://render.com/docs/configure-other-dns),
[GoDaddy CNAME fields](https://www.godaddy.com/help/add-a-cname-record-19236).

## Repeatable HTTP smoke

Requires only Python 3.10+ standard library; no application imports or credentials.

```sh
python scripts/http_smoke.py https://ACTUAL-HOST.onrender.com --output render-http.json
python scripts/http_smoke.py https://smplxnf.anomalon.com --output public-http.json
# Small, bounded concurrency probe: 5 GETs then 10 POSTs across two clients.
python scripts/http_smoke.py https://smplxnf.anomalon.com --workers 2 --repeats 2 --output public-concurrent.json
```

The script verifies `/healthz`, the HTML workbench, JavaScript and CSS assets,
and `/api/presets`. It submits full preset objects to:

| Endpoint | Preset and semantic check |
| --- | --- |
| `/api/relational/normalize` | `ecommerce`: lossless chase; `lossy_decomposition`: spurious tuple witness |
| `/api/bqnf/simulate` | `financial_ledger`: North total 280 and count 4 |
| `/api/compiler/lower` | `employee_bcnf`: verified SQLite, trigger SQL and counterexamples |
| `/api/ai/lossledger` | `rag_research_context`: admission, token conservation and ledger integrity |

It records HTTP status, elapsed time and response hashes, validates HTTPS
certificates normally, rejects redirects as passing results, and exits nonzero
on failure. If health fails, later checks are explicitly skipped. A DNS failure
provides no TLS verdict. The elapsed times include client/network costs; record
them without claiming an SLA. Source identity must be checked separately in Render.

## Browser acceptance

On the public HTTPS origin, execute the default relational preset and the lossy
counterexample preset; inspect the resulting keys, decomposition and chase.
Run streaming with cochain lookup on and off; check logs, region-labelled
buckets and totals against API results. Run compiler lowering and inspect all
three output tabs. Run AI projection and check conservation and ledger output.
Open the quickstart tab, check developer links, inspect browser errors, and
inspect layout at desktop and narrow viewport sizes. Record the URL, deployed
SHA, time, screenshots, observed results and any remaining failures.

Localhost results establish local behavior only. The deployment gate remains
open until these checks pass on the public custom domain.
12 changes: 6 additions & 6 deletions docs/MVP_SELECTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The objective of this specification is to define, evaluate, and architect the si
2. Enable an external developer to clone the repository, install the package via standard tooling, and import the core normal-form logic into their own database, compiler, or AI workflows in under fifteen minutes to support the author's technical resume.

### 1.2 The Production Vision on Render
The application is provisioned as a lightweight, production-ready Web Service on Render bound to the custom hostname `smplxnf.anomalon.com`. Operating under a stateless ASGI process model powered by FastAPI and Uvicorn, the service serves:
The application is designed for a lightweight Web Service on Render bound to the custom hostname `smplxnf.anomalon.com`. Public provisioning and HTTPS verification remain separate gates; see [current status](PROJECT_STATUS.md). Operating under a stateless ASGI process model powered by FastAPI and Uvicorn, the service serves:
- A responsive, high-contrast single-page application (SPA) dashboard styled with modern systems-grade typography and Tailwind CSS.
- Strongly typed REST endpoints exposing relational synthesis, Tableau Chase verification, streaming CDC delta repair, 4-layer NF-IR compilation to SQLite triggers and Python guards, and AI context compression with Merkle LossLedger generation.
- Sub-50 millisecond algorithmic execution latencies for typical schemas and streams, executing purely in-process with zero external database dependencies.
Expand Down Expand Up @@ -601,15 +601,15 @@ services:
```

#### 5.3.2 Subdomain Routing via CNAME
1. **Render Hostname:** The service receives an internal endpoint: `smplxnf-studio.onrender.com`.
1. **Render Hostname:** Record the actual assigned public `onrender.com` endpoint from the service dashboard. `smplxnf-studio.onrender.com` below is an example, not a verified assignment.
2. **DNS Configuration:** In the DNS control panel for `anomalon.com`, a canonical name record is created:
```text
smplxnf.anomalon.com. CNAME smplxnf-studio.onrender.com.
```
3. **Automated TLS Termination:** Render automatically provisions and renews a Let's Encrypt SSL/TLS certificate for `smplxnf.anomalon.com`.

#### 5.3.3 Operational Bounds & Resource Footprint
- **Memory Footprint:** The complete process (FastAPI + Uvicorn + `normal_forms` libraries) consumes approximately 45MB of RAM at idle, fitting comfortably within Render's 512MB entry tier.
- **Memory Footprint:** The original design estimated approximately 45MB at idle. No retained production measurement establishes this figure; measure memory on the deployed instance.
- **CPU & Latency Profile:** Core synthesis, Tableau Chase fixed-point calculation, and trigger compilation execute in 5ms to 35ms on standard cloud vCPUs.
- **Cold-Start Latency:** Process startup takes approximately 1.2 seconds, ensuring rapid recovery on cold instances.

Expand Down Expand Up @@ -847,17 +847,17 @@ In compliance with the project Claim Hygiene standard, all architectural evaluat
4. Does not assert that 3NF or BCNF normalization eliminates application-level anomalies outside declared functional dependencies.

### 7.3 Narrowest Defensible Claim
In the declared discrete Python implementation, the relational synthesis algorithms, Chase tableau procedures, BQNF delta accumulation, and 4-layer NF-IR pipeline execute deterministically and pass all 136 automated tests in `simplex-normal-forms/tests/`.
The original MVP handoff reported 136 pytest items (89 unittest methods). Subsequent correctness and packaging work was merged in PRs #18–19, with 232 tests passing in premerge verification and hosted CI passing on merged `da498e5`. These are bounded implementation checks, not certification of every contract or a live deployment. See [current evidence and scope](PROJECT_STATUS.md).

### 7.4 Next Test Needed
Implement the FastAPI presentation prototype in `web/app.py`, deploy the service to Render under `smplxnf.anomalon.com`, and execute automated HTTP end-to-end integration tests measuring sub-200 millisecond response latencies across synthesis, streaming simulation, and compiler endpoints.
The FastAPI presentation prototype is implemented and PRs #17–19 are merged. Inspect/provision the Render service, verify its assigned hostname, hand off the exact CNAME target to the user, then verify custom-domain TLS and all four workbenches. Use [DEPLOYMENT.md](DEPLOYMENT.md) and `scripts/http_smoke.py`; record measured latency rather than treating the original sub-200 ms target as an established result.

---

## 8. Conclusion & Actionable Execution Sequence

1. **Approved Architecture:** Option E (Simplex-NF Studio) is established as the single canonical MVP for `smplxnf.anomalon.com`.
2. **Immediate Execution Phase:**
2. **Original implementation milestones (now implemented; live deployment pending):**
- **M2 (Web Prototype & Deployment):** Author `pyproject.toml`, implement `web/app.py`, author `render.yaml`, and build the responsive single-page studio dashboard.
- **M3 (Documentation & Import Guide):** Author comprehensive `docs/IMPORT_GUIDE.md` and update `README.md` with complete installation and code usage instructions.
- **M4 (Automated Tests & Verification):** Add test suites covering API endpoints, UI rendering, and external package import workflows.
Loading
Loading