pi-radar 0.2.0 → 0.3.0

package/extension/generated-contracts.ts

@@ -19,6 +19,70 @@ export interface TaskLaneStatus {
   available: boolean;
   error: string | null;
 }
+/**
+ * Inputs for publishing an immutable handoff. The wire request ID carries the
+ * stable communication identity; the daemon derives the sender execution.
+ */
+export interface HandoffPublishParamsDeserialize {
+  content: string;
+  correlation_id?: string | null;
+  recipient_subject_id: string;
+  sender_agent_id: string;
+  summary: string;
+}
+/**
+ * A bounded inbox page by stable handoff ID. Payloads are fetched one at a
+ * time with `communication.get`, keeping each response within the wire bound.
+ */
+export interface HandoffInboxSerialize {
+  handoff_ids: string[];
+}
+/**
+ * Immutable handoff content. The request id is the stable communication id.
+ */
+export interface HandoffSerialize {
+  content: string;
+  correlation_id?: string | null;
+  id: string;
+  published_at_unix_ms: number;
+  recipient_subject_id: string;
+  sender: HandoffIdentity;
+  summary: string;
+  version: number;
+}
+/**
+ * The current managed Pi execution that published or received a handoff.
+ * `subject_id` is stable across verified successors; `execution_id` and
+ * generation identify the exact execution that took the action.
+ */
+export interface HandoffIdentity {
+  agent_id: string;
+  execution_generation: number;
+  execution_id: string;
+  session_id: string;
+  subject_id: string;
+}
+/**
+ * Durable recipient-consumer receipt, stored separately from immutable content.
+ */
+export interface HandoffReceiptSerialize {
+  handoff_id: string;
+  received_at_unix_ms: number;
+  recipient: HandoffIdentity;
+  version: number;
+}
+/**
+ * The current managed Pi execution that published or received a handoff.
+ * `subject_id` is stable across verified successors; `execution_id` and
+ * generation identify the exact execution that took the action.
+ */
+export interface HandoffIdentity {
+  agent_id: string;
+  execution_generation: number;
+  execution_id: string;
+  session_id: string;
+  subject_id: string;
+}
 /**
  * Managed owner/parent metadata accepted with a spawn intent. Domain validation
  * and parent-binding checks remain in the daemon handler.

package/extension/radar-client.ts

@@ -6,6 +6,10 @@ import type {
 	DaemonPingSerialize,
 	LaunchIdentityMarkerSerialize,
 	FactsSnapshotDeserialize,
+	HandoffInboxSerialize,
+	HandoffReceiptSerialize,
+	HandoffPublishParamsDeserialize,
+	HandoffSerialize,
 	ManagedLaunchMetadataDeserialize,
 	SpawnExitObservationSerialize,
 } from "./generated-contracts.ts";
@@ -36,6 +40,7 @@ export const RADAR_SPAWN_CONTRACT = "spawn.v1";
 export const RADAR_SPAWN_CLOSE_CONTRACT = "spawn.close.v1";
 export const RADAR_SPAWN_LAUNCH_CONTEXT_CONTRACT = "spawn.launch_context.v1";
 export const RADAR_EVENTS_CONTRACT = "events.v1";
+export const RADAR_COMMUNICATION_CONTRACT = "communication.handoff.v1";
 /** The default audit identity; callers can supply their own requester. */
 export const RADAR_REQUESTER = "pi-radar";
 /** The daemon's own line bound; nothing longer is sent or accepted. */
@@ -162,6 +167,9 @@ export type RadarBackgroundTask = NonNullable<
 	FactsSnapshotDeserialize["background_tasks"]
 >[number];
 export type RadarFactsSnapshot = FactsSnapshotDeserialize;
+export type RadarHandoff = HandoffSerialize;
+export type RadarHandoffInbox = HandoffInboxSerialize;
+export type RadarHandoffReceipt = HandoffReceiptSerialize;
 
 /**
  * The assignment channel's interim fields. `request` is the owner's active
@@ -508,6 +516,46 @@ function numberAt(value: unknown, field: string): number | undefined {
 		: undefined;
 }
 
+function handoffAt(value: unknown): HandoffSerialize | undefined {
+	const version = numberAt(value, "version");
+	const id = stringAt(value, "id");
+	const sender = recordAt(value, "sender");
+	const senderGeneration = numberAt(sender, "execution_generation");
+	const target = stringAt(value, "recipient_subject_id");
+	const summary = stringAt(value, "summary");
+	const content = stringAt(value, "content");
+	const published = numberAt(value, "published_at_unix_ms");
+	const correlation = typeof value === "object" && value !== null
+		? (value as Record<string, unknown>).correlation_id
+		: undefined;
+	if (
+		version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "agent_id")) ||
+		!isUuid(stringAt(sender, "session_id")) || !isUuid(stringAt(sender, "subject_id")) ||
+		!isUuid(stringAt(sender, "execution_id")) || !Number.isSafeInteger(senderGeneration) ||
+		(senderGeneration ?? 0) < 1 || !isUuid(target) || summary === undefined || content === undefined ||
+		published === undefined || !Number.isSafeInteger(published) || published < 0 ||
+		(correlation !== undefined && correlation !== null &&
+			(typeof correlation !== "string" || correlation.length === 0 ||
+				Buffer.byteLength(correlation, "utf8") > 256 || /\p{Cc}/u.test(correlation)))
+	) return undefined;
+	return value as HandoffSerialize;
+}
+
+function handoffReceiptAt(value: unknown): HandoffReceiptSerialize | undefined {
+	const version = numberAt(value, "version");
+	const handoffId = stringAt(value, "handoff_id");
+	const recipient = recordAt(value, "recipient");
+	const generation = numberAt(recipient, "execution_generation");
+	const received = numberAt(value, "received_at_unix_ms");
+	if (
+		version !== 1 || !isUuid(handoffId) || !isUuid(stringAt(recipient, "agent_id")) ||
+		!isUuid(stringAt(recipient, "session_id")) || !isUuid(stringAt(recipient, "subject_id")) ||
+		!isUuid(stringAt(recipient, "execution_id")) || !Number.isSafeInteger(generation) ||
+		(generation ?? 0) < 1 || received === undefined || !Number.isSafeInteger(received) || received < 0
+	) return undefined;
+	return value as HandoffReceiptSerialize;
+}
+
 /** A writer binding a channel or context reply hands back to its publisher. */
 function writerBinding(value: unknown): RadarWriterBinding | undefined {
 	const handle = stringAt(value, "handle");
@@ -662,6 +710,7 @@ const RADAR_MANAGED_IDENTITY_ENV = new Set([
 	"PI_RADAR_MANAGED_SUBJECT_ID",
 	"PI_RADAR_MANAGED_LAUNCH_ID",
 	"PI_RADAR_MANAGED_EXECUTION_GENERATION",
+	"PI_RADAR_MANAGED_PARENT_SUBJECT_ID",
 ]);
 
 /**
@@ -1015,6 +1064,12 @@ export type RadarClient = {
 	agentGet(agent_id: string): Promise<RadarResult<RadarAgentProcess>>;
 	observe(): Promise<RadarResult<RadarInventory>>;
 	/** Read the durable event journal after `after`, waiting at most `wait_ms`. */
+	communicationPublish(request: HandoffPublishParamsDeserialize & {
+		request_id: string;
+	}): Promise<RadarResult<{ handoff: HandoffSerialize; created: boolean }>>;
+	communicationInbox(request: { agent_id: string }): Promise<RadarResult<HandoffInboxSerialize>>;
+	communicationGet(request: { agent_id: string; handoff_id: string }): Promise<RadarResult<{ handoff: HandoffSerialize; receipt: HandoffReceiptSerialize | null }>>;
+	communicationAck(request: { agent_id: string; handoff_id: string }): Promise<RadarResult<{ receipt: HandoffReceiptSerialize; created: boolean }>>;
 	events(request: {
 		after: number;
 		epoch?: string;
@@ -1666,6 +1721,56 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 				return protocol("spawn.close reply carries no close outcome");
 			});
 		},
+		async communicationPublish(request) {
+			return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+				const answer = await call("communication.publish", {
+					sender_agent_id: request.sender_agent_id,
+					recipient_subject_id: request.recipient_subject_id,
+					...(request.correlation_id !== undefined ? { correlation_id: request.correlation_id } : {}),
+					summary: request.summary,
+					content: request.content,
+				}, request.request_id);
+				if (answer.ok === false) return answer;
+				const handoff = handoffAt(recordAt(answer.value, "handoff"));
+				const created = recordAt(answer.value, "created");
+				if (handoff === undefined || typeof created !== "boolean")
+					return protocol("communication.publish reply carries no handoff");
+				return { ok: true, value: { handoff, created } };
+			});
+		},
+		async communicationInbox(request) {
+			return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+				const answer = await call("communication.inbox", request);
+				if (answer.ok === false) return answer;
+				const handoffIds = recordAt(answer.value, "handoff_ids");
+				if (!Array.isArray(handoffIds) || handoffIds.some((id) => !isUuid(id)))
+					return protocol("communication.inbox reply carries malformed handoff IDs");
+				return { ok: true, value: answer.value as HandoffInboxSerialize };
+			});
+		},
+		async communicationGet(request) {
+			return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+				const answer = await call("communication.get", request);
+				if (answer.ok === false) return answer;
+				const handoff = handoffAt(recordAt(answer.value, "handoff"));
+				const receiptValue = recordAt(answer.value, "receipt");
+				const receipt = receiptValue === null ? null : handoffReceiptAt(receiptValue);
+				if (handoff === undefined || (receiptValue !== null && receipt === undefined))
+					return protocol("communication.get reply carries malformed content or receipt");
+				return { ok: true, value: { handoff, receipt: receipt ?? null } };
+			});
+		},
+		async communicationAck(request) {
+			return withContract(RADAR_COMMUNICATION_CONTRACT, async () => {
+				const answer = await call("communication.ack", request);
+				if (answer.ok === false) return answer;
+				const receipt = handoffReceiptAt(recordAt(answer.value, "receipt"));
+				const created = recordAt(answer.value, "created");
+				if (receipt === undefined || typeof created !== "boolean")
+					return protocol("communication.ack reply carries no receipt");
+				return { ok: true, value: { receipt, created } };
+			});
+		},
 		async events(request) {
 			if (
 				!Number.isSafeInteger(request.after) ||

package/extension/radar-communication.ts

@@ -0,0 +1,66 @@
+import type { HandoffInboxSerialize, HandoffSerialize, HandoffReceiptSerialize } from "./generated-contracts.ts";
+import type { RadarClient, RadarResult } from "./radar-client.ts";
+import type { RadarPublication } from "./radar-publication.ts";
+
+export type RadarHandoffPort = {
+	/** Publish to this managed execution's Radar-recorded parent. Retry an uncertain result with the same ID and bytes. */
+	publish(request: {
+		request_id: string;
+		correlation_id?: string;
+		summary: string;
+		content: string;
+	}): Promise<RadarResult<{ handoff: HandoffSerialize; created: boolean }>>;
+	/** Durable inbox scan for this process's managed subject. Notifications are hints; callers can always rescan. */
+	inbox(): Promise<RadarResult<HandoffInboxSerialize>>;
+	/** Retrieve the full immutable content even after it has been acknowledged. */
+	get(handoff_id: string): Promise<RadarResult<{ handoff: HandoffSerialize; receipt: HandoffReceiptSerialize | null }>>;
+	/** Call only after the consumer durably recorded the retrieved payload. */
+	ack(handoff_id: string): Promise<RadarResult<{ receipt: HandoffReceiptSerialize; created: boolean }>>;
+};
+
+/**
+ * Bind handoff operations to this Pi process's Radar registration and the
+ * parent subject injected from its accepted managed-launch metadata.
+ */
+export function createRadarHandoffPort(
+	client: RadarClient,
+	publication: Pick<RadarPublication, "subject">,
+	parentSubjectId: () => string | undefined = () => process.env.PI_RADAR_MANAGED_PARENT_SUBJECT_ID,
+): RadarHandoffPort {
+	async function agentId(): Promise<RadarResult<string>> {
+		const subject = await publication.subject();
+		return subject === undefined
+			? { ok: false, code: "absent", message: "this process has no current Radar registration" }
+			: { ok: true, value: subject.agent_id };
+	}
+
+	return {
+		async publish(request) {
+			const identity = await agentId();
+			if (identity.ok === false) return identity;
+			const parent = parentSubjectId();
+			if (parent === undefined)
+				return { ok: false, code: "absent", message: "this managed execution has no Radar parent subject" };
+			return client.communicationPublish({
+				...request,
+				sender_agent_id: identity.value,
+				recipient_subject_id: parent,
+			});
+		},
+		async inbox() {
+			const identity = await agentId();
+			if (identity.ok === false) return identity;
+			return client.communicationInbox({ agent_id: identity.value });
+		},
+		async get(handoff_id) {
+			const identity = await agentId();
+			if (identity.ok === false) return identity;
+			return client.communicationGet({ agent_id: identity.value, handoff_id });
+		},
+		async ack(handoff_id) {
+			const identity = await agentId();
+			if (identity.ok === false) return identity;
+			return client.communicationAck({ agent_id: identity.value, handoff_id });
+		},
+	};
+}

package/extension/radar-launch.ts

@@ -64,9 +64,11 @@ export type LaunchMailbox<State extends LaunchState> = {
  * different leaves the launch unresolved rather than placed.
  */
 
-/** The exact parent this launch may use, and nothing inferred about it. */
+/** The exact managed parent this launch may use, and nothing inferred about it. */
 export type RadarLaunchParent = {
 	agent_id: string;
+	/** Stable subject from this process's current Radar registration. */
+	subject_id: string;
 	location?: RadarLocation;
 };
 
@@ -395,6 +397,10 @@ export async function launchRadarWorker<State extends LaunchState>(
 		return refusedLaunch(
 			"the launch has no exact parent registration to spawn under",
 		);
+	if (!isUuid(launch.parent.subject_id))
+		return refusedLaunch(
+			"the launch has no managed Radar subject for its parent",
+		);
 	// A spawn is created under the pane its parent registered, and this port
 	// registers no location it was not given: without one there is nothing to
 	// place the child beside, and a name or session lookup is not a substitute.
@@ -408,6 +414,7 @@ export async function launchRadarWorker<State extends LaunchState>(
 		parent: launch.parent.agent_id,
 		parent_session_id: launch.parent_session_id,
 		executable: launch.executable,
+		managed: { parent_subject_id: launch.parent.subject_id },
 		argv: launch.argv,
 		...(launch.cwd !== "" ? { cwd: launch.cwd } : {}),
 		...(Object.keys(launch.env).length > 0 ? { env: launch.env } : {}),

package/extension/radar-publication.ts

@@ -1318,6 +1318,8 @@ export type RadarPublication = {
 /** What a process's own registration resolved to, and where it says it is. */
 export type RadarSubject = {
 	agent_id: string;
+	/** Stable managed logical subject, present only for a Radar-issued launch. */
+	subject_id?: string;
 	location?: RadarLocation;
 };
 
@@ -1716,8 +1718,10 @@ function createRadarPublicationInner(
 			const record = await ensureRegistration();
 			if (record === undefined) return undefined;
 			const location = record.registration.location;
+			const subjectId = process.env.PI_RADAR_MANAGED_SUBJECT_ID;
 			return {
 				agent_id: agentId,
+				...(subjectId !== undefined ? { subject_id: subjectId } : {}),
 				...(location !== undefined ? { location } : {}),
 			};
 		},

package/extension/radar-runtime.ts

@@ -1,14 +1,17 @@
 import type { RadarExecutionAdapter } from "./radar-execution.ts";
+import type { RadarHandoffPort } from "./radar-communication.ts";
 import type { RadarPublication } from "./radar-publication.ts";
 
 /** The event channel through which Pi extensions obtain the baseline runtime. */
 export const RADAR_RUNTIME_REQUEST = "pi-radar/runtime-request";
-export const RADAR_RUNTIME_VERSION = 1 as const;
+export const RADAR_RUNTIME_VERSION = 2 as const;
 
 /** The sole baseline publisher's session-scoped runtime, shared with consumers. */
 export type RadarRuntimeServices = {
 	/** The one baseline publication; Herdsman contributes through its channels. */
 	publication: RadarPublication;
+	/** Durable handoffs bound to this process's registration and managed parent. */
+	communication: RadarHandoffPort;
 	execution: RadarExecutionAdapter;
 };
 

package/index.ts

@@ -1,4 +1,5 @@
 export * as client from "./extension/radar-client.ts";
+export * as communication from "./extension/radar-communication.ts";
 export * as execution from "./extension/radar-execution.ts";
 export * as inspection from "./extension/radar-inspection.ts";
 export * as launch from "./extension/radar-launch.ts";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pi-radar",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
-  "description": "Radar daemon client, publication, execution, location, launch and inspection surface for Pi extensions.",
+  "description": "Radar daemon client, communication, publication, execution, location, launch and inspection surface for Pi extensions.",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22.19.0"
@@ -25,6 +25,10 @@
       "types": "./extension/radar-client.ts",
       "import": "./dist/extension/radar-client.js"
     },
+    "./communication": {
+      "types": "./extension/radar-communication.ts",
+      "import": "./dist/extension/radar-communication.js"
+    },
     "./execution": {
       "types": "./extension/radar-execution.ts",
       "import": "./dist/extension/radar-execution.js"
@@ -67,6 +71,7 @@
     "schema/public/v1/**",
     "extension/generated-contracts.ts",
     "extension/radar-client.ts",
+    "extension/radar-communication.ts",
     "extension/radar-execution.ts",
     "extension/radar-inspection.ts",
     "extension/radar-launch.ts",
@@ -77,10 +82,10 @@
     "extension/baseline.ts"
   ],
   "scripts": {
-    "build": "esbuild index.ts extension/generated-contracts.ts extension/radar-client.ts extension/radar-execution.ts extension/radar-inspection.ts extension/radar-launch.ts extension/radar-location.ts extension/radar-publication.ts extension/radar-session-marker.ts extension/radar-runtime.ts extension/baseline.ts --outbase=. --outdir=dist --bundle --platform=node --format=esm --target=node22",
+    "build": "esbuild index.ts extension/generated-contracts.ts extension/radar-client.ts extension/radar-communication.ts extension/radar-execution.ts extension/radar-inspection.ts extension/radar-launch.ts extension/radar-location.ts extension/radar-publication.ts extension/radar-session-marker.ts extension/radar-runtime.ts extension/baseline.ts --outbase=. --outdir=dist --bundle --platform=node --format=esm --target=node22",
     "generate:contracts": "node tools/generate-contracts.mjs",
     "check:contracts": "node tools/generate-contracts.mjs --check",
-    "typecheck:contracts": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext --allowImportingTsExtensions --types node index.ts extension/baseline.ts extension/generated-contracts.ts extension/generated-contracts.typecheck.ts extension/radar-client.ts extension/radar-execution.ts extension/radar-publication.ts extension/radar-session-marker.ts extension/radar-session-marker.test.ts extension/radar-runtime.ts extension/radar-runtime.test.ts",
+    "typecheck:contracts": "tsc --noEmit --strict --skipLibCheck --target ES2022 --module NodeNext --moduleResolution NodeNext --allowImportingTsExtensions --types node index.ts extension/baseline.ts extension/generated-contracts.ts extension/generated-contracts.typecheck.ts extension/radar-client.ts extension/radar-communication.ts extension/radar-execution.ts extension/radar-launch.test.ts extension/radar-publication.ts extension/radar-session-marker.ts extension/radar-session-marker.test.ts extension/radar-runtime.ts extension/radar-runtime.test.ts",
     "prepack": "npm run build",
     "test": "npm run check:contracts && npm run typecheck:contracts && node --experimental-strip-types --test extension/*.test.ts"
   },

package/schema/public/v1/handoff-inbox.deserialize.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "A bounded inbox page by stable handoff ID. Payloads are fetched one at a\ntime with `communication.get`, keeping each response within the wire bound.",
+  "properties": {
+    "handoff_ids": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "handoff_ids"
+  ],
+  "title": "handoff-inbox-deserialize",
+  "type": "object"
+}

package/schema/public/v1/handoff-inbox.serialize.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "A bounded inbox page by stable handoff ID. Payloads are fetched one at a\ntime with `communication.get`, keeping each response within the wire bound.",
+  "properties": {
+    "handoff_ids": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "handoff_ids"
+  ],
+  "title": "handoff-inbox-serialize",
+  "type": "object"
+}

package/schema/public/v1/handoff-publish-params.deserialize.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Inputs for publishing an immutable handoff. The wire request ID carries the\nstable communication identity; the daemon derives the sender execution.",
+  "properties": {
+    "content": {
+      "type": "string"
+    },
+    "correlation_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "recipient_subject_id": {
+      "type": "string"
+    },
+    "sender_agent_id": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "sender_agent_id",
+    "recipient_subject_id",
+    "summary",
+    "content"
+  ],
+  "title": "handoff-publish-params-deserialize",
+  "type": "object"
+}

package/schema/public/v1/handoff-publish-params.serialize.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Inputs for publishing an immutable handoff. The wire request ID carries the\nstable communication identity; the daemon derives the sender execution.",
+  "properties": {
+    "content": {
+      "type": "string"
+    },
+    "correlation_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "recipient_subject_id": {
+      "type": "string"
+    },
+    "sender_agent_id": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "sender_agent_id",
+    "recipient_subject_id",
+    "summary",
+    "content"
+  ],
+  "title": "handoff-publish-params-serialize",
+  "type": "object"
+}

package/schema/public/v1/handoff-receipt.deserialize.schema.json

@@ -0,0 +1,66 @@
+{
+  "$defs": {
+    "HandoffIdentity": {
+      "additionalProperties": false,
+      "description": "The current managed Pi execution that published or received a handoff.\n`subject_id` is stable across verified successors; `execution_id` and\ngeneration identify the exact execution that took the action.",
+      "properties": {
+        "agent_id": {
+          "type": "string"
+        },
+        "execution_generation": {
+          "format": "uint32",
+          "maximum": 4294967295,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "execution_id": {
+          "type": "string"
+        },
+        "session_id": {
+          "type": "string"
+        },
+        "subject_id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "agent_id",
+        "session_id",
+        "subject_id",
+        "execution_id",
+        "execution_generation"
+      ],
+      "type": "object"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Durable recipient-consumer receipt, stored separately from immutable content.",
+  "properties": {
+    "handoff_id": {
+      "type": "string"
+    },
+    "received_at_unix_ms": {
+      "format": "uint64",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "recipient": {
+      "$ref": "#/$defs/HandoffIdentity"
+    },
+    "version": {
+      "format": "uint32",
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "version",
+    "handoff_id",
+    "recipient",
+    "received_at_unix_ms"
+  ],
+  "title": "handoff-receipt-deserialize",
+  "type": "object"
+}

package/schema/public/v1/handoff-receipt.serialize.schema.json

@@ -0,0 +1,66 @@
+{
+  "$defs": {
+    "HandoffIdentity": {
+      "additionalProperties": false,
+      "description": "The current managed Pi execution that published or received a handoff.\n`subject_id` is stable across verified successors; `execution_id` and\ngeneration identify the exact execution that took the action.",
+      "properties": {
+        "agent_id": {
+          "type": "string"
+        },
+        "execution_generation": {
+          "format": "uint32",
+          "maximum": 4294967295,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "execution_id": {
+          "type": "string"
+        },
+        "session_id": {
+          "type": "string"
+        },
+        "subject_id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "agent_id",
+        "session_id",
+        "subject_id",
+        "execution_id",
+        "execution_generation"
+      ],
+      "type": "object"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Durable recipient-consumer receipt, stored separately from immutable content.",
+  "properties": {
+    "handoff_id": {
+      "type": "string"
+    },
+    "received_at_unix_ms": {
+      "format": "uint64",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "recipient": {
+      "$ref": "#/$defs/HandoffIdentity"
+    },
+    "version": {
+      "format": "uint32",
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "version",
+    "handoff_id",
+    "recipient",
+    "received_at_unix_ms"
+  ],
+  "title": "handoff-receipt-serialize",
+  "type": "object"
+}