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
fix(x-content): make the posting minute unknowable from the public repo
nirholas53f2a200f5a7
diff --git a/api/_lib/announce/kit.js b/api/_lib/announce/kit.jsindex b5f768f58..8c73f00d4 100644--- a/api/_lib/announce/kit.js+++ b/api/_lib/announce/kit.js@@ -67,7 +67,7 @@ export function renderPack({ brief, draft, slot, ledgerEntry = {}, rank = null,push(`# Announcement pack: ${draft.headline || ledgerEntry.title || id}`,'',- `**Surface:** [\`${brief.key}\`](${url}) · **Stage:** drafted · **Slot:** ${slot.notBefore.slice(0, 16).replace('T', ' ')} UTC · **Announced externally:** never`,+ `**Surface:** [\`${brief.key}\`](${url}) · **Stage:** drafted · **Slot:** ${slot.notBefore.slice(0, 10)} · **Announced externally:** never`,'',`${rank && total ? `Ranked ${rank} of ${total} never-announced surfaces by \`npm run announce:rank\`` : 'From the announcement backlog'}${ledgerEntry.score ? ` (score ${ledgerEntry.score})` : ''}. ${model && !/^hand/i.test(model) ? `Drafted on ${model} and packed by \`npm run announce:kit\`` : 'Drafted by hand and packed by `npm run announce:kit`'}, from the evidence brief in [\`data/announce-plan/briefs/${id}.json\`](../../data/announce-plan/briefs/${id}.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.`,'',@@ -78,7 +78,7 @@ export function renderPack({ brief, draft, slot, ledgerEntry = {}, rank = null,'| Field | Value |','|---|---|',`| Pack id | \`${id}\` |`,- `| Publish slot | ${slot.notBefore.slice(0, 16).replace('T', ' ')} UTC, jittered inside ${slot.windowMinutes} minutes by the scheduler |`,+ `| Publish slot | ${slot.notBefore.slice(0, 10)}. The minute is decided at send time from the production schedule seed, so it is not knowable from this repository |`,`| Lane and pattern | ${brief.lane} / ${brief.pattern} |`,`| Audience | ${LANE_AUDIENCE[brief.lane] || LANE_AUDIENCE.community} |`,'| Primary channel | X, @trythreews, through the reviewed content queue |',diff --git a/api/_lib/x-content/runner.js b/api/_lib/x-content/runner.jsindex 6947f039f..feb40873e 100644--- a/api/_lib/x-content/runner.js+++ b/api/_lib/x-content/runner.js@@ -26,6 +26,8 @@ export async function runTick({ root, store, now = Date.now(), dryRun = true, requality: queue.quality,requestedId,anyStatus: dryRun,+ // The queue is public; the minute an item lands is not. See schedule.js.+ seed: env.X_CONTENT_SCHEDULE_SEED || null,});if (!decision.item) return { published: null, reason: decision.reason, blocked };diff --git a/api/_lib/x-content/schedule.js b/api/_lib/x-content/schedule.jsindex 8902f98a4..05383a81e 100644--- a/api/_lib/x-content/schedule.js+++ b/api/_lib/x-content/schedule.js@@ -12,7 +12,7 @@// Pure: no I/O, so the rules are unit-tested and the CLI shows the same// decision the cron will make.-import { createHash } from 'node:crypto';+import { createHash, createHmac } from 'node:crypto';const MINUTE = 60_000;const DAY = 24 * 60 * MINUTE;@@ -24,14 +24,61 @@ export const DEFAULT_CADENCE = {quietHoursUtc: null,};-export function jitterMinutes(id, windowMinutes) {- const digest = createHash('sha256').update(String(id)).digest();+// ── Why the schedule carries a secret ────────────────────────────────────────+// The queue is a committed file in a public repository, so the day an item+// posts is public by construction. Without a seed the minute is public too:+// the jitter was a plain hash of the item's id, which anyone holding the repo+// can compute, and an announcement whose exact minute is knowable days ahead+// can be camped, front-run, or pre-empted.+//+// `X_CONTENT_SCHEDULE_SEED` (production env, never committed) turns that hash+// into an HMAC. Same properties for us (stable per item, so a preview, a retry+// and the real tick all agree), no properties at all for anyone without the+// seed. It also deals out the day's anchor times, so which of the day's posts+// goes first is unknowable as well. With no seed configured the behaviour is+// exactly what it was, which keeps local previews and the tests honest.++export function jitterMinutes(id, windowMinutes, seed = null) {+ const digest = seed+ ? createHmac('sha256', String(seed)).update(String(id)).digest()+ : createHash('sha256').update(String(id)).digest();return digest.readUInt32BE(0) % Math.max(1, windowMinutes);}-export function dueAt(item, cadence = DEFAULT_CADENCE) {+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);- return Date.parse(item.notBefore) + jitterMinutes(item.id, window) * MINUTE;+ 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) {@@ -55,16 +102,18 @@ function trailingRun(published, field, value) {// `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 }) {+export function pickDue({ items, state, now = Date.now(), cadence: rawCadence = {}, quality = {}, requestedId = null, anyStatus = false, seed = null }) {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 candidates = items+ const eligible = items.filter((item) => (item.status === 'approved' || (anyStatus && requestedId)) && !publishedIds.has(item.id))- .filter((item) => !requestedId || item.id === requestedId)- .map((item) => ({ item, at: dueAt(item, cadence) }))+ .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) {diff --git a/docs/announcement-factory.md b/docs/announcement-factory.mdindex 5898b5645..94c021fb8 100644--- a/docs/announcement-factory.md+++ b/docs/announcement-factory.md@@ -160,6 +160,46 @@ npm run x:content -- review --status reviewnpm run x:content -- approve --status review```+## The schedule is public, the timing is not++This repository is public, so the queue is public: anyone can read which surface is announced on+which day, and read the copy before it goes out. That is tolerable for what this backlog contains,+because every one of these surfaces already shipped and is already live on three.ws. There is no+unreleased information in a pack. What is worth protecting is the *moment*, which is what lets+somebody camp a post, reply-farm it, pre-empt it, or trade the attention spike around a token-lane+announcement.++Until 2026-09-17 the moment was public too. The jitter was `sha256(item id)`, and the id is in the+committed queue, so the exact minute of every queued post was computable by anyone, days ahead.++It now comes from `X_CONTENT_SCHEDULE_SEED`, an HMAC key that lives only in the production+environment:++| Knowable from the repository | Decided by the seed |+|---|---|+| The day an item is eligible | The minute inside its window |+| That the account posts up to three times a day in a handful of anchor windows | Which of the day's items takes which anchor, and therefore the order |++The seed keeps every property the cron needs: stable per item, so a preview, a retry and the real+tick all agree, and a half-sent thread resumes at the same moment it was going to use. With no seed+configured the behaviour is exactly what it always was, so local previews and the tests are+unaffected; `npm run x:content -- plan` says out loud when it is printing unseeded placeholder+times rather than the real schedule.++```bash+# Generate one and put it on the service (once):+openssl rand -hex 32+gcloud run services update three-ws-api --region us-central1 --update-env-vars X_CONTENT_SCHEDULE_SEED=<value>+```++Rotating the seed reshuffles every unpublished item's minute and order, which is a reasonable thing+to do and costs nothing. It does not move anything to a different day.++**What this does not hide** is the copy itself. If an announcement is genuinely market-moving+(a launch, a partnership, a listing), it should not sit in a public queue for a week beforehand+whatever the timing defence says: post it from a pack that is written and committed the same day,+or hold it out of this pipeline entirely.+## CredentialsThe factory needs a model for the drafting step and the editorial review. It uses the shared chain@@ -169,6 +209,9 @@ On a workstation, `gcloud auth application-default login` is enough. Everythingplanning, briefs, media capture, packing, the whole gate) runs with no model at all:`npm run announce:kit -- --brief-only` is the offline half.+`X_CONTENT_SCHEDULE_SEED` is separate and belongs on the Cloud Run service, not in a checkout: see+the section above.+## Where things live| Path | Role |diff --git a/docs/announcements/forge-max.md b/docs/announcements/forge-max.mdindex 3ba7b6045..65f45289a 100644--- a/docs/announcements/forge-max.md+++ b/docs/announcements/forge-max.md@@ -1,6 +1,6 @@# Announcement pack: The Forge, opened at its top tier-**Surface:** [`/forge-max`](https://three.ws/forge-max) · **Stage:** drafted · **Slot:** 2026-09-18 23:00 UTC · **Announced externally:** never+**Surface:** [`/forge-max`](https://three.ws/forge-max) · **Stage:** drafted · **Slot:** 2026-09-18 · **Announced externally:** neverRanked 19 of 322 never-announced surfaces by `npm run announce:rank` (score 75). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/forge-max.json`](../../data/announce-plan/briefs/forge-max.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.@@ -11,7 +11,7 @@ Ranked 19 of 322 never-announced surfaces by `npm run announce:rank` (score 75).| Field | Value ||---|---|| Pack id | `forge-max` |-| Publish slot | 2026-09-18 23:00 UTC, jittered inside 90 minutes by the scheduler |+| Publish slot | 2026-09-18. The minute is decided at send time from the production schedule seed, so it is not knowable from this repository || Lane and pattern | developer / number || Audience | Engineers who will read the code || Primary channel | X, @trythreews, through the reviewed content queue |diff --git a/docs/announcements/materialize.md b/docs/announcements/materialize.mdindex d270dedca..75d5570ac 100644--- a/docs/announcements/materialize.md+++ b/docs/announcements/materialize.md@@ -1,6 +1,6 @@# Announcement pack: A print priced from the mesh, not from a guess-**Surface:** [`/materialize`](https://three.ws/materialize) · **Stage:** drafted · **Slot:** 2026-09-19 23:00 UTC · **Announced externally:** never+**Surface:** [`/materialize`](https://three.ws/materialize) · **Stage:** drafted · **Slot:** 2026-09-19 · **Announced externally:** neverRanked 22 of 322 never-announced surfaces by `npm run announce:rank` (score 73). Drafted by hand and packed by `npm run announce:kit`, from the evidence brief in [`data/announce-plan/briefs/materialize.json`](../../data/announce-plan/briefs/materialize.json), against [the announcement voice](../announce-voice.md). Every fact below comes from that brief; nothing in this pack was written from memory.@@ -11,7 +11,7 @@ Ranked 22 of 322 never-announced surfaces by `npm run announce:rank` (score 73).| Field | Value ||---|---|| Pack id | `materialize` |-| Publish slot | 2026-09-19 23:00 UTC, jittered inside 90 minutes by the scheduler |+| Publish slot | 2026-09-19. The minute is decided at send time from the production schedule seed, so it is not knowable from this repository || Lane and pattern | developer / mechanism || Audience | Engineers who will read the code || Primary channel | X, @trythreews, through the reviewed content queue |diff --git a/docs/x-content-pipeline.md b/docs/x-content-pipeline.mdindex 08eab07b3..390fdd08c 100644--- a/docs/x-content-pipeline.md+++ b/docs/x-content-pipeline.md@@ -26,6 +26,7 @@ pipeline, enforced before anything is sent:| Hype copy | [api/_lib/x-content/quality.js](../api/_lib/x-content/quality.js) rejects launch openers ("Introducing", "We're excited"), hype vocabulary, hashtags, emoji, stacked exclamation marks, all-caps shouting, and en or em dashes. || Repeats | A head that reads too much like another queued item, or like anything @trythreews already posted (the scraped archive in `data/archives/` plus everything this pipeline published), is rejected. || Clockwork timing | Each item lands at a stable, jittered minute inside a window after its `notBefore`, with a minimum gap, a daily cap, and quiet hours. |+| A schedule anyone can read off the repository | The jitter is an HMAC under `X_CONTENT_SCHEDULE_SEED` (production only), which also deals out the day's anchor times. The day is public; the minute and the order are not. Unset, it falls back to the old public hash, and `plan` says so. || Same format on repeat | Lane (audience) and pattern (post shape) rotate. A due item waits if it would repeat the previous lane or pattern too many times, unless it has been waiting a full day. || Retry double-posts | Every created media id, post id, and Article id is written to the ledger the moment X returns it. A crash mid-thread resumes at the next unposted reply. |diff --git a/scripts/x-content.mjs b/scripts/x-content.mjsindex d85068eff..190bb4a12 100644--- a/scripts/x-content.mjs+++ b/scripts/x-content.mjs@@ -23,7 +23,7 @@ import { spawnSync } from 'node:child_process';import { fileURLToPath } from 'node:url';import { QUEUE_PATH, loadQueue, validateQueue } from '../api/_lib/x-content/queue.js';-import { dueAt, pickDue } from '../api/_lib/x-content/schedule.js';+import { anchorAssignments, dueAt, pickDue } from '../api/_lib/x-content/schedule.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';@@ -86,14 +86,21 @@ async function plan() {const { problems } = validateQueue(queue, root, { state });const published = new Map((state.published || []).map((row) => [row.id, row]));console.log(`ledger: ${s.label}\n`);- for (const item of [...queue.items].sort((a, b) => dueAt(a, queue.cadence) - dueAt(b, queue.cadence))) {+ // 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 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(dueAt(item, queue.cadence)).toISOString()}`;+ 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 publishable = queue.items.filter((item) => !problems[item.id].length);- const next = pickDue({ items: publishable, state, cadence: queue.cadence, quality: queue.quality });+ 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}`);}@@ -418,7 +425,7 @@ async function approve() {continue;}item.status = 'approved';- console.log(`ok ${item.id}: approved for ${dueAt(item, queue.cadence) ? new Date(dueAt(item, queue.cadence)).toISOString() : item.notBefore}`);+ console.log(`ok ${item.id}: approved, lands on ${item.notBefore.slice(0, 10)} at a moment only the schedule seed decides`);}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.jsindex b4089a162..d6c37ae97 100644--- a/tests/x-content.test.js+++ b/tests/x-content.test.js@@ -6,7 +6,7 @@ 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 { dueAt, inQuietHours, jitterMinutes, pickDue } from '../api/_lib/x-content/schedule.js';+import { anchorAssignments, dueAt, inQuietHours, jitterMinutes, pickDue } from '../api/_lib/x-content/schedule.js';import { validateItem, validateQueue, loadQueue } from '../api/_lib/x-content/queue.js';import { previewClient, publishItem } from '../api/_lib/x-content/publisher.js';@@ -363,3 +363,40 @@ describe('review', () => {expect(() => parseReview('no json here')).toThrow(/no JSON/);});});++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);+ });+});