​

SPEC-019 v1.1 — Environment Resolution Contract (HOST_ENV + PRISM_ENV + MODE_PROFILES)

​

v1.1 change log

• Renamed PRISM_MODE value personal -> local throughout (aligns with dev conventions: .env.local / .env.lan / .env.cloud). Same semantic, better name.
• All other content unchanged from v1.0.

​

Purpose

​

Scope

• Install-time: host probing, mode selection, env-block write to editor MCP configs.
• Runtime: env read, tiered resolution, provenance logging at backend startup.
• Backend, MCP server, installer, and docker-compose files all consume the same resolver surface.

• Secrets management (use OS keychain / vault).
• Per-project config overrides (future).
• Feature flags.

​

The two buckets

​

HOST_ENV — discovered facts about the host

​

PRISM_ENV — Prism’s wiring, chosen per mode

• PRISM_MODE: local | lan | cloud (the one switch everything keys off)

• PRISM_ROOT, PROJECT_ROOT, PRISM_GITHUB_USER, PRISM_FS_MCP_NAME, LOG_DIR, LOG_LEVEL

​

Resolution order (tiered — first tier to answer wins)

1. System facts - socket/platform/filesystem calls.
2. Environment variables - PRISM_* read from process env.
3. Config files - .env, .env., backend/app/config (pydantic BaseSettings).
4. MODE_PROFILES - module-level constant in backend/app/config/env.py. Per-mode fallback dict. Last resort.

​

MODE_PROFILES (the in-code fallback)

MODE_PROFILES: dict[str, dict[str, Any]] = {
    "local": {
        "PRISM_BIND_ADDR": "127.0.0.1",
        "PRISM_BACKEND_PORT": 8765,
        "PRISM_PG_PORT": 5433,
        "PRISM_NEO4J_HTTP_PORT": 7474,
        "PRISM_NEO4J_BOLT_PORT": 7687,
        "PRISM_ALLOWED_ORIGINS": ["http://127.0.0.1:*"],
    },
    "lan": {
        "PRISM_BIND_ADDR": "0.0.0.0",
        "PRISM_BACKEND_PORT": 41765,
        "PRISM_PG_PORT": 45432,
        "PRISM_NEO4J_HTTP_PORT": 47474,
        "PRISM_NEO4J_BOLT_PORT": 47687,
        # ALLOWED_ORIGINS derived from HOST_FQDN at resolve-time
    },
    "cloud": {
        "PRISM_BIND_ADDR": "0.0.0.0",
        "PRISM_BACKEND_PORT": 443,
        # ALLOWED_ORIGINS must be explicit, https-only. Refuse otherwise.
    },
}

​

Provenance logging (mandatory)

CORS allowed_origins=['http://127.0.0.1:*'] (source: profile:local)
PRISM_API_URL=http://server1.home.lan:41765 (source: env)
PRISM_HOST_OS=Darwin (source: system:platform.system())

​

Backend integration surface

# backend/app/config/env.py
class HostEnv: ...
class PrismEnv: ...
def resolve() -> tuple[HostEnv, PrismEnv]: ...

​

install.py integration

1. Probe HOST_ENV (tier-1).
2. Prompt user for PRISM_MODE + override knobs (tier-2 user intent).
3. Merge into MODE_PROFILES[mode] baseline (tier-4).
4. Validate cloud mode has PRISM_WEB_URL https://.
5. Validate lan mode’s PRISM_API_URL is FQDN-shaped (ADR-18).
6. Write flat env block to all 4 editor MCP configs.

​

Migration path (physical-artifact renames)

• docker-compose.personal.yml -> docker-compose.local.yml
• .env.personal -> .env.local (already exists as backend/.env.local for dev; reconcile)
• prism-personal-backend / -postgres / -neo4j container names -> prism-local-*
• NEO4J_AUTH neo4j/prism_personal -> neo4j/prism_local
• install/backend.py BackendMode = Literal["personal","lan","cloud"] -> Literal["local","lan","cloud"]
• install/backend.py DEFAULT_PERSONAL_URL, resolve_personal(), start_personal(), COMPOSE_PERSONAL, DEFAULT_CREDENTIALS (all personal symbols) rename to local
• Existing running local stack: teardown during TODO #70 cutover; fresh up with new names.

​

Test requirements

1. Mode-profile baseline: resolve on empty env -> MODE_PROFILES values for each mode.
2. Tier precedence: env overrides config overrides profile.
3. HOST_ENV probes return expected shape on Darwin/Linux/Windows.
4. ADR-18 FQDN enforcement: lan bare-hostname PRISM_API_URL is rejected at install.
5. Cloud https enforcement: cloud plain-http PRISM_ALLOWED_ORIGINS is rejected at install.
6. Provenance log contains one line per resolved key at startup.

1. Local mode, same-origin fetch: allowed.
2. Local mode, cross-origin from not-allowed port: denied (no ACAO header).
3. Lan mode, cross-origin from allowed Mac FQDN: allowed.
4. Cloud mode, http:// origin: startup refuses to boot backend.

​

Migration path from current code

1. File SPEC-019 v1.0. (done, superseded)
2. File SPEC-019 v1.1 (this). (done)
3. File ADR-19 + ADR-20 (done, superseded) + ADR-21 + ADR-22 (done).
4. TODO #72 (localhost audit) executes first.
5. Implement backend/app/config/env.py with HostEnv + PrismEnv.
6. Mount CORSMiddleware always in backend/app/main.py.
7. Rename personal -> local across compose files, container names, install.py symbols.
8. Update install.py for MODE_PROFILES baseline + FQDN/https validation at tier 2.
9. Update docker-compose files so every port/bind reads from env.
10. Drop legacy PRISMGR_API_URL fallback in mcp/client.py + smoke scripts.
11. Smoke batteries (env_resolve + cors) green before merge.

​

Exit criteria

• PRISM_MODE values are local, lan, cloud — no personal references remain in code, compose files, container names, or docs.
• Zero platform.system() calls in backend or mcp/ runtime code.
• Zero hardcoded ports in docker-compose files.
• CORSMiddleware mounted in main.py; allowlist from resolved env.
• Provenance log at startup, one line per resolved key.
• install.py rejects lan bare-hostname URL + cloud http URL.
• mcp/smoke_env_resolve.py green across local/lan/cloud.
• mcp/smoke_cors.py green across local/lan.