Move operator notes out of repo, add generic architecture doc

memory/infrastructure.md and memory/build_log.md held environment-
specific details — hostnames, IPs, account names, credentials
retrieval commands, local kubeconfig paths, operational status
notes. These don't belong in a project repo; by convention they
live in private operator notes.

Moved to ~/shorashim-operator-notes/ (private, outside git).

In their place, added deploy/ARCHITECTURE.md — a generic
description of the deployment shape: components, external
dependencies, configuration surface. No hostnames. No IPs.
No account names. Any competent operator can read it and
know how to deploy shorashim to their own infrastructure.

Updated cross-references in AGENTS.md and BUILD_KORBAN.md to
point to "the operator's private notes" instead of memory/.

Project repo is spec + implementation + deployment shape.
Operator notes are the kohen's personal log.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Scott KarpandClaude Opus 4.6 committed 2026-04-21 09:03:57 -04:00
1 parent 2c1ca9116a
commit 66686329ed
3 files changed
+68 -2

No files matched your search

+2 -1
View File
@@ -60,7 +60,8 @@ before writing code. Do not summarize from memory. Read fresh.
## Broken Tablets (Build Log) ## Broken Tablets (Build Log)
Record what broke and how it was fixed. The correction is as important Record what broke and how it was fixed. The correction is as important
as the specification. See `memory/build_log.md` for the full log. as the specification. The full log is kept in the operator's private
notes, outside this repo.
Key corrections from L1 build: Key corrections from L1 build:
- U+05BD (siluq/meteg) misclassified as vowel — moved to TEAMIM_MAP - U+05BD (siluq/meteg) misclassified as vowel — moved to TEAMIM_MAP
+1 -1
View File
@@ -100,7 +100,7 @@ Add to the Principles section:
## Task 3: Record Broken Tablets ## Task 3: Record Broken Tablets
As you build, record what breaks and how it was fixed in `memory/build_log.md`. The correction is as important as the specification. Include: As you build, record what breaks and how it was fixed in the operator's build log (kept outside this repo). The correction is as important as the specification. Include:
- What you expected vs what happened - What you expected vs what happened
- The root cause - The root cause
- The fix - The fix
+65
View File
@@ -0,0 +1,65 @@
# Deployment Architecture
Generic architecture shape for a shorashim deployment. Specifics of a particular deployment (hostnames, IPs, account names, credentials) live in the operator's private notes, not in this repo.
## Components
One Kubernetes namespace runs the following:
| Component | Runtime | Purpose |
|-----------|---------|---------|
| `vav-pipeline` | Elixir/OTP release | Bereishit cycle, ShemaContext, Cloud, Manna, HTTP API (pe'ah, courtyard, chatzer, kodesh) |
| `shoresh-engine` | Haskell binary (sidecar via Erlang Port) | Root activation, te'amim parsing, gematria |
| `talmudic-engine` | SWI-Prolog (sidecar via Unix socket) | 613 mitzvot, 13 middot, kushya generation, teiku |
| `korban-processor` | Python 3.12 (sidecar) | Offering protocol, eish zarah validation |
All four run in the same pod; the vav-pipeline is the main container, the other three are sidecars.
## External dependencies
| Dependency | Purpose | Contract |
|-----------|---------|----------|
| Managed PostgreSQL 17+ | L3 Oral Tradition (append-only) | `DATABASE_URL` env var. Requires SSL. Role with `SELECT, INSERT` only — `UPDATE`, `DELETE` revoked (see migration). |
| Block-storage PersistentVolume | L1 Torah filesystem (read-only, ~1 GiB) | Mount read-only at `/mnt/torah`. SHA-256 hash verified at boot. |
| Block-storage PersistentVolume | Manna provision (read-write, ~100 MiB) | Mount at `/var/lib/shorashim/manna`. Operator writes `today.json` daily. |
| Ingress controller + TLS cert | Public HTTPS access | Cert-manager with Let's Encrypt HTTP-01 is the reference setup. |
| Container registry | Image distribution | Any registry that supports Docker v2 protocol. |
## Kubernetes manifests
Kept in `deploy/k8s/`:
- `namespace.yaml` — the namespace
- `configmap.yaml` — non-secret configuration
- `secrets.yaml` — **template only**; operator fills in `DATABASE_URL`
- `l1-volume.yaml` — PV and PVC for Torah filesystem
- `manna-volume.yaml` — PVC for provision file
- `deployment.yaml` — the pod with 4 containers + init container for migrations
- `service.yaml` — ClusterIP and external LoadBalancer
- `gitea-mcp-deployment.yaml` — separate MCP server for Gitea connector (optional)
- `gitea-mcp-ingress.yaml` — TLS ingress for the MCP server
- `gitea-mcp-secret.yaml` — template for Gitea PAT
- `cert-manager-issuer.yaml` — Let's Encrypt ClusterIssuer
## Containers
Four Dockerfiles in `deploy/docker/`:
- `Dockerfile.vav_pipeline` — multi-stage Elixir 1.16.1 / OTP 26.2.1 release
- `Dockerfile.shoresh_engine` — multi-stage Haskell GHC 9.6.4 / Cabal
- `Dockerfile.talmudic_engine` — SWI-Prolog 9.2.2 with socket server
- `Dockerfile.korban_processor` — Python 3.12.2 slim
## Configuration surface
The system reads three things from its environment:
1. **L1 Torah** — mounted read-only at `$L1_MOUNT_POINT`. Integrity verified at every boot.
2. **Manna provision** — JSON file at `$MANNA_PROVISION_FILE`, written by the kohen/treasurer.
3. **L3 database** — connection string in `$DATABASE_URL`.
Nothing else is configurable. The system obeys Torah (L1 + calendar) for governance and the provision file for resources.
## Seven-day inauguration
Before serving users, run the `shiv'at y'mei milu'im` sequence documented in `KOHEN.md`. Each day validates a specific layer. Partial inauguration is no inauguration.