@yojahny/wp-design-library 0.5.1 → 0.6.0

package/src/cli/motion.mjs

@@ -8,7 +8,8 @@ import yaml from 'js-yaml';
 import sharp from 'sharp';
 import { paths } from '../paths.mjs';
 import { parseEntry } from '../entry.mjs';
-import { isHttpsUrl, localMotionPath, validateMotion } from '../motion.mjs';
+import { localMotionPath, validateMotion } from '../motion.mjs';
+import { objectUrl, r2Config, s3Upload } from '../r2.mjs';
 
 const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function probe(file) {
@@ -90,19 +91,6 @@ export async function prepareMotion({ p = paths(), slug, input, id, title, notes
   } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
 }
 
-export function r2Config(env = process.env) {
-  const required = ['R2_ACCOUNT_ID', 'R2_ACCESS_KEY_ID', 'R2_SECRET_ACCESS_KEY', 'R2_BUCKET', 'R2_PUBLIC_BASE_URL'];
-  const missing = required.filter((k) => !env[k]);
-  if (missing.length) throw new Error(`configure ${missing.join(', ')} locally before publishing`);
-  if (!/^[a-f0-9]{32}$/.test(env.R2_ACCOUNT_ID)) throw new Error('invalid R2_ACCOUNT_ID');
-  if (!isHttpsUrl(env.R2_PUBLIC_BASE_URL)) throw new Error('R2_PUBLIC_BASE_URL must be HTTPS without credentials');
-  const base = new URL(env.R2_PUBLIC_BASE_URL);
-  if (base.search || base.hash) throw new Error('R2_PUBLIC_BASE_URL must not contain a query or fragment');
-  if (base.hostname.endsWith('.r2.dev')) throw new Error('use a production custom domain for R2_PUBLIC_BASE_URL');
-  return { account: env.R2_ACCOUNT_ID, bucket: env.R2_BUCKET, base: base.href.replace(/\/$/, ''),
-    accessKeyId: env.R2_ACCESS_KEY_ID, secretAccessKey: env.R2_SECRET_ACCESS_KEY };
-}
-
 export async function publishMotion({ p = paths(), slug, id, config = r2Config(), upload, fetcher = fetch }) {
   const entry = entryFor(p, slug);
   const errors = validateMotion(entry);
@@ -115,33 +103,25 @@ export async function publishMotion({ p = paths(), slug, id, config = r2Config()
     const body = fs.readFileSync(file);
     if (body.length !== clip.bytes || createHash('sha256').update(body).digest('hex') !== clip.sha256)
       throw new Error(`local video checksum mismatch: ${clip.id}`);
-    return { clip, body, url: `${config.base}/${clip.key}` };
+    return { clip, body, url: objectUrl(config, clip.key) };
   });
-  let client;
-  if (!upload) {
-    const { S3Client, PutObjectCommand } = await import('@aws-sdk/client-s3');
-    client = new S3Client({ region: 'auto', endpoint: `https://${config.account}.r2.cloudflarestorage.com`,
-      credentials: { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey } });
-    upload = (args) => client.send(new PutObjectCommand(args));
-  }
-  try {
-    for (const { clip, body, url } of work) {
-      await upload({ Bucket: config.bucket, Key: clip.key, Body: body, ContentType: 'video/mp4',
-        CacheControl: 'public, max-age=31536000, immutable', Metadata: { sha256: clip.sha256 } });
-      const response = await fetcher(url, { headers: { Range: 'bytes=0-31' }, signal: AbortSignal.timeout(20000) });
-      const type = response.headers.get('content-type')?.split(';')[0];
-      const range = response.headers.get('content-range');
-      if (response.status !== 206 || type !== 'video/mp4' || range !== `bytes 0-31/${clip.bytes}`) {
-        await response.body?.cancel();
-        throw new Error(`uploaded ${clip.id}, but public playback verification failed (HTTP ${response.status}); entry URL was not changed`);
-      }
-      const bytes = Buffer.from(await response.arrayBuffer());
-      if (!bytes.equals(body.subarray(0, 32))) throw new Error(`public video bytes differ for ${clip.id}`);
+  if (!upload) upload = await s3Upload(config);
+  for (const { clip, body, url } of work) {
+    await upload({ Bucket: config.bucket, Key: clip.key, Body: body, ContentType: 'video/mp4',
+      CacheControl: 'public, max-age=31536000, immutable', Metadata: { sha256: clip.sha256 } });
+    const response = await fetcher(url, { headers: { Range: 'bytes=0-31' }, signal: AbortSignal.timeout(20000) });
+    const type = response.headers.get('content-type')?.split(';')[0];
+    const range = response.headers.get('content-range');
+    if (response.status !== 206 || type !== 'video/mp4' || range !== `bytes 0-31/${clip.bytes}`) {
+      await response.body?.cancel();
+      throw new Error(`uploaded ${clip.id}, but public playback verification failed (HTTP ${response.status}); entry URL was not changed`);
     }
-    for (const { clip, url } of work) clip.url = url;
-    writeEntry(entry);
-    return { slug, published: work.map(({ clip, url }) => ({ id: clip.id, url })) };
-  } finally { client?.destroy(); }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (!bytes.equals(body.subarray(0, 32))) throw new Error(`public video bytes differ for ${clip.id}`);
+  }
+  for (const { clip, url } of work) clip.url = url;
+  writeEntry(entry);
+  return { slug, published: work.map(({ clip, url }) => ({ id: clip.id, url })) };
 }
 
 export async function run(args = []) {

package/src/cli/refresh.mjs

@@ -8,13 +8,18 @@ import { loadVocab } from '../vocab.mjs';
 import { buildIndex } from '../index/build.mjs';
 import { measure } from '../ingest/measure.mjs';
 import { refuseUnsafeUrl } from '../ingest/url-guard.mjs';
+import { artifactKey, putAndVerify, r2Config, s3Upload } from '../r2.mjs';
 
-// Re-measures an entry that was drafted from a live URL: rewrites measure.json and
-// the two screenshots, bumps captured.at, and reindexes. Every judgement field
-// (roles, feel, palette, type, motion, body…) is untouched — only measure.json and
-// captured.at change. `transport` is undefined for the CLI, 'http' for the hosted
-// MCP server; the SSRF guard only consults DNS in the latter case.
-export async function refreshEntry({ slug, transport }) {
+const REFRESHED = ['measure.json', 'screen-1440.png', 'screen-390.png'];
+const TYPES = { '.png': 'image/png', '.json': 'application/json' };
+
+// Re-measures an entry that was drafted from a live URL: re-uploads measure.json and
+// the two screenshots, rewrites their artifact records, bumps captured.at, and reindexes.
+// Every judgement field (roles, feel, palette, type, motion, body…) is untouched — only
+// the measurement and captured.at change. `transport` is undefined for the CLI, 'http'
+// for the hosted MCP server; the SSRF guard only consults DNS in the latter case.
+// `measurer` exists so this path can be driven without a browser; nothing but a test passes it.
+export async function refreshEntry({ slug, transport, config, upload, fetcher = fetch, measurer = measure }) {
   const p = paths();
   const dir = path.join(p.entries, slug);
   let e;
@@ -29,13 +34,17 @@ export async function refreshEntry({ slug, transport }) {
   // so it would attribute a fresh measurement to a capture that never made it.
   if ((e.fm.captured?.captures?.length ?? 0) > 1)
     return { refused: `${slug}: refresh cannot update a multi-capture entry; it does not know which capture's slot it would write` };
+  // The records are what a reader resolves, so a refresh with nowhere to write them would leave
+  // the entry naming the OLD objects while the new bytes sat unreferenced.
+  const capture = e.fm.captured?.captures?.[0];
+  if (!capture) return { refused: `${slug}: refresh needs a recorded capture; run the artifacts migration first` };
   const refusal = await refuseUnsafeUrl(url, { transport });
   if (refusal) return { refused: refusal };
 
   const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'wpdl-refresh-'));
   let result;
   try {
-    result = await measure(url, scratch, {});
+    result = await measurer(url, scratch, {});
   } catch (err) {
     fs.rmSync(scratch, { recursive: true, force: true });
     return { refused: `measure failed: ${err.message}` };
@@ -44,16 +53,37 @@ export async function refreshEntry({ slug, transport }) {
     fs.rmSync(scratch, { recursive: true, force: true });
     return { refused: result.error };
   }
-  for (const f of ['measure.json', 'screen-1440.png', 'screen-390.png']) {
-    fs.copyFileSync(path.join(scratch, f), path.join(dir, f));
+  // Upload and re-record before anything is written into the entry. The bytes live in R2 now:
+  // rewriting the three files locally and leaving the records alone left the entry describing the
+  // OLD objects — right key, stale {bytes, sha256} — which every reader verifies the fetch against.
+  // Same key, new digest: the key is stable across re-captures by design.
+  let uploaded;
+  try {
+    config ??= r2Config();
+    if (!upload) upload = await s3Upload(config);
+    uploaded = [];
+    for (const f of REFRESHED) {
+      uploaded.push(await putAndVerify({ config, key: artifactKey(slug, 1, f), body: fs.readFileSync(path.join(scratch, f)),
+        contentType: TYPES[path.extname(f)], upload, fetcher }));
+    }
+  } catch (err) {
+    fs.rmSync(scratch, { recursive: true, force: true });
+    // The loop has no rollback, so an earlier object may already be live in R2 while entry.md
+    // still records the old digest — a cold reader then reports "expected N bytes, got M". Nothing
+    // LOCAL changed and a successful re-run converges the two, so say that rather than "nothing was
+    // changed", which sends the operator looking for corruption instead of re-running.
+    return { refused: `${slug}: upload failed: ${err.message}; nothing local was changed, re-run to converge R2` };
   }
+  for (const f of REFRESHED) fs.copyFileSync(path.join(scratch, f), path.join(dir, f));
   fs.rmSync(scratch, { recursive: true, force: true });
 
+  const keys = new Set(uploaded.map((a) => a.key));
+  capture.artifacts = [...(capture.artifacts ?? []).filter((a) => !keys.has(a?.key)), ...uploaded];
   e.fm.captured.at = new Date().toISOString().slice(0, 10);
   const body = e.body ? `\n${e.body}\n` : '';
   fs.writeFileSync(path.join(dir, 'entry.md'), `---\n${yaml.dump(e.fm, { lineWidth: 120 })}---\n${body}`);
 
-  await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models });
+  await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models, p });
   return { ok: true, slug, captured: e.fm.captured };
 }
 

package/src/cli/save.mjs

@@ -5,7 +5,7 @@ import { saveEntry } from '../ingest/save.mjs';
 
 export async function run(args) {
   const p = paths();
-  const r = await saveEntry({ dir: path.join(p.entries, args[0]), vocab: loadVocab(p.vocab), indexPath: p.index, entriesDir: p.entries, models: p.models });
+  const r = await saveEntry({ dir: path.join(p.entries, args[0]), vocab: loadVocab(p.vocab), indexPath: p.index, entriesDir: p.entries, models: p.models, p });
   if (!r.ok) {
     for (const m of r.errors) process.stderr.write(`${r.slug}: ${m}\n`);
     process.stdout.write(JSON.stringify(r) + '\n');

package/src/cli/serve.mjs

@@ -1,26 +1,46 @@
 async function syncSeed(p) {
   const fs = await import('node:fs');
-  // Every start: copy seed entries the volume does not have yet. Never overwrite —
-  // the volume may hold hosted ingests and edits the image knows nothing about.
+  // Every start: copy seed entries the volume does not have yet, and heal an entry the
+  // volume already has by copying in only the files it is missing (a new required
+  // artifact, or one renamed since the volume was last seeded — e.g. strip.png ->
+  // strip.webp in 0.5.1). Never overwrite a file the volume already has, and never
+  // delete one the seed no longer ships: the volume may hold hosted ingests and operator
+  // edits the image knows nothing about, and a superseded file (the old strip.png) is
+  // inert dead weight, not a landmine — deleting it on every operator's behalf is a
+  // destructive guess this server is not positioned to make.
   if (p.seed !== p.entries && fs.existsSync(p.seed)) {
     const path = await import('node:path');
     fs.mkdirSync(p.entries, { recursive: true });
     let copied = 0;
+    let healed = 0;
     for (const d of fs.readdirSync(p.seed, { withFileTypes: true })) {
       if (!d.isDirectory() || !fs.existsSync(path.join(p.seed, d.name, 'entry.md'))) continue;
+      const src = path.join(p.seed, d.name);
       const dest = path.join(p.entries, d.name);
-      if (fs.existsSync(dest)) continue;
-      fs.cpSync(path.join(p.seed, d.name), dest, { recursive: true });
-      copied++;
+      if (!fs.existsSync(dest)) {
+        fs.cpSync(src, dest, { recursive: true });
+        copied++;
+        continue;
+      }
+      fs.cpSync(src, dest, {
+        recursive: true,
+        filter: (s, dst) => {
+          if (fs.statSync(s).isDirectory()) return true;
+          if (fs.existsSync(dst)) return false;
+          healed++;
+          return true;
+        },
+      });
     }
     process.stderr.write(`seed: copied ${copied} new entries into ${p.entries}\n`);
+    process.stderr.write(`seed: healed ${healed} missing files into existing entries\n`);
   }
 }
 
 async function buildTheIndex(p) {
   const { loadVocab } = await import('../vocab.mjs');
   const { buildIndex } = await import('../index/build.mjs');
-  const r = await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models });
+  const r = await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models, p });
   process.stderr.write(`index: ${r.entries} entries, refused ${r.refused.length}\n`);
   for (const s of r.skipped) process.stderr.write(`embeddings: skipped (${s.reason})\n`);
 }
@@ -48,7 +68,7 @@ export async function run(args) {
     await buildTheIndex(p);
     try {
       const { buildUi } = await import('../ui/build.mjs');
-      await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir: path.join(p.data, 'ui') });
+      await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir: path.join(p.data, 'ui'), p });
     } catch (err) {
       // the gallery is a convenience for a human; the MCP API must not depend on it
       process.stderr.write(`ui: build failed, serving without it: ${err.stack || err}\n`);

package/src/cli/ui.mjs

@@ -8,7 +8,7 @@ export async function run(args = []) {
   const p = paths();
   const outDir = path.join(p.data, 'ui');
   const previewMediaDir = args.includes('--local-media') ? path.join(p.data, '.library', 'media') : undefined;
-  const r = await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir, previewMediaDir });
+  const r = await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir, previewMediaDir, p });
   process.stdout.write(`ui: ${r.entries} entries, ${r.drafts} drafts, built into ${outDir}\n`);
   if (args.includes('--serve')) {
     const port = Number(opt(args, '--port') ?? 4180);

package/src/entry.mjs

@@ -2,12 +2,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
 import { validateMotion } from './motion.mjs';
+import { isArtifactKey } from './r2.mjs';
 import { resolveTerm } from './vocab.mjs';
 
 export const REQUIRED_BLANKS = ['roles', 'feel', 'motion.devices', 'motion.notes', 'type.display', 'type.body', 'body',
   'palette.canvas', 'palette.ink', 'palette.accent'];
 const REQUIRED = ['slug', 'title', 'tier', 'source.kind', 'source.license', 'captured.method', 'captured.at', 'captured.tool',
-  ...REQUIRED_BLANKS];
+  'captured.captures', ...REQUIRED_BLANKS];
 
 export function parseEntry(dir) {
   const file = path.join(dir, 'entry.md');
@@ -58,18 +59,21 @@ export function validateEntry(entry, vocab) {
       errors.push(`licence gate: tier ported is not allowed with source.kind ${fm.source.kind}`);
     if (blank(fm.ported_from)) errors.push('ported_from: required for tier ported');
   }
-  // Every strip a capture names, not only the root one: get_entry hands back `strips` built
-  // from these paths, so a capture claiming an artifact it never wrote would otherwise be
-  // reported ok by `check` and then serve a path to a file that is not there.
-  // The same resolution get_entry uses, basename equality and the conventional fallback
-  // included — validating anything else would pass a path the server never serves, or refuse
-  // one it does.
-  const strips = new Set(['strip.webp']);
+  // An artifact is a record, not a file: {key, bytes, sha256}. The bytes live in R2, so validity is
+  // a question about what the entry claims, and the claim must be strong enough to detect a swap.
   (fm.captured?.captures ?? []).forEach((c, i) => {
-    const named = (c.artifacts ?? []).find((a) => path.basename(String(a)) === 'strip.webp');
-    strips.add(named ?? (i === 0 ? 'strip.webp' : `captures/${i + 1}/strip.webp`));
+    const list = c.artifacts ?? [];
+    if (!list.length) errors.push(`capture ${i + 1}: no artifacts recorded`);
+    for (const a of list) {
+      if (!a || typeof a !== 'object') { errors.push(`capture ${i + 1}: an artifact is not a record`); continue; }
+      // isArtifactKey, not startsWith('entries/'): the shared shape cachePath resolves against, so
+      // a key cannot be valid and indexed while being permanently unresolvable.
+      if (!isArtifactKey(a.key)) errors.push(`capture ${i + 1}: artifact key is missing or not an entries/ key`);
+      if (!Number.isInteger(a.bytes) || a.bytes <= 0) errors.push(`${a.key ?? 'artifact'}: bytes must be a positive integer`);
+      if (typeof a.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(a.sha256)) errors.push(`${a.key ?? 'artifact'}: sha256 must be 64 hex characters`);
+    }
+    if (!list.some((a) => String(a?.key ?? '').endsWith('/strip.webp'))) errors.push(`capture ${i + 1}: no strip recorded`);
   });
-  for (const s of strips) if (!fs.existsSync(path.join(entry.dir, s))) errors.push(`${s}: missing`);
   errors.push(...validateMotion(entry));
   return { ok: errors.length === 0, errors };
 }

package/src/index/build.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { listEntries, parseEntry, validateEntry } from '../entry.mjs';
 import { openIndex } from './query.mjs';
 import { getEmbedder, absentReason } from './embed.mjs';
+import { artifactFile } from '../artifacts.mjs';
 
 const DIR = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA = fs.readFileSync(path.join(DIR, 'schema.sql'), 'utf8');
@@ -19,7 +20,7 @@ function searchableBody(entry) {
     .filter(Boolean).join('\n');
 }
 
-export async function buildIndex({ entriesDir, indexPath, vocab, models }) {
+export async function buildIndex({ entriesDir, indexPath, vocab, models, p }) {
   fs.mkdirSync(path.dirname(indexPath), { recursive: true });
   const tmpPath = indexPath + '.tmp';
   // a killed build can leave a half-written .tmp behind; clear it so the open below always starts fresh
@@ -59,8 +60,17 @@ export async function buildIndex({ entriesDir, indexPath, vocab, models }) {
         const tagsStr = tags.map(([f, t]) => `${f}/${t}`).join(' ');
         const tv = await emb.text(e.fm.title + '\n' + searchableBody(e) + '\n' + tagsStr);
         insVecText.run(e.slug, Buffer.from(tv.buffer));
-        const iv = await emb.image(path.join(e.dir, 'strip.webp'));
-        insVecImage.run(e.slug, Buffer.from(iv.buffer));
+        // An unreachable strip must not abort the whole index: skip this entry's image
+        // vector and keep going, the same degradation buildUi applies to its thumbnail.
+        const strip = (e.fm.captured?.captures?.[0]?.artifacts ?? []).find((a) => a?.key?.endsWith('/strip.webp'));
+        if (strip) {
+          try {
+            const iv = await emb.image(await artifactFile(p, strip));
+            insVecImage.run(e.slug, Buffer.from(iv.buffer));
+          } catch (err) {
+            process.stderr.write(`index: ${e.slug}: image vector skipped: ${err.message}\n`);
+          }
+        }
       }
       n++;
     }

package/src/ingest/agreement.mjs

@@ -2,6 +2,17 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { observedColours } from './observed.mjs';
 
+// An artifact's key is entries/<slug>/<n>/<name>. Capture 1's files live at the entry root and
+// every other capture's under captures/<n>/ (add.mjs's captureDir), so the local path this
+// process can still read is recoverable from the key alone, without add.mjs handing it over
+// separately -- the bytes live in R2 now, but the just-written local copy is what this reads.
+function localArtifactPath(key) {
+  const m = /^entries\/[^/]+\/(\d+)\/(.+)$/.exec(key ?? '');
+  if (!m) return null;
+  const [, n, name] = m;
+  return n === '1' ? name : path.join('captures', n, name);
+}
+
 // Records numbers, never prose. "canvas declared dark-blue but the frames read warm" is an
 // interpretation, and this library's rule is that the session is the tagger — the server
 // never guesses what a design feels like. Here are the declared values and the observed
@@ -21,7 +32,9 @@ export async function computeAgreement({ fm, dir }) {
   const declared = fm.palette;
   if (!declared || Object.values(declared).every((v) => !v)) return null;
 
-  const strip = (frames.artifacts ?? []).find((a) => a.endsWith('strip.webp'));
+  const stripArtifact = (frames.artifacts ?? []).find((a) => a?.key?.endsWith('/strip.webp'));
+  if (!stripArtifact) return null;
+  const strip = localArtifactPath(stripArtifact.key);
   if (!strip) return null;
   const file = path.join(dir, strip);
   if (!fs.existsSync(file)) return null;

package/src/ingest/attach.mjs

@@ -9,17 +9,6 @@ function isBlank(v) {
     || (typeof v === 'object' && Object.values(v).every((x) => x === '' || x == null));
 }
 
-// An entry written before captures[] existed describes one capture in its top-level fields.
-// Synthesise it rather than dropping it, so attaching to an old entry does not lose what it
-// already recorded.
-function existingCaptureFrom(fm) {
-  const c = { method: fm.captured.method, input: fm.source?.url ?? null, artifacts: ['strip.webp'] };
-  if (fm.captured.method !== 'frames') c.artifacts.push('measure.json', 'screen-1440.png', 'screen-390.png');
-  if (fm.media?.frames) c.frames = fm.media.frames;
-  if (fm.media?.duration_ms) c.duration_ms = fm.media.duration_ms;
-  return c;
-}
-
 // `both` keeps its existing meaning — measured AND frames are present — which is what
 // refresh.mjs is really asking when it says "needs measured or both, not frames": is there
 // a URL here I can re-measure.
@@ -35,10 +24,14 @@ export async function attachCapture({ entriesDir, slug, capture, palette, type,
   const e = parseEntry(dir);
   const fm = e.fm;
 
-  // An EMPTY captures[] is treated like an absent one: the entry still describes a capture in
-  // its top-level fields, and nextCaptureIndex counts it as capture 1, so synthesising it here
-  // is what keeps the list and the captures/<n>/ paths agreeing.
-  const captures = fm.captured.captures?.length ? fm.captured.captures : [existingCaptureFrom(fm)];
+  // A pre-captures[] entry has no recorded keys, and inventing one would name an object that was
+  // never uploaded. Migration writes them; this only carries across what is already there. An
+  // EMPTY captures[] is the same case in disguise -- nextCaptureIndex already counts it as
+  // capture 1, so an attach reaching here with nothing recorded has nothing safe to carry forward.
+  if (!fm.captured.captures?.length) {
+    throw new Error(`entry ${slug} has no recorded capture 1 artifacts; run the artifacts migration before attaching`);
+  }
+  const captures = fm.captured.captures;
   captures.push(capture);
 
   // Fill only if blank. palette and type are mechanically derived, but the session may have

package/src/ingest/save.mjs

@@ -1,11 +1,11 @@
 import { parseEntry, validateEntry } from '../entry.mjs';
 import { buildIndex } from '../index/build.mjs';
 
-export async function saveEntry({ dir, vocab, indexPath, entriesDir, models }) {
+export async function saveEntry({ dir, vocab, indexPath, entriesDir, models, p }) {
   const e = parseEntry(dir);
   const r = validateEntry(e, vocab);
   if (!r.ok) return { ok: false, slug: e.slug, errors: r.errors, refused: r.errors.join('; ') };
   // Phase 1: a full rebuild is cheap; single-entry upsert arrives with the vector arms.
-  await buildIndex({ entriesDir, indexPath, vocab, models });
+  await buildIndex({ entriesDir, indexPath, vocab, models, p });
   return { ok: true, slug: e.slug, errors: [] };
 }

package/src/mcp/tools.mjs

@@ -6,6 +6,8 @@ import { resolveTerm } from '../vocab.mjs';
 import { refuseUnsafeUrl } from '../ingest/url-guard.mjs';
 import { getMotion, motionFrame } from '../motion.mjs';
 import { parseEntry } from '../entry.mjs';
+import { artifactFile } from '../artifacts.mjs';
+import { readConfig, objectUrl } from '../r2.mjs';
 
 const facetList = z.array(z.string()).optional();
 const FILTER_FACETS = ['role', 'feel', 'motion', 'source'];
@@ -78,30 +80,40 @@ export function makeTools(ctx) {
     },
     {
       name: 'get_entry',
-      description: "Return one entry: frontmatter, prose body, and the path to its strip.webp. detail:'summary' returns the body's first paragraph instead of the whole body — enough to decide whether to fetch the rest.",
+      description: "Return one entry: frontmatter, prose body, and its strip.webp as both a cached local path (strip/strips) and a public URL (strip_url/strip_urls); either may be null if the object cannot be resolved right now. detail:'summary' returns the body's first paragraph instead of the whole body — enough to decide whether to fetch the rest.",
       schema: z.object({
         slug: z.string(),
         detail: z.enum(['summary', 'full']).default('full'),
       }),
-      handler: withDb((db, { slug, detail }) => {
+      handler: withDb(async (db, { slug, detail }) => {
         const e = getEntry(db, slug);
         if (!e) return { refused: `no entry with slug ${slug}` };
         // Every capture's strip, one slot per capture, capture 1 first — strips[i] always
-        // describes captures[i]. `strip` is derived from e.dir alone, independently of what
-        // a capture's own artifacts happen to list, so a capture that names no strip falls
-        // back to its conventional path (entry root for capture 1, captures/<n>/strip.webp
-        // after) instead of being silently dropped: that keeps strips[0] === strip true by
-        // construction, not by writer discipline. Match on basename exactly, not by suffix —
-        // a suffix match would let an unrelated file like extra-strip.webp count as a strip.
+        // describes captures[i]. An artifact is a {key, bytes, sha256} record now (Task 2),
+        // matched by its key ending in "/strip.webp" so an unrelated file like
+        // extra-strip.webp is never picked up by a loose suffix match. validateEntry
+        // requires every capture to record one, so an indexed entry always has one to
+        // resolve — but the bytes live in R2, and R2 may be unreachable (not yet migrated,
+        // or simply down). One unreachable object must not refuse the whole entry: it
+        // resolves to null, the same degradation buildUi and buildIndex apply, while
+        // strip_url — built from the key alone, no fetch required — is still returned.
         const captures = e.fm?.captured?.captures ?? [];
-        const conventionalStrip = (i) => (i === 0 ? 'strip.webp' : `captures/${i + 1}/strip.webp`);
-        const strips = captures.length
-          ? captures.map((c, i) => {
-              const named = (c.artifacts ?? []).find((a) => path.basename(a) === 'strip.webp');
-              return `${e.dir}/${named ?? conventionalStrip(i)}`;
-            })
-          : [`${e.dir}/strip.webp`];
-        const out = { ...e, strip: `${e.dir}/strip.webp`, strips };
+        let config = null;
+        // readConfig, not r2Config: building a public URL (and fetching one) needs the base URL,
+        // not a write secret. get_entry never writes.
+        try { config = readConfig(); } catch { config = null; }
+        const strips = [];
+        const stripUrls = [];
+        for (const c of captures) {
+          const artifact = (c.artifacts ?? []).find((a) => a?.key?.endsWith('/strip.webp'));
+          if (!artifact) { strips.push(null); stripUrls.push(null); continue; }
+          let local = null;
+          try { local = await artifactFile(ctx.paths, artifact); } catch { local = null; }
+          strips.push(local);
+          stripUrls.push(config ? objectUrl(config, artifact.key) : null);
+        }
+        // strips[0] === strip holds by construction: strip is never computed separately.
+        const out = { ...e, strip: strips[0] ?? null, strips, strip_url: stripUrls[0] ?? null, strip_urls: stripUrls };
         if (detail !== 'summary') return out;
         // The first PROSE paragraph. Bodies conventionally open with `## What it does`,
         // so splitting on the first blank line alone would return a bare heading, which
@@ -238,7 +250,7 @@ export function makeTools(ctx) {
       schema: z.object({ slug: z.string().regex(/^[a-z0-9-]+$/) }),
       handler: async ({ slug }) => {
         const { saveEntry } = await import('../ingest/save.mjs');
-        return saveEntry({ dir: path.join(ctx.paths.entries, slug), vocab: ctx.vocab, indexPath: ctx.paths.index, entriesDir: ctx.paths.entries, models: ctx.paths.models });
+        return saveEntry({ dir: path.join(ctx.paths.entries, slug), vocab: ctx.vocab, indexPath: ctx.paths.index, entriesDir: ctx.paths.entries, models: ctx.paths.models, p: ctx.paths });
       },
     },
   ];

package/src/r2.mjs

@@ -0,0 +1,95 @@
+// The only file that knows R2 exists. Everything else speaks in keys.
+import { createHash } from 'node:crypto';
+
+export function isHttpsUrl(value) {
+  try { const u = new URL(value); return u.protocol === 'https:' && !u.username && !u.password; } catch { return false; }
+}
+
+export function r2Config(env = process.env) {
+  const required = ['R2_ACCOUNT_ID', 'R2_ACCESS_KEY_ID', 'R2_SECRET_ACCESS_KEY', 'R2_BUCKET', 'R2_PUBLIC_BASE_URL'];
+  const missing = required.filter((k) => !env[k]);
+  if (missing.length) throw new Error(`configure ${missing.join(', ')} locally before publishing`);
+  if (!/^[a-f0-9]{32}$/.test(env.R2_ACCOUNT_ID)) throw new Error('invalid R2_ACCOUNT_ID');
+  if (!isHttpsUrl(env.R2_PUBLIC_BASE_URL)) throw new Error('R2_PUBLIC_BASE_URL must be HTTPS without credentials');
+  const base = new URL(env.R2_PUBLIC_BASE_URL);
+  if (base.search || base.hash) throw new Error('R2_PUBLIC_BASE_URL must not contain a query or fragment');
+  if (base.hostname.endsWith('.r2.dev')) throw new Error('use a production custom domain for R2_PUBLIC_BASE_URL');
+  return { account: env.R2_ACCOUNT_ID, bucket: env.R2_BUCKET, base: base.href.replace(/\/$/, ''),
+    accessKeyId: env.R2_ACCESS_KEY_ID, secretAccessKey: env.R2_SECRET_ACCESS_KEY };
+}
+
+// Reading a public object needs the base URL and nothing else: a range GET of
+// entries/<slug>/<n>/<name> is unauthenticated. The hosted server only ever reads, so requiring
+// R2_SECRET_ACCESS_KEY there would make a write credential the price of rendering a thumbnail —
+// and the failure is soft (a gallery with no images), so nobody would notice the misconfiguration.
+export function readConfig(env = process.env) {
+  if (!env.R2_PUBLIC_BASE_URL) throw new Error('configure R2_PUBLIC_BASE_URL to read artifacts from R2');
+  if (!isHttpsUrl(env.R2_PUBLIC_BASE_URL)) throw new Error('R2_PUBLIC_BASE_URL must be HTTPS without credentials');
+  const base = new URL(env.R2_PUBLIC_BASE_URL);
+  if (base.search || base.hash) throw new Error('R2_PUBLIC_BASE_URL must not contain a query or fragment');
+  return { base: base.href.replace(/\/$/, '') };
+}
+
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const NAME = /^[a-z0-9][a-z0-9.-]*$/;
+
+// The one definition of what artifactKey can produce, so a key that validates is a key that
+// resolves. validateEntry used to accept anything starting with `entries/`, which let
+// `entries/../../etc/strip.webp` be valid, indexed and permanently unresolvable — and get_entry
+// handed that to an agent as a URL an HTTP client normalizes to a different prefix of the bucket.
+export function isArtifactKey(key) {
+  return typeof key === 'string' && !key.includes('..')
+    && /^entries\/[a-z0-9-]+\/[0-9]+\/[a-z0-9][a-z0-9.-]*$/.test(key);
+}
+
+// entries/<slug>/<capture>/<name>. Recomputable from the entry that owns it, so a key is never
+// a fact you have to store twice.
+export function artifactKey(slug, captureIndex, name) {
+  if (!SLUG.test(slug)) throw new Error('invalid slug for an artifact key');
+  if (!Number.isInteger(captureIndex) || captureIndex < 1) throw new Error('capture index must be a positive integer');
+  if (!NAME.test(name) || name.includes('..')) throw new Error('invalid artifact name');
+  return `entries/${slug}/${captureIndex}/${name}`;
+}
+
+export function objectUrl(config, key) {
+  return `${config.base}/${key}`;
+}
+
+export function sha256(body) {
+  return createHash('sha256').update(body).digest('hex');
+}
+
+export async function s3Upload(config) {
+  const { S3Client, PutObjectCommand } = await import('@aws-sdk/client-s3');
+  const client = new S3Client({ region: 'auto', endpoint: `https://${config.account}.r2.cloudflarestorage.com`,
+    credentials: { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey } });
+  return (args) => client.send(new PutObjectCommand(args));
+}
+
+// Upload, then prove the object is publicly readable and byte-identical before any caller records
+// the key. motion.mjs established this order: an entry must never name an object nobody can read.
+//
+// `immutable` is NOT carried over from motion.mjs with it. That key embeds the digest
+// (motion/<slug>/<id>-<sha256[0:16]>.mp4) so it never names two different bodies; an artifact key
+// is entries/<slug>/<n>/<name>, stable across re-captures on purpose — get_entry hands those keys
+// to agents and the migration's value is that a key is predictable from a slug — so `add --force`
+// PUTs different bytes at the same key. Take the header, not the key: putting a digest in the key
+// would make every re-capture a fresh key and re-open the orphan problem. It also breaks the
+// verification below, which range-fetches through R2_PUBLIC_BASE_URL (the edge): under `immutable`
+// it can compare the new body against a cached old object and throw `public bytes differ` AFTER
+// the object was overwritten. The cost is a re-capture taking up to max-age to reach the edge.
+export async function putAndVerify({ config, key, body, contentType, upload, fetcher = fetch }) {
+  const digest = sha256(body);
+  await upload({ Bucket: config.bucket, Key: key, Body: body, ContentType: contentType,
+    CacheControl: 'public, max-age=300', Metadata: { sha256: digest } });
+  const url = objectUrl(config, key);
+  const response = await fetcher(url, { headers: { Range: 'bytes=0-31' }, signal: AbortSignal.timeout(20000) });
+  const range = response.headers.get('content-range');
+  if (response.status !== 206 || range !== `bytes 0-31/${body.length}`) {
+    await response.body?.cancel();
+    throw new Error(`uploaded ${key}, but public verification failed (HTTP ${response.status}); nothing was recorded`);
+  }
+  const head = Buffer.from(await response.arrayBuffer());
+  if (!head.equals(body.subarray(0, 32))) throw new Error(`public bytes differ for ${key}`);
+  return { key, bytes: body.length, sha256: digest };
+}