Native Options Recovery Guardrails

Summary

The repo-side change is small and targeted: remove the misleading Environment=OPTIONS_INGEST_ADAPTER=synthetic line from the checked-in native ingest-options unit, and document that Bun-launched services effectively take adapter selection from /home/delta/islandflow/.env.

Changes Made

• Removed the checked-in systemd override from deployment/native/systemd/user/islandflow-ingest-options.service.
• Added an explicit env-precedence warning to deployment/native/README.md.
• Captured the live diagnosis that the native server had drifted to OPTIONS_INGEST_ADAPTER=alpaca while the prior Docker deployment was running synthetic options.

Context

On the VPS, islandflow-ingest-options.service was crash-looping with repeated 401 Unauthorized responses from Alpaca while the rest of the native stack stayed healthy. The previous Docker-owned islandflow-vps-ingest-options-1 container showed OPTIONS_INGEST_ADAPTER=synthetic, which explains why the UI had been healthy before the runtime transition.

Important Implementation Details

• The checked-in unit already referenced /home/delta/islandflow/.env, and Bun's runtime env loading meant a conflicting adapter value there still won in practice.
• The static key currently stored as ALPACA_API_KEY does not authenticate the failing market-data snapshot request as a Bearer token.
• Because the real outage fix required a server-side .env correction, this repo patch focuses on preventing operator confusion during the next native cutover.

Relevant Diff Snippets

Unified diff blocks below are formatted for diffs-compatible rendering.

diff --git a/deployment/native/README.md b/deployment/native/README.md
@@ -98,6 +98,8 @@ These are written for the current VPS layout:
 - Bun binary: `/home/delta/.bun/bin/bun`
 - env file: `/home/delta/islandflow/.env`
 
+Important: treat `/home/delta/islandflow/.env` as the effective source of truth for adapter selection. The Bun-launched services read that file directly at runtime, so a conflicting `OPTIONS_INGEST_ADAPTER` value in `.env` can still win over a systemd-only override and push `ingest-options` onto the wrong provider path.
+
 ### Install the units

diff --git a/deployment/native/systemd/user/islandflow-ingest-options.service b/deployment/native/systemd/user/islandflow-ingest-options.service
@@ -7,7 +7,6 @@ Wants=network-online.target
 Type=simple
 WorkingDirectory=/home/delta/islandflow
 EnvironmentFile=/home/delta/islandflow/.env
-Environment=OPTIONS_INGEST_ADAPTER=synthetic
 ExecStart=/home/delta/.bun/bin/bun services/ingest-options/src/index.ts

Expected Impact for End-Users

End users should not see the options tape stall the next time native units are installed or audited by following the checked-in assets. Operators now have a clearer paper trail that the actual runtime adapter comes from the deployment env file.

Validation

• Verified the native outage mode on the VPS: islandflow-ingest-options.service crash-looped on Alpaca 401 responses.
• Confirmed the previous Docker container had been running OPTIONS_INGEST_ADAPTER=synthetic.
• After the server-side env fix, confirmed fresh rows in default.option_prints and new compute emissions in the native logs.
• Ran git diff to verify the repo change stayed scoped to the deployment README and the checked-in user unit.

Issues, Limitations, and Mitigations

• The repo patch does not add new credential support for Alpaca. It only documents the current env-precedence behavior and removes a misleading override.
• The live server is restored with synthetic options, which matches the last known-good Docker behavior, but it is not a true live Alpaca ingest path.

Follow-up Work

• islandflow-wf5: Decide whether production options should remain synthetic or move to a fully supported live provider configuration.
• islandflow-wf5: If Alpaca live data is still desired, add a validated auth flow and a deploy-time smoke test that catches provider auth failures before cutover.