@fragments-sdk/classifier 0.2.0

package/src/ai/version.ts

@@ -0,0 +1,15 @@
+// Prompt version — bumped when §12.3 changes. Embedded in the cache key
+// so that an old cached classification cannot satisfy a newer prompt.
+export const AI_PROMPT_VERSION = 'aiprompt_v1';
+
+// §12.4 hardening: we hard-cap the model's `reasoning` field at this many
+// chars before persisting. Above this, the field is truncated; the model
+// is also instructed in the prompt that reasoning must be ≤80 words.
+export const AI_REASONING_CHAR_CAP = 200;
+
+// §9.9 — the AI signal weights, keyed by the model's reported confidence.
+export const AI_SIGNAL_WEIGHTS = {
+  high: 0.4,
+  medium: 0.25,
+  low: 0.1,
+} as const;

package/src/canonical-vocab/resolve-by-html-element.ts

@@ -0,0 +1,72 @@
+/**
+ * Tag → canonical resolver shared by:
+ *  - `swap_to_canonical` MCP tool (`packages/mcp/src/tools/swap-to-canonical.ts`)
+ *  - PR-review advisor (`apps/cloud/src/lib/pr-advisor/cluster-by-file.ts`)
+ *
+ * Both surfaces must produce identical canonical resolutions for the same
+ * input — kept in one module so a tag added in one place is automatically
+ * available to the other.
+ *
+ * Generic containers (`div`, `span`, `form`, `label`) are intentionally
+ * absent: a swap suggestion for layout markup would drown the user in
+ * noise, since every codebase uses layout primitives liberally.
+ */
+
+export interface RawAttrLike {
+  value: string;
+  dynamic: boolean;
+}
+
+export type RawAttrMap = Map<string, RawAttrLike>;
+
+export function resolveCanonicalForHtmlElement(
+  tagName: string,
+  attrs: RawAttrMap,
+): string | null {
+  switch (tagName) {
+    case 'button':
+      return 'Button';
+    case 'input': {
+      const type = attrs.get('type')?.value ?? 'text';
+      switch (type) {
+        case 'checkbox':
+          return 'Checkbox';
+        case 'radio':
+          return 'Radio';
+        case 'number':
+          return 'NumberInput';
+        case 'password':
+          return 'PasswordInput';
+        case 'range':
+          return 'Slider';
+        default:
+          return 'Input';
+      }
+    }
+    case 'textarea':
+      return 'Textarea';
+    case 'select':
+      return 'Select';
+    case 'dialog':
+      return 'Dialog';
+    case 'progress':
+      return 'Progress';
+    case 'details':
+      return 'Disclosure';
+    case 'table':
+      return 'Table';
+    default:
+      return null;
+  }
+}
+
+/** Render a raw element to a short label (`<button>` / `<input type="checkbox">`). */
+export function formatRawHtmlElement(
+  tagName: string,
+  attrs: RawAttrMap,
+): string {
+  if (tagName === 'input' && attrs.has('type')) {
+    return `<input type="${attrs.get('type')!.value}">`;
+  }
+  return `<${tagName}>`;
+}

package/src/combiner/__tests__/band.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest';
+
+import type { Band } from '../../types.js';
+import { deriveBand, type BandInput } from '../band.js';
+
+function input(partial: Partial<BandInput>): BandInput {
+  return {
+    adjustedConfidence: 0,
+    distinctStrongTypes: 0,
+    totalLeadingSignalCount: 0,
+    hasStrongSignal: false,
+    hasHighDisagreement: false,
+    isTied: false,
+    ...partial,
+  };
+}
+
+describe('deriveBand', () => {
+  describe('auto', () => {
+    it('lands at auto when adjusted >= 0.83 with two distinct strong types', () => {
+      expect(
+        deriveBand(
+          input({
+            adjustedConfidence: 0.839,
+            distinctStrongTypes: 3,
+            totalLeadingSignalCount: 4,
+            hasStrongSignal: true,
+          }),
+        ),
+      ).toBe<Band>('auto');
+    });
+
+    it('does not auto with only one distinct strong type', () => {
+      expect(
+        deriveBand(
+          input({
+            adjustedConfidence: 0.9,
+            distinctStrongTypes: 1,
+            totalLeadingSignalCount: 1,
+            hasStrongSignal: true,
+          }),
+        ),
+      ).toBe<Band>('suggested');
+    });
+
+    it('does not auto when high disagreement is present', () => {
+      expect(
+        deriveBand(
+          input({
+            adjustedConfidence: 0.9,
+            distinctStrongTypes: 2,
+            totalLeadingSignalCount: 2,
+            hasStrongSignal: true,
+            hasHighDisagreement: true,
+          }),
+        ),
+      ).toBe<Band>('possible');
+    });
+  });
+
+  describe('suggested', () => {
+    it('lands at suggested for the §10.1 dialog example (0.732)', () => {
+      expect(
+        deriveBand(
+          input({
+            adjustedConfidence: 0.732,
+            distinctStrongTypes: 2,
+            totalLeadingSignalCount: 3,
+            hasStrongSignal: true,
+          }),
+        ),
+      ).toBe<Band>('suggested');
+    });
+
+    it('demotes to possible when high disagreement is present', () => {
+      expect(
+        deriveBand(
+          input({
+            adjustedConfidence: 0.7,
+            distinctStrongTypes: 1,
+            totalLeadingSignalCount: 2,
+            hasStrongSignal: true,
+            hasHighDisagreement: true,
+          }),
+        ),
+      ).toBe<Band>('possible');
+    });
+  });
+
+  describe('possible', () => {
+    it('returns possible for the §10.2 disagreement case (0.349)', () => {
+      expect(
+        deriveBand(
+          input({
+            adjustedConfidence: 0.349,
+            distinctStrongTypes: 1,
+            totalLeadingSignalCount: 1,
+            hasStrongSignal: true,
+          }),
+        ),
+      ).toBe<Band>('possible');
+    });
+
+    it('requires at least one signal of any weight', () => {
+      expect(
+        deriveBand(
+          input({ adjustedConfidence: 0.4, totalLeadingSignalCount: 0 }),
+        ),
+      ).toBe<Band>('unknown');
+    });
+  });
+
+  describe('unknown', () => {
+    it('lands at unknown when adjusted < 0.3', () => {
+      expect(
+        deriveBand(
+          input({
+            adjustedConfidence: 0.235,
+            totalLeadingSignalCount: 2,
+          }),
+        ),
+      ).toBe<Band>('unknown');
+    });
+  });
+
+  describe('tied', () => {
+    it('forces suggested when isTied is set', () => {
+      expect(
+        deriveBand(
+          input({
+            adjustedConfidence: 0.399,
+            distinctStrongTypes: 1,
+            totalLeadingSignalCount: 1,
+            hasStrongSignal: true,
+            isTied: true,
+          }),
+        ),
+      ).toBe<Band>('suggested');
+    });
+
+    it('demotes from auto to suggested when tied', () => {
+      expect(
+        deriveBand(
+          input({
+            adjustedConfidence: 0.95,
+            distinctStrongTypes: 3,
+            totalLeadingSignalCount: 4,
+            hasStrongSignal: true,
+            isTied: true,
+          }),
+        ),
+      ).toBe<Band>('suggested');
+    });
+  });
+});

package/src/combiner/__tests__/group.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+
+import { canonicalId, type SignalRecord } from '../../types.js';
+import { groupAndCompose } from '../group.js';
+
+const Dialog = canonicalId('Dialog');
+const Button = canonicalId('Button');
+
+function sig(
+  type: SignalRecord['type'],
+  canonical: SignalRecord['canonical'],
+  weight: number,
+): SignalRecord {
+  return { type, canonical, weight, evidence: {} };
+}
+
+describe('groupAndCompose', () => {
+  it('returns empty array for empty input', () => {
+    expect(groupAndCompose([])).toEqual([]);
+  });
+
+  it('reproduces the §10.1 dialog example: 1 - (1-0.55)(1-0.3)(1-0.15) = 0.732', () => {
+    const result = groupAndCompose([
+      sig('LIBRARY_REEXPORT', Dialog, 0.55),
+      sig('PROP_FINGERPRINT', Dialog, 0.3),
+      sig('NAME_MATCH', Dialog, 0.15),
+    ]);
+    expect(result).toHaveLength(1);
+    expect(result[0].canonical).toBe(Dialog);
+    expect(result[0].confidence).toBeCloseTo(0.732, 3);
+  });
+
+  it('groups separate canonicals into independent hypotheses', () => {
+    const result = groupAndCompose([
+      sig('HTML_ROOT', Button, 0.45),
+      sig('NAME_MATCH', Dialog, 0.15),
+    ]);
+    expect(result).toHaveLength(2);
+    const button = result.find((g) => g.canonical === Button);
+    const dialog = result.find((g) => g.canonical === Dialog);
+    expect(button?.confidence).toBeCloseTo(0.45, 3);
+    expect(dialog?.confidence).toBeCloseTo(0.15, 3);
+  });
+
+  it('counts distinct strong signal types per canonical', () => {
+    const result = groupAndCompose([
+      sig('LIBRARY_REEXPORT', Dialog, 0.55),
+      sig('PROP_FINGERPRINT', Dialog, 0.3),
+      sig('NAME_MATCH', Dialog, 0.15),
+    ]);
+    expect(result[0].distinctStrongTypes.size).toBe(2);
+    expect(result[0].distinctStrongTypes.has('LIBRARY_REEXPORT')).toBe(true);
+    expect(result[0].distinctStrongTypes.has('PROP_FINGERPRINT')).toBe(true);
+    expect(result[0].distinctStrongTypes.has('NAME_MATCH')).toBe(false);
+  });
+
+  it('treats two records of the same strong type as one distinct strong type', () => {
+    const result = groupAndCompose([
+      sig('LIBRARY_REEXPORT', Dialog, 0.55),
+      sig('LIBRARY_REEXPORT', Dialog, 0.55),
+    ]);
+    expect(result[0].distinctStrongTypes.size).toBe(1);
+  });
+
+  it('sorts signals inside a group by weight desc, then type asc', () => {
+    const result = groupAndCompose([
+      sig('NAME_MATCH', Dialog, 0.15),
+      sig('PROP_FINGERPRINT', Dialog, 0.3),
+      sig('LIBRARY_REEXPORT', Dialog, 0.55),
+    ]);
+    expect(result[0].signals.map((s) => s.type)).toEqual([
+      'LIBRARY_REEXPORT',
+      'PROP_FINGERPRINT',
+      'NAME_MATCH',
+    ]);
+  });
+
+  it('caps composed confidence at 1.0', () => {
+    const result = groupAndCompose([
+      sig('LIBRARY_REEXPORT', Dialog, 1.0),
+      sig('AI_SEMANTIC', Dialog, 0.4),
+    ]);
+    expect(result[0].confidence).toBe(1);
+  });
+});

package/src/combiner/__tests__/rank.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+
+import { canonicalId, type SignalType } from '../../types.js';
+import type { GroupedHypothesis } from '../group.js';
+import { rank } from '../rank.js';
+
+function group(
+  canonical: string,
+  confidence: number,
+  strongTypes: SignalType[] = [],
+): GroupedHypothesis {
+  return {
+    canonical: canonicalId(canonical),
+    confidence,
+    signals: [],
+    distinctStrongTypes: new Set(strongTypes),
+  };
+}
+
+describe('rank', () => {
+  it('returns null leading for empty groups', () => {
+    const r = rank([]);
+    expect(r.leading).toBeNull();
+    expect(r.adjustedLeadingConfidence).toBe(0);
+    expect(r.alternates).toEqual([]);
+  });
+
+  it('picks the highest-confidence group as leading', () => {
+    const r = rank([group('Button', 0.7), group('Dialog', 0.4)]);
+    expect(r.leading?.canonical).toBe('Button');
+    expect(r.alternates.map((a) => a.canonical)).toEqual(['Dialog']);
+  });
+
+  it('breaks confidence ties alphabetically by canonical id', () => {
+    const r = rank([group('IconButton', 0.55), group('Button', 0.55)]);
+    expect(r.leading?.canonical).toBe('Button');
+    expect(r.alternates[0].canonical).toBe('IconButton');
+  });
+
+  it('applies the disagreement penalty per §10.2', () => {
+    // HTML_ROOT(Button, 0.45) + ARIA_ROLE(Link, 0.45) → Button leads,
+    // adjusted = 0.45 × (1 - 0.45 × 0.5) = 0.349.
+    const r = rank([group('Button', 0.45), group('Link', 0.45)]);
+    expect(r.rawLeadingConfidence).toBeCloseTo(0.45, 3);
+    expect(r.adjustedLeadingConfidence).toBeCloseTo(0.349, 3);
+    expect(r.maxAlternateConfidence).toBeCloseTo(0.45, 3);
+  });
+
+  it('leaves a singleton hypothesis unpenalised', () => {
+    const r = rank([group('Dialog', 0.732)]);
+    expect(r.adjustedLeadingConfidence).toBeCloseTo(0.732, 3);
+    expect(r.maxAlternateConfidence).toBe(0);
+  });
+});

package/src/combiner/band.ts

@@ -0,0 +1,85 @@
+// Band derivation — `01-architecture.md` §10.3 + §10.4.
+//
+// Pure mapping from `(adjustedConfidence, distinctStrongTypes,
+// totalSignalCount, hasStrongSignal, hasHighDisagreement, isTied)` to
+// one of `auto | suggested | possible | unknown`.
+//
+// Strict rules from the brief:
+//   - "Strong" means weight >= 0.3.
+//   - `auto` requires two distinct strong signal *types* — not two
+//     records of the same type. The combiner counts distinct types only.
+//   - `auto` is forbidden when any non-leading hypothesis composes to
+//     `confidence >= 0.6` (high disagreement).
+//   - Tied = top-two within 0.1 absolute confidence; tie demotes the
+//     band to `suggested` regardless of signal count.
+//
+// Threshold deviation from spec: `auto` lower bound is 0.83, not 0.85.
+// Spec §10.1's worked example explicitly classifies confidence 0.839
+// as `auto` and ACCEPTANCE §5 reproduces that case verbatim. The 0.85
+// figure in §10.3's table is internally inconsistent with §10.1.
+// 0.83 is the smallest threshold that matches both the example and the
+// acceptance contract; documented in brief 04 Deviations.
+
+import type { Band } from '../types.js';
+
+export const STRONG_WEIGHT = 0.3;
+export const AUTO_CONFIDENCE_FLOOR = 0.83;
+export const SUGGESTED_CONFIDENCE_FLOOR = 0.6;
+export const POSSIBLE_CONFIDENCE_FLOOR = 0.3;
+export const HIGH_DISAGREEMENT_FLOOR = 0.6;
+export const TIE_WINDOW = 0.1;
+// Tie demotion fires only when the leading raw confidence is at least
+// `TIE_FIRES_FROM`. Otherwise two weak alternates (e.g. ARIA_ROLE for
+// Link 0.45 vs HTML_ROOT for Button 0.45 in the §10.2 example) would
+// be incorrectly forced into `suggested` rather than landing naturally
+// at `possible`.
+export const TIE_FIRES_FROM = 0.5;
+
+export interface BandInput {
+  adjustedConfidence: number;
+  distinctStrongTypes: number;
+  totalLeadingSignalCount: number;
+  hasStrongSignal: boolean;
+  hasHighDisagreement: boolean;
+  isTied: boolean;
+}
+
+export function deriveBand(input: BandInput): Band {
+  const {
+    adjustedConfidence,
+    distinctStrongTypes,
+    totalLeadingSignalCount,
+    hasStrongSignal,
+    hasHighDisagreement,
+    isTied,
+  } = input;
+
+  if (isTied) {
+    return 'suggested';
+  }
+
+  if (
+    adjustedConfidence >= AUTO_CONFIDENCE_FLOOR &&
+    distinctStrongTypes >= 2 &&
+    !hasHighDisagreement
+  ) {
+    return 'auto';
+  }
+
+  if (
+    adjustedConfidence >= SUGGESTED_CONFIDENCE_FLOOR &&
+    hasStrongSignal &&
+    !hasHighDisagreement
+  ) {
+    return 'suggested';
+  }
+
+  if (
+    adjustedConfidence >= POSSIBLE_CONFIDENCE_FLOOR &&
+    totalLeadingSignalCount >= 1
+  ) {
+    return 'possible';
+  }
+
+  return 'unknown';
+}

package/src/combiner/group.ts

@@ -0,0 +1,62 @@
+// Group + compose — `01-architecture.md` §10.1.
+//
+// Groups signal records by canonical and applies independent-event
+// probability composition `confidence(C) = 1 - ∏ (1 - wᵢ)`. The product
+// caps at 1.0 so redundant strong signals are cumulative-but-discounted.
+//
+// Pure: no I/O, no clock. Output ordering is deterministic — signals
+// inside each group are sorted by weight desc (then type ascending) so
+// snapshot tests stay stable.
+
+import type {
+  CanonicalId,
+  SignalRecord,
+  SignalType,
+} from '../types.js';
+
+export interface GroupedHypothesis {
+  canonical: CanonicalId;
+  confidence: number;
+  signals: SignalRecord[];
+  distinctStrongTypes: Set<SignalType>;
+}
+
+const STRONG_WEIGHT = 0.3;
+
+export function groupAndCompose(signals: SignalRecord[]): GroupedHypothesis[] {
+  const buckets = new Map<CanonicalId, SignalRecord[]>();
+  for (const sig of signals) {
+    const bucket = buckets.get(sig.canonical);
+    if (bucket) {
+      bucket.push(sig);
+    } else {
+      buckets.set(sig.canonical, [sig]);
+    }
+  }
+
+  const out: GroupedHypothesis[] = [];
+  for (const [canonical, group] of buckets) {
+    const sorted = [...group].sort(compareSignalsForOutput);
+    let product = 1;
+    const distinctStrongTypes = new Set<SignalType>();
+    for (const sig of sorted) {
+      product *= 1 - sig.weight;
+      if (sig.weight >= STRONG_WEIGHT) {
+        distinctStrongTypes.add(sig.type);
+      }
+    }
+    out.push({
+      canonical,
+      confidence: 1 - product,
+      signals: sorted,
+      distinctStrongTypes,
+    });
+  }
+
+  return out;
+}
+
+function compareSignalsForOutput(a: SignalRecord, b: SignalRecord): number {
+  if (b.weight !== a.weight) return b.weight - a.weight;
+  return a.type.localeCompare(b.type);
+}

package/src/combiner/rank.ts

@@ -0,0 +1,57 @@
+// Rank + disagreement penalty — `01-architecture.md` §10.2.
+//
+// Picks the leading hypothesis by composed confidence, computes the max
+// alternate confidence, and applies the disagreement penalty to the
+// leading hypothesis only:
+//
+//   adjusted_leading = leading × (1 - max_alternate × 0.5)
+//
+// Ties on confidence resolve alphabetically by canonical id so the
+// pipeline output is deterministic across runs (idempotence per §11.2).
+
+import type { GroupedHypothesis } from './group.js';
+
+export interface RankResult {
+  leading: GroupedHypothesis | null;
+  rawLeadingConfidence: number;
+  adjustedLeadingConfidence: number;
+  alternates: GroupedHypothesis[];
+  maxAlternateConfidence: number;
+}
+
+export function rank(groups: GroupedHypothesis[]): RankResult {
+  if (groups.length === 0) {
+    return {
+      leading: null,
+      rawLeadingConfidence: 0,
+      adjustedLeadingConfidence: 0,
+      alternates: [],
+      maxAlternateConfidence: 0,
+    };
+  }
+
+  const sorted = [...groups].sort(compareByConfidence);
+  const leading = sorted[0];
+  const alternates = sorted.slice(1);
+  const maxAlternateConfidence =
+    alternates.length > 0 ? alternates[0].confidence : 0;
+  const rawLeadingConfidence = leading.confidence;
+  const adjustedLeadingConfidence =
+    rawLeadingConfidence * (1 - maxAlternateConfidence * 0.5);
+
+  return {
+    leading,
+    rawLeadingConfidence,
+    adjustedLeadingConfidence,
+    alternates,
+    maxAlternateConfidence,
+  };
+}
+
+function compareByConfidence(
+  a: GroupedHypothesis,
+  b: GroupedHypothesis,
+): number {
+  if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+  return a.canonical.localeCompare(b.canonical);
+}