@unicity-astrid/sdk 0.1.0

package/dist/identity.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Multi-platform identity resolution and linking. Mirrors `astrid_sdk::identity`.
+ *
+ * Required capability in `Capsule.toml`:
+ *   `["resolve"]` — resolve platform users
+ *   `["link"]`    — resolve, link, unlink, list-links
+ *   `["admin"]`   — all of the above + create new users
+ *
+ * Post per-domain WIT split, the host returns typed records directly (no
+ * `linksJson` blob, no `ok` flags). Errors surface as `SysError` with
+ * `code` set to the WIT variant (`link-not-found`, `already-linked`, etc.).
+ *
+ * The {@link resolve} helper preserves the pre-migration "absent → undefined"
+ * shape by catching `link-not-found` and returning `undefined`. Other errors
+ * propagate.
+ */
+export interface ResolvedUser {
+    userId: string;
+    displayName: string | undefined;
+}
+export interface Link {
+    platform: string;
+    platformUserId: string;
+    /** ISO 8601 timestamp the link was created. */
+    linkedAt: string;
+    /** Auth method used at link time (e.g. "passkey", "token"). */
+    method: string;
+}
+/**
+ * Resolve a platform identity to an Astrid user, or `undefined` if no link
+ * exists. Other identity errors (capability-denied, store-unavailable, etc.)
+ * propagate as `SysError`.
+ */
+export declare function resolve(platform: string, platformUserId: string): ResolvedUser | undefined;
+/** Link a platform identity to an Astrid user. */
+export declare function link(platform: string, platformUserId: string, astridUserId: string, method: string): void;
+/**
+ * Unlink a platform identity. Returns `true` if a link was removed,
+ * `false` if there was nothing to remove.
+ */
+export declare function unlink(platform: string, platformUserId: string): boolean;
+/** Create a new Astrid user. Returns the new user UUID. */
+export declare function createUser(displayName?: string): string;
+/** List all platform links for an Astrid user. */
+export declare function listLinks(astridUserId: string): Link[];
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAWH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAU1F;AAED,kDAAkD;AAClD,wBAAgB,IAAI,CAClB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,IAAI,CAIN;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAQxE;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED,kDAAkD;AAClD,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,EAAE,CAQtD"}

package/dist/identity.js

@@ -0,0 +1,69 @@
+/**
+ * Multi-platform identity resolution and linking. Mirrors `astrid_sdk::identity`.
+ *
+ * Required capability in `Capsule.toml`:
+ *   `["resolve"]` — resolve platform users
+ *   `["link"]`    — resolve, link, unlink, list-links
+ *   `["admin"]`   — all of the above + create new users
+ *
+ * Post per-domain WIT split, the host returns typed records directly (no
+ * `linksJson` blob, no `ok` flags). Errors surface as `SysError` with
+ * `code` set to the WIT variant (`link-not-found`, `already-linked`, etc.).
+ *
+ * The {@link resolve} helper preserves the pre-migration "absent → undefined"
+ * shape by catching `link-not-found` and returning `undefined`. Other errors
+ * propagate.
+ */
+import { identityResolve as hostResolve, identityLink as hostLink, identityUnlink as hostUnlink, identityCreateUser as hostCreateUser, identityListLinks as hostListLinks, } from "astrid:identity/host@1.0.0";
+import { SysError, callHost } from "./errors.js";
+/**
+ * Resolve a platform identity to an Astrid user, or `undefined` if no link
+ * exists. Other identity errors (capability-denied, store-unavailable, etc.)
+ * propagate as `SysError`.
+ */
+export function resolve(platform, platformUserId) {
+    try {
+        const resp = callHost(`identity.resolve(${JSON.stringify(platform)})`, () => hostResolve({ platform, platformUserId }));
+        return { userId: resp.userId, displayName: resp.displayName };
+    }
+    catch (err) {
+        if (err instanceof SysError && err.code === "link-not-found")
+            return undefined;
+        throw err;
+    }
+}
+/** Link a platform identity to an Astrid user. */
+export function link(platform, platformUserId, astridUserId, method) {
+    callHost("identity.link", () => hostLink({ platform, platformUserId, astridUserId, method }));
+}
+/**
+ * Unlink a platform identity. Returns `true` if a link was removed,
+ * `false` if there was nothing to remove.
+ */
+export function unlink(platform, platformUserId) {
+    try {
+        callHost("identity.unlink", () => hostUnlink({ platform, platformUserId }));
+        return true;
+    }
+    catch (err) {
+        if (err instanceof SysError && err.code === "link-not-found")
+            return false;
+        throw err;
+    }
+}
+/** Create a new Astrid user. Returns the new user UUID. */
+export function createUser(displayName) {
+    const resp = callHost("identity.createUser", () => hostCreateUser({ displayName }));
+    return resp.userId;
+}
+/** List all platform links for an Astrid user. */
+export function listLinks(astridUserId) {
+    const links = callHost("identity.listLinks", () => hostListLinks(astridUserId));
+    return links.map((l) => ({
+        platform: l.platform,
+        platformUserId: l.platformUserId,
+        linkedAt: l.linkedAt,
+        method: l.method,
+    }));
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,eAAe,IAAI,WAAW,EAC9B,YAAY,IAAI,QAAQ,EACxB,cAAc,IAAI,UAAU,EAC5B,kBAAkB,IAAI,cAAc,EACpC,iBAAiB,IAAI,aAAa,GACnC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAgBjD;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,QAAgB,EAAE,cAAsB;IAC9D,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,CAC1E,WAAW,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAC1C,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;IAChE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB;YAAE,OAAO,SAAS,CAAC;QAC/E,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,IAAI,CAClB,QAAgB,EAChB,cAAsB,EACtB,YAAoB,EACpB,MAAc;IAEd,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE,CAC7B,QAAQ,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAC7D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,QAAgB,EAAE,cAAsB;IAC7D,IAAI,CAAC;QACH,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB;YAAE,OAAO,KAAK,CAAC;QAC3E,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,UAAU,CAAC,WAAoB;IAC7C,MAAM,IAAI,GAAG,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE,CAChD,cAAc,CAAC,EAAE,WAAW,EAAE,CAAC,CAChC,CAAC;IACF,OAAO,IAAI,CAAC,MAAM,CAAC;AACrB,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,SAAS,CAAC,YAAoB;IAC5C,MAAM,KAAK,GAAG,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC;IAChF,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,cAAc,EAAE,CAAC,CAAC,cAAc;QAChC,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM;KACjB,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export { SysError, type SysErrorKind } from "./errors.js";
+export { capsule, install, upgrade, run } from "./capsule.js";
+export { tool, interceptor, command, type ToolOptions, type InterceptorOptions, type CommandOptions, } from "./tool.js";
+export * as log from "./log.js";
+export * as kv from "./kv.js";
+export * as ipc from "./ipc.js";
+export * as fs from "./fs.js";
+export * as http from "./http.js";
+export * as net from "./net.js";
+export * as process from "./process.js";
+export * as env from "./env.js";
+export * as time from "./time.js";
+export * as runtime from "./runtime.js";
+export * as capabilities from "./capabilities.js";
+export * as elicit from "./elicit.js";
+export * as identity from "./identity.js";
+export * as approval from "./approval.js";
+export * as uplink from "./uplink.js";
+export * as interceptors from "./interceptors.js";
+export type { IpcMessage, PollResult, Subscription, InterceptorBinding, PrincipalAttribution, } from "./ipc.js";
+export type { Stats, Dirent, FileHandle, OpenMode, FileType } from "./fs.js";
+export type { Request as HttpRequest, Response as HttpResponse, HttpMethod, HttpStreamHandle, StreamStart, FetchInit, FetchResponse, } from "./http.js";
+export type { UnixListener, TcpListener, TcpStream, UdpSocket, ListenerHandle, StreamHandle, RecvError, SendError, TryRecvError, ShutdownHow, NetReadStatus, UdpDatagram, } from "./net.js";
+export type { ProcessResult, ProcessLogs, KillResult, BackgroundProcessHandle, SpawnOptions, ProcessSignal, EnvVar, } from "./process.js";
+export type { CallerContext } from "./runtime.js";
+export type { ResolvedUser, Link } from "./identity.js";
+export type { UplinkId, UplinkProfile } from "./uplink.js";
+export type { ApprovalDecision } from "./approval.js";
+export type { KeyPage } from "./kv.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,IAAI,EACJ,WAAW,EACX,OAAO,EACP,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC;AAKnB,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC;AAGlD,YAAY,EACV,UAAU,EACV,UAAU,EACV,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7E,YAAY,EACV,OAAO,IAAI,WAAW,EACtB,QAAQ,IAAI,YAAY,EACxB,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,SAAS,EACT,cAAc,EACd,YAAY,EACZ,SAAS,EACT,SAAS,EACT,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,aAAa,EACb,WAAW,EACX,UAAU,EACV,uBAAuB,EACvB,YAAY,EACZ,aAAa,EACb,MAAM,GACP,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,27 @@
+// Public API of @unicity-astrid/sdk.
+//
+// Module-by-module mirror of `astrid_sdk::prelude`, with idiom translated
+// from Rust-std to Node/WHATWG conventions where appropriate.
+export { SysError } from "./errors.js";
+export { capsule, install, upgrade, run } from "./capsule.js";
+export { tool, interceptor, command, } from "./tool.js";
+// Namespaced submodules. Authors import as
+// `import { fs, http, ipc, ... } from "@unicity-astrid/sdk"` and call
+// `await fs.readFile(...)`, `ipc.publish(...)`, etc.
+export * as log from "./log.js";
+export * as kv from "./kv.js";
+export * as ipc from "./ipc.js";
+export * as fs from "./fs.js";
+export * as http from "./http.js";
+export * as net from "./net.js";
+export * as process from "./process.js";
+export * as env from "./env.js";
+export * as time from "./time.js";
+export * as runtime from "./runtime.js";
+export * as capabilities from "./capabilities.js";
+export * as elicit from "./elicit.js";
+export * as identity from "./identity.js";
+export * as approval from "./approval.js";
+export * as uplink from "./uplink.js";
+export * as interceptors from "./interceptors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,0EAA0E;AAC1E,8DAA8D;AAE9D,OAAO,EAAE,QAAQ,EAAqB,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EACL,IAAI,EACJ,WAAW,EACX,OAAO,GAIR,MAAM,WAAW,CAAC;AAEnB,2CAA2C;AAC3C,sEAAsE;AACtE,qDAAqD;AACrD,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC"}

package/dist/interceptors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Interceptor binding registry — metadata for the kernel-managed
+ * interceptor subscriptions a capsule declared in `Capsule.toml`.
+ *
+ * Mirrors `astrid_sdk::interceptors`. Under the per-domain ABI, interceptor
+ * events are delivered to the capsule via `astrid-hook-trigger` rather than
+ * a run-loop IPC subscription. The host fn `get-interceptor-bindings` returns
+ * metadata-only — capsules use it to enumerate the `(action, topic)` pairs
+ * they're subscribed to for debugging, introspection, and tooling. `handle`
+ * is the kernel-side registry handle (for log correlation only); it is NOT
+ * convertible into an `ipc.Subscription`.
+ */
+import { type InterceptorBinding } from "./ipc.js";
+export type { InterceptorBinding } from "./ipc.js";
+/**
+ * Query the runtime for auto-subscribed interceptor handles. Returns an
+ * empty array if this capsule has no auto-subscribed interceptors (i.e. it
+ * does not have both `@run` and `[[interceptor]]`).
+ */
+export declare function bindings(): InterceptorBinding[];
+//# sourceMappingURL=interceptors.d.ts.map

package/dist/interceptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptors.d.ts","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAuB,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAExE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,kBAAkB,EAAE,CAE/C"}

package/dist/interceptors.js

@@ -0,0 +1,22 @@
+/**
+ * Interceptor binding registry — metadata for the kernel-managed
+ * interceptor subscriptions a capsule declared in `Capsule.toml`.
+ *
+ * Mirrors `astrid_sdk::interceptors`. Under the per-domain ABI, interceptor
+ * events are delivered to the capsule via `astrid-hook-trigger` rather than
+ * a run-loop IPC subscription. The host fn `get-interceptor-bindings` returns
+ * metadata-only — capsules use it to enumerate the `(action, topic)` pairs
+ * they're subscribed to for debugging, introspection, and tooling. `handle`
+ * is the kernel-side registry handle (for log correlation only); it is NOT
+ * convertible into an `ipc.Subscription`.
+ */
+import { runtimeInterceptors } from "./ipc.js";
+/**
+ * Query the runtime for auto-subscribed interceptor handles. Returns an
+ * empty array if this capsule has no auto-subscribed interceptors (i.e. it
+ * does not have both `@run` and `[[interceptor]]`).
+ */
+export function bindings() {
+    return runtimeInterceptors();
+}
+//# sourceMappingURL=interceptors.js.map

package/dist/interceptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptors.js","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,mBAAmB,EAA2B,MAAM,UAAU,CAAC;AAIxE;;;;GAIG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,mBAAmB,EAAE,CAAC;AAC/B,CAAC"}

package/dist/ipc.d.ts

@@ -0,0 +1,143 @@
+/**
+ * IPC event bus. Mirrors `astrid_sdk::ipc`.
+ *
+ * Publish: {@link publish} / {@link publishJson} for the calling capsule's
+ * own principal, {@link publishAs} / {@link publishJsonAs} for uplinks
+ * asserting an end-user principal (requires `uplink = true` capability —
+ * subscribers see the principal as `claimed`, not `verified`).
+ *
+ * Subscribe: {@link subscribe} returns a {@link Subscription} resource handle.
+ * Resources are Component Model objects with a drop step; we surface
+ * `Symbol.dispose` so `using sub = ipc.subscribe(...)` cleans up automatically
+ * on scope exit, and an explicit `.close()` for codebases that haven't moved
+ * to the explicit-resource-management proposal. AsyncIterable convenience
+ * preserved from the pre-migration API.
+ *
+ * Request/response: {@link requestResponse} mirrors `astrid_sdk::ipc::request_response`.
+ * Validates the request payload, pre-subscribes to the reply topic, publishes
+ * with an auto-injected `correlation_id`, blocks up to `timeoutMs` for the
+ * single reply, always tears down the subscription.
+ */
+import { type PrincipalAttribution, type Subscription as WitSubscription } from "astrid:ipc/host@1.0.0";
+/** A single IPC message dispatched to a subscriber. */
+export interface IpcMessage {
+    topic: string;
+    payload: string;
+    /** UUID of the capsule that published this message. */
+    sourceId: string;
+    /**
+     * Principal attributed to the publisher. `verified(...)` for kernel-attributed
+     * principals, `claimed(...)` for uplink-asserted principals (NOT kernel-
+     * verified), `system` for kernel-originated events.
+     *
+     * Subscribers MUST check this variant on sensitive actions. Multi-message
+     * batches MUST be read per-message rather than relying on `runtime.caller()`
+     * (which only reflects the first message's publisher).
+     */
+    principal: PrincipalAttribution;
+    /** Convenience: parse `payload` as JSON. Throws SysError.json on failure. */
+    json<T = unknown>(): T;
+}
+export type { PrincipalAttribution } from "astrid:ipc/host@1.0.0";
+export interface PollResult {
+    messages: IpcMessage[];
+    /** Messages dropped due to buffer overflow since the previous poll. */
+    dropped: bigint;
+    /** Cumulative lag — total messages missed since subscription opened. */
+    lagged: bigint;
+}
+export interface InterceptorBinding {
+    /** Subscription handle ID. */
+    handle: bigint;
+    /** Hook action name the kernel dispatches when a message matches. */
+    action: string;
+    /** Topic pattern this subscription was registered for. */
+    topic: string;
+}
+export declare function publish(topic: string, payload: string): void;
+export declare function publishJson<T>(topic: string, payload: T): void;
+/**
+ * Publish on behalf of a specific principal. Requires `uplink = true` in
+ * `Capsule.toml [capabilities]`; non-uplinks see `capability-denied`.
+ * Subscribers see the principal as `claimed(...)`, NOT `verified(...)` —
+ * downstream consumers MUST treat the principal as caller-input, not
+ * authenticated context.
+ */
+export declare function publishAs(topic: string, payload: string, principal: string): void;
+export declare function publishJsonAs<T>(topic: string, payload: T, principal: string): void;
+/**
+ * Subscribe to an IPC topic pattern. Supports exact matches and trailing-suffix
+ * wildcards (`foo.bar.*`). Mid-segment wildcards are rejected by the host.
+ *
+ * The returned {@link Subscription} is a Resource handle. Use `using` for
+ * scope-bound cleanup, or call `.close()` explicitly:
+ *
+ * ```ts
+ * using sub = ipc.subscribe("foo.bar");      // disposed at scope exit
+ * for await (const msg of sub) { ... }
+ *
+ * const sub = ipc.subscribe("foo.bar");      // explicit close
+ * try { ... } finally { sub.close(); }
+ * ```
+ *
+ * Per-capsule cap: 128 subscriptions.
+ */
+export declare function subscribe(topicPattern: string): Subscription;
+/**
+ * Pre-registered interceptor handles for run-loop capsules. Returns ONLY the
+ * calling capsule's own interceptors. Most authors don't call this — the
+ * `@interceptor` decorator + bridge handle dispatch.
+ */
+export declare function runtimeInterceptors(): InterceptorBinding[];
+export declare class Subscription {
+    #private;
+    readonly topic: string;
+    constructor(inner: WitSubscription, topic: string);
+    /** Non-blocking poll. Returns whatever's already queued. */
+    poll(): PollResult;
+    /** Blocking receive (timeout capped at 60s by the host). */
+    recv(timeoutMs?: bigint): PollResult;
+    /**
+     * Idempotent — closing an already-closed subscription is a no-op.
+     * Equivalent to the resource Drop. Prefer `using` when the surrounding
+     * code can adopt explicit resource management.
+     */
+    close(): void;
+    [Symbol.dispose](): void;
+    /**
+     * AsyncIterable convenience. Loops calling `.recv()` and yielding each
+     * message. Stops when the subscription is closed. Drops `lagged`/`dropped`
+     * info — use `.poll()`/`.recv()` explicitly if you need to react to lag.
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<IpcMessage>;
+}
+/**
+ * Send a request on `requestTopic` and await a single response on a scoped
+ * reply topic. Mirrors `astrid_sdk::ipc::request_response` exactly.
+ *
+ * The helper:
+ * 1. Generates a v4 correlation ID.
+ * 2. Subscribes to `{responseNamespace}.{correlationId}` *before* publishing
+ *    (so the response can never be missed in the race).
+ * 3. Injects the correlation ID into the request payload as a top-level
+ *    `correlation_id` field.
+ * 4. Publishes the request.
+ * 5. Blocks up to `timeoutMs` for the response.
+ * 6. Unsubscribes (always, even on error).
+ * 7. Returns the parsed response payload as `Resp`.
+ *
+ * `request` must serialize to a JSON object. Primitives, arrays, strings,
+ * etc. are rejected synchronously with `SysError.api` because there is
+ * nowhere to put the correlation ID.
+ *
+ * `responseNamespace` should be the dotted topic prefix the responder
+ * publishes to, *without* the trailing correlation id segment. For example,
+ * if the responder publishes to
+ * `registry.v1.response.set_active_model.<corr_id>`, pass
+ * `"registry.v1.response.set_active_model"`.
+ *
+ * `timeoutMs` is capped at 60,000 ms by the host. A timeout throws
+ * `SysError.api` with `request_response: no reply within …`.
+ */
+export declare function requestResponse<Req, Resp = unknown>(requestTopic: string, responseNamespace: string, request: Req, timeoutMs: number | bigint): Resp;
+//# sourceMappingURL=ipc.d.ts.map

package/dist/ipc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc.d.ts","sourceRoot":"","sources":["../src/ipc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAQL,KAAK,oBAAoB,EACzB,KAAK,YAAY,IAAI,eAAe,EACrC,MAAM,uBAAuB,CAAC;AAI/B,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;IACH,SAAS,EAAE,oBAAoB,CAAC;IAChC,6EAA6E;IAC7E,IAAI,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC;CACxB;AAED,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;CACf;AAID,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAIjF;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAEnF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,YAAY,CAK5D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,kBAAkB,EAAE,CAK1D;AAED,qBAAa,YAAY;;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAGX,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM;IAKjD,4DAA4D;IAC5D,IAAI,IAAI,UAAU;IAKlB,4DAA4D;IAC5D,IAAI,CAAC,SAAS,GAAE,MAAgC,GAAG,UAAU;IAO7D;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAYb,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB;;;;OAIG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,qBAAqB,CAAC,UAAU,CAAC;CAenE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,IAAI,GAAG,OAAO,EACjD,YAAY,EAAE,MAAM,EACpB,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,GAAG,EACZ,SAAS,EAAE,MAAM,GAAG,MAAM,GACzB,IAAI,CA0CN"}

package/dist/ipc.js

@@ -0,0 +1,261 @@
+/**
+ * IPC event bus. Mirrors `astrid_sdk::ipc`.
+ *
+ * Publish: {@link publish} / {@link publishJson} for the calling capsule's
+ * own principal, {@link publishAs} / {@link publishJsonAs} for uplinks
+ * asserting an end-user principal (requires `uplink = true` capability —
+ * subscribers see the principal as `claimed`, not `verified`).
+ *
+ * Subscribe: {@link subscribe} returns a {@link Subscription} resource handle.
+ * Resources are Component Model objects with a drop step; we surface
+ * `Symbol.dispose` so `using sub = ipc.subscribe(...)` cleans up automatically
+ * on scope exit, and an explicit `.close()` for codebases that haven't moved
+ * to the explicit-resource-management proposal. AsyncIterable convenience
+ * preserved from the pre-migration API.
+ *
+ * Request/response: {@link requestResponse} mirrors `astrid_sdk::ipc::request_response`.
+ * Validates the request payload, pre-subscribes to the reply topic, publishes
+ * with an auto-injected `correlation_id`, blocks up to `timeoutMs` for the
+ * single reply, always tears down the subscription.
+ */
+import { publish as hostPublish, publishAs as hostPublishAs, subscribe as hostSubscribe, getInterceptorBindings as hostGetInterceptorBindings, } from "astrid:ipc/host@1.0.0";
+import { randomBytes as hostRandomBytes } from "astrid:sys/host@1.0.0";
+import { SysError, callHost } from "./errors.js";
+const DEFAULT_RECV_TIMEOUT_MS = 5000n;
+export function publish(topic, payload) {
+    callHost(`ipc.publish(${quote(topic)})`, () => hostPublish(topic, payload));
+}
+export function publishJson(topic, payload) {
+    publish(topic, jsonify(`ipc.publishJson(${quote(topic)})`, payload));
+}
+/**
+ * Publish on behalf of a specific principal. Requires `uplink = true` in
+ * `Capsule.toml [capabilities]`; non-uplinks see `capability-denied`.
+ * Subscribers see the principal as `claimed(...)`, NOT `verified(...)` —
+ * downstream consumers MUST treat the principal as caller-input, not
+ * authenticated context.
+ */
+export function publishAs(topic, payload, principal) {
+    callHost(`ipc.publishAs(${quote(topic)})`, () => hostPublishAs(topic, payload, principal));
+}
+export function publishJsonAs(topic, payload, principal) {
+    publishAs(topic, jsonify(`ipc.publishJsonAs(${quote(topic)})`, payload), principal);
+}
+/**
+ * Subscribe to an IPC topic pattern. Supports exact matches and trailing-suffix
+ * wildcards (`foo.bar.*`). Mid-segment wildcards are rejected by the host.
+ *
+ * The returned {@link Subscription} is a Resource handle. Use `using` for
+ * scope-bound cleanup, or call `.close()` explicitly:
+ *
+ * ```ts
+ * using sub = ipc.subscribe("foo.bar");      // disposed at scope exit
+ * for await (const msg of sub) { ... }
+ *
+ * const sub = ipc.subscribe("foo.bar");      // explicit close
+ * try { ... } finally { sub.close(); }
+ * ```
+ *
+ * Per-capsule cap: 128 subscriptions.
+ */
+export function subscribe(topicPattern) {
+    const inner = callHost(`ipc.subscribe(${quote(topicPattern)})`, () => hostSubscribe(topicPattern));
+    return new Subscription(inner, topicPattern);
+}
+/**
+ * Pre-registered interceptor handles for run-loop capsules. Returns ONLY the
+ * calling capsule's own interceptors. Most authors don't call this — the
+ * `@interceptor` decorator + bridge handle dispatch.
+ */
+export function runtimeInterceptors() {
+    const handles = callHost("ipc.runtimeInterceptors", () => hostGetInterceptorBindings());
+    return handles.map((h) => ({ handle: h.handleId, action: h.action, topic: h.topic }));
+}
+export class Subscription {
+    topic;
+    #inner;
+    constructor(inner, topic) {
+        this.#inner = inner;
+        this.topic = topic;
+    }
+    /** Non-blocking poll. Returns whatever's already queued. */
+    poll() {
+        const env = callHost(`ipc.poll(${quote(this.topic)})`, () => this.#requireInner().poll());
+        return envelopeToPollResult(env);
+    }
+    /** Blocking receive (timeout capped at 60s by the host). */
+    recv(timeoutMs = DEFAULT_RECV_TIMEOUT_MS) {
+        const env = callHost(`ipc.recv(${quote(this.topic)})`, () => this.#requireInner().recv(timeoutMs));
+        return envelopeToPollResult(env);
+    }
+    /**
+     * Idempotent — closing an already-closed subscription is a no-op.
+     * Equivalent to the resource Drop. Prefer `using` when the surrounding
+     * code can adopt explicit resource management.
+     */
+    close() {
+        if (this.#inner === undefined)
+            return;
+        const inner = this.#inner;
+        this.#inner = undefined;
+        try {
+            inner[Symbol.dispose]();
+        }
+        catch {
+            // Resource may already be released (interceptor-owned handles, etc.).
+            // close() is meant to be safe to call from any cleanup path.
+        }
+    }
+    [Symbol.dispose]() {
+        this.close();
+    }
+    /**
+     * AsyncIterable convenience. Loops calling `.recv()` and yielding each
+     * message. Stops when the subscription is closed. Drops `lagged`/`dropped`
+     * info — use `.poll()`/`.recv()` explicitly if you need to react to lag.
+     */
+    async *[Symbol.asyncIterator]() {
+        while (this.#inner !== undefined) {
+            const batch = this.recv();
+            for (const msg of batch.messages) {
+                yield msg;
+            }
+        }
+    }
+    #requireInner() {
+        if (this.#inner === undefined) {
+            throw SysError.api(`subscription on ${quote(this.topic)} is closed`);
+        }
+        return this.#inner;
+    }
+}
+/**
+ * Send a request on `requestTopic` and await a single response on a scoped
+ * reply topic. Mirrors `astrid_sdk::ipc::request_response` exactly.
+ *
+ * The helper:
+ * 1. Generates a v4 correlation ID.
+ * 2. Subscribes to `{responseNamespace}.{correlationId}` *before* publishing
+ *    (so the response can never be missed in the race).
+ * 3. Injects the correlation ID into the request payload as a top-level
+ *    `correlation_id` field.
+ * 4. Publishes the request.
+ * 5. Blocks up to `timeoutMs` for the response.
+ * 6. Unsubscribes (always, even on error).
+ * 7. Returns the parsed response payload as `Resp`.
+ *
+ * `request` must serialize to a JSON object. Primitives, arrays, strings,
+ * etc. are rejected synchronously with `SysError.api` because there is
+ * nowhere to put the correlation ID.
+ *
+ * `responseNamespace` should be the dotted topic prefix the responder
+ * publishes to, *without* the trailing correlation id segment. For example,
+ * if the responder publishes to
+ * `registry.v1.response.set_active_model.<corr_id>`, pass
+ * `"registry.v1.response.set_active_model"`.
+ *
+ * `timeoutMs` is capped at 60,000 ms by the host. A timeout throws
+ * `SysError.api` with `request_response: no reply within …`.
+ */
+export function requestResponse(requestTopic, responseNamespace, request, timeoutMs) {
+    // Validate input before touching the host so bad calls never allocate a
+    // subscription handle.
+    if (typeof request !== "object" || request === null || Array.isArray(request)) {
+        throw SysError.api("request_response: request payload must serialize to a JSON object so the " +
+            "correlation_id can be injected");
+    }
+    const correlationId = randomUuidV4();
+    // Defensive copy + injection. Don't mutate the caller's object.
+    const augmented = {
+        ...request,
+        correlation_id: correlationId,
+    };
+    const payload = jsonify("requestResponse", augmented);
+    const replyTopic = `${responseNamespace}.${correlationId}`;
+    const sub = subscribe(replyTopic);
+    try {
+        publish(requestTopic, payload);
+        const timeoutBig = typeof timeoutMs === "bigint" ? timeoutMs : BigInt(Math.max(0, Math.floor(timeoutMs)));
+        const poll = sub.recv(timeoutBig);
+        const msg = poll.messages[0];
+        if (msg === undefined) {
+            throw SysError.api(`request_response: no reply on '${replyTopic}' within ${String(timeoutMs)}ms`);
+        }
+        try {
+            return JSON.parse(msg.payload);
+        }
+        catch (err) {
+            throw SysError.json(`request_response: failed to parse reply on '${replyTopic}': ${err.message}`, err);
+        }
+    }
+    finally {
+        sub.close();
+    }
+}
+function envelopeToPollResult(env) {
+    return {
+        messages: env.messages.map(makeIpcMessage),
+        dropped: env.dropped,
+        lagged: env.lagged,
+    };
+}
+function makeIpcMessage(m) {
+    return {
+        topic: m.topic,
+        payload: m.payload,
+        sourceId: m.sourceId,
+        principal: m.principal,
+        json() {
+            try {
+                return JSON.parse(m.payload);
+            }
+            catch (err) {
+                throw SysError.json(`IpcMessage.json() on topic ${quote(m.topic)}: ${err.message}`, err);
+            }
+        },
+    };
+}
+function jsonify(label, value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch (err) {
+        throw SysError.json(`${label}: ${err.message}`, err);
+    }
+}
+function quote(s) {
+    return `"${s.replace(/"/g, '\\"')}"`;
+}
+/**
+ * UUIDv4 generator. The Astrid host exposes `randomBytes`; pulling from
+ * `globalThis.crypto` would work too (StarlingMonkey exposes `crypto`), but
+ * routing through `sys::randomBytes` keeps the audit trail on the host side.
+ *
+ * Lazy-loaded to avoid a load-order cycle between ipc.ts and sys.ts.
+ */
+function randomUuidV4() {
+    // 16 random bytes → format as 8-4-4-4-12 hex with version (0x40) and
+    // variant (0x80) bits set. RFC 4122 §4.4.
+    const bytes = getRandomBytes();
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    const hex = [];
+    for (let i = 0; i < 16; i++) {
+        hex.push((bytes[i] ?? 0).toString(16).padStart(2, "0"));
+    }
+    return (hex.slice(0, 4).join("") +
+        "-" +
+        hex.slice(4, 6).join("") +
+        "-" +
+        hex.slice(6, 8).join("") +
+        "-" +
+        hex.slice(8, 10).join("") +
+        "-" +
+        hex.slice(10, 16).join(""));
+}
+function getRandomBytes() {
+    // Audit-traced via sys::random-bytes rather than reaching for globalThis.crypto
+    // so every UUID generation flows through the kernel's principal-scoped audit.
+    return hostRandomBytes(16n);
+}
+//# sourceMappingURL=ipc.js.map