@milesroxas/design-hub 0.0.0-stage → 0.1.0

package/dist/core/checks.js

@@ -0,0 +1,53 @@
+// The model and thresholds every Jev check reads, from one file in the
+// project: .design-hub/checks.json. `design-hub calibrate --write` rewrites it
+// from labelled judgments, so thresholds come from data, never from a
+// constant in a script. The model is pinned, not an alias: an alias moves on
+// a release, and the thresholds were set against one model. A file that does
+// not validate turns every Jev check off (and `design-hub preflight` reports
+// it), because a check must never block on a config typo. A project without
+// the file runs on DEFAULT_CHECKS.
+export const DEFAULT_CHECKS = {
+    jev: { model: 'jev-1.14.0', timeoutMs: 2000 },
+    fidelity: { warnAt: 0.7, blockAt: 0.9 },
+    states: { blockAt: 0.8 },
+    contacts: { privateAt: 0.5, allow: [] },
+    skillHint: { gateAt: 0.3, fitsAt: 0.3 },
+    triage: { at: 0.5 },
+    visual: { warnAt: 0.7 },
+};
+const isAt = (v) => v === null || (typeof v === 'number' && v >= 0 && v <= 1);
+const obj = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+/** Every problem with a checks object, by path; empty when it is valid. */
+export function validateChecks(value) {
+    const c = obj(value);
+    const problems = [];
+    const jev = obj(c.jev);
+    if (typeof jev.model !== 'string' || !jev.model)
+        problems.push('jev.model: a model name');
+    if (typeof jev.timeoutMs !== 'number' || jev.timeoutMs <= 0)
+        problems.push('jev.timeoutMs: milliseconds > 0');
+    const thresholds = [
+        ['fidelity', 'warnAt'],
+        ['fidelity', 'blockAt'],
+        ['states', 'blockAt'],
+        ['contacts', 'privateAt'],
+        ['skillHint', 'gateAt'],
+        ['skillHint', 'fitsAt'],
+        ['triage', 'at'],
+        ['visual', 'warnAt'],
+    ];
+    for (const [group, key] of thresholds)
+        if (!isAt(obj(c[group])[key]))
+            problems.push(`${group}.${key}: a probability from 0 to 1, or null`);
+    const allow = obj(c.contacts).allow;
+    if (!Array.isArray(allow) || !allow.every((a) => typeof a === 'string'))
+        problems.push('contacts.allow: a list of strings');
+    return problems;
+}
+/** The checks a raw value yields: the value when it validates, else null with the problems. */
+export function loadChecks(raw) {
+    const problems = validateChecks(raw);
+    return { checks: problems.length ? null : raw, problems };
+}
+/** True when p reaches the threshold; a null threshold never does. */
+export const reaches = (p, at) => at !== null && p >= at;

package/dist/core/contacts.d.ts

@@ -0,0 +1,9 @@
+export type Contact = {
+    kind: 'email' | 'phone';
+    value: string;
+    path: string;
+};
+/** Every contact in a string, in order of appearance. */
+export declare function contactsIn(text: string, path?: string): Contact[];
+/** Every contact in any string of a JSON value, with the path to it (`real[2].owner`). */
+export declare function contactsInJson(value: unknown, path?: string): Contact[];

package/dist/core/contacts.js

@@ -0,0 +1,34 @@
+// Emails and phone numbers in fixture data. A CMS pull can put a real
+// person's details behind a share link a client forwards, so the pre-flight
+// stops on every match until it is confirmed as a business contact. This is
+// the code half of the contact check; Jev, when on, only judges whether a
+// match is a private person or a public business.
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+// A run that starts and ends with a digit, may hold spaces, dots, dashes and
+// brackets, and is not glued to letters or digits on either side.
+const PHONE = /(?<![\w.+-])\+?\d[\d\s().-]{6,}\d(?![\w])/g;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}/;
+function phones(text) {
+    return [...text.matchAll(PHONE)]
+        .map((m) => m[0].trim())
+        .filter((v) => {
+        const digits = v.replace(/\D/g, '').length;
+        return digits >= 9 && digits <= 15 && !ISO_DATE.test(v);
+    });
+}
+/** Every contact in a string, in order of appearance. */
+export function contactsIn(text, path = '') {
+    const emails = [...text.matchAll(EMAIL)].map((m) => ({ kind: 'email', value: m[0], path }));
+    const withoutEmails = text.replace(EMAIL, ' ');
+    return [...emails, ...phones(withoutEmails).map((value) => ({ kind: 'phone', value, path }))];
+}
+/** Every contact in any string of a JSON value, with the path to it (`real[2].owner`). */
+export function contactsInJson(value, path = '') {
+    if (typeof value === 'string')
+        return contactsIn(value, path);
+    if (Array.isArray(value))
+        return value.flatMap((v, i) => contactsInJson(v, `${path}[${i}]`));
+    if (value && typeof value === 'object')
+        return Object.entries(value).flatMap(([k, v]) => contactsInJson(v, path ? `${path}.${k}` : k));
+    return [];
+}

package/dist/core/doc.d.ts

@@ -0,0 +1,11 @@
+export type TocEntry = {
+    id: string;
+    text: string;
+    depth: number;
+};
+export type Doc = {
+    meta: Record<string, string>;
+    title: string;
+    toc: TocEntry[];
+    html: string;
+};

package/dist/core/doc.js

@@ -0,0 +1 @@
+export {};

package/dist/core/feature.d.ts

@@ -0,0 +1,3 @@
+export declare const SLUG: RegExp;
+export declare const featureTitle: (slug: string) => string;
+export declare const guideHref: (feature: string) => string;

package/dist/core/feature.js

@@ -0,0 +1,4 @@
+// The feature slug names docs/sprints/<feature>/ and a prototype's `feature:`. One rule for its shape and its display name.
+export const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export const featureTitle = (slug) => slug.replace(/-/g, ' ').replace(/^\w/, (c) => c.toUpperCase());
+export const guideHref = (feature) => `/guide/${feature}/`;

package/dist/core/fixtures.d.ts

@@ -0,0 +1,19 @@
+export declare const SET_NAMES: readonly ['real', 'longest', 'empty', 'max', 'missing'];
+export type SetName = (typeof SET_NAMES)[number];
+export type FixtureSets<T> = Record<SetName, T[]>;
+type Source<T> = {
+    real: T[];
+    missing: T[];
+} & Partial<Record<SetName, T[]>>;
+/** The keys of T whose values are strings: the only fields `longest` can stretch. */
+type TextKey<T> = {
+    [K in keyof T & string]: T[K] extends string | null | undefined ? K : never;
+}[keyof T & string];
+type Options<T> = {
+    /** The design's maximum count, for `max`. */
+    max: number;
+    /** The free-text fields a reviewer reads (a name, a title), for `longest`. */
+    text: readonly TextKey<T>[];
+};
+export declare function fixtureSets<T extends Record<string, unknown>>(source: Source<T>, { max, text }: Options<T>): FixtureSets<T>;
+export {};

package/dist/core/fixtures.js

@@ -0,0 +1,52 @@
+// Hostile fixture sets, derived from the real ones so Claude never writes
+// them by hand. A feature's fixtures.json holds `real` (pulled from the CMS
+// or copied from the comp) and `missing` (the item with no image, no link,
+// hand-written because no rule can derive it). This file fills in the rest:
+//
+//   longest  the first item carries, in each free-text field the component
+//            names (`text`), the longest real value for that field doubled,
+//            because the CMS will hold a longer title than anything in it
+//            today; the other items stay real, so the monster row is judged
+//            beside normal ones. Only named fields stretch: a doubled date,
+//            status or URL is not a longer value, it is a broken one
+//   empty    nothing
+//   max      the real items repeated up to the design's maximum count, ids
+//            made unique so React keys hold
+//
+// A set written in the JSON by hand wins over the derived one, so a feature
+// can replace any of them when its component needs something the rule
+// cannot know.
+export const SET_NAMES = ['real', 'longest', 'empty', 'max', 'missing'];
+export function fixtureSets(source, { max, text }) {
+    return {
+        real: source.real,
+        longest: source.longest ?? longest(source.real, text),
+        empty: source.empty ?? [],
+        max: source.max ?? repeat(source.real, max),
+        missing: source.missing,
+    };
+}
+function longest(real, text) {
+    const [first, ...rest] = real;
+    if (!first)
+        return [];
+    const hostile = { ...first };
+    for (const key of text) {
+        const widest = real
+            .map((item) => item[key])
+            .filter((v) => typeof v === 'string')
+            .reduce((a, b) => (b.length > a.length ? b : a), '');
+        if (widest)
+            hostile[key] = `${widest} ${widest}`;
+    }
+    return [hostile, ...rest];
+}
+function repeat(real, count) {
+    if (!real.length)
+        return [];
+    return Array.from({ length: count }, (_, i) => {
+        const item = real[i % real.length];
+        const round = Math.floor(i / real.length);
+        return round === 0 || !('id' in item) ? item : { ...item, id: `${String(item.id)}-${round}` };
+    });
+}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,4 @@
+export declare function frontmatter(md: string): {
+    data: Record<string, string>;
+    body: string;
+};

package/dist/core/frontmatter.js

@@ -0,0 +1,15 @@
+// The YAML block at the top of a Markdown file, read as flat `key: value`
+// pairs. Shared by the index (in the browser) and the ?doc plugin (in Node).
+export function frontmatter(md) {
+    const match = md.match(/^---\n([\s\S]*?)\n---\n?/);
+    const data = {};
+    for (const line of (match?.[1] ?? '').split('\n')) {
+        const at = line.indexOf(':');
+        if (at > 0)
+            data[line.slice(0, at).trim()] = line
+                .slice(at + 1)
+                .trim()
+                .replace(/^["']|["']$/g, '');
+    }
+    return { data, body: match ? md.slice(match[0].length) : md };
+}

package/dist/core/html.d.ts

@@ -0,0 +1,2 @@
+/** Text made safe to place in HTML content or a double-quoted attribute. */
+export declare const escapeHtml: (s: string) => string;

package/dist/core/html.js

@@ -0,0 +1,2 @@
+/** Text made safe to place in HTML content or a double-quoted attribute. */
+export const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');

package/dist/core/image.d.ts

@@ -0,0 +1,6 @@
+export type ImageSize = {
+    width: number;
+    height: number;
+    format: 'png' | 'jpg';
+};
+export declare const imageSize: (bytes: Uint8Array) => ImageSize | null;

package/dist/core/image.js

@@ -0,0 +1,34 @@
+// Pixel size from an image's header, without decoding it: PNG from its IHDR
+// chunk, JPEG from its first frame header. The walkthrough compiler sizes
+// figures with it, and the visual match checks TypeSafe's image limits.
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const u16 = (b, i) => (b[i] << 8) | b[i + 1];
+const u32 = (b, i) => ((b[i] << 24) | (b[i + 1] << 16) | (b[i + 2] << 8) | b[i + 3]) >>> 0;
+function pngSize(b) {
+    if (b.length < 24 || PNG_SIGNATURE.some((v, i) => b[i] !== v))
+        return null;
+    return { width: u32(b, 16), height: u32(b, 20), format: 'png' };
+}
+// Markers with no length field: start of image, TEM, and the restart markers.
+const standalone = (m) => m === 0xd8 || m === 0x01 || (m >= 0xd0 && m <= 0xd7);
+// SOF0 to SOF15 carry the frame size, except DHT (C4), JPG (C8) and DAC (CC).
+const frame = (m) => m >= 0xc0 && m <= 0xcf && m !== 0xc4 && m !== 0xc8 && m !== 0xcc;
+function jpegSize(b) {
+    if (b[0] !== 0xff || b[1] !== 0xd8)
+        return null;
+    let i = 2;
+    while (i + 9 < b.length) {
+        const marker = b[i + 1];
+        // A byte that is not a marker, or 0xFF fill before one, moves on by one.
+        if (b[i] !== 0xff || marker === 0xff)
+            i += 1;
+        else if (standalone(marker))
+            i += 2;
+        else if (frame(marker))
+            return { height: u16(b, i + 5), width: u16(b, i + 7), format: 'jpg' };
+        else
+            i += 2 + u16(b, i + 2);
+    }
+    return null;
+}
+export const imageSize = (bytes) => pngSize(bytes) ?? jpegSize(bytes);

package/dist/core/jev.d.ts

@@ -0,0 +1,54 @@
+export type Question = {
+    type: 'noul';
+    instructions: string;
+} | {
+    type: 'choice';
+    instructions: string;
+    criteria: Record<string, string | null>;
+};
+export type Answer = {
+    type: 'noul';
+    noul: number;
+} | {
+    type: 'choice';
+    choice: string;
+    confidence: number;
+    probabilities: Record<string, number>;
+};
+/** An image the state or a question refers to by its key. Experimental on TypeSafe's side. */
+export type ImageAsset = {
+    type: 'image';
+    format: 'png' | 'jpg' | 'jpeg';
+    data_base64: string;
+};
+export type JevRequest = {
+    model: string;
+    state: unknown;
+    questions: Record<string, Question>;
+    assets?: Record<string, ImageAsset>;
+};
+export type JevResult = {
+    ok: true;
+    model: string;
+    answers: Record<string, Answer>;
+    ms: number;
+} | {
+    ok: false;
+    error: string;
+    ms: number;
+};
+type Options = {
+    timeoutMs: number;
+    fetch?: typeof fetch;
+};
+export declare function askJev(apiKey: string, request: JevRequest, options: Options): Promise<JevResult>;
+/** The yes-probability of a Noul answer, or null when it is missing or another type. */
+export declare const noulOf: (answers: Record<string, Answer>, key: string) => number | null;
+/** A Choice answer, or null when it is missing or another type. */
+export declare const choiceOf: (answers: Record<string, Answer>, key: string) => {
+    type: 'choice';
+    choice: string;
+    confidence: number;
+    probabilities: Record<string, number>;
+} | null;
+export {};

package/dist/core/jev.js

@@ -0,0 +1,52 @@
+// One client for TypeSafe's Jev (System One), on plain fetch, so the same
+// code runs in the scripts and in the Vercel server code with no SDK to
+// install. API: https://docs.typesafe.ai/api/system-one.md
+//
+// It never throws and never retries. Every caller treats a failure the same
+// way, fail open: a check is never the reason the user is blocked, and a
+// retry would only spend the latency budget the caller set.
+const JEV_URL = 'https://api.typesafe.ai/v1/systemone';
+export async function askJev(apiKey, request, options) {
+    const started = Date.now();
+    const ms = () => Date.now() - started;
+    const headers = {
+        authorization: `Bearer ${apiKey}`,
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    // Images sit behind TypeSafe's "danger zone" header; without it the request is a 400.
+    if (request.assets && Object.keys(request.assets).length)
+        headers['typesafe-danger-zone-images'] = 'true';
+    try {
+        const response = await (options.fetch ?? fetch)(JEV_URL, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(request),
+            signal: AbortSignal.timeout(options.timeoutMs),
+        });
+        if (!response.ok) {
+            const id = response.headers.get('x-typesafe-request-id');
+            const body = (await response.text()).slice(0, 300);
+            return { ok: false, error: `${response.status}${id ? ` (${id})` : ''}: ${body}`, ms: ms() };
+        }
+        const json = (await response.json());
+        if (!json.answers)
+            return { ok: false, error: 'response had no answers', ms: ms() };
+        return { ok: true, model: json.model ?? request.model, answers: json.answers, ms: ms() };
+    }
+    catch (error) {
+        const name = error instanceof Error ? error.name : '';
+        const error_ = name === 'TimeoutError' ? `timeout after ${options.timeoutMs}ms` : String(error);
+        return { ok: false, error: error_, ms: ms() };
+    }
+}
+/** The yes-probability of a Noul answer, or null when it is missing or another type. */
+export const noulOf = (answers, key) => {
+    const a = answers[key];
+    return a?.type === 'noul' && typeof a.noul === 'number' ? a.noul : null;
+};
+/** A Choice answer, or null when it is missing or another type. */
+export const choiceOf = (answers, key) => {
+    const a = answers[key];
+    return a?.type === 'choice' ? a : null;
+};

package/dist/core/review/model.d.ts

@@ -0,0 +1,85 @@
+export declare const ROLES: readonly ['editor', 'reviewer'];
+export type Role = (typeof ROLES)[number];
+/** How a comment is triaged: something broken, a design opinion, or the words. */
+export declare const KINDS: readonly ['bug', 'taste', 'copy'];
+export type Kind = (typeof KINDS)[number];
+/** How long an invite link signs its person in before an editor must issue a new one. */
+export declare const INVITE_DAYS = 14;
+export declare const LIMITS: {
+    readonly name: 80;
+    readonly team: 80;
+    readonly body: 4000;
+    readonly url: 2000;
+    readonly target: 500;
+    readonly dialsChars: 8000;
+    readonly states: 50;
+    readonly stateName: 120;
+};
+export type Person = {
+    id: string;
+    name: string;
+    /** The group a person belongs to, shown beside their name: the studio, or the client's company. */
+    team: string;
+    role: Role;
+    createdAt: string;
+    revokedAt: string | null;
+    /** Bumped on revoke and on a new invite, which signs out every session signed with the old one. */
+    epoch: number;
+};
+/** A comment's author as it was when they wrote it, so a revoked person's comments still read. */
+export type Author = Pick<Person, 'id' | 'name' | 'team'>;
+export type Anchor = {
+    prototype: string;
+    feature: string;
+    /** Path, query and hash when the comment was written: reopening it reopens the state. */
+    url: string;
+    /** Every dial panel's values by panel name, so the state includes what the dials were set to. */
+    dials: Record<string, Record<string, unknown>>;
+    /** A CSS selector for the element the pin sits on, or null for the page as a whole. */
+    target: string | null;
+    /** Where on the target, as fractions of its box. */
+    offset: {
+        x: number;
+        y: number;
+    } | null;
+    viewport: {
+        width: number;
+        height: number;
+    };
+};
+export type Triage = {
+    kind: Kind | null;
+    /** A row of the prototype README's States table. */
+    state: string | null;
+    by: 'jev' | 'person';
+    confidence: number | null;
+};
+export type Comment = {
+    id: string;
+    /** The root comment's id; a root's thread is its own id. */
+    thread: string;
+    author: Author;
+    body: string;
+    createdAt: string;
+    editedAt: string | null;
+    /** Roots only. */
+    anchor: Anchor | null;
+    status: 'open' | 'resolved';
+    resolvedBy: Author | null;
+    triage: Triage | null;
+};
+export declare const authorOf: (p: Person) => Author;
+export declare const isRoot: (c: Comment) => boolean;
+export type Checked<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    problems: string[];
+};
+export declare function checkPersonInput(input: unknown): Checked<Pick<Person, 'name' | 'team' | 'role'>>;
+export declare function checkBody(body: unknown): Checked<string>;
+export declare function checkAnchor(input: unknown): Checked<Anchor>;
+/** The README states a client offers for triage: trimmed, capped, de-duplicated. */
+export declare function checkStates(input: unknown): string[];
+export declare function checkTriage(input: unknown, states: string[] | null): Checked<Pick<Triage, 'kind' | 'state'>>;

package/dist/core/review/model.js

@@ -0,0 +1,112 @@
+// The review domain: people who may comment on the deployed prototypes, and
+// the comments they leave, pinned to a prototype, its state and an element.
+// Pure: no I/O, no environment. Every limit and rule lives here once and is
+// enforced by the service, whichever adapter (Vercel, Vite dev, the CLI)
+// calls it.
+import { SLUG } from '../feature.js';
+export const ROLES = ['editor', 'reviewer'];
+/** How a comment is triaged: something broken, a design opinion, or the words. */
+export const KINDS = ['bug', 'taste', 'copy'];
+/** How long an invite link signs its person in before an editor must issue a new one. */
+export const INVITE_DAYS = 14;
+export const LIMITS = {
+    name: 80,
+    team: 80,
+    body: 4000,
+    url: 2000,
+    target: 500,
+    dialsChars: 8000,
+    states: 50,
+    stateName: 120,
+};
+export const authorOf = (p) => ({ id: p.id, name: p.name, team: p.team });
+export const isRoot = (c) => c.thread === c.id;
+const text = (v, path, max, problems) => {
+    if (typeof v !== 'string' || !v.trim()) {
+        problems.push(`${path}: required`);
+        return '';
+    }
+    const s = v.trim();
+    if (s.length > max)
+        problems.push(`${path}: ${max} characters at most`);
+    return s;
+};
+const fraction = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+const size = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v < 100_000;
+export function checkPersonInput(input) {
+    const i = (input ?? {});
+    const problems = [];
+    const name = text(i.name, 'name', LIMITS.name, problems);
+    const team = text(i.team, 'team', LIMITS.team, problems);
+    const role = i.role ?? 'reviewer';
+    if (!ROLES.includes(role))
+        problems.push(`role: one of ${ROLES.join(', ')}`);
+    return problems.length ? { ok: false, problems } : { ok: true, value: { name, team, role: role } };
+}
+export function checkBody(body) {
+    const problems = [];
+    const value = text(body, 'body', LIMITS.body, problems);
+    return problems.length ? { ok: false, problems } : { ok: true, value };
+}
+const isSlug = (v) => typeof v === 'string' && SLUG.test(v);
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** One rule per field: the field, whether a value passes, and what the field must be. */
+const ANCHOR_RULES = [
+    ['prototype', isSlug, 'a prototype slug'],
+    ['feature', (v) => v === '' || isSlug(v), 'a feature slug or empty'],
+    [
+        'url',
+        (v) => typeof v === 'string' && v.startsWith('/') && v.length <= LIMITS.url,
+        `a path starting with /, ${LIMITS.url} characters at most`,
+    ],
+    [
+        'dials',
+        (v) => isObject(v) && JSON.stringify(v).length <= LIMITS.dialsChars,
+        `an object of panels, ${LIMITS.dialsChars} characters at most`,
+    ],
+    [
+        'target',
+        (v) => v === null || (typeof v === 'string' && v.length <= LIMITS.target),
+        `a selector, ${LIMITS.target} characters at most, or null`,
+    ],
+    [
+        'offset',
+        (v) => v === null || (isObject(v) && fraction(v.x) && fraction(v.y)),
+        'x and y from 0 to 1, or null',
+    ],
+    ['viewport', (v) => isObject(v) && size(v.width) && size(v.height), 'width and height in pixels'],
+];
+export function checkAnchor(input) {
+    const given = isObject(input) ? input : {};
+    // Absent optional fields take their empty form before the rules run.
+    const a = { dials: {}, target: null, offset: null, ...given };
+    const problems = ANCHOR_RULES.filter(([key, passes]) => !passes(a[key])).map(([key, , must]) => `anchor.${key}: ${must}`);
+    if (problems.length)
+        return { ok: false, problems };
+    // Every rule passed, so each field holds its Anchor type.
+    const { prototype, feature, url, dials, target, offset, viewport } = a;
+    return { ok: true, value: { prototype, feature, url, dials, target, offset, viewport } };
+}
+/** The README states a client offers for triage: trimmed, capped, de-duplicated. */
+export function checkStates(input) {
+    if (!Array.isArray(input))
+        return [];
+    const names = input
+        .filter((s) => typeof s === 'string')
+        .map((s) => s.trim().slice(0, LIMITS.stateName));
+    return [...new Set(names.filter(Boolean))].slice(0, LIMITS.states);
+}
+export function checkTriage(input, states) {
+    const t = (input ?? {});
+    const problems = [];
+    const kind = t.kind ?? null;
+    if (kind !== null && !KINDS.includes(kind))
+        problems.push(`triage.kind: one of ${KINDS.join(', ')}, or null`);
+    const state = t.state ?? null;
+    if (state !== null &&
+        (typeof state !== 'string' || state.length > LIMITS.stateName || (states && !states.includes(state))))
+        problems.push('triage.state: a row of the States table, or null');
+    return problems.length
+        ? { ok: false, problems }
+        : { ok: true, value: { kind: kind, state: state } };
+}

package/dist/core/review/policy.d.ts

@@ -0,0 +1,3 @@
+import type { Comment, Person } from './model.ts';
+export type Action = 'read' | 'comment' | 'edit' | 'delete' | 'resolve' | 'triage' | 'people';
+export declare function can(actor: Person | null, action: Action, subject?: Comment): boolean;

package/dist/core/review/policy.js

@@ -0,0 +1,19 @@
+export function can(actor, action, subject) {
+    if (!actor || actor.revokedAt)
+        return false;
+    const editor = actor.role === 'editor';
+    const own = subject?.author.id === actor.id;
+    switch (action) {
+        case 'read':
+        case 'comment':
+            return true;
+        case 'edit':
+            return own;
+        case 'delete':
+        case 'resolve':
+            return own || editor;
+        case 'triage':
+        case 'people':
+            return editor;
+    }
+}