omp-onlyne 0.1.0 → 0.3.0

package/src/drafts.ts

@@ -11,11 +11,17 @@ interface Draft {
 	prepared: PreparedSend;
 }
 
+/** How a caller names the draft it wants sent: by id, or by the message it answers. */
+export interface DraftRequest {
+	id?: string;
+	in_reply_to?: Json;
+}
+
 export async function createDraft(runtime: PluginRuntime, ctx: ExtensionContext, input: MsgInput, signal?: AbortSignal): Promise<unknown> {
 	const meta = { ...input.meta };
 	delete meta.op;
 	if (meta.relation !== "reply" && meta.relation !== "followup") throw new OnlyneError("invalid_request", t("draftNeedsRelation"));
-	const original = await resolveSource(runtime, meta.in_reply_to);
+	const original = await sourceReference(runtime, meta.in_reply_to);
 	if (ctx.agent.kind === "sub") {
 		const authorized = (await runtime.contexts.list()).some(record => record.agent_id === ctx.agent.id
 			&& record.source?.sender === original.sender && record.source.id === original.id);
@@ -30,28 +36,71 @@ export async function createDraft(runtime: PluginRuntime, ctx: ExtensionContext,
 		in_reply_to: original, body: prepared.message.msg, state: "draft", send: { meta: { draft_id: draft.id } } };
 }
 
-export async function sendDraft(runtime: PluginRuntime, ctx: ExtensionContext, id: string, signal?: AbortSignal): Promise<unknown> {
+/**
+ * Sends a prepared reply. The caller may name the draft by id or by the message it answers; a
+ * call that names neither continues with the most recent draft this session created, because
+ * the draft already carries the one decision that must not be taken twice — its plan.
+ */
+export async function sendDraft(runtime: PluginRuntime, ctx: ExtensionContext, request: DraftRequest, signal?: AbortSignal): Promise<unknown> {
 	if (ctx.agent.kind === "sub") throw new OnlyneError("forbidden", t("draftChildCannotSend"));
-	const draft = await runtime.storage.transaction(tx => tx.get<Draft>(`draft/${id}`));
-	if (draft === undefined) throw new OnlyneError("not_found", t("draftNotFound", { id }));
+	const draft = await findDraft(runtime, ctx, request);
 	const { to, message, plan } = draft.prepared;
 	return runtime.node.client.send(to, message, plan, { context: ctx.agent.id, signal });
 }
 
-async function resolveSource(runtime: PluginRuntime, value: Json | undefined): Promise<MessageRef> {
-	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new OnlyneError("invalid_request", t("draftNeedsReference"));
-	if (typeof value.sender === "string" && typeof value.id === "string") return { sender: value.sender, id: value.id };
-	if (typeof value.thread === "string" && (typeof value.seq === "string" || typeof value.seq === "number")) {
-		const slash = value.thread.lastIndexOf("/");
-		const thread = slash < 0 ? { owner: runtime.config.node.id, id: value.thread }
-			: { owner: value.thread.slice(0, slash), id: value.thread.slice(slash + 1) };
-		let cursor: string | undefined;
-		do {
-			const result = await runtime.node.messages.list(runtime.node.auth, thread, { attention: "thread", page_size: 100, cursor });
-			const found = result.items.find(row => row.seq === String(value.seq));
-			if (found !== undefined) return { sender: found.message.sender, id: found.message.id };
-			cursor = result.next_cursor ?? undefined;
-		} while (cursor !== undefined);
+/**
+ * Draft lookup. The index is (created_by, in_reply_to): a reference names the draft that
+ * answered that message, and a session with no reference of its own sends the newest draft it
+ * created. Several drafts can answer one message — a child drafted, then the main session
+ * answered something else — so the newest wins; the draft's own plan is what makes the choice
+ * safe, since no wording is decided again here.
+ */
+async function findDraft(runtime: PluginRuntime, ctx: ExtensionContext, request: DraftRequest): Promise<Draft> {
+	if (request.id !== undefined) {
+		const draft = await runtime.storage.transaction(tx => tx.get<Draft>(`draft/${request.id}`));
+		if (draft === undefined) throw new OnlyneError("not_found", t("draftNotFound", { id: request.id }));
+		return draft;
+	}
+	// The store is the only index: drafts outlive the session that created them, and a scan of
+	// a handful of rows costs less than a second index that could disagree with it.
+	const stored = await runtime.storage.transaction(tx => tx.scan<Draft>("draft/"));
+	const drafts = stored.map(row => row.value);
+	const wanted = request.in_reply_to === undefined ? undefined : await sourceReference(runtime, request.in_reply_to);
+	const matching = wanted === undefined
+		? drafts
+		: drafts.filter(draft => {
+				const ref = draft.prepared.message.meta?.in_reply_to;
+				return ref !== undefined && ref.sender === wanted.sender && ref.id === wanted.id;
+			});
+	// This session's own draft is preferred; a child's draft it was just handed still answers,
+	// because the reference, not the author, is what the caller named.
+	const own = matching.filter(draft => draft.created_by === ctx.agent.id);
+	const pool = wanted === undefined ? own : own.length > 0 ? own : matching;
+	const newest = pool.sort((left, right) =>
+		right.created_at.localeCompare(left.created_at) || right.id.localeCompare(left.id))[0];
+	if (newest !== undefined) return newest;
+	throw wanted === undefined
+		? new OnlyneError("not_found", t("draftNoRecent"))
+		: new OnlyneError("not_found", t("draftNoMatch", { sender: wanted.sender, id: wanted.id }));
+}
+
+/** The message a draft answers, in the two shapes a caller can copy from a receipt or a read. */
+async function sourceReference(runtime: PluginRuntime, value: Json | undefined): Promise<MessageRef> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		throw new OnlyneError("invalid_request", t("draftNeedsReference"));
+	}
+	const sender = typeof value.sender === "string" && value.sender.length > 0 ? value.sender : undefined;
+	const id = typeof value.id === "string" && value.id.length > 0 ? value.id : undefined;
+	if (sender !== undefined && id !== undefined) {
+		return { sender: await runtime.decider.refs.peerId(sender).catch(() => sender), id };
+	}
+	const thread = typeof value.thread === "string" && value.thread.length > 0 ? value.thread : undefined;
+	const seq = typeof value.seq === "number" ? String(value.seq) : typeof value.seq === "string" && value.seq.length > 0 ? value.seq : undefined;
+	if (thread !== undefined && seq !== undefined) {
+		const ref = await runtime.decider.refs.threadByAlias(thread);
+		const entry = await runtime.decider.refs.entryAt(ref, seq);
+		if (entry !== undefined) return { sender: entry.message.sender, id: entry.message.id };
+		throw new OnlyneError("not_found", t("draftSourceUnavailable"));
 	}
-	throw new OnlyneError("not_found", t("draftSourceUnavailable"));
+	throw new OnlyneError("invalid_request", t("draftNeedsReference"));
 }

package/src/guard.ts

@@ -0,0 +1,107 @@
+import { OnlyneError, type Action, type Json, type NodeId } from "@onlyne/lib";
+import type { ContextRegistry } from "@onlyne/node-host/store";
+import type { ContextRecord } from "@onlyne/node-host/types";
+import { text } from "./decider-text.ts";
+import { resourceFields } from "./plan.ts";
+import { threadKey } from "./resolve.ts";
+
+/** The five intents node O-1 chooses among. */
+export type OutboundIntent = "communicate" | "inspect" | "manage_thread" | "manage_domain" | "operate_resource";
+
+export interface IntentSettlement {
+	intent: OutboundIntent;
+	/** Set when a judged intent could not execute and a deterministic rule replaced it. */
+	override?: { chosen: OutboundIntent; fallback: OutboundIntent; reason: string };
+}
+
+/** A call that names a recipient: `meta.to`, or the message it answers. */
+function addressed(meta: Record<string, Json> | undefined): boolean {
+	if (meta === undefined) return false;
+	if (typeof meta.to === "string" && meta.to.length > 0) return true;
+	return meta.in_reply_to !== null && typeof meta.in_reply_to === "object" && !Array.isArray(meta.in_reply_to);
+}
+
+/**
+ * A resource intent is executable only when the fields it needs are present. The O-1 criteria
+ * already say a message that merely mentions a file is not a resource operation, but a criterion
+ * is prose the model may violate; this is the same rule in code.
+ *
+ * When a message names an explicit recipient and carries no complete resource action, the
+ * resource choice is a misread of a communication: letting it through can only fail on missing
+ * fields, and the error would send the caller to add `meta.resource` — turning a legitimate
+ * message into an operation on somebody's resource (issue: outbound-intent-resource-false-
+ * positive). With no recipient named the resource branch keeps its own hard error, because
+ * nothing in the call says the message was meant for anyone.
+ */
+export function settleIntent(intent: OutboundIntent, meta: Record<string, Json> | undefined): IntentSettlement {
+	if (intent !== "operate_resource") return { intent };
+	if (resourceFields(meta) !== undefined) return { intent };
+	if (!addressed(meta)) return { intent };
+	return {
+		intent: "communicate",
+		override: {
+			chosen: "operate_resource",
+			fallback: "communicate",
+			reason: "the message names a recipient and carries no complete meta.resource",
+		},
+	};
+}
+
+/**
+ * A subagent may read only the threads its own context records authorize on this node. The
+ * unfiltered node-wide views stay with the main session.
+ */
+export class ActionGuard {
+	constructor(private readonly deps: { contexts: ContextRegistry; nodeId: NodeId }) {}
+
+	async assert(scope: { readOnly?: boolean; agentId: string }, action: Action): Promise<void> {
+		if (scope.readOnly !== true) return;
+		if (action.kind !== "read") {
+			throw new OnlyneError("forbidden", text("error.guard_write"));
+		}
+		if (action.scope === "resources") throw new OnlyneError("forbidden", text("error.resources_main_only"));
+		if (action.scope === "directory" || action.scope === "neighbors" || action.scope === "threads" || action.scope === "inbox") {
+			throw new OnlyneError("forbidden", text("error.guard_node_listing"));
+		}
+		const records = await this.authorized(scope.agentId);
+		if (action.scope === "evidence") {
+			const ref = action.message;
+			const tied = ref !== undefined && records.some(record =>
+				record.source !== undefined && record.source.sender === ref.sender && record.source.id === ref.id,
+			);
+			if (!tied) throw new OnlyneError("forbidden", text("error.guard_evidence"));
+			return;
+		}
+		// `{sender,id}` names no thread, so the record that received that message is the
+		// authorization — the same tie evidence uses.
+		if (action.scope === "message" && action.thread === undefined && action.message !== undefined) {
+			const ref = action.message;
+			const tied = records.some(record =>
+				record.source !== undefined && record.source.sender === ref.sender && record.source.id === ref.id,
+			);
+			if (!tied) throw new OnlyneError("forbidden", text("error.guard_message"));
+			return;
+		}
+		if (action.thread === undefined) {
+			throw new OnlyneError("forbidden", text("error.guard_thread_required"));
+		}
+		const key = threadKey(action.thread);
+		if (!records.some(record => record.thread_ref !== undefined && threadKey(record.thread_ref) === key)) {
+			throw new OnlyneError("forbidden", text("error.guard_no_slice", { thread: key }));
+		}
+	}
+
+	private async authorized(agentId: string): Promise<ContextRecord[]> {
+		let records: ContextRecord[];
+		try {
+			records = await this.deps.contexts.list();
+		} catch (error) {
+			throw new OnlyneError("unavailable", text("error.registry_unreadable", {
+				error: error instanceof Error ? error.message : String(error),
+			}));
+		}
+		return records.filter(record =>
+			record.node_id === this.deps.nodeId && record.agent_id === agentId && record.thread_ref !== undefined,
+		);
+	}
+}

package/src/handshake.ts

@@ -0,0 +1,291 @@
+import { OnlyneError, type Json, type KeyExchange, type Message, type NodeId, type Storage, type ThreadRef, type TrustEntry, type TrustPhase } from "@onlyne/lib";
+import { evaluateAcquisition, type AcquireInput, type AcquireVerdict, type AcquisitionPolicy } from "@onlyne/node-host/acquire";
+import { bridgeText as t } from "./bridge-text.ts";
+import { hostText } from "@onlyne/node-host/host-text";
+
+/**
+ * RFC 0018 §3.2: the handshake entries live in one thread this node owns alone, so nothing in
+ * them ever leaves the node, and the business thread tree stays a record of conversations
+ * rather than a log of system events.
+ */
+export const TRUST_THREAD = "trust";
+
+export function trustThread(nodeId: NodeId): ThreadRef {
+	return { owner: nodeId, id: TRUST_THREAD };
+}
+
+export function isTrustThread(nodeId: NodeId, ref: ThreadRef | undefined): boolean {
+	return ref !== undefined && ref.owner === nodeId && ref.id === TRUST_THREAD;
+}
+
+/** RFC 0018 §2.1: where one peer statement's connection arrived from. */
+export interface StatementObservation {
+	/** The address the connection came from; absent when this host could not observe one. */
+	observed?: string;
+	at: string;
+	cause: string;
+}
+
+const OBSERVED = "acquire/observed/";
+const DELIVERED = "acquire/delivered/";
+
+function observedKey(nodeId: NodeId, fingerprint: string): string {
+	return `${OBSERVED}${encodeURIComponent(nodeId)}/${encodeURIComponent(fingerprint)}`;
+}
+
+function deliveredKey(nodeId: NodeId, fingerprint: string, phase: TrustPhase): string {
+	return `${DELIVERED}${encodeURIComponent(nodeId)}/${encodeURIComponent(fingerprint)}/${phase}`;
+}
+
+/**
+ * RFC 0018 §2.1/§3: the two durable records this host keeps about a handshake. The observed
+ * address is written for every statement, before any verdict, so an approval decided later
+ * reads the address that statement itself arrived from and never the address of the call that
+ * asks (§2.1). The delivered records are one per `(node_id, fingerprint, phase)`, so a
+ * replayed event appends no second entry.
+ */
+export class AcquisitionLog {
+	constructor(private readonly storage: Storage) {}
+
+	async observe(nodeId: NodeId, fingerprint: string, observation: StatementObservation): Promise<void> {
+		await this.storage.transaction(tx => tx.put(observedKey(nodeId, fingerprint), observation));
+	}
+
+	/**
+	 * A local transition is still an observed trust event, but it must not replace the address
+	 * of the peer statement. Keep its timestamp and cause beside the original address instead.
+	 */
+	async transition(nodeId: NodeId, fingerprint: string, at: string, cause: string): Promise<void> {
+		await this.storage.transaction(async tx => {
+			const key = observedKey(nodeId, fingerprint);
+			const current = await tx.get<StatementObservation>(key);
+			await tx.put(key, { ...(current?.observed === undefined ? {} : { observed: current.observed }), at, cause });
+		});
+	}
+
+	async observation(nodeId: NodeId, fingerprint: string): Promise<StatementObservation | undefined> {
+		return this.storage.transaction(tx => tx.get<StatementObservation>(observedKey(nodeId, fingerprint)));
+	}
+
+	async delivered(nodeId: NodeId, fingerprint: string, phase: TrustPhase): Promise<boolean> {
+		return (await this.storage.transaction(tx => tx.get(deliveredKey(nodeId, fingerprint, phase)))) !== undefined;
+	}
+
+	async markDelivered(nodeId: NodeId, fingerprint: string, phase: TrustPhase, at: string): Promise<void> {
+		await this.storage.transaction(tx => tx.put(deliveredKey(nodeId, fingerprint, phase), { node_id: nodeId, fingerprint, phase, at }));
+	}
+
+	/**
+	 * RFC 0018 §3: the reports an agent already acted on are settled. A revocation names no
+	 * fingerprint, so it settles every report held for the node; a later statement opens its own.
+	 */
+	async settle(nodeId: NodeId, fingerprint?: string): Promise<void> {
+		const prefix = `${DELIVERED}${encodeURIComponent(nodeId)}/${fingerprint === undefined ? "" : `${encodeURIComponent(fingerprint)}/`}`;
+		await this.storage.transaction(async tx => {
+			for (const row of await tx.scan(prefix)) await tx.delete(row.key);
+		});
+	}
+}
+
+/** The machine facts a handshake entry carries beside its body (RFC 0018 §3). */
+export interface HandshakeFacts {
+	node_id: NodeId;
+	fingerprint: string;
+	phase: TrustPhase;
+	/** Whether this entry owes an agent decision; a status update owes none. */
+	pending: boolean;
+}
+
+/** The facts one handshake entry carries, or undefined for an entry that is not one. */
+export function handshakeFacts(meta: Message["meta"] | undefined): HandshakeFacts | undefined {
+	const value = meta?.data?.trust;
+	if (value === null || value === undefined || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const row = value as Record<string, Json>;
+	const { node_id: node, fingerprint, phase, pending } = row;
+	if (typeof node !== "string" || typeof fingerprint !== "string" || typeof pending !== "boolean") return undefined;
+	if (phase !== "invited" && phase !== "requested" && phase !== "exchanged" && phase !== "revoked") return undefined;
+	return { node_id: node, fingerprint, phase, pending };
+}
+
+export interface HandshakeInput {
+	node_id: NodeId;
+	fingerprint: string;
+	phase: TrustPhase;
+	/** The address the peer wrote into its own statement. */
+	declared: string;
+	/** The address that statement arrived from; absent when this host observed none. */
+	observed?: string;
+	policy: AcquisitionPolicy;
+	/** The judgement made for this event, when one was made. */
+	judgement?: ApprovalJudgement;
+	/** Whether an approval was committed without an agent deciding first. */
+	approved: boolean;
+}
+
+/**
+ * RFC 0018 §3: one handshake entry. The body carries what the judgement read and concluded;
+ * the action identifiers appear only when a decision is actually owed, and a status update
+ * says so instead. `pending` is the same fact for the host's todo hook.
+ */
+export function handshakeEntry(input: HandshakeInput): { msg: string; trust: { [key: string]: Json } } {
+	// RFC 0018 §3: only an invitation this host did not approve itself is work. A pending local
+	// approval waits on the peer, so there is nothing to do and nothing to wake a turn for.
+	const pending = input.phase === "invited" && !input.approved;
+	const lines = [
+		t("trustHeader", { phase: input.phase, node: input.node_id }),
+		t("trustFingerprint", { fingerprint: input.fingerprint }),
+		t("trustDeclared", { declared: input.declared }),
+		t("trustObserved", { observed: input.observed ?? t("trustUnobserved") }),
+		t("trustPolicy", { policy: input.policy.policy }),
+	];
+	if (input.judgement !== undefined) {
+		lines.push(t("trustJudgement", {
+			reason: input.judgement.verdict.reason,
+			conclusion: input.judgement.verdict.allowed ? t("trustAllowed") : t("trustRefused"),
+		}));
+	}
+	if (input.phase === "invited") lines.push(input.approved ? t("trustApproved") : t("trustInvited"));
+	else if (input.phase === "requested") lines.push(t("trustRequested"));
+	else if (input.phase === "exchanged") lines.push(t("trustExchanged"));
+	else lines.push(t("trustRevoked"));
+	if (input.phase === "invited" && !input.approved) {
+		// RFC 0018 §3: under `none` the agent may only look. Offering an action the policy
+		// refuses would ask for a decision that can never be made.
+		lines.push(input.policy.policy === "none"
+			? t("trustPanelOnly")
+			: t("trustAcceptAction", { node: input.node_id, fingerprint: input.fingerprint }));
+	}
+	if (pending) lines.push(t("trustRevokeAction", { node: input.node_id }));
+	return { msg: lines.join("\n"), trust: { node_id: input.node_id, fingerprint: input.fingerprint, phase: input.phase, pending } };
+}
+
+/** RFC 0018 §2: one approval judgement and every input it read. */
+export interface ApprovalJudgement {
+	at: string;
+	node_id: NodeId;
+	/** Absent when no fingerprint has been proved yet: an initiation reads the peer's key after the gate. */
+	fingerprint?: string;
+	policy: AcquisitionPolicy;
+	input: AcquireInput;
+	verdict: AcquireVerdict;
+}
+
+/** The judgement as the audit line records it: the time, the peer, and every input the verdict read. */
+export function judgementFacts(judgement: ApprovalJudgement): Record<string, unknown> {
+	const { input, verdict } = judgement;
+	return {
+		at: judgement.at,
+		node: judgement.node_id,
+		fingerprint: judgement.fingerprint ?? null,
+		policy: judgement.policy.policy,
+		allow: [...judgement.policy.allow],
+		observed: input.observed ?? null,
+		declared: input.declared ?? null,
+		recorded: [...(input.recorded ?? [])],
+		allowed: verdict.allowed,
+		reason: verdict.reason,
+		...(verdict.matched === undefined ? {} : { matched: verdict.matched }),
+	};
+}
+
+/** Everything the judgement reads from the host, and the two calls it may then commit. */
+export interface ApprovalDeps {
+	policy: AcquisitionPolicy;
+	log: AcquisitionLog;
+	/** RFC 0018 §2.1: the address the peer's last statement arrived from, as this host recorded it. */
+	observed(nodeId: NodeId, fingerprint: string): Promise<string | undefined>;
+	/** The address the peer wrote into its own statement, never the address of this call. */
+	declared(nodeId: NodeId): Promise<string | undefined>;
+	/** Every discovery address recorded for this node id; each is an outbound candidate (§2.2). */
+	recorded(nodeId: NodeId): Promise<string[]>;
+	/** The audit line, written whether or not the verdict allows the approval (§4.1). */
+	audit(judgement: ApprovalJudgement): void;
+	accept(nodeId: NodeId, fingerprint: string): Promise<TrustEntry>;
+	revoke(nodeId: NodeId): Promise<void>;
+	now(): string;
+}
+
+export interface ApprovalRequest {
+	node_id: NodeId;
+	/** The fingerprint the peer proved. Omitted by an initiation, whose key read comes after the gate. */
+	fingerprint?: string;
+	/** The statement's own connection address, when the caller is holding it. */
+	observed?: string;
+	/**
+	 * The discovery addresses as they stood when the statement arrived (RFC 0018 §2.2). A record
+	 * this host derives from the statement itself is not part of the judgement.
+	 */
+	recorded?: string[];
+}
+
+/**
+ * RFC 0018 §2: the one judgement, read by both the agent path and the auto-approval path.
+ * `observed` is the address a recorded statement arrived from — the caller's live connection
+ * address only when it is judging the statement it just received — and the declared address
+ * and every recorded address are checked with it (§2.1–2.2).
+ */
+export async function judgeApproval(deps: ApprovalDeps, request: ApprovalRequest): Promise<ApprovalJudgement> {
+	const observed = request.observed
+		?? (request.fingerprint === undefined ? undefined : await deps.observed(request.node_id, request.fingerprint));
+	const declared = await deps.declared(request.node_id);
+	const input: AcquireInput = {
+		...(observed === undefined || observed === "" ? {} : { observed }),
+		...(declared === undefined || declared === "" ? {} : { declared }),
+		recorded: request.recorded ?? await deps.recorded(request.node_id),
+	};
+	const judgement: ApprovalJudgement = {
+		at: deps.now(), node_id: request.node_id, fingerprint: request.fingerprint,
+		policy: deps.policy, input, verdict: await evaluateAcquisition(deps.policy, input),
+	};
+	deps.audit(judgement);
+	return judgement;
+}
+
+/** The refusal an agent-initiated approval gets. A refused approval is not a revocation: the peer's row is left as it is. */
+export function approvalRefused(judgement: ApprovalJudgement): OnlyneError {
+	const { policy, verdict } = judgement;
+	return new OnlyneError("forbidden", hostText("acquireDenied", { policy: policy.policy, reason: verdict.reason }), {
+		policy_denied: verdict.reason,
+		policy: policy.policy,
+		...(judgement.input.observed === undefined ? {} : { observed: judgement.input.observed }),
+		...(judgement.input.declared === undefined ? {} : { declared: judgement.input.declared }),
+	});
+}
+
+/** RFC 0018 §2/§3.1: the agent's `trust_accept`, judged before anything is committed. */
+export async function approvePeer(deps: ApprovalDeps, nodeId: NodeId, fingerprint: string): Promise<TrustEntry> {
+	const judgement = await judgeApproval(deps, { node_id: nodeId, fingerprint });
+	if (!judgement.verdict.allowed) throw approvalRefused(judgement);
+	const entry = await deps.accept(nodeId, fingerprint);
+	await deps.log.settle(nodeId, fingerprint);
+	return entry;
+}
+
+/**
+ * RFC 0018 §2/§3.1: the agent's `trust_begin`. The judgement reads stored facts only and runs
+ * before `exchange`, which is this path's first outbound request — the key read that starts the
+ * exchange — so a refusal sends nothing and leaves the peer's row untouched. On an allow the
+ * library commits the local approval and mails the statement, and the entry it returns carries
+ * the phase that commit produced.
+ */
+export async function beginPeer(
+	deps: ApprovalDeps,
+	exchange: (nodeId: NodeId) => Promise<KeyExchange>,
+	request: ApprovalRequest,
+): Promise<{ session: KeyExchange; entry: TrustEntry }> {
+	const judgement = await judgeApproval(deps, request);
+	if (!judgement.verdict.allowed) throw approvalRefused(judgement);
+	const session = await exchange(request.node_id);
+	const entry = await session.confirm(session.fingerprint);
+	await deps.log.settle(request.node_id, entry.fingerprint);
+	return { session, entry };
+}
+
+/**
+ * RFC 0018 §2: the agent's `trust_revoke`, never judged. The policy decides who may come in;
+ * it has no say over who may be turned away, which is also why this path reads no address.
+ */
+export async function revokePeer(deps: ApprovalDeps, nodeId: NodeId): Promise<void> {
+	await deps.revoke(nodeId);
+	await deps.log.settle(nodeId);
+}