Skip to content

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

36.8 KB
Raw Blame
/**
 * Versioned, install-portable PortOS world design contract for Eidoverse.
 *
 * PortOS ships only this small recipe. Eidoverse keeps the model library and
 * cached bytes; each PortOS install resolves the recipe once and persists the
 * resulting paths in its machine-local world state.
 */

import { normalizeEidoverseLabelAliases } from './eidoverseWorldLabels.js';
import { createHash } from 'node:crypto';
import { canonicalStringify, deepMerge } from './objects.js';

export const EIDOVERSE_WORLD_STATE_SCHEMA_VERSION = 3;
export const EIDOVERSE_WORLD_DESIGN_VERSION = 3;
export const EIDOVERSE_ASSET_RECIPE_VERSION = 3;
export const EIDOVERSE_MAX_LIVE_ENTITIES = 48;
export const EIDOVERSE_LIBRARY_MODEL_ROOT = 'eidoverse/assets/models/';
export const EIDOVERSE_MANAGED_PREFIX = 'portos-design-v2-';
export const EIDOVERSE_PROJECTION_PREFIX = `${EIDOVERSE_MANAGED_PREFIX}signal-`;
// The world's self-description rides on one managed convention entity rather
// than a world-scope singleton: a `meta` slot on WorldState would be a protocol
// amendment, while this replays, forks, and degrades gracefully on a host that
// has never heard of PortOS.
export const EIDOVERSE_META_ENTITY_ID = `${EIDOVERSE_MANAGED_PREFIX}meta`;

export const EIDOVERSE_SOURCE_KEYS = Object.freeze([
  'apps',
  'agents',
  'tasks',
  'features',
  'peers',
  'health',
  'productivity',
  'activity',
  'goals',
  'memory',
  'storage',
  'jira',
  'operations',
]);

const MODEL_ROOT = EIDOVERSE_LIBRARY_MODEL_ROOT;

// Frozen forever: migration must compare legacy leaves against the exact V1
// values that shipped, never against a moving approximation of them.
export const EIDOVERSE_WORLD_DESIGN_V1 = Object.freeze({
  version: 1,
  includes: {
    apps: true, agents: true, tasks: true, features: true, peers: true,
    health: true, productivity: true, activity: true, goals: true,
    memory: true, storage: true, jira: true, operations: true,
  },
  limits: {
    apps: 48, agents: 24, tasks: 48, features: 32, peers: 16,
    health: 1, productivity: 1, activity: 24, goals: 32,
    memory: 16, storage: 48, jira: 48, operations: 1,
  },
  layout: { origin: [-24, 0, -24], spacing: 7, laneGap: 6, columns: 8 },
  scale: {
    app: 1, agent: 1, task: 0.8, feature: 1, peer: 1.2, health: 1.2,
    productivity: 1.2, activity: 0.55, goal: 1.1, memory: 0.9,
    storage: 0.8, jira: 0.75, operations: 1.3,
  },
  assets: {
    app: `${MODEL_ROOT}computer_servers_rack_with_fans_on_back_row_of_four_4_columns.glb`,
    agent: `${MODEL_ROOT}scifi_quad_small_drone_blue.glb`,
    task: `${MODEL_ROOT}scifi_cyberpunk_intermodal_shipping_container_crate_blue.glb`,
    feature: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    peer: `${MODEL_ROOT}modern_sedan_car_blue_vehicle_generic.glb`,
    health: `${MODEL_ROOT}inanna_tech_cyber_scifi_sumerian_retrofuturist_vehicle_car_light.glb`,
    productivity: `${MODEL_ROOT}inanna_tech_cyber_scifi_sumerian_retrofuturist_vehicle_car_light.glb`,
    activity: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    goal: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    memory: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    storage: `${MODEL_ROOT}computer_servers_rack_with_fans_on_back_row_of_four_4_columns.glb`,
    jira: `${MODEL_ROOT}scifi_cyberpunk_intermodal_shipping_container_crate_blue.glb`,
    operations: `${MODEL_ROOT}inanna_tech_cyber_scifi_sumerian_retrofuturist_vehicle_car_light.glb`,
  },
  terrain: {
    seed: 'portos', size: 128, segments: 64, amplitude: 1.8, flatRadius: 28,
    layers: [{ color: '#142338', repeat: 18 }, { color: '#1c3b43', repeat: 10 }],
  },
});

const assetSlot = ({ preferredPaths, fallbackQueries, requiredTokens, excludedTokens = [], maxBytes, fallback }) => ({
  preferredPaths,
  fallbackQueries,
  requiredTokens,
  excludedTokens,
  maxBytes,
  format: 'glb',
  animation: 'optional',
  sourcePolicy: 'library-only',
  fallback,
});

// Paths are preferences, not bundled payloads. Queries allow a future library
// to satisfy the same semantic role even when its filenames evolve.
export const EIDOVERSE_ASSET_RECIPE_V2 = Object.freeze({
  version: 2,
  slots: {
    nexus: assetSlot({
      preferredPaths: [`${MODEL_ROOT}scifi_perimeter_watchtower_standalone_or_with_wall_middle_four_way.glb`],
      fallbackQueries: ['scifi tower', 'technology tower'],
      requiredTokens: ['tower'], excludedTokens: ['car', 'vehicle', 'rubble'], maxBytes: 24_000_000,
      fallback: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    }),
    app: assetSlot({
      preferredPaths: [`${MODEL_ROOT}single_loose_computer_server.glb`],
      fallbackQueries: ['computer server', 'technology console'],
      requiredTokens: ['server'], excludedTokens: ['car', 'vehicle'], maxBytes: 32_000_000,
      fallback: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    }),
    agent: assetSlot({
      preferredPaths: [`${MODEL_ROOT}scifi_quad_small_drone_blue.glb`],
      fallbackQueries: ['scifi drone', 'robot drone'],
      requiredTokens: ['drone'], excludedTokens: ['car', 'vehicle'], maxBytes: 24_000_000,
      fallback: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    }),
    task: assetSlot({
      preferredPaths: [`${MODEL_ROOT}scifi_cyberpunk_intermodal_shipping_container_crate_blue.glb`],
      fallbackQueries: ['scifi crate', 'data container'],
      requiredTokens: ['crate'], excludedTokens: ['car', 'vehicle'], maxBytes: 16_000_000,
      fallback: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    }),
    goal: assetSlot({
      preferredPaths: [`${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`],
      fallbackQueries: ['scifi orb', 'beacon'],
      requiredTokens: ['orb'], excludedTokens: ['car', 'vehicle'], maxBytes: 12_000_000,
      fallback: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    }),
    memory: assetSlot({
      preferredPaths: [`${MODEL_ROOT}cyborg_brain_cybernetic_implant_neuralink_cyberbrain_organ.glb`],
      fallbackQueries: ['cyber brain', 'memory tree'],
      requiredTokens: ['brain'], excludedTokens: ['car', 'vehicle'], maxBytes: 56_000_000,
      fallback: `${MODEL_ROOT}stylized_yucca_joshua_tree_desert_cactus_plant.glb`,
    }),
    storage: assetSlot({
      preferredPaths: [`${MODEL_ROOT}scif_cyberpunk_crt_retro_computer_monitor_screen_keyboard_tower.glb`],
      fallbackQueries: ['computer mainframe', 'data terminal'],
      requiredTokens: ['computer'], excludedTokens: ['car', 'vehicle'], maxBytes: 44_000_000,
      fallback: `${MODEL_ROOT}single_loose_computer_server.glb`,
    }),
    peer: assetSlot({
      preferredPaths: [`${MODEL_ROOT}scifi_perimeter_wall_gate.glb`],
      fallbackQueries: ['scifi gate', 'portal arch'],
      requiredTokens: ['gate'], excludedTokens: ['car', 'vehicle'], maxBytes: 24_000_000,
      fallback: `${MODEL_ROOT}scifi_perimeter_watchtower_standalone_or_with_wall_middle_four_way.glb`,
    }),
    activity: assetSlot({
      preferredPaths: [`${MODEL_ROOT}streetlight_lamp_light_street_blade_runner_cyberpunk.glb`],
      fallbackQueries: ['cyberpunk streetlight', 'light marker'],
      requiredTokens: ['light'], excludedTokens: ['car', 'vehicle', 'rubble'], maxBytes: 16_000_000,
      fallback: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    }),
    district: assetSlot({
      preferredPaths: [`${MODEL_ROOT}scifi_perimeter_wall_pillar.glb`],
      fallbackQueries: ['scifi pillar', 'technology marker'],
      requiredTokens: ['pillar'], excludedTokens: ['car', 'vehicle'], maxBytes: 20_000_000,
      fallback: `${MODEL_ROOT}inanna_tech_cyber_scifi_sphere_orb.glb`,
    }),
  },
});

/**
 * The signal sources that are a single object rather than a list. Everything
 * else in `buildEidoverseWorldSignals()`'s output is an array (or `null` when
 * it could not be read). Shared so the projection's availability check and the
 * observation report's density count cannot drift into disagreeing about what
 * an empty district looks like — the #7458 misreport, from either side.
 */
export const EIDOVERSE_SCALAR_SOURCE_KEYS = Object.freeze(['health']);

export const EIDOVERSE_DISTRICTS_V2 = Object.freeze([
  { id: 'nexus', label: 'PortOS Nexus', direction: 'Center', landmark: 'status spire', anchor: [0, 0, 0], sources: ['health', 'operations', 'features'], accent: '#ffb86b' },
  { id: 'apps', label: 'App Terraces', direction: 'Northwest', landmark: 'service pylons', anchor: [-30, 0, -18], sources: ['apps'], accent: '#65d9ff' },
  { id: 'agents', label: 'Agent Foundry', direction: 'North', landmark: 'drone foundry', anchor: [0, 0, -34], sources: ['agents', 'tasks'], accent: '#a78bfa' },
  { id: 'goals', label: 'Goal Observatory', direction: 'Northeast', landmark: 'orbital beacon', anchor: [30, 0, -18], sources: ['goals', 'jira'], accent: '#f7d774' },
  { id: 'memory', label: 'Memory Grove', direction: 'Southeast', landmark: 'neural lanterns', anchor: [32, 0, 17], sources: ['memory'], accent: '#72e6a6' },
  { id: 'data', label: 'Data Vault', direction: 'South', landmark: 'vault servers', anchor: [0, 0, 34], sources: ['storage'], accent: '#55c2ff' },
  { id: 'federation', label: 'Federation Harbor', direction: 'Southwest', landmark: 'portal gate', anchor: [-32, 0, 17], sources: ['peers'], accent: '#66f0d0' },
  { id: 'activity', label: 'Activity River', direction: 'Inner south', landmark: 'light river', anchor: [0, 0, 14], sources: ['activity', 'productivity'], accent: '#ff78b7' },
]);

export const EIDOVERSE_ASSET_SLOTS_BY_DISTRICT = Object.freeze({
  // Include retired V1 kind keys as well as V2 semantic slots. A scoped reset
  // must clear hidden preserved overrides that can still win assetPathFor().
  nexus: ['nexus', 'health', 'operations', 'feature', 'district', 'activity', 'tree'],
  apps: ['app', 'desk', 'activity', 'tree'],
  agents: ['agent', 'task', 'desk', 'app', 'barrel', 'activity', 'tree'],
  goals: ['goal', 'jira', 'desk', 'app', 'activity', 'tree'],
  memory: ['memory', 'activity', 'tree'],
  data: ['storage', 'app', 'desk', 'barrel', 'task', 'activity', 'tree'],
  federation: ['peer', 'barrel', 'task', 'activity', 'tree'],
  activity: ['activity', 'productivity', 'tree'],
});

export const EIDOVERSE_PATHS_V2 = Object.freeze(EIDOVERSE_DISTRICTS_V2
  .filter(({ id }) => id !== 'nexus')
  .map((district) => ({
    id: `nexus-${district.id}`,
    label: `Nexus to ${district.label}`,
    toDistrictId: district.id,
    nodes: [0.27, 0.52, 0.77].map((amount) => [
      Number((district.anchor[0] * amount).toFixed(2)),
      0.08,
      Number((district.anchor[2] * amount).toFixed(2)),
    ]),
  })));

export const EIDOVERSE_WORLD_DESIGN_V2 = Object.freeze({
  version: 2,
  name: 'Luminous Systems Garden',
  maxEntities: EIDOVERSE_MAX_LIVE_ENTITIES,
  includes: Object.fromEntries(EIDOVERSE_SOURCE_KEYS.map((key) => [key, true])),
  limits: {
    apps: 8, agents: 6, tasks: 6, features: 4, peers: 4,
    health: 1, productivity: 1, activity: 3, goals: 4,
    memory: 3, storage: 4, jira: 3, operations: 1,
  },
  scale: {
    app: 0.55, agent: 0.55, task: 0.48, feature: 0.5, peer: 0.7,
    health: 0.8, productivity: 0.75, activity: 0.52, goal: 0.6,
    memory: 0.42, storage: 0.48, jira: 0.5, operations: 0.9,
  },
  districts: EIDOVERSE_DISTRICTS_V2,
  paths: EIDOVERSE_PATHS_V2,
  environment: {
    terrain: {
      seed: 'portos-systems-garden-v2', size: 180, segments: 96,
      amplitude: 1.4, flatRadius: 48,
      layers: [{ color: '#0d1629', repeat: 22 }, { color: '#152942', repeat: 13 }],
    },
    sky: {
      system: 'skymesh', hours: 7.2, azimuth: 145, sun: 1.35,
      ambient: 1.2, fill: 1.1, exposure: 1.08, fog: 0.42,
      clouds: 'cirrus', weather: 'clear',
    },
    grass: {
      species: 'grass', width: 154, depth: 144, center: [0, 0],
      height: 0.22, color: 'gray-green', density: 0.45,
    },
    lights: [
      { id: `${EIDOVERSE_MANAGED_PREFIX}light-nexus`, pos: [0, 8, 1], color: 0x65d9ff, intensity: 22, range: 28, keep: true, day: true },
      { id: `${EIDOVERSE_MANAGED_PREFIX}light-east`, pos: [25, 7, 4], color: 0x72e6a6, intensity: 15, range: 23, keep: true, day: true },
      { id: `${EIDOVERSE_MANAGED_PREFIX}light-west`, pos: [-25, 7, 4], color: 0x65d9ff, intensity: 15, range: 23, keep: true, day: true },
    ],
  },
  assetRecipe: EIDOVERSE_ASSET_RECIPE_V2,
  assets: {},
});

// V2 remains frozen as the exact migration baseline. V3 uses the framework's
// existing structure component; the shared architecture contains no user data.
export const EIDOVERSE_ASSET_RECIPE_V3 = {
  version: 3,
  slots: {
    ...EIDOVERSE_ASSET_RECIPE_V2.slots,
    app: { ...EIDOVERSE_ASSET_RECIPE_V2.slots.app,
      preferredPaths: [`${MODEL_ROOT}scif_cyberpunk_crt_retro_computer_monitor_screen_keyboard_tower.glb`],
      fallbackQueries: ['retro computer', 'computer terminal'], requiredTokens: ['computer'], maxBytes: 44_000_000 },
    storage: { ...EIDOVERSE_ASSET_RECIPE_V2.slots.storage,
      preferredPaths: [`${MODEL_ROOT}single_loose_computer_server.glb`],
      fallbackQueries: ['computer server'], requiredTokens: ['server'] },
    task: { ...EIDOVERSE_ASSET_RECIPE_V2.slots.task,
      preferredPaths: [`${MODEL_ROOT}crate_large_blue.glb`] },
    desk: assetSlot({
      preferredPaths: [`${MODEL_ROOT}scifi_art_deco_office_desk.glb`],
      fallbackQueries: ['office desk'], requiredTokens: ['desk'], maxBytes: 24_000_000,
      fallback: `${MODEL_ROOT}crate_large_blue.glb`,
    }),
    barrel: assetSlot({
      preferredPaths: [`${MODEL_ROOT}scifi_barrels_single.glb`],
      fallbackQueries: ['barrel'], requiredTokens: ['barrel'], maxBytes: 16_000_000,
      fallback: `${MODEL_ROOT}crate_large_blue.glb`,
    }),
    tree: assetSlot({
      preferredPaths: [`${MODEL_ROOT}palm_date_tree_tropical_deseert_oasis_plant.glb`],
      fallbackQueries: ['palm tree'], requiredTokens: ['tree'], maxBytes: 24_000_000,
      fallback: `${MODEL_ROOT}stylized_yucca_joshua_tree_desert_cactus_plant.glb`,
    }),
  },
};

export const EIDOVERSE_WORLD_DESIGN_V3 = {
  ...structuredClone(EIDOVERSE_WORLD_DESIGN_V2),
  version: 3,
  name: 'PortOS Commons',
  districts: EIDOVERSE_DISTRICTS_V2.map((district) => ({
    ...district,
    anchor: ({
      nexus: [-44, 0, 0], apps: [-31.11, 0, -31.11], agents: [0, 0, -44],
      goals: [31.11, 0, -31.11], memory: [44, 0, 0], data: [31.11, 0, 31.11],
      federation: [-31.11, 0, 31.11], activity: [0, 0, 44],
    })[district.id],
    label: ({ apps: 'App Arcade', memory: 'Memory Library', data: 'Data Depot', federation: 'Federation Terminal', activity: 'Activity Exchange' })[district.id] || district.label,
    landmark: ({ nexus: 'civic spire', apps: 'console arcade', agents: 'workshop courtyard', goals: 'beacon hall', memory: 'reading hall', data: 'storage depot', federation: 'arrival gate', activity: 'exchange hall' })[district.id],
    direction: ({ nexus: 'West', memory: 'East', data: 'Southeast', activity: 'South' })[district.id] || district.direction,
  })),
  // A pedestrian promenade links inward-facing halls around the arrival park.
  paths: [],
  environment: {
    ...structuredClone(EIDOVERSE_WORLD_DESIGN_V2.environment),
    sky: { ...structuredClone(EIDOVERSE_WORLD_DESIGN_V2.environment.sky), hours: 10, fog: 0.16, exposure: 1.15 },
    terrain: {
      seed: 'portos-commons-v3', size: 180, segments: 96,
      amplitude: 0.7, flatRadius: 65,
      layers: [{ color: '#527044', repeat: 32 }, { color: '#738459', repeat: 18 }],
    },
    grass: {
      species: 'grass', width: 38, depth: 38, center: [0, 0],
      height: 0.24, color: 'emerald', density: 0.7,
    },
  },
  assetRecipe: EIDOVERSE_ASSET_RECIPE_V3,
};

const EIDOVERSE_V2_DEFAULT_CHANGES = Object.freeze([
  { area: 'Composition', from: 'uniform resource lanes', to: 'eight semantic districts and circulation paths' },
  { area: 'Atmosphere', from: 'terrain only', to: 'warm dawn sky, authored light, restrained fog, and sparse grass' },
  { area: 'Assets', from: 'resource-kind model paths', to: 'portable semantic slots with install-local locks' },
  { area: 'Signals', from: 'independent high source caps', to: 'bounded aggregate signals under one 48-entity budget' },
]);

export const EIDOVERSE_WORLD_DESIGNS = Object.freeze({
  1: EIDOVERSE_WORLD_DESIGN_V1,
  2: EIDOVERSE_WORLD_DESIGN_V2,
  3: EIDOVERSE_WORLD_DESIGN_V3,
});

function freezeWorldContract(value) {
  if (value && typeof value === 'object') {
    for (const child of Object.values(value)) freezeWorldContract(child);
    Object.freeze(value);
  }
  return value;
}

// Object.freeze is shallow. Recursively lock every registry leaf so a route or
// test cannot accidentally mutate the migration baseline for later installs.
freezeWorldContract(EIDOVERSE_WORLD_DESIGN_V1);
freezeWorldContract(EIDOVERSE_ASSET_RECIPE_V2);
freezeWorldContract(EIDOVERSE_DISTRICTS_V2);
freezeWorldContract(EIDOVERSE_ASSET_SLOTS_BY_DISTRICT);
freezeWorldContract(EIDOVERSE_PATHS_V2);
freezeWorldContract(EIDOVERSE_WORLD_DESIGN_V2);
freezeWorldContract(EIDOVERSE_ASSET_RECIPE_V3);
freezeWorldContract(EIDOVERSE_WORLD_DESIGN_V3);
freezeWorldContract(EIDOVERSE_WORLD_DESIGNS);

const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
const clone = (value) => structuredClone(value);
const equal = (left, right) => canonicalStringify(left) === canonicalStringify(right);

const mergeDesign = (base, patch) => clone(deepMerge(clone(base), clone(patch)));

function diffLeaves(value, baseline) {
  if (equal(value, baseline)) return undefined;
  if (!isObject(value) || !isObject(baseline)) return clone(value);
  const output = {};
  for (const [key, child] of Object.entries(value)) {
    const diff = diffLeaves(child, baseline[key]);
    if (diff !== undefined) output[key] = diff;
  }
  return Object.keys(output).length ? output : undefined;
}

export function resolveEidoverseDesign(userOverrides = {}, assetResolutions = {}) {
  const resolved = mergeDesign(EIDOVERSE_WORLD_DESIGN_V3, userOverrides);
  resolved.version = EIDOVERSE_WORLD_DESIGN_VERSION;
  resolved.assetRecipe = clone(EIDOVERSE_ASSET_RECIPE_V3);
  resolved.assets = { ...(resolved.assets || {}) };
  for (const [slot, resolution] of Object.entries(assetResolutions || {})) {
    const path = typeof resolution === 'string' ? resolution : resolution?.path;
    if (path) resolved.assets[slot] = path;
  }
  return resolved;
}

export function extractEidoverseDesignOverrides(recipe) {
  if (!isObject(recipe)) return {};
  const candidate = {};
  // `recipe.assets` contains the materialized per-install resolution lock in
  // status responses. It is not a user override merely because the client
  // round-tripped the effective recipe; explicit overrides use the dedicated
  // `assetOverrides` config field.
  for (const section of ['name', 'maxEntities', 'includes', 'limits', 'scale', 'districts', 'paths', 'environment']) {
    if (recipe[section] !== undefined) candidate[section] = clone(recipe[section]);
  }
  const baseline = EIDOVERSE_WORLD_DESIGNS[recipe.version] || EIDOVERSE_WORLD_DESIGN_V3;
  return diffLeaves(mergeDesign(baseline, candidate), baseline) || {};
}

const validLibraryPath = (path) => typeof path === 'string'
  && path.startsWith(EIDOVERSE_LIBRARY_MODEL_ROOT)
  && !path.includes('..')
  && path.toLowerCase().endsWith('.glb');

export const isValidEidoverseAssetOverridePath = (path) => validLibraryPath(path) || (
  typeof path === 'string'
  && /^store\/[A-Za-z0-9._/-]+$/.test(path)
  && !path.includes('..')
);

function v1OverridesForV2(legacyRecipe) {
  const legacy = mergeDesign(EIDOVERSE_WORLD_DESIGN_V1, legacyRecipe || {});
  const v1Diff = diffLeaves(legacy, EIDOVERSE_WORLD_DESIGN_V1) || {};
  const overrides = {};
  for (const section of ['includes', 'scale']) {
    if (v1Diff[section]) overrides[section] = clone(v1Diff[section]);
  }
  const unsupportedLimits = {};
  if (isObject(v1Diff.limits)) {
    const preservedLimits = {};
    for (const [source, value] of Object.entries(v1Diff.limits)) {
      const v2Limit = EIDOVERSE_WORLD_DESIGN_V2.limits[source];
      if (!Number.isInteger(value) || value < 0 || !Number.isInteger(v2Limit) || value > v2Limit) {
        unsupportedLimits[source] = clone(value);
        continue;
      }
      preservedLimits[source] = value;
    }
    if (Object.keys(preservedLimits).length) overrides.limits = preservedLimits;
  } else if (v1Diff.limits !== undefined) {
    unsupportedLimits.value = clone(v1Diff.limits);
  }
  if (v1Diff.terrain) overrides.environment = { terrain: clone(v1Diff.terrain) };
  let unportableAssets;
  if (isObject(v1Diff.assets)) {
    const entries = Object.entries(v1Diff.assets);
    const portable = entries.filter(([, path]) => isValidEidoverseAssetOverridePath(path));
    if (portable.length) {
      overrides.assets = Object.fromEntries(portable.map(([key, path]) => [key, clone(path)]));
    }
    const rejected = entries.filter(([, path]) => !isValidEidoverseAssetOverridePath(path));
    if (rejected.length) {
      unportableAssets = Object.fromEntries(rejected.map(([key, path]) => [key, clone(path)]));
    }
  } else if (v1Diff.assets !== undefined) {
    unportableAssets = clone(v1Diff.assets);
  }
  // V1's lane geometry and any unknown legacy extension have no safe semantic
  // translation to districts. Preserve their exact values in the report
  // instead of silently distorting the V2 garden or losing customization.
  const unsupportedOverrides = Object.fromEntries(Object.entries(v1Diff)
    .filter(([section]) => !['includes', 'limits', 'scale', 'terrain', 'assets'].includes(section))
    .map(([section, value]) => [section, clone(value)]));
  if (Object.keys(unsupportedLimits).length) unsupportedOverrides.limits = unsupportedLimits;
  if (unportableAssets !== undefined) unsupportedOverrides.assets = unportableAssets;
  return { overrides, unsupportedOverrides };
}

export function migrateEidoverseWorldState(raw, { now = new Date().toISOString() } = {}) {
  if (raw !== null && raw !== undefined && !isObject(raw)) {
    return {
      compatible: false,
      state: raw,
      report: {
        status: 'blocked', fromSchemaVersion: null,
        toSchemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
        reason: 'invalid-state-shape', at: now,
      },
    };
  }
  const input = isObject(raw) ? clone(raw) : {};
  const inputSchema = Number(input.schemaVersion ?? 1);
  if (!Number.isInteger(inputSchema) || inputSchema < 1) {
    return {
      compatible: false,
      state: input,
      report: {
        status: 'blocked', fromSchemaVersion: input.schemaVersion ?? null,
        toSchemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
        reason: 'invalid-state-schema', at: now,
      },
    };
  }
  if (inputSchema > EIDOVERSE_WORLD_STATE_SCHEMA_VERSION) {
    return {
      compatible: false,
      state: input,
      report: {
        status: 'blocked', fromSchemaVersion: inputSchema,
        toSchemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
        reason: 'newer-state-schema', at: now,
      },
    };
  }
  const inputDesignVersions = [
    input.selectedDesignVersion,
    input.lastAppliedDesignVersion,
    input.pendingDesignVersion,
    input.recipe?.version,
  ].filter((value) => value !== null && value !== undefined).map(Number);
  if (inputDesignVersions.some((version) => !Number.isInteger(version) || version < 1)) {
    return {
      compatible: false,
      state: input,
      report: {
        status: 'blocked', fromSchemaVersion: inputSchema,
        toSchemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
        reason: 'invalid-design-version', at: now,
      },
    };
  }
  if (inputDesignVersions.some((version) => version > EIDOVERSE_WORLD_DESIGN_VERSION)) {
    return {
      compatible: false,
      state: input,
      report: {
        status: 'blocked', fromSchemaVersion: inputSchema,
        toSchemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
        reason: 'newer-design-version', at: now,
      },
    };
  }
  const inputAssetRecipeVersion = input.assetRecipeVersion === null || input.assetRecipeVersion === undefined
    ? null
    : Number(input.assetRecipeVersion);
  if (inputAssetRecipeVersion !== null
    && (!Number.isInteger(inputAssetRecipeVersion) || inputAssetRecipeVersion < 1)) {
    return {
      compatible: false,
      state: input,
      report: {
        status: 'blocked', fromSchemaVersion: inputSchema,
        toSchemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
        reason: 'invalid-asset-recipe-version', at: now,
      },
    };
  }
  if (inputAssetRecipeVersion > EIDOVERSE_ASSET_RECIPE_VERSION) {
    return {
      compatible: false,
      state: input,
      report: {
        status: 'blocked', fromSchemaVersion: inputSchema,
        toSchemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
        reason: 'newer-asset-recipe-version', at: now,
      },
    };
  }

  const removedMachineDerivedIdentity = input.human?.source === 'instance-name';
  if (removedMachineDerivedIdentity) {
    const retiredWorld = typeof input.world === 'string' && input.world.trim()
      ? input.world.trim()
      : 'portos';
    const retiredIdentity = typeof input.human?.name === 'string'
      ? input.human.name.trim()
      : '';
    if (retiredIdentity) {
      const ownership = isObject(input.ownership) ? input.ownership : {};
      const existingRetired = Array.isArray(ownership.retired) ? ownership.retired : [];
      input.ownership = {
        ...ownership,
        retired: [
          ...existingRetired.filter((entry) => !(
            entry?.world === retiredWorld && entry?.id === retiredIdentity
          )),
          {
            world: retiredWorld,
            id: retiredIdentity,
            ...(typeof input.cos?.id === 'string' && input.cos.id.trim() ? {
              actorId: input.cos.id.trim(),
              ...(typeof input.cos?.avatar === 'string' ? { actorAvatar: input.cos.avatar } : {}),
            } : {}),
          },
        ],
      };
    }
    input.human = {
      ...input.human,
      name: null,
      source: null,
      role: null,
    };
  }

  if (inputSchema >= 2) {
    const userOverrides = isObject(input.userOverrides)
      ? input.userOverrides
      : extractEidoverseDesignOverrides(input.recipe);
    const assetResolutions = isObject(input.assetResolutions) ? input.assetResolutions : {};
    const upgradingDesign = Number(input.selectedDesignVersion ?? input.recipe?.version ?? 2) < 3;
    const report = upgradingDesign
      ? { ...(input.migrationReport || {}),
          ...(removedMachineDerivedIdentity ? { removedMachineDerivedIdentity: true } : {}),
          status: 'ready', fromDesignVersion: Number(input.selectedDesignVersion ?? input.recipe?.version ?? 2),
          toDesignVersion: 3, preservedOverrides: Object.keys(userOverrides), at: now }
      : removedMachineDerivedIdentity
      ? {
        ...(input.migrationReport || {}),
        status: input.migrationReport?.status || 'applied',
        removedMachineDerivedIdentity: true,
        at: input.migrationReport?.at || now,
      }
      : (input.migrationReport || null);
    return {
      compatible: true,
      state: {
        ...input,
        schemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
        labelAliases: normalizeEidoverseLabelAliases(input.labelAliases),
        selectedDesignVersion: EIDOVERSE_WORLD_DESIGN_VERSION,
        ...(upgradingDesign ? { pendingDesignVersion: 3 } : {}),
        assetRecipeVersion: EIDOVERSE_ASSET_RECIPE_VERSION,
        userOverrides,
        assetResolutions,
        migrationReport: report,
        recipe: resolveEidoverseDesign(userOverrides, assetResolutions),
      },
      report,
    };
  }

  const { overrides, unsupportedOverrides } = v1OverridesForV2(input.recipe);
  const customizedLeaves = Object.keys(overrides).flatMap((section) =>
    Object.keys(overrides[section] || {}).map((key) => `${section}.${key}`));
  const report = {
    status: 'ready', fromSchemaVersion: inputSchema,
    fromDesignVersion: 1, toSchemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
    toDesignVersion: EIDOVERSE_WORLD_DESIGN_VERSION,
    inheritedDefaultLeaves: true,
    adoptedDefaultChanges: clone(EIDOVERSE_V2_DEFAULT_CHANGES),
    preservedOverrides: customizedLeaves,
    unsupportedOverrides,
    removedMachineDerivedIdentity,
    // Retain the named field used by the V2 UI and early migration previews.
    ignoredLegacyLayout: unsupportedOverrides.layout || null,
    at: now,
  };
  return {
    compatible: true,
    state: {
      ...input,
      schemaVersion: EIDOVERSE_WORLD_STATE_SCHEMA_VERSION,
      labelAliases: {},
      selectedDesignVersion: EIDOVERSE_WORLD_DESIGN_VERSION,
      lastAppliedDesignVersion: 1,
      pendingDesignVersion: EIDOVERSE_WORLD_DESIGN_VERSION,
      userOverrides: overrides,
      assetRecipeVersion: EIDOVERSE_ASSET_RECIPE_VERSION,
      assetResolutions: {},
      migrationReport: report,
      reconciliation: {
        status: 'pending', checkpoint: 'migration-complete', error: null,
        startedAt: null, completedAt: null,
      },
      recipe: resolveEidoverseDesign(overrides),
    },
    report,
  };
}

const tokenized = (value) => String(value || '')
  .toLowerCase()
  .replace(/\.[a-z0-9]+$/i, '')
  .split(/[^a-z0-9]+/)
  .filter(Boolean);

const contractFingerprint = (value) => createHash('sha256')
  .update(canonicalStringify(value))
  .digest('hex')
  .slice(0, 16);

function candidateScore(candidate, slot, preferredIndex, searchRank, allowCatalogFallback) {
  const tokens = tokenized(candidate.path);
  const hasSemanticToken = (needle) => tokens.some((token) => token === needle || token.includes(needle));
  if (slot.excludedTokens.some((needle) => tokens.includes(needle))) return null;
  if (candidate.size !== null && candidate.size > slot.maxBytes) return null;
  const preferred = preferredIndex.get(candidate.path);
  const searched = searchRank.get(candidate.path);
  const fallback = candidate.path === slot.fallback;
  if (preferred === undefined && searched === undefined && !allowCatalogFallback) return null;
  const queryTokens = slot.fallbackQueries.flatMap(tokenized);
  const queryMatches = queryTokens.filter((token) => tokens.some((candidateToken) => (
    candidateToken === token || candidateToken.includes(token)
  ))).length;
  const requiredMatches = slot.requiredTokens.filter(hasSemanticToken).length;
  return (preferred === undefined ? 0 : 1_000_000 - preferred * 10_000)
    + (searched === undefined ? 0 : 200_000 - searched * 100)
    + (fallback ? 100_000 : 0)
    + requiredMatches * 1_000
    + queryMatches * 10
    - (candidate.size === null ? 10_000 : 0)
    - Number(candidate.size || 0) / 1_000_000;
}

function addCatalogCandidate(catalog, candidate) {
  const path = typeof candidate === 'string' ? candidate : candidate?.path;
  if (!validLibraryPath(path)) return;
  const rawSize = typeof candidate === 'string' ? null : candidate?.size;
  const numericSize = Number(rawSize);
  const size = rawSize !== null && rawSize !== undefined && rawSize !== ''
    && Number.isFinite(numericSize) && numericSize >= 0
    ? numericSize
    : null;
  const prior = catalog.get(path);
  if (!prior
    || (prior.size === null && size !== null)
    || (prior.size !== null && size !== null && size < prior.size)) {
    catalog.set(path, { path, size });
  }
}

/**
 * Inspect a persisted V2 lock without touching the Eidoverse catalog.
 *
 * A projection can reuse a complete lock after verifying its selected paths;
 * only changed recipe slots, changed overrides, or incomplete metadata need a
 * catalog/search pass.
 */
export function inspectEidoverseAssetResolutionLocks({ existing = {}, overrides = {} } = {}) {
  const resolutions = {};
  const invalidated = [];
  for (const [slotName, slot] of Object.entries(EIDOVERSE_ASSET_RECIPE_V3.slots)) {
    const lock = isObject(existing[slotName]) ? existing[slotName] : null;
    const overridePath = overrides[slotName];
    const hasOverride = isValidEidoverseAssetOverridePath(overridePath);
    const expectedPathIsValid = hasOverride
      ? lock?.path === overridePath
      : validLibraryPath(lock?.path);
    const current = expectedPathIsValid
      && lock.slot === slotName
      && lock.recipeFingerprint === contractFingerprint(slot)
      && lock.userOverride === hasOverride;
    if (!current) {
      invalidated.push(slotName);
      continue;
    }
    resolutions[slotName] = {
      ...clone(lock),
      designVersion: EIDOVERSE_WORLD_DESIGN_VERSION,
      assetRecipeVersion: EIDOVERSE_ASSET_RECIPE_VERSION,
    };
  }
  return { current: invalidated.length === 0, invalidated, resolutions };
}

/** Resolve every semantic slot deterministically from an Eidoverse catalog. */
export function resolveEidoverseAssetRecipe({
  files = [],
  searchResults = {},
  existing = {},
  overrides = {},
  resolvedAt = null,
} = {}) {
  const catalog = new Map();
  for (const candidate of files) addCatalogCandidate(catalog, candidate);
  for (const values of Object.values(searchResults || {})) {
    for (const candidate of Array.isArray(values) ? values : []) addCatalogCandidate(catalog, candidate);
  }

  const fingerprint = createHash('sha256')
    .update([...catalog.values()].sort((a, b) => a.path.localeCompare(b.path)).map(({ path, size }) => `${path}:${size ?? 'unknown'}`).join('\n'))
    .digest('hex').slice(0, 16);
  const resolutions = {};
  const missing = [];
  for (const [slotName, slot] of Object.entries(EIDOVERSE_ASSET_RECIPE_V3.slots)) {
    const recipeFingerprint = contractFingerprint(slot);
    const overridePath = overrides[slotName];
    const locked = isObject(existing[slotName]) ? existing[slotName] : { path: existing[slotName] };
    const lockedPath = locked.path;
    const baseResolution = (path, strategy, userOverride, prior = null, bytes = null) => ({
      designVersion: EIDOVERSE_WORLD_DESIGN_VERSION,
      assetRecipeVersion: EIDOVERSE_ASSET_RECIPE_VERSION,
      slot: slotName,
      path,
      catalogFingerprint: prior?.catalogFingerprint || fingerprint,
      recipeFingerprint,
      bytes: prior?.bytes ?? bytes,
      ...(prior?.bounds ? { bounds: clone(prior.bounds) } : {}),
      strategy,
      // `source` is retained for the V2 UI and pre-metadata lock readers.
      source: strategy,
      resolvedAt: prior?.resolvedAt || resolvedAt,
      shippedDefault: !userOverride,
      userOverride,
    });
    if (isValidEidoverseAssetOverridePath(overridePath)) {
      if (lockedPath === overridePath
        && locked.userOverride === true
        && locked.recipeFingerprint === recipeFingerprint) {
        resolutions[slotName] = baseResolution(overridePath, 'user-override', true, locked, catalog.get(overridePath)?.size ?? null);
      } else {
        resolutions[slotName] = baseResolution(overridePath, 'user-override', true, null, catalog.get(overridePath)?.size ?? null);
      }
      continue;
    }
    const lockMatchesRecipe = locked.recipeFingerprint === undefined
      || locked.recipeFingerprint === recipeFingerprint;
    if (validLibraryPath(lockedPath)
      && catalog.has(lockedPath)
      && locked.userOverride !== true
      && lockMatchesRecipe) {
      const strategy = locked.strategy || locked.source || 'lock';
      resolutions[slotName] = baseResolution(lockedPath, strategy, false, locked, catalog.get(lockedPath)?.size ?? null);
      continue;
    }
    const preferredIndex = new Map(slot.preferredPaths.map((path, index) => [path, index]));
    const searchRank = new Map();
    slot.fallbackQueries.forEach((query, queryIndex) => {
      const candidates = Array.isArray(searchResults[query]) ? searchResults[query] : [];
      candidates.forEach((candidate, resultIndex) => {
        const path = typeof candidate === 'string' ? candidate : candidate?.path;
        if (!validLibraryPath(path)) return;
        const rank = queryIndex * 1000 + resultIndex;
        if (!searchRank.has(path) || rank < searchRank.get(path)) {
          searchRank.set(path, rank);
        }
      });
    });
    const searchWasAttempted = slot.fallbackQueries.some((query) => Object.hasOwn(searchResults, query));
    const ranked = [...catalog.values()]
      .map((candidate) => ({
        candidate,
        score: candidateScore(candidate, slot, preferredIndex, searchRank, searchWasAttempted),
      }))
      .filter(({ score }) => score !== null)
      .sort((a, b) => b.score - a.score || a.candidate.path.localeCompare(b.candidate.path));
    const fallbackCandidate = catalog.get(slot.fallback);
    const fallbackTokens = fallbackCandidate ? tokenized(fallbackCandidate.path) : [];
    const fallbackAllowed = fallbackCandidate
      && (fallbackCandidate.size === null || fallbackCandidate.size <= slot.maxBytes)
      && !slot.excludedTokens.some((needle) => fallbackTokens.includes(needle));
    const chosen = ranked[0]?.candidate || (searchWasAttempted && fallbackAllowed ? fallbackCandidate : null);
    if (!chosen) {
      missing.push(slotName);
      continue;
    }
    const strategy = preferredIndex.has(chosen.path)
      ? 'preferred'
      : (searchRank.has(chosen.path)
          ? 'query'
          : (chosen.path === slot.fallback ? 'fallback' : 'catalog-fallback'));
    resolutions[slotName] = baseResolution(chosen.path, strategy, false, null, chosen.size);
  }
  return { resolutions, missing, catalogFingerprint: fingerprint };
}

export function stableEidoverseUnit(value) {
  const hash = createHash('sha256').update(String(value)).digest();
  return hash.readUInt32BE(0) / 0xffffffff;
}