Multiple Cities and Federation

Multiple Cities and Federation

A Federation user session owns identity, permissions, and Credits. City owns Agents, Workspaces, Powers, and local runtime resources. City borrows a local or remote Federation; its host remains responsible for disposing Federation after dependent work finishes.

import { Federation } from "@downcity/federation";
import { City } from "@downcity/city";
import { resolve_local_city_id } from "@downcity/city/local";
const federation = new Federation({ url: federation_url, user_token });
const city = new City({ federation, city_id: resolve_local_city_id(root_path) });

CLI/Desktop persist a stable source in the host root city-id file across restarts. A process instance_id is separate for each launch. An in-memory City can omit city_id to get a temporary label. Sign-in and direct user requests require no City.

City model and Power requests use the same source. Independent callers can create fixed source views:

const first = federation.user.with_city("city_first");
const second = federation.user.with_city("city_second");
await Promise.all([
  first.service("reports").action("create").invoke({}),
  second.service("reports").action("create").invoke({}),
]);

Views share user credentials while keeping their sources separate. The x-downcity-city-id header records source in request context, usage, and jobs. Labels have 1–128 ASCII letters, digits, underscores, or hyphens and start with a letter or digit. This is caller-supplied information, not machine identity or authorization. Private resources require authenticated ownership or active organization membership.

Desktop profile, Credits, and model calls use host DOWNCITY_FEDERATION_URL / DOWNCITY_USER_TOKEN first, then the saved session for that target. The account page shows active overrides. Saved accounts remain available after overrides are removed. Workspace environments cannot change the host target.