pi-radar 0.9.0 → 0.11.0

package/extension/radar-publication.ts

@@ -318,7 +318,7 @@ type PendingPublish = {
 
 type ChannelRecord = {
 	version: typeof RADAR_PUBLICATION_VERSION;
-	registration_id: string;
+	target_id: string;
 	channel: RadarChannel;
 	publisher: RadarPublisherIdentity;
 	writer?: { handle: string; generation: number };
@@ -353,10 +353,11 @@ type ContextRecord = {
 	diagnostic?: string;
 };
 
-/** What a managed child tells its owner: which exact subject to publish about. */
+/** What a managed child tells its owner: which subject to address, once granted. */
 export type RadarChildBinding = {
 	version: typeof RADAR_PUBLICATION_VERSION;
 	registration_id: string;
+	subject_id?: string;
 	incarnation: string;
 	run: string;
 	owner: string;
@@ -571,36 +572,6 @@ function pendingAt(
 	return { sequence, snapshot, lease_ms: lease, observed_at: observed };
 }
 
-const CONTEXT_PENDING_KEYS = "lease_ms,observed_at,sequence,session";
-const CONTEXT_ACCEPTED_KEYS = "lease_ms,observed_at,sent_at,sequence,session";
-// Records written before session-bound management also carry a launch-identity
-// marker. It is read past and never used: the attached subject is the identity.
-const CONTEXT_PENDING_LEGACY_KEYS = "launch_identity,lease_ms,observed_at,sequence,session";
-const CONTEXT_ACCEPTED_LEGACY_KEYS = "launch_identity,lease_ms,observed_at,sent_at,sequence,session";
-
-/** The reported session, or `undefined` when the field is not one of the two. */
-function sessionAt(value: unknown): string | null | undefined {
-	if (typeof value !== "object" || value === null) return undefined;
-	const found = (value as Record<string, unknown>).session;
-	if (found === null) return null;
-	return typeof found === "string" ? found : undefined;
-}
-
-function contextReportAt(
-	value: unknown,
-	keys: string,
-	legacyKeys: string,
-): ContextReport | undefined {
-	if (!exactKeys(value, keys) && !exactKeys(value, legacyKeys)) return undefined;
-	const sequence = numberAt(value, "sequence");
-	const lease = numberAt(value, "lease_ms");
-	const observed = textAt(value, "observed_at");
-	const session = sessionAt(value);
-	if (sequence === undefined || sequence < 1) return undefined;
-	if (lease === undefined || observed === undefined || session === undefined)
-		return undefined;
-	return { sequence, session, lease_ms: lease, observed_at: observed };
-}
 
 export type RadarFactsWriter = Omit<RadarChannelWriter, "update"> & {
 	update(snapshot: RadarFactsSnapshot): void;
@@ -652,16 +623,21 @@ function createChannelWriter(input: ChannelWriterInput): RadarChannelWriter {
 	function blank(agentId: string): ChannelRecord {
 		return {
 			version: RADAR_PUBLICATION_VERSION,
-			registration_id: agentId,
+			target_id: agentId,
 			channel,
 			publisher,
 			sequence: 0,
 		};
 	}
 
+	/** An assignment names a child subject; every other channel names a process. */
+	function addressed(target: string): { registration_id: string } | { subject_id: string } {
+		return channel === "assignment" ? { subject_id: target } : { registration_id: target };
+	}
+
 	function loadRecord(): ChannelRecord {
 		const value = store.read(recordName);
-		const agentId = textAt(value, "registration_id");
+		const agentId = textAt(value, "target_id");
 		const storedPublisher = recordAt(value, "publisher");
 		// A record written for another channel or publisher is not this writer's
 		// binding: adopting it would publish under someone else's identity.
@@ -689,7 +665,7 @@ function createChannelWriter(input: ChannelWriterInput): RadarChannelWriter {
 		const sentAt = numberAt(acceptedValue, "sent_at");
 		return {
 			version: RADAR_PUBLICATION_VERSION,
-			registration_id: agentId,
+			target_id: agentId,
 			channel,
 			publisher,
 			...(handle !== undefined && generation !== undefined
@@ -757,18 +733,14 @@ function createChannelWriter(input: ChannelWriterInput): RadarChannelWriter {
 		// identical immutable content that was persisted with it.
 		const agentId = await input.subject(recovering);
 		if (agentId === undefined) return false;
-		if (record.registration_id !== agentId) {
+		if (record.target_id !== agentId) {
 			// A different subject incarnation is a different channel: the previous
 			// binding, sequence and unresolved request do not apply to it, so the
 			// next drain publishes a complete snapshot instead of replaying one.
 			record = blank(agentId);
 			save();
 		}
-		const answer = await client.acquire({
-			registration_id: agentId,
-			channel,
-			publisher,
-		});
+		const answer = await client.acquire({...addressed(agentId), channel, publisher});
 		if (answer.ok === false) {
 			if (answer.code === "not_found") {
 				// The daemon has lost this subject. The identical immutable content is
@@ -805,15 +777,12 @@ function createChannelWriter(input: ChannelWriterInput): RadarChannelWriter {
 	async function send(pending: PendingPublish): Promise<void> {
 		const writer = record.writer;
 		if (writer === undefined) return;
-		const answer = await client.publish({
-			registration_id: record.registration_id,
-			channel,
+		const answer = await client.publish({...addressed(record.target_id), channel,
 			writer_handle: writer.handle,
 			sequence: pending.sequence,
 			lease_ms: pending.lease_ms,
 			observed_at: pending.observed_at,
-			snapshot: pending.snapshot,
-		});
+			snapshot: pending.snapshot,});
 		if (answer.ok === true) {
 			recovering = false;
 			record.sequence = Math.max(record.sequence, answer.value.sequence);
@@ -919,10 +888,9 @@ function createChannelWriter(input: ChannelWriterInput): RadarChannelWriter {
 			stopPump();
 			const writer = record.writer;
 			if (writer === undefined) return;
-			const agentId = record.registration_id;
+			const agentId = record.target_id;
 			try {
-				void client
-					.retire({ registration_id: agentId, channel, writer_handle: writer.handle })
+				void client.retire({...addressed(agentId), channel, writer_handle: writer.handle})
 					.then((answer) => {
 				if (answer.ok === true) {
 						try {
@@ -970,6 +938,8 @@ type PresenceReporterInput = {
 	scheduler: RadarScheduler;
 	recordName: string;
 	registration(): Promise<RadarRegistration | undefined>;
+	/** The subject Radar granted this process's session, when it granted one. */
+	granted?(subjectId: string): void;
 	heartbeatMs: number;
 };
 
@@ -1052,6 +1022,7 @@ function createPresenceReporter(input: PresenceReporterInput): RadarPresenceRepo
 			}
 			claim.registration_id = answer.value.registration_id;
 			claim.subject_id = answer.value.standing === "granted" ? answer.value.subject_id ?? undefined : undefined;
+			if (claim.subject_id !== undefined) input.granted?.(claim.subject_id);
 			standing = answer.value.standing === "granted"
 				? { state: "managed", subject_id: claim.subject_id! }
 				: answer.value.standing === "duplicate"
@@ -1365,7 +1336,7 @@ function createRadarPublicationInner(
 			agentId = registered;
 			processRecord = { ...record, registration_id: agentId };
 			store.write(registrationName, processRecord);
-			if (options.binding !== undefined) writeBinding(options.binding);
+			if (options.binding !== undefined) writeBinding(options.binding, grantedSubject());
 			return agentId;
 		})();
 		try {
@@ -1375,16 +1346,23 @@ function createRadarPublicationInner(
 		}
 	}
 
+	/** The subject Radar granted this process, once presence has been answered. */
+	function grantedSubject(): string | undefined {
+		const standing = presence.management();
+		return standing?.state === "managed" ? standing.subject_id : undefined;
+	}
+
 	function writeBinding(binding: {
 		key: string;
 		run: string;
 		owner: string;
 		label: string;
-	}): void {
+	}, subjectId?: string): void {
 		if (agentId === undefined) return;
 		store.write(`bindings/${binding.key}.json`, {
 			version: RADAR_PUBLICATION_VERSION,
 			registration_id: agentId,
+			...(subjectId !== undefined ? { subject_id: subjectId } : {}),
 			incarnation,
 			run: binding.run,
 			owner: binding.owner,
@@ -1426,6 +1404,9 @@ function createRadarPublicationInner(
 				...(launchRegistrationId ? { registration_id: launchRegistrationId } : {}),
 			};
 		},
+		granted: (subjectId) => {
+			if (options.binding !== undefined) writeBinding(options.binding, subjectId);
+		},
 		heartbeatMs: options.heartbeatMs ?? RADAR_HEARTBEAT_MS,
 	});
 
@@ -1460,8 +1441,7 @@ function createRadarPublicationInner(
 					channel: "assignment",
 					publisher: publisher("herdsman-owner", reportingOwner),
 					codec: assignmentCodec,
-					// The owner publishes about a subject it did not register: the exact
-					// registration_id from the child's sidecar is the whole correlation.
+					// Radar owns this assignment across the child's process replacements.
 					subject: async () => target,
 					leaseMs: options.leaseMs ?? RADAR_LEASE_MS,
 					heartbeatMs: options.heartbeatMs ?? RADAR_HEARTBEAT_MS,
@@ -1482,6 +1462,7 @@ function createRadarPublicationInner(
 				return undefined;
 			}
 			const bound = textAt(value, "registration_id");
+			const subjectId = textAt(value, "subject_id");
 			const boundIncarnation = textAt(value, "incarnation");
 			const run = textAt(value, "run");
 			const owner = textAt(value, "owner");
@@ -1491,6 +1472,7 @@ function createRadarPublicationInner(
 			// identity is ever used as a channel target.
 			if (
 				!isUuid(bound) ||
+				(subjectId !== undefined && !isUuid(subjectId)) ||
 				!isUuid(boundIncarnation) ||
 				run === undefined ||
 				owner === undefined ||
@@ -1501,6 +1483,7 @@ function createRadarPublicationInner(
 			return {
 				version: RADAR_PUBLICATION_VERSION,
 				registration_id: bound,
+				...(subjectId !== undefined ? { subject_id: subjectId } : {}),
 				incarnation: boundIncarnation,
 				run,
 				owner,

package/extension/radar-runtime.ts

@@ -5,7 +5,7 @@ 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 = 3 as const;
+export const RADAR_RUNTIME_VERSION = 5 as const;
 
 /** The sole baseline publisher's session-scoped runtime, shared with consumers. */
 export type RadarRuntimeServices = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-radar",
-  "version": "0.9.0",
+  "version": "0.11.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/observation-get-response.deserialize.schema.json

@@ -732,7 +732,7 @@
           "type": "array"
         },
         "context_usage": {
-          "description": "The percentage a Herdr token states, percent sign included. It carries no\ncounts, so it is never presented as a typed window.",
+          "description": "The percentage a background-task token states, percent sign included. It carries no\ncounts, so it is never presented as a typed window.",
           "type": [
             "string",
             "null"
@@ -757,7 +757,7 @@
           ]
         },
         "label": {
-          "description": "A managed worker's runtime label: the name its owner and its siblings\nuse for it, and the only faithful source for a worker's name. Herdr's\nown agent name truncates it and its title welds it to the task.",
+          "description": "A managed worker's runtime label: the name its owner and its siblings\nuse for it, and the only faithful source for a worker's name. The backend's\nown agent name truncates it and its title welds it to the task.",
           "type": [
             "string",
             "null"
@@ -893,12 +893,6 @@
         },
         "subject_id": {
           "type": "string"
-        },
-        "successor": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [
@@ -968,7 +962,7 @@
       "type": "object"
     },
     "Location": {
-      "description": "Connector-scoped runtime location: Herdr workspace, tab and pane identifiers.\n\nPane identity is a runtime location detail; it is never an agent identity.",
+      "description": "Backend-scoped runtime location: workspace, tab and pane identifiers.\n\nPane identity is a runtime location detail; it is never an agent identity.",
       "properties": {
         "pane_id": {
           "type": "string"
@@ -1040,9 +1034,6 @@
         "claim_id": {
           "type": "string"
         },
-        "identity_unresolved": {
-          "type": "boolean"
-        },
         "metadata": {
           "$ref": "#/$defs/ManagedMetadata"
         },
@@ -1060,19 +1051,12 @@
         },
         "subject_id": {
           "type": "string"
-        },
-        "successor": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [
         "subject_id",
         "claim_id",
         "process",
-        "identity_unresolved",
         "metadata",
         "state"
       ],
@@ -1631,9 +1615,6 @@
         "channel": {
           "$ref": "#/$defs/Channel"
         },
-        "registration_id": {
-          "type": "string"
-        },
         "snapshot": {
           "anyOf": [
             {
@@ -1655,7 +1636,6 @@
       },
       "required": [
         "version",
-        "registration_id",
         "channel",
         "writer"
       ],
@@ -2464,7 +2444,7 @@
       ]
     },
     "Tab": {
-      "description": "A Herdr tab within a workspace; shown as location detail, not a tree level.",
+      "description": "A tab within a workspace; shown as location detail, not a tree level.",
       "properties": {
         "label": {
           "type": [
@@ -2690,7 +2670,7 @@
       ]
     },
     "Workspace": {
-      "description": "A Herdr workspace: the first display grouping for the fleet tree.",
+      "description": "A workspace: the first display grouping for the fleet tree.",
       "properties": {
         "label": {
           "type": [

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

@@ -758,7 +758,7 @@
           "type": "array"
         },
         "context_usage": {
-          "description": "The percentage a Herdr token states, percent sign included. It carries no\ncounts, so it is never presented as a typed window.",
+          "description": "The percentage a background-task token states, percent sign included. It carries no\ncounts, so it is never presented as a typed window.",
           "type": [
             "string",
             "null"
@@ -783,7 +783,7 @@
           ]
         },
         "label": {
-          "description": "A managed worker's runtime label: the name its owner and its siblings\nuse for it, and the only faithful source for a worker's name. Herdr's\nown agent name truncates it and its title welds it to the task.",
+          "description": "A managed worker's runtime label: the name its owner and its siblings\nuse for it, and the only faithful source for a worker's name. The backend's\nown agent name truncates it and its title welds it to the task.",
           "type": [
             "string",
             "null"
@@ -941,12 +941,6 @@
         },
         "subject_id": {
           "type": "string"
-        },
-        "successor": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [
@@ -954,8 +948,7 @@
         "bound_registration_id",
         "process",
         "state",
-        "session",
-        "successor"
+        "session"
       ],
       "type": "object"
     },
@@ -1026,7 +1019,7 @@
     },
     "Location": {
       "additionalProperties": false,
-      "description": "Connector-scoped runtime location: Herdr workspace, tab and pane identifiers.\n\nPane identity is a runtime location detail; it is never an agent identity.",
+      "description": "Backend-scoped runtime location: workspace, tab and pane identifiers.\n\nPane identity is a runtime location detail; it is never an agent identity.",
       "properties": {
         "pane_id": {
           "type": "string"
@@ -1099,9 +1092,6 @@
         "claim_id": {
           "type": "string"
         },
-        "identity_unresolved": {
-          "type": "boolean"
-        },
         "metadata": {
           "$ref": "#/$defs/ManagedMetadata"
         },
@@ -1119,24 +1109,16 @@
         },
         "subject_id": {
           "type": "string"
-        },
-        "successor": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [
         "subject_id",
         "claim_id",
         "process",
-        "identity_unresolved",
         "metadata",
         "child_close",
         "state",
-        "session",
-        "successor"
+        "session"
       ],
       "type": "object"
     },
@@ -1729,9 +1711,6 @@
         "channel": {
           "$ref": "#/$defs/Channel"
         },
-        "registration_id": {
-          "type": "string"
-        },
         "snapshot": {
           "anyOf": [
             {
@@ -1753,7 +1732,6 @@
       },
       "required": [
         "version",
-        "registration_id",
         "channel",
         "writer"
       ],
@@ -2584,7 +2562,7 @@
     },
     "Tab": {
       "additionalProperties": false,
-      "description": "A Herdr tab within a workspace; shown as location detail, not a tree level.",
+      "description": "A tab within a workspace; shown as location detail, not a tree level.",
       "properties": {
         "label": {
           "type": [
@@ -2819,7 +2797,7 @@
     },
     "Workspace": {
       "additionalProperties": false,
-      "description": "A Herdr workspace: the first display grouping for the fleet tree.",
+      "description": "A workspace: the first display grouping for the fleet tree.",
       "properties": {
         "label": {
           "type": [

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

@@ -732,7 +732,7 @@
           "type": "array"
         },
         "context_usage": {
-          "description": "The percentage a Herdr token states, percent sign included. It carries no\ncounts, so it is never presented as a typed window.",
+          "description": "The percentage a background-task token states, percent sign included. It carries no\ncounts, so it is never presented as a typed window.",
           "type": [
             "string",
             "null"
@@ -757,7 +757,7 @@
           ]
         },
         "label": {
-          "description": "A managed worker's runtime label: the name its owner and its siblings\nuse for it, and the only faithful source for a worker's name. Herdr's\nown agent name truncates it and its title welds it to the task.",
+          "description": "A managed worker's runtime label: the name its owner and its siblings\nuse for it, and the only faithful source for a worker's name. The backend's\nown agent name truncates it and its title welds it to the task.",
           "type": [
             "string",
             "null"
@@ -893,12 +893,6 @@
         },
         "subject_id": {
           "type": "string"
-        },
-        "successor": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [
@@ -968,7 +962,7 @@
       "type": "object"
     },
     "Location": {
-      "description": "Connector-scoped runtime location: Herdr workspace, tab and pane identifiers.\n\nPane identity is a runtime location detail; it is never an agent identity.",
+      "description": "Backend-scoped runtime location: workspace, tab and pane identifiers.\n\nPane identity is a runtime location detail; it is never an agent identity.",
       "properties": {
         "pane_id": {
           "type": "string"
@@ -1040,9 +1034,6 @@
         "claim_id": {
           "type": "string"
         },
-        "identity_unresolved": {
-          "type": "boolean"
-        },
         "metadata": {
           "$ref": "#/$defs/ManagedMetadata"
         },
@@ -1060,19 +1051,12 @@
         },
         "subject_id": {
           "type": "string"
-        },
-        "successor": {
-          "type": [
-            "string",
-            "null"
-          ]
         }
       },
       "required": [
         "subject_id",
         "claim_id",
         "process",
-        "identity_unresolved",
         "metadata",
         "state"
       ],
@@ -1496,9 +1480,6 @@
         "channel": {
           "$ref": "#/$defs/Channel"
         },
-        "registration_id": {
-          "type": "string"
-        },
         "snapshot": {
           "anyOf": [
             {
@@ -1520,7 +1501,6 @@
       },
       "required": [
         "version",
-        "registration_id",
         "channel",
         "writer"
       ],
@@ -2329,7 +2309,7 @@
       ]
     },
     "Tab": {
-      "description": "A Herdr tab within a workspace; shown as location detail, not a tree level.",
+      "description": "A tab within a workspace; shown as location detail, not a tree level.",
       "properties": {
         "label": {
           "type": [
@@ -2555,7 +2535,7 @@
       ]
     },
     "Workspace": {
-      "description": "A Herdr workspace: the first display grouping for the fleet tree.",
+      "description": "A workspace: the first display grouping for the fleet tree.",
       "properties": {
         "label": {
           "type": [