~ knotless Search/
↑↓ move↵ open⇧↵ all results

johnandersen777.bsky.social/socialweb-computer-console

console.socialweb.computer: kcp, kubectl and ssh compiled to wasm in a browser tab with a terminal; a kcp fork

0
0
main
1100 lines · 50.9 KB Raw History
// Copyright 2026 The KCP Authors.
// SPDX-License-Identifier: Apache-2.0

// Pure helpers for the page's Compute panel: contract names, phases and the
// ComputeContract manifest. A VM gets both shells: ssh over WebRTC (plan
// 0034; the page's key in sshAuthorizedKeys) and, when the served schema
// still has spec.tunnels[].shell, the wootty web terminal behind opentunnel
// (plan 0032; a browser-made token in a vault bundle the guest fetches
// through secretsRef). The webrtc shell is up ~2 s after Held; the wootty
// address takes 70-165 s, waiting on its TLS certificate. With the agent
// (plan 0035, spec.agent) the bundle also holds an ATIRC_TOKEN placeholder
// the requester fills with a minted atirc token; the guest starts the agent
// on an events.guest.agentStart ContractEvent (the Agent button).

export const WOOTTY_TAG = "wootty";
export const WOOTTY_PORT = 7681;
export const WOOTTY_ENV = "/etc/wootty/wootty.env";
export const ATIRC_ENV = "/etc/atirc/atirc.env";
export const SSH_TAG = "ssh";
export const SECRETS_MOUNT = "requester";
// The requester policy on every page contract, as the CLI's `run request`
// defaults contract.policy (socialweb requester.DefaultPolicyWorkflow); the
// PolicyEngine runs it in the fenced browser sandbox (plan 0037).
export const REQUESTER_POLICY = "requester-tangled-vouch";
export const GUEST_TOOL = "socialweb-computer";
export const R2_ASSOCIATES_ITSELF = "R2 associates itself; leave Associate DID empty";

/** The per-tab EphemeralInfra record lives long enough to outlast a page session. */
export const ORIGIN_INFRA_TTL_SECONDS = 30 * 24 * 3600;

const INFRA_RECORD_CAP = 64;

export function base64url(bytes) {
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

/** 24 random bytes, base64url without padding: 32 chars, wootty's minimum. */
export function randomToken() {
  return base64url(crypto.getRandomValues(new Uint8Array(24)));
}

export function contractName(bytes = crypto.getRandomValues(new Uint8Array(6))) {
  const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
  return "vmshell-" + Array.from(bytes, (b) => alphabet[b % alphabet.length]).join("");
}

export function randomTabId(bytes = crypto.getRandomValues(new Uint8Array(6))) {
  const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
  return Array.from(bytes, (b) => alphabet[b % alphabet.length]).join("");
}

/** FNV-1a 64-bit, 16 lowercase hex chars. Synchronous and secure-context free. */
export function fnv1a64(text) {
  let hash = 0xcbf29ce484222325n;
  for (const byte of new TextEncoder().encode(String(text))) {
    hash = ((hash ^ BigInt(byte)) * 0x100000001b3n) & 0xffffffffffffffffn;
  }
  return hash.toString(16).padStart(16, "0");
}

/**
 * The EphemeralInfra object name, which is also the atproto record rkey. One
 * record per tab: the origin and a stable per-tab id, with the origin hash so
 * scheme/port changes cannot collide. Kept short enough that
 * einfra-<name>-vmshell-xxxxxx stays a DNS label.
 */
export function originInfraName(origin, tabId) {
  const raw = String(origin ?? "").trim().toLowerCase();
  let host = raw;
  try {
    host = new URL(raw).host;
  } catch {
    // Not an absolute origin: sanitize the raw value below.
  }
  const slug = host.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 12).replace(/-+$/g, "") || "origin";
  const tab = String(tabId ?? "").toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 6) || "tab";
  return `web-${slug}-${fnv1a64(raw)}-${tab}`;
}

/** Pure JS mirror of internal/contract/atprotorepo.RepoName. */
export function repoName(did) {
  let name = ("repo-" + String(did ?? "")).toLowerCase()
    .replace(/[^a-z0-9.-]+/g, "-")
    .replace(/-+/g, "-")
    .replace(/^[-.]+|[-.]+$/g, "");
  if (!name) name = "repo";
  return name.slice(0, 253).replace(/[-.]+$/g, "");
}

export function infraRepoRef(did) {
  return { group: "socialweb.computer", kind: "AtprotoRepo", name: repoName(did) };
}

// The EventSources the page's compose runs: its MarketRequester has no relay
// (createRoot), so socialweb's watchSources are the public jetstreams, and
// the MarketRequester's watch selector links grant subscribing to them.
export const INFRA_EVENT_SOURCES = ["jetstream-bsky-us-east", "jetstream-bsky-us-west"];

/**
 * The tab infra's spec.record: synced both ways with the signed-in repo and
 * watched through the jetstream EventSources (without eventSourceRefs it takes
 * a per-watch PDS source no link grants: "bus: link denied").
 */
export function infraRecordBinding(did) {
  return {
    repoRef: infraRepoRef(did),
    sync: "Both",
    eventSourceRefs: INFRA_EVENT_SOURCES.map((name) => ({ group: "events.socialweb.computer", kind: "EventSource", name })),
  };
}

/** True when a live spec.record needs patching to infraRecordBinding. */
export function infraRecordStale(binding) {
  return !binding?.repoRef || (binding.sync && binding.sync !== "Both") || !(binding.eventSourceRefs?.length > 0);
}

export function infraCondition(infra, type) {
  return (infra?.status?.conditions ?? []).find((condition) => condition?.type === type) ?? null;
}

export function recordSynced(infra) {
  return infraCondition(infra, "Synced")?.status === "True";
}

// A record read the browser dropped without any HTTP response (Safari "Load
// failed", Chrome "Failed to fetch", Firefox "NetworkError"), as Go's js
// net/http reports it. The controller retries it, so it is not a failure.
const NETWORK_DROP = /fetch\(\) failed|Load failed|Failed to fetch|NetworkError/;

/** True while the controller is retrying a transient record read. */
export function recordSyncRetrying(infra) {
  const synced = infraCondition(infra, "Synced");
  if (synced?.status !== "False") return false;
  return synced.reason === "RecordReadRetrying" || (synced.reason === "RecordUnavailable" && NETWORK_DROP.test(synced.message ?? ""));
}

/** The record sync failure to show, if the record is invalid or unavailable. */
export function recordSyncError(infra) {
  const valid = infraCondition(infra, "RecordValid");
  if (valid?.status === "False") return valid.message || "the EphemeralInfra record is invalid";
  const synced = infraCondition(infra, "Synced");
  if (recordSyncRetrying(infra)) return "";
  if (synced?.status === "False" && (synced.reason === "RecordUnavailable" || synced.reason === "RecordInvalid")) {
    return synced.message || "the EphemeralInfra record is unavailable";
  }
  return "";
}

// The record the controller bound: the infra's name, or (socialweb rc140) a
// successor rkey `<name>-<8 hex of the object UID>` when that name already
// holds an ended record, which is kept rather than deleted; later successors
// of the same object append `-<n>` (socialweb infra.Successor, n >= 2).
export function infraRecordURI(infra, did, name) {
  if (!did || !name) return "";
  const base = `at://${did}/computer.socialweb.ephemeralInfra/${name}`;
  const uri = String(infra?.status?.record?.uri ?? "");
  return uri === base || (uri.startsWith(`${base}-`) && /^[0-9a-f]{8}(-[1-9][0-9]*)?$/.test(uri.slice(base.length + 1))) ? uri : "";
}

/**
 * Replace or append a contract, pruning the oldest released entries when the
 * record is full. Never drops an active entry. Returns the dropped names so
 * the caller can remove their secrets.
 *
 * The always-run rule (owner rule): an active entry without
 * REQUESTER_POLICY is refused, and every other active entry in the record
 * (one an older page or the synced PDS record left without it, or with
 * another policy) is written back with it.
 */
export function addContract(contracts, entry, cap = INFRA_RECORD_CAP) {
  if (entry?.state !== "Released" && entry?.policy !== REQUESTER_POLICY) {
    throw new Error(`refusing contract ${entry?.name}: its policy is ${JSON.stringify(entry?.policy ?? "")}, not ${REQUESTER_POLICY}`);
  }
  const list = (Array.isArray(contracts) ? contracts : []).map((contract) =>
    contract?.state === "Released" || contract?.policy === REQUESTER_POLICY ? contract : { ...contract, policy: REQUESTER_POLICY });
  const index = list.findIndex((contract) => contract?.name === entry.name);
  if (index >= 0) list[index] = entry;
  else list.push(entry);
  const dropped = [];
  while (list.length > cap) {
    const oldest = list.findIndex((contract) => contract?.state === "Released");
    if (oldest < 0) throw new Error(`the EphemeralInfra record is full (${cap} contracts); release a VM first`);
    dropped.push(list[oldest].name);
    list.splice(oldest, 1);
  }
  return { contracts: list, dropped };
}

/** Requested infra entries whose child ComputeContract has already finished. */
export function finishedInfraContracts(infra, contracts) {
  const name = infra?.metadata?.name;
  if (!name) return [];
  const terminal = new Set((contracts ?? [])
    .filter((contract) => contract?.phase === "Released" || contract?.phase === "Failed")
    .map((contract) => contract.name));
  return (infra?.spec?.contracts ?? []).filter((entry) =>
    entry?.state === "Requested" && terminal.has(infraContractName(name, entry.name)));
}

const FINISHED = new Set(["Released", "Failed"]);

/** A contract that still holds (or is getting) a VM and is not being released. */
export function isActive(contract) {
  return !contract?.release && !FINISHED.has(contract?.phase ?? "Pending");
}

/** A contract whose release was asked for but has not finished. */
export function isReleasing(contract) {
  return (Boolean(contract?.release) && !FINISHED.has(contract?.phase ?? "Pending")) || releasePending(contract);
}

/**
 * Release work this tab's requester still runs for the contract: a release in
 * progress (isReleasing), atirc token revokes Pending, or the A8 cascade
 * waiting for the guest requester. Closing the tab then would stall it.
 */
export function releaseWorkPending(contract) {
  return isReleasing(contract) || contract?.atircRevokes === "Pending" || contract?.step === "releasingGuestRequester";
}

// Release requests (socialweb r128 10558978, ephemeralinfras 11): the
// composer is the only writer of a ComputeContract's spec, so the page does
// not write a contract an EphemeralInfra owns. Every Release (the button,
// Release again, d.release and so the demo's leftover sweep) of such a
// contract sets the EphemeralInfra entry to
// {state: Released, releaseRequestedAt: now}; the infra controller copies
// spec.release and the stamp onto the ComputeContract (manager
// socialweb.computer/ephemeralinfra) and re-asks a Failed one for a newer
// stamp. The requester copies the request it answered into
// status.release.requestedAt (the feed's releaseAnsweredAt), and a newer
// request restarts a Failed contract whose ReleaseFailed condition is True.
//
// The page is its EphemeralInfra's composer (linux-kcp, rc128 option A;
// ephemeralinfras 12 makes spec.contracts a list map keyed by name). Every
// infra write (create, add an entry, a record rebind, Release,
// markFinished) is one server-side apply of the page's FULL desired spec
// (INFRA_PAGE_FIELDS: every entry with every field, the secrets, the record
// binding, description, ttl and endWhen) under INFRA_FIELD_MANAGER with
// force, built from a fresh read and re-applied whole (composeInfra). An
// apply that omits something its manager applied before removes it, so a
// partial apply would drop entries or fields; the full spec never does. The
// first apply takes over the entries earlier pages wrote by merge patch
// (Go-http-client, Update). The apply carries the resourceVersion it read,
// so a concurrent writer is a 409 and a fresh read, never a lost entry or
// stamp. All of it runs in the page's infra write queue.
//
// A contract with no ownerReferences at all (rc127 leftovers, `run request`
// from the terminal) has no composer to ask, so the page releases it as
// rc127 did (linux-kcp, rc128): a server-side apply of exactly
// {spec.release, spec.releaseRequestedAt} under
// socialweb.computer/requester-release, force, the manager socialweb's own
// release intent used for these two fields. A contract owned by anything
// else is refused.
export const RELEASE_FIELD_MANAGER = "socialweb.computer/requester-release";

/** The field manager of every page write of its EphemeralInfra. */
export const INFRA_FIELD_MANAGER = "socialweb.computer/page";

/** The EphemeralInfra spec fields the page composes (sessionInfraManifest, addContract, the secrets). */
export const INFRA_PAGE_FIELDS = ["description", "ttlSeconds", "endWhen", "record", "contracts", "secrets"];

/** The page's part of an EphemeralInfra spec: INFRA_PAGE_FIELDS that are set, deep-copied. */
export function pageInfraSpec(spec) {
  const out = {};
  for (const field of INFRA_PAGE_FIELDS) {
    if (spec?.[field] !== undefined && spec[field] !== null) out[field] = structuredClone(spec[field]);
  }
  return out;
}

/** The server-side apply of the page's full EphemeralInfra spec (resourceVersion: the one read, "" on create). */
export function infraApply(api, name, spec, resourceVersion = "") {
  const metadata = { name };
  if (resourceVersion) metadata.resourceVersion = resourceVersion;
  return {
    path: `${api}/ephemeralinfras/${name}?fieldManager=${encodeURIComponent(INFRA_FIELD_MANAGER)}&force=true`,
    contentType: "application/apply-patch+yaml",
    body: { apiVersion: "socialweb.computer/v1alpha1", kind: "EphemeralInfra", metadata, spec },
  };
}

/** spec.releaseRequestedAt for a Release now: strictly after previous, so a second Release always differs. */
export function releaseRequestedAt(previous = "", now = new Date()) {
  const before = Date.parse(previous ?? "");
  const at = Number.isNaN(before) ? now.getTime() : Math.max(now.getTime(), before + 1);
  return new Date(at).toISOString();
}

/** The server-side apply that releases ownerless ComputeContract name. */
export function releaseApply(api, name, requestedAt) {
  return {
    path: `${api}/computecontracts/${name}?fieldManager=${encodeURIComponent(RELEASE_FIELD_MANAGER)}&force=true`,
    contentType: "application/apply-patch+yaml",
    body: {
      apiVersion: "socialweb.computer/v1alpha1",
      kind: "ComputeContract",
      metadata: { name },
      spec: { release: true, releaseRequestedAt: requestedAt },
    },
  };
}

/** The later of RFC 3339 stamps ("" when none parses). */
export function latestStamp(...stamps) {
  let best = "";
  for (const stamp of stamps) {
    if (!Number.isNaN(Date.parse(stamp ?? "")) && (!best || Date.parse(stamp) > Date.parse(best))) best = stamp;
  }
  return best;
}

/** a is a stamp later than b (any parsable a is later than a missing or unparsable b). */
export function stampAfter(a, b) {
  const x = Date.parse(a ?? "");
  if (Number.isNaN(x)) return false;
  const y = Date.parse(b ?? "");
  return Number.isNaN(y) || x > y;
}

/** The infra entry for a Release: Released with releaseRequestedAt strictly after any stored request. */
export function releasedEntry(entry, ccRequestedAt = "", now = new Date()) {
  return { ...entry, state: "Released", releaseRequestedAt: releaseRequestedAt(latestStamp(entry?.releaseRequestedAt, ccRequestedAt), now) };
}

/**
 * markFinishedInfraContracts' update: a Requested entry becomes Released
 * like a Release does (releasedEntry: a fresh releaseRequestedAt strictly
 * after the entry's and the contract's, ccRequestedAt), so the infra
 * controller re-asks a Failed contract whose guest may still run; every
 * other field stays. null for anything else, so an entry a Release already
 * wrote is not written again.
 */
export function finishedEntry(entry, ccRequestedAt = "", now = new Date()) {
  return entry?.state === "Requested" ? releasedEntry(entry, ccRequestedAt, now) : null;
}

const INFRA_WRITE_ATTEMPTS = 3;

/**
 * Creates EphemeralInfra name with spec only if it is absent: a POST under
 * INFRA_FIELD_MANAGER. A 409 means it exists: it is read and the page's
 * full spec (what is there, spec's fields filling the gaps) applied with
 * the resourceVersion read, so a create never applies contracts: [] over
 * existing entries. Returns the object.
 */
export async function createInfra({ rest, api, name, spec }) {
  const manifest = { apiVersion: "socialweb.computer/v1alpha1", kind: "EphemeralInfra", metadata: { name }, spec };
  try {
    return await rest("POST", `${api}/ephemeralinfras?fieldManager=${encodeURIComponent(INFRA_FIELD_MANAGER)}`, manifest);
  } catch (err) {
    if (Number(err?.status ?? 0) !== 409) throw err;
  }
  return composeInfra({ rest, api, infra: name, update: (current) => ({ ...structuredClone(spec), ...current }) });
}

/**
 * Update-operation managedFields entries that co-own the page's spec fields:
 * the merge patches of earlier pages (Go-http-client) and the create POST
 * (INFRA_FIELD_MANAGER, operation Update). While one of them co-owns an
 * entry, the page's apply cannot remove it: a pruned secret or entry would
 * stay. Seen live on a migrated infra: Go-http-client owned every
 * spec.secrets key (a list map since before rev 12) and kept a pruned one.
 */
export function staleSpecOwners(obj) {
  return (obj?.metadata?.managedFields ?? []).filter((m) => m?.operation === "Update" &&
    (m.manager === "Go-http-client" || m.manager === INFRA_FIELD_MANAGER) &&
    INFRA_PAGE_FIELDS.some((field) => m.fieldsV1?.["f:spec"]?.[`f:${field}`] !== undefined));
}

/** The JSON patch that drops stale managedFields entries from obj, guarded by its resourceVersion. */
export function dropOwnersPatch(obj, stale) {
  const kept = (obj?.metadata?.managedFields ?? []).filter((m) => !stale.includes(m));
  return [
    { op: "test", path: "/metadata/resourceVersion", value: obj?.metadata?.resourceVersion },
    { op: "replace", path: "/metadata/managedFields", value: kept },
  ];
}

/**
 * One composer write of EphemeralInfra infra: reads it, update(spec, live)
 * returns the page's full desired spec from the fresh page spec (null: no
 * write), and that is applied whole (infraApply) with the resourceVersion
 * read (409: read again, 3 attempts). Returns the object kcp answers, or
 * null without a write.
 *
 * An infra other writers still co-own (staleSpecOwners) is first taken
 * over: the page's spec as read is applied unchanged, so the page owns all
 * of it, and the stale entries are dropped from managedFields; only then
 * the update is applied, so whatever it prunes really goes.
 */
export async function composeInfra({ rest, api, infra, update }) {
  const path = `${api}/ephemeralinfras/${infra}`;
  let tookOver = false;
  for (let attempt = 1; ; attempt++) {
    const live = await rest("GET", path);
    try {
      if (!tookOver && staleSpecOwners(live).length > 0) {
        tookOver = true;
        const take = infraApply(api, infra, pageInfraSpec(live?.spec), live?.metadata?.resourceVersion ?? "");
        const owned = await rest("PATCH", take.path, take.body, take.contentType);
        try {
          await rest("PATCH", `${path}?fieldManager=${encodeURIComponent(INFRA_FIELD_MANAGER)}`,
            dropOwnersPatch(owned, staleSpecOwners(owned)), "application/json-patch+json");
        } catch (err) {
          // 409/422 (the test op): someone wrote meanwhile; read again and take over again
          if (![409, 422].includes(Number(err?.status ?? 0))) throw err;
          tookOver = false;
          if (attempt >= INFRA_WRITE_ATTEMPTS) throw err;
          continue;
        }
        attempt--;
        continue;
      }
      const next = update(pageInfraSpec(live?.spec), live);
      if (!next) return null;
      const apply = infraApply(api, infra, next, live?.metadata?.resourceVersion ?? "");
      return await rest("PATCH", apply.path, apply.body, apply.contentType);
    } catch (err) {
      if (Number(err?.status ?? 0) !== 409 || attempt >= INFRA_WRITE_ATTEMPTS) throw err;
      tookOver = false;
    }
  }
}

/**
 * One spec.contracts entry of EphemeralInfra infra through composeInfra:
 * update(current) returns the new entry (null: no write); every other entry
 * and spec field is applied as read. Returns the entry written, or null.
 */
export async function updateInfraEntry({ rest, api, infra, match, update, what = "the contract" }) {
  let written = null;
  await composeInfra({
    rest,
    api,
    infra,
    update: (spec) => {
      const contracts = spec.contracts ?? [];
      const current = contracts.find(match);
      if (!current) throw new Error(`EphemeralInfra ${infra} has no entry for ${what}`);
      written = update(current);
      if (!written) return null;
      return { ...spec, contracts: contracts.map((entry) => entry === current ? written : entry) };
    },
  });
  return written;
}

/**
 * Request VM's update: contract entry added (or replaced) with addContract,
 * and its secrets entry (secret, or null) set; the secrets of entries
 * addContract pruned go too.
 */
export function withInfraContract(spec, entry, secret = null) {
  const { contracts, dropped } = addContract(spec?.contracts ?? [], entry);
  const next = { ...spec, contracts };
  if (secret) {
    next.secrets = [
      ...(spec?.secrets ?? []).filter((x) => !dropped.includes(x.contract) && x.contract !== secret.contract),
      secret,
    ];
  } else if (dropped.length > 0) {
    next.secrets = (spec?.secrets ?? []).filter((x) => !dropped.includes(x.contract));
  }
  return next;
}

/**
 * Releases ComputeContract name. Owned by an EphemeralInfra: through its
 * entry (state Released with a fresh releaseRequestedAt, strictly after the
 * entry's and the contract's), no write to the contract. No owner at all:
 * the rc127 apply of spec.release + a fresh releaseRequestedAt on the
 * contract (releaseApply), no infra write. Any other owner: refused.
 * rest(method, path, body, contentType) is kcpREST; serialize(run) runs run
 * in the page's infra write queue. Returns the releaseRequestedAt sent.
 */
export async function requestRelease({ rest, api, name, serialize = (run) => run(), now = new Date() }) {
  const cc = await rest("GET", `${api}/computecontracts/${name}`);
  if (!cc) throw new Error(`ComputeContract ${name} not found`);
  const owners = cc.metadata?.ownerReferences ?? [];
  if (owners.length === 0) {
    const requestedAt = releaseRequestedAt(cc.spec?.releaseRequestedAt, now);
    const apply = releaseApply(api, name, requestedAt);
    await rest("PATCH", apply.path, apply.body, apply.contentType);
    return requestedAt;
  }
  const owner = owners.find((o) => o.kind === "EphemeralInfra");
  if (!owner?.name) {
    const kinds = owners.map((o) => `${o.kind ?? "?"}/${o.name ?? "?"}`).join(", ");
    throw new Error(`ComputeContract ${name} is owned by ${kinds}, not an EphemeralInfra; its composer releases it, not the page`);
  }
  const short = cc.metadata?.labels?.["infra.socialweb.computer/contract"];
  const entry = await serialize(() => updateInfraEntry({
    rest,
    api,
    infra: owner.name,
    match: (c) => Boolean(c?.name) && (c.name === short || infraContractName(owner.name, c.name) === name),
    update: (current) => releasedEntry(current, cc.spec?.releaseRequestedAt, now),
    what: name,
  }));
  return entry.releaseRequestedAt;
}

/**
 * The contract as this tab sees it: a Release this tab sent (sentAt) that the
 * contract does not show yet (the infra controller copies the stamp a moment
 * later) counts as spec.release with that releaseRequestedAt, so the row says
 * release requested instead of the earlier outcome.
 */
export function withReleaseSent(contract, sentAt = "") {
  if (!contract || contract.phase === "Released" || !stampAfter(sentAt, contract.releaseRequestedAt)) return contract;
  return { ...contract, release: true, releaseRequestedAt: sentAt };
}

/** status.release answers the current Release (a contract without releaseRequestedAt predates rc127: always). */
export function releaseAnswered(contract) {
  const requested = contract?.releaseRequestedAt ?? "";
  return !requested || (contract?.releaseAnsweredAt ?? "") === requested;
}

/**
 * The requester's guestMayRun from the feed: an ok receipt, no termination,
 * no release the bidder acknowledged (receiptOk, terminated, releaseOk).
 */
export function guestMayRun(contract) {
  return Boolean(contract?.receiptOk) && !contract?.terminated && !contract?.releaseOk;
}

/**
 * A Failed contract with a newer, unanswered Release that the requester
 * restarts (r128 388ccee6, releaseRequestedAgain): its ReleaseFailed is
 * True, or its guest may still run. Pending, not Failed.
 */
export function releasePending(contract) {
  return Boolean(contract?.release) && contract?.phase === "Failed" &&
    (Boolean(contract?.releaseFailed) || guestMayRun(contract)) && !releaseAnswered(contract);
}

/**
 * The Release again button: a failed release whose outcome answers the
 * latest request, and nothing newer sent from this tab (sentAt).
 */
export function canReleaseAgain(contract, sentAt = "") {
  return Boolean(contract?.release) && contract?.phase === "Failed" && Boolean(contract?.releaseFailed) &&
    releaseAnswered(contract) && !stampAfter(sentAt, contract?.releaseRequestedAt);
}

/**
 * The requester gave up at its release bound (r128 e2a117e8: ReleaseFailed
 * True, reason ReleaseBound) and that answers the latest request.
 */
export function releaseTimedOut(contract) {
  return Boolean(contract?.release) && contract?.phase === "Failed" && Boolean(contract?.releaseFailed) &&
    contract?.releaseFailedReason === "ReleaseBound" && releaseAnswered(contract);
}

/**
 * The Release button: an active contract, or a Failed one the requester
 * re-releases for a newer stamp (r128 388ccee6): phase Failed, a valid
 * receipt (receiptOk), not terminated and not released/acked (releaseOk),
 * with no request pending (the Release sends the newer stamp) and no
 * Release again offered instead. ReleaseFailed is not needed.
 */
export function releaseOffered(contract) {
  if (isActive(contract)) return true;
  return contract?.phase === "Failed" && guestMayRun(contract) && releaseAnswered(contract) && !canReleaseAgain(contract);
}

/** The row's phase: a pending re-release shows as Releasing, not the earlier Failed. */
export function phaseLabel(contract) {
  const phase = contract?.phase ?? "Pending";
  if (releasePending(contract)) return { phase: "Releasing", text: ` Releasing · release requested ${contract.releaseRequestedAt}` };
  if (releaseTimedOut(contract)) return { phase, text: ` ${phase} · release timed out` };
  return { phase, text: ` ${phase}${contract?.release && phase !== "Released" && phase !== "Failed" ? " · releasing" : ""}` };
}

/** Feed order with Released contracts below everything else. */
export function orderContracts(contracts) {
  return [...contracts].sort((a, b) => (a?.phase === "Released") - (b?.phase === "Released"));
}

export function secretsPath(name) {
  return `contracts/${name}/secrets`;
}

/**
 * The secrets bundle field: JSON text of [{path, value, mode?}]. The agent
 * entry is an empty ATIRC_TOKEN the requester fills in after the RFP; it also
 * keeps an agent-only bundle non-empty (both consumers reject an empty one).
 */
export function secretsBundle({ woottyToken, agent = false }) {
  return JSON.stringify([
    ...(woottyToken ? [{ path: WOOTTY_ENV, value: `WOOTTY_AUTH_TOKEN=${woottyToken}\n` }] : []),
    ...(agent ? [{ path: ATIRC_ENV, value: "ATIRC_TOKEN=\n", mode: "0600" }] : []),
  ]);
}

/**
 * The page tab's EphemeralInfra: every VM this tab requests is a contract in
 * it, so the requester only tracks this tab's contracts and deleting (or the
 * deadline of) the infra releases and collects all of them. Deadline, not
 * Complete: a tab outlives its first released VM. record binds the object to
 * the tab's atproto record; without it the infra is local to browser kcp.
 */
export function sessionInfraManifest(name, ttlSeconds = ORIGIN_INFRA_TTL_SECONDS, record = null) {
  const spec = { description: "socialweb.computer page session", ttlSeconds, endWhen: "Deadline", contracts: [] };
  if (record) spec.record = record;
  return {
    apiVersion: "socialweb.computer/v1alpha1",
    kind: "EphemeralInfra",
    metadata: { name },
    spec,
  };
}

/**
 * The Associate DID input: "" (no association) or a did:plc:/did:web: DID
 * other than the signed-in identity's own (the requester refuses those too).
 */
export function associationSubject(text, selfDid = "") {
  const subject = String(text ?? "").trim();
  if (!subject) return { subject: "" };
  if (!/^did:(plc|web):[A-Za-z0-9._:%-]+$/.test(subject)) return { error: "Associate DID: enter a did:plc: or did:web: DID" };
  if (subject === selfDid) return { error: "Associate DID: that is your own DID" };
  return { subject };
}

/** The ComputeContract the infra controller creates for contract short in infra. */
export function infraContractName(infra, short) {
  return `einfra-${infra}-${short}`;
}

const INFRA_WRITE_PATH = /^(?:\/clusters\/[^/]+)?\/apis\/socialweb\.computer\/v1alpha1\/(?:namespaces\/[^/]+\/)?ephemeralinfras(?:\/([^/?]+))?(?:\?.*)?$/;

/**
 * What a kubectl write of an EphemeralInfra (in this tab's kcp) still needs
 * so its contracts work like Request VM ones, or null when the request is not
 * a JSON create/replace/patch of one. For every Requested contract: keys
 * lists the index and ComputeContract name to give an ssh key held in this
 * browser (hasKey(cc) false) and, with no ssh tunnel declared, gets the ssh
 * over WebRTC one Request VM declares; a non-vm computeKind (a sandbox) gets
 * none of it. For every Requested agent contract: a secrets
 * entry (added to body.spec.secrets, merged with current.spec.secrets on a
 * PATCH, which replaces the list) and the bundle to write when absent. body
 * is a mutated copy; the caller adds each key's authorized line to
 * body.spec.contracts[index].sshAuthorizedKeys.
 */
export function infraWritePlan({ method, path, body }, { current = null, hasKey = () => false } = {}) {
  if (!["POST", "PUT", "PATCH"].includes(String(method).toUpperCase())) return null;
  const match = INFRA_WRITE_PATH.exec(String(path ?? ""));
  if (!match) return null;
  let doc;
  try {
    doc = JSON.parse(body);
  } catch {
    return null;
  }
  const name = doc?.metadata?.name ?? match[1] ?? current?.metadata?.name ?? "";
  const contracts = doc?.spec?.contracts;
  if (!name || !Array.isArray(contracts)) return null;
  const keys = [];
  const bundles = [];
  let secrets = Array.isArray(doc.spec.secrets) ? doc.spec.secrets
    : String(method).toUpperCase() === "PATCH" && Array.isArray(current?.spec?.secrets) ? current.spec.secrets : [];
  let secretsChanged = false;
  let tunnelsAdded = false;
  contracts.forEach((contract, index) => {
    if (!contract?.name || (contract.state ?? "Requested") !== "Requested") return;
    // A sandbox (computeKind deno, ...) has no guest to ssh into or run an agent.
    if ((contract.computeKind ?? "vm") !== "vm") return;
    const cc = infraContractName(name, contract.name);
    if (!hasKey(cc)) keys.push({ index, cc });
    // The guest starts its ssh-over-WebRTC side only for a declared ssh
    // tunnel; one the user declared (another transport) is left as it is.
    const tunnels = Array.isArray(contract.tunnels) ? contract.tunnels : [];
    if (!tunnels.some((t) => t?.tag === "ssh")) {
      contract.tunnels = [...tunnels, { tag: "ssh", port: 22, transport: "webrtc" }];
      tunnelsAdded = true;
    }
    if (!contract.agent) return;
    let entry = secrets.find((s) => s?.contract === contract.name);
    if (!entry) {
      entry = { contract: contract.name, secretsRef: { mount: SECRETS_MOUNT, path: secretsPath(cc) } };
      secrets = [...secrets, entry];
      secretsChanged = true;
    }
    const ref = entry.secretsRef ?? {};
    if ((ref.mount ?? SECRETS_MOUNT) === SECRETS_MOUNT && ref.path) bundles.push({ cc, mount: SECRETS_MOUNT, path: ref.path });
  });
  if (keys.length === 0 && bundles.length === 0 && !secretsChanged && !tunnelsAdded) return null;
  if (secretsChanged) doc.spec.secrets = secrets;
  return { name, body: doc, keys, bundles };
}

/**
 * One EphemeralInfra contract entry (and its secrets entry, with wootty or
 * the agent) for the VM short; cc is the ComputeContract name it becomes.
 * The template is the one contractManifest builds.
 */
export function infraContract({ infra, short, wootty = false, agent = false, sshKeys = [], association = "", guestTools = false }) {
  const cc = infraContractName(infra, short);
  const { spec } = contractManifest({ name: cc, wootty, agent, sshKeys, association, guestTools });
  const { secretsRef, ...template } = spec;
  return {
    cc,
    contract: { name: short, state: "Requested", ...template },
    secret: secretsRef ? { contract: short, secretsRef } : null,
  };
}

/**
 * A ComputeContract for the page: the webrtc ssh tunnel (sshKeys must hold
 * the page's key), with wootty the opentunnel wootty tunnel, with agent the
 * atirc agent, and with either the secretsRef of their bundle. association
 * (a DID, plan 0036 P1) has the requester write a contract-scoped
 * market.association for it; its ref file reaches the guest through the
 * secrets bundle, so it needs the secretsRef too.
 */
export function contractManifest({ name, ownerDid, wootty = false, agent = false, sshKeys = [], association = "", guestTools = false }) {
  // No bidderDids: the requester's discovery picks the bidders.
  const spec = { vmName: name, policy: REQUESTER_POLICY };
  spec.tunnels = [{ tag: SSH_TAG, port: 22, transport: "webrtc" }];
  if (association && guestTools) throw new Error(R2_ASSOCIATES_ITSELF);
  if (wootty || agent || association || guestTools) spec.secretsRef = { mount: SECRETS_MOUNT, path: secretsPath(name) };
  if (association) spec.association = { subject: association };
  // R2: socialweb-computer in the guest (linux/amd64 bidders only; others
  // fail their bid with GuestToolsUnserved). It associates itself: with
  // fromGuest the requester writes association-request.json into the bundle.
  if (guestTools) {
    spec.guestTools = [GUEST_TOOL];
    spec.association = { fromGuest: true };
  }
  if (agent) spec.agent = { envFile: ATIRC_ENV };
  if (wootty) {
    spec.tunnels.unshift({ tag: WOOTTY_TAG, port: WOOTTY_PORT, transport: "opentunnel", shell: { envFile: WOOTTY_ENV } });
  }
  if (sshKeys.length > 0) spec.sshAuthorizedKeys = sshKeys;
  if (ownerDid) spec.ownerDid = ownerDid;
  return {
    apiVersion: "socialweb.computer/v1alpha1",
    kind: "ComputeContract",
    metadata: { name },
    spec,
  };
}

/** True when an APIResourceSchema's ComputeContract tunnels have the wootty shell field. */
export function schemaHasShell(schema) {
  return (schema?.spec?.versions ?? []).some((v) =>
    v.schema?.properties?.spec?.properties?.tunnels?.items?.properties?.shell !== undefined);
}

/** True when an APIResourceSchema's ComputeContract has spec.agent (plan 0035). */
export function schemaHasAgent(schema) {
  return (schema?.spec?.versions ?? []).some((v) => v.schema?.properties?.spec?.properties?.agent !== undefined);
}

/**
 * Release notes for the contract row (plan 0036 A8). The cascade runs in the
 * requester: it publishes guest.r2Release (outbound ContractEvent
 * <contract>-r2-release), waits up to R2_RELEASE_MINUTES with
 * status.execution.step releasingGuestRequester for the guest's r2Released
 * (only the time left since requestedAt after a restart), then deletes the
 * VM. atircRevokes runs before Released.
 */
// socialweb cloudinit.GuestRequesterReleaseTimeout (201937b0): stop 2 min +
// release unit (3 + 15 + 2 + 1 min) + 1 min.
export const R2_RELEASE_MINUTES = 24;

export function releaseNotes(contract, contractEvents = [], now = Date.now()) {
  const notes = [];
  // status.contract.r2Release (rc127, socialweb 34f74335): phase
  // Requested|Released|Failed|TimedOut; ok is omitted when false, so the
  // phase decides.
  const r2 = contract?.r2Release;
  if (r2) {
    const why = r2.message || "no message";
    notes.push({
      Requested: `R2 release: asked ${r2.requestedAt ?? "?"}, waiting (up to ${R2_RELEASE_MINUTES} min${minutesLeft(r2.requestedAt, now)})`,
      Released: `R2 release: guest released ${r2.answeredAt ?? "?"}`,
      Failed: `R2 release: FAILED: ${why}`,
      TimedOut: `R2 release: TIMED OUT after ${R2_RELEASE_MINUTES} min; bidder backstop releases R2's VMs after the association expires`,
    }[r2.phase] ?? `R2 release: [${r2.phase ?? "unknown"}] ${why}`);
  }
  const asked = contractEvents.find((e) => e?.contract === contract?.name && e.direction === "outbound" &&
    e.nsid === "com.publicdomainrelay.temp.compute.events.guest.r2Release");
  if (r2) {
    // the answer above replaces the wait/request lines
  } else if (contract?.step === "releasingGuestRequester") {
    notes.push(`R2 release: waiting for the guest requester to release its contracts (up to ${R2_RELEASE_MINUTES} min)${asked ? `, request ${asked.phase ?? "Pending"}` : ""}`);
  } else if (asked) {
    notes.push(`R2 release: asked (${asked.phase ?? "Pending"}); answered or ${R2_RELEASE_MINUTES} min bound passed`);
  }
  const revokes = { Pending: "tokens: revoking", Done: "tokens: revoked", Abandoned: "tokens: revoke ABANDONED, revoke them by hand" };
  // A contract that failed before any mint (no bids, no VM) still finishes
  // its revoke step; "revoked" would claim a token that never existed.
  if (contract?.atircRevokes === "Done" && !contract?.atircToken) notes.push("tokens: none minted");
  else if (contract?.atircRevokes) notes.push(revokes[contract.atircRevokes] ?? `tokens: ${contract.atircRevokes}`);
  if (!releasePending(contract)) return notes;
  // The outcomes above answer an earlier Release; the requester restarts it.
  return [`release: requested ${contract.releaseRequestedAt}, pending (the earlier release failed${contract.message ? `: ${contract.message}` : ""})`,
    ...notes.map((note) => `${note} (earlier attempt)`)];
}

/**
 * The row note for the requester's atirc token mint (socialweb r130: the
 * agent/R2 token is minted, with a lease, only after the verified receipt;
 * condition AtircTokenMinted, fed as contract.atircToken {status, reason,
 * message}). "" for a contract without the agent or R2.
 */
export function agentTokenNote(contract) {
  // socialweb mints and records the condition for spec.agent; an R2-only
  // contract (guest tools, agent off) never gets one (review page-rc131 2).
  const token = contract?.atircToken;
  if (!contract?.agent && !token) return "";
  const finished = FINISHED.has(contract.phase ?? "");
  if (!token) return finished ? "" : "agent token: waiting for receipt";
  if (token.status === "True") {
    return {
      Leased: "agent token: leased",
      Unleased: "agent token: minted without a lease (the atirc server has no leases)",
      Present: "agent token: in the bundle",
    }[token.reason] ?? `agent token: minted (${token.reason || "no reason"})`;
  }
  const why = token.message || "no message";
  // r131 3dca8612: a leased mint whose token has no leases claim fails, for good.
  if (token.reason === "LeaseClaimMissing") return "agent token: server returned no lease (refused)";
  if (token.reason === "GaveUp") return `agent token: mint GAVE UP: ${why}`;
  // A finished contract's retry loop exits without a last condition.
  if (finished) return `agent token: mint failed: ${why}`;
  // r131 mints only after the verified receipt; before it the requester
  // records MintFailed "…no verified receipt…" and tries again later.
  if (/no verified receipt/.test(why)) return "agent token: waiting for receipt";
  // A receipt outside a DID repo cannot carry a lease: never retried, so no
  // "attempt 1 of 12" either.
  if (/is not in a DID repo/.test(why)) return `agent token: mint failed (not retried): ${why.replace(/^attempt \d+ of \d+: /, "")}`;
  // "attempt N of M": retried while N < M; anything else is not retried.
  const attempt = /attempt (\d+) of (\d+)/.exec(why);
  if (attempt && Number(attempt[1]) < Number(attempt[2])) return `agent token: mint failed, retrying: ${why}`;
  return `agent token: mint failed: ${why}`;
}

// ", ~N min left" for the requester's remaining wait, "" without a time.
function minutesLeft(requestedAt, now) {
  const at = Date.parse(requestedAt ?? "");
  if (Number.isNaN(at)) return "";
  return `, ~${Math.max(0, Math.ceil((at + R2_RELEASE_MINUTES * 60_000 - now) / 60_000))} min left`;
}

/** The Start R2 button: a Held contract that runs R2 and lets it associate itself. */
export function r2StartShown(contract) {
  return contract?.phase === "Held" && (contract.guestTools ?? []).includes(GUEST_TOOL) && contract.fromGuest === true &&
    !contract.release;
}

/** True when an APIResourceSchema's ComputeContract has spec.guestTools (R2). */
export function schemaHasGuestTools(schema) {
  return (schema?.spec?.versions ?? []).some((v) => v.schema?.properties?.spec?.properties?.guestTools !== undefined);
}

/**
 * The wootty link for a status-feed contract: the "wootty" tagged https
 * address from status.contract.networks with the token in the fragment (it
 * never reaches the tunnel or a server log), or "" while it is not reported.
 */
export function shellLink(contract, token) {
  const network = (contract?.networks ?? []).find((n) => n?.tag === WOOTTY_TAG);
  if (!network?.address || !token) return "";
  let url;
  try {
    url = new URL(network.address);
  } catch {
    return "";
  }
  if (url.protocol !== "https:") return "";
  url.hash = `token=${encodeURIComponent(token)}`;
  return url.toString();
}

// --- other tabs' EphemeralInfras (linux-kcp, rc129) ---------------------------
//
// Every tab of an origin shares one kcp state, so infras of tabs that are gone
// stay in it until their ttl. On boot the page collects those of its own
// origin: an infra none of whose entries points at a live ComputeContract is
// deleted once it is history older than INFRA_HISTORY_MS (a new browser
// session is a new tab id, and deleting the infra cascades to its Released
// contracts, whose rows carry the "tokens: revoked" proof); one with a live
// contract keeps running and gets its record binding repaired as sessionInfra
// repairs the tab's own. An infra already ending (deletionTimestamp or
// status.endedAt: the infra controller expires it) is left to the controller.

/** How long another tab's finished infra stays as history rows (linux-kcp, rc130). */
export const INFRA_HISTORY_MS = 24 * 3600 * 1000;

/** The newest of the RFC 3339 times given, in ms (0 when none parses). */
export function newestTime(...times) {
  let newest = 0;
  for (const t of times) {
    const ms = typeof t === "string" && t ? Date.parse(t) : NaN;
    if (Number.isFinite(ms) && ms > newest) newest = ms;
  }
  return newest;
}

/**
 * When a ComputeContract last changed toward its end: the newest condition
 * transition, release request or answer, or guest termination. A terminal
 * contract has no separate end stamp; these are set on the way there.
 */
export function contractFinishedAt(obj) {
  const status = obj?.status ?? {};
  return newestTime(
    ...(status.conditions ?? []).map((c) => c?.lastTransitionTime),
    obj?.spec?.releaseRequestedAt,
    status.release?.requestedAt,
    status.contract?.termination?.observedAt,
  );
}

/** The feed's view (statusfeed contract()) of a ComputeContract object, for the liveness rule. */
export function feedContract(obj) {
  const status = obj?.status ?? {};
  const spec = obj?.spec ?? {};
  const failed = (status.conditions ?? []).find((c) => c?.type === "ReleaseFailed" && c?.status === "True");
  const guest = status.contract ?? {};
  return {
    name: obj?.metadata?.name ?? "",
    phase: status.phase ?? "",
    release: spec.release === true,
    releaseRequestedAt: spec.releaseRequestedAt ?? "",
    releaseAnsweredAt: status.release?.requestedAt ?? "",
    releaseFailed: Boolean(failed),
    releaseFailedReason: failed?.reason ?? "",
    atircRevokes: status.atircRevokes ?? "",
    step: status.execution?.step ?? "",
    receiptOk: guest.receipt !== undefined && guest.receiptOk === true,
    terminated: guest.termination !== undefined,
    releaseOk: guest.release?.ok === true,
    finishedAt: contractFinishedAt(obj),
  };
}

/**
 * A ComputeContract that may still hold a VM or release work: not Released
 * or Failed; Failed with the guest possibly running (the Release offer's
 * guestMayRun) or a failed release; or release work still pending
 * (releaseWorkPending: a re-release, atirc revokes, the guest requester).
 */
export function contractLive(contract) {
  if (!contract) return false;
  if (!FINISHED.has(contract.phase || "Pending")) return true;
  if (contract.phase === "Failed" && (guestMayRun(contract) || contract.releaseFailed)) return true;
  return releaseWorkPending(contract);
}

/** The DID of the infra's PDS record (status.record.uri, else spec.record.uri), or "". */
export function infraRecordDid(infra) {
  const uri = infra?.status?.record?.uri || infra?.spec?.record?.uri || "";
  return /^at:\/\/(did:[^/]+)\//.exec(uri)?.[1] ?? "";
}

/**
 * Whether the infra controller can reach the infra's PDS record, so deleting
 * the infra ends it there (socialweb rc140 writes a final endedAt status and
 * keeps the record; older controllers deleted it): no RecordUnresolved=True (nor the older
 * "repo.read handle" sync error) and spec.record.repoRef names did's current
 * repo. An infra without a record binding has no record to orphan.
 */
export function infraRecordResolvable(infra, did) {
  const binding = infra?.spec?.record;
  if (!binding) return true;
  // r131: RecordOrphaned=True means the controller released the record
  // without a delete (its repo is gone, or it gave up); nothing is left to
  // orphan, so the infra counts as finished and may go.
  if (infraCondition(infra, "RecordOrphaned")?.status === "True") return true;
  if (infraCondition(infra, "RecordUnresolved")?.status === "True") return false;
  if ((infra?.status?.conditions ?? []).some((c) => /repo\.read handle/.test(c?.message ?? ""))) return false;
  return binding.repoRef?.name === infraRepoRef(did).name;
}

/**
 * After a rebind written at generation: the controller has reconciled it
 * (status.observedGeneration) and the record now resolves (no
 * RecordUnresolved=True, the current repo, a record URI), so a delete also
 * reaches the PDS record (its final ended status).
 */
export function infraRebindSettled(infra, did, generation) {
  return Number(infra?.status?.observedGeneration ?? 0) >= Number(generation ?? 0) &&
    infraRecordResolvable(infra, did) && Boolean(infra?.status?.record?.uri);
}

/**
 * The GC's rebind-delete: rebinds infra name's spec.record to did's binding
 * (composeInfra, the page's full-spec apply; serialize is the page's infra
 * write queue), waits up to timeoutMs for infraRebindSettled, and only then
 * deletes the infra so the controller writes the record's final ended
 * status (rc140; older controllers deleted the record). Returns true
 * when deleted, false when it was kept (record still unresolved).
 */
export async function rebindThenDelete({
  rest, api, name, did, serialize = (run) => run(), timeoutMs = 30_000, pollMs = 750,
  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = Date.now,
}) {
  const record = infraRecordBinding(did);
  const written = await serialize(() => composeInfra({ rest, api, infra: name, update: (spec) => ({ ...spec, record }) }));
  const generation = written?.metadata?.generation ?? 0;
  const path = `${api}/ephemeralinfras/${name}`;
  const deadline = now() + timeoutMs;
  while (now() < deadline) {
    await sleep(pollMs);
    if (infraRebindSettled(await rest("GET", path), did, generation)) {
      await rest("DELETE", path).catch((err) => {
        if (Number(err?.status ?? 0) !== 404) throw err;
      });
      return true;
    }
  }
  return false;
}

/**
 * The contracts' phase/step fingerprint for a feed update and whether it
 * moved since previous (null: the first update, which only sets the base).
 * A move is a Go-side status write (Held, a release step) the page flushes
 * at once instead of leaving it in kcp's persist coalescer for up to 10 s.
 */
export function contractTransitions(previous, contracts) {
  const key = (contracts ?? []).map((c) => `${c?.name}:${c?.phase ?? ""}:${c?.step ?? ""}`).sort().join("|");
  return { key, changed: previous !== null && previous !== undefined && previous !== key };
}

/** The tab id in name when it is an infra of origin (originInfraName), else null. */
export function originInfraTab(origin, name) {
  const prefix = originInfraName(origin, "x").slice(0, -1);
  const tab = String(name ?? "").startsWith(prefix) ? String(name).slice(prefix.length) : "";
  return /^[a-z0-9]{1,6}$/.test(tab) ? tab : null;
}

/**
 * What to do with each EphemeralInfra of origin besides tabId's own:
 * {name, action: "delete"|"rebind"|"keep"|"skip", reason, live}. Other
 * origins' infras and the tab's own are not listed. contracts are
 * feedContract views; did is the signed-in identity (rebind target).
 */
export function planInfraGC({ infras, contracts, origin, tabId, did, now = Date.now(), historyMs = INFRA_HISTORY_MS }) {
  const own = originInfraName(origin, tabId);
  const byName = new Map((contracts ?? []).map((c) => [c?.name, c]));
  const plan = [];
  for (const infra of infras ?? []) {
    const name = infra?.metadata?.name ?? "";
    if (!name || name === own || originInfraTab(origin, name) === null) continue;
    if (infra.metadata?.deletionTimestamp || infra.status?.endedAt) {
      plan.push({ name, action: "skip", reason: "already ending", live: [] });
      continue;
    }
    const live = (infra.spec?.contracts ?? [])
      .map((entry) => infraContractName(name, entry?.name))
      .filter((cc) => contractLive(byName.get(cc)));
    if (live.length === 0) {
      // The newest end among its contracts (and entries' release stamps),
      // else the infra's creation: history younger than historyMs stays.
      const entries = infra.spec?.contracts ?? [];
      const ended = newestTime(
        infra.status?.endedAt,
        ...entries.map((entry) => entry?.releaseRequestedAt),
        ...entries.map((entry) => {
          const c = byName.get(infraContractName(name, entry?.name));
          return c?.finishedAt ? new Date(c.finishedAt).toISOString() : "";
        }),
      ) || newestTime(infra.metadata?.creationTimestamp);
      const hours = ended ? ((now - ended) / 3600_000).toFixed(1) : "unknown";
      if (!ended || now - ended <= historyMs) {
        plan.push({ name, action: "keep", reason: `history: finished ${hours} h ago`, live });
      } else if (infraRecordResolvable(infra, did)) {
        plan.push({ name, action: "delete", reason: `no live ComputeContract; finished ${hours} h ago`, live });
      } else {
        // Deleting it now would leave its PDS record without its final ended
        // status (the controller cannot reach the repo). The same DID's:
        // rebind, wait for the record, then
        // delete; anyone else's: keep.
        const owner = infraRecordDid(infra);
        const mine = owner ? owner === did : infra.spec?.record?.repoRef?.name === infraRepoRef(did).name;
        plan.push(mine
          ? { name, action: "rebind-delete", reason: `finished ${hours} h ago; record unresolved, rebinding first`, live }
          : { name, action: "keep", reason: "kept: record unresolved", live });
      }
      continue;
    }
    const binding = infra.spec?.record;
    if (binding?.uri || (binding?.repoRef?.name && binding.repoRef.name !== repoName(did))) {
      plan.push({ name, action: "keep", reason: "live contracts; its record is bound to another repo", live });
    } else if (infraRecordStale(binding)) {
      plan.push({ name, action: "rebind", reason: "live contracts; stale record binding", live });
    } else {
      plan.push({ name, action: "keep", reason: "live contracts", live });
    }
  }
  return plan;
}