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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* The documented creative toolkit for minds building Eidoverse vernacular
* content (#7459, part of the stigmergic-federation epic #7453).
*
* `eidoverseFoundations.js` already gives an install a place to keep a build
* ({ body, style }, vernacular by default, promotion explicit) and
* `eidoverseWorld.js`'s `eidoverse.augment` already lets a mind place bounded
* geometry in the live scene. What was still missing was a small, DOCUMENTED
* vocabulary a mind can reach for instead of inventing coordinates and colors
* from scratch every time: named materials, named motifs, and named
* generative placement layouts.
*
* - **Materials** and **motifs** are cosmetics — install-local style, the
* kind of choice `eidoverseFoundations.js` keeps out of a promoted `body`.
* - **Layouts** are generative PLACEMENT algorithms, keyed by a closed id so
* a promoted `district-template.body.layoutId` reproduces the same
* geometry on any install that inherits it — the same reason
* `EIDOVERSE_FOUNDATION_KINDS` is a closed list rather than free text.
*
* Every layout is a deterministic, seeded placement function: same
* `{layoutId, anchor, propCount, seed, facing}` always yields the same
* positions, and nothing here ever calls an AI provider. That is what keeps
* "generative placement" on the right side of the no-cold-bootstrap-LLM-call
* rule (root `AGENTS.md`) — a mind (or a human, through the same helpers)
* picks a layout/material/motif and this module computes WHERE things go
* with plain seeded math, not a model call.
*
* `buildDistrictTemplateFoundationDraft` shapes its output to match
* `eidoverseFoundationInputSchema` (`eidoverseFoundations.js`) directly: the
* generative placement is substance and lands in `body`; the material/motif
* choice is cosmetics and lands in `style`. Pure: no I/O, no clock, no
* provider calls.
*
* Every builder here has a real, non-test caller (#7627): `describeCreativeCatalog()`
* is `eidoverse.creative-catalog`; `buildDistrictTemplateAugmentOperations()`
* (via `generateDistrictTemplatePlacement()`) is `eidoverse.place-layout`;
* `buildDistrictTemplateFoundationDraft()` is `eidoverse.draft-foundation`
* (`services/cosToolRegistry.js`); and `generateDistrictTemplatePlacement()`
* is also what `services/eidoverseFoundationLedger.js`'s
* `recordEidoverseFoundation()` replays server-side to derive a
* `district-template`'s `body.placement` from its declared
* `{layoutId, anchor, seed}` rather than trusting a caller-supplied one.
*/
import { z } from 'zod';
import { eidoverseFoundationInputSchema } from './eidoverseFoundations.js';
const clampInt = (value, min, max) => Math.min(max, Math.max(min, Math.round(value)));
// ---------------------------------------------------------------------------
// Catalog
// ---------------------------------------------------------------------------
/** Cosmetic palettes. Style-layer only — never a foundation `body` key. */
export const EIDOVERSE_CREATIVE_MATERIALS = Object.freeze([
{ id: 'sunbaked-clay', label: 'Sunbaked Clay', colorHex: '#c97a4a', description: 'Warm terracotta walls and rammed-earth paths.' },
{ id: 'weathered-copper', label: 'Weathered Copper', colorHex: '#4fa389', description: 'Oxidized green-blue metal roofing and trim.' },
{ id: 'moonlit-slate', label: 'Moonlit Slate', colorHex: '#5b6b8c', description: 'Cool blue-grey stone for quiet, nocturnal districts.' },
{ id: 'coral-lacquer', label: 'Coral Lacquer', colorHex: '#e0637a', description: 'Glossy warm accent panels for a lively market feel.' },
{ id: 'moss-stone', label: 'Moss Stone', colorHex: '#6f8f5a', description: 'Lichen-soft greys and greens for overgrown, garden districts.' },
{ id: 'brushed-steel', label: 'Brushed Steel', colorHex: '#8d97a3', description: 'Cool neutral metal for utilitarian, technical districts.' },
]);
/** Decorative arrangement intent. Style-layer only — never a `body` key. */
export const EIDOVERSE_CREATIVE_MOTIFS = Object.freeze([
{ id: 'lantern-row', label: 'Lantern Row', description: 'Evenly spaced light fixtures tracing the placement path.' },
{ id: 'garden-grove', label: 'Garden Grove', description: 'Planted greenery softening every prop position.' },
{ id: 'colonnade', label: 'Colonnade', description: 'Repeated vertical structural accents, formal and rhythmic.' },
{ id: 'market-stalls', label: 'Market Stalls', description: 'Low, dense furniture suggesting trade and gathering.' },
{ id: 'tide-pools', label: 'Tide Pools', description: 'Irregular, water-adjacent clustering.' },
]);
const RING_RADIUS = 6;
const GRID_SPACING = 3;
const ARC_RADIUS = 7;
const ARC_SPAN = Math.PI / 1.5; // 120 degrees, centered on `facing`
const GROVE_RADIUS = 5;
/** Deterministic seeded placement, one point (and facing yaw) per prop index. */
function radialRing(anchor, count, rng, facing) {
return Array.from({ length: count }, (_, index) => {
const angle = facing + (Math.PI * 2 * index) / count;
const pos = [anchor[0] + Math.cos(angle) * RING_RADIUS, anchor[1], anchor[2] + Math.sin(angle) * RING_RADIUS];
return { pos, yaw: angle + Math.PI };
});
}
function gridPlot(anchor, count, rng, facing) {
const columns = Math.max(1, Math.ceil(Math.sqrt(count)));
const cos = Math.cos(facing);
const sin = Math.sin(facing);
return Array.from({ length: count }, (_, index) => {
const row = Math.floor(index / columns);
const col = index % columns;
const localX = (col - (columns - 1) / 2) * GRID_SPACING;
const localZ = row * GRID_SPACING + GRID_SPACING;
const pos = [anchor[0] + localX * cos + localZ * sin, anchor[1], anchor[2] - localX * sin + localZ * cos];
return { pos, yaw: facing + Math.PI };
});
}
function arcRow(anchor, count, rng, facing) {
return Array.from({ length: count }, (_, index) => {
const spread = count > 1 ? (index / (count - 1) - 0.5) * ARC_SPAN : 0;
const angle = facing + spread;
const pos = [anchor[0] + Math.cos(angle) * ARC_RADIUS, anchor[1], anchor[2] + Math.sin(angle) * ARC_RADIUS];
return { pos, yaw: angle + Math.PI };
});
}
function groveCluster(anchor, count, rng, facing) {
return Array.from({ length: count }, () => {
const angle = facing + rng() * Math.PI * 2;
const radius = GROVE_RADIUS * Math.sqrt(rng());
const pos = [anchor[0] + Math.cos(angle) * radius, anchor[1], anchor[2] + Math.sin(angle) * radius];
return { pos, yaw: rng() * Math.PI * 2 };
});
}
/** Named generative placement algorithms. Structural — safe in a foundation `body`. */
const LAYOUT_GENERATORS = Object.freeze({
'radial-ring': radialRing,
'grid-plot': gridPlot,
'arc-row': arcRow,
'grove-cluster': groveCluster,
});
export const EIDOVERSE_CREATIVE_LAYOUTS = Object.freeze([
{ id: 'radial-ring', label: 'Radial Ring', description: 'Props spaced evenly around the anchor, facing inward.' },
{ id: 'grid-plot', label: 'Grid Plot', description: 'A rectangular grid of props extending from the anchor.' },
{ id: 'arc-row', label: 'Arc Row', description: 'Props along a 120-degree arc facing one direction, e.g. a storefront row.' },
{ id: 'grove-cluster', label: 'Grove Cluster', description: 'An organic, seeded-random cluster — useful for gardens or ruins.' },
]);
const findById = (catalog, id) => catalog.find((entry) => entry.id === id);
function requireCatalogEntry(catalog, id, label) {
const entry = findById(catalog, id);
if (!entry) throw new RangeError(`Unknown ${label} "${id}". Expected one of ${catalog.map((item) => item.id).join(', ')}.`);
return entry;
}
/**
* A mind- and prompt-safe projection of the toolkit: ids, labels, descriptions
* — plus, for materials, `colorHex` (#7627). A palette id whose value a mind
* cannot see is not a usable catalog entry: the mind picks `sunbaked-clay` for
* a foundation's `style` and needs the actual hex to reason about how it reads
* next to whatever else it is building. `colorHex` is cosmetic display data,
* not a foundation `body` key, so exposing it here does not widen what a mind
* can put in a promotable body.
*/
export function describeCreativeCatalog() {
const project = (catalog) => catalog.map(({ id, label, description }) => ({ id, label, description }));
const projectMaterials = (catalog) => catalog.map(({ id, label, description, colorHex }) => ({ id, label, description, colorHex }));
return {
materials: projectMaterials(EIDOVERSE_CREATIVE_MATERIALS),
motifs: project(EIDOVERSE_CREATIVE_MOTIFS),
layouts: project(EIDOVERSE_CREATIVE_LAYOUTS),
};
}
// ---------------------------------------------------------------------------
// Deterministic seeded placement
// ---------------------------------------------------------------------------
/** FNV-1a: a short string seed to a 32-bit unsigned int. */
function hashSeed(text) {
let hash = 0x811c9dc5;
for (let index = 0; index < text.length; index += 1) {
hash ^= text.charCodeAt(index);
hash = Math.imul(hash, 0x01000193);
}
return hash >>> 0;
}
/** mulberry32: a small, fast, deterministic PRNG — replayable across installs. */
function mulberry32(seed) {
let state = seed >>> 0;
return function next() {
state = (state + 0x6d2b79f5) | 0;
let t = Math.imul(state ^ (state >>> 15), 1 | state);
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
function requireAnchor(anchor) {
if (!Array.isArray(anchor) || anchor.length !== 3 || anchor.some((value) => !Number.isFinite(value))) {
throw new RangeError('anchor must be [x, y, z] finite numbers.');
}
}
/**
* Generate deterministic prop placements for a named layout.
*
* @param {object} options
* @param {string} options.layoutId - one of `EIDOVERSE_CREATIVE_LAYOUTS`
* @param {number[]} options.anchor - [x, y, z] world-space origin
* @param {number} [options.propCount] - clamped to [1, 16]
* @param {string} [options.seed] - any string; same seed replays the same placement.
* The geometric layouts (`radial-ring`, `grid-plot`, `arc-row`) are fully
* determined by anchor/count/facing and so are seed-invariant by design;
* only `grove-cluster` consumes the seeded RNG for its jitter. The
* reproducibility guarantee — same inputs, same output — holds for every
* layout either way.
* @param {number} [options.facing] - radians, the layout's orientation
* @returns {Array<{ pos: number[], yaw: number }>}
*/
export function generateDistrictTemplatePlacement({ layoutId, anchor, propCount = 6, seed = layoutId, facing = 0 }) {
const generator = LAYOUT_GENERATORS[layoutId];
if (!generator) throw new RangeError(`Unknown layout "${layoutId}". Expected one of ${EIDOVERSE_CREATIVE_LAYOUTS.map((item) => item.id).join(', ')}.`);
requireAnchor(anchor);
const count = clampInt(propCount, 1, 16);
const rng = mulberry32(hashSeed(String(seed ?? layoutId)));
return generator(anchor, count, rng, Number.isFinite(facing) ? facing : 0)
.map((prop) => ({ pos: prop.pos.map((value) => Number(value.toFixed(3))), yaw: Number(prop.yaw.toFixed(4)) }));
}
/**
* Turn a generated placement into `eidoverse.augment` `spawn` operations,
* ready to submit as-is. Asset validity (a real library path) is checked by
* `eidoverseWorld.js`'s augment implementation when the operations land —
* this helper only owns the placement math.
*/
export function buildDistrictTemplateAugmentOperations({ layoutId, anchor, propCount, seed, facing, assetPath, idPrefix }) {
if (typeof assetPath !== 'string' || !assetPath.trim()) throw new RangeError('assetPath must be a non-empty Eidoverse library or store path.');
const prefix = typeof idPrefix === 'string' && idPrefix.trim() ? idPrefix.trim() : layoutId;
const placement = generateDistrictTemplatePlacement({ layoutId, anchor, propCount, seed, facing });
return placement.map((prop, index) => ({
verb: 'spawn',
args: { id: `${prefix}-${index}`, lib: assetPath, pos: prop.pos, yaw: prop.yaw, scale: 1 },
}));
}
/**
* Compose a `district-template` foundation input, shaped for
* `eidoverseFoundationInputSchema` (`eidoverseFoundations.js`) and ready to
* pass to `recordEidoverseFoundation` — it always lands on the local
* `vernacular` layer by construction, matching every other authored
* foundation. The generative placement (layout, anchor, seed, resulting
* positions) is the promotable substance and goes in `body`; the material
* and motif choice are cosmetics and go in `style`, exactly as
* `styleLeakFindings` expects.
*
* The placement is emitted BESIDE the `{ layoutId, anchor, propCount, seed,
* facing }` it was generated from, which is what makes the draft promotable:
* the promote gate re-derives the placement from those declarations and refuses
* one that no longer reproduces (`lib/eidoverseFoundationSandbox.js`, #7625).
* There is no `contributionId` to pass — the gate replays this body, so the
* binding label is derived from it.
*/
export function buildDistrictTemplateFoundationDraft({
id, title, summary, layoutId, materialId, motifId, anchor, propCount = 6, seed, facing = 0, disclosure,
}) {
const material = requireCatalogEntry(EIDOVERSE_CREATIVE_MATERIALS, materialId, 'material');
const motif = requireCatalogEntry(EIDOVERSE_CREATIVE_MOTIFS, motifId, 'motif');
const resolvedSeed = seed ?? `${id}-${layoutId}`;
const placement = generateDistrictTemplatePlacement({ layoutId, anchor, propCount, seed: resolvedSeed, facing });
return {
id,
kind: 'district-template',
title,
summary,
body: {
layoutId,
anchor: anchor.map((value) => Number(value)),
propCount: clampInt(propCount, 1, 16),
seed: resolvedSeed,
facing,
placement,
},
style: { materialId: material.id, motifId: motif.id, palette: material.colorHex, motif: motif.id },
disclosure: disclosure ?? {},
};
}
// ---------------------------------------------------------------------------
// Tool input schemas (#7627)
// ---------------------------------------------------------------------------
// `services/cosToolRegistry.js` wires the two generative builders above as
// `eidoverse.place-layout` (live-scene augment operations) and
// `eidoverse.draft-foundation` (an `eidoverse.record`-ready district-template
// input) — the "two ways to use a chosen layout" the module header always
// described, now with a caller on both. Declared here, beside the functions
// they validate for, rather than in `services/cosToolRegistry.js`.
const eidoverseCreativeLayoutIdSchema = z.enum(EIDOVERSE_CREATIVE_LAYOUTS.map((layout) => layout.id));
const eidoverseCreativeMaterialIdSchema = z.enum(EIDOVERSE_CREATIVE_MATERIALS.map((material) => material.id));
const eidoverseCreativeMotifIdSchema = z.enum(EIDOVERSE_CREATIVE_MOTIFS.map((motif) => motif.id));
// `.length(3)`, not `z.tuple`, matching `eidoverseValidation.js`'s own vector
// schema: a fixed-length array survives the `zodToOpenApiSchema` → JSON Schema
// → `z.fromJSONSchema` round trip `validateArguments()` runs at dispatch.
const eidoverseAnchorSchema = z.array(z.number().finite()).length(3);
const eidoverseSeedSchema = z.string().trim().min(1).max(120).optional();
const eidoverseFacingSchema = z.number().finite().optional();
const eidoversePropCountSchema = z.number().int().min(1).max(16).optional();
/**
* `eidoverse.place-layout`: compute a named layout's placement and return
* augment-ready `eidoverse.augment` `spawn` operations. Read-only — it
* computes, it never writes to the world; the operations still need a
* separate `eidoverse.augment` call to land.
*/
export const eidoversePlaceLayoutInputSchema = z.object({
layoutId: eidoverseCreativeLayoutIdSchema,
anchor: eidoverseAnchorSchema,
propCount: eidoversePropCountSchema,
seed: eidoverseSeedSchema,
facing: eidoverseFacingSchema,
assetPath: z.string().trim().min(1).max(512),
idPrefix: z.string().trim().min(1).max(64).optional(),
}).strict();
/**
* `eidoverse.draft-foundation`: compose a layout, material, and motif choice
* into an `eidoverseFoundationInputSchema`-ready `district-template` input,
* ready to pass straight to `eidoverse.record`. The `id`/`title`/`summary`/
* `disclosure` fields are lifted from `eidoverseFoundationInputSchema` itself
* rather than re-declared, so a limit change there cannot silently diverge
* from what this schema accepts. There is no `contributionId`: the promote
* gate derives the binding label from the drafted body (#7625), so a drafter
* has nothing to name.
*/
export const eidoverseDraftFoundationInputSchema = z.object({
id: eidoverseFoundationInputSchema.shape.id,
title: eidoverseFoundationInputSchema.shape.title,
summary: eidoverseFoundationInputSchema.shape.summary,
disclosure: eidoverseFoundationInputSchema.shape.disclosure,
layoutId: eidoverseCreativeLayoutIdSchema,
materialId: eidoverseCreativeMaterialIdSchema,
motifId: eidoverseCreativeMotifIdSchema,
anchor: eidoverseAnchorSchema,
propCount: eidoversePropCountSchema,
seed: eidoverseSeedSchema,
facing: eidoverseFacingSchema,
}).strict();