# Native Options Recovery Guardrails

The production outage turned out to be a native deployment config mismatch, not a data-pipeline code failure. I restored the VPS to the last known-good synthetic options adapter, then tightened the checked-in native deployment assets so they no longer imply a systemd override will beat the repo `.env`.

Generated 2026-05-19 19:24 EDT

## 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.