@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/mflux-provider.test.mjs

@@ -0,0 +1,174 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mfluxImageGenerate } from "./mflux-provider.mjs";
+
+// 40GB clears the 32GB klein tier and the 8GB schnell tier below it; the 64GB
+// qwen tier stays out of reach. Two rungs is what makes demotion observable.
+const bothTiersSpecs = { availableRamMB: 40000, gpu: { present: true } };
+const SNAPSHOT = "/tmp/hf-snapshot";
+
+// exec stub covering all three shells-out mflux does: the PATH probe, the
+// idempotent `hf download`, and the generate itself.
+function stubExec({ failGenerateFor = [], failWhichFor = [] } = {}) {
+  const calls = [];
+  const exec = (...call) => {
+    calls.push(call);
+    const [bin, argv] = call;
+    if (bin === "which") {
+      if (failWhichFor.includes(argv[0])) throw new Error("not found");
+      return "";
+    }
+    if (bin === "hf") return `Fetching 6 files...\n${SNAPSHOT}\n`;
+    if (failGenerateFor.some((id) => argv.join(" ").includes(id))) {
+      const err = new Error("exit 1");
+      err.stderr = "mlx.core.metal: out of memory";
+      throw err;
+    }
+    return "";
+  };
+  return { calls, exec };
+}
+
+const generateCalls = (calls) =>
+  calls.filter(([bin]) => bin !== "which" && bin !== "hf").map(([, argv]) => argv.join(" "));
+
+test("no local model fits: falls through to the upsell without shelling out", async () => {
+  const { calls, exec } = stubExec();
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: { availableRamMB: 100, gpu: { present: true } } },
+    exec,
+    () => true,
+  );
+
+  assert.equal(result, null);
+  assert.deepEqual(calls, []);
+});
+
+test("a top tier that cannot run demotes to the next fitting tier", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+  );
+
+  assert.ok(result, "the schnell tier still produced an image");
+  assert.equal(result.metadata.provider, "mflux.flux-schnell-mflux-q4");
+  const generated = generateCalls(calls);
+  assert.equal(generated.length, 2, "klein attempted first, then schnell");
+  assert.match(generated[0], /flux2-klein-4b/);
+  assert.match(generated[1], /--model schnell/);
+  assert.equal(errors.length, 1, "the demotion is reported, not silent");
+  assert.match(errors[0], /flux2-klein-mflux-q4\) failed/);
+});
+
+test("a snapshot that will not resolve demotes rather than failing outright", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const calls = [];
+  const exec = (...call) => {
+    calls.push(call);
+    const [bin, argv] = call;
+    if (bin === "which") return "";
+    // klein's weights won't download; schnell's do
+    if (bin === "hf") {
+      if (argv[1].includes("FLUX.2-klein")) throw new Error("403 Forbidden");
+      return `${SNAPSHOT}\n`;
+    }
+    return "";
+  };
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+  );
+
+  assert.ok(result, "demoted past the ungettable weights");
+  assert.equal(result.metadata.provider, "mflux.flux-schnell-mflux-q4");
+  assert.equal(errors.length, 1);
+  assert.match(errors[0], /hf download failed/);
+});
+
+test("runner missing from PATH reports the install hint per tier and returns null", async (t) => {
+  const errors = [];
+  t.mock.method(console, "error", (message) => errors.push(message));
+  const { exec } = stubExec({ failWhichFor: ["mflux-generate"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+  );
+
+  assert.equal(result, null);
+  assert.equal(errors.length, 2, "both fitting tiers reported");
+  assert.match(errors[0], /uv pip install mflux/);
+  // each hint states that tier's download cost before the user commits
+  assert.match(errors[0], /GB of weights to/);
+  assert.match(errors[1], /GB of weights to/);
+});
+
+// Same per-attempt temp path, same orphaning risk as the LTX provider: a
+// partial png from a failed tier must not survive a lower tier succeeding.
+const outputOf = (argv) => argv[argv.indexOf("--output") + 1];
+const attemptedOutputs = (calls) =>
+  calls.filter(([bin]) => bin !== "which" && bin !== "hf").map(([, argv]) => outputOf(argv));
+
+test("a failed attempt's partial output is discarded before demoting", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const unlinked = [];
+  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.ok(result, "the schnell tier still produced an image");
+  assert.deepEqual(unlinked, [attemptedOutputs(calls)[0]], "the failed klein partial is removed");
+});
+
+test("every tier failing discards every partial, one per attempt", async (t) => {
+  t.mock.method(console, "error", () => {});
+  const unlinked = [];
+  const { calls, exec } = stubExec({ failGenerateFor: ["flux2-klein-4b", "schnell"] });
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.equal(result, null);
+  assert.deepEqual(unlinked, attemptedOutputs(calls), "nothing is left behind");
+});
+
+test("a successful generation is never discarded", async () => {
+  const unlinked = [];
+  const { exec } = stubExec();
+
+  const result = await mfluxImageGenerate(
+    "a red bicycle",
+    { specs: bothTiersSpecs },
+    exec,
+    () => true,
+    (path) => unlinked.push(path),
+  );
+
+  assert.ok(result);
+  assert.deepEqual(unlinked, [], "the returned artifact must survive");
+});

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/misses.mjs

@@ -0,0 +1,49 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { globalMediaDir } from "./media-home.mjs";
+
+const MISSES_FILE = "misses.jsonl";
+
+function missesPath() {
+  return join(globalMediaDir(), MISSES_FILE);
+}
+
+export function recordMiss({ type, intent, provider_override, local_only }) {
+  try {
+    const path = missesPath();
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(
+      path,
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        type,
+        intent,
+        provider_override: !!provider_override,
+        local_only: !!local_only,
+      }) + "\n",
+    );
+  } catch {
+    // local miss logging is best-effort; never surface into resolve
+  }
+}
+
+export function readMisses() {
+  const p = missesPath();
+  try {
+    if (!existsSync(p)) return [];
+    const raw = readFileSync(p, "utf8");
+    const records = [];
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        records.push(JSON.parse(trimmed));
+      } catch {
+        // skip malformed local lines, don't crash stats
+      }
+    }
+    return records;
+  } catch {
+    return [];
+  }
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/misses.test.mjs

@@ -0,0 +1,89 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readMisses, recordMiss } from "./misses.mjs";
+
+function sandbox() {
+  const root = mkdtempSync(join(tmpdir(), "mu-misses-"));
+  const home = join(root, "home");
+  mkdirSync(home, { recursive: true });
+  process.env.HYPERFRAMES_MEDIA_HOME = home;
+  return { root, home };
+}
+
+function restoreEnv(saved) {
+  for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+  Object.assign(process.env, saved);
+}
+
+test("recordMiss appends a well-formed local miss", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    recordMiss({ type: "bgm", intent: "moody synth pulse", provider_override: true });
+    const misses = readMisses();
+    assert.equal(misses.length, 1);
+    assert.equal(misses[0].type, "bgm");
+    assert.equal(misses[0].intent, "moody synth pulse");
+    assert.equal(misses[0].provider_override, true);
+    assert.equal(misses[0].local_only, false);
+    assert.ok(!Number.isNaN(Date.parse(misses[0].ts)));
+
+    const raw = readFileSync(join(home, ".media/misses.jsonl"), "utf8");
+    assert.match(raw, /moody synth pulse/);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("recordMiss swallows filesystem failures", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    writeFileSync(join(home, ".media"), "not a directory");
+    assert.doesNotThrow(() =>
+      recordMiss({ type: "image", intent: "unwritable", local_only: true }),
+    );
+    assert.equal(existsSync(join(home, ".media/misses.jsonl")), false);
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("recordMiss stays best-effort when the media home cannot be resolved", () => {
+  const savedEnv = { ...process.env };
+  delete process.env.HYPERFRAMES_MEDIA_HOME;
+  process.env.HYPERFRAMES_MEDIA_HOME_REQUIRED = "1";
+  try {
+    assert.doesNotThrow(() => recordMiss({ type: "sfx", intent: "no home", local_only: true }));
+  } finally {
+    restoreEnv(savedEnv);
+  }
+});
+
+test("readMisses skips corrupt lines", () => {
+  const savedEnv = { ...process.env };
+  const { root, home } = sandbox();
+  try {
+    mkdirSync(join(home, ".media"), { recursive: true });
+    writeFileSync(
+      join(home, ".media/misses.jsonl"),
+      [
+        JSON.stringify({ ts: "2026-07-09T00:00:00.000Z", type: "bgm", intent: "one" }),
+        "{not json",
+        JSON.stringify({ ts: "2026-07-09T00:00:01.000Z", type: "sfx", intent: "two" }),
+      ].join("\n"),
+    );
+    assert.deepEqual(
+      readMisses().map((miss) => miss.intent),
+      ["one", "two"],
+    );
+  } finally {
+    restoreEnv(savedEnv);
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/npx-sync.mjs

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
+
+// Sync-spawn analog of the audio engine's spawnP, for execFileSync call sites
+// that must hard-fail (rather than fall through to another provider) when npx
+// cannot be resolved. On Windows a bare "npx" is npx.cmd, which
+// execFileSync/spawnSync cannot exec (spawnSync npx ENOENT) —
+// resolveSpawnCommand reroutes it through node + npx-cli.js, no shell:true.
+//
+// `platform`/`env`/`pathExists` params (defaulting to the real values) exist
+// so tests can exercise the win32 branch without mocking node:child_process
+// (its ESM exports are non-configurable) — same idiom as spawnP and
+// localTtsGenerate.
+export function resolveNpxInvocation(
+  argv,
+  opts,
+  platform = process.platform,
+  env = process.env,
+  pathExists = existsSync,
+) {
+  const resolved = resolveSpawnCommand("npx", argv, opts, platform, env, pathExists);
+  if (!resolved) {
+    // npx-on-win32 with no resolvable npx-cli.js — same terminal condition
+    // spawnP warns about, surfaced as a throw for callers with no fallback.
+    throw new Error(
+      "cannot run npx on Windows: npm's npx-cli.js was not found " +
+        "(install npm with Node, or run via npx/npm run so npm_execpath is set)",
+    );
+  }
+  return resolved;
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/npx-sync.test.mjs

@@ -0,0 +1,50 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveNpxInvocation } from "./npx-sync.mjs";
+
+// Coverage parity with tts-local-provider.test.mjs, for the whisper.cpp
+// fallback's call-site shape (transcribe.mjs runWhisper): the same three
+// branches, but with the hard-fail contract — no fallback provider exists,
+// so an unresolvable npx must throw actionably instead of returning null.
+
+const envWithNpxCli = {
+  npm_execpath: "C:/Program Files/nodejs/node_modules/npm/bin/npm-cli.js",
+  npm_node_execpath: "C:/Program Files/nodejs/node.exe",
+};
+const npxCliPath = "C:/Program Files/nodejs/node_modules/npm/bin/npx-cli.js";
+const pathExists = (path) => path === npxCliPath;
+
+const WHISPER_ARGV = ["hyperframes", "transcribe", "C:\\media\\input.wav", "--dir", "C:\\work"];
+const WHISPER_OPTS = { stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 };
+
+test("win32: routes the whisper fallback through node + npx-cli, never bare npx", () => {
+  const resolved = resolveNpxInvocation(
+    WHISPER_ARGV,
+    WHISPER_OPTS,
+    "win32",
+    envWithNpxCli,
+    pathExists,
+  );
+
+  assert.equal(resolved.cmd, envWithNpxCli.npm_node_execpath);
+  assert.equal(resolved.args[0], npxCliPath);
+  assert.deepEqual(resolved.args.slice(1, 3), ["hyperframes", "transcribe"]);
+  // execFileSync options survive the rerouting (the timeout bounds the
+  // whisper build/model download; the pipes surface its errors).
+  assert.deepEqual(resolved.opts.stdio, ["ignore", "pipe", "pipe"]);
+  assert.equal(resolved.opts.timeout, 1_800_000);
+});
+
+test("win32 without a resolvable npx-cli: throws the actionable install hint", () => {
+  assert.throws(
+    () => resolveNpxInvocation(WHISPER_ARGV, WHISPER_OPTS, "win32", {}, () => false),
+    /npx-cli\.js was not found/,
+  );
+});
+
+test("non-win32: spawns plain npx unchanged", () => {
+  const resolved = resolveNpxInvocation(WHISPER_ARGV, WHISPER_OPTS, "darwin", {}, () => false);
+
+  assert.equal(resolved.cmd, "npx");
+  assert.deepEqual(resolved.args, WHISPER_ARGV);
+});

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/parakeet-words.mjs

@@ -0,0 +1,27 @@
+// Merge Parakeet-MLX token timestamps into word timestamps.
+//
+// parakeet-mlx JSON emits SUB-WORD tokens (" H", "ello", ...) with per-token
+// start/end. Captions + transcript-cut need WORD timestamps, so join tokens
+// into words on the space boundary: a token whose text starts with a space
+// (or the very first token) begins a new word; the rest append. Output matches
+// the { words: [{ text, start, end }] } shape the rest of media-use consumes
+// (see words.mjs / cutlist.mjs).
+
+export function mergeTokensToWords(parakeet) {
+  const sentences = Array.isArray(parakeet?.sentences) ? parakeet.sentences : [];
+  const words = [];
+  for (const s of sentences) {
+    for (const t of s.tokens ?? []) {
+      const raw = typeof t.text === "string" ? t.text : "";
+      const startsWord = raw.startsWith(" ") || words.length === 0;
+      if (startsWord) {
+        words.push({ text: raw.trim(), start: t.start, end: t.end });
+      } else {
+        const w = words[words.length - 1];
+        w.text += raw;
+        w.end = t.end;
+      }
+    }
+  }
+  return { text: (parakeet?.text ?? "").trim(), words: words.filter((w) => w.text.length > 0) };
+}

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/parakeet-words.test.mjs

@@ -0,0 +1,44 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { mergeTokensToWords } from "./parakeet-words.mjs";
+
+test("mergeTokensToWords joins sub-word tokens on the space boundary", () => {
+  const parakeet = {
+    text: "Hello everyone. Um,",
+    sentences: [
+      {
+        tokens: [
+          { text: " H", start: 0.0, end: 0.24 },
+          { text: "ello", start: 0.24, end: 0.48 },
+          { text: " everyone.", start: 0.48, end: 1.28 },
+          { text: " Um,", start: 1.28, end: 1.92 },
+        ],
+      },
+    ],
+  };
+  const { words } = mergeTokensToWords(parakeet);
+  assert.deepEqual(words, [
+    { text: "Hello", start: 0.0, end: 0.48 },
+    { text: "everyone.", start: 0.48, end: 1.28 },
+    { text: "Um,", start: 1.28, end: 1.92 },
+  ]);
+});
+
+test("mergeTokensToWords spans multiple sentences and drops empties", () => {
+  const parakeet = {
+    text: "Hi there",
+    sentences: [
+      { tokens: [{ text: "Hi", start: 0, end: 0.2 }] },
+      { tokens: [{ text: " there", start: 0.5, end: 0.9 }] },
+    ],
+  };
+  const { words } = mergeTokensToWords(parakeet);
+  assert.equal(words.length, 2);
+  assert.equal(words[1].text, "there");
+  assert.equal(words[1].start, 0.5);
+});
+
+test("mergeTokensToWords tolerates missing sentences/tokens", () => {
+  assert.deepEqual(mergeTokensToWords({}).words, []);
+  assert.deepEqual(mergeTokensToWords({ sentences: [{}] }).words, []);
+});

package/vendor/hyperframes/dist/skills/media-use/scripts/lib/prefs-store.mjs

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { globalMediaDir } from "./media-home.mjs";
+
+/**
+ * Remembered defaults — the lightweight tier of HyperFrames user memory.
+ *
+ * Two files, same shape as the rest of media-use's storage split:
+ * - project `.media/preferences.json` — committed with the repo, so the whole
+ *   team inherits it; written every time a brief answer is confirmed.
+ * - user `~/.media/preferences.json` — personal, cross-repo. A key is promoted
+ *   here only once the same value has been confirmed in two different projects
+ *   (`PROMOTE_AT`), so a one-off choice never pollutes the global defaults.
+ *   Pre-promotion evidence accumulates in the user file's `sightings` ledger —
+ *   project files can't see each other, so the cross-project count has to live
+ *   user-side.
+ *
+ * Consumption contract (brief-contract § 2, Remembered defaults): a remembered
+ * value becomes the recommended option with a receipt naming its source — it
+ * never skips a question, and explicit request content always wins.
+ */
+
+const PREFS_FILE = "preferences.json";
+
+/** Keys the brief contract records; `style_preset` is stored per workflow. */
+export const PREFERENCE_KEYS = [
+  "destination",
+  "aspect",
+  "language",
+  "flow",
+  "storyboard",
+  "voice",
+  "style_preset",
+];
+
+/** A value must be confirmed in this many distinct projects to go user-tier. */
+export const PROMOTE_AT = 2;
+
+export function projectPrefsPath(projectDir) {
+  return join(resolve(projectDir), ".media", PREFS_FILE);
+}
+
+export function userPrefsPath() {
+  return join(globalMediaDir(), PREFS_FILE);
+}
+
+function emptyFile() {
+  return { version: 1, preferences: {}, sightings: {} };
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Tolerant read — a missing or malformed file counts as empty. */
+function readPrefsFile(path) {
+  try {
+    if (!existsSync(path)) return emptyFile();
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!isRecord(parsed)) return emptyFile();
+    return {
+      version: 1,
+      preferences: isRecord(parsed.preferences) ? parsed.preferences : {},
+      sightings: isRecord(parsed.sightings) ? parsed.sightings : {},
+    };
+  } catch {
+    return emptyFile();
+  }
+}
+
+/** Atomic write (tmp + rename) so a crash never leaves a torn file. */
+function writePrefsFile(path, file) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/** `style_preset` entries are stored per workflow as `style_preset.<workflow>`. */
+export function preferenceKeyFor(key, workflow) {
+  return key === "style_preset" && workflow ? `style_preset.${workflow}` : key;
+}
+
+function validEntry(entry) {
+  return isRecord(entry) && typeof entry.value === "string" && entry.value.length > 0;
+}
+
+/**
+ * The merged view the brief reads: user-tier promoted entries first, project
+ * entries on top (project wins). Each entry carries `source` plus the receipt
+ * material (`confirmed_in`, `updated_at`).
+ */
+export function mergedPreferences(projectDir) {
+  const user = readPrefsFile(userPrefsPath());
+  const project = readPrefsFile(projectPrefsPath(projectDir));
+  const merged = {};
+  for (const [key, entry] of Object.entries(user.preferences)) {
+    if (validEntry(entry)) merged[key] = { ...entry, source: "user" };
+  }
+  for (const [key, entry] of Object.entries(project.preferences)) {
+    if (validEntry(entry)) merged[key] = { ...entry, source: "project" };
+  }
+  return merged;
+}
+
+function dedupe(list) {
+  return [...new Set(list)];
+}
+
+/**
+ * Project tier: same value accumulates confirmations; a changed value starts
+ * provenance over (the old confirmations vouched for the old value).
+ */
+function recordProjectTier(projectDir, fullKey, value, projectName, now) {
+  const path = projectPrefsPath(projectDir);
+  const file = readPrefsFile(path);
+  const previous = file.preferences[fullKey];
+  const keepProvenance = validEntry(previous) && previous.value === value;
+  const confirmedIn = keepProvenance
+    ? dedupe([...(Array.isArray(previous.confirmed_in) ? previous.confirmed_in : []), projectName])
+    : [projectName];
+  file.preferences[fullKey] = { value, confirmed_in: confirmedIn, updated_at: now };
+  writePrefsFile(path, file);
+  return confirmedIn;
+}
+
+/**
+ * User tier: accumulate this sighting in the ledger, and promote the key once
+ * the same value has been confirmed in PROMOTE_AT distinct projects.
+ */
+function recordUserSighting(fullKey, value, projectName, now) {
+  const path = userPrefsPath();
+  const file = readPrefsFile(path);
+  const keySightings = isRecord(file.sightings[fullKey]) ? file.sightings[fullKey] : {};
+  const seenIn = dedupe([
+    ...(Array.isArray(keySightings[value]) ? keySightings[value] : []),
+    projectName,
+  ]);
+  keySightings[value] = seenIn;
+  file.sightings[fullKey] = keySightings;
+  const promoted = seenIn.length >= PROMOTE_AT;
+  if (promoted) {
+    file.preferences[fullKey] = { value, confirmed_in: seenIn, updated_at: now };
+  }
+  writePrefsFile(path, file);
+  return promoted;
+}
+
+/**
+ * Record one confirmed brief answer. Always writes the project tier; feeds the
+ * user tier's sightings ledger and promotes once the same value has been
+ * confirmed in PROMOTE_AT distinct projects. Idempotent per project.
+ */
+export function recordPreference({ projectDir, key, value, workflow }) {
+  if (!PREFERENCE_KEYS.includes(key)) {
+    throw new Error(`unknown preference key: "${key}" (known: ${PREFERENCE_KEYS.join(", ")})`);
+  }
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("a preference needs a non-empty string value");
+  }
+  if (key === "style_preset" && (!workflow || !String(workflow).trim())) {
+    throw new Error("style_preset is stored per workflow — pass --workflow <w>");
+  }
+  const fullKey = preferenceKeyFor(key, workflow);
+  const projectName = basename(resolve(projectDir));
+  const trimmed = value.trim();
+  const now = new Date().toISOString();
+
+  const confirmedIn = recordProjectTier(projectDir, fullKey, trimmed, projectName, now);
+
+  // Best-effort — a read-only home directory must never fail a brief.
+  let promoted = false;
+  try {
+    promoted = recordUserSighting(fullKey, trimmed, projectName, now);
+  } catch {
+    // The project record already landed; promotion just waits for next time.
+  }
+
+  return { key: fullKey, value: trimmed, confirmed_in: confirmedIn, promoted };
+}