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
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.jsindex 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, sroute: 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.jsindex 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 = 'draftid: 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.jsindex 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, cryptoPaurl: 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, cryptoPatotals: {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.mjsindex 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.mjsindex 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.jsindex 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);});});