Federation and City

Service execution, business identity, and City ownership.

Federation owns account identity, AI, business Services, and the service database. City owns Agents, Groups, Workspaces, Powers, Storage, and HTTP/RPC transports.

import { Federation } from "@downcity/federation";
import { City } from "@downcity/city";

const federation = new Federation({ database });
// Register the account, AI, and business Services your application needs.
await federation.ready();
const city = new City();
city.federation.set(federation);

await city.close();
await federation.dispose();

Local Federation uses Request/Response, authorization, Actions, Hooks, and SSE in the current process. Remote Federation uses new Federation({ url, user_token }) with the same user/admin API. database and url are mutually exclusive. Construction does not choose a default database, install account or AI Services, or open a listening port.

User Token and Admin Session Token remain independent. The local server entry federation.fetch(request) uses the request's own identity. Trusted initialization can pass trusted_identity as an in-process method argument; HTTP headers and bodies cannot supply it. City Powers receive only the user access view.

City keeps an optional in-memory Federation binding. Use city.federation.set(client) to select a client and city.federation.set(undefined) to clear it. Read the selected client through city.federation.current. Setting a binding performs no network request and does not persist credentials.

City, Agents, Workspaces, Sessions, and local HTTP/RPC services remain available without a Federation login or connection. Authentication, network, and missing-model errors affect the operation that needs the remote capability. Changing the binding preserves local entities and Session history. Host model adapters must resolve the current binding when they need remote access; City does not replace models supplied directly by an application.

The host handles login interaction, account storage, and client disposal. Multiple Cities can borrow one instance. When selecting a different target or account, prepare a client and bind it to the City. Release the previous client only after its dependent work has finished.