@moondeck/station 0.0.1 → 1.0.1

package/src/never-proxied-domains.ts

@@ -0,0 +1,31 @@
+/**
+ * Domains a key may never be proxied to (ADR-153 §4 "Fail closed"), a name
+ * itself or any name under it. GitHub keeps its own credential path (the GH
+ * identity work), and the product's own domains, runuai.com and moondeck.io
+ * both, carry the runner's and the cloud's traffic; moondeckapp.com serves
+ * user content (previews, the editor) as runuai.com's preview names do. A name with no dot, or
+ * under `localhost`, can never hold a public certificate.
+ *
+ * The one list: the runner's proxy and `.env.schema` parser, the protocol's
+ * binding checks and the cloud's task secrets all call isNeverProxiedDomain.
+ * lib/__tests__/never-proxied-domains.test.ts checks that each of those three
+ * lets its result decide (a `&&`-joined veto in its `return`, or an
+ * `||`-joined trigger in a throwing `if`), and fails on
+ * any other array literal in the source naming two or more of these domains
+ * (literals, concatenations and scope-resolved const strings). It cannot see
+ * a copy written another way (a regular expression, a list built at
+ * runtime): don't write one.
+ */
+export const NEVER_PROXIED_DOMAIN_SUFFIXES = [
+  "github.com",
+  "githubusercontent.com",
+  "runuai.com",
+  "moondeck.io",
+  "moondeckapp.com",
+  "localhost",
+] as const;
+
+/** For a canonical (lower-case, no trailing dot) hostname. */
+export function isNeverProxiedDomain(name: string): boolean {
+  return NEVER_PROXIED_DOMAIN_SUFFIXES.some((suffix) => name === suffix || name.endsWith(`.${suffix}`));
+}

package/src/outbound-frame.ts

@@ -0,0 +1,31 @@
+/**
+ * What the runner may send the cloud. The cloud's bridge closes a runner's
+ * connection on any frame past its ceiling (100 MiB, lib/host-bridge.ts), so
+ * a frame that would serialize past it is never sent: a command's result is
+ * replaced by its failure, and anything else is dropped. Either way the
+ * connection, and every other task's traffic on it, stays open.
+ */
+import { HostErrorCode, type HostToCloud } from "./protocol";
+
+/** Under the cloud's ceiling, with room to spare. */
+export const MAX_OUTBOUND_FRAME_BYTES = 96 * 1024 * 1024;
+
+/** The serialized frame to send for `frame`: itself, a command result's
+ *  failure in its place, or null when nothing of it can be sent. */
+export function outboundFrameJson(frame: HostToCloud): string | null {
+  const json = JSON.stringify(frame);
+  if (Buffer.byteLength(json, "utf8") <= MAX_OUTBOUND_FRAME_BYTES) return json;
+  if (frame.kind === "result") {
+    return JSON.stringify({
+      kind: "result",
+      commandId: frame.commandId,
+      result: {
+        ok: false,
+        code: HostErrorCode.Internal,
+        message: "the result is too large to send",
+      },
+    } satisfies HostToCloud);
+  }
+  console.warn(`[host] dropped an outbound ${frame.kind} frame past the bridge's size limit`);
+  return null;
+}

package/src/paths.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared filesystem paths for the host service + local UI (ADR-028).
+ * Used by main.ts (server boot), cli.ts (status/open/logs), and the per-OS
+ * install modules so the log/port/asset locations have a single definition.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { env } from "../lib/env";
+import { STATION } from "./station-identity";
+
+const srcDir = dirname(fileURLToPath(import.meta.url)); // host-agent/src
+
+/** Base dir for host state — the repo root in a checkout, ~/.moondeck when
+ *  installed via npm. Used as the service working directory. */
+export function uaiHome(): string {
+  return env.uaiHome;
+}
+
+/** `.env.local` under UAI_HOME — where `setup`/`pair` persist the credential. */
+export function envLocalPath(): string {
+  return join(env.uaiHome, ".env.local");
+}
+
+/** Static UI asset dir (`host-agent/ui`). */
+export function uiAssetsDir(): string {
+  return resolve(srcDir, "..", "ui");
+}
+
+/** Where the chosen UI port is persisted (`$UAI_DATA_DIR/host.port`). */
+export function uiPortFilePath(): string {
+  return join(env.dataDir, "host.port");
+}
+
+/** Stable host identity persisted by the daemon for legacy/token-only setups. */
+export function hostIdFilePath(): string {
+  return join(env.dataDir, "host-id");
+}
+
+/** Read the daemon's persisted identity without creating one. */
+export function readPersistedHostId(): string | null {
+  const path = hostIdFilePath();
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, "utf8").trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Per-OS service log path — informational in `/api/status`, the file
+ *  `uai-host logs` tails. Linux logs to journald, so returns a hint there. */
+export function serviceLogPath(): string {
+  if (process.platform === "darwin") {
+    return resolve(homedir(), "Library", "Logs", STATION.logDirName, STATION.logFileName);
+  }
+  if (process.platform === "win32") {
+    return join(
+      process.env.LOCALAPPDATA ?? homedir(),
+      STATION.logDirName,
+      "service",
+      "logs",
+      STATION.logFileName,
+    );
+  }
+  return `journald (journalctl --user -u ${STATION.command})`;
+}
+
+/** `@moondeck/station` package version (read at runtime; no JSON-import dance). */
+export function packageVersion(): string {
+  try {
+    const raw = readFileSync(resolve(srcDir, "..", "package.json"), "utf8");
+    const pkg = JSON.parse(raw) as { version?: string };
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}

package/src/project-env-latest.ts

@@ -0,0 +1,130 @@
+/**
+ * ADR-153 §4, "The latest observation": the one order the cloud keeps each
+ * project's latest schema observation by. The state is the greatest report
+ * the cloud has accepted, so it never depends on the order reports arrive
+ * in. Pure: the cloud's storage applies a move atomically, with the
+ * project's next generation.
+ *
+ * Reports are ordered by, in turn:
+ * 1. what they say: nothing about the schema, below a proven-empty
+ *    repository, below a reading of a commit (readable or not);
+ * 2. the parser epoch;
+ * 3. for readings of a commit, the commit time, then the commit id;
+ * 4. a resolved reading over an unreadable one of the same commit;
+ * 5. their canonical bytes.
+ */
+
+import { isProjectEnvSchemaObservation, type ProjectEnvSchemaObservation } from "./protocol";
+
+/** A report the cloud could not read, or a stored state that fails its
+ *  check: it says nothing about the schema, from epoch 0. */
+export interface UnreadableProjectEnvSchemaReport {
+  status: "unreadable_report";
+}
+
+/** A report as the order reads it. */
+export type OrderedProjectEnvSchemaReport = ProjectEnvSchemaObservation | UnreadableProjectEnvSchemaReport;
+
+/** A project's latest observation: none until the first report. */
+export type LatestProjectEnvSchema = { status: "none" } | OrderedProjectEnvSchemaReport;
+
+const UNREADABLE: UnreadableProjectEnvSchemaReport = { status: "unreadable_report" };
+
+/** A report checked against the contract: one it rejects, including one from
+ *  a parser epoch newer than this build knows, says nothing. */
+export function orderedProjectEnvSchemaReport(input: unknown): OrderedProjectEnvSchemaReport {
+  return isProjectEnvSchemaObservation(input) ? input : UNREADABLE;
+}
+
+/** JSON with every object's keys sorted, no whitespace, and arrays in their
+ *  own order. As on the wire, a field set to undefined is absent, and an
+ *  array's hole or undefined item is null. */
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${Array.from(value, (item) => (item === undefined ? "null" : canonicalJson(item))).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const fields = Object.entries(value)
+      .filter(([, inner]) => inner !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${fields.map(([key, inner]) => `${JSON.stringify(key)}:${canonicalJson(inner)}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+/** The report's canonical bytes: its canonical JSON as UTF-8. Two reports
+ *  with the same bytes are the same report as JSON on the wire. */
+export function canonicalProjectEnvSchemaReportBytes(report: OrderedProjectEnvSchemaReport): Uint8Array {
+  return new TextEncoder().encode(canonicalJson(report));
+}
+
+/** Byte by byte as unsigned values; a prefix before anything longer that
+ *  starts with it. */
+function compareBytes(a: Uint8Array, b: Uint8Array): number {
+  const shared = Math.min(a.length, b.length);
+  for (let index = 0; index < shared; index += 1) {
+    if (a[index] !== b[index]) return a[index]! < b[index]! ? -1 : 1;
+  }
+  return Math.sign(a.length - b.length);
+}
+
+/** What a report says: nothing about the schema (0), that the repository is
+ *  empty (1), or a reading of a commit, readable or not (2). */
+function says(report: OrderedProjectEnvSchemaReport): 0 | 1 | 2 {
+  if (report.status === "unreadable_report" || report.baseOid === null) {
+    return report.status === "resolved" ? 1 : 0;
+  }
+  return 2;
+}
+
+const epochOf = (report: OrderedProjectEnvSchemaReport): number =>
+  report.status === "unreadable_report" ? 0 : report.parserEpoch;
+
+/** Commit time, then commit id (lowercase hex), for two readings of a commit. */
+function compareCommits(a: OrderedProjectEnvSchemaReport, b: OrderedProjectEnvSchemaReport): number {
+  if (a.status === "unreadable_report" || b.status === "unreadable_report") return 0;
+  if (a.baseOid === null || b.baseOid === null) return 0;
+  const time = Math.sign((a.baseCommitTimeMs ?? 0) - (b.baseCommitTimeMs ?? 0));
+  if (time !== 0) return time;
+  return a.baseOid < b.baseOid ? -1 : a.baseOid > b.baseOid ? 1 : 0;
+}
+
+const readable = (report: OrderedProjectEnvSchemaReport): number => (report.status === "resolved" ? 1 : 0);
+
+/** Negative, zero or positive as `a` is below, the same report as, or above
+ *  `b`. Zero only for reports with the same canonical bytes. */
+export function compareProjectEnvSchemaReports(a: OrderedProjectEnvSchemaReport, b: OrderedProjectEnvSchemaReport): number {
+  return (
+    Math.sign(says(a) - says(b)) ||
+    Math.sign(epochOf(a) - epochOf(b)) ||
+    compareCommits(a, b) ||
+    Math.sign(readable(a) - readable(b)) ||
+    compareBytes(canonicalProjectEnvSchemaReportBytes(a), canonicalProjectEnvSchemaReportBytes(b))
+  );
+}
+
+function isNone(value: unknown): boolean {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    Object.keys(value).length === 1 &&
+    Object.hasOwn(value, "status") &&
+    (value as { status: unknown }).status === "none"
+  );
+}
+
+/**
+ * Where one report leaves a project's latest observation. It moves only when
+ * the report is greater than the stored state, and nothing returns it to
+ * none. A stored state that fails its check counts as a report the cloud
+ * could not read, so any valid report repairs it.
+ */
+export function nextLatestProjectEnvSchema(
+  stored: unknown,
+  reportInput: unknown,
+): { moved: boolean; latest: LatestProjectEnvSchema } {
+  const report = orderedProjectEnvSchemaReport(reportInput);
+  if (isNone(stored)) return { moved: true, latest: report };
+  const current = orderedProjectEnvSchemaReport(stored);
+  return compareProjectEnvSchemaReports(report, current) > 0
+    ? { moved: true, latest: report }
+    : { moved: false, latest: current };
+}

package/src/project-env-policy.ts

@@ -0,0 +1,396 @@
+/**
+ * ADR-153 §4 "Pinning": what a task gets for one stored env key, from what
+ * the repository declares for it and what the owner approved (its binding).
+ *
+ * One derivation for the runner, which applies it to each task's own
+ * immutable schema observation, and for the web API, which applies it to a
+ * project's latest observation to show the settings page and to know what
+ * Approve would apply. The two never disagree, and the browser only renders
+ * what the server derived. Pure: no storage, no I/O.
+ *
+ * The bindings, from least to most the owner approved:
+ * - `omit` or `withhold`: nothing reaches the task.
+ * - none (null): today's plain value is delivered, and no domain is
+ *   approved, so a declaration that asks for proxying waits for approval.
+ * - `proxy(domains)`: the key is proxied to those domains only; never
+ *   delivered.
+ * - `passthrough`: the real value may be delivered, so proxying it anywhere
+ *   the repository declares exposes nothing more. It is the top: nothing
+ *   is ever proposed beyond it.
+ * A declaration never widens a binding: anything it asks for beyond it is a
+ * proposal, which only the owner's Approve applies, and until then the task
+ * gets the narrower policy. Approving moves a binding up, so tasks on other
+ * commits only gain (the first proxy approval of an unbound key is the one
+ * exception: it stops delivering the plain value, which is its point).
+ *
+ * Inputs come from storage and frames, so they are checked here with the
+ * contract's guards: a binding the contract rejects withholds the key, and
+ * schema evidence that is not exactly one of its two shapes, with a
+ * declaration the contract accepts, counts as a schema that could not be
+ * read.
+ */
+
+import {
+  MAX_PROJECT_ENV_PROXY_DOMAINS,
+  isDeclaredProjectEnvBinding,
+  isProjectEnvBinding,
+  isProjectEnvSchemaDeclaration,
+  type ProjectEnvBinding,
+  type ProjectEnvPlaceholderShape,
+  type ProjectEnvSchemaDeclaration,
+} from "./protocol";
+
+/**
+ * The newest policy epoch: what `projectEnvKeyPolicy` and
+ * `initialProjectEnvBinding` derive. Bump it with any change to what they
+ * return for some input, and keep the previous epoch's derivation, frozen,
+ * in `PROJECT_ENV_POLICY_EPOCHS`: a binding is read under the epoch it was
+ * written under, and a token the settings page was given under another
+ * epoch is refused, so an owner never approves what a different policy
+ * showed them (ADR-153 §4, "Policy epochs"). The policy test's fingerprints
+ * pin each retained epoch's results on a fixed set of inputs: a tripwire,
+ * not a proof.
+ */
+export const PROJECT_ENV_POLICY_EPOCH = 2;
+
+/** Every policy epoch this build derives under, oldest first. A runner
+ *  advertises this set; the cloud derives under the newest it shares.
+ *
+ * - 1: ADR-153.
+ * - 2: ADR-154 §9, a key the owner declared proxied in Settings (a `proxy`
+ *   binding with `declared`): the repository can only narrow it. Every other
+ *   binding derives exactly as under 1, so it is stored under 1
+ *   (`projectEnvBindingEpoch`) and needs no upgrade. */
+export const PROJECT_ENV_POLICY_EPOCHS: readonly number[] = [1, 2];
+
+/** What one task gets for a key. */
+export type ProjectEnvDecision =
+  | { kind: "deliver" }
+  | { kind: "proxy"; domains: string[] }
+  | { kind: "withhold"; reason: string };
+
+/** Why a key is withheld, beyond the declaration's own unsupported reasons
+ *  and a `withhold` binding's reason. Lower-case snake_case, like every code
+ *  on the wire. */
+export const PROJECT_ENV_WITHHELD_REASONS = [
+  /** The declaration asks for more than the binding approves. */
+  "awaiting_approval",
+  /** The task's schema could not be read, and the key has no binding. */
+  "schema_unavailable",
+  /** The repository declares `@proxy=omit`. */
+  "repository_omits",
+  /** The owner's binding omits it. */
+  "binding_omits",
+  /** The stored binding is not one the contract accepts. */
+  "binding_invalid",
+  /** Approving what the declaration asks for would take the key past the
+   *  domain limit. */
+  "too_many_domains",
+  /** The binding was written under a policy epoch this build does not know. */
+  "policy_epoch_unknown",
+] as const;
+
+export interface ProjectEnvKeyPolicy {
+  decision: ProjectEnvDecision;
+  /** The binding the declaration asks for, when it is wider than the one
+   *  approved. Only the owner's Approve applies it; it always passes the
+   *  contract's binding guard. */
+  proposal: ProjectEnvBinding | null;
+  /** Why the declaration's wider ask cannot be proposed at all. */
+  blocked: "too_many_domains" | null;
+}
+
+/** What a task's schema says about one key: its declaration (null if the
+ *  repository does not declare it), or that the schema could not be read. */
+export type ProjectEnvSchemaEvidence =
+  | { status: "resolved"; declaration: ProjectEnvSchemaDeclaration | null }
+  | { status: "unavailable" };
+
+const withhold = (reason: string): ProjectEnvDecision => ({ kind: "withhold", reason });
+const sorted = (domains: Iterable<string>): string[] => [...new Set(domains)].sort();
+const policy = (
+  decision: ProjectEnvDecision,
+  proposal: ProjectEnvBinding | null = null,
+  blocked: ProjectEnvKeyPolicy["blocked"] = null,
+): ProjectEnvKeyPolicy => ({ decision, proposal, blocked });
+
+/** An object with exactly these own fields: none missing, inherited or extra. */
+function exactly(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    keys.every((key) => Object.hasOwn(value, key)) &&
+    Object.keys(value).length === keys.length
+  );
+}
+
+/** Schema evidence in exactly one of its two shapes, with a declaration the
+ *  contract accepts; anything else could not be read. */
+function evidenceOf(schema: unknown): ProjectEnvSchemaEvidence {
+  if (exactly(schema, ["status", "declaration"]) && schema.status === "resolved") {
+    const { declaration } = schema;
+    if (declaration === null) return { status: "resolved", declaration: null };
+    if (isProjectEnvSchemaDeclaration(declaration)) return { status: "resolved", declaration };
+  }
+  return { status: "unavailable" };
+}
+
+/** What the binding alone gives a key, with nothing declared beyond it. */
+function bindingDecision(binding: ProjectEnvBinding | null): ProjectEnvDecision {
+  if (binding === null || binding.kind === "passthrough") return { kind: "deliver" };
+  if (binding.kind === "proxy") return { kind: "proxy", domains: sorted(binding.domains) };
+  if (binding.kind === "omit") return withhold("binding_omits");
+  return withhold(binding.reason);
+}
+
+/** Whether a binding may hand the task the real value. */
+const deliversValue = (binding: ProjectEnvBinding | null): boolean =>
+  binding === null || binding.kind === "passthrough";
+
+/**
+ * What a task gets for one key under epoch 1 (ADR-153), frozen: what its
+ * declaration proposes beyond the binding, and why a wider ask cannot be
+ * proposed if so. A binding declared in Settings did not exist under it, and
+ * is one it cannot accept.
+ */
+function projectEnvKeyPolicyV1(schemaInput: unknown, bindingInput: unknown): ProjectEnvKeyPolicy {
+  if (bindingInput !== null && (!isProjectEnvBinding(bindingInput) || isDeclaredProjectEnvBinding(bindingInput))) {
+    return policy(withhold("binding_invalid"));
+  }
+  const binding = bindingInput as ProjectEnvBinding | null;
+  const schema = evidenceOf(schemaInput);
+
+  if (schema.status === "unavailable") {
+    // Nothing declared can be trusted: a bound key follows its binding, and
+    // an unbound one is withheld rather than delivered as a plain value.
+    return policy(binding === null ? withhold("schema_unavailable") : bindingDecision(binding));
+  }
+  // An undeclared key is a plain value, like one declared with no directive.
+  const directive = schema.declaration?.directive ?? { kind: "none" as const };
+
+  switch (directive.kind) {
+    case "none":
+    case "passthrough":
+      // A plain value: the binding decides, and where it does not deliver
+      // (proxy, omit, withhold), delivering is a proposal.
+      return policy(bindingDecision(binding), deliversValue(binding) ? null : { kind: "passthrough" });
+
+    // The repository's own withholding wins under every binding.
+    case "omit":
+      return policy(withhold("repository_omits"));
+
+    case "unsupported":
+      return policy(withhold(directive.reason));
+
+    case "proxy": {
+      const declared = sorted(directive.domains);
+      // passthrough is the top: proxying exposes nothing it did not allow.
+      if (binding?.kind === "passthrough") return policy({ kind: "proxy", domains: declared });
+      // Otherwise only approved domains, which only a proxy binding has.
+      const approved = binding?.kind === "proxy" ? binding.domains : [];
+      const allowed = declared.filter((domain) => approved.includes(domain));
+      const decision: ProjectEnvDecision =
+        allowed.length > 0
+          ? { kind: "proxy", domains: allowed }
+          : binding === null || binding.kind === "proxy"
+            ? withhold("awaiting_approval")
+            : bindingDecision(binding);
+      if (allowed.length === declared.length) return policy(decision);
+      // Wider than approved: propose the approved and declared domains
+      // together, unless that would take the key past the domain limit.
+      const union = sorted([...approved, ...declared]);
+      if (union.length > MAX_PROJECT_ENV_PROXY_DOMAINS) {
+        return policy(allowed.length > 0 ? decision : withhold("too_many_domains"), null, "too_many_domains");
+      }
+      return policy(decision, { kind: "proxy", domains: union });
+    }
+  }
+}
+
+/**
+ * ADR-154 §9: a key the owner declared proxied in Settings. Declaring was the
+ * owner's approval of exactly these domains, which the repository's schema
+ * can only narrow:
+ * - unreadable, undeclared, plain or `passthrough`: proxied to the declared
+ *   domains, and nothing proposed (the repository never asks to deliver it);
+ * - `@proxy=omit`, or an unsupported directive: withheld;
+ * - `@proxy` naming some of the declared domains: proxied to those; any it
+ *   names beyond them are a proposal (still declared), as in ADR-153, or
+ *   blocked past the domain limit.
+ */
+function declaredKeyPolicy(
+  schema: ProjectEnvSchemaEvidence,
+  binding: Extract<ProjectEnvBinding, { kind: "proxy" }> & { declared: { placeholder: ProjectEnvPlaceholderShape | null } },
+): ProjectEnvKeyPolicy {
+  const settings = sorted(binding.domains);
+  const asDeclared: ProjectEnvDecision = { kind: "proxy", domains: settings };
+  if (schema.status === "unavailable") return policy(asDeclared);
+  const directive = schema.declaration?.directive ?? { kind: "none" as const };
+  switch (directive.kind) {
+    case "none":
+    case "passthrough":
+      return policy(asDeclared);
+    case "omit":
+      return policy(withhold("repository_omits"));
+    case "unsupported":
+      return policy(withhold(directive.reason));
+    case "proxy": {
+      const declared = sorted(directive.domains);
+      const allowed = declared.filter((domain) => settings.includes(domain));
+      const decision: ProjectEnvDecision =
+        allowed.length > 0 ? { kind: "proxy", domains: allowed } : withhold("awaiting_approval");
+      if (allowed.length === declared.length) return policy(decision);
+      const union = sorted([...settings, ...declared]);
+      if (union.length > MAX_PROJECT_ENV_PROXY_DOMAINS) {
+        return policy(allowed.length > 0 ? decision : withhold("too_many_domains"), null, "too_many_domains");
+      }
+      return policy(decision, { kind: "proxy", domains: union, declared: { placeholder: binding.declared.placeholder } });
+    }
+  }
+}
+
+/**
+ * What a task gets for one key under the newest epoch (2), what its
+ * declaration proposes beyond the binding, and why a wider ask cannot be
+ * proposed if so. `binding` is null for a row the owner never approved. Both
+ * arguments are checked: see the file's header. A binding declared in
+ * Settings follows `declaredKeyPolicy`; every other derives as under epoch 1.
+ */
+export function projectEnvKeyPolicy(schemaInput: unknown, bindingInput: unknown): ProjectEnvKeyPolicy {
+  if (bindingInput !== null && !isProjectEnvBinding(bindingInput)) return policy(withhold("binding_invalid"));
+  if (isDeclaredProjectEnvBinding(bindingInput as ProjectEnvBinding | null)) {
+    return declaredKeyPolicy(
+      evidenceOf(schemaInput),
+      bindingInput as Parameters<typeof declaredKeyPolicy>[1],
+    );
+  }
+  return projectEnvKeyPolicyV1(schemaInput, bindingInput);
+}
+
+/**
+ * The binding a value is stored with when its row has none yet (ADR-153 §4:
+ * "a value set in settings is stored atomically with the policy the owner
+ * was shown"): what the project's latest schema declares for the key, as
+ * the settings page showed it. Null when it declares nothing: the row stays
+ * unbound, a plain value. Where the schema could not be read the page showed
+ * the key withheld, and so it stays (withhold: schema_unavailable): a schema
+ * that later reads as plain cannot deliver it without the owner's Approve.
+ *
+ * A project no task has reported a schema for yet (`none`) has no evidence
+ * to pass: the caller branches on it first and leaves the row unbound. Here,
+ * anything that is not evidence, null included, is a schema that could not
+ * be read.
+ */
+export function initialProjectEnvBinding(schemaInput: unknown): ProjectEnvBinding | null {
+  const schema = evidenceOf(schemaInput);
+  if (schema.status === "unavailable") return { kind: "withhold", reason: "schema_unavailable" };
+  if (schema.declaration === null) return null;
+  const { directive } = schema.declaration;
+  switch (directive.kind) {
+    case "none":
+      return null;
+    case "proxy":
+      return { kind: "proxy", domains: sorted(directive.domains) };
+    case "passthrough":
+      return { kind: "passthrough" };
+    case "omit":
+      return { kind: "omit" };
+    case "unsupported":
+      return { kind: "withhold", reason: directive.reason };
+  }
+}
+
+/**
+ * What a task gets for one key under the epoch its binding was written
+ * under. An epoch this build does not know withholds the key, with nothing
+ * proposed: it never falls back to another epoch's meaning.
+ */
+export function projectEnvKeyPolicyAt(epoch: unknown, schemaInput: unknown, bindingInput: unknown): ProjectEnvKeyPolicy {
+  switch (epoch) {
+    case 1:
+      return projectEnvKeyPolicyV1(schemaInput, bindingInput);
+    case 2:
+      return projectEnvKeyPolicy(schemaInput, bindingInput);
+    default:
+      return policy(withhold("policy_epoch_unknown"));
+  }
+}
+
+/** The binding a first save stores under a given epoch; withheld under an
+ *  epoch this build does not know. Epoch 2 stores what 1 does: a Settings
+ *  declaration is the owner's own act, never a first save's. */
+export function initialProjectEnvBindingAt(epoch: unknown, schemaInput: unknown): ProjectEnvBinding | null {
+  switch (epoch) {
+    case 1:
+    case 2:
+      return initialProjectEnvBinding(schemaInput);
+    default:
+      return { kind: "withhold", reason: "policy_epoch_unknown" };
+  }
+}
+
+/**
+ * The placeholder shape a proxied key's task gets, under its binding's
+ * epoch: the repository's `@placeholder` when its schema declares the key
+ * proxied with one; under epoch 2 a Settings declaration's shape next; null
+ * otherwise (the default shape). Only meaningful for a key the policy
+ * proxies; checked like the policy's own inputs.
+ */
+export function projectEnvPlaceholderAt(
+  epoch: unknown,
+  schemaInput: unknown,
+  bindingInput: unknown,
+): ProjectEnvPlaceholderShape | null {
+  if (epoch !== 1 && epoch !== 2) return null;
+  const schema = evidenceOf(schemaInput);
+  const fromSchema =
+    schema.status === "resolved" && schema.declaration?.directive.kind === "proxy"
+      ? (schema.declaration.placeholder ?? null)
+      : null;
+  if (fromSchema !== null || epoch === 1) return fromSchema;
+  const binding = bindingInput !== null && isProjectEnvBinding(bindingInput) ? bindingInput : null;
+  return isDeclaredProjectEnvBinding(binding) ? binding.declared.placeholder : null;
+}
+
+/**
+ * The epoch to store a binding under: the lowest this build knows whose
+ * derivation for it is the newest's, never below `floor` (a record's epoch
+ * only moves up). A declared binding needs 2; every other means under 1 what
+ * it means under 2, so it stays readable by runners that know only 1.
+ */
+export function projectEnvBindingEpoch(binding: ProjectEnvBinding | null, floor = 1): number {
+  return Math.max(isDeclaredProjectEnvBinding(binding) ? 2 : 1, floor);
+}
+
+/** Whether moving a binding from one epoch to a newer one changes what any
+ *  task would get: only then is an upgrade offered for the owner's Approve. */
+export function projectEnvEpochUpgradeChanges(fromEpoch: number, toEpoch: number, binding: unknown): boolean {
+  if (fromEpoch >= toEpoch) return false;
+  // Epochs 1 and 2 derive the same for every binding valid under 1.
+  return !(fromEpoch === 1 && toEpoch === 2 && !(isProjectEnvBinding(binding) && isDeclaredProjectEnvBinding(binding)));
+}
+
+/** The most policy epochs a runner may advertise. */
+export const MAX_ADVERTISED_PROJECT_ENV_POLICY_EPOCHS = 64;
+
+/** A runner's advertised epochs: a dense array of unique positive safe
+ *  integers, no longer than the bound. Anything else is no set at all. */
+function isAdvertisedEpochSet(value: unknown): value is number[] {
+  if (!Array.isArray(value) || value.length > MAX_ADVERTISED_PROJECT_ENV_POLICY_EPOCHS) return false;
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index)) return false;
+    const epoch: unknown = value[index];
+    if (typeof epoch !== "number" || !Number.isSafeInteger(epoch) || epoch < 1) return false;
+  }
+  return new Set(value).size === value.length;
+}
+
+/** The newest policy epoch this build shares with a runner's advertised set,
+ *  or null when they share none, or the set is malformed: then nothing is
+ *  derived for that runner. */
+export function sharedProjectEnvPolicyEpoch(advertised: unknown): number | null {
+  if (!isAdvertisedEpochSet(advertised)) return null;
+  const shared = PROJECT_ENV_POLICY_EPOCHS.filter((epoch) => advertised.includes(epoch));
+  return shared.length > 0 ? Math.max(...shared) : null;
+}