Skip to content
Python
23.7 KB
Raw Blame
import { createHash } from "node:crypto";
import type { HostReadTool } from "@one-memory/host-bridge";

export interface BatchOwner {
  userId: string;
  runtimeId: string;
}
export interface SourceIdentity {
  sourceId: string;
  rootId: string;
  rootPath: string;
  grantRevision: number;
}
/** layoutDigest covers the COMPLETE trusted RecallHostLayout, including paths,
 * plugin/supersedes/channel. It is not a host label or a renderer-chosen path. */
export interface HostIdentity {
  hostId: string;
  layoutDigest: string;
  installationId: string | null;
  permissionRevision: number;
  /** Hash of nonsecret managed-file/layout state; NEVER a credential digest. */
  installationDigest: string | null;
}
export type ConnectionItem =
  | {
      id: string;
      kind: "install";
      sources: SourceIdentity[];
      host: HostIdentity;
      previewFingerprint: string;
    }
  | {
      id: string;
      kind: "readGrant";
      sources: SourceIdentity[];
      host: HostIdentity;
      installItemId?: string;
      allowedTools: readonly HostReadTool[];
      allowedScopes: readonly string[];
    };
export interface ConnectionPlan extends BatchOwner {
  schemaVersion: 1;
  operationId: string;
  items: ConnectionItem[];
}
interface ReceiptBinding extends BatchOwner {
  operationId: string;
  itemId: string;
  intentDigest: string;
}
export type ItemReceipt = ReceiptBinding &
  (
    | { kind: "install"; host: HostIdentity }
    | {
        kind: "readGrant";
        host: HostIdentity;
        allowedTools: readonly HostReadTool[];
        allowedScopes: readonly string[];
      }
  );
export interface ItemContext extends ReceiptBinding {
  /** Receipt of this batch's completed install, or the exact original identity. */
  host: HostIdentity | null;
}
export type Inspection =
  | { status: "denied" | "unavailable" }
  | {
      status: "ready";
      sources: SourceIdentity[];
      host: HostIdentity | null;
      previewFingerprint: string | null;
    };
export type AdapterResult =
  | { status: "succeeded"; receipt: ItemReceipt }
  | { status: "unknown" | "rejected" | "changed" | "not_applied" };
export interface ItemAdapter {
  /** Must atomically recheck supplied identities/fingerprints with the effect.
   * Rejected means authoritative refusal, not an arbitrary transport exception. */
  apply(
    item: Readonly<ConnectionItem>,
    context: Readonly<ItemContext>,
  ): Promise<AdapterResult>;
  /** READ ONLY. Correlate operation/intent to authority receipts. Mere presence
   * of an installation or enabled flag does not prove this operation succeeded. */
  reconcile(
    item: Readonly<ConnectionItem>,
    context: Readonly<ItemContext>,
  ): Promise<AdapterResult>;
}
export interface BatchAdapters {
  inspect(
    item: Readonly<ConnectionItem>,
    context: Readonly<ItemContext>,
  ): Promise<Inspection>;
  install: ItemAdapter;
  readGrant: ItemAdapter;
}
export type ItemState =
  | "pending"
  | "in_flight"
  | "succeeded"
  | "unknown"
  | "rejected"
  | "changed"
  | "not_applied"
  | "unavailable"
  | "dependency_blocked";
export interface ItemJournal {
  id: string;
  kind: ConnectionItem["kind"];
  intentDigest: string;
  state: ItemState;
  receipt: ItemReceipt | null;
}
/** Nonsecret operation summary only, not permission authority or host config. */
export interface BatchJournal extends BatchOwner {
  schemaVersion: 1;
  operationId: string;
  planDigest: string;
  revision: number;
  items: ItemJournal[];
}
export interface BatchLedger {
  durability: "process" | "persistent";
  /** Runtime-wide exclusive execution across all batches/instances for this
   * owner, held until in-flight calls settle. Persistent implementations must
   * fence process owners; timeout alone may not steal a live executor's lock. */
  exclusive<T>(owner: BatchOwner, operation: () => Promise<T>): Promise<T>;
  load(owner: BatchOwner, operationId: string): Promise<BatchJournal | null>;
  /** Atomic durable CAS; create expected=null must refuse existing files. A
   * successful return must survive restart before any adapter effect starts. */
  commit(
    owner: BatchOwner,
    operationId: string,
    expectedRevision: number | null,
    next: BatchJournal,
  ): Promise<void>;
}
export interface BatchOptions {
  mode?: "preview" | "execute";
  userConfirmed?: boolean;
  planDigest?: string;
  signal?: AbortSignal;
}
export interface BatchResult {
  mode: "preview" | "execute";
  operationId: string;
  planDigest: string;
  state: "preview" | "completed" | "partial";
  recovery: "none" | "process" | "persistent";
  cancelled: boolean;
  items: ItemJournal[];
}

/** Only trusted Runtime control callers may instantiate this module. Digest is
 * confirmation integrity, NOT authentication. Nothing here accesses files or
 * credentials; the injected ledger/adapters own those established boundaries. */
export class ConnectionBatch {
  private readonly owner: BatchOwner;
  constructor(
    owner: BatchOwner,
    private readonly adapters: BatchAdapters,
    private readonly ledger?: BatchLedger,
  ) {
    this.owner = freeze(clone(owner));
    exact(this.owner, ["userId", "runtimeId"]);
    identifier(this.owner.userId);
    identifier(this.owner.runtimeId);
  }

  async run(
    input: ConnectionPlan,
    options: BatchOptions = {},
  ): Promise<BatchResult> {
    const plan = checkedPlan(input);
    if (
      plan.userId !== this.owner.userId ||
      plan.runtimeId !== this.owner.runtimeId
    )
      fail("owner_mismatch");
    const digest = connectionPlanDigest(plan);
    if (
      options.mode !== undefined &&
      options.mode !== "preview" &&
      options.mode !== "execute"
    )
      fail("invalid_input");
    const confirmed = options.userConfirmed === true;
    const approvedDigest = options.planDigest;
    const signal = options.signal;
    const initial: BatchJournal = {
      schemaVersion: 1,
      ...this.owner,
      operationId: plan.operationId,
      planDigest: digest,
      revision: 1,
      items: plan.items.map((item) => ({
        id: item.id,
        kind: item.kind,
        intentDigest: itemDigest(item),
        state: "pending",
        receipt: null,
      })),
    };
    if (options.mode !== "execute") {
      for (const [index, item] of plan.items.entries()) {
        if (signal?.aborted) break;
        const context = this.context(plan, item, initial);
        initial.items[index].state = context
          ? await this.inspect(item, context)
          : "dependency_blocked";
      }
      return this.result(initial, "preview", signal?.aborted === true);
    }
    if (!confirmed) fail("confirmation_required");
    if (approvedDigest !== digest) fail("plan_changed");
    const ledger = this.ledger;
    if (!ledger) fail("ledger_required");
    if (!["process", "persistent"].includes(ledger.durability))
      fail("ledger_invalid");
    return ledger
      .exclusive(this.owner, async () => {
        let saved: BatchJournal | null;
        try {
          saved = await ledger.load(this.owner, plan.operationId);
        } catch {
          fail("ledger_unavailable");
        }
        let journal = initial;
        if (saved !== null) {
          journal = this.validateJournal(saved, plan, digest);
        } else if (!signal?.aborted) {
          await this.commit(ledger, null, journal);
        } else return this.result(journal, "execute", true);
        const persist = async (
          index: number,
          state: ItemState,
          receipt: ItemReceipt | null = null,
        ) => {
          const next = clone(journal);
          next.revision++;
          next.items[index] = { ...next.items[index], state, receipt };
          await this.commit(ledger, journal.revision, next);
          journal = next;
        };
        for (const [index, item] of plan.items.entries()) {
          if (signal?.aborted) break;
          const previous = journal.items[index];
          if (
            ["succeeded", "rejected", "changed", "not_applied"].includes(
              previous.state,
            )
          )
            continue;
          const context = this.context(plan, item, journal);
          if (!context) {
            if (previous.state !== "dependency_blocked")
              await persist(index, "dependency_blocked");
            continue;
          }
          const adapter = this.adapters[item.kind];
          if (previous.state === "unknown" || previous.state === "in_flight") {
            // Effect may have committed before connection/ledger loss. No retry
            // is permitted, even if reconciliation reports definitively absent.
            const recoveryIdentity = await this.recoveryIdentity(item, context);
            if (recoveryIdentity !== "pending") {
              await persist(index, recoveryIdentity);
              continue;
            }
            const resolved = await this.effect(
              adapter,
              "reconcile",
              item,
              context,
            );
            await persist(index, resolved.state, resolved.receipt);
            continue;
          }
          const inspection = await this.inspect(item, context);
          if (signal?.aborted) break;
          if (inspection !== "pending") {
            await persist(index, inspection);
            continue;
          }
          // Journal I/O is deliberately outside effect catch: a failed save
          // stops the batch and preserves in_flight for later reconciliation.
          await persist(index, "in_flight");
          if (signal?.aborted) {
            await persist(index, "not_applied");
            break;
          }
          const outcome = await this.effect(adapter, "apply", item, context);
          await persist(index, outcome.state, outcome.receipt);
        }
        return this.result(journal, "execute", signal?.aborted === true);
      })
      .catch((error: unknown) => {
        if (
          error instanceof Error &&
          [
            "connection_batch_operation_conflict",
            "connection_batch_journal_invalid",
            "connection_batch_ledger_unavailable",
          ].includes(error.message)
        )
          throw error;
        fail("ledger_unavailable");
      });
  }

  private context(
    plan: ConnectionPlan,
    item: ConnectionItem,
    journal: BatchJournal,
  ): Readonly<ItemContext> | null {
    let host = item.host;
    if (item.kind === "readGrant" && item.installItemId) {
      const dependency = journal.items.find(
        (row) => row.id === item.installItemId,
      );
      if (
        dependency?.state !== "succeeded" ||
        dependency.receipt?.kind !== "install"
      )
        return null;
      host = dependency.receipt.host;
    }
    return freeze(
      clone({
        ...this.owner,
        operationId: plan.operationId,
        itemId: item.id,
        intentDigest: itemDigest(item),
        host,
      }),
    );
  }

  private async inspect(
    item: ConnectionItem,
    context: Readonly<ItemContext>,
  ): Promise<ItemState> {
    try {
      const value = await this.adapters.inspect(item, context);
      if (value.status === "denied") return "rejected";
      if (value.status !== "ready") return "unavailable";
      if (canonical(value.sources) !== canonical(item.sources))
        return "changed";
      if (canonical(value.host) !== canonical(context.host)) return "changed";
      if (
        item.kind === "install" &&
        value.previewFingerprint !== item.previewFingerprint
      )
        return "changed";
      return "pending";
    } catch {
      return "unavailable";
    }
  }

  private async recoveryIdentity(
    item: ConnectionItem,
    context: Readonly<ItemContext>,
  ): Promise<"pending" | "changed" | "unknown" | "rejected"> {
    try {
      const current = await this.adapters.inspect(item, context);
      if (current.status === "denied") return "rejected";
      if (current.status !== "ready") return "unknown";
      if (canonical(current.sources) !== canonical(item.sources))
        return "changed";
      // The write itself may have changed revision/fingerprint. Reconciliation
      // must prove that exact transition, but never across another layout/root.
      return current.host?.hostId === item.host.hostId &&
        current.host.layoutDigest === item.host.layoutDigest
        ? "pending"
        : "changed";
    } catch {
      return "unknown";
    }
  }

  private async effect(
    adapter: ItemAdapter,
    method: "apply" | "reconcile",
    item: ConnectionItem,
    context: Readonly<ItemContext>,
  ): Promise<{ state: ItemState; receipt: ItemReceipt | null }> {
    try {
      const result = await adapter[method](item, context);
      if (result.status === "succeeded")
        return {
          state: "succeeded",
          receipt: validatedReceipt(result.receipt, item, context),
        };
      if (["rejected", "changed", "not_applied"].includes(result.status))
        return { state: result.status as ItemState, receipt: null };
    } catch {
      /* Transport and malformed receipt errors must never leak secrets. */
    }
    return { state: "unknown", receipt: null };
  }

  private async commit(
    ledger: BatchLedger,
    expected: number | null,
    next: BatchJournal,
  ) {
    try {
      await ledger.commit(
        this.owner,
        next.operationId,
        expected,
        freeze(clone(next)),
      );
    } catch {
      fail("ledger_unavailable");
    }
  }

  private validateJournal(
    value: BatchJournal,
    plan: ConnectionPlan,
    digest: string,
  ): BatchJournal {
    try {
      exact(value, [
        "schemaVersion",
        "userId",
        "runtimeId",
        "operationId",
        "planDigest",
        "revision",
        "items",
      ]);
      if (
        value.schemaVersion !== 1 ||
        value.userId !== this.owner.userId ||
        value.runtimeId !== this.owner.runtimeId ||
        value.operationId !== plan.operationId
      )
        fail("journal_invalid");
      integer(value.revision, 1);
      hash(value.planDigest);
      if (value.planDigest !== digest) fail("operation_conflict");
      if (
        !Array.isArray(value.items) ||
        value.items.length !== plan.items.length
      )
        fail("journal_invalid");
      const journal = clone(value);
      for (const [index, row] of journal.items.entries()) {
        const item = plan.items[index];
        exact(row, ["id", "kind", "intentDigest", "state", "receipt"]);
        if (
          row.id !== item.id ||
          row.kind !== item.kind ||
          row.intentDigest !== itemDigest(item) ||
          ![
            "pending",
            "in_flight",
            "succeeded",
            "unknown",
            "rejected",
            "changed",
            "not_applied",
            "dependency_blocked",
            "unavailable",
          ].includes(row.state)
        )
          fail("journal_invalid");
        if (row.state === "succeeded") {
          const context = this.context(plan, item, journal);
          if (!context || !row.receipt) fail("journal_invalid");
          row.receipt = validatedReceipt(row.receipt, item, context);
        } else if (row.receipt !== null) fail("journal_invalid");
      }
      return journal;
    } catch (error) {
      if (
        error instanceof Error &&
        error.message === "connection_batch_operation_conflict"
      )
        throw error;
      fail("journal_invalid");
    }
  }

  private result(
    journal: BatchJournal,
    mode: "preview" | "execute",
    cancelled: boolean,
  ): BatchResult {
    return clone({
      mode,
      operationId: journal.operationId,
      planDigest: journal.planDigest,
      state:
        mode === "preview"
          ? "preview"
          : journal.items.every((item) => item.state === "succeeded")
            ? "completed"
            : "partial",
      recovery:
        mode === "preview" ? "none" : (this.ledger?.durability ?? "none"),
      cancelled,
      items: journal.items,
    });
  }
}

export function connectionPlanDigest(plan: ConnectionPlan): string {
  return createHash("sha256")
    .update(`one-memory:connection-batch:v1\n${canonical(checkedPlan(plan))}`)
    .digest("hex");
}
function itemDigest(item: ConnectionItem) {
  return createHash("sha256").update(canonical(item)).digest("hex");
}
function checkedPlan(input: ConnectionPlan): ConnectionPlan {
  let plan: ConnectionPlan;
  try {
    plan = clone(input);
  } catch {
    fail("invalid_input");
  }
  exact(plan, ["schemaVersion", "userId", "runtimeId", "operationId", "items"]);
  if (plan.schemaVersion !== 1) fail("invalid_input");
  identifier(plan.userId);
  identifier(plan.runtimeId);
  identifier(plan.operationId);
  if (
    !Array.isArray(plan.items) ||
    plan.items.length > 96 ||
    plan.items.length === 0
  )
    fail("invalid_input");
  const ids = new Set<string>(),
    targets = new Set<string>();
  for (const item of plan.items) {
    identifier(item.id);
    if (ids.has(item.id)) fail("invalid_input");
    if (item.kind === "install" || item.kind === "readGrant") {
      exact(item, [
        "id",
        "kind",
        "sources",
        "host",
        ...(item.kind === "install"
          ? ["previewFingerprint"]
          : [
              "allowedTools",
              "allowedScopes",
              ...(Object.hasOwn(item, "installItemId")
                ? ["installItemId"]
                : []),
            ]),
      ]);
      hostIdentity(item.host);
      if (!Array.isArray(item.sources) || item.sources.length > 32)
        fail("invalid_input");
      item.sources.forEach(sourceIdentity);
      if (
        new Set(item.sources.map((source) => source.sourceId)).size !==
        item.sources.length
      )
        fail("invalid_input");
      if (item.kind === "install") hash(item.previewFingerprint);
      else {
        stringSet(item.allowedTools, 5);
        stringSet(item.allowedScopes, 64);
        if (
          !item.allowedTools.every((tool) =>
            [
              "om_recall",
              "om_ask",
              "om_conversations",
              "om_matters",
              "om_diagnostic_trace",
            ].includes(tool),
          )
        )
          fail("invalid_input");
        for (const scope of item.allowedScopes) {
          if (
            !(
              scope === "all-apps" ||
              /^workspace:v1:[a-f0-9]{64}$/.test(scope) ||
              /^source:[a-z0-9][a-z0-9-]{0,127}$/.test(scope)
            )
          )
            fail("invalid_input");
          if (
            scope.startsWith("source:") &&
            !item.sources.some(
              (source) => scope === `source:${source.sourceId}`,
            )
          )
            fail("invalid_input");
        }
        if (item.installItemId !== undefined) {
          identifier(item.installItemId);
          const prior = plan.items.find(
            (candidate) => candidate.id === item.installItemId,
          );
          if (
            !ids.has(item.installItemId) ||
            prior?.kind !== "install" ||
            canonical(prior.host) !== canonical(item.host) ||
            canonical(prior.sources) !== canonical(item.sources)
          )
            fail("invalid_input");
        } else if (
          item.host.installationId === null ||
          plan.items.some(
            (candidate) =>
              candidate.kind === "install" &&
              candidate.host.hostId === item.host.hostId,
          )
        )
          fail("invalid_input");
      }
    } else fail("invalid_input");
    const target = `${item.kind}:${item.host.hostId}`;
    if (targets.has(target)) fail("invalid_input");
    ids.add(item.id);
    targets.add(target);
  }
  return freeze(plan);
}
function validatedReceipt(
  input: ItemReceipt,
  item: ConnectionItem,
  context: ItemContext,
): ItemReceipt {
  const value = clone(input);
  const base = [
    "userId",
    "runtimeId",
    "operationId",
    "itemId",
    "intentDigest",
    "kind",
  ];
  if (
    !value ||
    value.kind !== item.kind ||
    value.userId !== context.userId ||
    value.runtimeId !== context.runtimeId ||
    value.operationId !== context.operationId ||
    value.itemId !== context.itemId ||
    value.intentDigest !== context.intentDigest
  )
    fail("receipt_invalid");
  exact(value, [
    ...base,
    "host",
    ...(value.kind === "readGrant" ? ["allowedTools", "allowedScopes"] : []),
  ]);
  hostIdentity(value.host);
  if (
    !context.host ||
    value.host.hostId !== context.host.hostId ||
    value.host.layoutDigest !== context.host.layoutDigest ||
    !value.host.installationId ||
    !value.host.installationDigest
  )
    fail("receipt_invalid");
  if (value.kind === "install") {
    if (
      value.host.permissionRevision !== 1 ||
      value.host.installationId === context.host.installationId
    )
      fail("receipt_invalid");
  } else if (item.kind === "readGrant") {
    if (
      value.host.installationId !== context.host.installationId ||
      value.host.installationDigest !== context.host.installationDigest ||
      value.host.permissionRevision !== context.host.permissionRevision + 1 ||
      canonical(value.allowedTools) !== canonical(item.allowedTools) ||
      canonical(value.allowedScopes) !== canonical(item.allowedScopes)
    )
      fail("receipt_invalid");
  }
  return value;
}
function sourceIdentity(source: SourceIdentity) {
  exact(source, ["sourceId", "rootId", "rootPath", "grantRevision"]);
  identifier(source.sourceId);
  identifier(source.rootId);
  text(source.rootPath);
  integer(source.grantRevision, 1);
}
function hostIdentity(host: HostIdentity) {
  exact(host, [
    "hostId",
    "layoutDigest",
    "installationId",
    "permissionRevision",
    "installationDigest",
  ]);
  identifier(host.hostId);
  hash(host.layoutDigest);
  integer(host.permissionRevision, 0);
  if (host.installationId === null) {
    if (host.permissionRevision !== 0 || host.installationDigest !== null)
      fail("invalid_input");
  } else {
    identifier(host.installationId);
    hash(host.installationDigest);
    if (host.permissionRevision < 1) fail("invalid_input");
  }
}
function exact(value: unknown, keys: string[]) {
  if (
    !value ||
    typeof value !== "object" ||
    Array.isArray(value) ||
    Object.keys(value).length !== keys.length ||
    keys.some((key) => !Object.hasOwn(value, key))
  )
    fail("invalid_input");
}
function identifier(value: unknown) {
  if (
    typeof value !== "string" ||
    !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$/.test(value)
  )
    fail("invalid_input");
}
function text(value: unknown) {
  if (
    typeof value !== "string" ||
    value.length < 1 ||
    value.length > 4096 ||
    [...value].some(
      (character) =>
        character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
    )
  )
    fail("invalid_input");
}
function hash(value: unknown) {
  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value))
    fail("invalid_input");
}
function integer(value: unknown, minimum: number) {
  if (
    !Number.isSafeInteger(value) ||
    (value as number) < minimum ||
    (value as number) >= Number.MAX_SAFE_INTEGER
  )
    fail("invalid_input");
}
function stringSet(values: readonly string[], max: number) {
  if (
    !Array.isArray(values) ||
    values.length < 1 ||
    values.length > max ||
    new Set(values).size !== values.length
  )
    fail("invalid_input");
  values.forEach(text);
}
function canonical(value: unknown): string {
  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
  if (value && typeof value === "object")
    return `{${Object.keys(value)
      .sort()
      .map(
        (key) =>
          `${JSON.stringify(key)}:${canonical((value as Record<string, unknown>)[key])}`,
      )
      .join(",")}}`;
  return JSON.stringify(value);
}
function clone<T>(value: T): T {
  return structuredClone(value);
}
function freeze<T>(value: T): T {
  if (value && typeof value === "object") {
    for (const child of Object.values(value)) freeze(child);
    Object.freeze(value);
  }
  return value;
}
function fail(code: string): never {
  throw new Error(`connection_batch_${code}`);
}