pi-radar 0.5.0 → 0.6.0

package/extension/radar-client.ts

@@ -11,6 +11,8 @@ import type {
 	HandoffSerialize,
 	ManagedLaunchMetadataDeserialize,
 	SpawnExitObservationSerialize,
+	SpawnListParamsDeserialize,
+	SpawnListPageSerialize,
 } from "./generated-contracts.ts";
 
 /**
@@ -30,12 +32,16 @@ import type {
  * served under the old name.
  */
 export const RADAR_PROTOCOL_VERSION = 2;
-/** The minimum daemon wire revision this client understands. */
-export const RADAR_MINIMUM_REVISION = 3;
+/**
+ * Revision 5 names attempts by claim_id and requires exact-claim controls.
+ * Earlier daemons expose different identity fields; require a coordinated update.
+ */
+export const RADAR_MINIMUM_REVISION = 5;
 /** Public daemon contracts this client may preflight. */
 export const RADAR_REGISTRY_CONTRACT = "registry.v1";
 export const RADAR_REGISTRY_FACTS_CONTRACT = "registry.facts.v1";
 export const RADAR_SPAWN_CONTRACT = "spawn.v1";
+export const RADAR_SPAWN_LIST_CONTRACT = "spawn.list.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";
@@ -558,7 +564,6 @@ 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");
@@ -569,8 +574,7 @@ function handoffAt(value: unknown): HandoffSerialize | undefined {
 	if (
 		version !== 1 || !isUuid(id) || !isUuid(stringAt(sender, "registration_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 ||
+		!isUuid(stringAt(sender, "claim_id")) || !isUuid(target) || summary === undefined || content === undefined ||
 		published === undefined || !Number.isSafeInteger(published) || published < 0 ||
 		(correlation !== undefined && correlation !== null &&
 			(typeof correlation !== "string" || correlation.length === 0 ||
@@ -583,13 +587,11 @@ 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, "registration_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
+		!isUuid(stringAt(recipient, "claim_id")) || received === undefined || !Number.isSafeInteger(received) || received < 0
 	) return undefined;
 	return value as HandoffReceiptSerialize;
 }
@@ -1099,6 +1101,8 @@ export type RadarClient = {
 		env?: Record<string, string>;
 		managed?: RadarManagedLaunchMetadata;
 	}): Promise<RadarResult<RadarSpawnEdge>>;
+	/** List launches owned by this client's registered process. */
+	spawnList(request: Pick<SpawnListParamsDeserialize, "after" | "limit">): Promise<RadarResult<SpawnListPageSerialize>>;
 	spawnGet(request_id: string): Promise<RadarResult<RadarSpawnTopology>>;
 	/** The registered child's process verdict, read from its immutable claim. */
 	agentGet(registration_id: string): Promise<RadarResult<RadarAgentProcess>>;
@@ -1442,6 +1446,7 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 			};
 		return answer;
 	};
+	let processRegistrationId: string | undefined;
 	let handshake: Promise<RadarResult<RadarHandshake>> | undefined;
 	const negotiated = async (): Promise<RadarResult<RadarHandshake>> => {
 		handshake ??= probe();
@@ -1547,6 +1552,7 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 				const record = (answer.value as { registration?: unknown }).registration;
 				const agentId = stringAt(record, "registration_id");
 				if (!isUuid(agentId)) return protocol("registration reply carries no registration_id");
+				processRegistrationId = agentId;
 				return { ok: true, value: { registration_id: agentId } };
 			});
 		},
@@ -1700,6 +1706,32 @@ export function createRadarClient(options: RadarClientOptions = {}): RadarClient
 				},
 			);
 		},
+		async spawnList(request) {
+			const registrationId = processRegistrationId;
+			if (registrationId === undefined)
+				return { ok: false, code: "refused", message: "spawn.list requires this client's process registration" };
+			return withContract(RADAR_SPAWN_LIST_CONTRACT, async () => {
+				const params: SpawnListParamsDeserialize = {
+					registration_id: registrationId,
+					...(request.after !== undefined ? { after: request.after } : {}),
+					...(request.limit !== undefined ? { limit: request.limit } : {}),
+				};
+				const answer = await call("spawn.list", { ...params });
+				if (answer.ok === false) return answer;
+				const spawns = recordAt(answer.value, "spawns");
+				const next = recordAt(answer.value, "next");
+				if (!Array.isArray(spawns) || (next != null && !isUuid(next)))
+					return protocol("spawn.list reply carries no valid page");
+				for (const spawn of spawns) {
+					const decoded = spawnTopology(spawn);
+					if (decoded.ok === false) return decoded;
+					if (typeof recordAt(spawn, "version") !== "number" || typeof recordAt(spawn, "recorded_at") !== "string" ||
+						!["unbound", "bound", "unresolved"].includes(String(recordAt(spawn, "state"))))
+						return protocol("spawn.list reply carries an incomplete topology");
+				}
+				return { ok: true, value: answer.value as SpawnListPageSerialize };
+			});
+		},
 		async spawnGet(requestId) {
 			if (!isUuid(requestId))
 				return {

package/extension/radar-publication.ts

@@ -975,6 +975,7 @@ function createPresenceReporter(input: PresenceReporterInput): RadarPresenceRepo
 	type State = {
 		version: 2;
 		claim_id: string;
+	initial_load?: boolean;
 		session: string;
 		registration_id?: string;
 		subject_id?: string;
@@ -1032,6 +1033,13 @@ function createPresenceReporter(input: PresenceReporterInput): RadarPresenceRepo
 			await releasePending();
 			const registration = await input.registration();
 			if (!registration?.process || state !== claim || stopped) return undefined;
+			// The first load spends the pre-minted launch claim. Reloads get a fresh
+			// claim; they must not reuse the released launch credential.
+			if (claim.initial_load) {
+				if (registration.spawn_token) claim.claim_id = registration.spawn_token;
+				claim.initial_load = false;
+				if (!save()) return undefined;
+			}
 			const answer = await client.presence({
 				...registration, process: registration.process,
 				session_id: claim.session, claim_id: claim.claim_id,
@@ -1071,7 +1079,7 @@ function createPresenceReporter(input: PresenceReporterInput): RadarPresenceRepo
 				releases.push({ registration_id: state.registration_id, claim_id: state.claim_id });
 			}
 			standing = undefined;
-			state = { version: 2, session, claim_id: randomUUID(), releases };
+			state = { version: 2, session, claim_id: randomUUID(), initial_load: state === undefined, releases };
 			save(); stopped = false;
 			void ensure();
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-radar",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Radar daemon client, communication, publication, execution, location, launch and inspection surface for Pi extensions.",
   "license": "Apache-2.0",

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

@@ -4,13 +4,7 @@
       "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": {
-        "execution_generation": {
-          "format": "uint32",
-          "maximum": 4294967295,
-          "minimum": 1,
-          "type": "integer"
-        },
-        "execution_id": {
+        "claim_id": {
           "type": "string"
         },
         "registration_id": {
@@ -27,8 +21,7 @@
         "registration_id",
         "session_id",
         "subject_id",
-        "execution_id",
-        "execution_generation"
+        "claim_id"
       ],
       "type": "object"
     }

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

@@ -4,13 +4,7 @@
       "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": {
-        "execution_generation": {
-          "format": "uint32",
-          "maximum": 4294967295,
-          "minimum": 1,
-          "type": "integer"
-        },
-        "execution_id": {
+        "claim_id": {
           "type": "string"
         },
         "registration_id": {
@@ -27,8 +21,7 @@
         "registration_id",
         "session_id",
         "subject_id",
-        "execution_id",
-        "execution_generation"
+        "claim_id"
       ],
       "type": "object"
     }

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

@@ -4,13 +4,7 @@
       "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": {
-        "execution_generation": {
-          "format": "uint32",
-          "maximum": 4294967295,
-          "minimum": 1,
-          "type": "integer"
-        },
-        "execution_id": {
+        "claim_id": {
           "type": "string"
         },
         "registration_id": {
@@ -27,8 +21,7 @@
         "registration_id",
         "session_id",
         "subject_id",
-        "execution_id",
-        "execution_generation"
+        "claim_id"
       ],
       "type": "object"
     }

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

@@ -4,13 +4,7 @@
       "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": {
-        "execution_generation": {
-          "format": "uint32",
-          "maximum": 4294967295,
-          "minimum": 1,
-          "type": "integer"
-        },
-        "execution_id": {
+        "claim_id": {
           "type": "string"
         },
         "registration_id": {
@@ -27,8 +21,7 @@
         "registration_id",
         "session_id",
         "subject_id",
-        "execution_id",
-        "execution_generation"
+        "claim_id"
       ],
       "type": "object"
     }

package/schema/public/v1/observation-get-response.deserialize.schema.json

@@ -1037,6 +1037,9 @@
             }
           ]
         },
+        "claim_id": {
+          "type": "string"
+        },
         "identity_unresolved": {
           "type": "boolean"
         },
@@ -1067,6 +1070,7 @@
       },
       "required": [
         "subject_id",
+        "claim_id",
         "process",
         "identity_unresolved",
         "metadata",
@@ -2375,6 +2379,12 @@
             "null"
           ]
         },
+        "claim_id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "parent": {
           "type": "string"
         },
@@ -2383,12 +2393,6 @@
         },
         "state": {
           "$ref": "#/$defs/SpawnState"
-        },
-        "subject_id": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [

package/schema/public/v1/observation-get-response.serialize.schema.json

@@ -1096,6 +1096,9 @@
             }
           ]
         },
+        "claim_id": {
+          "type": "string"
+        },
         "identity_unresolved": {
           "type": "boolean"
         },
@@ -1126,6 +1129,7 @@
       },
       "required": [
         "subject_id",
+        "claim_id",
         "process",
         "identity_unresolved",
         "metadata",
@@ -2491,6 +2495,12 @@
             "null"
           ]
         },
+        "claim_id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "parent": {
           "type": "string"
         },
@@ -2499,18 +2509,12 @@
         },
         "state": {
           "$ref": "#/$defs/SpawnState"
-        },
-        "subject_id": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [
         "parent",
         "request_id",
-        "subject_id",
+        "claim_id",
         "child_source",
         "child_incarnation",
         "state"

package/schema/public/v1/observation-snapshot.deserialize.schema.json

@@ -1037,6 +1037,9 @@
             }
           ]
         },
+        "claim_id": {
+          "type": "string"
+        },
         "identity_unresolved": {
           "type": "boolean"
         },
@@ -1067,6 +1070,7 @@
       },
       "required": [
         "subject_id",
+        "claim_id",
         "process",
         "identity_unresolved",
         "metadata",
@@ -2240,6 +2244,12 @@
             "null"
           ]
         },
+        "claim_id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "parent": {
           "type": "string"
         },
@@ -2248,12 +2258,6 @@
         },
         "state": {
           "$ref": "#/$defs/SpawnState"
-        },
-        "subject_id": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [

package/schema/public/v1/observation-snapshot.serialize.schema.json

@@ -1096,6 +1096,9 @@
             }
           ]
         },
+        "claim_id": {
+          "type": "string"
+        },
         "identity_unresolved": {
           "type": "boolean"
         },
@@ -1126,6 +1129,7 @@
       },
       "required": [
         "subject_id",
+        "claim_id",
         "process",
         "identity_unresolved",
         "metadata",
@@ -2347,6 +2351,12 @@
             "null"
           ]
         },
+        "claim_id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "parent": {
           "type": "string"
         },
@@ -2355,18 +2365,12 @@
         },
         "state": {
           "$ref": "#/$defs/SpawnState"
-        },
-        "subject_id": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [
         "parent",
         "request_id",
-        "subject_id",
+        "claim_id",
         "child_source",
         "child_incarnation",
         "state"