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.

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.js
index 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.js
index 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, re
quality: 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.js
index 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.md
index 5898b5645..94c021fb8 100644
--- a/docs/announcement-factory.md
+++ b/docs/announcement-factory.md
@@ -160,6 +160,46 @@ npm run x:content -- review --status review
npm 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.
+
## Credentials
The 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. Everything
planning, 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.md
index 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:** never
Ranked 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.md
index 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:** never
Ranked 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.md
index 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.mjs
index 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.js
index 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);
+ });
+});