docs(environment): state the snapshot's name-matching contract

The Windows case-folding in the lookup was implemented without a
user-facing contract. Name matching follows the platform, and the
reason it must is the layer ranking it would otherwise invert.
This commit is contained in:
Yichen Jiang
2026-08-05 12:45:18 +08:00
parent 84b119619a
commit 2c47636a85
3 changed files with 6 additions and 2 deletions

View File

@@ -18,6 +18,8 @@ Values do also reach `process.env` — a user's `--config` tree and third-party
**Omitting a layer is a refusal, not a demotion** — a caller that must never accept a layer leaves it out of the list, so no future reordering can let it back in. The provider adapters name all three, because the product trusts the project it runs in; the mechanism exists for the decisions where that is not true.
Names match the way the platform matches them: exactly on POSIX, case-insensitively on Windows. A case-sensitive lookup there would rank the wrong layer — a shell's `deepseek_api_key` and a project `.env`'s `DEEPSEEK_API_KEY` are one variable to the OS, and treating them as two would let the project win.
```ts
import type { Context } from 'cordis'
import { environmentOf } from '@deepseek-ai/dsh-environment'