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

20.3 KB
Raw Blame
/**
 * Derive the agent-free resilience-assay sandbox for a foundation FROM ITS OWN
 * BODY (#7625, epic #7453).
 *
 * The promote gate's whole promise is "a contribution still works without its
 * creator narrating it". #7460 built the harness and #7455 made the server run
 * it rather than accept a caller's verdict — but the harness was pointed at
 * whatever module the author NAMED (`contributionId`, free text on the
 * authoring surface), never at the foundation being promoted. Any local
 * foundation could name a shipped demo fixture and inherit its pass; peers then
 * inherited on evidence that described the fixture, not the body inside the
 * envelope. This module closes that: the sandbox is derived from `body`, so
 * "what was evaluated" and "what gets promoted" are the same object by
 * construction rather than by an author-supplied string.
 *
 * **This adds no arbitrary-code-execution surface.** Every executable part is
 * still code PortOS ships: a `controller` foundation names a SHIPPED controller
 * definition and supplies only declarative config; the other three kinds are
 * replayed by the interpreters below, which are ordinary PortOS code. What
 * varies per install is the declarative input the install actually authored —
 * which is exactly what the assay needed to be replaying all along.
 *
 * One derivation per declared kind:
 *
 *   - `controller` — `body.controller.definitionId` names a shipped definition
 *     and `body.controller.config` is parsed through that definition's own
 *     `configSchema`. THIS INSTALL'S config is what gets replayed, not
 *     upstream's `exampleConfig`; a broken local config now fails the gate
 *     instead of promoting on evidence about a config nobody runs.
 *   - `district-template` — the declared placement has to REPRODUCE from its
 *     own `{ layoutId, anchor, propCount, seed, facing }` through
 *     `generateDistrictTemplatePlacement()`, and the body is handed to the
 *     harness as the projection source, because a template's consequence is
 *     its projection plan.
 *   - `schema` / `affordance` — replayed through the declarative interpreter
 *     below: a clean world state is built from the declared field types, and
 *     every declared affordance is resolved against it each tick. A declaration
 *     that cannot be interpreted without its author is not promotable, which is
 *     the correct answer rather than a gap.
 *
 * `contributionId` survives only as a DERIVED label (`derivedContributionId()`)
 * so `assayEvidenceRefusal()`'s binding check in `eidoverseFoundations.js` —
 * "the evidence is about this foundation" — keeps working unchanged, and so a
 * receiving peer can re-derive it from the envelope's own `kind`/`body` and
 * catch an envelope whose evidence was minted against something else.
 *
 * Pure: no I/O, no clock, no provider calls. `foundationSandbox()` is async
 * ONLY because resolving a shipped controller definition is; the resolver is
 * injected so this module never imports the service layer.
 */

import { canonicalStringify, isPlainObject } from './objects.js';
import { generateDistrictTemplatePlacement } from './eidoverseCreativeToolkit.js';
// Declared beside the schemas that carry the label rather than here, so this
// module can keep reaching the creative toolkit without closing an ESM cycle
// back through it — see `derivedContributionId`'s own note.
import { controllerDefinitionIdFromBody, derivedContributionId } from './eidoverseFoundations.js';

const refuse = (refusal) => ({ contribution: null, refusal });
const accept = (contribution) => ({ contribution, refusal: null });

/**
 * The declared field-type vocabulary a `schema` foundation may use, and the
 * interpreter that gives each one a clean starting value, a per-tick successor,
 * and a conformance check.
 *
 * `advance` derives the next value from the TICK ORDINAL rather than from a
 * clock or a random source, which is what keeps a replay deterministic and
 * lets the harness's own re-invocation of `createSandbox()` per scenario mean
 * something. Every sample is JSON-portable, so the harness's built-in
 * serializability check is a real check and not a formality.
 */
export const EIDOVERSE_DECLARED_FIELD_TYPES = Object.freeze({
  boolean: { sample: () => false, advance: (_prev, tick) => tick % 2 === 0, valid: (value) => typeof value === 'boolean' },
  id: { sample: () => 'declared-0', advance: (_prev, tick) => `declared-${tick}`, valid: (value) => typeof value === 'string' && value.length > 0 },
  integer: { sample: () => 0, advance: (prev) => prev + 1, valid: (value) => Number.isInteger(value) },
  list: { sample: () => [], advance: (prev, tick) => [...prev, tick], valid: (value) => Array.isArray(value) },
  map: { sample: () => ({}), advance: (prev, tick) => ({ ...prev, [`t${tick}`]: tick }), valid: isPlainObject },
  number: { sample: () => 0, advance: (prev) => prev + 0.5, valid: (value) => typeof value === 'number' && Number.isFinite(value) },
  string: { sample: () => 'declared', advance: (_prev, tick) => `tick-${tick}`, valid: (value) => typeof value === 'string' },
  timestamp: {
    sample: () => new Date(0).toISOString(),
    advance: (_prev, tick) => new Date(tick * 1000).toISOString(),
    valid: (value) => typeof value === 'string' && !Number.isNaN(Date.parse(value)),
  },
});

/** The declared field types, sorted, for a reader-facing refusal. */
const DECLARED_TYPE_NAMES = Object.freeze(Object.keys(EIDOVERSE_DECLARED_FIELD_TYPES).sort());

// ---------------------------------------------------------------------------
// controller
// ---------------------------------------------------------------------------

/**
 * Replay a `controller` foundation through the shipped definition it names,
 * against the config THIS INSTALL authored.
 *
 * `step` and `applyDisturbance` are shaped exactly as
 * `controllerAssayContributions()` shapes them for the CLI's shipped-controller
 * sweep, so the assay is replaying the real tick path. The difference — the
 * whole point of #7625 — is the config: upstream's `exampleConfig` proves
 * upstream's example survives, which says nothing about an install whose own
 * config is broken.
 */
function controllerSandbox({ body, definition, definitionId, contributionId }) {
  if (!definitionId) {
    return refuse('a `controller` foundation must declare `body.controller.definitionId` naming a shipped controller definition — the assay replays the controller this install actually configured, not one it names in prose');
  }
  if (!definition) {
    return refuse(`no shipped controller definition is registered under "${definitionId}" — this install cannot replay the foundation, so it cannot promote it`);
  }
  const config = definition.configSchema.safeParse(body.controller.config ?? {});
  if (!config.success) {
    const detail = config.error.issues.slice(0, 8).map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ');
    return refuse(`this foundation's own controller config does not satisfy "${definitionId}"'s schema: ${detail}`);
  }

  return accept({
    id: contributionId,
    description: definition.summary,
    createSandbox() {
      // Re-parsed per sandbox rather than closing over one parsed object: the
      // harness re-invokes `createSandbox()` for every scenario precisely so no
      // state survives between them, and a shared config object would be the
      // one thing that did.
      const scenarioConfig = definition.configSchema.parse(body.controller.config ?? {});
      return {
        worldState: definition.createState(scenarioConfig),
        controller: {
          // `outcome?.state === undefined` mirrors `runControllerStep()`'s own
          // rule, and has to: a step that returns nothing (or returns effects
          // with no `state`) is asserting "this tick changed no state", which
          // is ordinary for a controller that acts every Nth tick. Reading
          // `.state` off the result directly would throw on the live contract
          // and fail the promote gate for a controller that runs correctly —
          // an assay verdict about something other than the real tick path,
          // which is the very thing this module exists to stop.
          step: (worldState, tick) => {
            const outcome = definition.step(worldState, { tick, config: scenarioConfig });
            return outcome?.state === undefined ? worldState : outcome.state;
          },
          // Every disturbance in the suite is an ENVIRONMENT event; a
          // controller that keeps its durable state in `state` survives all
          // three, and the round-trip proves it holds no in-process handle.
          applyDisturbance: (worldState) => JSON.parse(JSON.stringify(worldState)),
        },
        projectionSource: {},
      };
    },
    invariants: definition.invariants ?? [],
  });
}

// ---------------------------------------------------------------------------
// district-template
// ---------------------------------------------------------------------------

const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
const isAnchor = (value) => Array.isArray(value) && value.length === 3 && value.every(isFiniteNumber);

/**
 * Replay a `district-template` foundation as its own placement.
 *
 * A template's consequence IS its geometry, and the one thing that makes that
 * geometry author-free is that it re-derives from the declarations beside it.
 * So the gate is: `generateDistrictTemplatePlacement()` run over the body's own
 * `{ layoutId, anchor, propCount, seed, facing }` must reproduce
 * `body.placement` exactly. A template carrying hand-edited coordinates its own
 * declarations no longer produce is a template only its author can rebuild.
 *
 * The body is handed to the harness as `projectionSource`, so the assay's
 * "load projections in a clean sandbox" leg runs `buildProjectionPlan()`
 * against the template rather than against an empty object.
 */
function districtTemplateSandbox({ body, contributionId }) {
  const { layoutId, anchor, propCount, seed, facing, placement } = body;
  if (typeof layoutId !== 'string' || !layoutId.trim()) return refuse('a `district-template` foundation must declare `body.layoutId` — a placement that names no generator cannot be re-derived without its author');
  if (!isAnchor(anchor)) return refuse('a `district-template` foundation must declare `body.anchor` as three finite numbers');
  if (!Array.isArray(placement) || placement.length === 0) return refuse('a `district-template` foundation must declare `body.placement` — the geometry the template produces is the thing being promoted');

  const declared = { layoutId: layoutId.trim(), anchor, propCount, seed, facing };
  let regenerated;
  try {
    regenerated = generateDistrictTemplatePlacement(declared);
  } catch (error) {
    return refuse(`this template's placement cannot be re-derived from its own declarations: ${error.message}`);
  }
  if (canonicalStringify(regenerated) !== canonicalStringify(placement)) {
    return refuse('`body.placement` does not reproduce from this template\'s own layout, anchor, count, seed and facing — a placement only its author can rebuild is not promotable');
  }

  return accept({
    id: contributionId,
    description: `Declared ${declared.layoutId} district template with ${placement.length} props.`,
    createSandbox() {
      return {
        // `scratch` is deliberately NOT part of the template's declarations —
        // it is what the `missing-optional-deps` disturbance takes away, so
        // "the template does not depend on anything it did not declare" is
        // proven rather than assumed.
        worldState: { layoutId: declared.layoutId, anchor: [...anchor], props: instantiateProps(placement), tick: null, scratch: { hint: declared.layoutId } },
        controller: {
          step(worldState, tick) {
            return { ...worldState, props: instantiateProps(generateDistrictTemplatePlacement(declared)), tick };
          },
          applyDisturbance(worldState, disturbance) {
            if (disturbance === 'restart-world-host') return JSON.parse(JSON.stringify(worldState));
            if (disturbance === 'missing-optional-deps') {
              const { scratch: _gone, ...durable } = worldState;
              return durable;
            }
            return worldState;
          },
        },
        projectionSource: body,
      };
    },
    invariants: [
      function propsMatchTheDeclaredPlacement(worldState) {
        const expected = canonicalStringify(instantiateProps(placement));
        if (canonicalStringify(worldState.props) !== expected) {
          return { ok: false, reason: 'the replayed props drifted from the declared placement' };
        }
        return true;
      },
    ],
  });
}

/** Declared placement as world props — ids derived from the ordinal, so the
 * instantiation is as reproducible as the placement it comes from. */
function instantiateProps(placement) {
  return placement.map((prop, index) => ({
    id: `prop-${index}`,
    pos: Array.isArray(prop?.pos) ? prop.pos.map(Number) : null,
    yaw: isFiniteNumber(prop?.yaw) ? prop.yaw : null,
  }));
}

// ---------------------------------------------------------------------------
// schema / affordance
// ---------------------------------------------------------------------------

/**
 * The declarative interpreter behind the `schema` and `affordance` kinds.
 *
 * `body.schema` is `{ fieldName: declaredType }`; `body.affordance` is
 * `{ verb: { summary?, reads?: [...], writes?: [...] } }` naming DECLARED
 * fields. That structure is what makes a declaration interpretable at all: an
 * affordance recorded as free prose ("reads the pulse count") can only be
 * resolved by the person who wrote it, which is precisely the dependency the
 * agent-free assay exists to refuse. An `affordance` foundation therefore has
 * to carry the schema its verbs resolve against.
 *
 * The replay builds a clean world state from the declared types, resolves every
 * affordance against it each tick, and lets the harness's per-tick invariant
 * pass assert that every declared field still holds a value of its declared
 * type and that the whole state stays JSON-portable.
 */
function declarativeSandbox({ kind, body, contributionId }) {
  const schema = body.schema;
  if (!isPlainObject(schema) || Object.keys(schema).length === 0) {
    return refuse(`a \`${kind}\` foundation must declare \`body.schema\` as a non-empty { field: type } map — a state shape nobody can instantiate cannot be replayed without its author`);
  }
  for (const [field, declaredType] of Object.entries(schema)) {
    if (typeof declaredType !== 'string' || !Object.hasOwn(EIDOVERSE_DECLARED_FIELD_TYPES, declaredType)) {
      return refuse(`\`body.schema.${field}\` declares "${declaredType}", which is not an interpretable field type (expected one of ${DECLARED_TYPE_NAMES.join(', ')})`);
    }
  }

  const affordances = body.affordance;
  if (kind === 'affordance' && (!isPlainObject(affordances) || Object.keys(affordances).length === 0)) {
    return refuse('an `affordance` foundation must declare `body.affordance` as a non-empty { verb: … } map');
  }
  const resolved = [];
  for (const [verb, declaration] of Object.entries(isPlainObject(affordances) ? affordances : {})) {
    if (!isPlainObject(declaration)) {
      return refuse(`\`body.affordance.${verb}\` is prose, not a resolvable declaration — declare it as { summary, reads: [...], writes: [...] } naming fields from \`body.schema\``);
    }
    const reads = declaration.reads ?? [];
    const writes = declaration.writes ?? [];
    if (!Array.isArray(reads) || !Array.isArray(writes)) return refuse(`\`body.affordance.${verb}\` must declare \`reads\` and \`writes\` as arrays of field names`);
    if (reads.length === 0 && writes.length === 0) return refuse(`\`body.affordance.${verb}\` touches no declared field — an affordance with no readable consequence cannot be replayed`);
    for (const field of [...reads, ...writes]) {
      if (!Object.hasOwn(schema, field)) return refuse(`\`body.affordance.${verb}\` names "${field}", which \`body.schema\` does not declare`);
    }
    resolved.push({ verb, reads, writes });
  }
  resolved.sort((a, b) => a.verb.localeCompare(b.verb));

  return accept({
    id: contributionId,
    description: `Declared ${Object.keys(schema).length}-field ${kind} with ${resolved.length} resolvable affordance(s).`,
    createSandbox() {
      const fields = Object.fromEntries(Object.entries(schema).map(([field, type]) => [field, EIDOVERSE_DECLARED_FIELD_TYPES[type].sample()]));
      return {
        // `scratch` is undeclared state on purpose — see the district-template
        // sandbox: `missing-optional-deps` removes it, and nothing may miss it.
        worldState: { fields, applied: [], scratch: { kind } },
        controller: {
          step(worldState, tick) {
            const fields = { ...worldState.fields };
            const applied = [];
            for (const { verb, reads, writes } of resolved) {
              for (const field of reads) {
                if (!Object.hasOwn(fields, field)) throw new Error(`affordance "${verb}" reads "${field}", which is no longer present in the world state`);
              }
              for (const field of writes) fields[field] = EIDOVERSE_DECLARED_FIELD_TYPES[schema[field]].advance(fields[field], tick);
              applied.push(verb);
            }
            return { ...worldState, fields, applied, tick };
          },
          applyDisturbance(worldState, disturbance) {
            if (disturbance === 'restart-world-host') return JSON.parse(JSON.stringify(worldState));
            if (disturbance === 'missing-optional-deps') {
              const { scratch: _gone, ...durable } = worldState;
              return durable;
            }
            return worldState;
          },
        },
        projectionSource: {},
      };
    },
    invariants: [
      function declaredFieldsKeepTheirDeclaredTypes(worldState) {
        for (const [field, type] of Object.entries(schema)) {
          if (!Object.hasOwn(worldState.fields || {}, field)) return { ok: false, reason: `declared field "${field}" went missing` };
          if (!EIDOVERSE_DECLARED_FIELD_TYPES[type].valid(worldState.fields[field])) {
            return { ok: false, reason: `declared field "${field}" no longer holds a ${type}` };
          }
        }
        return true;
      },
      function everyDeclaredAffordanceResolved(worldState) {
        if (!Array.isArray(worldState.applied) || worldState.applied.length !== resolved.length) {
          return { ok: false, reason: `expected ${resolved.length} affordance(s) to resolve, saw ${worldState.applied?.length ?? 'none'}` };
        }
        return true;
      },
    ],
  });
}

// ---------------------------------------------------------------------------
// Entry point
// ---------------------------------------------------------------------------

/**
 * The resilience-assay contribution for one foundation, derived from its own
 * body — or a refusal reason when the body cannot be replayed at all.
 *
 * Async only for the `controller` kind's registry read, which is injected:
 * `findControllerDefinition(id)` resolves a SHIPPED definition by id (the
 * ledger and the migration both pass
 * `eidoverseControllerRegistry.js#findControllerDefinitionById`). Nothing here
 * imports the service layer, and no caller-supplied path is ever resolved.
 *
 * @param {{ kind: string, id: string, body: object }} record
 * @param {{ findControllerDefinition: (id: string) => Promise<object|null> }} resolvers
 * @returns {Promise<{ contribution: object|null, refusal: string|null }>}
 */
export async function foundationSandbox({ kind, id, body }, { findControllerDefinition } = {}) {
  if (!isPlainObject(body)) return refuse('this foundation has no body to replay');
  const contributionId = derivedContributionId({ kind, id, body });

  if (kind === 'controller') {
    const definitionId = controllerDefinitionIdFromBody(body);
    const definition = definitionId && findControllerDefinition ? await findControllerDefinition(definitionId) : null;
    return controllerSandbox({ body, definition, definitionId, contributionId });
  }
  if (kind === 'district-template') return districtTemplateSandbox({ body, contributionId });
  if (kind === 'schema' || kind === 'affordance') return declarativeSandbox({ kind, body, contributionId });
  return refuse(`"${kind}" has no sandbox derivation, so nothing can replay it without its author`);
}