@runuai/host 0.9.148 → 0.9.150

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,281 @@
+/**
+ * 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,
+  isProjectEnvBinding,
+  isProjectEnvSchemaDeclaration,
+  type ProjectEnvBinding,
+  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 = 1;
+
+/** Every policy epoch this build derives under, oldest first. A runner
+ *  advertises this set; the cloud derives under the newest it shares. */
+export const PROJECT_ENV_POLICY_EPOCHS: readonly number[] = [1];
+
+/** 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, 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.
+ */
+export function projectEnvKeyPolicy(schemaInput: unknown, bindingInput: unknown): ProjectEnvKeyPolicy {
+  if (bindingInput !== null && !isProjectEnvBinding(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 });
+    }
+  }
+}
+
+/**
+ * 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 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. */
+export function initialProjectEnvBindingAt(epoch: unknown, schemaInput: unknown): ProjectEnvBinding | null {
+  switch (epoch) {
+    case 1:
+      return initialProjectEnvBinding(schemaInput);
+    default:
+      return { kind: "withhold", reason: "policy_epoch_unknown" };
+  }
+}
+
+/** 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;
+}

package/src/project-env-wording.ts

@@ -0,0 +1,47 @@
+/**
+ * ADR-153 §4: why Uai withholds a key, in words for people, by the
+ * contract's snake_case codes. The settings page and the task's note both
+ * read these, so the owner and the task see the same reason.
+ */
+
+import { MAX_PROJECT_ENV_PROXY_DOMAINS } from "./protocol";
+
+const WITHHELD_REASONS: Readonly<Record<string, string>> = {
+  // The repository's @proxy, as the parser reports it.
+  malformed: "its @proxy could not be read",
+  invalid_value: "its @proxy is neither a domain, passthrough nor omit",
+  conflicting_forms: "its @proxy declarations conflict",
+  missing_domain: "its @proxy names no domain",
+  option_path: "its @proxy uses path, which Uai does not support",
+  option_method: "its @proxy uses method, which Uai does not support",
+  option_block: "its @proxy uses block, which Uai does not support",
+  option_keys: "its @proxy uses keys, which Uai does not support",
+  option_substitute_in: "its @proxy uses substituteIn, which Uai does not support",
+  option_transform: "its @proxy uses transform, which Uai does not support",
+  option_approval: "its @proxy uses approval, which Uai does not support",
+  option_rules: "its @proxy uses rules, which Uai does not support",
+  option_unknown: "its @proxy uses an option Uai does not know",
+  wildcard_domain: "a wildcard domain cannot be pinned",
+  ip_literal: "an IP address cannot be proxied",
+  localhost: "localhost cannot be proxied",
+  reserved_domain: "Uai itself depends on that domain",
+  invalid_domain: "its domain is not a public DNS name",
+  // The repository's own list, or that list with the approved ones: either
+  // way, more than one key may be proxied to.
+  too_many_domains: `it would take the key past ${MAX_PROJECT_ENV_PROXY_DOMAINS} proxy domains`,
+  header_rule: "a header-level @proxy rule names it",
+  duplicate_key: "the repository declares it more than once",
+  // A runner's state for the key.
+  awaiting_approval: "waiting for approval",
+  schema_unavailable: "its .env.schema could not be read",
+  repository_omits: "the repository omits it",
+  binding_omits: "omitted on this runner",
+  binding_invalid: "this runner's approval for it could not be read",
+  policy_epoch_unknown: "it was approved under a policy this runner does not know; update the runner",
+};
+
+/** The words for a withheld reason. A code these words do not know yet still
+ *  reads as withheld, with the code shown. */
+export function projectEnvWithheldReason(reason: string): string {
+  return Object.hasOwn(WITHHELD_REASONS, reason) ? WITHHELD_REASONS[reason]! : `not supported (${reason})`;
+}