@milesroxas/design-hub 0.0.0-stage → 0.1.1

package/core/review/service.ts

@@ -0,0 +1,309 @@
+// The review use cases over the storage port. Every adapter (the Vercel
+// function, the Vite dev server, the CLI) builds one of these and calls it;
+// none of them touches the store directly, so the rules in model.ts and
+// policy.ts hold everywhere. Writes are per record (one hash field per
+// person, per comment), so two people commenting at once never collide;
+// two edits of the same comment at once keep the last.
+import { base64url, hex, sha256 } from '../bytes.ts';
+import {
+  authorOf,
+  type Checked,
+  type Comment,
+  checkAnchor,
+  checkBody,
+  checkPersonInput,
+  checkStates,
+  checkTriage,
+  INVITE_DAYS,
+  isRoot,
+  type Person,
+  type Triage,
+} from './model.ts';
+import { type Action, can } from './policy.ts';
+import { KEY, type KV } from './store.ts';
+
+export type ErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid';
+
+export class ReviewError extends Error {
+  code: ErrorCode;
+  problems: string[];
+  constructor(code: ErrorCode, message: string, problems: string[] = []) {
+    super(message);
+    this.code = code;
+    this.problems = problems;
+  }
+}
+
+export type TriageInput = { body: string; prototype: string; url: string; states: string[] };
+/** Classifies a new comment; null when it cannot (TypeSafe off, slow, unsure). */
+export type Triager = (input: TriageInput) => Promise<Triage | null>;
+
+export type Deps = {
+  now: () => Date;
+  random: (bytes: number) => Uint8Array;
+  triage: Triager | null;
+};
+
+const DAY_MS = 86_400_000;
+
+const defaults: Deps = {
+  now: () => new Date(),
+  random: (n) => crypto.getRandomValues(new Uint8Array(n)),
+  triage: null,
+};
+
+type Invite = { person: string; expiresAt: string };
+
+export function createReview(kv: KV, overrides: Partial<Deps> = {}) {
+  const deps = { ...defaults, ...overrides };
+  const now = () => deps.now().toISOString();
+  // Sortable by time, unique without coordination.
+  const newId = () => `${deps.now().getTime().toString(36).padStart(9, '0')}${hex(deps.random(5))}`;
+
+  const parse = <T>(json: string | null): T | null => (json === null ? null : (JSON.parse(json) as T));
+
+  function allow(actor: Person | null, action: Action, subject?: Comment): asserts actor is Person {
+    if (!actor) throw new ReviewError('unauthorized', 'Sign in with an invite link to do that.');
+    if (!can(actor, action, subject)) throw new ReviewError('forbidden', 'You cannot do that.');
+  }
+
+  function valid<T>(checked: Checked<T>): T {
+    if (!checked.ok) throw new ReviewError('invalid', 'Some fields are not valid.', checked.problems);
+    return checked.value;
+  }
+
+  // Every field checked before any throws, so one save names every problem.
+  function validAll<A, B>(a: Checked<A>, b: Checked<B>): [A, B] {
+    const problems = [...(a.ok ? [] : a.problems), ...(b.ok ? [] : b.problems)];
+    if (!a.ok || !b.ok) throw new ReviewError('invalid', 'Some fields are not valid.', problems);
+    return [a.value, b.value];
+  }
+
+  const person = async (id: string) => parse<Person>(await kv.hget(KEY.people, id));
+  const savePerson = (p: Person) => kv.hset(KEY.people, p.id, JSON.stringify(p));
+
+  async function issueInvite(p: Person): Promise<string> {
+    // The link carries the token; the store keeps only its hash, so a leaked store signs nobody in.
+    const token = base64url(deps.random(32));
+    const invite: Invite = {
+      person: p.id,
+      expiresAt: new Date(deps.now().getTime() + INVITE_DAYS * DAY_MS).toISOString(),
+    };
+    await kv.hset(KEY.invites, hex(await sha256(token)), JSON.stringify(invite));
+    return token;
+  }
+
+  async function dropInvites(personId: string): Promise<void> {
+    const all = await kv.hgetall(KEY.invites);
+    for (const [hash, json] of Object.entries(all))
+      if ((JSON.parse(json) as Invite).person === personId) await kv.hdel(KEY.invites, hash);
+  }
+
+  async function needPerson(id: string): Promise<Person> {
+    const p = await person(id);
+    if (!p) throw new ReviewError('not_found', 'No such person.');
+    return p;
+  }
+
+  const commentsOf = async (prototype: string) =>
+    Object.values(await kv.hgetall(KEY.comments(prototype)))
+      .map((json) => JSON.parse(json) as Comment)
+      .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+
+  const saveComment = (prototype: string, c: Comment) =>
+    kv.hset(KEY.comments(prototype), c.id, JSON.stringify(c));
+
+  async function needComment(prototype: string, id: string): Promise<Comment> {
+    const c = parse<Comment>(await kv.hget(KEY.comments(prototype), id));
+    if (!c) throw new ReviewError('not_found', 'No such comment.');
+    return c;
+  }
+
+  async function needRoot(prototype: string, id: string): Promise<Comment> {
+    const c = await needComment(prototype, id);
+    if (!isRoot(c)) throw new ReviewError('invalid', 'That is a reply; act on its thread.');
+    return c;
+  }
+
+  return {
+    person,
+
+    /** The person a signed session names, if they still may sign in with it. */
+    async sessionPerson(id: string, epoch: number): Promise<Person | null> {
+      const p = await person(id);
+      return p && !p.revokedAt && p.epoch === epoch ? p : null;
+    },
+
+    async listPeople(actor: Person | null): Promise<Person[]> {
+      allow(actor, 'people');
+      const all = Object.values(await kv.hgetall(KEY.people)).map((j) => JSON.parse(j) as Person);
+      return all.sort((a, b) => a.team.localeCompare(b.team) || a.name.localeCompare(b.name));
+    },
+
+    async invite(actor: Person | null, input: unknown): Promise<{ person: Person; token: string }> {
+      allow(actor, 'people');
+      const p: Person = {
+        id: newId(),
+        ...valid(checkPersonInput(input)),
+        createdAt: now(),
+        revokedAt: null,
+        epoch: 0,
+      };
+      await savePerson(p);
+      return { person: p, token: await issueInvite(p) };
+    },
+
+    /** A fresh link for someone; their old link and every session they hold stop working. */
+    async reissue(actor: Person | null, id: string): Promise<{ person: Person; token: string }> {
+      allow(actor, 'people');
+      const p = await needPerson(id);
+      if (p.revokedAt) throw new ReviewError('invalid', 'That person is revoked; invite them again.');
+      const next = { ...p, epoch: p.epoch + 1 };
+      await dropInvites(id);
+      await savePerson(next);
+      return { person: next, token: await issueInvite(next) };
+    },
+
+    async revoke(actor: Person | null, id: string): Promise<Person> {
+      allow(actor, 'people');
+      if (actor.id === id) throw new ReviewError('invalid', 'You cannot revoke yourself.');
+      const p = await needPerson(id);
+      const next = { ...p, revokedAt: p.revokedAt ?? now(), epoch: p.epoch + 1 };
+      await dropInvites(id);
+      await savePerson(next);
+      return next;
+    },
+
+    /** The person an invite token names, while the invite is current and they are not revoked. */
+    async acceptInvite(token: string): Promise<Person | null> {
+      if (!/^[\w-]{20,100}$/.test(token)) return null;
+      const invite = parse<Invite>(await kv.hget(KEY.invites, hex(await sha256(token))));
+      if (!invite || invite.expiresAt <= now()) return null;
+      const p = await person(invite.person);
+      return p && !p.revokedAt ? p : null;
+    },
+
+    async listComments(actor: Person | null, prototype: string): Promise<Comment[]> {
+      allow(actor, 'read');
+      return commentsOf(prototype);
+    },
+
+    /** Every comment on every prototype, for the CLI, which holds the store's own credentials. */
+    async allComments(): Promise<Comment[]> {
+      const prototypes = await kv.smembers(KEY.prototypes);
+      return (await Promise.all(prototypes.map(commentsOf))).flat();
+    },
+
+    async add(
+      actor: Person | null,
+      input: { body?: unknown; anchor?: unknown; states?: unknown },
+    ): Promise<Comment> {
+      allow(actor, 'comment');
+      const [body, anchor] = validAll(checkBody(input.body), checkAnchor(input.anchor));
+      const id = newId();
+      const triage = deps.triage
+        ? await deps
+            .triage({ body, prototype: anchor.prototype, url: anchor.url, states: checkStates(input.states) })
+            // Triage is a convenience; a triager that throws never costs the comment.
+            .catch(() => null)
+        : null;
+      const c: Comment = {
+        id,
+        thread: id,
+        author: authorOf(actor),
+        body,
+        createdAt: now(),
+        editedAt: null,
+        anchor,
+        status: 'open',
+        resolvedBy: null,
+        triage,
+      };
+      await kv.sadd(KEY.prototypes, anchor.prototype);
+      await saveComment(anchor.prototype, c);
+      return c;
+    },
+
+    async reply(
+      actor: Person | null,
+      input: { prototype: string; thread: string; body?: unknown },
+    ): Promise<Comment> {
+      allow(actor, 'comment');
+      const root = await needRoot(input.prototype, input.thread);
+      const id = newId();
+      const c: Comment = {
+        id,
+        thread: root.id,
+        author: authorOf(actor),
+        body: valid(checkBody(input.body)),
+        createdAt: now(),
+        editedAt: null,
+        anchor: null,
+        status: 'open',
+        resolvedBy: null,
+        triage: null,
+      };
+      await saveComment(input.prototype, c);
+      return c;
+    },
+
+    async edit(
+      actor: Person | null,
+      input: { prototype: string; id: string; body?: unknown },
+    ): Promise<Comment> {
+      const c = await needComment(input.prototype, input.id);
+      allow(actor, 'edit', c);
+      const next = { ...c, body: valid(checkBody(input.body)), editedAt: now() };
+      await saveComment(input.prototype, next);
+      return next;
+    },
+
+    /** Deletes a comment; deleting a thread's root deletes its replies with it. */
+    async remove(actor: Person | null, input: { prototype: string; id: string }): Promise<string[]> {
+      const c = await needComment(input.prototype, input.id);
+      allow(actor, 'delete', c);
+      const gone = isRoot(c)
+        ? (await commentsOf(input.prototype)).filter((x) => x.thread === c.id).map((x) => x.id)
+        : [c.id];
+      for (const id of gone) await kv.hdel(KEY.comments(input.prototype), id);
+      return gone;
+    },
+
+    async resolve(
+      actor: Person | null,
+      input: { prototype: string; id: string; resolved: boolean },
+    ): Promise<Comment> {
+      const c = await needRoot(input.prototype, input.id);
+      allow(actor, 'resolve', c);
+      const next: Comment = input.resolved
+        ? { ...c, status: 'resolved', resolvedBy: authorOf(actor) }
+        : { ...c, status: 'open', resolvedBy: null };
+      await saveComment(input.prototype, next);
+      return next;
+    },
+
+    async retriage(
+      actor: Person | null,
+      input: { prototype: string; id: string; triage?: unknown; states?: unknown },
+    ): Promise<Comment> {
+      allow(actor, 'triage');
+      const c = await needRoot(input.prototype, input.id);
+      const states = checkStates(input.states);
+      const { kind, state } = valid(checkTriage(input.triage, states.length ? states : null));
+      const next: Comment = { ...c, triage: { kind, state, by: 'person', confidence: null } };
+      await saveComment(input.prototype, next);
+      return next;
+    },
+
+    /** Where a comment lives, for the CLI, which has an id and no prototype. */
+    async locate(id: string): Promise<{ prototype: string; comment: Comment } | null> {
+      for (const prototype of await kv.smembers(KEY.prototypes)) {
+        const c = parse<Comment>(await kv.hget(KEY.comments(prototype), id));
+        if (c) return { prototype, comment: c };
+      }
+      return null;
+    },
+  };
+}
+
+export type Review = ReturnType<typeof createReview>;

package/core/review/store.ts

@@ -0,0 +1,51 @@
+// The one storage port the review service needs: a few Redis-shaped hash
+// and set operations. Production is Upstash Redis over REST
+// (server/upstash.ts); dev and tests use the in-memory store below, which
+// the dev server persists to a file (server/file-kv.ts).
+
+export interface KV {
+  hget(key: string, field: string): Promise<string | null>;
+  hset(key: string, field: string, value: string): Promise<void>;
+  hdel(key: string, field: string): Promise<void>;
+  hgetall(key: string): Promise<Record<string, string>>;
+  sadd(key: string, member: string): Promise<void>;
+  smembers(key: string): Promise<string[]>;
+}
+
+/** Every key the hub writes starts here, so a shared Redis never mixes it with another app's data. */
+export const KEY = {
+  people: 'hub:people',
+  invites: 'hub:invites',
+  prototypes: 'hub:prototypes',
+  comments: (prototype: string) => `hub:comments:${prototype}`,
+} as const;
+
+export type Snapshot = { hashes: Record<string, Record<string, string>>; sets: Record<string, string[]> };
+
+export function memoryKV(initial: Snapshot = { hashes: {}, sets: {} }, onChange?: (s: Snapshot) => void): KV {
+  const hashes = new Map(Object.entries(initial.hashes).map(([k, v]) => [k, new Map(Object.entries(v))]));
+  const sets = new Map(Object.entries(initial.sets).map(([k, v]) => [k, new Set(v)]));
+  const changed = () =>
+    onChange?.({
+      hashes: Object.fromEntries([...hashes].map(([k, v]) => [k, Object.fromEntries(v)])),
+      sets: Object.fromEntries([...sets].map(([k, v]) => [k, [...v]])),
+    });
+  const hash = (key: string) => hashes.get(key) ?? hashes.set(key, new Map()).get(key)!;
+  return {
+    hget: async (key, field) => hashes.get(key)?.get(field) ?? null,
+    hset: async (key, field, value) => {
+      hash(key).set(field, value);
+      changed();
+    },
+    hdel: async (key, field) => {
+      hashes.get(key)?.delete(field);
+      changed();
+    },
+    hgetall: async (key) => Object.fromEntries(hashes.get(key) ?? []),
+    sadd: async (key, member) => {
+      (sets.get(key) ?? sets.set(key, new Set()).get(key)!).add(member);
+      changed();
+    },
+    smembers: async (key) => [...(sets.get(key) ?? [])],
+  };
+}

package/core/review/triage.test.ts

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { DEFAULT_CHECKS } from '../checks.ts';
+import type { askJev } from '../jev.ts';
+import { jevTriager } from './triage.ts';
+
+const answering = (answers: Record<string, unknown>): typeof askJev =>
+  (async () => ({ ok: true, model: 'm', answers, ms: 1 })) as unknown as typeof askJev;
+
+const input = { body: 'Typo in the title', prototype: 'p', url: '/p/', states: ['Real', 'Empty'] };
+
+test('keeps a confident kind and state', async () => {
+  const triage = jevTriager(
+    'key',
+    DEFAULT_CHECKS,
+    answering({
+      kind: { type: 'choice', choice: 'copy', confidence: 0.8, probabilities: {} },
+      state: { type: 'choice', choice: 'Real', confidence: 0.6, probabilities: {} },
+    }),
+  );
+  assert.deepEqual(await triage?.(input), { kind: 'copy', state: 'Real', by: 'jev', confidence: 0.6 });
+});
+
+test('leaves an unsure field for a person', async () => {
+  const triage = jevTriager(
+    'key',
+    DEFAULT_CHECKS,
+    answering({
+      kind: { type: 'choice', choice: 'bug', confidence: 0.2, probabilities: {} },
+      state: { type: 'choice', choice: 'Empty', confidence: 0.9, probabilities: {} },
+    }),
+  );
+  assert.deepEqual(await triage?.(input), { kind: null, state: 'Empty', by: 'jev', confidence: 0.9 });
+});
+
+test('is off without a key or checks, and null when Jev fails', async () => {
+  assert.equal(jevTriager('', DEFAULT_CHECKS), null);
+  assert.equal(jevTriager('key', null), null);
+  const failing = (async () => ({ ok: false, error: 'x', ms: 1 })) as unknown as typeof askJev;
+  assert.equal(await jevTriager('key', DEFAULT_CHECKS, failing)?.(input), null);
+});

package/core/review/triage.ts

@@ -0,0 +1,58 @@
+// Comment triage with Jev: each new comment gets a kind (bug, taste, copy)
+// and the README state it is about, so feedback lands on the state it
+// concerns. Two Choices in one request. Below the project's `triage.at`
+// confidence a field stays null for a person to set; Jev never guesses
+// loudly. TypeSafe off, slow or failing: no triage, and the comment saves.
+import type { Checks } from '../checks.ts';
+import { askJev, choiceOf, type Question } from '../jev.ts';
+import type { Kind, Triage } from './model.ts';
+import type { Triager } from './service.ts';
+
+const KIND_CRITERIA: Record<Kind, string> = {
+  bug: 'Something is broken or wrong: it does not work, shows the wrong thing, or the layout breaks.',
+  taste: 'A design opinion about look, feel, motion, spacing or hierarchy, where nothing is broken.',
+  copy: 'About the words: a typo, a label, wording or content to change.',
+};
+
+type Ask = typeof askJev;
+
+export function jevTriager(apiKey: string, checks: Checks | null, ask: Ask = askJev): Triager | null {
+  if (!apiKey || !checks) return null;
+  const { model, timeoutMs } = checks.jev;
+  const at = checks.triage.at;
+  return async ({ body, prototype, url, states }) => {
+    const questions: Record<string, Question> = {
+      kind: {
+        type: 'choice',
+        instructions: 'What kind of review note is `comment`?',
+        criteria: KIND_CRITERIA,
+      },
+    };
+    if (states.length)
+      questions.state = {
+        type: 'choice',
+        instructions: 'Which state of the prototype is `comment` about? `url` is where the reviewer was.',
+        criteria: Object.fromEntries(states.map((s) => [s, null])),
+      };
+    const result = await ask(
+      apiKey,
+      { model, state: { comment: body, prototype, url }, questions },
+      { timeoutMs },
+    );
+    if (!result.ok) return null;
+    const pick = (key: string) => {
+      const c = choiceOf(result.answers, key);
+      return c && at !== null && c.confidence >= at ? c : null;
+    };
+    const kind = pick('kind');
+    const state = pick('state');
+    if (!kind && !state) return null;
+    const triage: Triage = {
+      kind: (kind?.choice as Kind | undefined) ?? null,
+      state: state?.choice ?? null,
+      by: 'jev',
+      confidence: Math.min(kind?.confidence ?? 1, state?.confidence ?? 1),
+    };
+    return triage;
+  };
+}

package/core/states.test.ts

@@ -0,0 +1,36 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { parseStates } from './states.ts';
+
+const readme = (table: string) =>
+  `# X\n\n## Question\n\nWhy?\n\n## States\n\nIntro line.\n\n${table}\n\n## Fixtures\n\n| real | x |\n`;
+
+test('reads every row after the header and separator', () => {
+  const md = readme(
+    '| State | How to reach it |\n| --- | --- |\n| Real list | Controls → **real** |\n| Empty | Controls → **empty** |',
+  );
+  assert.deepEqual(parseStates(md), [
+    { name: 'Real list', reach: 'Controls → **real**' },
+    { name: 'Empty', reach: 'Controls → **empty**' },
+  ]);
+});
+
+test('stops at the next section, so a later table is not read as states', () => {
+  const md = readme('| State | How |\n|:---|---:|\n| Dark | ?theme=dark |');
+  assert.deepEqual(
+    parseStates(md)?.map((s) => s.name),
+    ['Dark'],
+  );
+});
+
+test('drops the template placeholder row', () => {
+  assert.deepEqual(parseStates(readme('| State | How to reach it |\n| --- | --- |\n| | |')), []);
+});
+
+test('is null without a States section', () => {
+  assert.equal(parseStates('# X\n\n## Question\n'), null);
+});
+
+test('reads a States section that ends the file', () => {
+  assert.deepEqual(parseStates('## States\n\n| State | How |\n| --- | --- |\n| Open | click |\n')?.length, 1);
+});

package/core/states.ts

@@ -0,0 +1,34 @@
+// A prototype README's `## States` table: one row per state the prototype
+// holds, the first cell its name and the second how a reviewer reaches it.
+// The fidelity guard, the pre-flight, comment triage and `miles-port` all
+// read states through this one parser, so they never disagree on the list.
+
+export type State = { name: string; reach: string };
+
+const HEADING = /^##\s+States\s*$/m;
+const NEXT_HEADING = /^#{1,2}\s/m;
+const SEPARATOR = /^\|\s*:?-{3,}/;
+
+const cells = (row: string) =>
+  row
+    .trim()
+    .replace(/^\||\|$/g, '')
+    .split('|')
+    .map((c) => c.trim());
+
+/** The states listed in a README, or null when it has no States section. */
+export function parseStates(readme: string): State[] | null {
+  const start = readme.search(HEADING);
+  if (start < 0) return null;
+  const rest = readme.slice(start).replace(HEADING, '');
+  const end = rest.search(NEXT_HEADING);
+  const section = end < 0 ? rest : rest.slice(0, end);
+  const rows = section.split('\n').filter((l) => l.trim().startsWith('|'));
+  // The first row is the header, whatever it says; the separator follows it.
+  return rows
+    .slice(1)
+    .filter((r) => !SEPARATOR.test(r.trim()))
+    .map(cells)
+    .map(([name = '', reach = '']) => ({ name, reach }))
+    .filter((s) => s.name !== '');
+}

package/dist/core/bytes.d.ts

@@ -0,0 +1,5 @@
+export declare function sha256(text: string): Promise<Uint8Array>;
+export declare const hex: (bytes: Uint8Array) => string;
+export declare const base64: (bytes: Uint8Array) => string;
+/** URL-safe base64 without padding: cookies, tokens and links carry it unescaped. */
+export declare const base64url: (bytes: Uint8Array) => string;

package/dist/core/bytes.js

@@ -0,0 +1,9 @@
+// Bytes to text, and SHA-256, on Web Crypto only, so the same helpers serve
+// the browser, Node and Vercel's runtime.
+export async function sha256(text) {
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)));
+}
+export const hex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+export const base64 = (bytes) => btoa(String.fromCharCode(...bytes));
+/** URL-safe base64 without padding: cookies, tokens and links carry it unescaped. */
+export const base64url = (bytes) => base64(bytes).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '');

package/dist/core/catalog.d.ts

@@ -0,0 +1,17 @@
+import { type State } from './states.ts';
+export type Kind = 'sprint' | 'alternate' | 'exploration';
+export type Meta = {
+    slug: string;
+    title: string;
+    summary: string;
+    context: string;
+    status: string;
+    kind: Kind;
+    feature: string;
+    created: string;
+    /** null when the README has no States section. */
+    states: State[] | null;
+};
+export declare function readMeta(slug: string, readme: string): Meta;
+export declare const isLive: (m: Pick<Meta, 'status'>) => boolean;
+export declare const byIndexOrder: (a: Meta, b: Meta) => number;

package/dist/core/catalog.js

@@ -0,0 +1,24 @@
+// What a prototype's README says about it: the frontmatter the index lists
+// and the States table the checks read. One reader for the browser index
+// (shell/registry.ts) and the Node scripts (scripts/lib/catalog.ts), so
+// they never disagree about what a prototype is.
+import { frontmatter } from './frontmatter.js';
+import { parseStates } from './states.js';
+export function readMeta(slug, readme) {
+    const { data } = frontmatter(readme);
+    return {
+        slug,
+        title: data.title || slug,
+        summary: data.summary || '',
+        context: data.context || 'space',
+        status: data.status || 'exploring',
+        kind: data.kind === 'sprint' || data.kind === 'alternate' ? data.kind : 'exploration',
+        feature: data.feature || '',
+        created: data.created || '',
+        states: parseStates(readme),
+    };
+}
+export const isLive = (m) => m.status !== 'archived';
+// Open questions sit above answered ones; within a status, newest first.
+const rank = (status) => (status === 'exploring' ? 0 : 1);
+export const byIndexOrder = (a, b) => rank(a.status) - rank(b.status) || b.created.localeCompare(a.created) || a.title.localeCompare(b.title);

package/dist/core/checks.d.ts

@@ -0,0 +1,41 @@
+/** A probability threshold, or null for "never". */
+type At = number | null;
+export type Checks = {
+    jev: {
+        model: string;
+        timeoutMs: number;
+    };
+    fidelity: {
+        warnAt: At;
+        blockAt: At;
+    };
+    states: {
+        blockAt: At;
+    };
+    contacts: {
+        privateAt: At;
+        allow: string[];
+    };
+    skillHint: {
+        gateAt: At;
+        fitsAt: At;
+    };
+    triage: {
+        at: At;
+    };
+    visual: {
+        warnAt: At;
+    };
+};
+export declare const DEFAULT_CHECKS: Checks;
+/** Every problem with a checks object, by path; empty when it is valid. */
+export declare function validateChecks(value: unknown): string[];
+export type Loaded = {
+    checks: Checks | null;
+    problems: string[];
+};
+/** The checks a raw value yields: the value when it validates, else null with the problems. */
+export declare function loadChecks(raw: unknown): Loaded;
+/** True when p reaches the threshold; a null threshold never does. */
+export declare const reaches: (p: number, at: At) => boolean;
+export {};