Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
Eidoverse Worlds integration
Eidoverse Worlds is an optional, disabled-by-default PortOS feature. It is not vendored into PortOS and is not a git submodule. Choosing Install & enable under Settings → Features is the explicit consent boundary that downloads, installs, and enables the runtime; the ordinary feature toggle never installs it. If Bun is not already available, the same action first runs Bun's official platform installer under the PortOS service account on Windows, macOS, or Linux.
Signal ownership
server/services/eidoverseWorldSources.js owns local reads, cancellation, Jira
fetching, and destination lookup. It passes snapshots to the pure
server/lib/eidoverseWorldSignals.js owner for bounded aggregates and stable
opaque IDs. server/services/eidoverseWorldProjection.js then plans world verbs
from those signals. World orchestration loads the collector only during explicit
projection; identity and travel consumers import the pure signal owner directly.
The collector and world service retain their historical helper exports.
What PortOS installs
The installer keeps the two AGPL-3.0 projects as independent git checkouts. The
Worlds repository is selected per PortOS instance. The recommended default is
https://github.com/atomantic/eidoverse-worlds on branch portos; an instance
owner can enter another GitHub origin and branch before installing:
data/repos/{owner}/{repo}— the selected Worlds repository and the checkout PortOS registers under Apps. Ordinary GitHub forks retain theeidoverse-worldsrepository name.data/repos/anima-research/eidoverse-video— the upstream video/runtime checkout used by Worlds. A fork is not required unless changes to that repository itself become necessary.
PortOS runs bun install --frozen-lockfile in the Worlds root and client, then
writes an ignored .env.portos file that points Worlds at the video runtime and
at its durable world store. PortOS does not copy either project's source into
the PortOS repository, combine the codebases, or relicense them; each checkout
retains its own upstream license and git history.
After installation, Worlds GitHub repository and Worlds runtime / tracking
branch remain available on Settings → Features. Recommended (portos)
selects the recommended origin and branch; Update source applies the choice
in place. Branch changes require a clean checkout and refuse to overwrite local
commits absent from the target. Restart or update the managed app to load the
changed code. App updates honor the selected branch using the checkout-local
portos.runtimeBranch Git setting; clearing the field restores the origin default
branch on the next update. Existing saved choices are preserved. The managed-app
path, world data, and companion video origin remain unchanged.
The managed app's Git tab makes that two-repository topology explicit. It
shows the checked-out branch and revision for Worlds and Video, compares each
checkout with its configured origin, and—when Worlds points at an ordinary
GitHub fork—compares that fork with the canonical
anima-research/eidoverse-worlds upstream. A failed network comparison is
reported as unknown rather than as current.
Sync fork only fast-forwards the configured Worlds fork on GitHub without
changing either local checkout or restarting a process. PortOS never passes
--force, so a fork with its own incompatible commits is left untouched for
manual reconciliation. Update both pulls Worlds from its configured origin,
pulls the independent Video checkout from its own origin and branch, installs
Worlds' frozen Bun dependencies, and restarts only Eidoverse. Video is therefore
managed as a version-visible sidecar, not pinned as a PortOS submodule.
That topology is only visible to someone who goes looking for it, so freshness
is also reported where a user actually lives. Opening Eidoverse runs the
same repository-source check once per visit and, when a checkout or its fork is
behind something the update can pull it forward from, raises an advisory above
the world naming what is behind and offering the same one-click managed update.
Dismissing it silences that revision only — the next Eidoverse release raises it
again. The check is scoped to this page rather than added to the global PortOS
update banner because it costs a git fetch on both checkouts plus GitHub fork
metadata, which is not a price every screen should pay.
The advisory reports only drift an update can actually clear. The Video checkout
is cloned from a third party's fork of the canonical project, and PortOS can
read that fork but never push to it — so when it falls behind its own upstream,
neither gh repo sync nor a pull from its origin can move it, and an advisory
raised for that drift would never clear. PortOS therefore counts a fork toward
"update available" only when it is the application checkout's own fork, the
credential can push to it, and it has not diverged (isForkSyncable in
server/services/managedAppRepositories.js, surfaced to the client as each
source's forkSyncable). The drift is still reported on the app's Git tab,
where the card explains why no button there clears it.
Runtime and data ownership
The managed app uses port 8940 and starts with the Bun executable found or
installed during setup:
<bun> --env-file=.env.portos server/server.ts
Once installed and enabled, PortOS starts the runtime automatically at server
boot and when the feature is enabled. It waits for readiness, opens the host
bridge, reconnects the resident CoS presence when that presence is enabled, and
reconciles pending world-design updates. This startup never installs missing
dependencies, downloads assets, or calls an AI provider. A disabled feature does
not auto-start the runtime; manual app controls remain available. Start, stop,
logs, updates, and launch links remain visible on the normal managed-app screen.
Command-based Eidoverse launches use a 2 GB PM2 memory restart limit so the
loaded world and asset runtime can exceed the generic app limit of 500 MB.
Plain-HTTP managed apps
keep an http:// launch URL even when PortOS itself is open over HTTPS, so the
Apps launch action works from a Tailscale MagicDNS session. Managed updates pull
both the selected Worlds checkout and its companion video runtime before using
Bun's frozen lockfile rather than npm.
When the feature is enabled, Eidoverse is the primary PortOS world surface. Opening it starts the managed app when needed and embeds its web client in a full-width PortOS page. The retired OpenWorld paths remain as compatibility redirects to Eidoverse, so old bookmarks do not create a second world renderer.
Durable Eidoverse world logs live at data/eidoverse/worlds. This is
machine-local file-primary data: PortOS backups include it, but PortOS does
not federate it to peers. The git checkouts remain under data/repos, which is
the existing re-cloneable repository backup class.
Private persistence and identity
This is a private world for one PortOS install. It is not a public Eidoverse world and PortOS does not publish its world records or expose them through the peer-sync record layer. Trusted machines may reach the instance through the install's existing Tailscale boundary; the install remains the authority for the world and its history.
PortOS-owned integration state is stored in
data/eidoverse/portos-world.json. It contains the selected world, the human
display name, the stable Persistent Mind/CoS identity and local role
observations, the projection recipe, and the last projection checkpoint.
The human name can be configured explicitly. If it is cleared, PortOS derives a
stable pseudonymous label from the persisted instance id without placing the
raw id or the machine's display name in the Eidoverse log.
The V1-to-V2 migration recognizes the old instance-name source marker and
retires only that automatic value; an explicitly configured name is preserved.
Because Eidoverse history is append-only, PortOS does not rewrite prior log
entries, but it no longer joins or projects with the retired machine name.
The browser receives that same identity in the Eidoverse launch URL, so a
reload or a second trusted machine does not create a new anonymous user.
The default installation uses Eidoverse's name-based join protocol with the
empty join-token setting; the URL supplies the durable world, name, and avatar
instead of inventing a browser-local account. If an operator later adds a
join-token policy in the independent Eidoverse runtime, that policy remains an
explicit runtime configuration rather than a secret stored in PortOS state.
The Eidoverse runtime remains responsible for its own append-only world log,
snapshot, roles, chat, poses, and assets under data/eidoverse/worlds. PortOS
joins through the runtime's public WebSocket protocol and never edits the
external checkout to seed content. On a fresh world, PortOS establishes the
configured human identity first so it can own the world, then reconnects the
stable CoS identity as an agent and grants it an owner role. Eidoverse reserves
terrain, sky, and role handoff for owners, so the persistent CoS must retain
that role to maintain the projected world and hand ownership to a renamed
human identity. Once the new identity owns the world, PortOS demotes the prior
identity to visitor so a rename does not leave a stale owner behind. PortOS
exposes that authority through the separate, disabled-by-default Manage the
private Eidoverse world grant in both the Persistent Mind controls and the
local Agent Tools (MCP) controls; generic PortOS write access does not imply it.
This makes both the human and CoS roles durable in the Eidoverse world rather
than browser-session conveniences.
World Design V3: PortOS Commons
Commons arranges eight inward-facing halls around a grassy arrival park.
A broad circular promenade and short paths link rounded gathering terraces;
trees, planted beds, and timber seating soften the edges. The center stays
clear for pedestrian agents, Persistent Mind avatars, and human guests.
Buildings use Eidoverse's existing comp.structure grammar: tiled floors,
glass frontage, open archways, walls, and roofs, with native collision.
Large district landmarks sit on rooftop plinths behind the frontage. Their
measured bottom and animation clearance keep the entrance and physical sign
visible. Accent-edged paths and shallow entrance canopies connect each hall
to the promenade. These geometry changes reconcile through the existing V3
projection without resetting user overrides or visitor-authored objects.
A deterministic GLB adds walking surfaces, decorative seating, and physical
district signs through Eidoverse's ordinary content-addressed upload API.
Each install reuses the verified recipe-derived asset on later projections.
Library geometry summaries are measured once per resolved path and retained in the asset locks. Placement compensates model-origin offsets and fits a semantic size envelope; native structure anchors and the city surface retain their authored coordinates. Desktop computers sit at the measured desk height.
The portable recipe resolves desks, retro terminals, crates, barrels, palms, and streetlights from each install's own library. Furniture stays inside the buildings or beside entrances. Arcade computers sit on individual desks, with the first eight workstations inside the hall and overflow on its terrace. Other bounded live signals occupy distinct bays beside the entrance aisle, sharing the existing 48-signal budget. Decorative furniture has no floating label. Semantic landmarks and signals keep their optional annotations, hidden at the start of each visit until the user activates the Labels toolbar toggle or chooses a label mode in World controls.
V1 and V2 defaults remain immutable migration baselines. The V3 migration preserves explicit overrides, aliases, and the last successfully applied version. Changed asset slots invalidate their resolution fingerprints; unchanged locks remain reusable. Existing managed identifiers stay stable, obsolete trail markers are retired by normal reconciliation, and unrelated visitor-built entities remain untouched. Failure compensation restores native structure components through the existing component rollback path.
No Eidoverse framework change is required. Physical signs are authored scene geometry; camera-facing clickable labels are a separate, optional renderer capability. Building room labels describe topology and do not render signs.
World Design V2: Luminous Systems Garden
PortOS ships a versioned world-design recipe, not a one-instance scene. World Design V2 replaces V1's numbered resource lanes with eight stable semantic districts:
| District | PortOS meaning |
|---|---|
| PortOS Nexus | Aggregate health, operations, and feature affordances |
| App Terraces | Managed apps and their coarse runtime state |
| Agent Foundry | Active agents and bounded CoS task summaries |
| Goal Observatory | Goals and current-sprint Jira summaries |
| Memory Grove | Category and graph aggregates, never memory bodies |
| Data Vault | Bounded PostgreSQL and file-domain summaries |
| Federation Harbor | Coarse peer availability summaries |
| Activity River | Productivity and recent activity aggregates |
The authored environment is part of the design contract: deep slate/indigo
terrain, a warm dawn skymesh, three deliberate lights, restrained fog, and a
sparse wind-reactive field. District anchors have distinct silhouettes and
accent colors. Abstract metrics no longer use generic car meshes. Entity
position is derived from stable source id plus district anchor, so source array
reordering does not move the world around. Goal progress lifts its constellation
beacons, while activity summaries follow a shallow, stable river bend.
The central Nexus light follows aggregate health: cyan is healthy, amber needs attention, and red is an error. The corresponding health beacon also changes shape, elevation, and motion, so the status remains legible without color.
Every projected record is normalized to a bounded WorldSignal component. It
contains a one-way stable resource key, generic safe label, controlled
status/severity/freshness values, district, PortOS route, disclosure class, and
a shallow set of numeric/boolean metrics. Nested collections become counts and
arbitrary strings are discarded. Apps become a few status-count pylons rather
than one anonymous rack per app; storage becomes two aggregate landmarks plus
bounded anomaly markers; Jira becomes current-work status counts. PortOS never
places raw journal/memory bodies, database or file names, task prompts, ticket
titles, machine/peer identities, or federation records in the Eidoverse log.
The default per-family caps sum below the hard global ceiling, and a user-edited
recipe still cannot materialize more than 48 live PortOS signals.
When authored caps would exceed that ceiling, PortOS allocates one signal per
included current-or-stale source before filling additional slots in
deterministic rounds. The drawer reports the exact per-source omissions instead
of showing a populated source count beside an unexplained empty district.
Only ids under portos-design-v2-* and the retired V1
portos-projection-* namespace are reconciled. Unrelated Eidoverse entities are
never moved or removed. A temporarily unavailable PortOS source preserves its
last-good entities; a confirmed empty source retires that source's managed
entities. The eight district landmarks, luminous connector nodes, and three
authored lights are infrastructure rather than live records.
Assets are a recipe, not a payload
PortOS does not bundle model packs. server/lib/eidoverseWorldDesign.js stores
small semantic slots such as nexus, agent, memory, and peer. Each slot
declares:
- preferred Eidoverse library paths;
- fallback search queries;
- semantic filename tokens used as ranking hints and whole-token exclusions;
- maximum bytes, GLB/animation expectations, and
library-onlysource policy; - a final known-library fallback.
On first projection after an install or recipe update, PortOS reads
/library-list, uses /library-models only for unresolved slots, rejects
content-addressed store/<hash> paths for portable defaults, verifies each
chosen /library/... asset, and ranks candidates deterministically. It then
persists the exact path, byte-size metadata, design/recipe/slot versions, per-slot
recipe fingerprint, strategy, catalog fingerprint, resolution time, and
default-versus-user source in assetResolutions. Normal projections reuse that
lock and do not repeat model searches. A later design release invalidates only
slots whose recipe fingerprint changed; unchanged paths and local overrides
remain pinned. Eidoverse owns and caches the bytes. A user may retain an
explicit install-local store/... model override, but that path is recorded as
an override and never becomes a shipped PortOS default.
Search results remain eligible when a library rename removes an old filename
token, and a safe catalog GLB is the final deterministic fallback after searches
are exhausted. Catalog entries without byte metadata remain usable with
bytes: null; a known over-budget size is still rejected.
Versioning, updates, and recovery
data/eidoverse/portos-world.json schema V3 records
selectedDesignVersion, lastAppliedDesignVersion, pendingDesignVersion,
userOverrides, assetRecipeVersion, assetResolutions, migrationReport,
and the reconciliation checkpoint/error. The immutable V1 and V2 registries are
both retained in source.
Migration 323-eidoverse-world-design-v2.js runs in the normal PortOS migration
pass used by update.sh, update.ps1, and ordinary server boot. It compares
every stored V1 leaf against the immutable V1 default: a default-matching leaf
inherits V2, while a genuinely customized leaf becomes a V2 user override.
Customized V1 source caps above the corresponding V2 cap are reset to the V2
default and their original values stay visible under unsupported overrides,
preventing an old lane-scale cap from starving the semantic districts.
V1's lane coordinates have no safe district translation, so a custom layout is
reported rather than silently applied. Missing state is a fresh V2 install;
invalid or newer schema state fails closed and remains pending for repair or a
PortOS update.
Migration 325-eidoverse-video-companion.js backfills the canonical Video
checkout into older Eidoverse managed-app registrations. This lets those
installations use the same two-checkout managed update path after upgrading
PortOS without rewriting their selected Worlds origin or world data.
The offline migration never touches an external checkout or calls an AI
provider. It leaves V2 pending. After restart, a deterministic reconciler runs
only when the separately managed Eidoverse process is already online. It
preflights runtime build identity, the catalog, and every selected asset before
sending world operations. Reconciliation is staged: infrastructure and live
signals are created first, the managed environment follows, and only then are
obsolete V1 ids retired. Every acknowledged operation has an inverse derived
from the pre-update snapshot. A failed stage reconnects, applies those inverses
in reverse order, retains the old lastAppliedDesignVersion, and leaves a
resumable checkpoint. If Eidoverse is stopped or incompatible, PortOS leaves
the update pending and the page links directly to the managed app instead of
claiming the world is current.
A process restart during an applying or compensating stage marks that persisted
run as interrupted before boot reconciliation; the drawer then offers the same
explicit retry path as other failures. Retired owner-role cleanup is
best-effort and never blocks the current world: failed demotions retry up to
three projections, then age out with a generic manual-review warning. A later
clean run clears that warning, and a full reset clears all recovery state.
On a genuinely fresh world there is no previous atmosphere to protect, so the dawn environment is applied first and the user does not wait in darkness while the initial landmarks and signals stream in. The stricter order above remains mandatory for every upgrade with a previously applied design.
The hosted page retains a loading curtain until the embedded renderer arrives, then leaves the scene unobstructed. PortOS refresh, configuration, and standalone launch actions live in the page header rather than over the renderer. District, indicator-capacity, and reconciliation details stay in the World Design drawer, where they remain available without covering Eidoverse's own chat and world tools. World controls opens the shared tabbed drawer:
- Experience — durable identity and high-level design status;
- Districts & Data — source visibility, counts, current/stale state, direct PortOS routes, caps, and district resets;
- Appearance & Assets — dawn environment, selected size/source, local overrides, and the persisted asset recipe;
- Updates & Advanced — migration diff, checkpoints, apply/retry, asset re-resolution, and a two-step full reset.
The Persistent Mind and explicitly granted local CoS agents can use the
governed eidoverse.status, eidoverse.project, eidoverse.augment, and
eidoverse.say tools. eidoverse.augment accepts only bounded world verbs (for
example spawn, place, comp, light, terrain, sky, and grant); it
cannot execute arbitrary runtime behavior or modify the installed Eidoverse
source. Status requires bounded PortOS read access. Projection, augmentation,
and world chat retain the dedicated Eidoverse-management grant without widening
generic PortOS record-write authority.
Bounded local scene inspection. eidoverse.inspect-scene (provider alias
eidoverse_inspect_scene) requires manageEidoverse for minds and agents,
using the same local world-management authority as augmentation. It reads the
already admitted local connection; it never joins, starts the runtime, projects,
places objects, visits a peer, or adds a federation channel. If disconnected,
open/start the existing Eidoverse world through its normal controls first.
Input is exactly { anchor: [x, y, z], radius, limit? }: three finite coordinates
in [-10000,10000], spherical radius in (0,100], integer limit 1..12
(default 8), no extra keys. Use a new semantic requestId for a fresh read;
replaying one returns its original result under the common dispatch contract.
Output is exactly:
{
availability: "current" | "unavailable" | "incomplete",
sequence: integer | null,
observedAt: ISO timestamp | null,
complete: boolean,
truncated: boolean,
boundsComplete: boolean,
unknownBounds: nonnegative integer,
invalidEntities: nonnegative integer,
entities: [{
id: stable entity id,
pos: [x,y,z], yaw: radians, scale: positive number,
asset: normalized library model reference | null,
portosManaged: boolean,
bounds: {min:[x,y,z], max:[x,y,z]} | null,
boundsState: "known" | "unknown"
}]
}
sequence is the current authored log cut (including the snapshot's already
folded tail), then advances with contiguous live updates. observedAt records
when the response was assembled after draining received messages. Added, moved
and removed entities come from those updates, rather than the join handshake.
Sequence gaps, unknown spatial verbs and world resets invalidate completeness;
a new valid snapshot restores it. Closed/failed connections and snapshots without
a verifiable cut are unavailable. This is a point-in-time authored view, not a
reservation against later movement or construction.
Measured static model bounds become world AABBs by transforming all eight
corners with the authored position, yaw and scale. Known boxes intersecting the
sphere are returned even if their origin is outside it; entities with unknown
bounds are selected by their authored origin. Model summaries must be finite,
ordered, nondegenerate and within the coordinate range; transforms require a
finite yaw within ±2000π and scale in (0,100]. Malformed transforms and
parent-relative entities are omitted and counted in invalidEntities.
complete means every selectable entity in this query was enumerated.
boundsComplete additionally requires no invalid or unknown bounds anywhere
in the retained world view, because an unmeasured object outside the query
might extend into it. unknownBounds is that global count, not just returned
rows. An empty list with incomplete enumeration or unknown extents never
certifies an area clear. Even measured bounds describe authored model geometry,
not terrain, avatars or the full rendered scene. Procedural components, motion,
attachments, runtime behaviors and deterministic simulation are not evaluated;
their geometry remains unknown. Unsupported component/dynamic flags stay
conservative until a replacement spawn or fresh snapshot resolves them.
Inspection retains at most 2000 authored entities (more means incomplete),
fetches at most 16 unique model summaries per call with a shared two-second
budget, and reads at most 64 KiB per summary. Failed or oversized summaries stay
unknown. Whole result rows are capped at 3000 serialized characters, below the
mind's 4000-character semantic envelope budget; count or character clipping sets
truncated: true and complete: false. There is no pagination or clearance
certificate. Use smaller spatial queries to inspect candidate anchors.
Only eidoverse/assets/models/...glb library references and content-addressed
store/<16..64 lowercase hex>.glb references can appear as asset; all other
references become null. No raw component bags, record contents, chat, tickets,
actor identities, URLs, filesystem paths, error bodies or credentials are
exported. portosManaged reads only comp.portos.managedBy === "portos";
keep those existing projected objects intact. A small synthetic workflow uses
five calls: status → inspect occupied anchor → inspect alternate anchor →
augment original objects → inspect the result. Inspection itself places nothing.
Proposal vs consequence. eidoverse.augment is a two-phase contract, not a
direct write: a mind's call is a proposal (structured verb+args intent), and
only the world's own ack determines the consequence. The result's
operations array carries one outcome per submitted operation — accepted
(landed exactly as proposed), rewritten (the world acknowledged it with
different committed args than proposed, e.g. a clamped value), or refused
(PortOS's own bounds check or the world itself rejected it, and nothing
landed) — each with proposed/committed payloads so a mind cannot narrate a
build that never happened. A world-level refusal stops the rest of that batch
from being sent, since later operations often reference an id an earlier one
was meant to create. eidoverse.say is simpler — it either resolves with
committed: true once the world acks the message, or the tool call fails
outright, so a failed send can never be mistaken for a sent one.
Growth and automation
The world-design recipe and per-install asset lock are intentionally separate
from the current world log. As PortOS gains resources, the deterministic
projection runs when the hosted page opens and can also be run manually, from a
CoS task, or through the disabled-by-default autonomous job
job-eidoverse-projection. Enabling that job is an explicit install-local
choice; it performs no provider calls and only reflects resources that already
exist. The hosted page starts the managed runtime when it is opened; an
automated projection run expects that managed app to remain available, and
records a failed run instead of silently publishing stale or fabricated data.
CoS tasks can also augment the world with bounded authored landmarks or
messages, while recipe changes remain visible and editable in PortOS.
Disabling the feature hides the optional navigation entry but does not delete
repositories, unregister the app, stop a running process, block the direct
/eidoverse route, disable a separately configured projection job, or remove
world history. Destructive uninstall remains an explicit manual operation.
Network boundary
This integration is intended for the same private, single-user Tailscale trust boundary as PortOS. Eidoverse binds its server to the host network and permits an empty join token; do not expose this configuration to the public internet. An instance that needs a broader trust model should configure Eidoverse access control in that project before starting it.
Eidoverse itself remains a plain-HTTP service on :8940. The embedded page
starts the on-demand PortOS host and loads the renderer at the same origin
as the PortOS UI — ${location.origin}/eidoverse-host/?… — so a single-port
tailcat forward (127.0.0.1:15555 → remote :5555) works. The main :5555
server reverse-proxies /eidoverse-host to loopback :8940 (prefix stripped)
and, while the host is active, also forwards allowlisted absolute root routes
the renderer issues (/ws, /version, /library/…, /node_modules/…, …),
including the WebSocket upgrade for /ws. Both external repositories stay
unchanged. The host starts only when the page is opened, waits for the managed
app to answer before mounting the iframe, and returns an explicit unavailable
state when the runtime does not become ready.
An optional legacy bridge on :5563 still starts with the host (HTTPS when a
machine certificate is present) for ExternalLink / direct access on the box.
The iframe prefers the same-origin path; the single escape is a plain-HTTP page
in front of an HTTPS-only host certificate that does not cover the hostname
(loopback :5553 / some Vite setups), where the iframe falls back to a direct
:uiPort load — scene renders, handshake stays dormant.
World only / Open Eidoverse alone opens /eidoverse/solo — a chromeless
PortOS route that mounts the same /eidoverse-host/ iframe fullscreen
(outside the app sidebar). A top-level Safari tab aimed at /eidoverse-host/
can stick on the renderer splash; staying inside PortOS reuses the proven iframe
path through a single-port tailcat forward.
Projection protocol and asset preflight target the same runtime. The default
HTTP library origin is derived from EIDOVERSE_WS_URL by mapping ws/wss to
http/https on the same host and port. Deployments whose one Eidoverse runtime
publishes separate WebSocket and HTTP endpoints may set EIDOVERSE_HTTP_URL
explicitly; both values must identify that same runtime.
PortOS bridge boundary
The hosted page, identity bridge, projection service, and CoS tools are explicit PortOS adapters across the two projects' public protocols. They remain deterministic and install-local: opening PortOS does not call an AI provider, and no raw Eidoverse world log is copied to another machine by federation.
Object labels, aliases, and the saved legend
PortOS emits a generic comp.label beside each owned object's comp.portos:
{name, description?, visibility: 'nearby' | 'always' | 'inspect', offset?}.
District and world landmarks use always, bounded by the renderer's range;
live indicators use nearby; walkway markers use inspect. Ordinary refresh
adds labels to existing worlds. One projector helper updates the label and the
saved object legend together, including stale retained indicators. Repeating an
unchanged projection emits no label verbs. Removed managed entities take their
labels with them; foreign entities and their labels are preserved.
World controls → Districts & Data shows the last successful projection by district: semantic name, meaning, label mode, model path, and resolution reason. Search matches and catalog/recipe fallbacks are explicitly called fallbacks. A retained model whose path differs from the current resolution lock reports unverified provenance. The link to Appearance & Assets uses the existing asset override, refresh, and reset controls. The legend remains readable with floating labels off and on older renderers. Agent-tool, scheduled-job, and boot projection results use the service's compact response: operation summary, object count, and presence. The full legend remains in saved projection state for the drawer.
Optional aliases name individual live indicators using stable opaque resource keys, never private record IDs or titles. The configuration accepts at most 128 aliases, each plain text of at most 72 characters. Clear the field to restore the generic label. Every alias field displays its opaque resource reference, including when multiple objects share a display name. Aliases for absent objects remain editable in Saved aliases without a current object, so users can free slots without resetting a district or losing aliases during a temporary outage. Saving an alias explicitly publishes that display text into the private world's append-only history; removing it changes the current label, not older history. Asset resets preserve aliases; district/all resets clear the matching aliases. Migration 343 upgrades existing config to schema V3, preserving custom recipes and asset locks, and initializes an empty alias map without reading private records. No config seed or raw-data backfill ships. Older PortOS versions reject the newer config schema rather than discarding the aliases.
Renderer capabilities and frame contract V1
The external Worlds checkout remains the sole renderer. Its half of this
contract shipped in
Worlds issue 5 and
Worlds issue 7.
End-to-end label/picking/touch/keyboard acceptance requires that companion;
producer and frame-contract tests alone do not establish it, so
scripts/eidoverse-frame-acceptance.mjs drives the whole exchange against a
disposable synthetic world in a real browser. It is deliberately outside CI —
it needs the installed checkout, Bun, Playwright and a real Chrome — and it
never touches the install's own world under data/eidoverse/worlds.
GET /version advertises independently versioned capabilities alongside its
existing build identity:
{"sha":"example-build","commitTime":"2026-01-01T00:00:00Z","capabilities":{"objectLabels":1,"portosNavigation":1,"labelPreferences":1}}
Missing, malformed, or unknown capability versions do not block projection. The drawer shows an update/reload action when label support or the frame bridge is unavailable. Updating the managed checkout preserves PortOS design settings, explicit aliases, and asset overrides. The actual frame handshake takes precedence over the server capability report, so a stale browser bundle cannot pretend it supports the updated runtime.
After each iframe load, PortOS posts to its exact hosted origin:
{"type":"portos:connect","version":1,"nonce":"fresh-opaque-session","capabilities":{"portosNavigation":1,"labelPreferences":1,"identityRenameRequest":1},"labelVisibility":"nearby"}
The renderer validates event.source === parent and the embedding PortOS origin,
then replies to that exact origin with eidoverse:ready, echoing version and
nonce and advertising its supported capabilities. The renderer must obtain
the expected parent origin from its trusted embedding configuration; accepting
an arbitrary opener as the parent is not sufficient.
PortOS supplies that configuration. The renderer reads it from
GET /embed-config, which PortOS answers itself rather than forwarding: on the
same-origin /eidoverse-host mount (and the root allowlist proxy) the
parentOrigin is the full browser Host including a non-5555 forward port
(e.g. http://127.0.0.1:15555); on the legacy :5563 bridge it is the PortOS
page origin (hostname + API port), not the bridge port. The checkout's static
EMBED_PARENT_ORIGIN is deliberately left unset, because one install is
reachable as localhost, as a LAN address and as a MagicDNS name, and a single
configured origin could only ever match one of them — an unmatched origin leaves
the frame bridge silently dormant. A request whose Host is unusable resolves
to no embedder rather than to a repaired guess, since the browser compares
origins with === and a repair would be a silent mismatch at handshake time. Each later message carries
the same version and nonce. A reload invalidates the prior session. Unsupported
clients simply ignore the handshake and continue rendering.
For a user-triggered Open in PortOS, the renderer sends
{type:'eidoverse:navigate', version:1, nonce, entityId, route}. PortOS requires
all of: the current iframe window, its exact origin, the current nonce, a V1
navigation-capable handshake, an entity present in the saved projection legend,
and exact equality between the requested route and that object's known PortOS
section route. Only the fixed source-section routes (plus /eidoverse) are
allowed. URLs, query strings, encoded/relative paths, record payloads, and
unknown entities cannot navigate. No URL proxy is exposed.
When both sides advertise identityRenameRequest: 1, /name <new name> and
/rename <new name> in the home-world renderer send
{type:'eidoverse:identity-rename', version:1, nonce, name}. PortOS accepts the
request only from the current iframe window, exact hosted origin, and current
nonce, and only for a trimmed 1–64 character name without control characters.
The request stages the existing World Design human-name field and opens its
Experience tab; it cannot write configuration, change an actor id, or rename a
live session. Save and project uses the normal validated configuration path,
reconciles presence, and re-enters the world with the saved URL identity. Older
renderers keep the manual World Design flow. Standalone, authenticated, and
guest sessions retain their authoritative identity and receive guidance instead
of sending a host configuration request.
The Eidoverse framework leaves object labels off by default. PortOS explicitly enables
them through its trusted frame session only after the user enables Labels. Each
visit starts with off; an older stored always-on preference does not enable
an overlay. The toggle and World controls change only this visit's view.
Labels are positioned over their objects; clicking or tapping one opens its semantic
name and description, with Open in PortOS supplied only by our fork. The old detached
object dropdown and armed inspection buttons are removed.
Floating-label preference is browser-only: nearby respects authored modes,
all-nearby includes authored inspect-only objects within 60 metres,
and off hides floating labels while keeping selected-object details accessible.
PortOS sends portos:label-preference with version, nonce, and
labelVisibility only after the frame advertises V1 preference support. A
preference change never sends a world verb or rewrites configuration. The
renderer owns distance culling, object picking, and accessible selected details.
Federated guest travel
The Federation Terminal gives every connected, guest-capable peer a walk-in
visitor chamber. Chambers are infrastructure rather than sampled health signals,
so the live signal cap cannot silently omit a destination. Inspect a chamber
and choose Teleport as guest, or use the destination buttons above the world.
With an objectInteraction: 1 renderer, approach a visible pod within three
metres and press E, or tap its action prompt. This works with labels hidden.
The local controls name the destination; the authored chamber uses an opaque
reference rather than writing machine names into the world log. Destination
changes refresh the projection while the page is open and its draft is saved.
Departure checks the saved peer and its current capabilities, admits a fresh
visitor identity, and opens that host's /eidoverse/guest page. Before navigation, PortOS
requires the departing renderer's worldDeparture: 1 acknowledgement
when supported: presence and reconnect attempts stop, then the socket closes.
PortOS waits for a blank replacement frame before navigating in the same tab;
older renderers use that frame teardown as their compatibility path. Returning
through browser history restores the home frame. This moves the human visitor;
the install's resident CoS presence continues to belong to its home world.
The guest shell
loads its renderer without owner controls or private PortOS bootstrap requests,
including when the destination uses the optional instance password. An existing
Eidoverse browser login cannot replace the guest identity. Leave world returns
to the previous page. Admission links expire after 30 minutes.
Both ends need updated PortOS, Eidoverse enabled and running, and a renderer that
advertises guestEntry: 1; the host needs its resident CoS presence enabled to
admit visitors. Older runtimes remain unavailable for travel until updated.
For the Persistent Mind, enable Allow guest travel and chat with federated
worlds in its tool permissions. This is the separate visitEidoversePeers grant,
which defaults off and does not follow from local world-management permission.
The corresponding semantic MCP grant is available in API Access settings.
| Tool | Purpose |
|---|---|
eidoverse.destinations |
Discover connected registered guest worlds. |
eidoverse.visit |
Join a destination by its opaque peerId; returns a visitId. |
eidoverse.visit-chat |
Read live replies after a cursor; optional text sends one message. |
eidoverse.leave |
Disconnect the guest visit. |
eidoverse.chat |
Read the resident's live local chat (readPortos). |
eidoverse.say |
Reply locally as the resident (manageEidoverse, unchanged). |
Visits do not move the resident presence or give a visitor construction rights. Guest chat starts with the visit, is bounded and cursor-based for the Mind, and never automatically exports stored conversation history or private records. Incoming chat makes no AI call and is never an instruction or permission grant. The guest-conversation ADR documents this narrowly scoped exception to the machine-local record policy.
Vernacular labeling on a visit (#7459). A guest visit reaches only what the
destination install chose to build in its own private world — its local
vernacular style and buildings — never the shared PortOS baseline population,
which has no visit surface of its own. Both entry points say so explicitly
rather than leaving a visitor to infer it: eidoverse.visit's response
guidance tells a visiting Mind in the same turn it receives a visitId, and
the human guest shell (client/src/pages/EidoverseGuest.jsx) carries the same
line in its header. This is a labeling change only — nothing about what
crosses the federation layer changes: the vernacular/baseline ownership model
(below) already keeps a foundation's style and its whole local ledger out of
every peer exchange, and a guest visit was never a foundation-ledger read.
Object controls
The Commons island extends into an irregular grassy shoreline, a sandy beach,
an eight-kilometre ocean horizon, and distant mountain islands. This is bounded
authored scenery, not an infinite terrain-streaming or swimming system. It uses
the same portable generated GLB as the city, without texture downloads or AI
calls. Renderers advertising largeWorldColliders: 1 receive the larger scene
for the default terrain and district layout. Customized terrain or district
positions retain the compact city so scenery cannot cover authored buildings;
custom labels and assets remain supported. Older runtimes also retain the
compact city until upgraded. The renderer indexes
large landscape colliders once and uses their triangle BVH for local queries.
Worlds already supports use {id, action} and authored server-side behaviors.
The renderer's contextual control exposes a primary comp.interaction action
or a sole existing reaction. Switches can use a behavior to emit an ordinary
logged light or comp change; the world remains authoritative and late joiners
see the resulting state. PortOS pods use the validated frame bridge instead of
sending a world verb or embedding destination URLs in scene data. Keyboard
repeat, chat focus, overlays, distance, and occlusion suppress accidental use.
The renderer implementation and a toggle-lamp example live in the separate
Worlds repository. Controller support is tracked in
Worlds #11.
Agent-free resilience assay (promote-path pre-check)
Part of the SwarmWorld-inspired stigmergic Eidoverse epic:
a world foundation should not promote from an instance's local vernacular into
the shared PortOS baseline just because it "worked" while its author mind was
still narrating it live. server/services/eidoverseResilienceAssay.js runs a
candidate contribution through a clean, agent-free sandbox before that
decision is made:
createSandbox()is called fresh per scenario, so no state can leak in from a previous run or a live process handle.buildProjectionPlan()(eidoverseWorldProjection.js, already pure) loads once against the sandbox's initial state, standing in for "replay in a clean sandbox instance."- The controller then replays through the fixed disturbance suite —
reconnect,restart-world-host,missing-optional-deps— each with a warm-up run, the disturbance, and required recovery ticks. - A controller
step()(orapplyDisturbance()) that returns a Promise is itself a failure: the assay is synchronous by contract, so an "agent-free" contribution cannot reach for a live network, disk, or provider call during replay. - Every tick is checked against a built-in JSON-serializability invariant (a promoted foundation has to be loadable by a peer that never saw the authoring session) plus any contribution-supplied invariants.
runResilienceAssay(contribution) returns { contributionId, pass, scenarios, projection, reasons } with a readable reason per failure, naming the
disturbance and tick. scripts/eidoverse-resilience-assay.js
(npm run eidoverse:assay) is the CLI/CI entry point — with no arguments it
runs every reference contribution under
server/services/eidoverseResilienceAssayFixtures/*.contribution.js; given
module paths, it runs the assay against those instead and exits non-zero on
any failure. Two reference fixtures live beside the harness: a passing
beaconRelay.contribution.js and a deliberately-failing
narratedOnly.failing.fixture.js (named so the CLI's default fixture glob
skips it; only eidoverseResilienceAssay.test.js exercises it, proving the
harness catches the "author-mind-only" failure mode).
This harness is what the promote gate below runs:
services/eidoverseFoundationLedger.js replays a foundation through
runResilienceAssay() and refuses to package a promote candidate on a failing
verdict (#7455). Since #7625
the gate builds that contribution from the foundation's OWN body
(server/lib/eidoverseFoundationSandbox.js) rather than resolving one by id;
the CLI still sweeps the shipped fixtures through the registry in
server/services/eidoverseResilienceContributions.js.
Local vernacular vs shared baseline, and the promote gate (#7455)
Federated instances are meant to keep their own style and buildings while
discoveries that help everyone find a path into a shared PortOS baseline. That
boundary is a data model, not a convention. server/lib/eidoverseFoundations.js
declares three ownership layers:
runtime— the shared Eidoverse/PortOS framework. Upstream's to change; an instance never authors into it and never promotes it.baseline— the shared promoted-foundation population a peer can inherit.vernacular— this install's own artifacts. The default for everything authored locally, so nothing is shared by omission; promoting is an explicit act with a gate in front of it, never the absence of a "keep this private" flag.
A foundation is { body, style } by construction rather than one bag with a
blocklist. body is the promotable substance (declared schema, affordance,
optional controller spec); style is the cosmetics that make this Commons look
like itself — palette, motif, asset paths, placement, district, display aliases.
Packaging carries body and drops style outright, which is what makes "a peer
inherits the foundation without the author's cosmetics overwriting its own style
layer" a property of the payload rather than a merge rule a receiver has to get
right. On top of that split there is an authoring check: an unambiguously
cosmetic key found inside body (palette, motif, accent, color,
material, texture, a label alias) refuses the package rather than being
silently trimmed, so "I put the palette in body and expected peers to get it"
gets named. Spatial and asset-binding keys (pos, yaw, lib, districtId)
are deliberately not on that list — they are exactly the substance of a
district-template foundation.
data/eidoverse/foundations.json (server/services/eidoverseFoundationLedger.js)
is the install-local ledger — machine-local like portos-world.json beside it,
never federated, no seed file and no migration, since an absent file is the empty
ledger every install starts from.
The promote gate runs the assay against the foundation's OWN body; it never
accepts a verdict and never replays something the author merely named.
POST /api/eidoverse/world/foundations/:id/candidate DERIVES the sandbox from
body through server/lib/eidoverseFoundationSandbox.js (#7625), replays it
through the agent-free harness above, and packages against the verdict it just
produced.
Until #7625 the binding was a single author-supplied string: contributionId
was free text, it resolved against the shipped fixture directory, and naming a
shipped fixture was sufficient to clear the gate. A local build could promote —
and be offered to every federated peer — on evidence that described the demo
fixture rather than the body inside the envelope. contributionId is now
derived (controller:<definitionId>, or <kind>:<id>) and is not accepted
on any authoring surface: not the route body, not eidoverse.record, not the
panel. A receiving peer re-derives it from the envelope's own kind/body and
refuses one whose evidence is about something else.
One derivation per declared kind, each refusing a body it cannot interpret — which is the honest answer, because a declaration nobody but its author can replay is not promotable:
| kind | what gets replayed |
|---|---|
controller |
the shipped definition named by body.controller.definitionId, run against this install's body.controller.config through the definition's own configSchema. Upstream's exampleConfig proves only that upstream's example survives. |
district-template |
the declared body.placement must reproduce from its own { layoutId, anchor, propCount, seed, facing } via generateDistrictTemplatePlacement(), and the body is the harness's projection source — a template's consequence is its projection plan. |
schema / affordance |
the declarative interpreter: a clean world state is built from body.schema's declared field types and every body.affordance verb is resolved against it each tick. An affordance recorded as prose ({ inspect: 'reads the pulse count' }) is refused; it has to declare { reads, writes } over fields body.schema declares. |
The executable part stays shipped code in every case, so this adds no arbitrary-code-execution surface — what varies is the declarative input the install actually authored. A caller therefore cannot assert that its build survived its author's absence; it can only ask for the check — the same proposal-versus- consequence separation the construction tools got in #7454, applied to promotion. A foundation that is re-authored loses both its candidate and its verdict, because both described the previous body; a refused package likewise clears any candidate packaged earlier, since the verdict that vouched for it no longer holds.
server/services/eidoverseResilienceContributions.js still resolves the shipped
fixtures by id against a fixed directory for the CLI and the harness's own
tests. It is no longer the promote path's resolver, and there is no longer an
endpoint or mind tool advertising its ids — GET /api/eidoverse/world/contributions
and eidoverse.contributions are gone, because a list of ids that were
sufficient to pass the gate was a list of ways around it. An author choosing a
controller behaviour reads GET /api/eidoverse/world/controllers /
eidoverse.controllers, which already project the shipped registry.
Four refusals stand between a local artifact and the shared baseline, and every one returns a readable reason naming what to fix:
- Ownership — only a
vernacularfoundation is promotable. - Agent-free resilience — the body must have a derivable sandbox at all, and
the verdict must pass, cover the full disturbance suite, and be bound to the
label this foundation's own
kind/bodyderives (a passing verdict borrowed from another build is refused explicitly, on both the packaging and the receiving side). - Style leak — a vernacular style key inside
body. - Federation safety —
server/lib/federationSafety.jsrefuses the package when the candidate carries machine identity, network info, PII, credential-shaped values, or a credential-named field ({ apiKey: … }, which no value-shape scan can see), anywhere in its values or its keys. Nothing is redacted and shipped: a redacted promote would leave the author believing they published what they wrote.
The candidate envelope carries a content-addressed fingerprint (sha256 over the
canonicalized envelope), so verifyFoundationCandidate() is one gate seen from
both sides — the packaging side and a receiving peer's.
Promoting publishes into this install's baseline population.
POST /api/eidoverse/world/foundations/:id/promote re-packages first and
publishes the candidate it just produced, so promotion never rests on a stored
verdict — every gate above is re-run against the body as it stands. On a pass the
record moves to the baseline layer and takes a promotedAt stamp; its
style stays behind, because only the envelope crosses and the envelope has no
style layer at all. A refusal is a 200 with its reasons and moves nothing.
Re-authoring a promoted foundation returns it to vernacular and clears
promotedAt: the body that was published no longer exists on this install, and
keeping the stamp would also be a dead end, since the gate refuses to package a
baseline foundation.
Withdrawing retracts a publication, and it reaches the peers that pulled it
(#7632). POST /api/eidoverse/world/foundations/:id/withdraw de-promotes the
record — vernacular, promotedAt and candidate cleared, the body kept — and
records a tombstone for the fingerprint it had published. That tombstone
rides the peer offering, and a receiving install deletes its inherited copy
rather than merely ceasing to re-pull it. Re-authoring a promoted foundation
tombstones the replaced envelope for the same reason: it retracts a published
body, and before this it did so silently. Promotion used to be one-way, so a
foundation carrying something its author regretted — a personal detail the
regex-shaped federation-safety scan cannot recognize, a wrong attribution, a
body that turned out to be harmful — stayed on every install that had pulled it,
for good.
DELETE /api/eidoverse/world/foundations/:id removes a record outright, and
withdraws it first if it was promoted — so the most natural gesture an
author makes cannot orphan a peer's copy beyond recall. ?originInstanceId=
addresses an INHERITED copy; a bare id always means this install's own work,
because the two id spaces legitimately overlap.
What withdrawal does not promise. A peer running a PortOS older than the
tombstones wrapper key (schema v3) gently skips the whole offering and keeps
its copy, saying so in its log. That is unavoidable by construction — retraction
is best-effort across versions, never a guarantee — and it is the right failure
mode: the old peer degrades to the previous add-only behavior instead of acting
on a wrapper it cannot fully read. Deleting a record whose tombstone has already
aged out of the capped list is likewise final.
Where the user does this. Eidoverse > World controls > Foundations
(client/src/components/eidoverse/EidoverseFoundationsPanel.jsx) lists every
foundation with its ownership-layer badge, records or re-authors one, runs the
assay, promotes, and renders each refusal reason verbatim beside the foundation
it refused. The expanded foundation is a ?foundation=<id> search param, so a
refusal is linkable. The form has no contribution field: it seeds the body per
kind and, for a controller, fills it from a shipped definition read off
GET /api/eidoverse/world/controllers — an install that ships none says so
rather than offering an empty picker.
The mind needs its own grant to promote. eidoverse.promote (with the read
beside it, eidoverse.foundations) is gated on manageEidoverse and the
separate default-off promoteEidoverseFoundations grant, and is mind-scope only
— building in the local world is never permission to publish out of it, and an
ephemeral CoS task agent never gets the tool at all. The server runs the assay
itself, so a mind can ask for the check but can never assert a passing verdict.
Both tools return summaries (summarizeFoundation) rather than whole records:
the local style layer and the packaged envelope have no business riding into a
prompt.
A mind can also author, not just list and promote. eidoverse.record wraps the
same recordEidoverseFoundation() the HTTP route above uses, gated on
manageEidoverse alone (no promote grant needed — authoring stays local by
construction) and mind-scope only. authorKind is stamped 'mind' server-side
regardless of what the call arguments claim, the same reason layer is never
caller-supplied — and, since #7625, the same reason contributionId is not
accepted either: a mind that could name what the gate replays could point it at a
shipped demo. eidoverse.controllers (manageEidoverse, read) is what a mind
reads first, for the definitionId values a controller body may name.
Provenance graph and inheritance edges (#7461)
Every foundation carries queryable provenance: who authored it (an opaque
instance id + coarse authorKind — mind / cos / user, never a display
name) and its ordered lineage. foundationLineage()
(server/lib/eidoverseFoundations.js) derives that lineage — authored →
assayed → packaged → promoted, or inherited → assayed for a local
copy of a peer's — from fields the record already persists, so it costs no
extra storage and a ledger written before this existed still projects
correctly. GET /api/eidoverse/world/foundations returns it on every entry,
and the mind tools' summarizeFoundation() projection carries provenance,
inheritance, and lineage too — the same identity fields a candidate
envelope was already authorized to carry, now surfaced consistently
everywhere a foundation is read. GET /api/eidoverse/world/foundations/:id
names a locally-authored record by its plain id and an inherited copy by
?originInstanceId=<origin> (#7626): an inherited copy lives under a
separate ledger key precisely so it can share a human-readable id with a
local vernacular foundation without colliding, so the ORIGIN is what
disambiguates the two. The peer:<origin>:<id> storage key itself stays
internal and is never typed by a caller — { id, originInstanceId } is the
grammar (eidoverseFoundationTargetSchema), and foundationLedgerKey() is the
one place it becomes a key.
recordEidoverseFoundationInheritance() (eidoverseFoundationLedger.js)
is the accept-side of a peer pull: given an already-verified candidate
envelope, the peer this install pulled it FROM, and this install's own
instance id, it re-runs the exact gate a peer runs on a candidate it was
handed — schema, content-addressed fingerprint, the embedded assay evidence,
and federation safety — and, on a pass, stores a baseline local copy
carrying an inherited-from edge (origin instance, source instance, the
envelope's fingerprint, and when it was pulled). It refuses a self-referential
pull (a peer handing back a foundation this install itself originated) and
never re-runs the resilience assay itself — replaying a peer's controller code
on the receiving install is exactly what the assay harness exists to keep off
every OTHER install.
The inherited copy is stored under peer:<originInstanceId>:<foundationId> —
deliberately disjoint from any id a local author could ever write — so it can
never shadow, collide with, or erase a same-id local vernacular foundation;
both simply coexist in the listing. An inherited foundation can never be
re-promoted from this install (packageFoundationCandidate refuses it by
name): promotion publishes only what this install itself authored, never a
relay of another install's work.
Reading and adopting an inherited foundation (#7626)
Inheriting a peer's foundation used to store a row and nothing more: no
runtime on either install read a foundation's body, so the only way to use
what a peer contributed was a human reading raw JSON out of the Foundations
panel and retyping it — the "go read the author's transcript" path this whole
area exists to replace, and one that keeps no attribution. Two verbs close
that.
Read one. eidoverse.foundation (mind tool, manageEidoverse, read) and
GET /api/eidoverse/world/foundations/:id return detailFoundation() — every
field summarizeFoundation() carries, plus body and disclosure. The LIST
projection still omits both, deliberately: a list of whole bodies is kilobytes
of substance per entry riding into a prompt to answer a question about ids,
and which body to read is a decision made after the list. style is omitted
in both — it is this install's cosmetics and never leaves.
Adopt. eidoverse.adopt (mind tool, manageEidoverse and
installEidoverseControllers) and POST /api/eidoverse/world/foundations/:id/adopt stand an INHERITED foundation up
as something that runs here. planFoundationAdoption() decides per kind:
| kind | what adopting does |
|---|---|
controller |
Installs the SHIPPED controller body.controller.definitionId names, with the envelope's config, disarmed and with deliverEffects: false. |
district-template |
Refused — nothing turns a template body into geometry yet (#7627). |
schema, affordance |
Refused by name — a declaration with no interpreter here is not adoptable, and saying so is the honest answer. |
A locally-authored foundation is refused too: its author already has every way to install it, and adoption is specifically the path for a peer's work.
Adopting a controller can never execute a peer's bytes. The envelope names
which of this install's own shipped controllers to run and with what
settings; installEidoverseController() resolves that id against the fixed
local registry, exactly as an ordinary install does. The result lands disarmed
and silent, so arming it and letting it speak or build in the world stay
separate, local decisions rather than consequences of one tool call.
The resulting controller install carries a derived-from edge — origin
instance, foundation id, envelope fingerprint — in the same shape a derived
foundation uses. That edge SURVIVES a later re-install (it is preserved
alongside installedBy / installedAt), which is what makes adoption the
provenance-keeping way to re-use a peer's contribution as against retyping the
body, which keeps nothing and is refused as republishing (#7631). An adopt
whose install id is already taken by a controller derived from something else
is refused rather than overwriting a controller already running here.
The peer pull/inherit transport (#7455)
Authorized to cross the federation layer by the
federated Eidoverse foundations ADR.
server/services/sharing/peerEidoverseFoundationSync.js is the wire between
the two gates above. It owns no policy of its own — which foundations an
install offers is listPromotedFoundationCandidates() in the ledger, and
which it accepts is recordEidoverseFoundationInheritance(). It owns the
payload wrapper, the version gate, the caps and the sweep.
Outbound. GET /api/peer-sync/eidoverse-foundations advertises
{ schemaVersion, listHash, candidates: [...], tombstones: [...] }. The
candidates are exactly the foundations this install PROMOTED and AUTHORED:
layer === 'baseline'— a merely packaged candidate is a dry run ("would this pass?"), not a publication, and is never served.!inheritance—baselinealso covers a local copy of a peer's foundation, so an inherited record is excluded rather than relayed. That matches the ledger's existing refusal to re-package an inherited record: a peer that wants a third install's foundation pulls it from the install that authored it.- the stored envelope must still pass
verifyFoundationCandidate().foundations.jsonis a file a human can edit, and refuse-never-redact applies outbound as well as inbound, so a candidate that no longer passes is withheld from the offering and logged. - the fingerprint must not be tombstoned. Promoting clears a fingerprint's tombstone, so the two lists cannot normally disagree; a hand-edited ledger can make them, and an offering that both published and retracted one fingerprint would resolve differently on every receiver. The retraction wins.
tombstones is [{ fingerprint, deletedAt }] — a content-addressed name and an
instant, never any of the body. It caps on its own budget, never against
OFFERING_ENTRY_CAP: sharing one cap would let a large promoted population
silently truncate the retractions, which is the one trade this must never make.
Both lists feed the listHash, so a withdrawal with no other change still
breaks a receiver's unchanged short-circuit instead of waiting for the next
forced re-pull.
Unlike the older peer-pull routes, this one does not ride the warn-first
authorization ramp: it passes alwaysEnforce, so only a registered,
outbound-enabled peer ever reads it. The ramp exists so a peer mid-upgrade
does not lose sync it already had, and a brand-new endpoint has no such
history to protect.
Inbound. syncEidoverseFoundationsFromPeer() runs for peers the user
flagged fullSync, on the same 60-second sweep as the media-library,
CoS-history and CoS-task sweeps (services/sharing/index.js). It byte-caps
the response, validates the wrapper, gently skips a sender whose
schemaVersion is ahead of local (the ledger has no re-fetch path that would
correct a mis-applied envelope later), short-circuits on an unchanged
listHash, and hands every remaining candidate to
recordEidoverseFoundationInheritance() — which re-runs the entire
accept-side gate and writes nothing on a refusal. A candidate whose
fingerprint this install already holds is skipped, so the periodic forced
re-pull (there so a local deletion self-heals) never rewrites inheritedAt
on an unchanged copy.
The sweep applies the peer's retractions first, before it reads what this
install holds: a fingerprint the same offering re-publishes is then re-verified
through the whole accept-side gate on its way back in, rather than surviving in
place unchecked. A retraction authorizes dropping only a record this install
pulled from that same peer (inheritance.sourceInstanceId) — a fingerprint is
public inside the federation the moment it is offered, so it identifies a record
but authorizes nothing, and without the scope any registered peer could retract
a third install's work by naming it. A tombstone for a fingerprint this install
does not hold is a silent no-op. Peer tombstones are not persisted: this install
never re-offers an inherited record, and the sender keeps advertising the
tombstone while its candidate stays absent, so storing them would only let a
peer crowd out this install's own retractions.
Both directions are gated on the eidoverse instance feature: an install with
Eidoverse turned off neither offers nor accumulates.
Compatibility. The envelope's candidateVersion is v3 as of #7625. The
bump is semantic rather than structural: a pre-v3 envelope's assay evidence was
recorded against a contribution its author named, with no required relationship
to the body travelling beside it, so there is nothing to upgrade — the accept
side refuses v1 and v2 outright with that reason rather than inheriting on
them. Migration scripts/migrations/397-eidoverse-foundation-derived-assay.js
does the local half: it re-derives every record's binding label, drops the
verdicts the old replay produced, and returns an unreplayable baseline
foundation to vernacular with promotedAt: null — exactly what the ledger
already does when a body is re-authored, for exactly the same reason.
PORTOS_SCHEMA_VERSIONS.eidoverseFoundations (v3) is the
transport contract, registered in NON_RECORD_SCHEMA_CATEGORIES because this
is a receiver-pull category with no push to gate — a foundation is not a
peer-subscribable record kind. It is deliberately separate from the envelope's
own candidateVersion, which pins one envelope's shape and is hashed into its
fingerprint: a change to the envelope bumps both, a change to the wrapper or
the caps bumps only the category. v3 (#7632) added tombstones to the wrapper
and moved only the category, because a tombstone names a candidate by the
fingerprint it already had and no envelope field changed. A v2 sender omits the
key and a v3 receiver reads that as "nothing to retract"; a v2 receiver
gently skips a v3 offering and therefore keeps a copy it should have dropped.
Creative toolkit for minds (#7459, wired end-to-end in #7627)
Authoring a foundation from a blank body/style is a lot to invent from
scratch every time. server/lib/eidoverseCreativeToolkit.js is a small,
documented, closed vocabulary a mind reaches for instead: named materials
and motifs (cosmetics — install-local style, the same class of value
styleLeakFindings refuses inside a body) and named generative placement
layouts (radial-ring, grid-plot, arc-row, grove-cluster — structure,
safe as body). eidoverse.creative-catalog (manageEidoverse, read) lists
all three, including each material's colorHex — a palette id whose value a
mind cannot see is not a usable catalog entry. Nothing here calls an AI
provider; every layout is deterministic and seeded
(generateDistrictTemplatePlacement), so the same {layoutId, anchor, seed}
reproduces the same geometry on replay or on a peer that later inherits the
promoted foundation.
Two tools use a chosen layout, both read-only (they compute; they do not write to the world or the foundation ledger):
eidoverse.place-layout(manageEidoverse) callsbuildDistrictTemplateAugmentOperations()and returns ready-to-submiteidoverse.augmentspawnoperations for the live scene (asset-path validity is still checked whereeidoverse.augmentlands them). The same{layoutId, anchor, seed}yields byte-identical operations every call.eidoverse.draft-foundation(manageEidoverse) callsbuildDistrictTemplateFoundationDraft()and returns aneidoverseFoundationInputSchema-shapeddistrict-templateinput — the generative substance (layout id, anchor, seed, resulting positions) inbody, the material/motif cosmetics instyle— ready to pass straight toeidoverse.record. Drafting composes nothing itself; recording still lands on the localvernacularlayer, matching every other authored foundation, and publishing to the shared baseline remains the separate, expliciteidoverse.promoteact above.
eidoverse.record derives, never trusts, a district-template's
placement. When a recorded district-template's body carries
{layoutId, anchor} (with an optional seed), recordEidoverseFoundation()
(services/eidoverseFoundationLedger.js) replays
generateDistrictTemplatePlacement() server-side and stores the result as
body.placement — REPLACING any placement the caller supplied, not merging
it. That is what makes the replay claim above hold for a hand-assembled
eidoverse.record call too, not only for one built from
eidoverse.draft-foundation's output, and it is why the same district-template
is comparable and replayable on an older or newer install that later inherits
it (#7625).
Observation-first discovery (#7457)
SwarmWorld's finding is that reuse between agents starts by looking at the
world, not by asking its author about it. PortOS's mind tools grew the other
way round: a mind could speak (eidoverse.say), travel (eidoverse.visit) and
chat (eidoverse.chat, eidoverse.visit-chat) long before it could see what
was already standing in its own Commons. The continuous-play playbook has told
it to "move through the world and map what already exists" since that loop
landed — naming places, projections and affordances it had no tool to read.
eidoverse.observe is that missing read, and the playbook now leads with it.
What it answers
One mind-scoped call (manageEidoverse, the same grant as the foundation and
controller reads it summarizes) returns:
places— the eight districts as somewhere a mind can stand and describe: label, direction, landmark, which signal sources feed it, how many live signals those sources currently report, and whether any of them want attention. Districts come from the install's resolved design recipe, not from a constant, so a mind never names a district a later design version renamed (V3 calls it the Federation Terminal, not the V2 Harbor) or one the user's own overrides moved. A source the recipe has switched off reports asdisabledrather than counted — the projection places nothing for it.peers— the opaque travel idseidoverse.destinationsalso returns, so one carries straight intoeidoverse.visit— each with how many foundations this install inherited through it.foundations.inherited— a peer's contributions, newest first, with the peer they arrived through and the instance that authored them (distinct on purpose: a multi-hop re-share is only legible when they are).controllers.needsAttention— only installs that are disarmed or failing. A controller that has never ticked yet is one interval away from its first tick, which is normal, not an alarm.changes— what is new since this mind last observed.
That third bullet is the epic's acceptance criterion: a peer contribution is discoverable by touring the Commons, because the Federation Terminal chamber carries the count and the inherited list names the build — no repository read and no conversation with its author required.
Three distinctions the report refuses to collapse
- Unavailable is not empty. A district whose source failed to read reports
signalCount: nullandstatus: 'unknown', never0/quiet. Reporting an unreadable app list as "the terraces are empty" is the same misreport #7458 fixed for district density, and it would be worse here, where the mind acts on it. signalCountcounts signals, not placed entities. The projection allocates a capped, round-robin sample of live signals into the world, so the world may hold fewer. Counting sources keeps the tour readable without a running world runtime — a mind that cannot start the runtime still needs to know what is in its Commons — and the field name says "signals" so the difference is never implied away.- Never-observed is not nothing-new. A first observation reports
firstObservation: truewith no new items rather than handing a mind waking into a months-old install its entire world as "new". - A section that failed to collect is not an empty section. It arrives as
null, contributes no changes, and carries the previous marker's ids forward. Collapsing it to[]would report every peer as departed on a transient read failure, rewrite the marker without them, and then report them all as new on the next observation — a flap that repeats for as long as the source keeps failing intermittently.
Local attention reasons
Each place includes attentionSignals and attentionTruncated. Contributors
identify the enabled, successfully read source, its actual severity
(attention or error), its contributing signalCount (rows), and reasons.
The district's total signalCount includes healthy rows and is not a fault count.
An app group is one signal row even when it represents many applications.
Each reason contains an allowlisted code and affectedCount, an aggregate
number of affected records when known, otherwise null.
Use app_not_started, app_stopped, and app_unknown to distinguish registry
conditions before choosing a process diagnostic; not-started is not proof of a
crash. Nexus can report runtime_data_disk_pressure or
runtime_data_disk_critical (capacity of the filesystem holding runtime data),
memory_pressure or memory_critical, backup_failure, review_alerts, and
cos_paused. These come from the same predicates that determine source status;
health does not alarm on not-started apps, while App Arcade does.
Agent Foundry task errors mean blocked internal CoS queue entries, not
necessarily failed executions. task_user_terminated means the entry records
intentional user termination; task_blocked covers every other block category,
including absent or unknown categories. Each task row represents one entry, so
these reason counts aggregate entries. Recorded user intent does not authorize
retrying, restarting or mutating stopped work. Ordinary pending work stays
steady, approval-gated and challenged work stays attention, in-progress work
stays active, and terminal entries are excluded. No task names, raw block
reasons or arbitrary category strings enter the observation.
Federation Terminal counts errored peer records with structured failed-probe
reasons: peer_connection_refused, peer_transport_failure, peer_probe_timeout,
peer_auth_required, peer_dns_failure, peer_host_unreachable, and
peer_health_http_failure. Use these to select a bounded connection or credential
diagnostic, without retrying peers or changing admission. peer_failure_unknown
means the errored peer has no recognized failed-probe evidence (including legacy
records); neither status:error nor unavailable travel proves a configuration,
guest-admission or sync failure. Successful/healthy peers ignore old failure
metadata. Probe messages, HTTP response bodies and network identities stay private.
Other sources and older reason-less inputs use source_attention or source_error: these
say only that a coarse source status requires attention, without inventing a
cause. Error sources remain identifiable even though district status is attention.
Reasons are ordered by source, severity (error first), then code and capped at
24 entries per district. attentionTruncated: true means some entries were
omitted. Healthy recovery removes reasons on the next collection; disabled and
unreadable sources emit none, and unavailable inputs never reuse previous causes.
Diagnostics contain no app names, record identities, paths or raw errors. They
are collected only for local observation under the existing mind
manageEidoverse grant, without new routes, grants, world logs, renderer
payloads or peer exports. A subsequent observe still advances the visit marker;
use the internal commit: false form to inspect without consuming its delta.
The visit marker
"What is new since I last looked" has to cross a wake boundary: a mind
wakes, observes, acts, and ends its turn, and the next wake is a different
process. Nothing in-memory survives that. The world chat cursor lives in a
100-entry ring buffer a restart empties; the peer sync's lastOfferingListHash
is per-peer content-change detection for a background sweep, also in memory.
So observing stamps a marker — data/eidoverse/observation.json, covered
in STORAGE.md. That is the stigmergic half of the slice: the
trail a mind leaves is what makes the next observation's changes mean
anything. It also means eidoverse.observe is not idempotent, and that it
is declared sideEffect: 'write' even though a mind reads it like a read.
That is not a label: mindToolRecipes.js only lets a saved recipe compose
'read' tools, and the MCP bridge exports readOnlyHint: sideEffect === 'read'. Calling a marker-stamping tool a read would let a replayable recipe
silently consume the changes delta the playbook depends on, and would tell an
external MCP client the tool touches nothing.
observeEidoverseWorld({ commit: false }) is the internal look-without-stamping
form.
The marker holds ids, per-district status, and a timestamp — no body, no style,
no record content — and is machine-local like the ledger and the controller
store beside it. A marker written by a newer PortOS degrades to one honest
firstObservation rather than being diffed against fields this build does not
understand, and an unreadable marker file throws rather than reading as
never-observed, because the next write would otherwise replace a real marker
and re-report a settled world.
Signal, not noise
Two filters keep changes worth reading on a busy install:
- Places diff on a status flip, never on a count change. Signal counts move
every wake as agents and tasks come and go; diffing them would make
changespure churn. The live count stays inplacesfor a mind that wants it. - A controller already wanting attention last visit is not re-reported. A long-broken controller would otherwise re-alarm every wake and drown the one that just broke.
Where it lives
server/lib/eidoverseObservation.js is pure: buildEidoverseObservation()
takes already-collected snapshots plus the previous marker and returns
{ report, marker }, so the whole diff contract is testable without a world
runtime, a socket or a file. server/services/eidoverseObservationLedger.js is
the I/O, clock and marker shell around it — and every collection failure
degrades that section to null rather than failing the tour, because a mind
that cannot read its controllers should still get to see its districts.
Executable world controllers (#7456)
SwarmWorld's strongest result is that technologies are executable: they keep running once the agent that authored them is gone. PortOS minds wake intermittently, so a world that only changes during a mind turn is a world that is dead most of the time. A controller is the durable thing that keeps running between wakes — a resource tick, an ambient verb, a gentle NPC, a maintenance hook — supervised by PortOS rather than by whoever installed it.
Behavior is code PortOS ships; an install is data a mind authors. The only
thing an install may say about behavior is a controllerId, resolved by
server/services/eidoverseControllerRegistry.js against a fixed directory of
shipped modules. There is deliberately no path-taking export on that resolver at
all: an install arrives from an HTTP body or a mind's tool call, and "import the
module this request names" is arbitrary code execution wearing a feature's
clothes. This is the same rule the resilience-assay contribution registry
already applies, for the same reason.
A tick cannot reach an AI provider. runControllerStep
(server/lib/eidoverseControllers.js) refuses a step that returns a Promise, so
there is no await for a network, disk, or provider call to hide behind. Root
AGENTS.md's "no cold-bootstrap LLM calls" rule is therefore a structural
property of the tick path rather than a convention — boot arms a timer and
nothing else. The same synchronous rule is why every shipped controller is
replayable by the agent-free assay with no extra authoring: the controller
registry is both the assay CLI's second contribution source and what a
controller foundation's promote gate resolves body.controller.definitionId
against — replaying the definition against this install's own config, so the
evidence is about the controller this install actually configured.
Effects are proposals, from a closed vocabulary. A step returns effects, it
does not perform them — the same proposal-versus-consequence separation the
construction tools have. note never leaves the ledger; say and augment
reach the world only for an install whose deliverEffects was explicitly turned
on (it defaults to false), and augment reuses the existing world-verb
operation schema rather than inventing a second one. A delivery that fails is
recorded and the step still counts: the controller's own state advanced, and
re-running it to retry a world write would double-count everything it did.
Supervision. server/services/eidoverseControllerRuntime.js registers one
eidoverse-controller-tick interval with the event scheduler and steps every
install whose own cadence is due. Arming is reconciled at every gate move —
install, retire, arm/disarm — and not only at boot, so a controller installed at
16:00 is not waiting for a restart to start ticking. A pass never replays a
backlog: a machine asleep for three days wakes to ONE tick, because a cadence is
"about this often", never a ledger of owed executions. A controller that fails
maxConsecutiveFailures ticks in a row is disarmed with a recorded reason rather
than retried forever, and an install whose controllerId this version no longer
ships is disarmed immediately.
Every tick revalidates the stored install against its own definition
(#7629). record.config is re-parsed through definition.configSchema
before each step rather than trusted from install time — a config that no
longer parses (a shipped schema tightened, a hand-edited file) disarms the
install immediately instead of stepping it, and a newly-added default lands on
the record the first time it re-parses cleanly. definition.invariants — the
same predicates the resilience assay replays — run against the state a step
just produced; a violation fails that step and counts toward
maxConsecutiveFailures like any other failure, so the live supervisor holds a
controller to the same contract the promote gate does. The store's own
schemaVersion stamp is read back (not assumed to be this build's constant):
a store written by a newer build disarms rather than stepping under rules it
does not fully understand — and the writes that disarm never re-stamp the file
with this build’s older constant, so the signal survives the pass that reads it
rather than being erased by it.
Storage is data/eidoverse/controllers.json — file-primary and machine
local, never federated (docs/STORAGE.md). A controller crosses to a peer only
as the body of a promoted foundation, which carries no install.
Delivery evidence (#10818). Both the common list and semantic inspect
projection expose nullable lastCompletedDelivery: { at, tick, ok, delivered, reason }. It changes only after a say or augment delivery finishes and
still matches the installed record's latest tick. at is that tick's time;
read it and tick to assess the age of the acknowledgement. A refusal (including
partial delivery) or thrown error replaces prior success. Quiet ticks, local
notes, disabled delivery, step failures and in-flight requests leave the prior
completed verdict intact. Arming/config edits preserve it; reinstall resets it.
lastDelivery retains its latest-tick contract: quiet ticks report unknown
(ok: null). Neither historical acknowledgement nor pulse/failure counters or
recentEffects proposals prove current world state or visible rendering.
Migration 425 upgrades older stores to schema version 2 with unknown (null)
completed history, preserving their state and counters rather than manufacturing
success from ambiguous old outcomes. There is no shipped store seed.
Shipped controllers. ambient-beacon counts ticks and marks a pulse every
Nth one (announce decides whether that pulse is spoken into the world or kept
as a note). lantern-keeper re-issues the light verb for a fixed set of world
entities every Nth tick, so lamps an author placed stay lit across host restarts
while the author is away — re-lighting an already-lit lamp is a no-op, which is
what makes running it on a schedule safe.
Explicit riddle rounds. riddle-ledger implements a fixed offer → guess →
reveal interaction. It evaluates no foundation body: schema/affordance
foundations remain declarative, with their body, attribution, admission and
promotion contracts intact. Install a separate controller explicitly with an
unused id, controllerId: "riddle-ledger", config: {}, armed: true, and
deliverEffects: true to speak into the private world (false for local-only
play). Nothing installs at boot or resets another controller. Supervised ticks
are silent, including after restart.
Read GET /api/eidoverse/world/controllers/<id> or
eidoverse.inspect-controller, then send POST /api/eidoverse/world/controllers/<id>/riddle or the eidoverse.riddle tool:
{"action":"offer","expectedRevision":0,"clue":"Which shape has three sides?","answer":"triangle"}
{"action":"guess","expectedRevision":1,"guess":"TRIANGLE"}
{"action":"reveal","expectedRevision":2}
The tool also takes id. Both mind grants (manageEidoverse and
installEidoverseControllers) are required. HTTP gameplay uses the operator
gate, including authenticated local-agent sessions; scoped peer credentials do
not grant gameplay. Each request must use the inspected state.revision, which
advances once per accepted action. A stale revision, a second guess, a repeated
reveal, an offer before revealing the current round, or a disarmed/wrong-kind
install refuses without changing state or sending chat. Revealing without a
guess is allowed; its correct is null. Otherwise matching ignores case after
input trimming, and correctness is withheld until reveal.
outcome: "applied" means the local transition persisted, even if world
delivery failed. Inspect state.delivery (also returned as delivery):
disabled means local-only, pending means completion is unknown,
acknowledged means the existing world say protocol acknowledged one message,
and refused carries the failure reason and acknowledged count. The answer is
only spoken on reveal; private operator inspection includes it throughout.
World acknowledgement does not prove visible browser rendering. Progress lands
before delivery; neither a restart nor a repeated request retries the message.
A crash can leave pending evidence, which must not be called successful.
If a management operation replaces/retires the install during delivery,
outcome: "superseded" reports the receipt without attaching it to the
replacement. Round state lives entirely in the existing machine-local controller
store, never in a promoted foundation or federation envelope. This surface is
API/tool gameplay; it adds no world-client command or guest interaction UI.
The mind needs its own grant to install. eidoverse.install-controller and
eidoverse.retire-controller are gated on manageEidoverse and the separate
default-off installEidoverseControllers grant, and are mind-scope only:
building in the world during a turn is a different act from leaving something
running in it afterwards. The reads beside them, eidoverse.controllers and
eidoverse.inspect-controller, need only manageEidoverse — a mind that can
build should be able to see what is already ticking, and seeing is what makes
the writes usable rather than guesswork. eidoverse.controllers never carries
config/state (summarizeControllerInstall's LIST projection); a caller that
wants one install's config and accumulated state back reads
eidoverse.inspect-controller, backed by the same GET /api/eidoverse/world/controllers/:id the panel's Details view uses (#7629).
Changing a config without losing state. Re-installing an existing id
rebuilds its state from the new config from scratch — the deliberate behavior
for "I want this to start over." updateEidoverseControllerConfig (routed at
PATCH /api/eidoverse/world/controllers/:id/config) is the other verb: it
re-parses the new config through the definition's own schema and leaves
state untouched, for a later mind that wants to tune a value on a controller
it inherited without destroying what it has already accumulated.