@runuai/host 0.9.148 → 0.9.149

package/lib/env-schema.ts

@@ -1,71 +1,861 @@
 /**
- * ADR-122 phase 1: a minimal, OWNED parser for the env-spec subset Uai
- * reads — key names and the @required / @sensitive / @type decorators from
- * comment lines above each declaration in a committed `.env.schema`.
+ * Uai's own parser for the env-spec subset it reads from a repository's
+ * committed `.env.schema` (ADR-122 phase 1, ADR-153 §4): key names, the
+ * @required / @sensitive / @type decorators, and @proxy / @placeholder.
  *
- * Deliberately dependency-free: this phase must stand alone even if the
- * upstream tooling vanishes (the graduated-adoption ladder in ADR-122).
- * Unknown decorators are preserved verbatim but unused; values in the
- * schema file are IGNORED — a schema declares, it never supplies.
+ * Deliberately dependency-free: it must stand alone even if the upstream
+ * tooling vanishes (the graduated-adoption ladder in ADR-122). Values in the
+ * schema file are never read: a schema declares, it never supplies.
  *
- * First consumer: the post-task-up validation note. A project that
- * declares `@required DATABASE_URL` with no value stored on this host gets
- * one visible system note instead of a blank 500 hours later (the
- * 2026-08-25 incident this phase exists to retire).
+ * The env-spec rules it follows (varlock.dev/env-spec/reference):
+ * - A comment line carries decorators only if its content starts with `@`;
+ *   any `@` in another comment is prose. A post-value comment may carry them
+ *   too (`KEY= # @sensitive`).
+ * - Comment lines directly above an item attach to it. A blank line or a
+ *   divider (`# ---`, `# ===`) ends a block; a block that ends before the
+ *   first item belongs to the document header.
+ * - `@name` is `@name=true`. Value decorators are single-use; function calls
+ *   (`@name(...)`) accumulate.
+ *
+ * Fail closed (ADR-153): an @proxy Uai cannot fully interpret makes its key
+ * `unsupported`, so the key is withheld; it never reads as no directive, which
+ * would deliver the real value. A detached @proxy (outside any item) that
+ * names keys withholds them; one that cannot be read at all, like a value
+ * that never ends or text that is not text, makes the whole schema
+ * unreadable, which withholds every key without an approved binding.
  */
 
-export interface EnvSchemaEntry {
+import { isIP } from "node:net";
+
+import {
+  MAX_PROJECT_ENV_KEY_CHARS,
+  MAX_PROJECT_ENV_PLACEHOLDER_CHARS,
+  MAX_PROJECT_ENV_PROXY_DOMAINS,
+  MAX_PROJECT_ENV_SCHEMA_DECLARATIONS,
+  MAX_PROJECT_ENV_TYPE_CHARS,
+  type KnownProjectEnvSchemaIssueCode,
+  type KnownProjectEnvSchemaUnavailableReason,
+  type KnownProjectEnvUnsupportedReason,
+  type ProjectEnvDirective,
+  type ProjectEnvSchemaDeclaration,
+  type ProjectEnvSchemaIssue,
+} from "../src/protocol";
+import { canonicalHostname, isProxiableDomain } from "./secrets-proxy/hostname";
+
+/**
+ * The epoch of what this parser reads, stamped on every schema report: the
+ * cloud prefers a newer epoch's reading of a commit to any older one's
+ * (ADR-153 §4). Bump it in the contract with any change to what
+ * `parseEnvSchemaDeclarations` returns for some input. The fingerprint test
+ * beside this file pins its results on a fixed corpus under the current
+ * epoch, so most such changes fail it until the epoch moves.
+ */
+export { CURRENT_PROJECT_ENV_PARSER_EPOCH } from "../src/protocol";
+
+export type EnvSchemaParse =
+  | { ok: true; declarations: ProjectEnvSchemaDeclaration[]; issues: ProjectEnvSchemaIssue[] }
+  | { ok: false; reason: KnownProjectEnvSchemaUnavailableReason };
+
+type Reason = KnownProjectEnvUnsupportedReason;
+type Failure = KnownProjectEnvSchemaUnavailableReason;
+
+/** A schema file larger than this is not read: no repository needs one. */
+export const MAX_ENV_SCHEMA_BYTES = 256 * 1024;
+/** A minted placeholder fills at least this many characters at random. */
+export const PLACEHOLDER_RANDOM_CHARACTERS = 32;
+
+// --- Decorator syntax -----------------------------------------------------------
+
+type Value =
+  | { kind: "string"; value: string }
+  | { kind: "bare"; value: string }
+  | { kind: "array"; items: Value[] }
+  | { kind: "object"; entries: Array<[string, Value]> }
+  | { kind: "call"; name: string; args: Arg[] };
+
+interface Arg {
+  name: string | null;
+  value: Value;
+}
+
+interface Decorator {
   name: string;
-  required: boolean;
-  sensitive: boolean;
-  type?: string;
-  /** Decorators Uai does not interpret, kept for diagnostics. */
-  otherDecorators: string[];
+  form: "bare" | "value" | "call";
+  value?: Value;
+  args?: Arg[];
+  /** As written after the `@`, for the legacy diagnostics list. */
+  source: string;
 }
 
-const KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)\s*=/;
-const DECORATOR = /@([A-Za-z][A-Za-z0-9]*)(?:=((?:[^\s(]+)?(?:\([^)]*\))?))?/g;
+const NAME = /[A-Za-z][A-Za-z0-9_]*/y;
+const NAMED_ARG = /([A-Za-z][A-Za-z0-9_]*)[ \t]*=/y;
+/** In a decorator's call, upstream takes `name=value` with nothing around
+ *  the `=`. */
+const TIGHT_NAMED_ARG = /([A-Za-z][A-Za-z0-9_]*)=/y;
+const QUOTES = new Set(["\"", "'", "`"]);
+/** Upstream's only whitespace: any other character (a vertical tab, a
+ *  no-break space) is text. */
+const isBlankChar = (char: string): boolean => char === " " || char === "\t";
+/** How deep lists, objects and calls may nest in one decorator or value:
+ *  enough for any real schema, and never a stack overflow. */
+const MAX_NESTING = 16;
 
-export function parseEnvSchema(content: string): EnvSchemaEntry[] {
-  const entries: EnvSchemaEntry[] = [];
-  let pending: {
-    required: boolean;
-    sensitive: boolean;
-    type?: string;
-    other: string[];
-  } = { required: false, sensitive: false, other: [] };
-  for (const rawLine of content.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (line.startsWith("#")) {
-      for (const match of line.matchAll(DECORATOR)) {
-        const name = match[1]!;
-        const value = match[2];
-        if (name === "required") pending.required = true;
-        else if (name === "sensitive") pending.sensitive = true;
-        else if (name === "type" && value) pending.type = value;
-        else pending.other.push(value ? `${name}=${value}` : name);
+class SyntaxFailure extends Error {}
+
+/** One line's decorators, or a value's call, list or object. Throws
+ *  SyntaxFailure on anything it cannot read. */
+class DecoratorReader {
+  private pos: number;
+  private depth = 0;
+  /** A value's structure: inside it, line breaks and `#` comments are blanks. */
+  private readonly multiline: boolean;
+
+  constructor(
+    private readonly text: string,
+    options: { start?: number; value?: boolean } = {},
+  ) {
+    this.pos = options.start ?? 0;
+    this.multiline = options.value === true;
+  }
+
+  /** Decorators up to a comment. */
+  readAll(into: Decorator[]): void {
+    for (;;) {
+      this.skipSpaces();
+      if (this.done() || this.peek() === "#") return;
+      if (this.peek() !== "@") {
+        // Stray text, as upstream reads it: skipped, and the decorators after
+        // it still count. It may not hold an `@` (upstream refuses that).
+        while (!this.done() && !isBlankChar(this.peek())) {
+          if (this.peek() === "@") throw new SyntaxFailure();
+          this.pos += 1;
+        }
+        continue;
+      }
+      const start = this.pos + 1;
+      this.pos += 1;
+      const name = this.name();
+      let decorator: Decorator;
+      if (this.peek() === "=") {
+        this.pos += 1;
+        decorator = { name, form: "value", value: this.value(true), source: "" };
+      } else if (this.peek() === "(") {
+        this.pos += 1;
+        decorator = { name, form: "call", args: this.nest(() => this.args(")")), source: "" };
+      } else {
+        decorator = { name, form: "bare", source: "" };
+      }
+      decorator.source = this.text.slice(start, this.pos);
+      into.push(decorator);
+      // Decorators end at whitespace or a comment; anything glued on is junk.
+      if (!this.done() && !isBlankChar(this.peek()) && this.peek() !== "#") throw new SyntaxFailure();
+    }
+  }
+
+  /** A function call, list or object at the start of a value: where it ends. */
+  structureEnd(): number {
+    if (this.peek() === "[" || this.peek() === "{") {
+      this.value(false);
+      return this.pos;
+    }
+    this.name();
+    if (this.peek() !== "(") throw new SyntaxFailure();
+    this.pos += 1;
+    this.nest(() => this.args(")"));
+    return this.pos;
+  }
+
+  private done(): boolean {
+    return this.pos >= this.text.length;
+  }
+
+  private peek(): string {
+    return this.text[this.pos] ?? "";
+  }
+
+  private skipSpaces(): void {
+    for (;;) {
+      const char = this.peek();
+      if (isBlankChar(char)) {
+        this.pos += 1;
+      } else if (this.multiline && this.depth > 0 && (char === "\n" || this.atCrLf())) {
+        this.pos += char === "\n" ? 1 : 2;
+      } else if (this.multiline && this.depth > 0 && char === "#") {
+        while (!this.done() && this.peek() !== "\n" && !this.atCrLf()) this.pos += 1;
+      } else {
+        return;
+      }
+    }
+  }
+
+  /** Spaces and tabs only: what upstream allows around an `=`. */
+  private skipBlanks(): void {
+    while (isBlankChar(this.peek())) this.pos += 1;
+  }
+
+  private atCrLf(): boolean {
+    return this.peek() === "\r" && this.text[this.pos + 1] === "\n";
+  }
+
+  private name(): string {
+    NAME.lastIndex = this.pos;
+    const match = NAME.exec(this.text);
+    if (match === null) throw new SyntaxFailure();
+    this.pos += match[0].length;
+    return match[0];
+  }
+
+  private nest<T>(read: () => T): T {
+    this.depth += 1;
+    if (this.depth > MAX_NESTING) throw new SyntaxFailure();
+    try {
+      return read();
+    } finally {
+      this.depth -= 1;
+    }
+  }
+
+  private value(topLevel: boolean): Value {
+    const char = this.peek();
+    if (QUOTES.has(char)) return { kind: "string", value: this.quoted() };
+    if (char === "[") {
+      this.pos += 1;
+      return { kind: "array", items: this.nest(() => this.list("]")) };
+    }
+    if (char === "{") {
+      this.pos += 1;
+      return { kind: "object", entries: this.nest(() => this.entries()) };
+    }
+    const start = this.pos;
+    while (!this.done()) {
+      const next = this.peek();
+      if (isBlankChar(next) || next === "(" || next === "\n" || next === "\r") break;
+      // A decorator's own value ends at a comment, as upstream reads it.
+      if (topLevel && next === "#") break;
+      if (!topLevel && (next === "," || next === ")" || next === "]" || next === "}")) break;
+      if (QUOTES.has(next) || next === "[" || next === "{") throw new SyntaxFailure();
+      this.pos += 1;
+    }
+    const word = this.text.slice(start, this.pos);
+    if (word.length === 0) throw new SyntaxFailure();
+    if (this.peek() === "(") {
+      if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(word)) throw new SyntaxFailure();
+      this.pos += 1;
+      return { kind: "call", name: word, args: this.nest(() => this.args(")")) };
+    }
+    return { kind: "bare", value: word };
+  }
+
+  private quoted(): string {
+    const quote = this.peek();
+    this.pos += 1;
+    let out = "";
+    for (;;) {
+      if (this.done()) throw new SyntaxFailure();
+      const char = this.peek();
+      if (char === "\\" && this.pos + 1 < this.text.length) {
+        const escaped = this.text[this.pos + 1]!;
+        // Not even escaped: a string never spans lines. (A lone CR is text;
+        // the LF of an escaped CRLF fails below, as any line break does.)
+        if (escaped === "\n") throw new SyntaxFailure();
+        out += escaped === quote || escaped === "\\" ? escaped : `\\${escaped}`;
+        this.pos += 2;
+        continue;
+      }
+      // A string never holds a line break, even in a structure that does.
+      if (char === "\n") throw new SyntaxFailure();
+      this.pos += 1;
+      if (char === quote) return out;
+      out += char;
+    }
+  }
+
+  /** Comma-separated values up to `close`; a trailing comma is allowed. */
+  private list(close: string): Value[] {
+    const items: Value[] = [];
+    for (;;) {
+      this.skipSpaces();
+      if (this.peek() === close) {
+        this.pos += 1;
+        return items;
+      }
+      items.push(this.value(false));
+      this.endOfItem(close);
+      if (this.text[this.pos - 1] === close) return items;
+    }
+  }
+
+  private entries(): Array<[string, Value]> {
+    const entries: Array<[string, Value]> = [];
+    for (;;) {
+      this.skipSpaces();
+      if (this.peek() === "}") {
+        this.pos += 1;
+        return entries;
+      }
+      const key = this.name();
+      this.skipBlanks();
+      if (this.peek() !== "=") throw new SyntaxFailure();
+      this.pos += 1;
+      this.skipBlanks();
+      entries.push([key, this.value(false)]);
+      this.endOfItem("}");
+      if (this.text[this.pos - 1] === "}") return entries;
+    }
+  }
+
+  private args(close: string): Arg[] {
+    const args: Arg[] = [];
+    for (;;) {
+      this.skipSpaces();
+      if (this.peek() === close) {
+        this.pos += 1;
+        return args;
+      }
+      const pattern = this.multiline ? NAMED_ARG : TIGHT_NAMED_ARG;
+      pattern.lastIndex = this.pos;
+      const named = pattern.exec(this.text);
+      let name: string | null = null;
+      if (named !== null) {
+        name = named[1]!;
+        this.pos += named[0].length;
+        if (this.multiline) this.skipBlanks();
+      }
+      args.push({ name, value: this.value(false) });
+      this.endOfItem(close);
+      if (this.text[this.pos - 1] === close) return args;
+    }
+  }
+
+  /** After an item: a comma (then more, or the close), or the close. */
+  private endOfItem(close: string): void {
+    this.skipSpaces();
+    if (this.peek() === ",") {
+      this.pos += 1;
+      this.skipSpaces();
+      if (this.peek() === close) this.pos += 1;
+      return;
+    }
+    if (this.peek() === close) {
+      this.pos += 1;
+      return;
+    }
+    throw new SyntaxFailure();
+  }
+}
+
+/** A decorator comment's decorators, or null if any of it is unreadable. */
+function readDecorators(content: string): Decorator[] | null {
+  const decorators: Decorator[] = [];
+  try {
+    new DecoratorReader(content).readAll(decorators);
+    return decorators;
+  } catch (error) {
+    if (error instanceof SyntaxFailure) return null;
+    throw error;
+  }
+}
+
+// --- Lines and values -------------------------------------------------------------
+
+interface Block {
+  decorators: Decorator[];
+}
+
+const emptyBlock = (): Block => ({ decorators: [] });
+
+/** `export ` and any blanks: once read, a key must follow (upstream never
+ *  takes it back to read `export` itself as the key). */
+const EXPORT_PREFIX = /^export [ \t]*/;
+/** A key as upstream reads one: `.` and `-` may follow its first character. */
+const ITEM_KEY = /^([A-Za-z_][A-Za-z0-9_.-]*)[ \t]*=/;
+/** A key the contract, the settings API and a shell can all hold. */
+const CONTRACT_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A value upstream reads as a structure: a call, a list or an object. */
+const STRUCTURE = /^(?:[A-Za-z][A-Za-z0-9_]*\(|\[|\{)/;
+/** Before a value's first `#`: a quote or an expansion it may sit inside. */
+const AMBIGUOUS_COMMENT = /["'`]|\$[({]/;
+
+/**
+ * A config item's value, from `from` on line `index`: where it ends, and its
+ * post-value comment if it has one, as upstream (@env-spec/parser) reads it:
+ * - `"` may span lines; `"""` and a ``` fence must, closing on a later line;
+ *   `'` and a single backtick may not.
+ * - A call, list or object is read whole, across lines if it spans them, so
+ *   a `#` in it is not the value's comment. Any other unquoted value ends at
+ *   its first `#`.
+ * Anything upstream refuses (a value that never ends, text after a closed
+ * one) is unreadable here too. So is a `#` that may sit inside quotes or an
+ * expansion, and a structure that does not read whole (too deep, or broken):
+ * where the value ends is a guess there, and a guess could lose a real
+ * @proxy or invent one.
+ */
+function endOfValue(
+  source: Source,
+  index: number,
+  firstLine: string,
+  from: number,
+  afterBlank: boolean,
+): { lastLine: number; comment: string | null } | Failure {
+  const { lines } = source;
+  const value = firstLine.slice(from);
+  const after = (lastLine: number, rest: string): { lastLine: number; comment: string | null } | Failure => {
+    const match = /^[ \t]*(?:#(.*))?$/.exec(rest);
+    if (match === null) return "schema_malformed";
+    return { lastLine, comment: match[1] ?? null };
+  };
+  const fence = value.startsWith('"""')
+    ? '"""'
+    : value.startsWith("```")
+      ? "```"
+      : QUOTES.has(value[0] ?? "")
+        ? value[0]!
+        : null;
+  if (afterBlank && fence !== null) {
+    // Upstream refuses a quoted value after a blank.
+    return "schema_malformed";
+  }
+  if (fence === null) {
+    // After a blank, upstream reads even a call, list or object as plain
+    // text, up to its first #.
+    if (!afterBlank && STRUCTURE.test(value)) {
+      // Read whole, across lines if it spans them (a line break or a `#`
+      // comment inside it is a blank there, as upstream reads it).
+      const start = source.lineStarts[index]! + (lines[index]!.length - firstLine.length) + from;
+      let end: number;
+      try {
+        end = new DecoratorReader(source.text, { start, value: true }).structureEnd();
+      } catch (error) {
+        if (!(error instanceof SyntaxFailure)) throw error;
+        // Not readable whole. Upstream reads some of these as plain text and
+        // refuses others; any reading here would be a guess.
+        return "schema_malformed";
       }
+      let lastLine = index;
+      while (lastLine + 1 < lines.length && source.lineStarts[lastLine + 1]! < end) lastLine += 1;
+      return after(lastLine, lines[lastLine]!.slice(end - source.lineStarts[lastLine]!));
+    }
+    const hash = value.indexOf("#");
+    if (hash === -1) return { lastLine: index, comment: null };
+    if (AMBIGUOUS_COMMENT.test(value.slice(0, hash))) return "schema_malformed";
+    return { lastLine: index, comment: value.slice(hash + 1) };
+  }
+  let text = value.slice(fence.length);
+  if (fence.length === 3) {
+    // Upstream refuses a triple-quoted or fenced value closed on its own line.
+    if (text.replaceAll(`\\${fence}`, "").includes(fence)) return "schema_malformed";
+  }
+  const spansLines = fence !== "'" && fence !== "`";
+  let lineIndex = index;
+  for (;;) {
+    let i = 0;
+    while (i < text.length) {
+      // An escaped delimiter (\" in "...", \""" in """...""") does not close.
+      if (text[i] === "\\" && (fence.length === 1 || text.startsWith(fence, i + 1))) {
+        i += 1 + (fence.length === 1 ? 1 : fence.length);
+        continue;
+      }
+      if (lineIndex > index || fence.length === 1) {
+        if (text.startsWith(fence, i)) return after(lineIndex, text.slice(i + fence.length));
+      }
+      i += 1;
+    }
+    lineIndex += 1;
+    if (!spansLines || lineIndex >= lines.length) return "schema_unterminated_value";
+    text = lines[lineIndex]!;
+  }
+}
+
+// --- The schema -------------------------------------------------------------------
+
+interface Item {
+  key: string;
+  block: Block;
+}
+
+/** The schema's text, its lines (without their line breaks), and the offset
+ *  each line starts at. */
+interface Source {
+  text: string;
+  lines: string[];
+  lineStarts: number[];
+}
+
+function sourceOf(text: string): Source {
+  const lines = text.split(/\r?\n/);
+  const lineStarts: number[] = [];
+  let offset = 0;
+  for (const line of lines) {
+    lineStarts.push(offset);
+    offset += line.length + (text[offset + line.length] === "\r" ? 2 : 1);
+  }
+  return { text, lines, lineStarts };
+}
+
+interface Reading {
+  items: Item[];
+  detached: Block[];
+}
+
+function read(text: string): Reading | Failure {
+  const source = sourceOf(text);
+  const { lines } = source;
+  const items: Item[] = [];
+  const detached: Block[] = [];
+  let block = emptyBlock();
+  const endBlock = (): void => {
+    if (block.decorators.length > 0) detached.push(block);
+    block = emptyBlock();
+  };
+  /** False when the decorators cannot be read: upstream refuses the file,
+   *  and what they say about routing is unknown. */
+  const addDecorators = (into: Block, content: string): boolean => {
+    const decorators = readDecorators(content);
+    if (decorators === null) return false;
+    into.decorators.push(...decorators);
+    return true;
+  };
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const raw = lines[index]!;
+    if (/^[ \t]*$/.test(raw)) {
+      endBlock();
       continue;
     }
-    if (line === "") {
-      // A blank line ends a decorator block that never reached a key —
-      // env-spec decorators attach to the declaration directly below them.
-      pending = { required: false, sensitive: false, other: [] };
+    if (raw.startsWith("#")) {
+      const content = raw.slice(1).replace(/^[ \t]+/, "");
+      // A divider, as upstream has it: three of - = * #, in any mix.
+      if (/^[-=*#]{3}/.test(content)) endBlock();
+      else if (content.startsWith("@") && !addDecorators(block, content)) return "schema_malformed";
       continue;
     }
-    const key = KEY_LINE.exec(line);
-    if (key) {
-      entries.push({
-        name: key[1]!,
-        required: pending.required,
-        sensitive: pending.sensitive,
-        ...(pending.type !== undefined ? { type: pending.type } : {}),
-        otherDecorators: pending.other,
+    // Only an item may be indented, and only with spaces and tabs: upstream
+    // refuses an indented comment, or a line led by any other character.
+    const line = raw.replace(/^[ \t]+/, "");
+    const keyStart = EXPORT_PREFIX.exec(line)?.[0].length ?? 0;
+    const item = ITEM_KEY.exec(line.slice(keyStart));
+    // Neither blank, a comment nor KEY=...: upstream refuses the file, and a
+    // line we cannot read may be a key whose decorators we would lose.
+    if (item === null || item[1]!.length > MAX_PROJECT_ENV_KEY_CHARS) return "schema_malformed";
+    const attached = block;
+    block = emptyBlock();
+    const itemEnd = keyStart + item[0].length;
+    const afterEquals = line.slice(itemEnd);
+    const blanks = afterEquals.length - afterEquals.replace(/^[ \t]+/, "").length;
+    const end = endOfValue(source, index, line, itemEnd + blanks, blanks > 0);
+    if (typeof end === "string") return end;
+    index = end.lastLine;
+    if (end.comment !== null) {
+      const comment = end.comment.replace(/^[ \t]+/, "");
+      // Upstream refuses a divider after a value.
+      if (/^[-=*#]{3}/.test(comment)) return "schema_malformed";
+      if (comment.startsWith("@") && !addDecorators(attached, comment)) return "schema_malformed";
+    }
+    items.push({ key: item[1]!, block: attached });
+  }
+  endBlock();
+  return { items, detached };
+}
+
+function booleanDecorator(decorators: readonly Decorator[], name: string): boolean | null {
+  let result: boolean | null = null;
+  for (const decorator of decorators) {
+    if (decorator.name !== name) continue;
+    const explicitFalse =
+      decorator.form === "value" && decorator.value?.kind === "bare" && decorator.value.value === "false";
+    result = (result ?? false) || !explicitFalse;
+  }
+  return result;
+}
+
+/** Withheld, for one of the reasons the contract knows. */
+const unsupported = (reason: Reason): ProjectEnvDirective => ({ kind: "unsupported", reason });
+
+const OPTION_REASONS: Readonly<Record<string, Reason>> = {
+  path: "option_path",
+  method: "option_method",
+  block: "option_block",
+  keys: "option_keys",
+  substituteIn: "option_substitute_in",
+  transform: "option_transform",
+  approval: "option_approval",
+  rules: "option_rules",
+};
+
+/** A declared domain in canonical form, or why it cannot be proxied. */
+function proxyDomain(raw: string): string | { reason: Reason } {
+  if (raw.includes("*")) return { reason: "wildcard_domain" };
+  const canonical = canonicalHostname(raw);
+  if (canonical === null) {
+    const bare = raw.replace(/^\[(.*)\]$/, "$1");
+    const lastLabel = raw.replace(/\.$/, "").split(".").pop() ?? "";
+    const looksNumeric = /^[0-9]+$/.test(lastLabel) || /^0x[0-9a-f]*$/i.test(lastLabel);
+    return { reason: isIP(bare) !== 0 || looksNumeric ? "ip_literal" : "invalid_domain" };
+  }
+  if (canonical === "localhost" || canonical.endsWith(".localhost")) return { reason: "localhost" };
+  if (!canonical.includes(".")) return { reason: "invalid_domain" };
+  if (!isProxiableDomain(canonical)) return { reason: "reserved_domain" };
+  return canonical;
+}
+
+function stringsOf(value: Value): string[] | null {
+  if (value.kind === "string" || value.kind === "bare") return [value.value];
+  if (value.kind !== "array") return null;
+  const out: string[] = [];
+  for (const item of value.items) {
+    if (item.kind !== "string" && item.kind !== "bare") return null;
+    out.push(item.value);
+  }
+  return out;
+}
+
+/** What an item's @proxy decorators ask for, failing closed on anything Uai
+ *  cannot honour in full. */
+function directiveOf(block: Block): ProjectEnvDirective {
+  const proxies = block.decorators.filter((decorator) => decorator.name === "proxy");
+  if (proxies.length === 0) return { kind: "none" };
+  const calls = proxies.filter((decorator) => decorator.form === "call");
+  const values = proxies.filter((decorator) => decorator.form !== "call");
+  if (values.length > 0) {
+    if (calls.length > 0 || values.length > 1) return unsupported("conflicting_forms");
+    // Quoted or not, a string is the same string (env-spec).
+    const value = values[0]!.value;
+    const word = value?.kind === "bare" || value?.kind === "string" ? value.value : null;
+    if (word === "passthrough") return { kind: "passthrough" };
+    if (word === "omit") return { kind: "omit" };
+    return unsupported("invalid_value");
+  }
+  const domains = new Set<string>();
+  for (const call of calls) {
+    let declared: string[] | null = null;
+    for (const arg of call.args ?? []) {
+      if (arg.name === null) return unsupported("malformed");
+      if (arg.name !== "domain") {
+        return unsupported(OPTION_REASONS[arg.name] ?? "option_unknown");
+      }
+      if (declared !== null) return unsupported("malformed");
+      declared = stringsOf(arg.value);
+      if (declared === null) return unsupported("malformed");
+    }
+    if (declared === null || declared.length === 0) return unsupported("missing_domain");
+    for (const raw of declared) {
+      const domain = proxyDomain(raw);
+      if (typeof domain !== "string") return unsupported(domain.reason);
+      domains.add(domain);
+    }
+  }
+  if (domains.size > MAX_PROJECT_ENV_PROXY_DOMAINS) return unsupported("too_many_domains");
+  return { kind: "proxy", domains: [...domains].sort() };
+}
+
+/** The declared placeholder's shape: the prefix up to and including its last
+ *  `_` or `-`, and a length that leaves room for the random part. */
+function placeholderOf(block: Block): { prefix: string; totalLength: number } | "unusable" | null {
+  const declared = block.decorators.filter((decorator) => decorator.name === "placeholder");
+  if (declared.length === 0) return null;
+  if (declared.length > 1) return "unusable";
+  const value = declared[0]!.value;
+  if (declared[0]!.form !== "value" || (value?.kind !== "string" && value?.kind !== "bare")) return "unusable";
+  const literal = value.value;
+  if (literal.length === 0 || literal.length > MAX_PROJECT_ENV_PLACEHOLDER_CHARS) return "unusable";
+  const cut = Math.max(literal.lastIndexOf("_"), literal.lastIndexOf("-"));
+  const prefix = literal.slice(0, cut + 1);
+  if (!/^[A-Za-z0-9._~-]*$/.test(prefix)) return "unusable";
+  const totalLength = Math.max(literal.length, prefix.length + PLACEHOLDER_RANDOM_CHARACTERS);
+  if (totalLength > MAX_PROJECT_ENV_PLACEHOLDER_CHARS) return "unusable";
+  return { prefix, totalLength };
+}
+
+function typeOf(block: Block): string | undefined {
+  const declared = block.decorators.find((decorator) => decorator.name === "type" && decorator.form === "value");
+  if (declared === undefined) return undefined;
+  const text = declared.source.slice("type=".length);
+  if (text.length === 0 || text.length > MAX_PROJECT_ENV_TYPE_CHARS || /[\u0000-\u001f\u007f]/.test(text)) return undefined;
+  return text;
+}
+
+const routes = (block: Block): boolean =>
+  block.decorators.some((decorator) => decorator.name === "proxy" || decorator.name === "placeholder");
+
+interface Parsed {
+  declarations: ProjectEnvSchemaDeclaration[];
+  issues: ProjectEnvSchemaIssue[];
+  /** Decorators Uai does not read, per key, for the legacy diagnostics. */
+  other: Map<string, string[]>;
+}
+
+function parse(input: string | Uint8Array): Parsed | Failure {
+  let text: string;
+  if (typeof input === "string") {
+    if (Buffer.byteLength(input, "utf8") > MAX_ENV_SCHEMA_BYTES) return "schema_too_large";
+    text = input;
+  } else {
+    if (input.byteLength > MAX_ENV_SCHEMA_BYTES) return "schema_too_large";
+    try {
+      text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(input);
+    } catch {
+      return "schema_not_text";
+    }
+  }
+  if (text.includes("\u0000")) return "schema_not_text";
+  // Upstream refuses a byte-order mark: so does this, rather than read past it.
+  if (text.startsWith("\uFEFF")) return "schema_malformed";
+
+  const reading = read(text);
+  if (typeof reading === "string") return reading;
+
+  // Each issue once per key (or once for the project), as an observation
+  // requires; this also keeps their number bounded by the keys.
+  const issues: ProjectEnvSchemaIssue[] = [];
+  const reported = new Set<string>();
+  const issue = (code: KnownProjectEnvSchemaIssueCode, key?: string): void => {
+    const id = `${code}\u0000${key ?? ""}`;
+    if (reported.has(id)) return;
+    reported.add(id);
+    issues.push(key === undefined ? { code } : { code, key });
+  };
+  /** The keys a `keys=[...]` argument names, or null if it cannot be read. */
+  const keysNamed = (decorator: Decorator): string[] | null => {
+    const named: string[] = [];
+    for (const arg of decorator.args ?? []) {
+      if (arg.name !== "keys") continue;
+      const keys = stringsOf(arg.value);
+      if (keys === null || keys.some((key) => !/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(key))) return null;
+      named.push(...keys);
+    }
+    return named;
+  };
+
+  const headerKeys = new Set<string>();
+  for (const block of reading.detached) {
+    for (const decorator of block.decorators) {
+      if (decorator.name === "proxyConfig") issue("proxy_config");
+      if (decorator.name !== "proxy") continue;
+      issue("header_proxy_rule");
+      const keys = keysNamed(decorator);
+      if (keys === null) return "schema_malformed";
+      for (const key of keys) headerKeys.add(key);
+    }
+  }
+  // An item's own @proxy can name other keys to inject too (`keys=[...]`).
+  // Uai cannot, so they are withheld like the item.
+  const optionKeys = new Set<string>();
+  for (const item of reading.items) {
+    for (const decorator of item.block.decorators) {
+      // @proxyConfig belongs in the header; Uai honours it nowhere.
+      if (decorator.name === "proxyConfig") issue("proxy_config");
+      if (decorator.name !== "proxy" || decorator.form !== "call") continue;
+      const keys = keysNamed(decorator);
+      if (keys === null) return "schema_malformed";
+      for (const key of keys) optionKeys.add(key);
+    }
+  }
+
+  const byKey = new Map<string, ProjectEnvSchemaDeclaration>();
+  const other = new Map<string, string[]>();
+  const routed = new Set<string>();
+  for (const item of reading.items) {
+    // A key with `.` or `-` in it is one upstream reads, but no value can be
+    // stored under it (the settings API and a shell refuse the name): not a
+    // declaration. Any keys its @proxy names were taken above.
+    if (!CONTRACT_KEY.test(item.key)) continue;
+    const { block } = item;
+    const directive = directiveOf(block);
+    const proxied = block.decorators.some((decorator) => decorator.name === "proxy");
+    const declaration: ProjectEnvSchemaDeclaration = {
+      key: item.key,
+      required: booleanDecorator(block.decorators, "required") ?? false,
+      sensitive: proxied || (booleanDecorator(block.decorators, "sensitive") ?? false),
+      directive,
+    };
+    const type = typeOf(block);
+    if (type !== undefined) declaration.type = type;
+    if (directive.kind === "proxy") {
+      const placeholder = placeholderOf(block);
+      if (placeholder === "unusable") issue("placeholder_ignored", item.key);
+      else if (placeholder !== null) declaration.placeholder = placeholder;
+    }
+    const unread = block.decorators
+      .filter((decorator) => !["required", "sensitive", "type", "proxy", "placeholder"].includes(decorator.name))
+      .map((decorator) => decorator.source);
+
+    const earlier = byKey.get(item.key);
+    if (earlier === undefined) {
+      byKey.set(item.key, declaration);
+      other.set(item.key, unread);
+      if (routes(block)) routed.add(item.key);
+      continue;
+    }
+    // Declared again: plain repeats merge; any routing on either withholds it.
+    if (routes(block) || routed.has(item.key)) {
+      routed.add(item.key);
+      byKey.set(item.key, {
+        key: item.key,
+        required: earlier.required || declaration.required,
+        sensitive: true,
+        ...(earlier.type !== undefined ? { type: earlier.type } : {}),
+        directive: unsupported("duplicate_key"),
+      });
+    } else {
+      byKey.set(item.key, {
+        ...earlier,
+        required: earlier.required || declaration.required,
+        sensitive: earlier.sensitive || declaration.sensitive,
       });
     }
-    pending = { required: false, sensitive: false, other: [] };
+    other.get(item.key)!.push(...unread);
+  }
+
+  // Keys a rule names: withheld, and declared here if the file did not.
+  const withhold = (key: string, reason: Reason): void => {
+    const earlier = byKey.get(key);
+    byKey.set(key, {
+      key,
+      required: earlier?.required ?? false,
+      sensitive: true,
+      ...(earlier?.type !== undefined ? { type: earlier.type } : {}),
+      directive: unsupported(reason),
+    });
+    if (!other.has(key)) other.set(key, []);
+  };
+  for (const key of [...headerKeys].sort()) if (CONTRACT_KEY.test(key)) withhold(key, "header_rule");
+  for (const key of [...optionKeys].sort()) {
+    if (CONTRACT_KEY.test(key) && !headerKeys.has(key)) withhold(key, "option_keys");
   }
-  return entries;
+  if (byKey.size > MAX_PROJECT_ENV_SCHEMA_DECLARATIONS) return "schema_too_many_declarations";
+  return { declarations: [...byKey.values()], issues, other };
+}
+
+/** A repository's `.env.schema`, as Uai reads it (ADR-153 §4). */
+export function parseEnvSchemaDeclarations(input: string | Uint8Array): EnvSchemaParse {
+  const parsed = parse(input);
+  if (typeof parsed === "string") return { ok: false, reason: parsed };
+  return { ok: true, declarations: parsed.declarations, issues: parsed.issues };
+}
+
+// --- ADR-122 phase 1: the required-keys note ---------------------------------------
+
+export interface EnvSchemaEntry {
+  name: string;
+  required: boolean;
+  sensitive: boolean;
+  type?: string;
+  /** Decorators Uai does not interpret, kept for diagnostics. */
+  otherDecorators: string[];
+}
+
+/** The ADR-122 shape, for the required-keys note. A schema that cannot be
+ *  read declares nothing here; the note is advisory. */
+export function parseEnvSchema(content: string): EnvSchemaEntry[] {
+  const parsed = parse(content);
+  if (typeof parsed === "string") return [];
+  return parsed.declarations.map((declaration) => ({
+    name: declaration.key,
+    required: declaration.required,
+    sensitive: declaration.sensitive,
+    ...(declaration.type !== undefined ? { type: declaration.type } : {}),
+    otherDecorators: parsed.other.get(declaration.key) ?? [],
+  }));
 }
 
 /** Required keys the provided value set does not cover. Presence is a