quiver-cli 0.7.0 → 1.0.0

package/template/.agents/skills/design/impeccable/scripts/lib/roll-selection.mjs

@@ -0,0 +1,362 @@
+// The one implementation of world-roll selection.
+//
+// Two copies of this logic used to exist: this repo's concept-seed.mjs and the
+// service repo's functions/api/_worldroll-core.js, whose header claimed they
+// matched "exactly". They did not. The API had no breadth gate on either pool,
+// no rating weighting for compositions, and dealt one composition where the
+// seeder dealt three. Because the catalog never ships with the skill, every real
+// user rolls through that API, so those gates reached nobody.
+//
+// Why generators. The two callers cannot agree on a hash: Node has a
+// synchronous one, Workers only have async crypto.subtle, and concept-seed's
+// local render path is deliberately synchronous so prepared eval sessions and
+// tests can call it without awaiting. Rather than fork the logic or force the
+// whole seeder async, the selection is written once as a generator that yields
+// batches of strings to hash and resumes with their digests. runSyncSelection
+// and runAsyncSelection below are the only runtime-specific code, about eight
+// lines each. Both digests are the same bytes, so a roll is identical either way.
+//
+// Nothing here reads a file, an environment variable, or the network: callers
+// pass pools in.
+
+export const WELL_TIERS = ['graphic', 'interaction', 'atmosphere'];
+
+// Grain: how much of the product a composition composes. Named grain rather than
+// scope because scope already means direction-or-surface on every roll, and
+// 'surface' is already a register value, so a scope of 'surface' would collide
+// with both.
+//
+// This axis is framed by what the skill can be asked for, not by what the
+// catalog happens to hold. A user asks for a docs site, an onboarding flow, a
+// landing page, or a data table, and those are four different amounts of
+// product. Register says what kind of work it is; grain says how much of it.
+// Without grain, a request for a hero section can be dealt a whole-site
+// navigation structure and nothing notices.
+//
+// Measured when this was added: 137 of 173 approved compositions were view
+// grain, product grain was empty, and flow grain held one entry. That is why an
+// onboarding request had nothing to draw.
+export const COMPOSITION_GRAINS = [
+  'product', // a whole site or app: its information architecture
+  'flow',    // a sequence of views with one outcome: onboarding, checkout, setup
+  'view',    // one page or screen
+  'region',  // a section inside a view: a hero, a feature grid, a table
+];
+
+// Delivery targets a composition can survive. Mirrors the skill's platform axis
+// minus 'adaptive', which is a project-level value meaning both native targets
+// rather than something a single composition is authored for.
+//
+// A composition that leans on hover, a pointer, or a wide viewport does not
+// survive a phone, and nothing in the schema could say so before this.
+export const COMPOSITION_PLATFORMS = ['web', 'ios', 'android'];
+
+// Both fields are optional and absence means eligible everywhere, so no entry
+// has to be backfilled before this ships and no existing roll changes.
+export function isGrain(value) {
+  return COMPOSITION_GRAINS.includes(value);
+}
+
+export function isPlatform(value) {
+  return COMPOSITION_PLATFORMS.includes(value);
+}
+
+
+/**
+ * Drives a selection generator with a synchronous hash.
+ * @param {Generator} generator yields string[] to hash, resumes with hex string[]
+ * @param {(input: string) => string} hash
+ */
+export function runSyncSelection(generator, hash) {
+  let step = generator.next();
+  while (!step.done) step = generator.next(step.value.map(hash));
+  return step.value;
+}
+
+/**
+ * Drives a selection generator with an asynchronous hash.
+ * @param {Generator} generator
+ * @param {(input: string) => Promise<string>} hash
+ */
+export async function runAsyncSelection(generator, hash) {
+  let step = generator.next();
+  while (!step.done) step = generator.next(await Promise.all(step.value.map(hash)));
+  return step.value;
+}
+
+// Ranks items by the digest of `${input}:${id}`, descending, with the id as a
+// stable tiebreak. Yields every needed digest in one batch so the async driver
+// can resolve them concurrently.
+function* rank(items, input, idFor = item => item.id) {
+  const ids = items.map(idFor);
+  const digests = yield ids.map(id => `${input}:${id}`);
+  return items
+    .map((item, index) => ({ item, id: ids[index], score: digests[index] }))
+    .sort((a, b) => b.score.localeCompare(a.score) || a.id.localeCompare(b.id))
+    .map(entry => entry.item);
+}
+
+// Two independent exclusions, and either one is enough to hold a world back.
+// Rating grades quality: a 3-star earns a second ticket, a 1-star marginal keep
+// leaves the pool. Breadth says whether a world can serve an arbitrary build at
+// all, so a niche world leaves however good it is, keeping its approval for
+// direct briefs. Breadth was split out of rating because the only way to hold a
+// narrow world back used to be calling it marginal, which made "excellent but
+// narrow" unrecordable and corrupted ratings as a calibration signal.
+function challengerTickets(pool) {
+  return pool.flatMap(concept => {
+    const rating = concept.review?.rating;
+    if (rating === 1 || concept.review?.breadth === 'niche') return [];
+    return rating === 3
+      ? [{ concept, ticket: 0 }, { concept, ticket: 1 }]
+      : [{ concept, ticket: 0 }];
+  });
+}
+
+function compositionTickets(pool) {
+  return pool.flatMap(composition => {
+    const rating = composition.review?.rating;
+    if (rating === 1) return [];
+    return rating === 3
+      ? [{ composition, ticket: 0 }, { composition, ticket: 1 }]
+      : [{ composition, ticket: 0 }];
+  });
+}
+
+/**
+ * Six challengers, two per translation tier, from an explicit approved pool.
+ * Drive with runSyncSelection or runAsyncSelection.
+ *
+ * @param {object} options
+ * @param {'direction'|'surface'} options.scope
+ * @param {string} options.key              same key reproduces the roll
+ * @param {number} [options.reroll]         round of the re-roll chain
+ * @param {number|null} [options.minRating] optional floor, skipped per tier it would empty
+ * @param {Array} options.concepts          merged concepts with status, review, wellTier, familyId
+ * @returns {Generator<string[], {approved: Array, picks: Array}, string[]>}
+ */
+// A world with no allowedModes is eligible everywhere, which is what keeps this
+// additive: nothing has to be backfilled for the filter to be safe.
+function modeAllows(concept, mode) {
+  const allowed = concept.review?.allowedModes;
+  if (!Array.isArray(allowed) || allowed.length === 0) return true;
+  return allowed.includes(mode);
+}
+
+export function* selectApprovedChallengers({ scope, key, reroll = 0, minRating = null, mode = null, concepts }) {
+  const approved = concepts.filter(concept => concept.status === 'approved');
+  // Direction chooses a durable identity, so it draws worlds; surface designs
+  // one page inside a committed identity, so it draws compositions. Duals serve
+  // both. A tier with no matching-strength approvals falls back to its full
+  // approved pool rather than starving the roll.
+  const wanted = scope === 'direction'
+    ? new Set(['world', 'dual'])
+    : new Set(['composition', 'dual']);
+
+  const approvedByTier = new Map();
+  for (const concept of approved) {
+    const tier = approvedByTier.get(concept.wellTier) || [];
+    tier.push(concept);
+    approvedByTier.set(concept.wellTier, tier);
+  }
+  if (WELL_TIERS.some(tier => !(approvedByTier.get(tier) || []).length)) {
+    throw new Error('concept-seed: every challenger tier needs at least one approved concept');
+  }
+
+  // Optional minimum-rating gate, applied per tier and skipped for any tier it
+  // would empty, so a thin tier degrades to its full approved pool.
+  if (minRating) {
+    for (const [tier, pool] of approvedByTier) {
+      const rated = pool.filter(concept => (concept.review?.rating || 0) >= minRating);
+      if (rated.length > 0) approvedByTier.set(tier, rated);
+    }
+  }
+  // Mode eligibility, per tier and skipped where it would empty a tier. Worlds
+  // used to be drawn with no mode awareness at all, so a build asking for an app
+  // UI could get six worlds that only make sense on a landing page. A world is an
+  // identity and identities transfer further than compositions do, so this is a
+  // ceiling the reviewer sets rather than a category assignment: eligible
+  // everywhere until someone says otherwise.
+  if (mode) {
+    for (const [tier, pool] of approvedByTier) {
+      const eligible = pool.filter(concept => modeAllows(concept, mode));
+      if (eligible.length > 0) approvedByTier.set(tier, eligible);
+    }
+  }
+  for (const [tier, pool] of approvedByTier) {
+    const matching = pool.filter(concept => wanted.has(concept.strength));
+    if (matching.length > 0) approvedByTier.set(tier, matching);
+  }
+
+  // Two challengers per tier, so every roll carries near-zero-translation
+  // graphic systems beside instrument languages and atmosphere worlds, with the
+  // second pick preferring a different family. Tier order is rolled too, to
+  // avoid positional bias.
+  function* pickRound(round, excluded) {
+    const salt = round === 0 ? '' : `:reroll-${round}`;
+    const tierOrder = (yield* rank(
+      WELL_TIERS.map(id => ({ id })),
+      `${scope}:${key}:tiers${salt}`
+    )).map(item => item.id);
+    const picks = [];
+    for (const [index, tier] of tierOrder.entries()) {
+      let pool = approvedByTier.get(tier).filter(concept => !excluded.has(concept.id));
+      // A tier exhausted by prior rounds falls back to reuse over starvation.
+      if (pool.length === 0) pool = approvedByTier.get(tier);
+      let tickets = challengerTickets(pool);
+      if (tickets.length === 0) tickets = pool.map(concept => ({ concept, ticket: 0 }));
+      const ranked = yield* rank(
+        tickets,
+        `${scope}:${key}:challenger-${index}${salt}`,
+        entry => `${entry.concept.id}#${entry.ticket}`
+      );
+      const order = [];
+      const seen = new Set();
+      for (const entry of ranked) {
+        if (seen.has(entry.concept.id)) continue;
+        seen.add(entry.concept.id);
+        order.push(entry.concept);
+      }
+      const first = order[0];
+      const second = order.find(concept => concept.familyId !== first.familyId)
+        || order.find(concept => concept.id !== first.id);
+      picks.push(...(second ? [first, second] : [first]));
+    }
+    return picks;
+  }
+
+  // Round n of a re-roll chain excludes everything rounds 0..n-1 drew, so the
+  // same base key reproduces the whole chain.
+  const excluded = new Set();
+  let picks = yield* pickRound(0, excluded);
+  for (let round = 1; round <= reroll; round += 1) {
+    for (const pick of picks) excluded.add(pick.id);
+    picks = yield* pickRound(round, excluded);
+  }
+  return { approved, picks };
+}
+
+function emptyMatch(grain, platform, platformExcluded = 0) {
+  return { grain: grain ?? null, atGrain: grain ? 0 : null, grainAvailable: grain ? 0 : null, platform: platform ?? null, platformExcluded };
+}
+
+/**
+ * Three identity-free composition inputs from an explicit approved pool.
+ * Drive with runSyncSelection or runAsyncSelection.
+ *
+ * One input was too weak a counterweight to a model's habitual page skeleton:
+ * it became a single optional flourish beside six identity challengers rather
+ * than a real search over composition. Distinct composition families are preferred
+ * so a roll tests materially different hierarchy, sequence, and interaction
+ * laws. Cross-mode fallback would make the input misleading, so an absent mode
+ * returns nothing rather than borrowing. Re-rolls exclude every earlier set
+ * until the pool runs out.
+ *
+ * @param {object} options
+ * @param {'direction'|'surface'} options.scope
+ * @param {string} options.key
+ * @param {number} [options.reroll]
+ * @param {string|null} [options.mode]  surface register to stay inside
+ * @param {string|null} [options.grain]     how much of the product is in play
+ * @param {string|null} [options.platform]  delivery target the result has to survive
+ * @param {Array} options.compositions  merged compositions with status, review, surface, familyId
+ * @param {number} [options.count]
+ * @returns {Generator<string[], {picks: Array, match: object}, string[]>}
+ */
+export function* selectApprovedCompositions({ scope, key, reroll = 0, mode = null, grain = null, platform = null, compositions, count = 3 }) {
+  // Compositions honour the same breadth gate as worlds: one too specific to serve
+  // an arbitrary build stays approved for direct briefs and leaves the
+  // challenger pool. Falls back to the full approved set rather than returning
+  // nothing if every approved composition is niche.
+  let approved = compositions.filter(composition => composition.status === 'approved');
+  const broad = approved.filter(composition => composition.review?.breadth !== 'niche');
+  if (broad.length > 0) approved = broad;
+  if (approved.length === 0) return { picks: [], match: emptyMatch(grain, platform) };
+  if (mode) {
+    const matching = approved.filter(composition => composition.surface === mode);
+    if (matching.length === 0) return { picks: [], match: emptyMatch(grain, platform) };
+    approved = matching;
+  }
+  // Platform is a hard filter, unlike grain. A composition that needs hover or a
+  // pointer does not degrade on a phone into something slightly worse; it stops
+  // working, so borrowing it would be a defect rather than a stretch. Absent
+  // platforms means it survives anywhere.
+  let platformExcluded = 0;
+  if (platform) {
+    const survives = approved.filter(composition => {
+      const only = composition.platforms;
+      return !Array.isArray(only) || only.length === 0 || only.includes(platform);
+    });
+    platformExcluded = approved.length - survives.length;
+    // No fallback here either: dealing a hover-only composition to a phone build
+    // is worse than dealing nothing, and an empty deal is a visible gap.
+    approved = survives;
+    if (approved.length === 0) return { picks: [], match: emptyMatch(grain, platform, platformExcluded) };
+  }
+
+  const prior = new Set();
+  let picks = [];
+  for (let round = 0; round <= reroll; round += 1) {
+    const available = approved.filter(composition => !prior.has(composition.id));
+    const base = available.length >= Math.min(count, approved.length) ? available : approved;
+    // Rating weights the draw as it does for worlds. It matters more here
+    // because the per-surface pools are small, so an unweighted shuffle repeats
+    // a weak composition far more often. Each ticket carries its index so the rank
+    // sees a distinct key per ticket: ranking bare duplicates would hash
+    // identically and the pick loop's id-dedupe would silently discard the
+    // second copy, making the weighting a no-op.
+    let tickets = compositionTickets(base);
+    // A pool of nothing but 1-star keeps still has to yield compositions.
+    if (tickets.length === 0) tickets = base.map(composition => ({ composition, ticket: 0 }));
+    const ranked = (yield* rank(
+      tickets,
+      // The salt keeps the word "staging" deliberately. It is hash input, so
+      // renaming it would re-deal every roll anyone has ever reproduced by key.
+      round === 0 ? `${scope}:${key}:staging` : `${scope}:${key}:staging:reroll-${round}`,
+      entry => `${entry.composition.id}#${entry.ticket}`
+    )).map(entry => entry.composition);
+
+    // Grain is a preference, not a filter: requesting an onboarding flow deals
+    // flow-grain compositions first and tops up from the rest of the register
+    // rather than dealing fewer than three. A stable partition of an already
+    // deterministic ranking is still deterministic.
+    //
+    // The top-up is why match is reported. Dealing three plausible view-grain
+    // compositions against a flow request, with no signal that none matched, is
+    // the same silent-plausibility failure this whole axis exists to fix: the
+    // model would improvise the flow structure while believing it was handed one.
+    const ordered = grain
+      ? [...ranked.filter(composition => composition.grain === grain),
+         ...ranked.filter(composition => composition.grain !== grain)]
+      : ranked;
+
+    const families = new Set();
+    picks = [];
+    for (const composition of ordered) {
+      const family = composition.familyId ?? composition.id;
+      if (families.has(family)) continue;
+      picks.push(composition);
+      families.add(family);
+      if (picks.length >= count) break;
+    }
+    for (const composition of ordered) {
+      if (picks.length >= count) break;
+      if (!picks.some(pick => pick.id === composition.id)) picks.push(composition);
+    }
+    if (round < reroll) picks.forEach(composition => prior.add(composition.id));
+  }
+
+  const atGrain = grain ? picks.filter(composition => composition.grain === grain).length : null;
+  return {
+    picks,
+    match: {
+      grain: grain ?? null,
+      // How many of the dealt compositions actually sit at the requested grain.
+      // 0 with a grain requested means every pick is a borrowed structure.
+      atGrain,
+      grainAvailable: grain ? approved.filter(composition => composition.grain === grain).length : null,
+      platform: platform ?? null,
+      platformExcluded,
+    },
+  };
+}