@runuai/host 0.9.150 → 0.9.151

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/project-env-policy.ts

@@ -32,9 +32,11 @@
 
 import {
   MAX_PROJECT_ENV_PROXY_DOMAINS,
+  isDeclaredProjectEnvBinding,
   isProjectEnvBinding,
   isProjectEnvSchemaDeclaration,
   type ProjectEnvBinding,
+  type ProjectEnvPlaceholderShape,
   type ProjectEnvSchemaDeclaration,
 } from "./protocol";
 
@@ -49,11 +51,17 @@ import {
  * pin each retained epoch's results on a fixed set of inputs: a tripwire,
  * not a proof.
  */
-export const PROJECT_ENV_POLICY_EPOCH = 1;
+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. */
-export const PROJECT_ENV_POLICY_EPOCHS: readonly number[] = [1];
+ *  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 =
@@ -141,13 +149,15 @@ 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.
+ * 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.
  */
-export function projectEnvKeyPolicy(schemaInput: unknown, bindingInput: unknown): ProjectEnvKeyPolicy {
-  if (bindingInput !== null && !isProjectEnvBinding(bindingInput)) return policy(withhold("binding_invalid"));
+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);
 
@@ -198,6 +208,66 @@ export function projectEnvKeyPolicy(schemaInput: unknown, bindingInput: unknown)
   }
 }
 
+/**
+ * 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
@@ -239,6 +309,8 @@ export function initialProjectEnvBinding(schemaInput: unknown): ProjectEnvBindin
 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"));
@@ -246,16 +318,59 @@ export function projectEnvKeyPolicyAt(epoch: unknown, schemaInput: unknown, bind
 }
 
 /** The binding a first save stores under a given epoch; withheld under an
- *  epoch this build does not know. */
+ *  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;