@fungi.computer/bonsai 0.0.0-stage → 0.0.1

package/backend/policy.ts

@@ -0,0 +1,160 @@
+/** Pure decisions over host identity, the stored proposal and pinned review facts. */
+import type {
+  RepoSummary,
+  Change,
+  ChangeRecord,
+  PolicyDecision,
+  Approval,
+  Check,
+} from "../shared/contract.js";
+import type { AppMethodCallContext } from "@fungi.computer/puffball/app-method-runtime";
+import type { BonsaiActor } from "./service.js";
+
+export type PolicyFacts = Readonly<{
+  actor: BonsaiActor;
+  change: Pick<
+    ChangeRecord,
+    "state" | "head" | "target" | "openedBy" | "conflict"
+  >;
+  head: string;
+  approvals: readonly Pick<Approval, "actor" | "head" | "kind">[];
+  checks: readonly Pick<Check, "head" | "status">[];
+  headAuthors: readonly string[];
+  isMaintainer: boolean;
+  mayPush: boolean;
+  sourceOwner: string | null;
+  /** Host-attested: the acting person is their Team's only member. */
+  soleMember: boolean;
+}>;
+export type Action =
+  "open" | "approve" | "merge" | "close" | "reportCheck" | "requestChecks";
+
+/** Someone who neither opened the Change nor authored its head. */
+function independent(facts: PolicyFacts, actor: string): boolean {
+  return actor !== facts.change.openedBy && !facts.headAuthors.includes(actor);
+}
+
+/**
+ * Review asks for a second person. A Team with only one member has none, so
+ * the host-attested sole member may approve and merge their own work. Their
+ * approval is recorded as `self` for the review history, and each decision
+ * reads the attestation afresh, so it stops applying once the Team grows.
+ * Agents are never members, so they never self-approve.
+ */
+function soleSelf(facts: PolicyFacts): boolean {
+  return facts.soleMember && facts.actor.kind === "human";
+}
+
+/** How the acting person's approval of this head is recorded. */
+export function approvalKind(facts: PolicyFacts): "human" | "self" {
+  return independent(facts, facts.actor.name) ? "human" : "self";
+}
+
+export function decide(action: Action, facts: PolicyFacts): PolicyDecision {
+  if (action === "open")
+    return facts.mayPush
+      ? { allowed: true }
+      : { allowed: false, reason: "not-source-writer" };
+  if (action === "merge" && facts.actor.kind !== "human")
+    return { allowed: false, reason: "agents-cannot-merge" };
+  if (action === "approve" && facts.actor.kind !== "human")
+    return { allowed: false, reason: "agents-cannot-approve" };
+  if (action === "reportCheck" || action === "requestChecks") {
+    if (facts.head !== facts.change.head)
+      return { allowed: false, reason: "moved" };
+    return facts.change.state === "open" || facts.change.state === "merging"
+      ? { allowed: true }
+      : { allowed: false, reason: "not-open" };
+  }
+  if (facts.change.state === "merging")
+    return { allowed: false, reason: "merging" };
+  if (facts.change.state !== "open")
+    return { allowed: false, reason: "not-open" };
+  if (action === "close")
+    return facts.isMaintainer ||
+      facts.actor.name === facts.change.openedBy ||
+      facts.actor.name === facts.sourceOwner
+      ? { allowed: true }
+      : { allowed: false, reason: "not-authorized" };
+  if (facts.head !== facts.change.head)
+    return { allowed: false, reason: "moved" };
+  if (!facts.isMaintainer) return { allowed: false, reason: "not-maintainer" };
+  if (action === "approve")
+    return independent(facts, facts.actor.name) || soleSelf(facts)
+      ? { allowed: true }
+      : { allowed: false, reason: "self-approval" };
+  const conflict = facts.change.conflict;
+  if (
+    conflict?.head === facts.change.head &&
+    conflict.target === facts.change.target
+  )
+    return { allowed: false, reason: "conflict" };
+  const checks = facts.checks.filter(
+    (check) => check.head === facts.change.head,
+  );
+  if (checks.some((check) => check.status === "failed"))
+    return { allowed: false, reason: "checks-failed" };
+  if (
+    checks.some(
+      (check) => check.status === "queued" || check.status === "running",
+    )
+  )
+    return { allowed: false, reason: "checks-running" };
+  const approvers = new Set(
+    facts.approvals
+      .filter(
+        (approval) =>
+          approval.head === facts.change.head &&
+          approval.kind === "human" &&
+          independent(facts, approval.actor),
+      )
+      .map((approval) => approval.actor),
+  );
+  if (independent(facts, facts.actor.name) || soleSelf(facts))
+    approvers.add(facts.actor.name);
+  return approvers.size > 0
+    ? { allowed: true }
+    : { allowed: false, reason: "needs-approval" };
+}
+
+export type Review = Readonly<{
+  status: Change["status"];
+  decision: PolicyDecision;
+}>;
+export function review(facts: PolicyFacts): Review {
+  const decision = decide("merge", facts);
+  const state = facts.change.state;
+  if (state !== "open") return { status: state, decision };
+  if (decision.allowed) return { status: "ready", decision };
+  switch (decision.reason) {
+    case "conflict":
+    case "checks-failed":
+    case "checks-running":
+      return { status: decision.reason, decision };
+    default:
+      return { status: "needs-approval", decision };
+  }
+}
+
+/** Host-issued IDs own forks; display names are never authorization facts. */
+export function mayPush(actor: BonsaiActor, repo: RepoSummary | null): boolean {
+  return (
+    repo !== null &&
+    (actor.kind === "human" ||
+      (repo.parent !== null && repo.owner === actor.name))
+  );
+}
+
+/** The acting identity, as the host attributed the call. */
+export function callerActor(caller: AppMethodCallContext): BonsaiActor {
+  switch (caller.actor.kind) {
+    case "member":
+      return caller.soleMember === true
+        ? { name: caller.actor.memberId, kind: "human", soleMember: true }
+        : { name: caller.actor.memberId, kind: "human" };
+    case "agent":
+      return { name: caller.actor.agentId, kind: "agent" };
+    case "team-key":
+      return { name: caller.actor.keyId, kind: "agent" };
+  }
+}

package/backend/read-copy-page.ts

@@ -0,0 +1,77 @@
+/** App-owned cursors select a page of a saved copy, without provider work. */
+import * as z from "zod";
+import type { JsonValue } from "../shared/contract.js";
+import { AppMethodRefusal } from "@fungi.computer/agar/backend";
+
+const cursor = z.strictObject({
+  version: z.literal(1),
+  scope: z.string(),
+  snapshot: z.string().nullable(),
+  offset: z.number().int().nonnegative(),
+});
+
+export function readCopyPageOffset(
+  after: string | undefined,
+  scope: string,
+  snapshot: string | null,
+): number {
+  if (after === undefined) return 0;
+  let decoded: z.output<typeof cursor>;
+  try {
+    const bytes = Uint8Array.from(atob(after), (char) => char.charCodeAt(0));
+    decoded = cursor.parse(
+      JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)),
+    );
+  } catch {
+    throw new AppMethodRefusal("invalid", "Invalid saved-copy cursor.");
+  }
+  if (decoded.scope !== scope)
+    throw new AppMethodRefusal("invalid", "Cursor belongs to another view.");
+  if (decoded.snapshot !== snapshot)
+    throw new AppMethodRefusal(
+      "conflict",
+      "The saved page changed; restart from the first page.",
+    );
+  return decoded.offset;
+}
+
+export function sliceReadCopyPage<T>(
+  values: readonly T[],
+  limit: number,
+  offset: number,
+  scope: string,
+  snapshot: string | null,
+) {
+  if (offset > values.length)
+    throw new AppMethodRefusal("invalid", "Cursor is outside the saved page.");
+  const items = values.slice(offset, offset + limit);
+  const nextOffset = offset + items.length;
+  const next =
+    nextOffset < values.length
+      ? btoa(
+          String.fromCharCode(
+            ...new TextEncoder().encode(
+              JSON.stringify(
+                cursor.parse({
+                  version: 1,
+                  scope,
+                  snapshot,
+                  offset: nextOffset,
+                }),
+              ),
+            ),
+          ),
+        )
+      : null;
+  return { items, next };
+}
+
+export async function copyListSnapshot(value: JsonValue): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(JSON.stringify(value)),
+  );
+  return Array.from(new Uint8Array(digest), (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+}

package/backend/repository-copy.ts

@@ -0,0 +1,70 @@
+/** Mutable read copies share one durable repository-ref readiness gate. */
+import { readCopyFrame } from "./git.js";
+import { AppMethodRefusal } from "@fungi.computer/agar/backend";
+import type { Bonsai } from "./service.js";
+import type { RepoDetail } from "../shared/contract.js";
+
+/** Local only: callers may not rebuild a mutable view from pending or missing refs. */
+export function readRepositoryRefs(
+  bonsai: Bonsai,
+  repo: string,
+): Omit<RepoDetail, "repo"> {
+  if (bonsai.state.repo(repo) === null)
+    throw new AppMethodRefusal("not_found", `No repository ${repo}`);
+  const copy = bonsai.state.repositoryCopies.read(repo);
+  if (bonsai.state.repositoryRefStatus(repo).pending || copy.kind !== "ready")
+    throw new AppMethodRefusal(
+      "unavailable",
+      "Repository refs are rebuilding.",
+    );
+  return copy.value;
+}
+
+/** Foreground metadata publication uses the same revision as its provider read. */
+export async function refreshRepositoryCopy(
+  bonsai: Bonsai,
+  name: string,
+  signal: AbortSignal,
+): Promise<RepoDetail> {
+  const summary = bonsai.state.repo(name);
+  if (summary === null)
+    throw new AppMethodRefusal("not_found", `No repository ${name}`);
+  const status = bonsai.state.repositoryRefStatus(name);
+  const saved = bonsai.state.repositoryCopies.read(name);
+  if (!status.pending && saved.kind === "ready")
+    return { repo: summary, ...saved.value };
+  const info = await bonsai.store.info(name);
+  if (info === null)
+    throw new AppMethodRefusal("not_found", "Repository storage is missing");
+  const refs = await bonsai.store.refs(name);
+  const value = {
+    defaultBranch: info.defaultBranch,
+    refs: refs.filter((ref) => ref.name !== "HEAD"),
+    cloneUrl: await bonsai.store.cloneUrl(name),
+    empty: refs.length === 0,
+  };
+  signal.throwIfAborted();
+  if (
+    !bonsai.state.publishRepositoryRefs(
+      name,
+      status.revision,
+      refs.find((ref) => ref.name === `refs/heads/${info.defaultBranch}`)
+        ?.hash ?? null,
+      value,
+    )
+  )
+    throw new AppMethodRefusal(
+      "unavailable",
+      "Repository refs changed during rebuild.",
+    );
+  return { repo: summary, ...value };
+}
+
+export async function getRepoDetail(
+  bonsai: Bonsai,
+  name: string,
+): Promise<RepoDetail> {
+  return readCopyFrame(bonsai.store, (store, signal) =>
+    refreshRepositoryCopy({ ...bonsai, store }, name, signal),
+  );
+}

package/backend/reviews.ts

@@ -0,0 +1,317 @@
+/** Pinned approvals and check attempts, backed by native receipts. */
+import { replayKey } from "@fungi.computer/cairn";
+import {
+  approvalResult,
+  checkRequestResult,
+  checkReportResult,
+  type ChangeRecord,
+  type ApprovalResult,
+  type CheckRequestResult,
+  type CheckReportResult,
+  type Check,
+} from "../shared/contract.js";
+import type { HookEvent } from "../shared/hooks.js";
+import { AppMethodRefusal } from "@fungi.computer/agar/backend";
+import { approvalKind, decide } from "./policy.js";
+import { authorsAtHead } from "./history.js";
+import { recoverExpiredLease } from "./merge.js";
+import type { Bonsai, BonsaiActor } from "./service.js";
+
+export async function approveChange(
+  bonsai: Bonsai,
+  actor: BonsaiActor,
+  input: { repo: string; number: number; head: string },
+  requestKey: string = replayKey(),
+): Promise<ApprovalResult> {
+  const key = `approve:${requestKey}`;
+  const digest = JSON.stringify({ actor, input });
+  const cached = bonsai.state.receipt(key, digest, approvalResult);
+  if (cached !== null) {
+    return cached.result;
+  }
+  const initial = await recoverExpiredLease(
+    bonsai,
+    bonsai.state.requireChange(input.repo, input.number),
+  );
+  const [authors, cloneUrl] = await Promise.all([
+    authorsAtHead(bonsai, initial),
+    bonsai.store.cloneUrl(initial.sourceRepo),
+  ]);
+  const result = bonsai.state.transition(key, digest, approvalResult, () => {
+    const row = bonsai.state.requireChange(input.repo, input.number);
+    if (row.head !== input.head)
+      return {
+        result: approvalResult.parse({ kind: "moved", head: row.head }),
+        events: [],
+      };
+    const facts = bonsai.state.reviewFacts(actor, row, input.head, authors);
+    const decision = decide("approve", facts);
+    if (!decision.allowed)
+      return {
+        result: approvalResult.parse({
+          kind: "refused",
+          reason: decision.reason,
+        }),
+        events: [],
+      };
+    const exists = bonsai.state
+      .approvals(row.repo, row.number)
+      .some(
+        (approval) =>
+          approval.head === row.head && approval.actor === actor.name,
+      );
+    if (exists)
+      return { result: approvalResult.parse({ kind: "approved" }), events: [] };
+    const next = bonsai.state.reviseChange(
+      { ...row, updatedAt: Date.now() },
+      row.revision,
+    );
+    bonsai.state.approve(row.repo, row.number, {
+      actor: actor.name,
+      kind: approvalKind(facts),
+      head: row.head,
+      at: next.updatedAt,
+    });
+    return {
+      result: approvalResult.parse({ kind: "approved" }),
+      events: [
+        bonsai.state.changeEvent(next, actor.name, "change.approved", cloneUrl),
+      ],
+    };
+  });
+  return result;
+}
+
+export async function requestChecks(
+  bonsai: Bonsai,
+  actor: BonsaiActor,
+  input: {
+    repo: string;
+    number: number;
+    head: string;
+    names?: string[] | undefined;
+  },
+  requestKey: string = replayKey(),
+): Promise<CheckRequestResult> {
+  const key = `checks-request:${requestKey}`;
+  const digest = JSON.stringify({ actor, input });
+  const cached = bonsai.state.receipt(key, digest, checkRequestResult);
+  if (cached !== null) {
+    return cached.result;
+  }
+  const initial = await recoverExpiredLease(
+    bonsai,
+    bonsai.state.requireChange(input.repo, input.number),
+  );
+  const cloneUrl = await bonsai.store.cloneUrl(initial.sourceRepo);
+  const result = bonsai.state.transition(
+    key,
+    digest,
+    checkRequestResult,
+    () => {
+      const row = bonsai.state.requireChange(input.repo, input.number);
+      if (row.head !== input.head)
+        return {
+          result: checkRequestResult.parse({ kind: "moved", head: row.head }),
+          events: [],
+        };
+      const decision = decide(
+        "requestChecks",
+        bonsai.state.reviewFacts(actor, row, input.head, []),
+      );
+      if (!decision.allowed)
+        return {
+          result: checkRequestResult.parse({
+            kind: "refused",
+            reason: decision.reason,
+          }),
+          events: [],
+        };
+      const next = bonsai.state.reviseChange(
+        { ...row, updatedAt: Date.now() },
+        row.revision,
+      );
+      const names = [
+        ...new Set(
+          input.names ??
+            bonsai.state
+              .checks(row.repo, row.number)
+              .filter((check) => check.head === row.head)
+              .map((check) => check.name),
+        ),
+      ];
+      const event =
+        input.names === undefined
+          ? bonsai.state.changeEvent(
+              next,
+              actor.name,
+              "change.checks_requested",
+              cloneUrl,
+            )
+          : bonsai.state.changeEvent(
+              next,
+              actor.name,
+              "change.checks_requested",
+              cloneUrl,
+              { names },
+            );
+      for (const name of names)
+        bonsai.state.reportCheck(row.repo, row.number, {
+          head: row.head,
+          name,
+          status: "queued",
+          reporter: actor.name,
+          attemptId: event.data.eventId,
+          runUrl: null,
+          summary: null,
+          updatedAt: next.updatedAt,
+        });
+      return {
+        result: checkRequestResult.parse({
+          kind: "requested",
+          attemptId: event.data.eventId,
+        }),
+        events: [event],
+      };
+    },
+  );
+  return result;
+}
+
+function checkAttempt(
+  bonsai: Bonsai,
+  row: ChangeRecord,
+  attemptId: string,
+): HookEvent | null {
+  const event = bonsai.state.event(attemptId);
+  if (
+    event === null ||
+    (event.type !== "change.opened" &&
+      event.type !== "change.updated" &&
+      event.type !== "change.checks_requested")
+  )
+    return null;
+  return event.data.change.repo === row.repo &&
+    event.data.change.number === row.number &&
+    event.data.change.head === row.head
+    ? event
+    : null;
+}
+
+export async function reportCheck(
+  bonsai: Bonsai,
+  actor: BonsaiActor,
+  input: {
+    repo: string;
+    number: number;
+    head: string;
+    name: string;
+    status: Check["status"];
+    attemptId: string;
+    runUrl?: string | undefined;
+    summary?: string | undefined;
+  },
+  requestKey: string = replayKey(),
+): Promise<CheckReportResult> {
+  const key = `check-report:${requestKey}`;
+  const digest = JSON.stringify({ actor, input });
+  const cached = bonsai.state.receipt(key, digest, checkReportResult);
+  if (cached !== null) {
+    return cached.result;
+  }
+  const initial = await recoverExpiredLease(
+    bonsai,
+    bonsai.state.requireChange(input.repo, input.number),
+  );
+  const cloneUrl = await bonsai.store.cloneUrl(initial.sourceRepo);
+  const result = bonsai.state.transition(key, digest, checkReportResult, () => {
+    const row = bonsai.state.requireChange(input.repo, input.number);
+    if (row.head !== input.head)
+      return {
+        result: checkReportResult.parse({ kind: "moved", head: row.head }),
+        events: [],
+      };
+    const decision = decide(
+      "reportCheck",
+      bonsai.state.reviewFacts(actor, row, input.head, []),
+    );
+    if (!decision.allowed)
+      return {
+        result: checkReportResult.parse({
+          kind: "refused",
+          reason: decision.reason,
+        }),
+        events: [],
+      };
+    const attempt = checkAttempt(bonsai, row, input.attemptId);
+    if (attempt === null)
+      throw new AppMethodRefusal(
+        "invalid",
+        "Checks require an actual Change trigger event identity",
+      );
+    const previous = bonsai.state
+      .checks(row.repo, row.number)
+      .find((check) => check.head === row.head && check.name === input.name);
+    const runUrl = input.runUrl ?? null;
+    const summary = input.summary ?? null;
+    if (previous !== undefined) {
+      const previousAttempt = checkAttempt(bonsai, row, previous.attemptId);
+      if (
+        previousAttempt !== null &&
+        previousAttempt.data.activity.id > attempt.data.activity.id
+      )
+        return {
+          result: checkReportResult.parse({ kind: "settled" }),
+          events: [],
+        };
+      if (previous.attemptId === input.attemptId) {
+        if (previous.status === "passed" || previous.status === "failed") {
+          const same =
+            previous.status === input.status &&
+            previous.runUrl === runUrl &&
+            previous.summary === summary &&
+            previous.reporter === actor.name;
+          return {
+            result: checkReportResult.parse({
+              kind: same ? "recorded" : "settled",
+            }),
+            events: [],
+          };
+        }
+        if (previous.status === "running" && input.status === "queued")
+          return {
+            result: checkReportResult.parse({ kind: "settled" }),
+            events: [],
+          };
+      }
+    }
+    const next = bonsai.state.reviseChange(
+      { ...row, updatedAt: Date.now() },
+      row.revision,
+    );
+    bonsai.state.reportCheck(row.repo, row.number, {
+      head: row.head,
+      name: input.name,
+      status: input.status,
+      reporter: actor.name,
+      attemptId: input.attemptId,
+      runUrl,
+      summary,
+      updatedAt: next.updatedAt,
+    });
+    const events =
+      input.status === "passed" || input.status === "failed"
+        ? [
+            bonsai.state.changeEvent(
+              next,
+              actor.name,
+              "change.checked",
+              cloneUrl,
+              { name: input.name, status: input.status },
+            ),
+          ]
+        : [];
+    return { result: checkReportResult.parse({ kind: "recorded" }), events };
+  });
+  return result;
+}