# NODE.DC Environment Contract

This contract separates local feature testing from deployed runtime.

## Profiles

`local`

- Runs Launcher, Engine, Ops/Gateway, AI Workspace Assistant, databases, and fixtures on the developer machine.
- May use the deployed AI Hub only as a thin relay for a remote Codex worker.
- Must not call production Launcher, Engine, Ops, Authentik, or Gateway endpoints.

`tunnel-local-e2e`

- Explicit escape hatch for Tailscale/ngrok-style testing.
- Same business services are still local, but relay URLs may use tunnel/private addresses.
- Must be opt-in through `NODEDC_ENV=tunnel-local-e2e`.

`staging`

- Deployed test stack with staging data and staging Authentik/OIDC clients.
- Used after local smoke is green.

`prod`

- Production data and production public domains.
- Only deploy artifacts that passed local and staging checks.

## URL Classes

- Browser URL: opened by a user browser.
- Internal service URL: used by one backend to call another backend.
- Relay URL: used only to move messages between a local assistant and a remote worker.
- Downstream app URL: used by an assistant adapter to read or mutate its owning app.

Do not mix these classes. A remote worker must not call Launcher, Engine, Ops, or Authentik directly in `local`.

## Local Remote Worker Chain

```text
local Engine
  -> local AI Workspace Assistant
  -> deployed AI Hub relay
  -> remote Codex worker
  -> deployed AI Hub relay
  -> local AI Workspace Assistant
  -> local Launcher / local Engine / local Ops
```

The deployed AI Hub is transport only. It must not decide product access, own app routes, or force production downstream URLs.

## Required Local Defaults

Engine local server:

```text
NODEDC_ENV=local
NODEDC_LAUNCHER_INTERNAL_URL=http://127.0.0.1:5173
NODEDC_LAUNCHER_ORIGIN=http://launcher.local.nodedc
AUTHENTIK_PUBLIC_BASE_URL=http://auth.local.nodedc
NODEDC_AI_WORKSPACE_ASSISTANT_URL=http://127.0.0.1:18082
OPS_RETENTION_ENABLED=false
```

Platform local stack:

```text
NODEDC_ENV=local
AI_WORKSPACE_HUB_PUBLIC_URL=wss://ai-hub.nodedc.ru/api/ai-workspace/hub
AI_WORKSPACE_HUB_INTERNAL_URL=https://ai-hub.nodedc.ru
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED=true
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID=local-dev
```

The AI Hub URLs above are allowed only because they are relay URLs. Production app URLs such as `https://hub.nodedc.ru`, `https://engine.nodedc.ru`, `https://ops.nodedc.ru`, and `https://id.nodedc.ru` are forbidden in local app config.

Assistant action calls in local must use the relay route:

```text
remote worker assistant_action_call
  -> deployed AI Hub /api/ai-workspace/hub/v1/assistant-relays/<relayId>/actions
  -> local AI Workspace Assistant long-poll
  -> local Launcher / Engine / Ops adapter
```

Do not route local assistant actions through the deployed Assistant or deployed product backends.

## Guardrail

Run the complete local testing gate before local AI Workspace testing:

```sh
sh platform/infra/scripts/check-local-test-system.sh
```

Run this narrower env-only guard when changing env files:

```sh
node platform/infra/scripts/check-local-environment-safety.mjs
```

Run the broader AI Workspace contract check before changing worker/assistant routing:

```sh
platform/infra/scripts/check-ai-workspace-config-contract.sh
```