pi-radar 0.2.0 → 0.4.0

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.4.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,20 +71,20 @@
     "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",
     "extension/radar-location.ts",
     "extension/radar-publication.ts",
-    "extension/radar-session-marker.ts",
     "extension/radar-runtime.ts",
     "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-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-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_registration_id": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "sender_registration_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_registration_id": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "sender_registration_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": {
+        "execution_generation": {
+          "format": "uint32",
+          "maximum": 4294967295,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "execution_id": {
+          "type": "string"
+        },
+        "registration_id": {
+          "type": "string"
+        },
+        "session_id": {
+          "type": "string"
+        },
+        "subject_id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "registration_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": {
+        "execution_generation": {
+          "format": "uint32",
+          "maximum": 4294967295,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "execution_id": {
+          "type": "string"
+        },
+        "registration_id": {
+          "type": "string"
+        },
+        "session_id": {
+          "type": "string"
+        },
+        "subject_id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "registration_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"
+}

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

@@ -0,0 +1,84 @@
+{
+  "$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": {
+        "execution_generation": {
+          "format": "uint32",
+          "maximum": 4294967295,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "execution_id": {
+          "type": "string"
+        },
+        "registration_id": {
+          "type": "string"
+        },
+        "session_id": {
+          "type": "string"
+        },
+        "subject_id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "registration_id",
+        "session_id",
+        "subject_id",
+        "execution_id",
+        "execution_generation"
+      ],
+      "type": "object"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Immutable handoff content. The request id is the stable communication id.",
+  "properties": {
+    "content": {
+      "type": "string"
+    },
+    "correlation_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "id": {
+      "type": "string"
+    },
+    "published_at_unix_ms": {
+      "format": "uint64",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "recipient_subject_id": {
+      "type": "string"
+    },
+    "sender": {
+      "$ref": "#/$defs/HandoffIdentity"
+    },
+    "summary": {
+      "type": "string"
+    },
+    "version": {
+      "format": "uint32",
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "version",
+    "id",
+    "sender",
+    "recipient_subject_id",
+    "summary",
+    "content",
+    "published_at_unix_ms"
+  ],
+  "title": "handoff-deserialize",
+  "type": "object"
+}

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

@@ -0,0 +1,84 @@
+{
+  "$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": {
+        "execution_generation": {
+          "format": "uint32",
+          "maximum": 4294967295,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "execution_id": {
+          "type": "string"
+        },
+        "registration_id": {
+          "type": "string"
+        },
+        "session_id": {
+          "type": "string"
+        },
+        "subject_id": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "registration_id",
+        "session_id",
+        "subject_id",
+        "execution_id",
+        "execution_generation"
+      ],
+      "type": "object"
+    }
+  },
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Immutable handoff content. The request id is the stable communication id.",
+  "properties": {
+    "content": {
+      "type": "string"
+    },
+    "correlation_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "id": {
+      "type": "string"
+    },
+    "published_at_unix_ms": {
+      "format": "uint64",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "recipient_subject_id": {
+      "type": "string"
+    },
+    "sender": {
+      "$ref": "#/$defs/HandoffIdentity"
+    },
+    "summary": {
+      "type": "string"
+    },
+    "version": {
+      "format": "uint32",
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "version",
+    "id",
+    "sender",
+    "recipient_subject_id",
+    "summary",
+    "content",
+    "published_at_unix_ms"
+  ],
+  "title": "handoff-serialize",
+  "type": "object"
+}

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

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Input accepted by `observation.get`.",
+  "properties": {
+    "classes": {
+      "default": null,
+      "items": {
+        "type": "string"
+      },
+      "type": [
+        "array",
+        "null"
+      ]
+    },
+    "epoch": {
+      "default": null,
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "since_revision": {
+      "default": null,
+      "format": "uint64",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "wait_ms": {
+      "default": null,
+      "format": "uint64",
+      "maximum": 30000,
+      "minimum": 0,
+      "type": [
+        "integer",
+        "null"
+      ]
+    }
+  },
+  "title": "observation-get-params-deserialize",
+  "type": "object"
+}

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

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "description": "Input accepted by `observation.get`.",
+  "properties": {
+    "classes": {
+      "default": null,
+      "items": {
+        "type": "string"
+      },
+      "type": [
+        "array",
+        "null"
+      ]
+    },
+    "epoch": {
+      "default": null,
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "since_revision": {
+      "default": null,
+      "format": "uint64",
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "wait_ms": {
+      "default": null,
+      "format": "uint64",
+      "maximum": 30000,
+      "minimum": 0,
+      "type": [
+        "integer",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "epoch",
+    "since_revision",
+    "wait_ms",
+    "classes"
+  ],
+  "title": "observation-get-params-serialize",
+  "type": "object"
+}