@askexenow/exe-os 0.9.362 → 0.9.365

package/deploy/compose/generate-env.ts

@@ -18,7 +18,7 @@ const EXE_BUILD_RELEASE_TAG = "v0.1.0";
 // Bug 58840873: pin exe-auth to the manifest-pinned tag so a generated .env never
 // lets compose fall back to its (stale) hardcoded default image. MUST equal the
 // AUTH_IMAGE_TAG tag in deploy/stack-manifests/v0.9.json and the compose default.
-const AUTH_RELEASE_TAG = "v0.2.0";
+const AUTH_RELEASE_TAG = "v0.5.0";
 
 const POSTGRES_USER = "exe";
 const POSTGRES_DB = "exedb";
@@ -27,7 +27,11 @@ const CLICKHOUSE_USER = "exe";
 export const CRM_IMAGE_TAG = `${REGISTRY}/exe-crm:${CRM_RELEASE_TAG}`;
 const CRM_HOST_PORT = "3000";
 export const WIKI_IMAGE_TAG = `${REGISTRY}/exe-wiki:${WIKI_RELEASE_TAG}`;
-const WIKI_DB_SCHEMA = "wiki";
+// Bug 2a8d3003: the wiki's data lives in `public` and generated .env files must say
+// so. This constant used to be "wiki", which meant every freshly generated stack
+// pinned the wiki to an empty schema — Prisma bootstraps it silently rather than
+// erroring, so the wiki simply comes up with no users and no documents.
+const WIKI_DB_SCHEMA = "public";
 const WIKI_VECTOR_DB = "exeOsMcp";
 const WIKI_HOST_PORT = "3001";
 export const EXE_OS_IMAGE_TAG = `${REGISTRY}/exe-os:${EXED_RELEASE_TAG}`;
@@ -42,6 +46,47 @@ const GATEWAY_WS_HOST_PORT = "3101";
 const RANDOM_SECRET_16 = 16;
 const RANDOM_SECRET_32 = 32;
 const RANDOM_SECRET_48 = 48;
+// Centralized role administration (e51ca54c §10.6b). Emitted verbatim into both
+// the generated customer .env and the checked-in .env.example so a fresh install
+// STATES its permissions posture instead of inheriting one silently.
+//
+// exe-crm#102 / exe-wiki#45 make managed permissions REQUIRED by default in the
+// apps, so an unmanaged first login can no longer mint its own admin. Those
+// defaults are kept. What a fresh install needs in addition is a legitimate way
+// to seat its FIRST admin, and for the CRM that way is EXE_CRM_ADMIN_EMAIL: the
+// boot-time WorkspaceBootstrapService seeds that user, so the intended owner is
+// an EXISTING user by the time they sign in and the first-login refusal never
+// applies to them. Leave it empty and the seed silently throws (onModuleInit
+// swallows it), after which nobody can ever get in.
+const MANAGED_PERMS_ENV_BLOCK = [
+  "# --- Centralized role administration (permissions) ---",
+  "# The apps refuse to let an unmanaged first login mint its own admin",
+  "# (exe-crm#102 / exe-wiki#45). Both flags below are therefore left at their",
+  "# SECURE default of true, stated explicitly rather than inherited silently.",
+  "#",
+  "# Because of that, a fresh CRM gets its first admin from EXE_CRM_ADMIN_EMAIL",
+  "# in the CRM section below — NOT from whoever signs in first. That user is",
+  "# seeded at boot, so their sign-in is an existing-user login and is allowed;",
+  "# every OTHER unmanaged first login is still refused. If you leave",
+  "# EXE_CRM_ADMIN_EMAIL empty, the seed silently does not happen and the CRM",
+  "# cannot be bootstrapped at all. The wiki does not need this: its first admin",
+  "# comes from POST /system/enable-multi-user, authorised by WIKI_AUTH_TOKEN.",
+  "CRM_REQUIRE_MANAGED_PERMS=true",
+  "WIKI_REQUIRE_MANAGED_PERMS=true",
+  "#",
+  "# MANAGED MODE — roles set ONLY in the Exe dashboard. Empty means unmanaged:",
+  "# no token can carry permissions for an org that was never named. To adopt it:",
+  "#   EXE_ORG_ID=<org id from the Exe dashboard>",
+  "#   EXE_ORG_WORKSPACE_ID=<the org's canonical ACTIVE CRM workspace>",
+  "# EXE_ORG_WORKSPACE_ID must ALREADY EXIST and have a legitimate admin, because",
+  "# managed users join THAT workspace instead of creating their own. That is why",
+  "# managed mode cannot be the shipped default: on a fresh stack the workspace",
+  "# does not exist yet, so its id is unknowable at install time. Bootstrap the",
+  "# stack first, then set these and redeploy. The wiki needs only EXE_ORG_ID.",
+  "EXE_ORG_ID=",
+  "EXE_ORG_WORKSPACE_ID=",
+];
+
 const LICENSE_KEY_COMMENT = "# injected by deploy_client";
 const MANUAL_VALUE_COMMENT = "# SET_MANUALLY";
 const EXAMPLE_LICENSE_KEY = "CHANGEME_EXE_LICENSE_KEY";
@@ -165,15 +210,34 @@ export function generateEnv(options: GenerateEnvOptions): string {
     "# resolved GOTRUE_DISABLE_SIGNUP value above (bug d6f980c1).",
     `AUTH_DISABLE_SIGNUP=${disableSignup}`,
     "",
+    ...MANAGED_PERMS_ENV_BLOCK,
+    "",
     "# --- CRM ---",
     `CRM_IMAGE_TAG=${CRM_IMAGE_TAG}`,
     `CRM_SERVER_URL=https://crm.${normalizedDomain}`,
     `CRM_APP_SECRET=${randomSecret(RANDOM_SECRET_48)}`,
     `EXE_CRM_ADMIN_TOKEN=${randomSecret(RANDOM_SECRET_48)}`,
+    // The CRM's first admin. Seeded into core."user" at boot by
+    // WorkspaceBootstrapService, which is what makes that person an EXISTING
+    // user whose sign-in is allowed while every other unmanaged first login is
+    // refused (e51ca54c §10.6b). It cannot be generated — it must be a real
+    // mailbox that also exists in GoTrue — so it ships as SET_MANUALLY rather
+    // than as a random secret or a guessed admin@<domain>.
+    MANUAL_VALUE_COMMENT,
+    "EXE_CRM_ADMIN_EMAIL=CHANGEME_ADMIN_EMAIL",
     `CRM_HOST_PORT=${CRM_HOST_PORT}`,
     "",
     "# --- Wiki ---",
     `WIKI_IMAGE_TAG=${WIKI_IMAGE_TAG}`,
+    "# Bug 2a8d3003 — DO NOT change this without migrating the data first.",
+    "# The wiki's users / workspaces / workspace_documents live in `public`. Point it at a",
+    "# different schema and Prisma will NOT error: it finds no tables, assumes a fresh",
+    "# database, creates empty ones, and the wiki comes up with zero documents and the",
+    "# admin locked out. It looks exactly like catastrophic data loss while every row is",
+    "# still sitting safely in `public`. That misread has a very expensive next step —",
+    "# restoring a backup over good data. This value used to default to `wiki`, and the",
+    "# only thing holding production together was a host-local compose override.",
+    "# exe-wiki-schema-guard blocks the boot if you get this wrong.",
     `WIKI_DB_SCHEMA=${WIKI_DB_SCHEMA}`,
     `WIKI_VECTOR_DB=${WIKI_VECTOR_DB}`,
     `WIKI_AUTH_TOKEN=${randomSecret(RANDOM_SECRET_48)}`,
@@ -415,19 +479,41 @@ export function generateExampleEnv(): string {
     "AUTH_SERVER_NAME=auth.CHANGEME_DOMAIN",
     "AUTH_CORS_ORIGIN=https://CHANGEME_DOMAIN",
     "AUTH_DEFAULT_PRODUCT=AUTH",
+    '# Brand word after the gold "EXE" in the login logo (exe-auth v0.5.0+). One',
+    "# identity for the whole front door — ?product= never rebrands the page. Leave",
+    '# unset for the stack default "EXE INTELLIGENCE"; white-label deploys set their',
+    "# own word here.",
+    "#AUTH_BRAND_NAME=INTELLIGENCE",
     "# Bug 5960ebb1: invite-only — mirror GOTRUE_DISABLE_SIGNUP so the auth SPA hides",
     "# the sign-up UI/route instead of showing a form that always fails.",
     "AUTH_DISABLE_SIGNUP=true",
     "",
+    ...MANAGED_PERMS_ENV_BLOCK,
+    "",
     "# --- CRM ---",
     `CRM_IMAGE_TAG=${CRM_IMAGE_TAG}`,
     "CRM_SERVER_URL=https://crm.CHANGEME_DOMAIN",
     "CRM_APP_SECRET=CHANGEME_CRM_APP_SECRET",
     "EXE_CRM_ADMIN_TOKEN=CHANGEME_EXE_CRM_ADMIN_TOKEN",
+    "# The CRM's first admin — seeded at boot by WorkspaceBootstrapService, which",
+    "# is what makes that person an EXISTING user whose sign-in is allowed while",
+    "# every other unmanaged first login is refused (e51ca54c §10.6b). Must be a",
+    "# real mailbox that also exists in GoTrue, so it cannot be generated.",
+    MANUAL_VALUE_COMMENT,
+    "EXE_CRM_ADMIN_EMAIL=CHANGEME_ADMIN_EMAIL",
     `CRM_HOST_PORT=${CRM_HOST_PORT}`,
     "",
     "# --- Wiki ---",
     `WIKI_IMAGE_TAG=${WIKI_IMAGE_TAG}`,
+    "# Bug 2a8d3003 — DO NOT change this without migrating the data first.",
+    "# The wiki's users / workspaces / workspace_documents live in `public`. Point it at a",
+    "# different schema and Prisma will NOT error: it finds no tables, assumes a fresh",
+    "# database, creates empty ones, and the wiki comes up with zero documents and the",
+    "# admin locked out. It looks exactly like catastrophic data loss while every row is",
+    "# still sitting safely in `public`. That misread has a very expensive next step —",
+    "# restoring a backup over good data. This value used to default to `wiki`, and the",
+    "# only thing holding production together was a host-local compose override.",
+    "# exe-wiki-schema-guard blocks the boot if you get this wrong.",
     `WIKI_DB_SCHEMA=${WIKI_DB_SCHEMA}`,
     `WIKI_VECTOR_DB=${WIKI_VECTOR_DB}`,
     "WIKI_AUTH_TOKEN=CHANGEME_WIKI_AUTH_TOKEN",

package/deploy/compose/status.sh

@@ -47,6 +47,36 @@ docker exec exe-db psql -U exe -d exedb -c "SELECT schemaname, COUNT(*) as table
 
 echo ""
 
+# Bug 2a8d3003: which schema is the wiki ACTUALLY running against?
+# exe-wiki-schema-guard gates `docker compose up`, but compose dependencies are not
+# evaluated by `docker start exe-wiki` or by restart:unless-stopped after a reboot —
+# so a wiki can still come back on the wrong schema without the guard ever running.
+# This makes that visible on demand. Read from the LIVE container, never from .env:
+# a docker-compose.override.yml can rewrite DATABASE_URL and .env would not show it.
+echo "Wiki schema (bug 2a8d3003):"
+WIKI_URL=$(docker inspect exe-wiki --format '{{range .Config.Env}}{{println .}}{{end}}' 2>/dev/null | sed -n 's/^DATABASE_URL=//p')
+if [[ -z "$WIKI_URL" ]]; then
+  echo "  ⚠️  exe-wiki not running — cannot determine schema"
+else
+  WIKI_SCHEMA=$(printf '%s' "$WIKI_URL" | sed -n 's/.*[?&]schema=\([^&]*\).*/\1/p')
+  [[ -z "$WIKI_SCHEMA" ]] && WIKI_SCHEMA="public"
+  COUNTS=$(docker exec exe-db psql -U exe -d exedb -tA -F' ' -c \
+    "SELECT COALESCE((SELECT count(*) FROM ${WIKI_SCHEMA}.users), -1),
+            COALESCE((SELECT count(*) FROM ${WIKI_SCHEMA}.workspace_documents), -1)" 2>/dev/null)
+  W_USERS=$(echo "$COUNTS" | awk '{print $1}')
+  W_DOCS=$(echo "$COUNTS" | awk '{print $2}')
+  if [[ "${W_USERS:-0}" -gt 0 || "${W_DOCS:-0}" -gt 0 ]]; then
+    echo -e "  ${GREEN}✅${NC} schema '$WIKI_SCHEMA' — users=$W_USERS documents=$W_DOCS"
+  else
+    echo -e "  ${RED}❌${NC} schema '$WIKI_SCHEMA' has NO users and NO documents — the wiki is"
+    echo -e "     serving an EMPTY schema. This is a config fault, not data loss."
+    echo -e "     ${YELLOW}DO NOT RESTORE FROM BACKUP.${NC} Check WIKI_DB_SCHEMA in .env and any"
+    echo -e "     docker-compose.override.yml, then: docker compose up -d exe-wiki"
+  fi
+fi
+
+echo ""
+
 # Disk/Memory
 echo "Resources:"
 echo "  RAM: $(free -h 2>/dev/null | awk '/^Mem:/ {print $3 "/" $2}' || echo 'N/A')"

package/deploy/compose/uptime-check.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # exe-os uptime check — runs every 5 min via cron.
-# Checks: CRM, Gateway, WhatsApp state, Postgres.
+# Checks: CRM, Gateway, WhatsApp state, Postgres, wiki schema (bug 2a8d3003).
 # Writes JSONL to /opt/exe-stack/uptime.jsonl.
 # Logs ALERT to stderr (captured by cron/syslog) on any failure.
 #
@@ -92,10 +92,40 @@ check_whatsapp() {
 # --- Run checks ---
 NOW=$(ts)
 
+# Bug 2a8d3003: is the wiki serving the schema its data is actually in?
+# exe-wiki-schema-guard gates `docker compose up`, but nothing evaluates compose
+# dependencies on `docker start exe-wiki` or on restart:unless-stopped after a
+# reboot. Those paths can bring the wiki back on an empty schema with no guard run
+# and no error anywhere — silent-empty, which is the whole failure mode. Checking it
+# here bounds how long that can go unnoticed to one cron interval.
+# Reads the LIVE container env, not .env: a compose override can rewrite DATABASE_URL.
+check_wiki_schema() {
+  local url schema counts users docs
+  url=$(docker inspect exe-wiki --format '{{range .Config.Env}}{{println .}}{{end}}' 2>/dev/null \
+    | sed -n 's/^DATABASE_URL=//p')
+  [[ -z "$url" ]] && { echo "skip"; return; }
+  schema=$(printf '%s' "$url" | sed -n 's/.*[?&]schema=\([^&]*\).*/\1/p')
+  [[ -z "$schema" ]] && schema="public"
+  # Only ever interpolate a bare identifier into SQL.
+  [[ ! "$schema" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] && { echo "fail:bad-schema-name"; return; }
+  counts=$(docker exec exe-db psql -U "${POSTGRES_USER:-exe}" -d "${POSTGRES_DB:-exedb}" -tA -F' ' -c \
+    "SELECT COALESCE((SELECT count(*) FROM ${schema}.users), 0),
+            COALESCE((SELECT count(*) FROM ${schema}.workspace_documents), 0)" 2>/dev/null)
+  [[ -z "$counts" ]] && { echo "skip"; return; }
+  users=$(echo "$counts" | awk '{print $1}')
+  docs=$(echo "$counts" | awk '{print $2}')
+  if [[ "${users:-0}" -gt 0 || "${docs:-0}" -gt 0 ]]; then
+    echo "ok:$schema"
+  else
+    echo "fail:empty-schema-$schema"
+  fi
+}
+
 crm_status=$(check_http "CRM" "http://127.0.0.1:3000/healthz")
 gateway_status=$(check_http "Gateway" "http://127.0.0.1:3100/health")
 whatsapp_status=$(check_whatsapp)
 postgres_status=$(check_postgres)
+wiki_schema_status=$(check_wiki_schema)
 
 # --- Determine overall health ---
 overall="ok"
@@ -117,11 +147,18 @@ if [[ "$postgres_status" != "ok" ]]; then
   overall="critical"
   alerts="${alerts}Postgres($postgres_status) "
 fi
+# A wiki serving an empty schema is critical: it looks like total data loss to
+# whoever opens it, and the wrong reflex (restore from backup) destroys the real
+# rows still sitting in the other schema. Say so in the alert itself.
+if [[ "$wiki_schema_status" == fail:* ]]; then
+  overall="critical"
+  alerts="${alerts}WikiSchema($wiki_schema_status — CONFIG FAULT, DO NOT RESTORE FROM BACKUP, see bug 2a8d3003) "
+fi
 
 # --- Write JSONL ---
 # Single-line JSON — no jq dependency required
 ENTRY=$(cat <<JSONEOF
-{"ts":"${NOW}","overall":"${overall}","crm":"${crm_status}","gateway":"${gateway_status}","whatsapp":"${whatsapp_status}","postgres":"${postgres_status}"}
+{"ts":"${NOW}","overall":"${overall}","crm":"${crm_status}","gateway":"${gateway_status}","whatsapp":"${whatsapp_status}","postgres":"${postgres_status}","wiki_schema":"${wiki_schema_status}"}
 JSONEOF
 )
 

package/deploy/compose/wiki-schema-guard.sh

@@ -0,0 +1,302 @@
+#!/usr/bin/env bash
+# exe-wiki schema guard — bug 2a8d3003.
+#
+# THE FAILURE THIS EXISTS TO PREVENT
+# ----------------------------------
+# exe-wiki reaches Postgres through a DATABASE_URL whose `?schema=` param decides
+# which schema it lives in. Production's real content (users, workspaces,
+# workspace_documents) is in `public`. A stale default of `?schema=wiki` — or a
+# WIKI_DB_SCHEMA typo, or a dropped docker-compose.override.yml — points the wiki at
+# a DIFFERENT schema. Prisma does not complain: it sees no tables, treats it as a
+# fresh database, bootstraps empty ones, and the wiki comes up looking completely
+# wiped. Admin locked out, zero documents. The real rows are fine, sitting in the
+# other schema, but anyone debugging that at speed reaches for a restore and turns a
+# config mistake into actual data loss.
+#
+# Silent-empty is the failure mode. This script makes it loud.
+#
+# WHAT IT DOES
+# ------------
+# Runs as a one-shot container BEFORE exe-wiki starts (compose service
+# exe-wiki-schema-guard, gated by service_completed_successfully). It:
+#   1. Parses the RESOLVED schema out of the same DATABASE_URL exe-wiki will use.
+#   2. Logs that schema plus live user / workspace / document counts.
+#   3. Compares them against the last passing boot, recorded in
+#      `meta.wiki_schema_guard` — deliberately OUTSIDE the wiki's own schema, so
+#      flipping schemas cannot also flip the evidence.
+#   4. Exits non-zero, with the remediation spelled out, if the wiki is about to
+#      boot into a schema with zero workspaces when the last boot recorded more.
+#
+# It never writes to wiki tables and never drops anything. Worst case it refuses to
+# let the wiki start, which is strictly better than presenting an empty wiki.
+#
+# ESCAPE HATCH
+# ------------
+# A genuine, intentional schema migration will trip the guard — that is the point.
+# Move the data across first and the guard passes on its own (the new schema is no
+# longer empty). If you really do mean to start empty, WIKI_SCHEMA_GUARD=warn for a
+# single boot logs the warning, proceeds, and adopts the new counts as the baseline.
+# WIKI_SCHEMA_GUARD=off disables the check entirely and is not recommended.
+#
+# Required env: DATABASE_URL (same value exe-wiki receives), PGPASSWORD.
+# Optional env: WIKI_SCHEMA_GUARD=enforce|warn|off  (default: enforce)
+
+set -uo pipefail
+
+MODE="${WIKI_SCHEMA_GUARD:-enforce}"
+LOG_PREFIX="[wiki-schema-guard]"
+
+log() { echo "$LOG_PREFIX $*"; }
+
+banner() {
+  echo "" >&2
+  echo "$LOG_PREFIX ============================================================" >&2
+  echo "$LOG_PREFIX  $1" >&2
+  echo "$LOG_PREFIX ============================================================" >&2
+  while IFS= read -r line; do echo "$LOG_PREFIX  $line" >&2; done <<< "$2"
+  echo "$LOG_PREFIX ============================================================" >&2
+  echo "" >&2
+}
+
+# Hard stop: the guard cannot do its job at all (bad config, no database). Never
+# downgraded by warn mode — a guard that cannot verify must not vouch.
+die() {
+  banner "REFUSING TO START exe-wiki" "$1"
+  exit 1
+}
+
+# The silent-empty tripwire. warn mode logs and lets the boot proceed so an operator
+# can deliberately accept a new state; enforce mode (the default) stops the boot.
+trip() {
+  if [[ "$MODE" == "enforce" ]]; then
+    banner "REFUSING TO START exe-wiki — WIKI WOULD COME UP EMPTY" "$1"
+    exit 1
+  fi
+  banner "WARNING: WIKI WILL COME UP EMPTY" "$1"
+  log "WIKI_SCHEMA_GUARD=$MODE — proceeding anyway and accepting the new counts as the baseline."
+}
+
+if [[ "$MODE" == "off" ]]; then
+  log "WIKI_SCHEMA_GUARD=off — skipping. The wiki may boot against an empty schema undetected."
+  exit 0
+fi
+
+if [[ -z "${DATABASE_URL:-}" ]]; then
+  die "DATABASE_URL is empty. The guard cannot determine which schema exe-wiki
+would use, so it cannot prove the wiki will find its data."
+fi
+
+# --- Resolve the schema exactly the way the wiki's client will ---
+# postgres://user:pass@host:port/db?schema=NAME&sslmode=disable
+SCHEMA="$(printf '%s' "$DATABASE_URL" | sed -n 's/.*[?&]schema=\([^&]*\).*/\1/p')"
+if [[ -z "$SCHEMA" ]]; then
+  # No explicit param: Postgres/Prisma fall back to the role search_path, which in
+  # practice resolves to `public`. Record that we INFERRED it — an inferred schema is
+  # exactly the ambiguity bug 2a8d3003 was about.
+  SCHEMA="public"
+  RESOLUTION="inferred (no ?schema= param in DATABASE_URL — resolution depends on the role search_path)"
+else
+  RESOLUTION="explicit (?schema=$SCHEMA)"
+fi
+
+# Reject anything that is not a plain identifier before it reaches SQL.
+if [[ ! "$SCHEMA" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+  die "Resolved schema '$SCHEMA' is not a valid bare identifier.
+Refusing to interpolate it into SQL. Check WIKI_DB_SCHEMA in .env."
+fi
+
+log "resolved schema: $SCHEMA  [$RESOLUTION]"
+
+# libpq does NOT understand `schema=` as a URI parameter — Prisma consumes it before
+# connecting, but psql errors out with "invalid URI query parameter". Strip it, then
+# tidy up the leftover separators so the remaining query string stays well-formed.
+PSQL_URL="$(printf '%s' "$DATABASE_URL" \
+  | sed -e 's/\([?&]\)schema=[^&]*&/\1/' -e 's/[?&]schema=[^&]*$//')"
+
+psql_q() {
+  psql "$PSQL_URL" -X -q -t -A -v ON_ERROR_STOP=1 -c "$1" 2>/dev/null
+}
+
+# Compose already gates this service on exe-db being healthy, but "healthy" and
+# "accepting this connection right now" are not the same thing. This container runs
+# with restart: "no", so a single transient refusal would leave the wiki down until
+# someone noticed. Retry before giving up.
+CONNECTED=0
+for attempt in 1 2 3 4 5; do
+  if psql_q "SELECT 1" >/dev/null; then CONNECTED=1; break; fi
+  log "postgres not answering yet (attempt $attempt/5) — retrying in 3s"
+  sleep 3
+done
+if [[ "$CONNECTED" -ne 1 ]]; then
+  die "Cannot reach Postgres with the wiki's DATABASE_URL after 5 attempts. The guard
+cannot verify the schema, so it will not vouch for the wiki's data."
+fi
+
+# --- Counting ----------------------------------------------------------------
+# Count a table, or emit "-" when the table does not exist yet. "-" and 0 are both
+# "empty" for the tripwire, but worth distinguishing in the log: "-" means Prisma
+# has not bootstrapped this schema at all yet.
+show() { if [[ "$1" == "-" ]]; then printf 'no-such-table'; else printf '%s' "$1"; fi; }
+n_of() { if [[ "$1" == "-" ]]; then printf '0'; else printf '%s' "$1"; fi; }
+
+count_in() {
+  local schema="$1" table="$2" out
+  out="$(psql_q "SELECT CASE WHEN to_regclass('${schema}.${table}') IS NULL THEN '-'
+                             ELSE (SELECT count(*)::text FROM ${schema}.${table}) END")"
+  printf '%s' "${out:--}"
+}
+
+USERS="$(count_in "$SCHEMA" users)"
+WORKSPACES="$(count_in "$SCHEMA" workspaces)"
+DOCUMENTS="$(count_in "$SCHEMA" workspace_documents)"
+
+log "live counts in '$SCHEMA': users=$(show "$USERS") workspaces=$(show "$WORKSPACES") workspace_documents=$(show "$DOCUMENTS")"
+
+# --- What counts as "the wiki really lives here" -------------------------------
+# Deliberately NOT `workspaces`. deploy/compose/init-db.sql creates its OWN
+# wiki.workspaces / wiki.workspace_documents projection tables for exe-os's
+# projection-worker, and the worker writes rows into them. So the vestigial `wiki`
+# schema on production reports workspaces=1 while containing none of the Prisma
+# wiki's actual content. A tripwire keyed on `workspaces` would wave that through —
+# the exact case this guard exists to catch.
+#
+# `users` is the honest signal: it holds the admin account, exe-os never writes it,
+# and zero users means nobody can log in. `workspace_documents` corroborates.
+OCCUPIED=0
+if [[ "$(n_of "$USERS")" -gt 0 || "$(n_of "$DOCUMENTS")" -gt 0 ]]; then OCCUPIED=1; fi
+
+# --- Stateless cross-schema check ----------------------------------------------
+# The strongest evidence needs no history: if THIS schema is empty but another
+# schema in the same database holds a populated wiki, we are pointed at the wrong
+# one right now. This fires on the very first run, before any watermark exists —
+# which matters, because a guard whose first boot lands on the empty schema would
+# otherwise record that as its baseline and bless it forever.
+RIVAL=""; RIVAL_USERS=0; RIVAL_DOCS=0
+if [[ "$OCCUPIED" -eq 0 ]]; then
+  # Candidate = any schema carrying BOTH wiki tables. Counting rows in a
+  # dynamically-named schema needs one query per candidate, so enumerate first.
+  CANDIDATES="$(psql_q "SELECT table_schema
+    FROM information_schema.tables
+    WHERE table_name IN ('users', 'workspace_documents')
+      AND table_schema NOT IN ('pg_catalog', 'information_schema', '${SCHEMA}')
+      AND table_schema NOT LIKE 'pg\\_%'
+    GROUP BY table_schema
+    HAVING count(DISTINCT table_name) = 2
+    ORDER BY table_schema")"
+  while IFS= read -r cand; do
+    [[ -z "$cand" ]] && continue
+    [[ ! "$cand" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] && continue
+    c_users="$(n_of "$(count_in "$cand" users)")"
+    c_docs="$(n_of "$(count_in "$cand" workspace_documents)")"
+    if [[ "$c_users" -gt 0 || "$c_docs" -gt 0 ]]; then
+      RIVAL="$cand"; RIVAL_USERS="$c_users"; RIVAL_DOCS="$c_docs"
+      break
+    fi
+  done <<< "$CANDIDATES"
+fi
+
+# --- Watermark, stored outside the wiki's schema -------------------------------
+# State inside the wiki's own schema would vanish along with the data the moment
+# someone flips the schema, leaving nothing to compare against.
+#
+# Every bookkeeping statement is checked. Under `set -uo pipefail` (no -e) an
+# unchecked psql failure would sail past and the guard would print OK having
+# verified nothing — a guard that fails open silently is worse than no guard.
+run_sql() {
+  local sql="$1" err
+  if ! err="$(psql "$PSQL_URL" -X -q -t -A -v ON_ERROR_STOP=1 -c "$sql" 2>&1)"; then
+    log "WARNING: guard bookkeeping failed — $err"
+    return 1
+  fi
+  return 0
+}
+
+WATERMARK_OK=1
+run_sql "CREATE SCHEMA IF NOT EXISTS meta" || WATERMARK_OK=0
+run_sql "CREATE TABLE IF NOT EXISTS meta.wiki_schema_guard (
+           id              boolean PRIMARY KEY DEFAULT true CHECK (id),
+           schema_name     text        NOT NULL,
+           users           bigint      NOT NULL,
+           workspaces      bigint      NOT NULL,
+           documents       bigint      NOT NULL,
+           observed_at     timestamptz NOT NULL DEFAULT now()
+         )" || WATERMARK_OK=0
+
+PREV=""; PREV_SCHEMA=""; PREV_USERS=0; PREV_WORKSPACES=0; PREV_DOCUMENTS=0
+if [[ "$WATERMARK_OK" -eq 1 ]]; then
+  PREV="$(psql_q "SELECT schema_name || '|' || users || '|' || workspaces || '|' || documents
+                  FROM meta.wiki_schema_guard WHERE id")"
+fi
+if [[ -n "$PREV" ]]; then
+  PREV_SCHEMA="${PREV%%|*}"; REST="${PREV#*|}"
+  PREV_USERS="${REST%%|*}";  REST="${REST#*|}"
+  PREV_WORKSPACES="${REST%%|*}"
+  PREV_DOCUMENTS="${REST##*|}"
+  log "last recorded: schema='$PREV_SCHEMA' users=$PREV_USERS workspaces=$PREV_WORKSPACES workspace_documents=$PREV_DOCUMENTS"
+elif [[ "$WATERMARK_OK" -eq 1 ]]; then
+  log "no previous record — first guard run against this database."
+fi
+
+# --- The tripwire ---------------------------------------------------------------
+EVIDENCE=""; SUGGEST=""
+if [[ "$OCCUPIED" -eq 0 && -n "$RIVAL" ]]; then
+  EVIDENCE="Schema '$RIVAL' in this SAME database does hold a wiki: users=$RIVAL_USERS,
+workspace_documents=$RIVAL_DOCS. That is almost certainly where your data is."
+  SUGGEST="$RIVAL"
+elif [[ "$OCCUPIED" -eq 0 && -n "$PREV_SCHEMA" ]] \
+  && [[ "$PREV_USERS" -gt 0 || "$PREV_DOCUMENTS" -gt 0 ]]; then
+  EVIDENCE="A previous boot saw users=$PREV_USERS and workspace_documents=$PREV_DOCUMENTS
+in schema '$PREV_SCHEMA'."
+  SUGGEST="$PREV_SCHEMA"
+fi
+
+if [[ -n "$EVIDENCE" ]]; then
+  trip "exe-wiki is about to start against schema '$SCHEMA', which holds NO wiki
+account and NO documents (users=$(show "$USERS"), workspace_documents=$(show "$DOCUMENTS")).
+The wiki would come up looking completely wiped, with the admin locked out.
+
+$EVIDENCE
+
+This is a CONFIGURATION problem, NOT data loss. DO NOT RESTORE FROM BACKUP — the
+rows are still there, and restoring over them is how this becomes real data loss.
+
+Fix the pointer instead:
+  1. Set WIKI_DB_SCHEMA=$SUGGEST in /opt/exe-stack/.env
+  2. Check for a docker-compose.override.yml that rewrites exe-wiki's DATABASE_URL.
+  3. Verify:  docker compose config | grep -A2 'exe-wiki' | grep DATABASE_URL
+  4. Re-run. The guard clears as soon as the wiki points at its data again.
+
+Note: 'workspaces' is NOT proof of life here — exe-os keeps its own projection
+tables in the 'wiki' schema (deploy/compose/init-db.sql), so a schema can report
+workspaces>0 while holding none of the wiki's real content.
+
+If you are INTENTIONALLY migrating to '$SCHEMA', move the rows first and the guard
+clears itself. To accept an empty wiki for exactly one boot:
+  WIKI_SCHEMA_GUARD=warn docker compose up -d exe-wiki"
+fi
+
+if [[ -n "$PREV_SCHEMA" && "$PREV_SCHEMA" != "$SCHEMA" && "$OCCUPIED" -eq 1 ]]; then
+  log "NOTE: schema changed '$PREV_SCHEMA' -> '$SCHEMA' and the new schema is populated. Accepting."
+fi
+
+# --- Record what we saw ---------------------------------------------------------
+# Last-observed, NOT a ratchet. A ratchet would wedge a wiki whose content was
+# legitimately all deleted: it would trip forever with no way back. Recording the
+# real counts means one WIKI_SCHEMA_GUARD=warn boot clears a deliberate emptying,
+# while an accidental schema flip still trips on the very next start.
+if [[ "$WATERMARK_OK" -eq 1 ]]; then
+  run_sql "INSERT INTO meta.wiki_schema_guard (id, schema_name, users, workspaces, documents, observed_at)
+           VALUES (true, '${SCHEMA}', $(n_of "$USERS"), $(n_of "$WORKSPACES"), $(n_of "$DOCUMENTS"), now())
+           ON CONFLICT (id) DO UPDATE SET
+             schema_name = EXCLUDED.schema_name,
+             users       = EXCLUDED.users,
+             workspaces  = EXCLUDED.workspaces,
+             documents   = EXCLUDED.documents,
+             observed_at = now()" \
+    || log "WARNING: watermark not recorded — the cross-schema check still applies next boot."
+else
+  log "WARNING: watermark table unavailable — relying on the cross-schema check alone."
+fi
+
+log "OK — exe-wiki cleared to start against schema '$SCHEMA'."
+exit 0