Skip to content

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.

feat(x-content): fill tiered daily slots with the highest-priority ready post and hold broken posts instead of stalling the tick

nirholas45448e6b1c0e
diff --git a/api/_lib/x-content/priority.js b/api/_lib/x-content/priority.js
new file mode 100644
index 000000000..92cf8f58d
--- /dev/null
+++ b/api/_lib/x-content/priority.js
@@ -0,0 +1,149 @@
+// Which approved post goes out next: always the highest-priority one that is
+// ready, never simply the oldest. Pacing (schedule.js) decides *when* a slot
+// opens; this module decides *what* fills it.
+//
+// A score is a sum of named, explainable parts, so `npm run x:content -- plan`
+// can show exactly why one post outranks another:
+//
+// engagement predicted lift from how @trythreews posts with the same signals
+// actually performed (data/x-archive/analysis), using the same
+// format, length, and topic classifiers that produced the report
+// timely a post with `expiresAt` rises as its window closes, and is
+// dropped once it has passed (stale news is worse than none)
+// boost the owner's explicit `priority` on the item, -50 to +50
+// waiting +1 per day an item has been ready, so nothing starves
+// review the AI editor's average score above or below 4
+// variety a penalty when the post would repeat the last lane or pattern
+// more times in a row than the queue allows
+//
+// Small samples are shrunk toward no effect: the archive measured "names
+// $THREE" at 13.3x over only four posts, and one lucky post should not decide
+// the whole queue.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { FORMAT_DIMENSIONS, LENGTH_BUCKETS, TOPICS } from '../../../scripts/x-archive-lib.mjs';
+import { weightedLength } from './quality.js';
+
+const DAY = 24 * 60 * 60_000;
+// Prior strength for shrinkage: a signal measured on n posts keeps n / (n + K)
+// of its log-lift.
+const SHRINK_K = 10;
+const TIMELY_WINDOW_MS = 2 * DAY;
+
+export const ENGAGEMENT_REPORT = 'data/x-archive/analysis/trythreews-engagement.json';
+
+export function loadLifts(root) {
+ const path = resolve(root, ENGAGEMENT_REPORT);
+ if (!existsSync(path)) return null;
+ const report = JSON.parse(readFileSync(path, 'utf8')).report || {};
+ const lifts = new Map();
+ const add = (group, row) => {
+ const lift = row.lift ?? row.with?.lift;
+ const count = row.count ?? row.with?.count ?? 0;
+ if (lift > 0 && count > 0) lifts.set(`${group}:${row.key}`, { lift, count });
+ };
+ for (const row of report.formats || []) add('format', row);
+ for (const row of report.lengths || []) add('length', row);
+ for (const row of report.topics || []) add('topic', row);
+ return lifts;
+}
+
+const shrunkLog = ({ lift, count }) => (count / (count + SHRINK_K)) * Math.log(lift);
+
+// The head post, described the way the archive classifiers describe a scraped
+// post, so the signals line up with the ones the report measured.
+function asArchivePost(item) {
+ const head = item.posts?.[0] || {};
+ const media = head.media || [];
+ const text = String(item.kind === 'article' ? `${item.article?.title || ''}\n${head.text || ''}` : head.text || '');
+ return {
+ text,
+ hasImage: media.some((row) => /\.(png|jpe?g|webp|gif)$/i.test(row.path)) || Boolean(item.article?.cover),
+ hasVideo: media.some((row) => /\.(mp4|mov)$/i.test(row.path)),
+ hasCard: false,
+ mentions: text.match(/(?<![\w@])@\w{1,15}/g) || [],
+ urls: [],
+ isReply: false,
+ };
+}
+
+export function engagementSignals(item, lifts) {
+ if (!lifts) return [];
+ const post = asArchivePost(item);
+ const keys = [];
+ for (const dimension of FORMAT_DIMENSIONS) if (dimension.test(post)) keys.push(`format:${dimension.key}`);
+ const length = weightedLength(item.posts?.[0]?.text || '');
+ const bucket = LENGTH_BUCKETS.find((row) => length >= row.min && length <= row.max);
+ if (bucket) keys.push(`length:${bucket.key}`);
+ const topics = TOPICS.filter((topic) => topic.patterns.some((pattern) => pattern.test(post.text))).map((topic) => topic.key);
+ for (const topic of topics.length ? topics : ['other']) keys.push(`topic:${topic}`);
+ return keys.filter((key) => lifts.has(key)).map((key) => ({ key, ...lifts.get(key), weight: shrunkLog(lifts.get(key)) }));
+}
+
+// The signals overlap (a post that tags a partner usually also carries an
+// image and a link), so summing them would count one good post several times.
+// The estimate is the strongest topic signal plus the average of the format
+// and length signals.
+function combinedLog(signals) {
+ const topics = signals.filter((row) => row.key.startsWith('topic:')).map((row) => row.weight);
+ const shape = signals.filter((row) => !row.key.startsWith('topic:')).map((row) => row.weight);
+ const topic = topics.length ? Math.max(...topics) : 0;
+ const form = shape.length ? shape.reduce((a, b) => a + b, 0) / shape.length : 0;
+ return topic + form;
+}
+
+function trailingRun(published, field, value) {
+ let run = 0;
+ for (let index = published.length - 1; index >= 0; index--) {
+ if (published[index][field] !== value) break;
+ run++;
+ }
+ return run;
+}
+
+// Returns { score, parts } or { expired: true } when a timely post has passed.
+export function scoreItem(item, { lifts, published = [], quality = {}, review = null, now = Date.now() }) {
+ const parts = {};
+
+ const signals = engagementSignals(item, lifts);
+ const predicted = Math.exp(combinedLog(signals));
+ parts.engagement = Math.round(10 * Math.log2(predicted) * 10) / 10;
+
+ if (item.expiresAt) {
+ const left = Date.parse(item.expiresAt) - now;
+ if (left <= 0) return { expired: true, score: -Infinity, parts, signals };
+ parts.timely = left < TIMELY_WINDOW_MS ? Math.round(20 * (1 - left / TIMELY_WINDOW_MS)) : 0;
+ }
+
+ const boost = Number(item.priority || 0);
+ if (boost) parts.boost = Math.max(-50, Math.min(50, boost));
+
+ const ready = Date.parse(item.notBefore);
+ if (Number.isFinite(ready) && now > ready) parts.waiting = Math.min(10, Math.floor((now - ready) / DAY));
+
+ const scores = review?.editor?.scores;
+ if (scores) {
+ const values = Object.values(scores).map(Number).filter(Number.isFinite);
+ if (values.length) parts.review = Math.round((values.reduce((a, b) => a + b, 0) / values.length - 4) * 5 * 10) / 10;
+ }
+
+ const sorted = [...published].sort((a, b) => a.publishedAt.localeCompare(b.publishedAt));
+ const maxLane = Number(quality.maximumSameLaneInARow ?? Infinity);
+ const maxPattern = Number(quality.maximumSamePatternInARow ?? Infinity);
+ if (trailingRun(sorted, 'lane', item.lane) >= maxLane || trailingRun(sorted, 'pattern', item.pattern) >= maxPattern) {
+ parts.variety = -25;
+ }
+
+ const score = Math.round(Object.values(parts).reduce((sum, value) => sum + value, 0) * 10) / 10;
+ return { score, parts, signals, predictedLift: Math.round(predicted * 100) / 100 };
+}
+
+// Every ready candidate, best first. Ties go to the item that has been ready
+// longest, then to id order, so the ranking is deterministic.
+export function rankItems(items, context) {
+ return items
+ .map((item) => ({ item, ...scoreItem(item, { ...context, review: context.reviews?.get?.(item.id) || null }) }))
+ .filter((row) => !row.expired)
+ .sort((a, b) => b.score - a.score || Date.parse(a.item.notBefore) - Date.parse(b.item.notBefore) || a.item.id.localeCompare(b.item.id));
+}
diff --git a/api/_lib/x-content/publisher.js b/api/_lib/x-content/publisher.js
index e7d8ab66c..43a46570f 100644
--- a/api/_lib/x-content/publisher.js
+++ b/api/_lib/x-content/publisher.js
@@ -108,9 +108,13 @@ async function publishArticle({ client, root, item, progress, persist }) {
}
// Publishes `item`, resuming from state.inflight. Returns the ledger row.
-export async function publishItem({ item, client, root, state, store, account = 'trythreews' }) {
+// `meta` (the slot and tier the scheduler gave this post) is pinned on the
+// first attempt, so a thread resumed after a crash is still credited to the
+// slot it started in and that slot is never spent twice.
+export async function publishItem({ item, client, root, state, store, account = 'trythreews', meta = {}, now = Date.now() }) {
state.inflight ||= {};
const progress = (state.inflight[item.id] ||= { media: {}, postIds: [] });
+ progress.meta ||= meta;
const persist = () => store.save(state);
if (item.kind === 'article') await publishArticle({ client, root, item, progress, persist });
@@ -122,10 +126,11 @@ export async function publishItem({ item, client, root, state, store, account =
kind: item.kind,
lane: item.lane,
pattern: item.pattern,
- publishedAt: new Date().toISOString(),
+ publishedAt: new Date(Math.max(now, Date.now() - 60 * 60_000 * 24 * 365)).toISOString(),
text: item.kind === 'article' ? item.article.title : item.posts[0].text,
postIds: progress.postIds,
url: `https://x.com/${account}/status/${leadId}`,
+ ...progress.meta,
};
if (progress.articlePostId) row.articlePostId = progress.articlePostId;
state.published = [...(state.published || []), row];
diff --git a/api/_lib/x-content/queue.js b/api/_lib/x-content/queue.js
index 0256e5a37..bae14103f 100644
--- a/api/_lib/x-content/queue.js
+++ b/api/_lib/x-content/queue.js
@@ -119,6 +119,14 @@ export function validateItem(item, root) {
if (!KINDS.includes(item.kind)) problems.push(`kind must be one of ${KINDS.join(', ')}`);
if (!item.lane || !item.pattern) problems.push('lane and pattern are required (they drive rotation)');
if (!Number.isFinite(Date.parse(item.notBefore))) problems.push('notBefore must be an ISO-8601 timestamp');
+ if (![1, 2, 3].includes(Number(item.tier))) problems.push('tier must be 1 (flagship), 2 (feature), or 3 (proof of work)');
+ if (item.expiresAt !== undefined && !Number.isFinite(Date.parse(item.expiresAt))) problems.push('expiresAt must be an ISO-8601 timestamp');
+ if (item.priority !== undefined && !(Number(item.priority) >= -50 && Number(item.priority) <= 50)) problems.push('priority is an owner boost from -50 to 50');
+ for (const probe of item.probes || []) {
+ if (!['api', 'browser', 'command'].includes(probe.type)) problems.push(`probe type ${probe.type} must be api, browser, or command`);
+ if (probe.type === 'api' && !/^https:\/\//.test(String(probe.url || ''))) problems.push('api probes need an https url');
+ if (probe.type === 'command' && !Array.isArray(probe.argv)) problems.push('command probes need an argv array');
+ }
if (item.kind === 'post') {
if (!item.posts?.length) problems.push('a post item needs at least one post');
diff --git a/api/_lib/x-content/review.js b/api/_lib/x-content/review.js
index abc0a2bf1..7e3b7e184 100644
--- a/api/_lib/x-content/review.js
+++ b/api/_lib/x-content/review.js
@@ -35,6 +35,7 @@ export function contentHash(item, root) {
: null,
claims: item.claims || [],
mentions: item.mentions || {},
+ probes: item.probes || [],
};
return createHash('sha256').update(JSON.stringify(subject)).digest('hex');
}
diff --git a/api/_lib/x-content/runner.js b/api/_lib/x-content/runner.js
index feb40873e..8d9a67065 100644
--- a/api/_lib/x-content/runner.js
+++ b/api/_lib/x-content/runner.js
@@ -1,12 +1,103 @@
// One tick of the content queue, shared by the Cloud Scheduler cron and the
-// CLI: validate, pick the due item, then either preview it or publish it.
+// CLI: validate, open a slot, fill it with the highest-priority ready post,
+// then either preview it or publish it.
+//
+// A tick never ends on a failed post. If the best post cannot go out right now
+// (a link is down, a feature probe fails, X rejects the content), that post is
+// put on hold with the reason and a backoff, and the slot goes to the next-best
+// post in the same tick. Only failures that are not the post's fault (X is
+// down, rate-limited, or rejecting our credentials) stop the tick, because
+// every post would fail the same way; the next tick retries.
import { loadQueue, validateQueue } from './queue.js';
-import { pickDue } from './schedule.js';
+import { TIERS, pickDue, tierOf } from './schedule.js';
+import { loadLifts } from './priority.js';
+import { loadReview, contentHash } from './review.js';
import { previewClient, publishItem, xClientFromEnv } from './publisher.js';
-import { itemTexts, linkChecks } from './verify.js';
+import { itemTexts, linkChecks, probeChecks } from './verify.js';
-export async function runTick({ root, store, now = Date.now(), dryRun = true, requestedId = null, env = process.env }) {
+const HOUR = 60 * 60_000;
+// Tries per tick before giving up the slot: enough to skip a few broken posts,
+// bounded so one tick cannot spend an hour on pre-flight checks.
+const MAX_ATTEMPTS_PER_TICK = 5;
+const HOLD_BACKOFF_MS = [2 * HOUR, 6 * HOUR, 24 * HOUR];
+
+// A hold lasts until its backoff ends, or until the post itself changes (a new
+// content hash means someone fixed it, so it may go again at once).
+export function activeHolds(state, items, root, now = Date.now()) {
+ const held = new Set();
+ for (const item of items) {
+ const hold = state.holds?.[item.id];
+ if (hold && hold.hash === contentHash(item, root) && Date.parse(hold.until) > now) held.add(item.id);
+ }
+ return held;
+}
+
+export function placeHold(state, item, root, reason, now = Date.now()) {
+ state.holds ||= {};
+ const previous = state.holds[item.id];
+ const hash = contentHash(item, root);
+ const attempts = previous?.hash === hash ? previous.attempts + 1 : 1;
+ const backoff = HOLD_BACKOFF_MS[Math.min(attempts, HOLD_BACKOFF_MS.length) - 1];
+ state.holds[item.id] = { reason, attempts, hash, heldAt: new Date(now).toISOString(), until: new Date(now + backoff).toISOString() };
+ return state.holds[item.id];
+}
+
+// Whether an X API error is about this post (hold it, try the next) or about
+// the account or the platform (stop, retry the same post next tick).
+export function isPostSpecific(err) {
+ const status = Number(err?.code ?? err?.status);
+ if (!status || status === 429 || status >= 500 || status === 401) return false;
+ const text = JSON.stringify(err?.data || err?.message || '').toLowerCase();
+ if (status === 403) return /duplicate|not allowed to create/.test(text);
+ return status >= 400 && status < 500;
+}
+
+// Nothing of this post exists on X yet, so skipping it cannot leave a thread
+// or an Article half-published.
+const untouched = (state, item) => {
+ const progress = state.inflight?.[item.id];
+ return !progress || (!progress.postIds?.length && !progress.articleDraftId && !progress.articlePostId);
+};
+
+async function preflight(item, root) {
+ const checks = [...(await linkChecks(itemTexts(item))), ...(await probeChecks(item, { root, where: 'publish' }))];
+ return checks.filter((check) => !check.ok);
+}
+
+// ── Inventory ───────────────────────────────────────────────────────────────
+// Days of approved, ready stock per tier (one slot per tier per day). Anything
+// under INVENTORY_WARN_DAYS is raised once a day through the platform's ops
+// alerts, so the queue asks for more posts before it goes quiet, instead of
+// after.
+export const INVENTORY_WARN_DAYS = 3;
+
+export function inventory(items, state, root, now = Date.now()) {
+ const publishedIds = new Set((state.published || []).map((row) => row.id));
+ const held = activeHolds(state, items, root, now);
+ const counts = new Map(TIERS.map((tier) => [tier, 0]));
+ for (const item of items) {
+ if (item.status !== 'approved' || publishedIds.has(item.id) || held.has(item.id)) continue;
+ if (item.expiresAt && Date.parse(item.expiresAt) <= now) continue;
+ counts.set(tierOf(item), counts.get(tierOf(item)) + 1);
+ }
+ return TIERS.map((tier) => ({ tier, days: counts.get(tier), low: counts.get(tier) < INVENTORY_WARN_DAYS }));
+}
+
+async function alertLowInventory(state, store, stock, now) {
+ const today = new Date(now).toISOString().slice(0, 10);
+ if (!stock.some((row) => row.low) || state.inventoryAlertedOn === today) return null;
+ const { sendOpsAlert } = await import('../alerts.js');
+ const summary = stock.map((row) => `T${row.tier}: ${row.days} day(s)`).join(', ');
+ await sendOpsAlert('x-content: approved post stock is low', `${summary}. Draft, review, and approve more posts: npm run x:content -- plan`);
+ state.inventoryAlertedOn = today;
+ await store.save(state);
+ return summary;
+}
+
+// `client` and `checks` default to the real X client and the real pre-flight;
+// tests pass their own to drive the hold-and-fall-through path.
+export async function runTick({ root, store, now = Date.now(), dryRun = true, requestedId = null, env = process.env, client: injectedClient = null, checks = preflight }) {
const queue = loadQueue(root);
const state = await store.load();
const { problems } = validateQueue(queue, root, { state });
@@ -17,8 +108,8 @@ export async function runTick({ root, store, now = Date.now(), dryRun = true, re
// A named preview shows the calls even for an item that still fails review,
// so the operator sees exactly what they are fixing.
const publishable = (queue.items || []).filter((item) => !problems[item.id]?.length || (dryRun && item.id === requestedId));
-
- const decision = pickDue({
+ const reviews = new Map(publishable.map((item) => [item.id, loadReview(root, item.id)]));
+ const context = {
items: publishable,
state,
now,
@@ -26,28 +117,63 @@ export async function runTick({ root, store, now = Date.now(), dryRun = true, re
quality: queue.quality,
requestedId,
anyStatus: dryRun,
- // The queue is public; the minute an item lands is not. See schedule.js.
+ // The queue is public; the minute a slot opens is not. See schedule.js.
seed: env.X_CONTENT_SCHEDULE_SEED || null,
- });
- if (!decision.item) return { published: null, reason: decision.reason, blocked };
+ lifts: loadLifts(root),
+ reviews,
+ };
- const item = decision.item;
if (dryRun) {
+ const decision = pickDue({ ...context, exclude: activeHolds(state, publishable, root, now) });
+ if (!decision.item) return { published: null, reason: decision.reason, blocked };
const client = previewClient();
// Preview against a scratch copy: the real ledger must not change.
const scratch = structuredClone(state);
- await publishItem({ item, client, root, state: scratch, store: { save: async () => {} }, account: queue.account });
- return { preview: { id: item.id, kind: item.kind, dueAt: new Date(decision.dueAt).toISOString(), calls: client.calls }, blocked };
- }
-
- // A page can break between review and publish. Never send a dead link.
- const broken = (await linkChecks(itemTexts(item))).filter((check) => !check.ok);
- if (broken.length) {
- return { published: null, reason: `${item.id} links a page that is down right now`, blocked: [...blocked, { id: item.id, problems: broken.map((check) => `${check.target}: ${check.detail}`) }] };
+ await publishItem({ item: decision.item, client, root, state: scratch, store: { save: async () => {} }, account: queue.account });
+ return { preview: { id: decision.item.id, kind: decision.item.kind, score: decision.score, parts: decision.parts, ranking: decision.ranking, calls: client.calls }, blocked };
}
- const client = await xClientFromEnv(env);
+ const client = injectedClient || (await xClientFromEnv(env));
if (!client) return { published: null, skipped: 'not_configured', reason: 'X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_SECRET are required', blocked };
- const row = await publishItem({ item, client, root, state, store, account: queue.account });
- return { published: row, resumed: Boolean(decision.resuming), blocked };
+
+ const stock = inventory(publishable, state, root, now);
+ const lowStock = requestedId ? null : await alertLowInventory(state, store, stock, now).catch(() => null);
+
+ const exclude = requestedId ? new Set() : activeHolds(state, publishable, root, now);
+ const held = [];
+ for (let attempt = 0; attempt < MAX_ATTEMPTS_PER_TICK; attempt++) {
+ const decision = pickDue({ ...context, exclude });
+ if (!decision.item) return { published: null, reason: decision.reason, held, blocked, stock, lowStock };
+ const item = decision.item;
+
+ // A resumed thread must finish what it started, so it skips pre-flight.
+ if (!decision.resuming) {
+ const failures = await checks(item, root);
+ if (failures.length) {
+ const reason = failures.map((check) => `${check.kind} ${check.target}: ${check.detail}`).join('; ');
+ held.push({ id: item.id, reason, hold: placeHold(state, item, root, reason, now) });
+ await store.save(state);
+ exclude.add(item.id);
+ continue;
+ }
+ }
+
+ try {
+ const meta = decision.slot ? { slot: decision.slot.key, tier: decision.tier, slotTier: decision.slot.tier } : {};
+ const row = await publishItem({ item, client, root, state, store, account: queue.account, meta });
+ if (state.holds?.[item.id]) {
+ delete state.holds[item.id];
+ await store.save(state);
+ }
+ return { published: row, stock, lowStock, score: decision.score, tier: decision.tier, filledDown: Boolean(decision.filledDown), resumed: Boolean(decision.resuming), held, blocked };
+ } catch (err) {
+ if (!isPostSpecific(err) || !untouched(state, item)) throw err;
+ const reason = `X rejected the post: ${err.message}`;
+ held.push({ id: item.id, reason, hold: placeHold(state, item, root, reason, now) });
+ delete state.inflight?.[item.id];
+ await store.save(state);
+ exclude.add(item.id);
+ }
+ }
+ return { published: null, reason: `${MAX_ATTEMPTS_PER_TICK} posts were held this tick; the slot stays open for the next tick`, held, blocked };
}
diff --git a/api/_lib/x-content/schedule.js b/api/_lib/x-content/schedule.js
index 05383a81e..9369285d0 100644
--- a/api/_lib/x-content/schedule.js
+++ b/api/_lib/x-content/schedule.js
@@ -1,18 +1,18 @@
-// Picks the one item a tick should publish, or explains why nothing is due.
-//
-// Human cadence, not cron cadence. An account that posts at 14:00:00 every day
-// in lane order is obviously a bot. So:
-// - each item lands at a stable jittered moment inside its window after
-// `notBefore` (hashed from its id, so a preview and the real tick agree);
-// - posts keep a minimum gap and a rolling 24h cap;
-// - quiet hours are respected;
-// - the same lane or format never runs more times in a row than the config
-// allows, unless the item has waited a full day past its moment (so a
-// one-lane queue still drains).
+// Decides when the next post may go out, and hands the slot to the
+// highest-priority ready post (priority.js). Which post and when are separate
+// questions on purpose: the queue always spends a slot on the most valuable
+// thing it has, and the slot itself follows a human cadence, not a cron one:
+// - a minimum gap between posts, stretched by a secret per-gap jitter, so the
+// account never posts on the hour and the next minute cannot be predicted;
+// - a rolling 24h cap and quiet hours;
+// - `notBefore` is an embargo: an item is not ready before it;
+// - a half-published item (thread cut off, Article drafted) always resumes
+// first, ahead of every pacing and priority rule.
// Pure: no I/O, so the rules are unit-tested and the CLI shows the same
// decision the cron will make.
import { createHash, createHmac } from 'node:crypto';
+import { rankItems } from './priority.js';
const MINUTE = 60_000;
const DAY = 24 * 60 * MINUTE;
@@ -45,42 +45,6 @@ export function jitterMinutes(id, windowMinutes, seed = null) {
return digest.readUInt32BE(0) % Math.max(1, windowMinutes);
}
-const startOfUtcDay = (timestamp) => Date.parse(`${new Date(timestamp).toISOString().slice(0, 10)}T00:00:00Z`);
-const minutesOfUtcDay = (timestamp) => (timestamp - startOfUtcDay(timestamp)) / MINUTE;
-
-// The anchor each of a day's items takes, as minutes past midnight UTC. The
-// anchors are the ones the plan already chose; the seed only decides which item
-// gets which, so no item ever moves outside the day, the quiet hours, or the
-// cadence it was planned under.
-export function anchorAssignments(items, seed = null) {
- const assignments = new Map();
- if (!seed) return assignments;
- const byDay = new Map();
- for (const item of items) {
- const at = Date.parse(item.notBefore);
- if (!Number.isFinite(at)) continue;
- const day = startOfUtcDay(at);
- if (!byDay.has(day)) byDay.set(day, []);
- byDay.get(day).push(item);
- }
- for (const [, dayItems] of byDay) {
- const anchors = dayItems.map((item) => minutesOfUtcDay(Date.parse(item.notBefore))).sort((left, right) => left - right);
- const order = [...dayItems].sort((left, right) => {
- const rank = (item) => createHmac('sha256', String(seed)).update(`order:${item.id}`).digest('hex');
- return rank(left).localeCompare(rank(right));
- });
- order.forEach((item, index) => assignments.set(item.id, anchors[index]));
- }
- return assignments;
-}
-
-export function dueAt(item, cadence = DEFAULT_CADENCE, { seed = null, anchorMinutes = null } = {}) {
- const window = Number(item.windowMinutes ?? cadence.windowMinutes ?? DEFAULT_CADENCE.windowMinutes);
- const planned = Date.parse(item.notBefore);
- const base = anchorMinutes === null || anchorMinutes === undefined ? planned : startOfUtcDay(planned) + anchorMinutes * MINUTE;
- return base + jitterMinutes(item.id, window, seed) * MINUTE;
-}
-
export function inQuietHours(now, quiet) {
if (!Array.isArray(quiet) || quiet.length !== 2) return false;
const minutes = new Date(now).getUTCHours() * 60 + new Date(now).getUTCMinutes();
@@ -91,62 +55,134 @@ export function inQuietHours(now, quiet) {
return start <= end ? minutes >= start && minutes < end : minutes >= start || minutes < end;
}
-function trailingRun(published, field, value) {
- let run = 0;
- for (let index = published.length - 1; index >= 0; index--) {
- if (published[index][field] !== value) break;
- run++;
+// ── The day plan ────────────────────────────────────────────────────────────
+// Three slots a day, each owned by a tier:
+// T1 flagship partner news, $THREE utility, major launches
+// T2 features shipped features with proof
+// T3 proof of work short demos, stats, build notes
+// Slot times come from the engagement report's hour-of-day data, and each slot
+// opens at a jittered minute only the seed can reproduce. A slot stays open
+// until the next one starts, so a missed tick (deploy, outage) still posts, but
+// a day never gets more than one post per slot.
+//
+// Filling a slot: the slot's own tier first, then lower tiers (T1 slot empty ->
+// best T2), so the best available post always gets the best time. A higher tier
+// only fills a lower slot when it has a surplus, so the last flagship post is
+// kept for prime time instead of being spent off-peak. Nothing ready at all
+// means nothing posts: 3 a day is a ceiling, not a quota.
+
+export const TIERS = [1, 2, 3];
+
+export const DEFAULT_SLOTS = [
+ { tier: 3, at: '08:00' },
+ { tier: 1, at: '16:00' },
+ { tier: 2, at: '22:00' },
+];
+
+const dayKey = (timestamp) => new Date(timestamp).toISOString().slice(0, 10);
+const atMinutes = (at) => {
+ const [h, m] = String(at).split(':').map(Number);
+ return h * 60 + (m || 0);
+};
+
+// Every slot opening from yesterday through tomorrow, in time order, so the
+// slot spanning midnight (22:00 until the next morning) is found too.
+export function slotOpenings(now, cadence = DEFAULT_CADENCE, seed = null) {
+ const slots = cadence.slots?.length ? cadence.slots : DEFAULT_SLOTS;
+ const window = Number(cadence.windowMinutes ?? DEFAULT_CADENCE.windowMinutes);
+ const today = Date.parse(`${dayKey(now)}T00:00:00Z`);
+ const openings = [];
+ for (const offset of [-1, 0, 1]) {
+ const day = today + offset * DAY;
+ slots.forEach((slot, index) => {
+ const key = `${dayKey(day)}#${index}`;
+ openings.push({ key, tier: Number(slot.tier), opensAt: day + (atMinutes(slot.at) + jitterMinutes(`slot:${key}`, window, seed)) * MINUTE });
+ });
}
- return run;
+ return openings.sort((a, b) => a.opensAt - b.opensAt);
+}
+
+// The slot that is open right now (the latest one that has opened), and when
+// the next one opens.
+export function currentSlot(now, cadence = DEFAULT_CADENCE, seed = null) {
+ const openings = slotOpenings(now, cadence, seed);
+ const index = openings.findLastIndex((slot) => slot.opensAt <= now);
+ return { slot: index >= 0 ? openings[index] : null, next: openings[index + 1] || null };
+}
+
+// The order tiers are tried in for a slot: its own, then every lower tier,
+// then higher tiers that have more than one post ready.
+export function tierOrder(slotTier, readyByTier) {
+ const lower = TIERS.filter((tier) => tier >= slotTier);
+ const higher = TIERS.filter((tier) => tier < slotTier && (readyByTier.get(tier) || 0) > 1).reverse();
+ return [...lower, ...higher];
}
-// `requestedId` names one item and skips pacing; `anyStatus` lets a preview of
-// that item run before it is approved.
-export function pickDue({ items, state, now = Date.now(), cadence: rawCadence = {}, quality = {}, requestedId = null, anyStatus = false, seed = null }) {
+export const tierOf = (item) => (TIERS.includes(Number(item.tier)) ? Number(item.tier) : 2);
+
+// `requestedId` names one item and skips pacing and ranking; `anyStatus` lets a
+// preview of that item run before it is approved. `exclude` holds ids this
+// tick already tried and could not send, so the slot falls to the next best.
+export function pickDue({
+ items,
+ state,
+ now = Date.now(),
+ cadence: rawCadence = {},
+ quality = {},
+ requestedId = null,
+ anyStatus = false,
+ seed = null,
+ lifts = null,
+ reviews = null,
+ exclude = new Set(),
+}) {
const cadence = { ...DEFAULT_CADENCE, ...rawCadence };
const published = [...(state?.published || [])].sort((a, b) => a.publishedAt.localeCompare(b.publishedAt));
const publishedIds = new Set(published.map((row) => row.id));
const inflight = state?.inflight || {};
- const eligible = items
+ const unpublished = items
.filter((item) => (item.status === 'approved' || (anyStatus && requestedId)) && !publishedIds.has(item.id))
.filter((item) => !requestedId || item.id === requestedId);
- const anchors = anchorAssignments(eligible, seed);
- const candidates = eligible
- .map((item) => ({ item, at: dueAt(item, cadence, { seed, anchorMinutes: anchors.get(item.id) ?? null }) }))
- .sort((a, b) => a.at - b.at);
if (requestedId) {
- return candidates[0] ? { item: candidates[0].item, dueAt: candidates[0].at, forced: true } : { item: null, reason: `no ${anyStatus ? '' : 'approved '}unpublished item named ${requestedId}` };
+ return unpublished[0] ? { item: unpublished[0], forced: true } : { item: null, reason: `no ${anyStatus ? '' : 'approved '}unpublished item named ${requestedId}` };
}
- // A half-published item (thread cut off mid-way, Article drafted but not
- // yet published) always resumes first, ahead of every pacing rule.
- const resuming = candidates.find(({ item }) => inflight[item.id]);
- if (resuming) return { item: resuming.item, dueAt: resuming.at, resuming: true };
+ const resuming = unpublished.find((item) => inflight[item.id] && !exclude.has(item.id));
+ if (resuming) return { item: resuming, resuming: true };
if (inQuietHours(now, cadence.quietHoursUtc)) return { item: null, reason: 'quiet hours' };
+ const { slot, next } = currentSlot(now, cadence, seed);
+ const nextAt = next ? new Date(next.opensAt).toISOString() : 'tomorrow';
+ if (!slot) return { item: null, reason: `no slot is open; the next opens at ${nextAt}` };
+ if (published.some((row) => row.slot === slot.key)) return { item: null, reason: `slot ${slot.key} (T${slot.tier}) is used; the next opens at ${nextAt}` };
const last = published[published.length - 1];
- if (last) {
- const nextAllowed = Date.parse(last.publishedAt) + cadence.minimumMinutesApart * MINUTE;
- if (now < nextAllowed) return { item: null, reason: `spacing: next post allowed at ${new Date(nextAllowed).toISOString()}` };
+ if (last && now < Date.parse(last.publishedAt) + cadence.minimumMinutesApart * MINUTE) {
+ return { item: null, reason: `spacing: the last post went out at ${last.publishedAt}` };
}
const lastDay = published.filter((row) => now - Date.parse(row.publishedAt) < DAY).length;
if (lastDay >= cadence.dailyCap) return { item: null, reason: `daily cap of ${cadence.dailyCap} reached` };
- const maxLane = Number(quality.maximumSameLaneInARow ?? Infinity);
- const maxPattern = Number(quality.maximumSamePatternInARow ?? Infinity);
- const due = candidates.filter(({ at }) => at <= now);
- if (!due.length) {
- const next = candidates[0];
- return { item: null, reason: next ? `next item ${next.item.id} is due at ${new Date(next.at).toISOString()}` : 'queue has no approved unpublished items' };
- }
- for (const candidate of due) {
- const starved = now - candidate.at >= DAY;
- const laneRun = trailingRun(published, 'lane', candidate.item.lane);
- const patternRun = trailingRun(published, 'pattern', candidate.item.pattern);
- if (starved || (laneRun < maxLane && patternRun < maxPattern)) return { item: candidate.item, dueAt: candidate.at };
+ const ready = unpublished.filter((item) => !exclude.has(item.id) && Date.parse(item.notBefore) <= now);
+ const context = { lifts, published, quality, reviews, now };
+ const readyByTier = new Map(TIERS.map((tier) => [tier, ready.filter((item) => tierOf(item) === tier).length]));
+ for (const tier of tierOrder(slot.tier, readyByTier)) {
+ const ranked = rankItems(ready.filter((item) => tierOf(item) === tier), context);
+ if (!ranked.length) continue;
+ const [top] = ranked;
+ return {
+ item: top.item,
+ slot,
+ tier,
+ filledDown: tier !== slot.tier,
+ score: top.score,
+ parts: top.parts,
+ ranking: ranked.map((row) => ({ id: row.item.id, score: row.score })),
+ };
}
- return { item: null, reason: 'every due item would repeat the previous lane or pattern; waiting for variety' };
+ const embargoed = unpublished.filter((item) => !exclude.has(item.id) && Date.parse(item.notBefore) > now).sort((a, b) => a.notBefore.localeCompare(b.notBefore));
+ if (embargoed[0]) return { item: null, slot, reason: `nothing is ready for slot ${slot.key}; ${embargoed[0].id} is embargoed until ${embargoed[0].notBefore}` };
+ return { item: null, slot, reason: exclude.size ? `every ready post was held this tick; slot ${slot.key} stays open` : 'queue has no approved unpublished posts' };
}
diff --git a/api/_lib/x-content/verify.js b/api/_lib/x-content/verify.js
index eeb0d7817..b1845883e 100644
--- a/api/_lib/x-content/verify.js
+++ b/api/_lib/x-content/verify.js
@@ -205,6 +205,94 @@ async function spellingChecks(item, texts, glossary) {
}));
}
+// ── Feature probes ──────────────────────────────────────────────────────────
+// A claim check proves the page says something. A probe proves the feature
+// does it. Every item headed for approval declares at least one, in `probes`:
+//
+// api fetch a URL; expect a status, text, or a JSON value. Cheap and
+// dependency-free, so it runs at review AND seconds before posting.
+// browser drive the live page in a real browser: goto, click, expect text.
+// command run a repo test that exercises the exact behavior the post claims
+// (e.g. `node --test packages/three-token-mcp/test/burn-policy.test.mjs`).
+// Browser and command probes need a browser and a checkout, so they run at
+// review time only; the production pre-flight runs the api probes.
+
+const jsonPath = (value, path) => String(path).split('.').reduce((node, key) => (node == null ? node : node[key]), value);
+
+async function apiProbe(probe) {
+ const response = await fetchWithTimeout(probe.url, {
+ method: probe.method || 'GET',
+ headers: probe.body ? { 'content-type': 'application/json' } : {},
+ body: probe.body ? JSON.stringify(probe.body) : undefined,
+ }, probe.timeoutMs || 20_000);
+ const expect = probe.expect || {};
+ const statusOk = expect.status ? response.status === expect.status : response.ok;
+ if (!statusOk) return { ok: false, detail: `HTTP ${response.status}` };
+ const body = await response.text();
+ if (expect.contains && !body.includes(expect.contains)) return { ok: false, detail: `response does not contain "${expect.contains}"` };
+ if (expect.json) {
+ let parsed;
+ try {
+ parsed = JSON.parse(body);
+ } catch {
+ return { ok: false, detail: 'response is not JSON' };
+ }
+ const value = jsonPath(parsed, expect.json.path);
+ if ('equals' in expect.json && JSON.stringify(value) !== JSON.stringify(expect.json.equals)) return { ok: false, detail: `${expect.json.path} is ${JSON.stringify(value)}` };
+ if (expect.json.exists && value === undefined) return { ok: false, detail: `${expect.json.path} is missing` };
+ if ('min' in expect.json && !(Number(value?.length ?? value) >= expect.json.min)) return { ok: false, detail: `${expect.json.path} is ${JSON.stringify(value)}; needs at least ${expect.json.min}` };
+ }
+ return { ok: true, detail: `HTTP ${response.status}, expectations met` };
+}
+
+async function browserProbe(probe) {
+ const { chromium } = await import('playwright');
+ const browser = await chromium.launch();
+ try {
+ const page = await browser.newPage({ userAgent: UA });
+ for (const step of probe.steps || []) {
+ if (step.goto) await page.goto(step.goto, { waitUntil: 'networkidle', timeout: 60_000 });
+ else if (step.click) await page.getByText(step.click, { exact: false }).first().click({ timeout: 20_000 });
+ else if (step.expect) await page.getByText(step.expect, { exact: false }).first().waitFor({ timeout: step.timeoutMs || 45_000 });
+ }
+ return { ok: true, detail: `${(probe.steps || []).length} steps passed` };
+ } catch (err) {
+ return { ok: false, detail: err.message.split('\n')[0] };
+ } finally {
+ await browser.close();
+ }
+}
+
+async function commandProbe(probe, root) {
+ const { spawnSync } = await import('node:child_process');
+ const [command, ...args] = probe.argv || [];
+ if (!command) return { ok: false, detail: 'command probe has no argv' };
+ const run = spawnSync(command, args, { cwd: root, encoding: 'utf8', timeout: probe.timeoutMs || 180_000 });
+ if (run.status === 0) return { ok: true, detail: 'exit 0' };
+ const tail = `${run.stdout || ''}${run.stderr || ''}`.trim().split('\n').slice(-3).join(' | ');
+ return { ok: false, detail: `exit ${run.status ?? run.signal}: ${tail}` };
+}
+
+// `where` is 'review' (every probe) or 'publish' (api probes only).
+export async function probeChecks(item, { root, where = 'review' }) {
+ const checks = [];
+ for (const probe of item.probes || []) {
+ if (where === 'publish' && probe.type !== 'api') continue;
+ const label = probe.name || probe.url || (probe.argv || []).join(' ');
+ try {
+ let result;
+ if (probe.type === 'api') result = await apiProbe(probe);
+ else if (probe.type === 'browser') result = await browserProbe(probe);
+ else if (probe.type === 'command') result = await commandProbe(probe, root);
+ else result = { ok: false, detail: `unknown probe type ${probe.type}` };
+ checks.push({ kind: `probe:${probe.type}`, target: label, ...result });
+ } catch (err) {
+ checks.push({ kind: `probe:${probe.type}`, target: label, ok: false, detail: err.message });
+ }
+ }
+ return checks;
+}
+
export async function verifyItem(item, { root, glossary = [], env = process.env }) {
const texts = itemTexts(item);
const pages = createPageReader();
@@ -222,6 +310,10 @@ export async function verifyItem(item, { root, glossary = [], env = process.env
} finally {
await pages.close();
}
+ if (!item.probes?.length) {
+ checks.push({ kind: 'probe', target: item.id, ok: false, detail: 'no feature probe declared; add one to `probes` that proves the feature works, not just that its page loads' });
+ }
+ checks.push(...(await probeChecks(item, { root, where: 'review' })));
checks.push(...(await linkChecks(texts)));
checks.push(...(await mentionChecks(texts, env)));
checks.push(...(await spellingChecks(item, texts, glossary)));
diff --git a/data/x-content/queue.json b/data/x-content/queue.json
index f8d11896b..0764304ee 100644
--- a/data/x-content/queue.json
+++ b/data/x-content/queue.json
@@ -2,12 +2,26 @@
"version": 2,
"account": "trythreews",
"cadence": {
- "windowMinutes": 90,
+ "windowMinutes": 45,
"minimumMinutesApart": 240,
"dailyCap": 3,
"quietHoursUtc": [
- "05:00",
- "12:00"
+ "02:00",
+ "07:00"
+ ],
+ "slots": [
+ {
+ "tier": 3,
+ "at": "08:00"
+ },
+ {
+ "tier": 1,
+ "at": "16:00"
+ },
+ {
+ "tier": 2,
+ "at": "22:00"
+ }
]
},
"quality": {
@@ -107,7 +121,8 @@
],
"mentions": {
"@solana": "Every Genesis agent is provisioned a custodial Solana wallet (POST /api/agents/:id/wallet/provision); Solana is the platform's home chain."
- }
+ },
+ "tier": 2
},
{
"id": "rig-doctor",
@@ -174,7 +189,8 @@
}
]
}
- ]
+ ],
+ "tier": 2
},
{
"id": "aws-authorization-spine",
@@ -242,7 +258,8 @@
],
"mentions": {
"@awscloud": "The article is published on the AWS Builder Center under the three.ws byline, as an AWS Partner."
- }
+ },
+ "tier": 1
},
{
"id": "three-token-mcp",
@@ -325,7 +342,8 @@
],
"mentions": {
"@solana": "three_burn signs and broadcasts one Solana mainnet transaction (packages/three-token-mcp/src/lib/token.js); $THREE is an SPL token and Solana is the platform's home chain."
- }
+ },
+ "tier": 1
},
{
"id": "forge-max",
@@ -362,7 +380,8 @@
]
}
],
- "mentions": {}
+ "mentions": {},
+ "tier": 2
},
{
"id": "materialize",
@@ -409,7 +428,8 @@
]
}
],
- "mentions": {}
+ "mentions": {},
+ "tier": 2
}
]
}
diff --git a/scripts/x-content.mjs b/scripts/x-content.mjs
index 190bb4a12..1dfd91a3a 100644
--- a/scripts/x-content.mjs
+++ b/scripts/x-content.mjs
@@ -23,14 +23,17 @@ import { spawnSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { QUEUE_PATH, loadQueue, validateQueue } from '../api/_lib/x-content/queue.js';
-import { anchorAssignments, dueAt, pickDue } from '../api/_lib/x-content/schedule.js';
+import { DEFAULT_CADENCE, TIERS, currentSlot, pickDue, slotOpenings, tierOf } from '../api/_lib/x-content/schedule.js';
+import { loadLifts, rankItems } from '../api/_lib/x-content/priority.js';
+import { activeHolds, inventory } from '../api/_lib/x-content/runner.js';
import { runTick } from '../api/_lib/x-content/runner.js';
import { dbStore, memoryStore } from '../api/_lib/x-content/state.js';
import { VIDEO_LIMITS, mediaType, parseFfmpegProbe } from '../api/_lib/x-content/media.js';
import { weightedLength } from '../api/_lib/x-content/quality.js';
-import { approvalProblems, reviewItem } from '../api/_lib/x-content/review.js';
+import { approvalProblems, loadReview, reviewItem } from '../api/_lib/x-content/review.js';
const root = resolve(fileURLToPath(new URL('..', import.meta.url)));
+const DAY = 24 * 60 * 60_000;
function loadEnvFile(path) {
if (!existsSync(path)) return;
@@ -84,24 +87,54 @@ async function plan() {
const s = store();
const state = await s.load();
const { problems } = validateQueue(queue, root, { state });
- const published = new Map((state.published || []).map((row) => [row.id, row]));
- console.log(`ledger: ${s.label}\n`);
- // Without the production seed the times below are the unseeded ones, which
- // are not the times production will use. Say so rather than printing a
- // schedule the operator would trust.
+ const now = Date.now();
+ const cadence = { ...DEFAULT_CADENCE, ...queue.cadence };
const seed = process.env.X_CONTENT_SCHEDULE_SEED || null;
- if (!seed) console.log('note X_CONTENT_SCHEDULE_SEED is not set here, so these are placeholder times; production picks the real ones\n');
- const anchors = anchorAssignments(queue.items, seed);
- const landsAt = (item) => dueAt(item, queue.cadence, { seed, anchorMinutes: anchors.get(item.id) ?? null });
- for (const item of [...queue.items].sort((a, b) => landsAt(a) - landsAt(b))) {
- const row = published.get(item.id);
- const when = row ? `posted ${row.publishedAt}` : `lands ${new Date(landsAt(item)).toISOString()}`;
- const flag = problems[item.id].length ? ` (${problems[item.id].length} problem(s))` : '';
- console.log(`${when.padEnd(33)} ${item.status.padEnd(8)} ${item.kind.padEnd(7)} ${item.lane.padEnd(10)} ${item.pattern.padEnd(10)} ${item.id}${flag}${row ? ` ${row.url}` : ''}`);
+ const published = new Map((state.published || []).map((row) => [row.id, row]));
+ const lifts = loadLifts(root);
+ const reviews = new Map(queue.items.map((item) => [item.id, loadReview(root, item.id)]));
+ const holds = activeHolds(state, queue.items, root, now);
+ console.log(`ledger: ${s.label}${seed ? '' : ' (slot minutes are placeholders here: X_CONTENT_SCHEDULE_SEED only exists in production)'}\n`);
+
+ console.log('Slots (T1 flagship, T2 features, T3 proof of work):');
+ const openings = slotOpenings(now, cadence, seed).filter((slot) => slot.opensAt > now - DAY && slot.opensAt < now + DAY);
+ const openKey = currentSlot(now, cadence, seed).slot?.key;
+ for (const slot of openings) {
+ const used = [...published.values()].find((row) => row.slot === slot.key);
+ const state_ = used ? `used by ${used.id}` : slot.key === openKey ? 'OPEN NOW' : slot.opensAt <= now ? 'passed' : 'upcoming';
+ console.log(` ${new Date(slot.opensAt).toISOString().slice(0, 16)}Z T${slot.tier} ${state_}`);
}
+
+ console.log('\nStock (approved, ready, not held), one slot per tier per day:');
+ for (const row of inventory(queue.items.filter((item) => !problems[item.id].length), state, root, now)) console.log(` T${row.tier}: ${row.days} day(s)${row.low ? ' LOW' : ''}`);
+
+ for (const tier of TIERS) {
+ const waiting = queue.items.filter((item) => tierOf(item) === tier && !published.has(item.id));
+ if (!waiting.length) continue;
+ console.log(`\nT${tier} by priority:`);
+ const ranked = rankItems(waiting, { lifts, published: state.published || [], quality: queue.quality, reviews, now });
+ for (const row of ranked) {
+ const item = row.item;
+ const flags = [
+ item.status !== 'approved' ? item.status : null,
+ problems[item.id].length ? `${problems[item.id].length} problem(s)` : null,
+ holds.has(item.id) ? `held until ${state.holds[item.id].until}: ${state.holds[item.id].reason}` : null,
+ Date.parse(item.notBefore) > now ? `embargoed until ${item.notBefore}` : null,
+ ].filter(Boolean);
+ const parts = Object.entries(row.parts).map(([key, value]) => `${key} ${value > 0 ? '+' : ''}${value}`).join(', ');
+ console.log(` ${String(row.score).padStart(6)} ${item.id.padEnd(26)} ${flags.length ? `[${flags.join('; ')}]` : 'ready'}`);
+ console.log(` ${parts} (predicted ${row.predictedLift}x the account median)`);
+ }
+ for (const item of waiting.filter((item) => !ranked.some((row) => row.item.id === item.id))) console.log(` gone ${item.id.padEnd(26)} [expired ${item.expiresAt}]`);
+ }
+ if (published.size) {
+ console.log('\nSent:');
+ for (const row of published.values()) console.log(` ${row.publishedAt} ${row.id.padEnd(26)} ${row.slot ? `slot ${row.slot} ` : ''}${row.url}`);
+ }
+
const publishable = queue.items.filter((item) => !problems[item.id].length);
- const next = pickDue({ items: publishable, state, cadence: queue.cadence, quality: queue.quality, seed });
- console.log(`\nnow: ${next.item ? `${next.item.id} is due` : next.reason}`);
+ const next = pickDue({ items: publishable, state, now, cadence: queue.cadence, quality: queue.quality, seed, lifts, reviews, exclude: holds });
+ console.log(`\nnow: ${next.item ? `${next.item.id} would fill slot ${next.slot.key} (T${next.tier}${next.filledDown ? `, filling a T${next.slot.tier} slot` : ''}, score ${next.score})` : next.reason}`);
}
async function run() {
@@ -114,11 +147,13 @@ async function run() {
const result = await runTick({ root, store: s, now, dryRun, requestedId: option('id') });
for (const row of result.blocked) console.error(`blocked ${row.id}:\n ${row.problems.join('\n ')}`);
if (result.preview) {
- console.log(`Preview of ${result.preview.id} (${result.preview.kind}), lands ${result.preview.dueAt}:\n`);
+ console.log(`Preview of ${result.preview.id} (${result.preview.kind}), score ${result.preview.score ?? 'n/a'}:\n`);
for (const call of result.preview.calls) console.log(JSON.stringify(call, null, 2));
} else if (result.published) {
+ for (const row of result.held || []) console.log(`held ${row.id} until ${row.hold.until}: ${row.reason}`);
console.log(`Published ${result.published.id}: ${result.published.url}`);
} else {
+ for (const row of result.held || []) console.log(`held ${row.id} until ${row.hold.until}: ${row.reason}`);
console.log(result.reason);
if (result.skipped) process.exit(1);
}
@@ -425,7 +460,7 @@ async function approve() {
continue;
}
item.status = 'approved';
- console.log(`ok ${item.id}: approved, lands on ${item.notBefore.slice(0, 10)} at a moment only the schedule seed decides`);
+ console.log(`ok ${item.id}: approved; it goes out in priority order once ready (embargo ${item.notBefore.slice(0, 10)})`);
}
writeFileSync(resolve(root, QUEUE_PATH), `${JSON.stringify(queue, null, '\t')}\n`);
if (blocked) process.exit(1);
diff --git a/tests/x-content.test.js b/tests/x-content.test.js
index 89b1840e2..bd0eb8196 100644
--- a/tests/x-content.test.js
+++ b/tests/x-content.test.js
@@ -6,7 +6,10 @@ import { join } from 'node:path';
import { copyProblems, weightedLength } from '../api/_lib/x-content/quality.js';
import { attachmentProblems, mediaProblems, parseFfmpegProbe } from '../api/_lib/x-content/media.js';
import { markdownToContentState, attachArticleMedia } from '../api/_lib/x-content/articles.js';
-import { anchorAssignments, dueAt, inQuietHours, jitterMinutes, pickDue } from '../api/_lib/x-content/schedule.js';
+import { currentSlot, inQuietHours, jitterMinutes, pickDue, slotOpenings, tierOrder } from '../api/_lib/x-content/schedule.js';
+import { engagementSignals, loadLifts, rankItems, scoreItem } from '../api/_lib/x-content/priority.js';
+import { activeHolds, inventory, isPostSpecific, placeHold, runTick } from '../api/_lib/x-content/runner.js';
+import { memoryStore } from '../api/_lib/x-content/state.js';
import { validateItem, validateQueue, loadQueue } from '../api/_lib/x-content/queue.js';
import { previewClient, publishItem } from '../api/_lib/x-content/publisher.js';
@@ -122,48 +125,194 @@ describe('articles', () => {
});
describe('schedule', () => {
- const item = (id, over = {}) => ({ id, status: 'approved', kind: 'post', lane: 'community', pattern: 'mechanism', notBefore: '2026-09-17T14:00:00Z', ...over });
- const cadence = { windowMinutes: 60, minimumMinutesApart: 240, dailyCap: 3 };
-
- it('jitters deterministically inside the window', () => {
- expect(jitterMinutes('genesis', 60)).toBe(jitterMinutes('genesis', 60));
- const at = dueAt(item('genesis'), cadence);
- expect(at).toBeGreaterThanOrEqual(Date.parse('2026-09-17T14:00:00Z'));
- expect(at).toBeLessThan(Date.parse('2026-09-17T15:00:00Z'));
- });
+ const cadence = { windowMinutes: 45, minimumMinutesApart: 240, dailyCap: 3, slots: [{ tier: 3, at: '08:00' }, { tier: 1, at: '16:00' }, { tier: 2, at: '22:00' }] };
+ const item = (id, over = {}) => ({ id, status: 'approved', kind: 'post', tier: 2, lane: id, pattern: id, notBefore: '2026-09-17T00:00:00Z', posts: [{ text: HEAD }], ...over });
+ // 16:50 UTC: the 16:00 T1 slot has opened whatever the jitter (under 45 min).
+ const primeTime = Date.parse('2026-09-17T16:50:00Z');
it('handles quiet hours that wrap midnight', () => {
expect(inQuietHours(Date.parse('2026-09-17T23:30:00Z'), ['22:00', '06:00'])).toBe(true);
expect(inQuietHours(Date.parse('2026-09-17T12:00:00Z'), ['22:00', '06:00'])).toBe(false);
});
- it('waits for the jittered moment, then spacing, then the daily cap', () => {
- const now = Date.parse('2026-09-17T16:00:00Z');
- expect(pickDue({ items: [item('a')], state: {}, now: Date.parse('2026-09-17T13:00:00Z'), cadence }).item).toBeNull();
- expect(pickDue({ items: [item('a')], state: {}, now, cadence }).item.id).toBe('a');
- const recent = { published: [{ id: 'z', lane: 'x', pattern: 'y', publishedAt: new Date(now - HOUR).toISOString() }] };
- expect(pickDue({ items: [item('a')], state: recent, now, cadence }).reason).toMatch(/spacing/);
- const capped = { published: [5, 11, 17].map((h, i) => ({ id: `p${i}`, lane: 'x', pattern: 'y', publishedAt: new Date(now - h * HOUR).toISOString() })) };
- expect(pickDue({ items: [item('a')], state: capped, now, cadence }).reason).toMatch(/daily cap/);
+ it('opens three tiered slots a day at jittered minutes only the seed reproduces', () => {
+ const openings = slotOpenings(primeTime, cadence).filter((slot) => slot.key.startsWith('2026-09-17'));
+ expect(openings.map((slot) => slot.tier)).toEqual([3, 1, 2]);
+ for (const [slot, hour] of openings.map((slot, index) => [slot, [8, 16, 22][index]])) {
+ const minutes = (slot.opensAt - Date.parse(`2026-09-17T${String(hour).padStart(2, '0')}:00:00Z`)) / 60_000;
+ expect(minutes).toBeGreaterThanOrEqual(0);
+ expect(minutes).toBeLessThan(45);
+ }
+ const seeded = slotOpenings(primeTime, cadence, 'production-seed');
+ expect(slotOpenings(primeTime, cadence, 'production-seed')).toEqual(seeded);
+ const bySeed = new Set(['s1', 's2', 's3', 's4', 's5'].map((seed) => slotOpenings(primeTime, cadence, seed)[4].opensAt));
+ expect(bySeed.size).toBeGreaterThan(1);
+ expect(jitterMinutes('genesis', 60)).toBe(jitterMinutes('genesis', 60, null));
+ });
+
+ it('keeps the overnight slot open until the next morning slot', () => {
+ expect(currentSlot(Date.parse('2026-09-18T03:00:00Z'), cadence).slot.key).toBe('2026-09-17#2');
+ expect(currentSlot(primeTime, cadence).slot.key).toBe('2026-09-17#1');
+ });
+
+ it('fills a slot from its own tier first, then lower tiers, then a higher tier with surplus', () => {
+ expect(tierOrder(1, new Map())).toEqual([1, 2, 3]);
+ expect(tierOrder(3, new Map([[1, 1], [2, 1]]))).toEqual([3]);
+ expect(tierOrder(3, new Map([[1, 2], [2, 2]]))).toEqual([3, 2, 1]);
+ const items = [item('feature', { tier: 2, priority: 40 }), item('flagship', { tier: 1 })];
+ const prime = pickDue({ items, state: {}, now: primeTime, cadence });
+ expect([prime.item.id, prime.slot.tier, prime.filledDown]).toEqual(['flagship', 1, false]);
+ const noFlagship = pickDue({ items: [items[0]], state: {}, now: primeTime, cadence });
+ expect([noFlagship.item.id, noFlagship.filledDown]).toEqual(['feature', true]);
+ // The last flagship post is kept for prime time, not spent off-peak.
+ const morning = Date.parse('2026-09-17T08:50:00Z');
+ expect(pickDue({ items: [item('flagship', { tier: 1 })], state: {}, now: morning, cadence }).item).toBeNull();
+ });
+
+ it('spends each slot once, and respects embargo, spacing, and the daily cap', () => {
+ const used = { published: [{ id: 'z', slot: '2026-09-17#1', publishedAt: '2026-09-17T16:40:00Z' }] };
+ expect(pickDue({ items: [item('a', { tier: 1 })], state: used, now: primeTime + 5 * HOUR, cadence }).reason).toMatch(/2026-09-17#1.*used|spacing/);
+ expect(pickDue({ items: [item('a', { tier: 1, notBefore: '2026-09-18T00:00:00Z' })], state: {}, now: primeTime, cadence }).reason).toMatch(/embargoed/);
+ const recent = { published: [{ id: 'z', slot: 'other', publishedAt: new Date(primeTime - HOUR).toISOString() }] };
+ expect(pickDue({ items: [item('a', { tier: 1 })], state: recent, now: primeTime, cadence }).reason).toMatch(/spacing/);
+ const capped = { published: [5, 11, 17].map((h, i) => ({ id: `p${i}`, slot: `s${i}`, publishedAt: new Date(primeTime - h * HOUR).toISOString() })) };
+ expect(pickDue({ items: [item('a', { tier: 1 })], state: capped, now: primeTime, cadence }).reason).toMatch(/daily cap/);
+ });
+
+ it('ranks within a tier and falls to the next post when one is held', () => {
+ const items = [item('low', { tier: 1, priority: -10 }), item('high', { tier: 1, priority: 30 }), item('mid', { tier: 1 })];
+ const first = pickDue({ items, state: {}, now: primeTime, cadence });
+ expect(first.ranking.map((row) => row.id)).toEqual(['high', 'mid', 'low']);
+ expect(pickDue({ items, state: {}, now: primeTime, cadence, exclude: new Set(['high']) }).item.id).toBe('mid');
+ expect(pickDue({ items, state: {}, now: primeTime, cadence, exclude: new Set(['high', 'mid', 'low']) }).reason).toMatch(/held this tick/);
+ });
+
+ it('resumes a half-published item ahead of pacing and priority', () => {
+ const state = { published: [{ id: 'p', publishedAt: new Date(primeTime - 10 * 60_000).toISOString() }], inflight: { a: { media: {}, postIds: ['1'] } } };
+ expect(pickDue({ items: [item('a'), item('b', { priority: 50 })], state, now: primeTime, cadence }).resuming).toBe(true);
+ });
+});
+
+describe('priority', () => {
+ const lifts = loadLifts(root);
+ const post = (text, over = {}) => ({ id: 'x', kind: 'post', lane: 'l', pattern: 'p', notBefore: '2026-09-17T00:00:00Z', posts: [{ text, media: [{ path: 'public/x.webp' }] }], ...over });
+
+ it('reads the measured lifts from the engagement report', () => {
+ expect(lifts.get('topic:token').lift).toBeGreaterThan(1);
+ const keys = engagementSignals(post('The $THREE layer, on @awscloud: three.ws/x'), lifts).map((row) => row.key);
+ expect(keys).toEqual(expect.arrayContaining(['format:image', 'format:mention', 'format:cashtag', 'topic:token']));
+ });
+
+ it('shrinks small samples and does not stack overlapping signals', () => {
+ const scored = scoreItem(post('The $THREE layer, on @awscloud, explained for partners: three.ws/x'), { lifts, now: Date.parse('2026-09-17T00:00:00Z') });
+ expect(scored.predictedLift).toBeGreaterThan(1.5);
+ expect(scored.predictedLift).toBeLessThan(10);
+ });
+
+ it('adds owner boost, timeliness, waiting, and review; penalizes repetition; drops expired posts', () => {
+ const now = Date.parse('2026-09-20T00:00:00Z');
+ const base = scoreItem(post('A plain update about avatars: three.ws/x'), { lifts, now });
+ expect(base.parts.waiting).toBe(3);
+ expect(scoreItem(post('A plain update about avatars: three.ws/x', { priority: 20 }), { lifts, now }).score).toBeCloseTo(base.score + 20, 5);
+ expect(scoreItem(post('A plain update about avatars: three.ws/x', { expiresAt: '2026-09-20T12:00:00Z' }), { lifts, now }).parts.timely).toBe(15);
+ expect(scoreItem(post('A plain update about avatars: three.ws/x', { expiresAt: '2026-09-19T00:00:00Z' }), { lifts, now }).expired).toBe(true);
+ const review = { editor: { scores: { a: 5, b: 5, c: 5, d: 5, e: 5, f: 5 } } };
+ expect(scoreItem(post('A plain update about avatars: three.ws/x'), { lifts, now, review }).parts.review).toBe(5);
+ const published = [{ id: 'q', lane: 'l', pattern: 'p', publishedAt: '2026-09-19T00:00:00Z' }];
+ expect(scoreItem(post('A plain update about avatars: three.ws/x'), { lifts, now, published, quality: { maximumSamePatternInARow: 1 } }).parts.variety).toBe(-25);
+ const ranked = rankItems([post('A plain update about avatars: three.ws/x', { id: 'old' }), post('A plain update about avatars: three.ws/x', { id: 'gone', expiresAt: '2026-09-19T00:00:00Z' })], { lifts, now });
+ expect(ranked.map((row) => row.item.id)).toEqual(['old']);
+ });
+});
+
+describe('holds and fall-through', () => {
+ it('tells a post problem from an account or platform problem', () => {
+ expect(isPostSpecific({ code: 403, data: { detail: 'You are not allowed to create a Tweet with duplicate content.' } })).toBe(true);
+ expect(isPostSpecific({ code: 400, message: 'invalid media' })).toBe(true);
+ expect(isPostSpecific({ code: 403, data: { detail: 'forbidden' } })).toBe(false);
+ expect(isPostSpecific({ code: 401 })).toBe(false);
+ expect(isPostSpecific({ code: 429 })).toBe(false);
+ expect(isPostSpecific({ code: 503 })).toBe(false);
+ expect(isPostSpecific(new Error('socket hang up'))).toBe(false);
});
- it('rotates lanes and patterns but never starves a one-lane queue', () => {
- const now = Date.parse('2026-09-17T16:00:00Z');
- const state = { published: [{ id: 'p', lane: 'community', pattern: 'mechanism', publishedAt: new Date(now - 5 * HOUR).toISOString() }] };
- const quality = { maximumSameLaneInARow: 2, maximumSamePatternInARow: 1 };
- const picked = pickDue({ items: [item('same'), item('fresh', { pattern: 'number', notBefore: '2026-09-17T14:30:00Z' })], state, now, cadence, quality });
- expect(picked.item.id).toBe('fresh');
- expect(pickDue({ items: [item('same')], state, now, cadence, quality }).item).toBeNull();
- expect(pickDue({ items: [item('same')], state, now: now + 26 * HOUR, cadence, quality }).item.id).toBe('same');
+ it('backs off a held post and releases it when the post changes', () => {
+ const dir = sandbox();
+ const item = { id: 'a', kind: 'post', posts: [{ text: HEAD }] };
+ const state = {};
+ const now = Date.parse('2026-09-17T00:00:00Z');
+ expect(placeHold(state, item, dir, 'link down', now).until).toBe('2026-09-17T02:00:00.000Z');
+ expect(placeHold(state, item, dir, 'link down', now).until).toBe('2026-09-17T06:00:00.000Z');
+ expect(placeHold(state, item, dir, 'link down', now).until).toBe('2026-09-18T00:00:00.000Z');
+ expect([...activeHolds(state, [item], dir, now)]).toEqual(['a']);
+ expect([...activeHolds(state, [{ ...item, posts: [{ text: `${HEAD} Now fixed.` }] }], dir, now)]).toEqual([]);
+ expect([...activeHolds(state, [item], dir, Date.parse('2026-09-18T00:00:01Z'))]).toEqual([]);
});
- it('resumes a half-published item ahead of pacing', () => {
- const now = Date.parse('2026-09-17T16:00:00Z');
- const state = {
- published: [{ id: 'p', lane: 'x', pattern: 'y', publishedAt: new Date(now - 10 * 60_000).toISOString() }],
- inflight: { a: { media: {}, postIds: ['1'] } },
+ it('counts days of stock per tier and flags the thin ones', () => {
+ const dir = sandbox();
+ const items = [
+ { id: 'a', status: 'approved', tier: 1, kind: 'post', posts: [{ text: 'a' }] },
+ { id: 'b', status: 'approved', tier: 2, kind: 'post', posts: [{ text: 'b' }] },
+ { id: 'c', status: 'approved', tier: 2, kind: 'post', posts: [{ text: 'c' }] },
+ { id: 'd', status: 'approved', tier: 2, kind: 'post', posts: [{ text: 'd' }] },
+ { id: 'e', status: 'review', tier: 3, kind: 'post', posts: [{ text: 'e' }] },
+ ];
+ const stock = inventory(items, { published: [{ id: 'a' }] }, dir);
+ expect(stock).toEqual([{ tier: 1, days: 0, low: true }, { tier: 2, days: 3, low: false }, { tier: 3, days: 0, low: true }]);
+ });
+
+ it('never ends a tick on a failed post: it holds it and publishes the next best', async () => {
+ const { contentHash, reviewPath } = await import('../api/_lib/x-content/review.js');
+ const dir = sandbox();
+ mkdirSync(join(dir, 'data/x-content/reviews'), { recursive: true });
+ const texts = {
+ broken: 'Rig Doctor names the skeleton convention of a humanoid GLB in the browser and lists the joints that stay frozen: three.ws/broken',
+ rejected: 'Genesis turns a sentence or a selfie into a rigged 3D agent with a custodial wallet, a persona, and a voice: three.ws/rejected',
+ working: 'Materialize measures the true solid volume of a repaired mesh and prices a physical print from that measurement: three.ws/working',
+ };
+ const items = Object.entries(texts).map(([id, text], index) => ({
+ id, status: 'approved', kind: 'post', tier: 1, lane: id, pattern: id, priority: 40 - index * 20,
+ notBefore: '2026-09-17T00:00:00Z', textOnly: true, posts: [{ text }],
+ probes: [{ type: 'api', url: `https://three.ws/api/${id}` }],
+ }));
+ for (const item of items) {
+ writeFileSync(join(dir, reviewPath(item.id)), JSON.stringify({ id: item.id, contentHash: contentHash(item, dir), reviewedAt: '2026-09-17T00:00:00Z', passed: true, blockers: [] }));
+ }
+ const cadence = { windowMinutes: 45, minimumMinutesApart: 240, dailyCap: 3, slots: [{ tier: 3, at: '08:00' }, { tier: 1, at: '16:00' }, { tier: 2, at: '22:00' }] };
+ writeFileSync(join(dir, 'data/x-content/queue.json'), JSON.stringify({ account: 'trythreews', cadence, items }));
+
+ const store = memoryStore();
+ const client = previewClient();
+ const tweet = client.tweet;
+ client.tweet = async (payload) => {
+ if (payload.text.includes('three.ws/rejected')) throw Object.assign(new Error('duplicate content'), { code: 403, data: { detail: 'You are not allowed to create a Tweet with duplicate content.' } });
+ return tweet(payload);
};
- expect(pickDue({ items: [item('a')], state, now, cadence }).resuming).toBe(true);
+ const checks = async (item) => (item.id === 'broken' ? [{ kind: 'probe:api', target: 'https://three.ws/api/broken', ok: false, detail: 'HTTP 500' }] : []);
+ const now = Date.parse('2026-09-17T16:50:00Z');
+
+ const result = await runTick({ root: dir, store, dryRun: false, now, client, checks, env: {} });
+ expect(result.blocked).toEqual([]);
+ expect(result.held.map((row) => row.id)).toEqual(['broken', 'rejected']);
+ expect(result.held[0].reason).toMatch(/probe:api .*HTTP 500/);
+ expect(result.held[1].reason).toMatch(/X rejected the post/);
+ expect(result.published.id).toBe('working');
+ expect(result.published.slot).toBe('2026-09-17#1');
+
+ const state = await store.load();
+ expect(Object.keys(state.holds).sort()).toEqual(['broken', 'rejected']);
+ expect(state.inflight.rejected).toBeUndefined();
+
+ // An account-wide failure is not the post's fault: it stops the tick
+ // instead of burning through the queue, and holds nothing new.
+ const outage = previewClient();
+ outage.tweet = async () => {
+ throw Object.assign(new Error('Service Unavailable'), { code: 503 });
+ };
+ const nextSlot = Date.parse('2026-09-17T22:50:00Z');
+ await expect(runTick({ root: dir, store, dryRun: false, now: nextSlot, client: outage, checks: async () => [], env: {} })).rejects.toThrow('Service Unavailable');
+ expect(Object.keys((await store.load()).holds).sort()).toEqual(['broken', 'rejected']);
});
});
@@ -373,39 +522,4 @@ describe('review', () => {
});
});
-describe('schedule seed', () => {
- const day = [
- { id: 'forge-max', notBefore: '2026-10-01T13:00:00Z', windowMinutes: 90 },
- { id: 'materialize', notBefore: '2026-10-01T18:00:00Z', windowMinutes: 90 },
- { id: 'walk-sdk', notBefore: '2026-10-01T23:00:00Z', windowMinutes: 90 },
- ];
-
- it('changes the minute an item lands, and keeps it stable per seed', () => {
- const open = dueAt(day[0], {});
- const secret = dueAt(day[0], {}, { seed: 'production-seed' });
- expect(secret).not.toBe(open);
- expect(dueAt(day[0], {}, { seed: 'production-seed' })).toBe(secret);
- expect(dueAt(day[0], {}, { seed: 'another-seed' })).not.toBe(secret);
- });
-
- it('is a plain hash with no seed, so previews and tests are unchanged', () => {
- expect(jitterMinutes('genesis', 60)).toBe(jitterMinutes('genesis', 60, null));
- expect(jitterMinutes('genesis', 60, 'seed')).not.toBe(jitterMinutes('genesis', 60));
- });
-
- it('deals the day\'s anchors out by seed without leaving the day', () => {
- const assignments = anchorAssignments(day, 'production-seed');
- expect([...assignments.values()].sort((left, right) => left - right)).toEqual([13 * 60, 18 * 60, 23 * 60]);
- expect(anchorAssignments(day, null).size).toBe(0);
- const orders = new Set(['s1', 's2', 's3', 's4', 's5'].map((seed) => [...anchorAssignments(day, seed)].map(([id]) => id).join(',')));
- expect(orders.size).toBeGreaterThan(1);
- });
- it('still respects the cadence when the seed moves an item', () => {
- const approved = day.map((item) => ({ ...item, status: 'approved', lane: 'developer', pattern: 'mechanism' }));
- const now = Date.parse('2026-10-02T04:00:00Z');
- const picked = pickDue({ items: approved, state: {}, now, cadence: { windowMinutes: 90, minimumMinutesApart: 240, dailyCap: 3, quietHoursUtc: ['05:00', '12:00'] }, seed: 'production-seed' });
- expect(approved.map((item) => item.id)).toContain(picked.item.id);
- expect(picked.dueAt).toBeLessThanOrEqual(now);
- });
-});