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
// The overlay root: how an approved post reaches production without a deploy.
//
// The engine reads everything from files under one root (the queue, the review
// records, the media), and in production that root is the Cloud Run image, so a
// post approved today could not go out until someone shipped a new image. This
// module removes that ceiling without touching a single editorial rule.
//
// `npm run x:bundle -- publish <id>` packs an approved item, its full review
// record, and every file it needs into a bundle, uploads the files to object
// storage under content-addressed keys, and lists the bundle in one index that
// is signed with X_CONTENT_BUNDLE_SECRET. At the start of a tick production
// verifies that signature, then materializes a directory that mirrors the repo
// layout: the image's own data/ and public/ reached through symlinks, the
// bundle files written on top after their bytes hash to what the index
// recorded. The unchanged engine then runs with `root` pointing at it. The
// review record is still bound to the content hash, still expires, and the
// media limits, link checks, and probes still run, because the engine cannot
// tell an overlay from an image.
//
// Nothing here can stop a tick. Any failure (no secret, no storage, a bad
// signature, a file that does not match its hash) falls back to the image root,
// which is exactly what production did before the overlay existed.
import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { isAbsolute, join, resolve, sep } from 'node:path';
import { MEDIA_ROOTS, mediaType } from './media.js';
import { QUEUE_PATH, loadArticle, loadQueue, validateItem } from './queue.js';
import { loadReview, reviewPath } from './review.js';
export const INDEX_KEY = 'x-content/bundles/index.json';
export const INDEX_VERSION = 1;
export const ARTICLE_ROOT = 'data/x-content/articles/';
export const REVIEW_ROOT = 'data/x-content/reviews/';
export const proofPath = (id) => `data/x-content/proofs/${id}.json`;
export const fileKey = (id, sha256) => `x-content/bundles/${id}/${sha256}`;
export const DEFAULT_OVERLAY_DIR = join(tmpdir(), 'x-content-overlay');
// A short secret is a guessable one, and this secret is the only thing standing
// between write access to the bucket and a post on @trythreews.
export const MIN_SECRET_LENGTH = 32;
// Marks a directory as one this module built, so materialize never prunes a
// directory that holds someone's files.
const MARKER = '.x-content-overlay';
// Top-level entries of the image that the overlay exposes. data/ and public/
// are what the engine reads; the rest is what a command probe or a textFrom
// check may look for under root.
const EXPOSED = ['data', 'public', 'scripts', 'docs', 'package.json'];
const SLUG = /^[a-z0-9][a-z0-9-]{1,80}$/;
const SHA256 = /^[0-9a-f]{64}$/;
export class OverlayError extends Error {
constructor(code, message) {
super(message);
this.name = 'OverlayError';
this.code = code;
}
}
const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
// ── Canonical JSON and the signature ────────────────────────────────────────
// Keys sorted at every depth, so the bytes that are signed do not depend on the
// order a writer happened to build an object in, or on a store that reorders
// keys. Values follow JSON.stringify: undefined members are dropped, undefined
// array entries become null.
export function canonical(value) {
if (value && typeof value.toJSON === 'function') return canonical(value.toJSON());
if (Array.isArray(value)) return `[${value.map((row) => canonical(row === undefined ? null : row)).join(',')}]`;
if (value && typeof value === 'object') {
const keys = Object.keys(value).filter((key) => value[key] !== undefined && typeof value[key] !== 'function').sort();
return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
}
return JSON.stringify(value) ?? 'null';
}
export const bundleHash = ({ item, review, files }) => sha256(canonical({ item, review, files }));
function secretFrom(env) {
const secret = String(env?.X_CONTENT_BUNDLE_SECRET ?? '').trim();
if (!secret) throw new OverlayError('unconfigured', 'X_CONTENT_BUNDLE_SECRET is not set');
if (secret.length < MIN_SECRET_LENGTH) throw new OverlayError('unconfigured', `X_CONTENT_BUNDLE_SECRET is shorter than ${MIN_SECRET_LENGTH} characters; generate one with \`openssl rand -hex 32\``);
return secret;
}
export function signIndex({ version, updatedAt, bundles }, env = process.env) {
return createHmac('sha256', secretFrom(env)).update(canonical({ version, updatedAt, bundles })).digest('hex');
}
export function verifyIndex(index, env = process.env) {
const expected = Buffer.from(signIndex(index, env), 'hex');
const given = SHA256.test(String(index?.signature || '')) ? Buffer.from(index.signature, 'hex') : null;
if (!given || given.length !== expected.length || !timingSafeEqual(given, expected)) {
throw new OverlayError('bad_signature', 'the bundle index signature does not verify; it was not written with this X_CONTENT_BUNDLE_SECRET, or it was changed after it was signed');
}
return index;
}
// ── Paths ───────────────────────────────────────────────────────────────────
// Why a path may not be written into the overlay, or null when it may. The
// queue and the review records are the overlay's own: a bundle file is never
// allowed to stand in for either.
export function bundlePathProblem(path) {
if (typeof path !== 'string' || !path) return 'is empty';
if (path.includes('..')) return 'contains ..';
if (isAbsolute(path) || path.startsWith('/') || /^[a-zA-Z]:/.test(path)) return 'is absolute';
if (path.includes('\\') || path.includes('\0')) return 'contains a backslash or a null byte';
if (path.split('/').some((part) => !part || part === '.')) return 'has an empty or dot segment';
if (![...MEDIA_ROOTS, ARTICLE_ROOT].some((prefix) => path.startsWith(prefix))) return `is outside ${[...MEDIA_ROOTS, ARTICLE_ROOT].join(', ')}`;
if (path === QUEUE_PATH || path.startsWith(REVIEW_ROOT)) return 'is reserved for the queue and the review records';
return null;
}
function checkBundle(bundle) {
const id = String(bundle?.id || '');
if (!SLUG.test(id)) throw new OverlayError('bad_bundle', `bundle id ${JSON.stringify(bundle?.id)} is not a lowercase slug`);
if (bundle.item?.id !== id) throw new OverlayError('bad_bundle', `${id}: the bundled item is ${JSON.stringify(bundle.item?.id)}`);
if (!bundle.review || bundle.review.id !== id) throw new OverlayError('bad_bundle', `${id}: the bundled review record is for ${JSON.stringify(bundle.review?.id)}`);
if (!Array.isArray(bundle.files)) throw new OverlayError('bad_bundle', `${id}: files is not a list`);
for (const file of bundle.files) {
const problem = bundlePathProblem(file?.path);
if (problem) throw new OverlayError('bad_path', `${id}: file path ${JSON.stringify(file?.path)} ${problem}`);
if (!SHA256.test(String(file.sha256 || ''))) throw new OverlayError('bad_bundle', `${id}: ${file.path} has no sha256`);
if (!Number.isInteger(file.bytes) || file.bytes < 0) throw new OverlayError('bad_bundle', `${id}: ${file.path} has no byte count`);
}
if (bundle.hash !== bundleHash(bundle)) throw new OverlayError('bad_bundle', `${id}: the bundle hash does not cover its item, review record, and files`);
return bundle;
}
// ── Storage ─────────────────────────────────────────────────────────────────
// The real store. Loaded on first use, so the cron module stays importable and
// cheap while the overlay is switched off.
// Where a key really lives in the bucket. The bucket is served on a public
// domain, and a bundle holds the copy of posts that have not gone out yet, some
// of them embargoed, so the bundles sit under a folder named from the secret:
// the index cannot be fetched by anyone who could not also have signed it.
export const BUNDLE_ROOT = 'x-content/bundles/';
export function sealedKey(key, env = process.env) {
if (!key.startsWith(BUNDLE_ROOT)) throw new OverlayError('bad_path', `${key} is not a bundle key`);
const folder = createHmac('sha256', secretFrom(env)).update('x-content bundle location').digest('hex').slice(0, 40);
return `${BUNDLE_ROOT}${folder}/${key.slice(BUNDLE_ROOT.length)}`;
}
export function r2Storage(env = process.env) {
const r2 = () => import('../r2.js');
return {
label: 'object storage',
async put(key, buffer, contentType) {
const { putObject } = await r2();
await putObject({ key: sealedKey(key, env), body: buffer, contentType });
},
async get(key) {
const { getObjectBuffer } = await r2();
try {
return await getObjectBuffer(sealedKey(key, env));
} catch (err) {
if (err?.name === 'NoSuchKey' || err?.$metadata?.httpStatusCode === 404) return null;
throw err;
}
},
async has(key) {
const { headObject } = await r2();
return Boolean(await headObject(sealedKey(key, env)));
},
async remove(key) {
const { deleteObject } = await r2();
await deleteObject(sealedKey(key, env));
},
};
}
// The same store on Google Cloud Storage, for when Cloudflare R2 is not
// available. Selected by X_CONTENT_BUNDLE_BUCKET; the Cloud Run service account
// and the partner job authenticate with their own identity, so no key is stored.
const GCS_API = 'https://storage.googleapis.com';
export function gcsStorage(env = process.env) {
const bucket = String(env.X_CONTENT_BUNDLE_BUCKET || '').trim();
if (!bucket) throw new OverlayError('unconfigured', 'X_CONTENT_BUNDLE_BUCKET is not set');
const call = async (method, url, { body, contentType } = {}) => {
const { getGcpAccessToken } = await import('../gcp-auth.js');
const headers = { authorization: `Bearer ${await getGcpAccessToken()}` };
if (contentType) headers['content-type'] = contentType;
return fetch(url, { method, headers, body, signal: AbortSignal.timeout(60_000) });
};
const mediaUrl = (key) => `${GCS_API}/storage/v1/b/${bucket}/o/${encodeURIComponent(sealedKey(key, env))}`;
const failed = async (res, what) => new Error(`${what}: Google Cloud Storage answered ${res.status} ${(await res.text()).slice(0, 200)}`);
return {
label: 'Google Cloud Storage',
async put(key, buffer, contentType) {
const url = `${GCS_API}/upload/storage/v1/b/${bucket}/o?uploadType=media&name=${encodeURIComponent(sealedKey(key, env))}`;
const res = await call('POST', url, { body: buffer, contentType: contentType || 'application/octet-stream' });
if (!res.ok) throw await failed(res, `put ${key}`);
},
async get(key) {
const res = await call('GET', `${mediaUrl(key)}?alt=media`);
if (res.status === 404) return null;
if (!res.ok) throw await failed(res, `get ${key}`);
return Buffer.from(await res.arrayBuffer());
},
async has(key) {
const res = await call('GET', `${mediaUrl(key)}?fields=name`);
if (res.status === 404) return false;
if (!res.ok) throw await failed(res, `has ${key}`);
return true;
},
async remove(key) {
const res = await call('DELETE', mediaUrl(key));
if (!res.ok && res.status !== 404) throw await failed(res, `remove ${key}`);
},
};
}
// The store the overlay really uses: GCS when a bucket is named, R2 otherwise.
export function bundleStorage(env = process.env) {
return String(env.X_CONTENT_BUNDLE_BUCKET || '').trim() ? gcsStorage(env) : r2Storage(env);
}
// `has` is optional on a store: one that only has put, get, and remove answers
// by reading the object.
const stored = async (storage, key) => (storage.has ? storage.has(key) : (await storage.get(key)) !== null);
const contentTypeOf = (path) => mediaType(path)?.mime || (path.endsWith('.md') ? 'text/markdown; charset=utf-8' : path.endsWith('.json') ? 'application/json' : 'application/octet-stream');
// ── Building and publishing ─────────────────────────────────────────────────
// Every file the item needs at publish time: each post's media, and for an
// Article its body, cover, and inline images. An item with a scenario also
// carries its proof record.
function itemPaths(item, root) {
const paths = [];
for (const post of item.posts || []) for (const media of post.media || []) paths.push(media.path);
if (item.kind === 'article') {
paths.push(item.article.body, item.article.cover.path);
for (const image of loadArticle(root, item.article).images) paths.push(image.path);
}
if (existsSync(resolve(root, proofPath(item.id)))) paths.push(proofPath(item.id));
return [...new Set(paths)];
}
export function buildBundle(root, id, { now = Date.now() } = {}) {
const item = (loadQueue(root).items || []).find((row) => row.id === id);
if (!item) throw new Error(`${id} cannot be bundled: no queue item has that id`);
const reasons = [];
if (item.status !== 'approved') reasons.push(`status is ${item.status}; only an approved item is bundled`);
reasons.push(...validateItem(item, root));
if (!reasons.length) {
for (const path of itemPaths(item, root)) {
const problem = bundlePathProblem(path);
if (problem) reasons.push(`file path ${path} ${problem}`);
}
}
if (reasons.length) throw new Error(`${id} cannot be bundled: ${reasons.join('; ')}`);
const review = loadReview(root, id);
const files = itemPaths(item, root).map((path) => {
const bytes = readFileSync(resolve(root, path));
return { path, sha256: sha256(bytes), bytes: bytes.length };
});
return { id, item, review, files, bundledAt: new Date(now).toISOString(), hash: bundleHash({ item, review, files }) };
}
// Two bundles may share a file (one hero image on two posts), but never
// disagree about its bytes: each review record is bound to one exact file.
function fileConflicts(bundles) {
const seen = new Map();
const conflicts = [];
for (const bundle of bundles) {
for (const file of bundle.files) {
const prior = seen.get(file.path);
if (prior && prior.sha256 !== file.sha256) conflicts.push(`${file.path} differs between ${prior.id} and ${bundle.id}`);
else seen.set(file.path, { id: bundle.id, sha256: file.sha256 });
}
}
return conflicts;
}
async function writeIndex({ bundles, storage, env, now }) {
const index = { version: INDEX_VERSION, updatedAt: new Date(now).toISOString(), bundles };
index.signature = signIndex(index, env);
await storage.put(INDEX_KEY, Buffer.from(`${JSON.stringify(index, null, '\t')}\n`), 'application/json');
return index;
}
async function removeFiles(storage, id, files, keep = new Set()) {
for (const file of files) if (!keep.has(file.sha256)) await storage.remove(fileKey(id, file.sha256));
}
// `replaceIndex` starts a new index when the stored one cannot be verified,
// which is what an operator needs after rotating the secret.
export async function publishBundles({ root, ids, storage = null, env = process.env, now = Date.now(), replaceIndex = false }) {
storage ||= bundleStorage(env);
secretFrom(env);
const built = [];
const failures = [];
for (const id of [...new Set(ids)]) {
try {
built.push(buildBundle(root, id, { now }));
} catch (err) {
failures.push(err.message);
}
}
if (failures.length) throw new Error(failures.join('\n'));
let existing = null;
try {
existing = await readIndex({ storage, env });
} catch (err) {
if (!(replaceIndex && err instanceof OverlayError && err.code !== 'unconfigured')) throw err;
}
const replaced = (existing?.bundles || []).filter((bundle) => built.some((row) => row.id === bundle.id));
const bundles = [...(existing?.bundles || []).filter((bundle) => !replaced.includes(bundle)), ...built];
const conflicts = fileConflicts(bundles);
if (conflicts.length) throw new Error(`bundles disagree about a file, so one of them would fail its review: ${conflicts.join('; ')}`);
// Files first, then the index, so the index never names a file that is not
// there yet.
let uploaded = 0;
let skipped = 0;
for (const bundle of built) {
for (const file of bundle.files) {
const key = fileKey(bundle.id, file.sha256);
if (await stored(storage, key)) {
skipped++;
continue;
}
await storage.put(key, readFileSync(resolve(root, file.path)), contentTypeOf(file.path));
uploaded++;
}
}
await writeIndex({ bundles, storage, env, now });
for (const old of replaced) {
const current = built.find((row) => row.id === old.id);
await removeFiles(storage, old.id, old.files, new Set(current.files.map((file) => file.sha256)));
}
return { published: built.map((bundle) => bundle.id), uploaded, skipped };
}
// Drops a bundle and its files. The last bundle takes the index with it, so an
// empty bucket reads as "no index" rather than as an index of nothing.
export async function removeBundle({ id, storage = null, env = process.env, now = Date.now() }) {
storage ||= bundleStorage(env);
const index = await readIndex({ storage, env });
const bundle = index?.bundles.find((row) => row.id === id);
if (!bundle) return { removed: false, remaining: index?.bundles.length || 0 };
const bundles = index.bundles.filter((row) => row !== bundle);
if (bundles.length) await writeIndex({ bundles, storage, env, now });
else await storage.remove(INDEX_KEY);
await removeFiles(storage, id, bundle.files);
return { removed: true, remaining: bundles.length };
}
export async function readIndex({ storage = null, env = process.env }) {
storage ||= bundleStorage(env);
secretFrom(env);
const bytes = await storage.get(INDEX_KEY);
if (!bytes) return null;
let index;
try {
index = JSON.parse(bytes.toString('utf8'));
} catch {
throw new OverlayError('bad_signature', 'the bundle index is not JSON, so there is nothing to verify');
}
verifyIndex(index, env);
if (index.version !== INDEX_VERSION) throw new OverlayError('bad_bundle', `bundle index version ${index.version} is not ${INDEX_VERSION}`);
if (!Array.isArray(index.bundles)) throw new OverlayError('bad_bundle', 'the bundle index has no bundle list');
index.bundles.forEach(checkBundle);
return index;
}
// Downloads every file the index names and checks it against its recorded hash.
export async function verifyBundles({ storage = null, env = process.env }) {
storage ||= bundleStorage(env);
const index = await readIndex({ storage, env });
if (!index) return { index: null, bundles: 0, files: 0, problems: [] };
const problems = fileConflicts(index.bundles);
let files = 0;
for (const bundle of index.bundles) {
for (const file of bundle.files) {
files++;
const bytes = await storage.get(fileKey(bundle.id, file.sha256));
if (!bytes) problems.push(`${bundle.id}: ${file.path} is missing from storage`);
else if (sha256(bytes) !== file.sha256) problems.push(`${bundle.id}: ${file.path} does not hash to ${file.sha256}`);
}
}
return { index, bundles: index.bundles.length, files, problems };
}
// ── The overlay directory ───────────────────────────────────────────────────
function kindOf(path) {
try {
const stat = lstatSync(path);
return stat.isSymbolicLink() ? 'link' : stat.isDirectory() ? 'directory' : 'file';
} catch (err) {
if (err.code === 'ENOENT') return null;
throw err;
}
}
const isDirectory = (path) => existsSync(path) && statSync(path).isDirectory();
// Removes what is at `path` and never what a symlink there points to.
function discard(path) {
const kind = kindOf(path);
if (kind === 'directory') rmSync(path, { recursive: true, force: true });
else if (kind) unlinkSync(path);
}
function link(target, path) {
if (kindOf(path) === 'link' && readlinkSync(path) === target) return;
discard(path);
symlinkSync(target, path);
}
// Written beside the destination and renamed over it. A rename replaces a
// symlink instead of following it, so a write can never land in the image.
function writeAtomic(path, bytes) {
const partial = `${path}.${process.pid}.partial`;
discard(partial);
writeFileSync(partial, bytes);
if (kindOf(path) === 'directory') discard(path);
renameSync(partial, path);
}
const parentOf = (path) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '');
const nameOf = (path) => path.slice(path.lastIndexOf('/') + 1);
// Every directory on the way to each path, nearest the root included.
function directoriesOf(paths) {
const directories = new Set();
for (const path of paths) for (let parent = parentOf(path); parent; parent = parentOf(parent)) directories.add(parent);
return directories;
}
// Lays `dir` out as a view of the image with room for `writes`, the relative
// paths of the files the overlay is about to write. A directory on the way to
// any of those paths becomes a real directory whose image entries are linked
// one by one; every other directory is a single link to the image's own. Works
// for a write at any depth, and leaves nothing behind from an earlier tick
// that this one does not want.
function layout({ imageRoot, dir, writes }) {
const owned = new Set(writes);
const parents = directoriesOf(writes);
const visit = (relative) => {
const here = join(dir, relative);
if (kindOf(here) !== 'directory') {
discard(here);
mkdirSync(here, { recursive: true });
}
const wanted = new Set(relative ? [] : [MARKER]);
const source = join(imageRoot, relative);
const names = isDirectory(source) ? readdirSync(source) : [];
for (const name of relative ? names : names.filter((entry) => EXPOSED.includes(entry))) {
const child = relative ? `${relative}/${name}` : name;
wanted.add(name);
if (!owned.has(child) && !parents.has(child)) link(join(source, name), join(here, name));
}
for (const path of [...owned, ...parents]) if (parentOf(path) === relative) wanted.add(nameOf(path));
for (const path of parents) if (parentOf(path) === relative) visit(path);
for (const name of readdirSync(here)) if (!wanted.has(name)) discard(join(here, name));
};
visit('');
}
const inside = (child, parent) => child === parent || child.startsWith(`${parent}${sep}`);
// The overlay prunes what it does not recognize, so it only ever takes a
// directory that is new, empty, or already its own.
function claimDirectory(dir, imageRoot) {
if (inside(imageRoot, dir)) throw new OverlayError('bad_dir', `${dir} contains the image root`);
if (EXPOSED.some((name) => inside(dir, join(imageRoot, name)))) throw new OverlayError('bad_dir', `${dir} is inside a directory the overlay mirrors`);
const kind = kindOf(dir);
if (kind && kind !== 'directory') throw new OverlayError('bad_dir', `${dir} is not a directory`);
if (kind && readdirSync(dir).length && !existsSync(join(dir, MARKER))) throw new OverlayError('bad_dir', `${dir} holds files that are not an overlay; pick an empty directory`);
mkdirSync(dir, { recursive: true, mode: 0o700 });
}
const hasBytes = (path, hash) => kindOf(path) === 'file' && sha256(readFileSync(path)) === hash;
// The image queue with the bundled items laid over it. A post the image records
// as posted is history and is never replaced; cadence and quality settings are
// always the image's.
export function mergeQueue(imageQueue, bundles) {
const items = [...(imageQueue.items || [])];
const applied = [];
const superseded = [];
for (const bundle of bundles) {
const at = items.findIndex((item) => item.id === bundle.id);
if (at >= 0 && items[at].status === 'posted') {
superseded.push(bundle.id);
continue;
}
if (at >= 0) items[at] = bundle.item;
else items.push(bundle.item);
applied.push(bundle);
}
return { queue: { ...imageQueue, items }, applied, superseded };
}
// Builds the overlay directory and returns its root. `files` counts the bundle
// files in the overlay, `reused` how many of them an earlier tick had already
// downloaded.
export async function materialize({ imageRoot, storage = null, env = process.env, dir = DEFAULT_OVERLAY_DIR, now = Date.now(), index = null }) {
storage ||= bundleStorage(env);
const image = resolve(imageRoot);
const root = resolve(dir);
const verified = index ? verifyIndex(index, env) : await readIndex({ storage, env });
if (!verified) throw new OverlayError('no_index', 'there is no bundle index in storage');
verified.bundles.forEach(checkBundle);
const { queue, applied, superseded } = mergeQueue(loadQueue(image), verified.bundles);
const conflicts = fileConflicts(applied);
if (conflicts.length) throw new OverlayError('bad_bundle', `bundles disagree about a file: ${conflicts.join('; ')}`);
const files = new Map();
for (const bundle of applied) for (const file of bundle.files) files.set(file.path, { ...file, id: bundle.id });
const writes = [QUEUE_PATH, ...applied.map((bundle) => reviewPath(bundle.id)), ...files.keys()];
const directories = directoriesOf(writes);
for (const path of files.keys()) if (directories.has(path)) throw new OverlayError('bad_path', `${path} is both a file and a directory on the way to another file`);
claimDirectory(root, image);
writeAtomic(join(root, MARKER), `${JSON.stringify({ imageRoot: image, materializedAt: new Date(now).toISOString() })}\n`);
layout({ imageRoot: image, dir: root, writes });
let reused = 0;
for (const file of files.values()) {
const path = join(root, file.path);
if (hasBytes(path, file.sha256)) {
reused++;
continue;
}
const bytes = await storage.get(fileKey(file.id, file.sha256));
if (!bytes) throw new OverlayError('bad_file', `${file.id}: ${file.path} is missing from storage`);
if (sha256(bytes) !== file.sha256) throw new OverlayError('bad_file', `${file.id}: ${file.path} does not hash to the ${file.sha256.slice(0, 12)} the index recorded`);
writeAtomic(path, bytes);
}
for (const bundle of applied) writeAtomic(join(root, reviewPath(bundle.id)), `${JSON.stringify(bundle.review, null, '\t')}\n`);
writeAtomic(join(root, QUEUE_PATH), `${JSON.stringify(queue, null, '\t')}\n`);
return { root, bundles: applied.map((bundle) => bundle.id), files: files.size, reused, superseded };
}
// The one call the cron makes: the root this tick should run against, and why.
// It answers with the image root whenever the overlay is switched off or cannot
// be trusted, and it never throws.
export async function resolveRoot({ imageRoot, env = process.env, storage = null, dir = DEFAULT_OVERLAY_DIR, now = Date.now() }) {
const image = (reason) => ({ root: imageRoot, overlay: null, reason });
const unavailable = (reason) => {
console.warn('[x-content] overlay unavailable, using the image queue', reason);
return image(reason);
};
if (env.X_CONTENT_REMOTE_QUEUE !== 'true') return image('X_CONTENT_REMOTE_QUEUE is not true');
try {
secretFrom(env);
// A named bucket is Cloud Storage, which needs no R2 credentials at all.
const gcs = Boolean(String(env.X_CONTENT_BUNDLE_BUCKET || '').trim());
if (!storage && !gcs && !(await import('../r2.js')).objectStorageConfigured()) return unavailable('object storage is not configured');
const store = storage || bundleStorage(env);
const index = await readIndex({ storage: store, env });
if (!index) return image('there is no bundle index in storage');
const { root, ...overlay } = await materialize({ imageRoot, storage: store, env, dir, now, index });
if (!overlay.bundles.length) return image('every bundle in the index is already posted in the image queue');
return { root, overlay, reason: `${overlay.bundles.length} bundle(s) laid over the image queue` };
} catch (err) {
return unavailable(String(err?.message || err));
}
}