@agentorg/cli 0.0.3 → 0.0.5

package/{node_modules → dist/node_modules}/@agentorg/hub/dist/src/state.js

@@ -23,6 +23,27 @@ const HUB_EXPORTS = {
     audit: hubAudit,
 };
 const NAME = /^[a-z][A-Za-z0-9_]*$/;
+/** The longest name of a slot made at run time, so a tool named `<slot>__<method>` fits. */
+const EXPOSED_MAX = 48;
+/** Exposure requests one Actor may have open toward one other at a time. */
+const MAX_OPEN_EXPOSURES = 32;
+/** The Actors that are the Hub itself: they take no slots. */
+const BUILTIN = new Set(["hub", "storage", "net"]);
+/**
+ * The default name of a slot exposing `exportName` of the Actor named `providerName`: the name's
+ * ASCII words camelCased, `_`, and the export's last part; the export's part alone when the name
+ * has no ASCII letters.
+ */
+export function exposedName(providerName, exportName) {
+    const words = (providerName.match(/[A-Za-z0-9]+/g) ?? []).map((word) => word.toLowerCase());
+    const joined = words
+        .map((word, i) => (i ? word[0]?.toUpperCase() + word.slice(1) : word))
+        .join("");
+    const letters = joined.replace(/^[^A-Za-z]+/, "");
+    const camel = letters && (letters[0] ?? "").toLowerCase() + letters.slice(1);
+    const part = exportName.slice(exportName.lastIndexOf(".") + 1);
+    return (camel ? `${camel}_${part}` : part).slice(0, EXPOSED_MAX);
+}
 const MEMBER = /^[a-z][A-Za-z0-9_]*(\.[a-z][A-Za-z0-9_]*)?$/;
 const now = () => new Date().toISOString();
 const digest = (secret) => createHash("sha256").update(secret).digest();
@@ -52,6 +73,9 @@ const MIGRATIONS = [
    CREATE TABLE audit (
      seq INTEGER PRIMARY KEY AUTOINCREMENT, at TEXT NOT NULL, actor TEXT NOT NULL,
      kind TEXT NOT NULL, details TEXT NOT NULL);`,
+    // Exposure: an Actor made for another (provenance only), and requests to expose.
+    `ALTER TABLE actors ADD COLUMN installed_for TEXT;
+   ALTER TABLE requests ADD COLUMN exposed INTEGER NOT NULL DEFAULT 0;`,
 ];
 /** Whether a process with this pid runs now. */
 function alive(pid) {
@@ -101,7 +125,11 @@ const bindingOf = (row) => ({
     interface: String(row.interface),
     madeBy: String(row.made_by),
     at: String(row.at),
+    ...(row.exposed ? { exposed: true } : {}),
 });
+/** A binding's columns, with whether its slot was made at run time. */
+const BINDING = `b.*, (SELECT d.dynamic FROM declarations d
+  WHERE d.actor = b.consumer AND d.side = 'slot' AND d.name = b.slot) AS exposed`;
 const requestOf = (row) => ({
     requestId: String(row.id),
     consumer: String(row.consumer),
@@ -112,8 +140,21 @@ const requestOf = (row) => ({
     requestedBy: String(row.requested_by),
     at: String(row.at),
     needs: row.needs === "slot" ? "slot" : "export",
+    ...(row.exposed ? { exposed: true } : {}),
 });
 const other = (side) => (side === "export" ? "slot" : "export");
+/** What a package's Actor declares: each module's slots and exports, by `module.name`. */
+function packageDeclarations(manifest) {
+    return Object.entries(manifest.modules).flatMap(([module, m]) => [
+        ["slot", m.slots],
+        ["export", m.exports],
+    ].flatMap(([side, members]) => Object.entries(members).map(([member, id]) => {
+        const entry = manifest.interfaces[id];
+        if (!entry)
+            throw new Refused("invalid", `The package doesn't record ${id}.`);
+        return { side, name: `${module}.${member}`, iface: { id, ...entry } };
+    })));
+}
 /**
  * The core's state in its home folder: Actors, packages, declarations, bindings, binding requests
  * and the audit trail, in `node:sqlite`. Every method that changes something takes its caller, and
@@ -302,7 +343,7 @@ export class HubState {
     // ── Actors ──────────────────────────────────────────────────────────────────
     #actor(actorId) {
         const row = this.#db
-            .prepare("SELECT id, name, package, state, restarts, last_exit FROM actors WHERE id = ?")
+            .prepare("SELECT id, name, package, state, restarts, last_exit, installed_for FROM actors WHERE id = ?")
             .get(actorId);
         return (row && {
             actorId: String(row.id),
@@ -311,12 +352,18 @@ export class HubState {
             state: row.state,
             restarts: Number(row.restarts),
             ...(row.last_exit ? { lastExit: JSON.parse(String(row.last_exit)) } : {}),
+            ...(row.installed_for ? { installedFor: String(row.installed_for) } : {}),
         });
     }
+    /** An Actor as a refusal names it: "Name (id)", or the id alone when there's no such Actor. */
+    named(actorId) {
+        const actor = this.#actor(actorId);
+        return actor ? `${actor.name} (${actor.actorId})` : actorId;
+    }
     actor(actorId) {
         const actor = this.#actor(actorId);
         if (!actor)
-            throw new Refused("unknown", `No Actor ${actorId}.`);
+            throw new Refused("unknown", `No Actor ${actorId}; hub.actors.list lists them.`);
         return actor;
     }
     /** The host sandbox's status changed: every package Actor's record (its `host`) differs. */
@@ -337,51 +384,49 @@ export class HubState {
     }
     #require(caller, hubExport) {
         if (!this.holds(caller, hubExport))
-            throw new Refused("forbidden", `${caller} isn't bound to hub.${hubExport}@1.`);
+            throw new Refused("forbidden", `${this.named(caller)} isn't bound to hub.${hubExport}@1; a manager (the person) can bind it, or do this for it.`);
     }
     /** Create an Actor: one that runs a package, or an external one, whose credential comes back once. */
     createActor(caller, input) {
         this.#require(caller, "actors");
+        if (input.for !== undefined) {
+            if (!this.isManager(caller))
+                throw new Refused("forbidden", `Only a manager says whom an Actor is made for; ${this.named(caller)} isn't one. Create it without for.`);
+            this.#open(input.for);
+        }
         const actorId = `act_${randomBytes(8).toString("hex")}`;
         const credential = input.package ? undefined : randomBytes(32).toString("base64url");
-        const insert = this.#db.prepare("INSERT INTO actors (id, name, package, state, credential, created_at) VALUES (?, ?, ?, 'created', ?, ?)");
+        const insert = this.#db.prepare("INSERT INTO actors (id, name, package, state, credential, created_at, installed_for) VALUES (?, ?, ?, 'created', ?, ?, ?)");
+        const madeFor = input.for ?? null;
         this.#transaction(() => {
             if (input.package) {
                 const { manifest } = this.package(input.package);
-                insert.run(actorId, input.name, input.package, null, now());
-                for (const [module, m] of Object.entries(manifest.modules))
-                    for (const [side, members] of [
-                        ["slot", m.slots],
-                        ["export", m.exports],
-                    ])
-                        for (const [member, id] of Object.entries(members)) {
-                            const entry = manifest.interfaces[id];
-                            if (!entry)
-                                throw new Refused("invalid", `The package doesn't record ${id}.`);
-                            this.#declare(actorId, side, `${module}.${member}`, { id, ...entry }, false);
-                        }
+                insert.run(actorId, input.name, input.package, null, now(), madeFor);
+                for (const { side, name, iface } of packageDeclarations(manifest))
+                    this.#declare(actorId, side, name, iface, false);
                 // A package's own wiring is applied as it is installed.
                 for (const [slot, exported] of manifest.connections)
                     this.#insertBinding({ consumer: actorId, slot, provider: actorId, export: exported }, HUB);
             }
             else
-                insert.run(actorId, input.name, "external", digest(credential), now());
+                insert.run(actorId, input.name, "external", digest(credential), now(), madeFor);
             this.#audit(caller, "actor.create", {
                 actorId,
                 name: input.name,
                 package: input.package ?? "external",
+                ...(input.for === undefined ? {} : { for: input.for }),
             });
             this.#emit(() => this.#events.actorChanged?.(actorId));
             for (const initial of input.bindings ?? []) {
                 const wiring = { consumer: actorId, ...initial };
                 if (!this.sides(caller, wiring).export)
-                    throw new Refused("forbidden", `${caller} can't grant ${initial.provider}'s ${initial.export}.`);
+                    throw new Refused("forbidden", `${this.named(caller)} can't grant ${this.named(initial.provider)}'s ${initial.export}. Create it without that binding, then it can ask for it with hub.grants.request, or the provider or a manager can bind it.`);
                 if (!input.package && !this.declaration(actorId, "slot", initial.slot)) {
                     if (!NAME.test(initial.slot))
                         throw new Refused("invalid", `${JSON.stringify(initial.slot)} isn't a valid slot name.`);
                     const offered = this.declaration(initial.provider, "export", initial.export);
                     if (!offered)
-                        throw new Refused("unknown", `${initial.provider} offers no ${initial.export}.`);
+                        throw new Refused("unknown", `${this.named(initial.provider)} offers no ${initial.export}; hub.exports.list lists what it offers.`);
                     this.#declare(actorId, "slot", initial.slot, offered.iface, false);
                 }
                 this.#insertBinding(wiring, caller);
@@ -403,14 +448,14 @@ export class HubState {
         this.#require(caller, "actors");
         const actor = this.actor(actorId);
         if (actor.package === "external" || actor.package === "builtin")
-            throw new Refused("state", `${actorId} isn't a package Actor; it connects itself.`);
+            throw new Refused("state", `${this.named(actorId)} isn't a package Actor, so the Hub doesn't run its process.`);
         return actor;
     }
     /** Refused unless the caller may start the Actor and it can be started now; changes nothing. */
     checkStart(caller, actorId) {
         const actor = this.#packageActor(caller, actorId);
         if (actor.state !== "created" && actor.state !== "stopped")
-            throw new Refused("state", `${actorId} is ${actor.state}.`);
+            throw new Refused("state", `${this.named(actorId)} is ${actor.state === "running" ? "already running" : "closed and can't start again; make another"}.`);
     }
     /** Start a package Actor: recorded as running; the Hub spawns its process. */
     start(caller, actorId) {
@@ -424,7 +469,7 @@ export class HubState {
     stop(caller, actorId) {
         const actor = this.#packageActor(caller, actorId);
         if (actor.state !== "running")
-            throw new Refused("state", `${actorId} is ${actor.state}.`);
+            throw new Refused("state", `${this.named(actorId)} is ${actor.state}, not running.`);
         this.#transaction(() => {
             this.#db.prepare("UPDATE actors SET state = 'stopped' WHERE id = ?").run(actorId);
             this.#audit(caller, "actor.stop", { actorId });
@@ -436,7 +481,7 @@ export class HubState {
         this.#require(caller, "actors");
         const actor = this.actor(actorId);
         if (actorId === HUB || actorId === PERSON || actorId === STORAGE || actorId === NET)
-            throw new Refused("forbidden", `${actorId} can't be closed.`);
+            throw new Refused("forbidden", `${this.named(actorId)} is built in and can't be closed.`);
         if (actor.state === "closed")
             return;
         this.#transaction(() => {
@@ -452,6 +497,112 @@ export class HubState {
             this.#emit(() => this.#events.closed?.(actorId));
         });
     }
+    /**
+     * Drop the bindings through one of an Actor's slots or exports, its interface having changed,
+     * but those `keeps` says still match: each is audited as `binding.drop`. Dropping only takes
+     * access away. Returns what was dropped.
+     */
+    #dropBindingsOf(actorId, side, name, by, keeps = () => false) {
+        const dropped = this.bindings(actorId).filter((b) => (side === "slot"
+            ? b.consumer === actorId && b.slot === name
+            : b.provider === actorId && b.export === name) && !keeps(b));
+        for (const b of dropped)
+            this.#removeBindings("consumer = ? AND slot = ?", b.consumer, b.slot);
+        const wirings = dropped.map(({ consumer, slot, provider, export: exported }) => ({
+            consumer,
+            slot,
+            provider,
+            export: exported,
+        }));
+        for (const wiring of wirings)
+            this.#audit(by, "binding.drop", { ...wiring, why: "its interface changed" });
+        return wirings;
+    }
+    /** Close the open requests to bind through one of an Actor's slots or exports. */
+    #closeRequestsThrough(actorId, side, name) {
+        const where = side === "slot" ? "consumer = ? AND slot = ?" : "provider = ? AND export = ?";
+        for (const open of this.#pending(where, actorId, name))
+            this.#decide(open, "closed");
+    }
+    /** Refused unless the caller may upgrade the Actor to the package now; changes nothing. */
+    checkUpgrade(caller, actorId, hash) {
+        this.#require(caller, "actors");
+        // An upgrade runs new code as an Actor that keeps its bindings and its store: whatever it was
+        // granted, the new code holds. Only a manager, who could grant all of it anyway, may.
+        if (!this.isManager(caller))
+            throw new Refused("forbidden", `Only a manager may upgrade an Actor, since the new package keeps its bindings and its store; ${this.named(caller)} isn't one.`);
+        const actor = this.actor(actorId);
+        if (actorId === HUB || actorId === PERSON || actorId === STORAGE || actorId === NET)
+            throw new Refused("forbidden", `${this.named(actorId)} is built in and can't be upgraded.`);
+        if (actor.package === "external")
+            throw new Refused("state", `${this.named(actorId)} isn't a package Actor; it declares what it takes when it connects.`);
+        if (actor.state === "closed")
+            throw new Refused("state", `${this.named(actorId)} is closed for good; make another.`);
+        packageDeclarations(this.package(hash).manifest);
+        return actor;
+    }
+    /**
+     * Run another package as the same Actor: its id, its stores and every binding whose interfaces
+     * still match stay; a binding through a slot or export the new package drops or declares as
+     * another interface is dropped, audited and returned. The new package's own wiring is applied
+     * where its slot is unbound. The process isn't touched here: a running Actor is stopped first
+     * and started after, by whoever runs processes.
+     */
+    upgrade(caller, actorId, hash) {
+        const actor = this.checkUpgrade(caller, actorId, hash);
+        if (actor.package === hash)
+            return [];
+        const { manifest } = this.package(hash);
+        const next = packageDeclarations(manifest);
+        const declared = (side, name) => next.find((n) => n.side === side && n.name === name)?.iface;
+        const dropped = [];
+        this.#transaction(() => {
+            // What it offered at run time was its process's, which this restarts: it goes, with the
+            // bindings to it, which are returned with the rest.
+            for (const row of this.#db
+                .prepare("SELECT name FROM declarations WHERE actor = ? AND side = 'export' AND dynamic = 1")
+                .all(actorId)) {
+                dropped.push(...this.#dropBindingsOf(actorId, "export", String(row.name), caller));
+                this.#drop(actorId, "export", String(row.name));
+            }
+            // A binding stays while its two ends declare the same interface: this Actor's end as the
+            // new package declares it, the other end as it is declared now.
+            const keeps = (b) => {
+                const slot = b.consumer === actorId
+                    ? declared("slot", b.slot)
+                    : this.declaration(b.consumer, "slot", b.slot)?.iface;
+                const exported = b.provider === actorId
+                    ? declared("export", b.export)
+                    : this.declaration(b.provider, "export", b.export)?.iface;
+                return !!slot && !!exported && compareInterfaces(slot, exported) === "same";
+            };
+            const old = this.#db
+                .prepare("SELECT side, name, iface FROM declarations WHERE actor = ? AND dynamic = 0")
+                .all(actorId).map((row) => ({
+                side: row.side,
+                name: String(row.name),
+                iface: JSON.parse(String(row.iface)),
+            }));
+            for (const was of old) {
+                dropped.push(...this.#dropBindingsOf(actorId, was.side, was.name, caller, keeps));
+                // A request through a name the package no longer declares as it was can't be made.
+                const fresh = declared(was.side, was.name);
+                if (!fresh || compareInterfaces(was.iface, fresh) !== "same")
+                    this.#closeRequestsThrough(actorId, was.side, was.name);
+            }
+            this.#db.prepare("DELETE FROM declarations WHERE actor = ? AND dynamic = 0").run(actorId);
+            for (const { side, name, iface } of next)
+                this.#declare(actorId, side, name, iface, false);
+            this.#db.prepare("UPDATE actors SET package = ? WHERE id = ?").run(hash, actorId);
+            for (const [slot, exported] of manifest.connections)
+                if (!this.binding(actorId, slot))
+                    this.#insertBinding({ consumer: actorId, slot, provider: actorId, export: exported }, HUB);
+            this.#audit(caller, "actor.upgrade", { actorId, from: actor.package, to: hash, dropped });
+            this.#emit(() => this.#events.exportsChanged?.(actorId));
+            this.#emit(() => this.#events.actorChanged?.(actorId));
+        });
+        return dropped;
+    }
     // ── Packages ────────────────────────────────────────────────────────────────
     /** Add a `.agentorg` archive from a path on this machine, verified; adding it again is a no-op. */
     addPackage(caller, path) {
@@ -557,18 +708,19 @@ export class HubState {
     #open(actorId) {
         const actor = this.actor(actorId);
         if (actor.state === "closed")
-            throw new Refused("state", `${actorId} is closed.`);
+            throw new Refused("state", `${this.named(actorId)} is closed for good; make another.`);
         return actor;
     }
     /**
      * An external Actor's slots and static exports, as it declares them when it connects; they
-     * replace what it declared before. A bound name keeps its interface: redeclaring it as another is
-     * refused. A name it no longer declares is dropped, with its bindings.
+     * replace what it declared before. A name redeclared as another interface loses its bindings
+     * (audited as `binding.drop`), since a binding holds only while both ends declare the same one.
+     * A name it no longer declares is dropped, with its bindings.
      */
     declareExternal(actorId, declares) {
         const actor = this.#open(actorId);
         if (actor.package !== "external")
-            throw new Refused("forbidden", `${actorId} declares through its package.`);
+            throw new Refused("forbidden", `${this.named(actorId)} declares through its package; an Actor of another package declares otherwise.`);
         this.#transaction(() => {
             for (const [side, members] of [
                 ["slot", declares.slots],
@@ -578,11 +730,27 @@ export class HubState {
                     if (!NAME.test(name))
                         throw new Refused("invalid", `${JSON.stringify(name)} isn't a valid name.`);
                     this.#checked(iface);
+                    if (side === "slot") {
+                        // The Actor's own slots are its to name: an exposure under the same name yields,
+                        // with its binding, and requests to make one under it close.
+                        if (this.declaration(actorId, side, name)?.dynamic)
+                            this.#drop(actorId, side, name);
+                        for (const open of this.#pending("consumer = ? AND slot = ? AND exposed = 1", actorId, name))
+                            this.#decide(open, "closed");
+                    }
+                    // A binding holds while both ends declare the same interface: redeclared as another,
+                    // the name's bindings whose other end doesn't declare it are dropped, and its requests
+                    // close.
                     const known = this.declaration(actorId, side, name);
-                    if (known &&
-                        this.#isBound(actorId, side, name) &&
-                        compareInterfaces(known.iface, iface) !== "same")
-                        throw new Refused("conflict", `${name} is bound as ${known.iface.id}; it can't change while bound.`);
+                    if (known && compareInterfaces(known.iface, iface) !== "same") {
+                        this.#dropBindingsOf(actorId, side, name, actorId, (b) => {
+                            const other = side === "slot"
+                                ? this.declaration(b.provider, "export", b.export)?.iface
+                                : this.declaration(b.consumer, "slot", b.slot)?.iface;
+                            return !!other && compareInterfaces(iface, other) === "same";
+                        });
+                        this.#closeRequestsThrough(actorId, side, name);
+                    }
                     this.#declare(actorId, side, name, iface, false);
                 }
                 const kept = Object.keys(members);
@@ -598,13 +766,6 @@ export class HubState {
             this.#emit(() => this.#events.exportsChanged?.(actorId));
         });
     }
-    #isBound(actor, side, name) {
-        return !!this.#db
-            .prepare(side === "slot"
-            ? "SELECT 1 FROM bindings WHERE consumer = ? AND slot = ?"
-            : "SELECT 1 FROM bindings WHERE provider = ? AND export = ?")
-            .get(actor, name);
-    }
     /** A declaration gone, and the bindings through it. */
     #drop(actor, side, name) {
         this.#db
@@ -622,7 +783,7 @@ export class HubState {
         if (!MEMBER.test(name))
             throw new Refused("invalid", `${JSON.stringify(name)} isn't a valid export name.`);
         if (this.declaration(actorId, "export", name))
-            throw new Refused("conflict", `${actorId} already offers ${name}.`);
+            throw new Refused("conflict", `${this.named(actorId)} already offers ${name}; offer it under another name${this.declaration(actorId, "export", name)?.dynamic ? ", or withdraw it first" : ""}.`);
         this.#checked(iface);
         this.#transaction(() => {
             this.#declare(actorId, "export", name, iface, true);
@@ -634,7 +795,7 @@ export class HubState {
     withdraw(actorId, name) {
         const declared = this.declaration(actorId, "export", name);
         if (!declared?.dynamic)
-            throw new Refused("unknown", `${actorId} offers no ${name} at run time to withdraw.`);
+            throw new Refused("unknown", `${this.named(actorId)} offers no ${name} at run time to withdraw; only exports offered at run time can be.`);
         this.#transaction(() => {
             this.#drop(actorId, "export", name);
             this.#audit(actorId, "export.withdraw", { export: name });
@@ -673,7 +834,7 @@ export class HubState {
     // ── Bindings: a binding is the grant ────────────────────────────────────────
     binding(consumer, slot) {
         const row = this.#db
-            .prepare("SELECT * FROM bindings WHERE consumer = ? AND slot = ?")
+            .prepare(`SELECT ${BINDING} FROM bindings b WHERE consumer = ? AND slot = ?`)
             .get(consumer, slot);
         return row && bindingOf(row);
     }
@@ -691,9 +852,9 @@ export class HubState {
     bindings(actor) {
         const rows = actor
             ? this.#db
-                .prepare("SELECT * FROM bindings WHERE consumer = ? OR provider = ? ORDER BY rowid")
+                .prepare(`SELECT ${BINDING} FROM bindings b WHERE consumer = ? OR provider = ? ORDER BY b.rowid`)
                 .all(actor, actor)
-            : this.#db.prepare("SELECT * FROM bindings ORDER BY rowid").all();
+            : this.#db.prepare(`SELECT ${BINDING} FROM bindings b ORDER BY b.rowid`).all();
         return rows.map(bindingOf);
     }
     /** A manager is bound to the hub's `hub.bindings@1`; there is no other role. */
@@ -737,10 +898,10 @@ export class HubState {
         this.#open(wiring.provider);
         const slot = this.declaration(wiring.consumer, "slot", wiring.slot);
         if (!slot)
-            throw new Refused("unknown", `${wiring.consumer} has no slot ${wiring.slot}.`);
+            throw new Refused("unknown", `${this.named(wiring.consumer)} has no slot ${wiring.slot}; hub.grants.expose makes one at run time.`);
         const exported = this.declaration(wiring.provider, "export", wiring.export);
         if (!exported)
-            throw new Refused("unknown", `${wiring.provider} offers no ${wiring.export}.`);
+            throw new Refused("unknown", `${this.named(wiring.provider)} offers no ${wiring.export}; hub.exports.list lists what it offers.`);
         const fit = compareInterfaces(slot.iface, exported.iface);
         if (fit === "unrelated")
             throw new Refused("conflict", `${wiring.slot} takes ${slot.iface.id}; ${wiring.export} offers ${exported.iface.id}.`);
@@ -751,7 +912,7 @@ export class HubState {
     #insertBinding(wiring, madeBy) {
         const iface = this.#ends(wiring);
         if (this.binding(wiring.consumer, wiring.slot))
-            throw new Refused("bound", `${wiring.consumer}'s ${wiring.slot} is already bound; unbind it first.`);
+            throw new Refused("bound", `${this.named(wiring.consumer)}'s ${wiring.slot} is already bound; unbind it first.`);
         const at = now();
         this.#db
             .prepare("INSERT INTO bindings (consumer, slot, provider, export, interface, made_by, at) VALUES (?, ?, ?, ?, ?, ?, ?)")
@@ -761,14 +922,19 @@ export class HubState {
         this.#emit(() => this.#events.bound?.(record));
     }
     #removeBindings(where, ...params) {
-        const removed = this.#db.prepare(`SELECT * FROM bindings WHERE ${where}`).all(...params).map(bindingOf);
+        const removed = this.#db.prepare(`SELECT ${BINDING} FROM bindings b WHERE ${where}`).all(...params).map(bindingOf);
         if (!removed.length)
             return;
-        if (removed.some((b) => b.consumer === PERSON && b.provider === HUB))
+        if (removed.some((b) => b.consumer === PERSON && b.provider === HUB && !b.exposed))
             throw new Refused("forbidden", "The person's hub bindings stay, so someone can always manage the Hub.");
         // Requests whose requester held its end through these bindings can't be approved any more.
         const open = this.#pending("1 = 1");
         this.#db.prepare(`DELETE FROM bindings WHERE ${where}`).run(...params);
+        // A slot made at run time goes with its binding.
+        const dropExposed = this.#db.prepare("DELETE FROM declarations WHERE actor = ? AND side = 'slot' AND name = ? AND dynamic = 1");
+        for (const binding of removed)
+            if (binding.exposed)
+                dropExposed.run(binding.consumer, binding.slot);
         this.#emit(() => this.#events.unbound?.(removed));
         for (const pending of open)
             if (!this.#standing(pending.request))
@@ -783,7 +949,7 @@ export class HubState {
     bind(caller, wiring) {
         const sides = this.sides(caller, wiring);
         if (!sides.export && !sides.slot)
-            throw new Refused("forbidden", `${caller} holds neither end of this binding.`);
+            throw new Refused("forbidden", `${this.named(caller)} holds neither end of this binding: the export side is ${this.named(wiring.provider)}, an Actor bound to that export, or a manager; the slot side is ${this.named(wiring.consumer)} or a manager. Ask one of them.`);
         if (!(sides.export && sides.slot)) {
             const has = sides.export ? "export" : "slot";
             if (!this.#asked(wiring, has))
@@ -805,9 +971,9 @@ export class HubState {
     unbind(caller, consumer, slot) {
         const binding = this.binding(consumer, slot);
         if (!binding)
-            throw new Refused("unknown", `${consumer}'s ${slot} isn't bound.`);
+            throw new Refused("unknown", `${this.named(consumer)}'s ${slot} isn't bound.`);
         if (caller !== consumer && caller !== binding.provider && !this.isManager(caller))
-            throw new Refused("forbidden", `${caller} can't unbind ${consumer}'s ${slot}.`);
+            throw new Refused("forbidden", `${this.named(caller)} can't unbind ${this.named(consumer)}'s ${slot}: its consumer, its provider or a manager can.`);
         this.#transaction(() => {
             this.#removeBindings("consumer = ? AND slot = ?", consumer, slot);
             this.#audit(caller, "unbind", {
@@ -818,6 +984,84 @@ export class HubState {
             });
         });
     }
+    /**
+     * Expose an export to one Actor: a slot made on `to` at run time, typed by the export's
+     * interface and bound to it, in one step. The authority is a binding's, with `to` as the
+     * consumer: with both ends it is made (approving any open request for it); with one, it is a
+     * request to the other end's approvers, who approve by exposing the same; with neither, it is
+     * refused. The same export already exposed to `to` gives that slot back.
+     */
+    expose(caller, input) {
+        const to = this.#open(input.to);
+        const provider = this.#open(input.provider);
+        // Authority first, as bind's: a caller with neither end learns nothing more.
+        const ends = { consumer: to.actorId, provider: provider.actorId, export: input.export };
+        const sides = this.sides(caller, { ...ends, slot: "" });
+        if (!sides.export && !sides.slot)
+            throw new Refused("forbidden", `${this.named(caller)} can't expose ${input.export} of ${this.named(provider.actorId)} to ${this.named(to.actorId)}: that takes the provider's side (it, an Actor bound to that export, or a manager) or ${this.named(to.actorId)}'s (it, or a manager). Ask one of them to expose it.`);
+        if (BUILTIN.has(to.actorId))
+            throw new Refused("forbidden", `${this.named(to.actorId)} is the Hub itself and takes no slots.`);
+        const offered = this.declaration(provider.actorId, "export", input.export);
+        if (!offered)
+            throw new Refused("unknown", `${this.named(provider.actorId)} offers no ${input.export}.`);
+        if (offered.iface.kind !== "rpc")
+            throw new Refused("unsupported", `Only an rpc export can be exposed; ${input.export} is ${offered.iface.kind}.`);
+        const same = (row) => row.provider === provider.actorId && row.export === input.export;
+        const already = this.bindings(to.actorId).find((b) => b.consumer === to.actorId && b.exposed && same(b));
+        if (already && (input.as === undefined || input.as === already.slot))
+            return { exposed: true, slot: already.slot };
+        const requested = this.#db
+            .prepare("SELECT * FROM requests WHERE status = 'open' AND exposed = 1 AND consumer = ?")
+            .all(to.actorId).map(requestOf);
+        // An open request's name for this export is taken again, so approving needs no `as`.
+        const slot = input.as ??
+            requested.find(same)?.slot ??
+            this.#freeName(to.actorId, exposedName(provider.name, input.export), requested);
+        if (!NAME.test(slot) || slot.length > EXPOSED_MAX)
+            throw new Refused("invalid", `${JSON.stringify(slot)} isn't a slot name: one word of letters, digits and _, at most ${EXPOSED_MAX}.`);
+        // A request reserves no name: the first exposure made under it has it, and the rest close.
+        if (this.declaration(to.actorId, "slot", slot))
+            throw new Refused("conflict", `${this.named(to.actorId)} already has a slot ${slot}; name another with as.`);
+        const wiring = { ...ends, slot };
+        if (!(sides.export && sides.slot)) {
+            const has = sides.export ? "export" : "slot";
+            if (!this.#asked(wiring, has)) {
+                const mine = requested.filter((r) => r.requestedBy === caller && !(same(r) && r.slot === slot));
+                if (mine.length >= MAX_OPEN_EXPOSURES)
+                    throw new Refused("limit", `${this.named(caller)} has ${MAX_OPEN_EXPOSURES} exposures to ${this.named(to.actorId)} waiting; wait for them to be decided, or withdraw one by exposing it.`);
+                const request = this.#ask(caller, wiring, "", other(has), true);
+                return { exposed: false, slot, requestId: request.requestId };
+            }
+        }
+        this.#transaction(() => {
+            // Settled: this slot's requests (approved if for this export), and this export's requests
+            // to `to` under other names, which can't be made any more.
+            const pending = this.#pending("consumer = ? AND (slot = ? OR (exposed = 1 AND provider = ? AND export = ?))", wiring.consumer, wiring.slot, wiring.provider, wiring.export);
+            this.#declare(to.actorId, "slot", slot, offered.iface, true);
+            this.#insertBinding(wiring, caller);
+            for (const open of pending)
+                this.#decide(open, same(open.request) && open.request.slot === slot ? "approved" : "closed");
+            this.#audit(caller, "expose", { ...wiring });
+        });
+        return { exposed: true, slot };
+    }
+    /** A name free on `to`: `base`, else `base_2`, `base_3`…, each within the longest name. */
+    #freeName(to, base, requested) {
+        const taken = (name) => !!this.declaration(to, "slot", name) || requested.some((r) => r.slot === name);
+        for (let n = 1;; n++) {
+            const suffix = n === 1 ? "" : `_${n}`;
+            const name = base.slice(0, EXPOSED_MAX - suffix.length) + suffix;
+            if (!taken(name))
+                return name;
+        }
+    }
+    /** Remove a slot made by `expose`, with its binding: its consumer, its provider or a manager may. */
+    unexpose(caller, to, slot) {
+        const binding = this.binding(to, slot);
+        if (!binding?.exposed)
+            throw new Refused("unknown", `${this.named(to)} has no slot ${slot} made by expose; unbind a declared slot instead.`);
+        this.unbind(caller, to, slot);
+    }
     /**
      * Ask for a binding the caller holds one end of; it goes to the other end's approvers. Asking
      * again for the same wiring while a request is open returns that request.
@@ -825,9 +1069,9 @@ export class HubState {
     request(caller, wiring, reason) {
         const sides = this.sides(caller, wiring);
         if (!sides.export && !sides.slot)
-            throw new Refused("forbidden", `${caller} holds neither end of this binding.`);
+            throw new Refused("forbidden", `${this.named(caller)} holds neither end of this binding: the export side is ${this.named(wiring.provider)}, an Actor bound to that export, or a manager; the slot side is ${this.named(wiring.consumer)} or a manager. Ask one of them.`);
         if (sides.export && sides.slot)
-            throw new Refused("state", `${caller} holds both ends: bind it instead.`);
+            throw new Refused("state", `${this.named(caller)} holds both ends: bind it instead.`);
         const has = sides.export ? "export" : "slot";
         if (this.#asked(wiring, has))
             throw new Refused("state", "The other end has asked already: bind to approve.");
@@ -841,10 +1085,12 @@ export class HubState {
             .map(requestOf)
             .some((request) => this.#standing(request));
     }
-    #ask(caller, wiring, reason, needs) {
-        this.#ends(wiring);
+    #ask(caller, wiring, reason, needs, exposed = false) {
+        // An exposure's slot doesn't exist until it is approved; `expose` checked its ends.
+        if (!exposed)
+            this.#ends(wiring);
         if (this.binding(wiring.consumer, wiring.slot))
-            throw new Refused("bound", `${wiring.consumer}'s ${wiring.slot} is already bound.`);
+            throw new Refused("bound", `${this.named(wiring.consumer)}'s ${wiring.slot} is already bound; unbind it first.`);
         const open = this.#db
             .prepare("SELECT * FROM requests WHERE status = 'open' AND requested_by = ? AND consumer = ? AND slot = ? AND provider = ? AND export = ?")
             .get(caller, wiring.consumer, wiring.slot, wiring.provider, wiring.export);
@@ -857,12 +1103,18 @@ export class HubState {
             reason,
             requestedBy: caller,
             at: now(),
+            ...(exposed ? { exposed: true } : {}),
         };
         this.#transaction(() => {
             this.#db
-                .prepare("INSERT INTO requests (id, consumer, slot, provider, export, reason, requested_by, at, status, needs) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'open', ?)")
-                .run(request.requestId, wiring.consumer, wiring.slot, wiring.provider, wiring.export, reason, caller, request.at, needs);
-            this.#audit(caller, "request", { ...wiring, needs, requestId: request.requestId });
+                .prepare("INSERT INTO requests (id, consumer, slot, provider, export, reason, requested_by, at, status, needs, exposed) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'open', ?, ?)")
+                .run(request.requestId, wiring.consumer, wiring.slot, wiring.provider, wiring.export, reason, caller, request.at, needs, exposed ? 1 : 0);
+            this.#audit(caller, "request", {
+                ...wiring,
+                needs,
+                requestId: request.requestId,
+                ...(exposed ? { exposed: true } : {}),
+            });
             const approvers = this.approvers(request).filter((a) => a !== caller);
             this.#emit(() => this.#events.requested?.(request, approvers));
         });
@@ -919,7 +1171,7 @@ export class HubState {
     decline(caller, requestId) {
         const request = this.requests(caller).find((r) => r.requestId === requestId);
         if (!request)
-            throw new Refused("unknown", `No open request ${requestId} for ${caller} to decide.`);
+            throw new Refused("unknown", `No open request ${requestId} for ${this.named(caller)} to decide; hub.grants.requests lists those it can.`);
         this.#transaction(() => {
             const [pending] = this.#pending("id = ?", requestId);
             if (pending)

package/{node_modules → dist/node_modules}/@agentorg/hub/dist/src/storage.d.ts

@@ -21,10 +21,11 @@ export declare class Storage {
      * Seed the store of (consumer, slot), all or none, if it holds nothing: `storage.admin@1`'s
      * `seed`. Each entry has kv@1's limits, and together they count toward the consumer's quota.
      */
+    /** `named` is the consumer as a refusal names it: "Name (id)". */
     seed(consumer: string, slot: string, entries: {
         key: string;
         value: unknown;
-    }[]): void;
+    }[], named?: string): void;
     /** Every store of an Actor, gone: it was closed for good. */
     deleteConsumer(consumer: string): void;
     /**