Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Degradation contracts.
//
// A fallback is not automatically an improvement. Serving a remembered value is
// the right answer for a price chip and the wrong answer for a question whose
// whole purpose is to be current: this repo shipped four of those in one week.
// A payment retry re-signed the blockhash the facilitator had just refused. A
// token security endpoint assembled a clean bill of health out of remembered
// on-chain state at the exact moment the chain was unreadable. An access gate
// answered from a cached verdict. An alert feed went quiet in a way that looked
// like a calm market.
//
// Every one of those passed a "does it have a fallback" review. What none of
// them had was a stated answer to a different question: when this upstream is
// down, what is this endpoint ALLOWED to say? That is the contract, and this
// module is the vocabulary plus the harness that proves it by actually breaking
// the upstream and looking at the response.
/**
* The contracts an endpoint can declare.
*
* MAY_SERVE_STALE
* A remembered value is a better answer than an error, and the response says
* so (a stale marker, an as_of stamp, or a header). Prices, feeds, boards.
*
* MUST_REFUSE
* There is no honest answer without a live read, so the endpoint must return a
* typed error rather than invent one. The failure mode this prevents is not a
* crash: it is a confident, wrong, cacheable 200.
*
* MUST_NOT_SERVE_STALE
* Stronger than MUST_REFUSE. The endpoint may answer 200 from live data, but
* a remembered value must never reach the caller, because acting on a stale
* answer costs money or grants access. Payment retries, security verdicts,
* authorization gates.
*/
export const CONTRACT = {
MAY_SERVE_STALE: 'may-serve-stale',
MUST_REFUSE: 'must-refuse',
MUST_NOT_SERVE_STALE: 'must-not-serve-stale',
};
export const CONTRACT_VALUES = new Set(Object.values(CONTRACT));
/** Status codes that count as a typed refusal rather than a crash. */
const REFUSAL_STATUSES = new Set([424, 425, 429, 502, 503, 504]);
/**
* Markers that say "this body is remembered, not live". A contract that allows
* stale data requires one of these to be present, because degrading silently is
* how a stale answer gets mistaken for a current one.
*/
export function staleMarkers(body, headers = {}) {
const found = [];
if (body && typeof body === 'object') {
if (body.stale === true) found.push('body.stale');
if (body.as_of !== undefined && body.as_of !== null) found.push('body.as_of');
if (body.data && typeof body.data === 'object') {
if (body.data.stale === true) found.push('body.data.stale');
if (body.data.as_of !== undefined && body.data.as_of !== null) found.push('body.data.as_of');
}
}
for (const key of Object.keys(headers || {})) {
const k = key.toLowerCase();
if (k.includes('stale')) found.push(`header.${k}`);
}
return found;
}
/**
* Judge one observed response against a contract.
*
* Deliberately pure and transport-agnostic: the caller performs the fault
* injection however its endpoint needs, then hands the outcome here. That keeps
* the judgement identical whether the response came from an HTTP handler, an
* exported library function, or a worker.
*
* @param {string} contract one of CONTRACT
* @param {{ status?: number, body?: any, headers?: object, threw?: unknown }} observed
* @returns {{ ok: boolean, reason: string }}
*/
export function judge(contract, observed) {
const { status, body, headers = {}, threw } = observed;
if (threw !== undefined && threw !== null) {
// A rejection that carries a typed status is a refusal expressed as an
// exception, which the HTTP boundary turns into the same envelope.
const typed = Number(threw?.status ?? threw?.statusCode);
if (contract === CONTRACT.MAY_SERVE_STALE) {
return { ok: false, reason: `threw instead of serving a remembered value: ${threw?.message || threw}` };
}
if (Number.isFinite(typed) && REFUSAL_STATUSES.has(typed)) {
return { ok: true, reason: `refused with a typed ${typed}` };
}
if (threw?.code) return { ok: true, reason: `refused with code ${threw.code}` };
return { ok: false, reason: `threw an untyped error: ${threw?.message || threw}` };
}
const markers = staleMarkers(body, headers);
const is2xx = status === undefined || (status >= 200 && status < 300);
switch (contract) {
case CONTRACT.MAY_SERVE_STALE: {
if (!is2xx) {
// Refusing is allowed only when nothing was ever remembered; the
// caller distinguishes those two cases by warming the endpoint first.
return REFUSAL_STATUSES.has(status)
? { ok: true, reason: `refused with a typed ${status} (nothing remembered yet)` }
: { ok: false, reason: `answered ${status}, which is neither stale data nor a typed refusal` };
}
if (!markers.length) {
return {
ok: false,
reason: 'served a 200 during a total upstream outage without marking it stale, so a remembered value is indistinguishable from a live one',
};
}
return { ok: true, reason: `served remembered data, marked by ${markers.join(', ')}` };
}
case CONTRACT.MUST_REFUSE: {
if (is2xx) {
return {
ok: false,
reason: 'answered 2xx with every upstream down, which states as fact something it could not check',
};
}
return REFUSAL_STATUSES.has(status)
? { ok: true, reason: `refused with a typed ${status}` }
: { ok: false, reason: `answered ${status}, which is not a typed "try again" refusal` };
}
case CONTRACT.MUST_NOT_SERVE_STALE: {
if (is2xx && markers.length) {
return {
ok: false,
reason: `served remembered data (${markers.join(', ')}) on a path where acting on a stale answer costs money or grants access`,
};
}
if (is2xx) {
return {
ok: false,
reason: 'answered 2xx with every upstream down, so the answer came from somewhere other than a live read',
};
}
return REFUSAL_STATUSES.has(status)
? { ok: true, reason: `refused with a typed ${status} rather than reusing a remembered answer` }
: { ok: false, reason: `answered ${status}, which is not a typed refusal` };
}
default:
return { ok: false, reason: `unknown contract "${contract}"` };
}
}
/**
* A fetch replacement that fails the way a dead upstream fails, for injecting a
* total outage. `mode` picks the shape of the failure, because a refused
* connection and a socket that accepts and never answers are different bugs and
* have caught different ones here.
*
* @param {'network' | 'timeout' | 'status'} mode
* @param {{ status?: number }} [opts]
*/
export function failingFetch(mode = 'network', { status = 503 } = {}) {
if (mode === 'status') {
return async () =>
new Response(JSON.stringify({ error: 'upstream is down' }), {
status,
headers: { 'content-type': 'application/json' },
});
}
if (mode === 'timeout') {
return async (_url, init) =>
new Promise((_resolve, reject) => {
const signal = init?.signal;
const fail = () => reject(Object.assign(new Error('The operation was aborted'), { name: 'AbortError' }));
if (!signal) return; // no deadline: hangs, which is itself the finding
if (signal.aborted) return fail();
signal.addEventListener('abort', fail, { once: true });
});
}
return async () => {
const err = new TypeError('fetch failed');
err.cause = { code: 'ECONNREFUSED' };
throw err;
};
}