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(announce): plan each surface into the slot its own tier owns

nirholas94e11c2b1ae3
diff --git a/api/_lib/announce/brief.js b/api/_lib/announce/brief.js
index 66037e809..4b91c1b94 100644
--- a/api/_lib/announce/brief.js
+++ b/api/_lib/announce/brief.js
@@ -190,6 +190,7 @@ export async function buildBrief(slot, { root, ledgerEntry = {}, pages = null, s
route: slot.url,
lane: slot.lane,
pattern: slot.pattern,
+ tier: slot.tier,
notBefore: slot.notBefore,
surface: {
kind: slot.kind,
diff --git a/api/_lib/announce/draft.js b/api/_lib/announce/draft.js
index 56099ad32..f04b1e128 100644
--- a/api/_lib/announce/draft.js
+++ b/api/_lib/announce/draft.js
@@ -24,6 +24,7 @@ import { callModelChain } from '../x-content/llm.js';
import { copyProblems, copySimilarity, weightedLength } from '../x-content/quality.js';
import { claimProblems, languageProblems } from '../x-content/editorial.js';
import { loadHistory } from '../x-content/queue.js';
+import { TIERS } from './plan.js';
export const TARGET_BAND = [100, 179];
@@ -115,6 +116,10 @@ export function itemFor(brief, draft, { mediaPath, probe = null, status = 'draft
id: brief.id,
status,
kind: 'post',
+ // The queue refuses an item without a tier, and the publisher gives each
+ // tier a slot of its own, so the plan's tier travels with the item
+ // rather than being re-guessed here.
+ tier: TIERS.includes(Number(brief.tier)) ? Number(brief.tier) : 2,
lane: brief.lane,
pattern: brief.pattern,
notBefore: brief.notBefore,
diff --git a/api/_lib/announce/plan.js b/api/_lib/announce/plan.js
index f5fa689ba..de1e55f38 100644
--- a/api/_lib/announce/plan.js
+++ b/api/_lib/announce/plan.js
@@ -13,8 +13,10 @@
// Three constraints shape it, and all three come from files that already exist
// rather than from taste:
//
-// cadence data/x-content/queue.json: daily cap, minimum gap, quiet hours.
-// Slot times are derived from those, never hardcoded.
+// cadence data/x-content/queue.json: the slot table when it declares one
+// (each slot is a time and the tier that owns it), otherwise the
+// daily cap, minimum gap and quiet hours it is derived from.
+// Slot times are read or derived, never hardcoded.
// rotation the same queue's quality block: no more than N of the same
// lane in a row, no more than M of the same pattern. The
// scheduler in api/_lib/x-content/schedule.js enforces this at
@@ -28,6 +30,9 @@
const MINUTE = 60_000;
+// The queue's tiers, best first. Mirrors api/_lib/x-content/schedule.js.
+export const TIERS = [1, 2, 3];
+
// Audience lane. Rotation only cares that neighbours differ, but the lane also
// decides who the pack is written for, so it is derived from where the surface
// lives rather than assigned round-robin.
@@ -116,6 +121,37 @@ export function slotTimes(cadence = {}) {
return times.length ? times : ['13:00'];
}
+// The same day as the publisher sees it: a list of slots, each with the tier
+// that owns it. api/_lib/x-content/schedule.js reads `cadence.slots` and fills
+// each one from its own tier first, so a calendar that ignored the table would
+// promise times the publisher never uses and tiers it never fills.
+export function slotTable(cadence = {}) {
+ const declared = Array.isArray(cadence.slots) ? cadence.slots : [];
+ const table = declared
+ .filter((slot) => slot && typeof slot.at === 'string' && TIERS.includes(Number(slot.tier)))
+ .map((slot) => ({ at: slot.at, tier: Number(slot.tier) }))
+ .sort((left, right) => minutesOf(left.at) - minutesOf(right.at));
+ if (table.length) return table;
+ // No table: fall back to the derived times, every one of them a feature
+ // slot, which is the tier the publisher itself defaults an item to.
+ return slotTimes(cadence).map((at) => ({ at, tier: 2 }));
+}
+
+// Which tier a surface belongs in, using the queue's own definitions: 1 is a
+// flagship (a $THREE utility or a partner we can truthfully tag), 3 is proof of
+// work (a package, worker or service, whose frame is a typeset card rather than
+// a route), and 2 is a shipped feature with a page behind it.
+export function tierFor(entry, lane = laneFor(entry)) {
+ if (!entry.url) return 3;
+ if (lane === 'token' || entry.partner) return 1;
+ return 2;
+}
+
+// The order a slot is filled from: its own tier, then the lower tiers, then the
+// higher ones. It mirrors tierOrder() in the publisher, so the calendar degrades
+// the same way the live scheduler does when one tier runs out of stock.
+const tierOrderFor = (slotTier) => [...TIERS.filter((tier) => tier >= slotTier), ...TIERS.filter((tier) => tier < slotTier).reverse()];
+
function runLength(list, field, value) {
let run = 0;
for (let index = list.length - 1; index >= 0; index--) {
@@ -129,18 +165,30 @@ function runLength(list, field, value) {
// previous lane or pattern too many times yields to the next one that fits,
// and a candidate whose preferred pattern is blocked falls through its own
// ranked list before it gives up its slot.
-export function sequence(entries, { maximumSameLaneInARow = 2, maximumSamePatternInARow = 1 } = {}) {
+export function sequence(entries, { maximumSameLaneInARow = 2, maximumSamePatternInARow = 1 } = {}, { tierAt = null } = {}) {
const pool = entries.map((entry) => ({
entry,
lane: laneFor(entry),
patterns: patternsFor(entry),
+ tier: tierFor(entry),
}));
const placed = [];
while (pool.length) {
let chosen = -1;
let pattern = null;
+ // Which of the remaining surfaces this position may take. With a slot
+ // table, a position belongs to a tier: the candidates are that tier's,
+ // and only when it is out of stock does the next tier get the slot,
+ // which is how the publisher fills down too. Rotation then chooses
+ // inside that group, so tier discipline never costs variety.
+ const wantedTier = tierAt ? tierAt(placed.length) : null;
+ const group = wantedTier
+ ? (tierOrderFor(wantedTier).map((tier) => pool.filter((candidate) => candidate.tier === tier)).find((list) => list.length) || pool)
+ : pool;
+ const eligible = new Set(group);
for (let index = 0; index < pool.length; index++) {
const candidate = pool[index];
+ if (!eligible.has(candidate)) continue;
if (runLength(placed, 'lane', candidate.lane) >= maximumSameLaneInARow) continue;
pattern = candidate.patterns.find((option) => runLength(placed, 'pattern', option) < maximumSamePatternInARow) || null;
if (pattern) {
@@ -156,25 +204,31 @@ export function sequence(entries, { maximumSameLaneInARow = 2, maximumSamePatter
// takes the best candidate that can at least change the post's shape.
if (chosen < 0) {
const lastPattern = placed[placed.length - 1]?.pattern;
- chosen = pool.findIndex((candidate) => candidate.patterns.some((option) => option !== lastPattern));
+ chosen = pool.findIndex((candidate) => eligible.has(candidate) && candidate.patterns.some((option) => option !== lastPattern));
+ if (chosen < 0) chosen = pool.findIndex((candidate) => eligible.has(candidate));
if (chosen < 0) chosen = 0;
pattern = pool[chosen].patterns.find((option) => option !== lastPattern) || pool[chosen].patterns[0];
}
const [candidate] = pool.splice(chosen, 1);
- placed.push({ entry: candidate.entry, lane: candidate.lane, pattern });
+ placed.push({ entry: candidate.entry, lane: candidate.lane, pattern, tier: candidate.tier });
}
return placed;
}
export function buildPlan(entries, { cadence = {}, quality = {}, start, cryptoPaths = new Set(), perDay = null } = {}) {
- const times = slotTimes(cadence).slice(0, perDay || Infinity);
+ const table = slotTable(cadence).slice(0, perDay || Infinity);
+ const times = table.map((slot) => slot.at);
const day0 = Date.parse(`${start}T00:00:00Z`);
if (!Number.isFinite(day0)) throw new Error(`start must be a YYYY-MM-DD date, got ${start}`);
- const ordered = sequence(entries, quality);
+ // Each position is sequenced against the tier of the slot it will land in,
+ // so a flagship takes the flagship slot instead of whichever minute came
+ // next in the list, while lane and shape still rotate inside that tier.
+ const ordered = sequence(entries, quality, { tierAt: (position) => table[position % table.length].tier });
+
const slots = ordered.map((row, index) => {
- const day = Math.floor(index / times.length);
- const time = times[index % times.length];
+ const day = Math.floor(index / table.length);
+ const { at: time, tier: slotTier } = table[index % table.length];
const notBefore = new Date(day0 + day * 1440 * MINUTE + minutesOf(time) * MINUTE).toISOString().replace('.000Z', 'Z');
const slug = slugFor(row.entry.key);
const gated = Boolean(row.entry.url && cryptoPaths.has(row.entry.url));
@@ -187,6 +241,8 @@ export function buildPlan(entries, { cadence = {}, quality = {}, start, cryptoPa
url: row.entry.url || null,
lane: row.lane,
pattern: row.pattern,
+ tier: row.tier,
+ slotTier,
notBefore,
windowMinutes: Number(cadence.windowMinutes ?? 90),
batch: Math.floor(day / 7) + 1,
@@ -208,6 +264,7 @@ export function buildPlan(entries, { cadence = {}, quality = {}, start, cryptoPa
totals: {
slots: slots.length,
gated: slots.filter((slot) => slot.mediaGate).length,
+ byTier: Object.fromEntries(TIERS.map((tier) => [tier, slots.filter((slot) => slot.tier === tier).length])),
byLane: Object.fromEntries(LANES.map((lane) => [lane, slots.filter((slot) => slot.lane === lane).length])),
byPattern: Object.fromEntries(PATTERNS.map((pattern) => [pattern, slots.filter((slot) => slot.pattern === pattern).length])),
},
diff --git a/scripts/announce-kit.mjs b/scripts/announce-kit.mjs
index 8289a9326..e94ba4fb1 100644
--- a/scripts/announce-kit.mjs
+++ b/scripts/announce-kit.mjs
@@ -115,6 +115,7 @@ const wanted = (() => {
url: entry.url || null,
lane: queued.lane,
pattern: queued.pattern,
+ tier: queued.tier,
notBefore: queued.notBefore,
windowMinutes: queued.windowMinutes || plan.slots[0]?.windowMinutes || 90,
batch: 0,
@@ -285,7 +286,7 @@ try {
results.push({
id: slot.id,
state: problems.length ? 'packed, item incomplete' : 'packed, awaiting review',
- detail: problems.length ? problems[0] : `${slot.notBefore.slice(0, 16).replace('T', ' ')} UTC, ${brief.lane}/${brief.pattern}`,
+ detail: problems.length ? problems[0] : `${slot.notBefore.slice(0, 16).replace('T', ' ')} UTC, T${item.tier} ${brief.lane}/${brief.pattern}`,
});
}
} finally {
diff --git a/scripts/announce-plan.mjs b/scripts/announce-plan.mjs
index 1e3424b1d..0a7552e36 100644
--- a/scripts/announce-plan.mjs
+++ b/scripts/announce-plan.mjs
@@ -59,6 +59,7 @@ function calendarMarkdown() {
'',
`**${plan.totals.slots} surfaces that have never been announced**, ${plan.perDay} a day at ${plan.times.join(', ')} UTC, starting ${plan.start}: ${plan.days} days of posting, ${batches} weekly batches. ${plan.totals.gated} of them capture media from a surface that renders live third-party market data, so those frames need owner approval before they can be committed.`,
'',
+ `Tier mix: ${Object.entries(plan.totals.byTier).map(([tier, count]) => `T${tier} ${count}`).join(', ')}. Each slot is owned by one tier, and a surface is planned into the slot its own tier owns, so the flagship slot gets flagship material and a package announcement takes the proof-of-work slot.`,
`Lane mix: ${Object.entries(plan.totals.byLane).map(([lane, count]) => `${lane} ${count}`).join(', ')}.`,
`Pattern mix: ${Object.entries(plan.totals.byPattern).map(([pattern, count]) => `${pattern} ${count}`).join(', ')}.`,
'',
@@ -82,11 +83,11 @@ function calendarMarkdown() {
batch = slot.batch;
const rows = plan.slots.filter((row) => row.batch === batch);
lines.push('', `## Batch ${batch}: ${rows[0].notBefore.slice(0, 10)} to ${rows[rows.length - 1].notBefore.slice(0, 10)}`, '');
- lines.push('| Slot (UTC) | Surface | Lane | Pattern | Shot | Gate |');
- lines.push('|---|---|---|---|---|---|');
+ lines.push('| Slot (UTC) | Tier | Surface | Lane | Pattern | Shot | Gate |');
+ lines.push('|---|---|---|---|---|---|---|');
}
lines.push(
- `| ${slot.notBefore.slice(0, 16).replace('T', ' ')} | \`${slot.key}\` | ${slot.lane} | ${slot.pattern} | \`${slot.shot}\`${slot.motion ? ' (motion)' : ''} | ${slot.mediaGate || ''} |`,
+ `| ${slot.notBefore.slice(0, 16).replace('T', ' ')} | T${slot.tier}${slot.tier === slot.slotTier ? '' : ` (in the T${slot.slotTier} slot)`} | \`${slot.key}\` | ${slot.lane} | ${slot.pattern} | \`${slot.shot}\`${slot.motion ? ' (motion)' : ''} | ${slot.mediaGate || ''} |`,
);
}
return `${lines.join('\n')}\n`;
@@ -109,12 +110,12 @@ console.log(
`${plan.totals.slots} unannounced surfaces, ${plan.perDay}/day at ${plan.times.join(', ')} UTC from ${plan.start}: ${plan.days} days, ${Math.ceil(plan.days / 7)} batches.`,
);
console.log(
- `lanes ${Object.entries(plan.totals.byLane).map(([lane, count]) => `${lane}:${count}`).join(' ')} patterns ${Object.entries(plan.totals.byPattern).map(([pattern, count]) => `${pattern}:${count}`).join(' ')} owner-gated media ${plan.totals.gated} deferred ${plan.deferred?.length || 0}\n`,
+ `tiers ${Object.entries(plan.totals.byTier).map(([tier, count]) => `T${tier}:${count}`).join(' ')} lanes ${Object.entries(plan.totals.byLane).map(([lane, count]) => `${lane}:${count}`).join(' ')} patterns ${Object.entries(plan.totals.byPattern).map(([pattern, count]) => `${pattern}:${count}`).join(' ')} owner-gated media ${plan.totals.gated} deferred ${plan.deferred?.length || 0}\n`,
);
-console.log(`${'when'.padEnd(17)} ${'surface'.padEnd(32)} ${'lane'.padEnd(10)} ${'pattern'.padEnd(11)} gate`);
+console.log(`${'when'.padEnd(17)} ${'tier'.padEnd(5)} ${'surface'.padEnd(32)} ${'lane'.padEnd(10)} ${'pattern'.padEnd(11)} gate`);
for (const slot of rows) {
console.log(
- `${slot.notBefore.slice(0, 16).replace('T', ' ').padEnd(17)} ${slot.key.padEnd(32)} ${slot.lane.padEnd(10)} ${slot.pattern.padEnd(11)} ${slot.mediaGate || ''}`,
+ `${slot.notBefore.slice(0, 16).replace('T', ' ').padEnd(17)} ${`T${slot.tier}`.padEnd(5)} ${slot.key.padEnd(32)} ${slot.lane.padEnd(10)} ${slot.pattern.padEnd(11)} ${slot.mediaGate || ''}`,
);
}
if (!only) console.log(`\n... ${Math.max(0, plan.totals.slots - rows.length)} more. Full calendar: npm run announce:plan -- --write`);
diff --git a/tests/announce-factory.test.js b/tests/announce-factory.test.js
index 9599e1192..fcacecff0 100644
--- a/tests/announce-factory.test.js
+++ b/tests/announce-factory.test.js
@@ -1,7 +1,7 @@
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
-import { buildPlan, laneFor, patternsFor, sequence, slotTimes, slugFor } from '../api/_lib/announce/plan.js';
+import { buildPlan, laneFor, patternsFor, sequence, slotTable, slotTimes, slugFor, tierFor } from '../api/_lib/announce/plan.js';
import { harvestFacts, quotableLines } from '../api/_lib/announce/brief.js';
import { draftFindings, itemFor, parseDraft } from '../api/_lib/announce/draft.js';
import { cardFacts, cardHtml, commandFrom, namesFrom } from '../api/_lib/announce/card.js';
@@ -32,6 +32,59 @@ describe('plan', () => {
}
});
+ it('takes the slot table the publisher obeys, in time order, when the cadence declares one', () => {
+ expect(slotTable({ ...CADENCE, slots: [{ tier: 1, at: '20:00' }, { tier: 3, at: '04:00' }, { tier: 2, at: '12:00' }] })).toEqual([
+ { at: '04:00', tier: 3 },
+ { at: '12:00', tier: 2 },
+ { at: '20:00', tier: 1 },
+ ]);
+ // No table: the derived times, each one a feature slot, which is what
+ // the publisher defaults an untier'd item to.
+ expect(slotTable(CADENCE)).toEqual([
+ { at: '13:00', tier: 2 },
+ { at: '18:00', tier: 2 },
+ { at: '23:00', tier: 2 },
+ ]);
+ });
+
+ it('tiers a surface by what it is: flagship, feature, or proof of work', () => {
+ expect(tierFor(entry('/vaults', { section: 'crypto' }))).toBe(1);
+ expect(tierFor(entry('/agi', { partner: '@ibm' }))).toBe(1);
+ expect(tierFor(entry('/mocap-studio', { section: 'labs' }))).toBe(2);
+ expect(tierFor(entry('@three-ws/alerts-mcp', { kind: 'package', section: 'package' }))).toBe(3);
+ });
+
+ it('plans each surface into the slot its own tier owns', () => {
+ const plan = buildPlan(
+ [
+ entry('/vaults', { section: 'crypto' }),
+ entry('@three-ws/alerts-mcp', { kind: 'package', section: 'package' }),
+ entry('/mocap-studio', { section: 'labs' }),
+ ],
+ {
+ cadence: { ...CADENCE, slots: [{ tier: 3, at: '04:00' }, { tier: 2, at: '12:00' }, { tier: 1, at: '20:00' }] },
+ quality: QUALITY,
+ start: '2026-10-01',
+ },
+ );
+ expect(plan.times).toEqual(['04:00', '12:00', '20:00']);
+ expect(plan.slots.map((slot) => [slot.key, slot.tier, slot.notBefore])).toEqual([
+ ['@three-ws/alerts-mcp', 3, '2026-10-01T04:00:00Z'],
+ ['/mocap-studio', 2, '2026-10-01T12:00:00Z'],
+ ['/vaults', 1, '2026-10-01T20:00:00Z'],
+ ]);
+ expect(plan.totals.byTier).toEqual({ 1: 1, 2: 1, 3: 1 });
+ });
+
+ it('gives a slot to the next tier down when its own tier is out of stock', () => {
+ const plan = buildPlan([entry('/vaults', { section: 'crypto' }), entry('/genome', { section: 'crypto' })], {
+ cadence: { ...CADENCE, slots: [{ tier: 3, at: '04:00' }, { tier: 1, at: '20:00' }] },
+ quality: QUALITY,
+ start: '2026-10-01',
+ });
+ expect(plan.slots.map((slot) => [slot.tier, slot.slotTier])).toEqual([[1, 3], [1, 1]]);
+ });
+
it('drops a slot whose jitter window would run into quiet hours', () => {
expect(slotTimes({ ...CADENCE, quietHoursUtc: ['00:00', '12:00'], dailyCap: 3, minimumMinutesApart: 600 })).toEqual(['13:00']);
});
@@ -118,6 +171,7 @@ const BRIEF = {
route: '/forge-max',
lane: 'developer',
pattern: 'number',
+ tier: 2,
notBefore: '2026-10-01T13:00:00Z',
surface: { kind: 'page', section: 'build', title: 'Forge Max', description: 'The maximum-quality lane.' },
evidenceCandidates: [{ type: 'page', url: 'https://three.ws/forge-max', contains: 'The highest-quality lane: 200k-poly geometry, 4K PBR textures.' }],
@@ -170,6 +224,11 @@ describe('draft', () => {
expect(item.posts[0].textFrom).toBe('docs/announcements/forge-max.post.txt');
expect(item.posts[0].media[0].alt).toBe(GOOD.alt);
expect(item.notBefore).toBe(BRIEF.notBefore);
+ // The queue validator refuses an item with no tier, so the plan's tier
+ // has to survive the trip through the brief.
+ expect(item.tier).toBe(2);
+ expect(itemFor({ ...BRIEF, tier: undefined }, GOOD, { mediaPath: 'x.webp' }).tier).toBe(2);
+ expect(itemFor({ ...BRIEF, tier: 1 }, GOOD, { mediaPath: 'x.webp' }).tier).toBe(1);
});
});