@jr2/orchestrator 0.2.1 → 0.4.1

package/src/names.ts

@@ -9,16 +9,29 @@ export const ORCHESTRATOR_PORT = 4000;
 /** The instance-owned Secret: Instance token + signing key (+ orchestrator-side creds). */
 export const INSTANCE_SECRET = "jr2-instance";
 
-/** The Instance Harness's Deployment + Service name (ADR-0031): converged by `jr2 up` whenever any
+/** The Instance Harness's StatefulSet + Service name (ADR-0031): converged by `jr2 up` whenever any
  * Agent definition declares `workspace: "none"`, and the deterministic Service DNS the Agent actor
  * resolves such a Turn to. Doubles as the delivery scope a Menu-only registration records — the
- * name the placement's Adapter token is signed for (tokens.ts, ADR-0013). The port is the
+ * name the placement's Sandbox token is signed for (tokens.ts, ADR-0013), which its Custodian holds. The port is the
  * Harness's own listen port (`PORT` default). */
 export const INSTANCE_HARNESS_SERVICE = "jr2-instance-harness";
 export const INSTANCE_HARNESS_PORT = 8080;
 
+/** The Instance Effector (ADR-0068): its Deployment, headless Service, NetworkPolicy and Secret all
+ * carry this name. `jr2 up` converges them when a registered Machine places an Effect there. The
+ * port is the Effector's own (`JR2_EFFECTOR_PORT` default) — none of the Harness pod's ports. */
+export const INSTANCE_EFFECTOR = "jr2-instance-effector";
+export const EFFECTOR_PORT = 8082;
+
+/** Where a Harness persists its conversations, and the env var that tells it so (ADR-0031): one
+ * fixed path in both placements — the Instance Harness's PersistentVolumeClaim (deploy.ts) and a
+ * Sandbox's emptyDir (sandbox-kube.ts), each mounted into the Harness container alone. */
+export const CONVERSATIONS_DIR = "/conversations";
+export const CONVERSATIONS_DIR_ENV = "JR2_CONVERSATIONS_DIR";
+export const CONVERSATIONS_VOLUME = "conversations";
+
 /** The harness config ConfigMap the stock Harness boots from (ADR-0018): what this instance can
- * REACH — the custom model provider, minus its key. No Agents ride it: a Machine carries its own
+ * REACH — the custom model provider minus its key, and the catalog providers' gateways (ADR-0059). No Agents ride it: a Machine carries its own
  * (ADR-0049), and the definition rides each admission, so this holds deployment facts alone
  * (ADR-0050). */
 export const HARNESS_CONFIGMAP = "jr2-harness";
@@ -26,7 +39,7 @@ export const HARNESS_CONFIGMAP = "jr2-harness";
 export const HARNESS_CONFIG_KEY = "harness.json";
 
 /** The resolved image map `jr2 up` writes and every provision reads (ADR-0037/0038): key → ref for
- * the Harness, the Adapter, and every Sandbox Image context the registered Machines carry — keyed
+ * the Harness, the Custodian, and every Sandbox Image context the registered Machines carry — keyed
  * by content digest, plus the reserved `default` (ADR-0049).
  *
  * MOUNTED, never projected into env — the load-bearing part. A mount updates in place through
@@ -38,13 +51,60 @@ export const IMAGES_MOUNT = "/etc/jr2/images";
 /** The ConfigMap key, hence the filename under the mount — the two-sided contract's other half. */
 export const IMAGES_KEY = "images.json";
 
-/** The HARNESS containers' env Secret — Agent creds only, never the Instance token (ADR-0013). */
+/** The HARNESS containers' env Secret — the literal `harness.env` values, never the Instance token
+ * (ADR-0013) and never a model key (ADR-0059: those are held). */
 export const HARNESS_ENV_SECRET = "jr2-harness-env";
 
-/** The instance's private-CA bundle ConfigMap (`harness.caBundle`, ADR-0020) — mounted into the
- * Harness container (and only it) so Agent egress trusts an internal CA. Public data by nature. */
+/** The instance's trust ConfigMap (ADR-0020, ADR-0059): the user's `harness.caBundle` as `ca.crt`
+ * and, while a held secret exists, the three bundles the held-secret path needs — `extra.crt` and
+ * `bundle.crt` for the Harness, `upstream.crt` for the Custodian. Public data by nature. */
 export const CA_CONFIGMAP = "jr2-ca";
 
+/** Held secrets (ADR-0059). The per-Instance CA — its key included — that `jr2 up` alone reads over
+ * the kube API, and that NO pod mounts: every leaf is issued before a pod starts. */
+export const HELD_CA_SECRET = "jr2-held-ca";
+/** The prefix of each pod's literal held values (`heldSecretsSecret`): one Secret per pod, one key
+ * per name it holds — mounted into that pod's Custodian and nothing else. */
+export const HELD_SECRETS_SECRET = "jr2-held-secrets";
+/** The literal held values of one pod (ADR-0059): `jr2-held-secrets-<pod>`. */
+export function heldSecretsSecret(pod: string): string {
+  return `${HELD_SECRETS_SECRET}-${pod}`;
+}
+/** One leaf per bound `host:port` (`<stem>.crt`, `<stem>.key`) — the Custodians' alone. */
+export const HELD_TLS_SECRET = "jr2-held-tls";
+/** What `jr2 up` DECLARES about held secrets: each pod's held manifest (`heldManifestKey` — names,
+ * bindings, headers; never a value) and the Custodian's program once (`CUSTODIAN_PROGRAM_KEY`).
+ * Nothing rendered per pod lives here: a shared object stops at 1 MiB, and Envoy's files are a
+ * pod's own, rendered where the pod is made (`sandboxCustodianConfigMap`,
+ * `INSTANCE_CUSTODIAN_CONFIGMAP`). Always applied, possibly holding no secret: every Harness pod
+ * runs a Custodian. */
+export const HELD_CONFIGMAP = "jr2-held";
+/** Where the Orchestrator reads a Workspace's held manifest, per provision — a mount, so a
+ * held-secret edit reaches future Sandboxes without rolling the Orchestrator (the `jr2-images`
+ * pattern, ADR-0038). */
+export const HELD_MOUNT = "/etc/jr2/held";
+/** The `jr2-held` key of one pod's manifest. */
+export const heldManifestKey = (pod: string): string => `held-${pod}.json`;
+/** The `jr2-held` key of the Custodian's fixed Lua — `custodian.lua` as written, once per Instance;
+ * each pod's own script loads it by this name from its config mount. */
+export const CUSTODIAN_PROGRAM_KEY = "program.lua";
+/** The ConfigMap with the Instance Harness's Custodian's two rendered files (`envoy.json`,
+ * `custodian.lua`), written by `jr2 up`: the one pod it makes. */
+export const INSTANCE_CUSTODIAN_CONFIGMAP = "jr2-held-custodian";
+/** The ConfigMap with one Sandbox's Custodian's two rendered files, written by the Orchestrator at
+ * provision and owned by the Sandbox CR — the `<name>-token` family: it goes with the pod. */
+export const sandboxCustodianConfigMap = (sandbox: string): string => `${sandbox}-custodian`;
+/** The Instance Harness's pod, as its held objects are keyed. A Workspace's is `ws-<digest>`
+ * (`workspaceHeldPod`), so the two cannot collide. */
+export const INSTANCE_HARNESS_HELD_POD = "instance";
+
+/** The Custodian's listeners (ADR-0059), all taken on every Harness pod (ADR-0005): the Harness's
+ * HTTPS proxy on loopback, the kubelet's probe, and the control listener the Menu and the ask ride
+ * to the Orchestrator, at the address `jr2-upload-pack` defaults to (ADR-0053). */
+export const CUSTODIAN_PORT = 15001;
+export const CUSTODIAN_HEALTH_PORT = 15021;
+export const CUSTODIAN_CONTROL_PORT = 8081;
+
 /** The scaffold's default deploy-key Secret name (ADR-0047/0051): what `jr2 init`'s wildcard
  * `git.credentials` entry names as its `sshKey`, and what `jr2 up`'s ssh offer generates into when
  * an entry names it. Only a default — an entry may name any Secret. */
@@ -76,3 +136,25 @@ export const ANNOTATION_REPO_LAST_ATTACHED = "jr2.dev/last-attached";
  * that started before the ask does not satisfy it. The Lease's shape: an annotation, written by
  * the Orchestrator, read by the operator. */
 export const askedAnnotation = (key: string): string => `jr2.dev/asked-${key}`;
+
+/** The two PriorityClasses `jr2 up` creates, cluster-scoped, beside the CRDs (ADR-0060) — unless
+ * `priorityClasses` in jr2.config.ts names existing ones. `jr2-control` (100000,
+ * PreemptLowerPriority) is for the Orchestrator, the operator and the Repo cache agent: small, fixed,
+ * and needed by every Sandbox. `jr2-sandbox` (1000, preemptionPolicy Never) is for Sandboxes and the
+ * Instance Harness: an ordinary pod cannot preempt a live Workspace, and a waiting Sandbox evicts
+ * nobody. Both stay far below the system classes. */
+export const PRIORITY_CLASS_CONTROL = "jr2-control";
+export const PRIORITY_CLASS_SANDBOX = "jr2-sandbox";
+
+/** The voluntary-disruption opt-outs (ADR-0060) a Sandbox pod and the Instance Harness pod carry:
+ * moving either loses work (`/work`; live conversations). No PodDisruptionBudget — `maxUnavailable:
+ * 0` blocks node upgrades without end. */
+export const NO_DISRUPT_ANNOTATIONS = {
+  "cluster-autoscaler.kubernetes.io/safe-to-evict": "false",
+  "karpenter.sh/do-not-disrupt": "true",
+} as const;
+
+/** The API server's CA as the kubelet mounts it with the Pod's ServiceAccount. The Orchestrator
+ * Deployment points `NODE_EXTRA_CA_CERTS` at it, so the Orchestrator's own Kubernetes client
+ * (kube-client.ts, ADR-0063) trusts the API server with built-in `fetch` and no TLS code. */
+export const SERVICE_ACCOUNT_CA = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt";

package/src/notices.ts

@@ -0,0 +1,88 @@
+// The Orchestrator's notices (ADR-0062): what happened that the next Turn cannot find out for
+// itself — a memory kill in its Workspace, a conversation that is new — kept as plain data in the
+// run's persisted state (ADR-0007), beside the admission and epoch ledgers, and handed to the next
+// admission in scope. The Harness writes every word; this is only the keeping.
+//
+// Delivered ONCE, and "delivered" means LEDGERED: a notice leaves the pending set in the same save
+// that records the admission it rode. A restart before that save finds it still pending and the
+// restored Turn's admission carries it again; a restart after it does not. Between `take` and that
+// save the notice is RESERVED, in memory only, so a second admission in the same scope cannot carry
+// it too — and a restart forgets reservations along with everything else in memory.
+
+import type { Notice } from "./wire.ts";
+
+/** Where an admission may hear notices: its continued conversation's base Instance ID (ADR-0057)
+ * and its Workspace's Sandbox name. Either may be absent — a fresh Turn has no conversation to be
+ * told about, and a Menu-only Agent works in no Workspace. */
+export type NoticeScope = { conversation?: string; workspace?: string };
+
+/** One pending notice: the notice, and the conversation or Workspace it goes to. `source` names
+ * the event that raised it, so the same event raised twice — two Turns lost to one kernel kill, a
+ * stream read replayed after a restore — is one notice. */
+export type PendingNotice = { id: string; notice: Notice; to: string; source?: string };
+
+/** The persisted form (`RunBlob.notices`). `seen` is every source ever raised, so a delivered
+ * notice is not raised again by a late or replayed witness of the same event. */
+export type NoticeLedgerState = { pending: PendingNotice[]; seen: string[] };
+
+/** What one admission takes: the notices it carries, and their ids for the ledger write. */
+export type TakenNotices = { ids: string[]; notices: Notice[] };
+
+export class NoticeLedger {
+  readonly #pending: PendingNotice[];
+  readonly #seen: Set<string>;
+  readonly #reserved = new Set<string>();
+  readonly #newId: () => string;
+
+  constructor(state: NoticeLedgerState | undefined, newId: () => string) {
+    this.#pending = [...(state?.pending ?? [])];
+    this.#seen = new Set(state?.seen ?? []);
+    this.#newId = newId;
+  }
+
+  /** Raise a notice for `to` (a conversation's base id, or a Sandbox name — the notice's own
+   * `scope` says which). False when `source` was already raised, or the same notice is already
+   * pending for `to`. */
+  raise(notice: Notice, to: string, source?: string): boolean {
+    if (source !== undefined) {
+      if (this.#seen.has(source)) return false;
+      this.#seen.add(source);
+    }
+    // The same news, still unheard, is one notice: the guard writes one kill to the stream of
+    // every conversation running in the pod, and each Turn following one reads it.
+    const same = JSON.stringify(notice);
+    if (this.#pending.some((p) => p.to === to && JSON.stringify(p.notice) === same)) return false;
+    this.#pending.push({ id: this.#newId(), notice, to, ...(source === undefined ? {} : { source }) });
+    return true;
+  }
+
+  /** Reserve every unreserved notice in this admission's scope, in the order raised. */
+  take(scope: NoticeScope): TakenNotices {
+    const taken = this.#pending.filter(
+      (p) =>
+        !this.#reserved.has(p.id) &&
+        (p.notice.scope === "conversation" ? p.to === scope.conversation : p.to === scope.workspace),
+    );
+    for (const p of taken) this.#reserved.add(p.id);
+    return { ids: taken.map((p) => p.id), notices: taken.map((p) => p.notice) };
+  }
+
+  /** The admission that carried them was ledgered: they are delivered. */
+  delivered(ids: readonly string[]): void {
+    for (const id of ids) {
+      this.#reserved.delete(id);
+      const at = this.#pending.findIndex((p) => p.id === id);
+      if (at !== -1) this.#pending.splice(at, 1);
+    }
+  }
+
+  /** The admission that carried them failed: they are pending again, for the next one. */
+  release(ids: readonly string[]): void {
+    for (const id of ids) this.#reserved.delete(id);
+  }
+
+  /** The persisted form — reserved notices included, because reserved is not delivered. */
+  state(): NoticeLedgerState {
+    return { pending: [...this.#pending], seen: [...this.#seen] };
+  }
+}