@hyperfixi/patterns-reference 3.1.1 → 3.3.0

package/src/api/llm.ts

@@ -5,7 +5,8 @@
  */
 
 import { getDatabase } from '../database/connection';
-import type { LLMExample, ConnectionOptions } from '../types';
+import type { LLMExample, ConnectionOptions, EngineCompat, ExampleOptions } from '../types';
+import { exampleCondition } from './engine-filter';
 
 // =============================================================================
 // Database Row Types
@@ -20,8 +21,20 @@ interface LLMExampleRow {
   quality_score: number;
   usage_count: number;
   created_at: string;
+  /** The verified engine of the example's pattern (joined from code_examples). */
+  engine: string | null;
 }
 
+/**
+ * Every example getter reads through this join: an example carries its
+ * pattern's verified engine, and one whose pattern no engine runs is never
+ * served (see engine-filter.ts). `le.` qualifies every column the queries use.
+ */
+const EXAMPLES_FROM = `
+  SELECT le.*, ce.engine AS engine
+  FROM llm_examples le
+  JOIN code_examples ce ON ce.id = le.code_example_id`;
+
 // =============================================================================
 // Query Functions
 // =============================================================================
@@ -34,9 +47,10 @@ export async function getLLMExamples(
   prompt: string,
   language: string = 'en',
   limit: number = 5,
-  options?: ConnectionOptions
+  options?: ExampleOptions
 ): Promise<LLMExample[]> {
   const db = getDatabase({ ...options, readonly: true });
+  const runs = exampleCondition('ce.engine', options?.engine);
 
   // Extract keywords from prompt
   const keywords = extractKeywords(prompt);
@@ -45,44 +59,30 @@ export async function getLLMExamples(
     // Return top-quality examples as fallback
     const rows = db
       .prepare(
-        `
-      SELECT * FROM llm_examples
-      WHERE language = ?
-      ORDER BY quality_score DESC, usage_count DESC
+        `${EXAMPLES_FROM}
+      WHERE le.language = ? AND ${runs.sql}
+      ORDER BY le.quality_score DESC, le.usage_count DESC
       LIMIT ?
     `
       )
-      .all(language, limit) as LLMExampleRow[];
-
-    // Track usage
-    trackUsage(
-      db,
-      rows.map(r => r.id)
-    );
+      .all(language, ...runs.params, limit) as LLMExampleRow[];
 
     return rows.map(mapRowToLLMExample);
   }
 
   // Build LIKE clauses for keyword matching
-  const likeClauses = keywords.map(() => '(prompt LIKE ? OR completion LIKE ?)').join(' OR ');
+  const likeClauses = keywords.map(() => '(le.prompt LIKE ? OR le.completion LIKE ?)').join(' OR ');
   const params = keywords.flatMap(k => [`%${k}%`, `%${k}%`]);
 
   const rows = db
     .prepare(
-      `
-    SELECT * FROM llm_examples
-    WHERE language = ? AND (${likeClauses})
-    ORDER BY quality_score DESC
+      `${EXAMPLES_FROM}
+    WHERE le.language = ? AND ${runs.sql} AND (${likeClauses})
+    ORDER BY le.quality_score DESC
     LIMIT ?
   `
     )
-    .all(language, ...params, limit) as LLMExampleRow[];
-
-  // Track usage
-  trackUsage(
-    db,
-    rows.map(r => r.id)
-  );
+    .all(language, ...runs.params, ...params, limit) as LLMExampleRow[];
 
   return rows.map(mapRowToLLMExample);
 }
@@ -94,20 +94,20 @@ export async function getExamplesByCommand(
   command: string,
   language: string = 'en',
   limit: number = 5,
-  options?: ConnectionOptions
+  options?: ExampleOptions
 ): Promise<LLMExample[]> {
   const db = getDatabase({ ...options, readonly: true });
+  const runs = exampleCondition('ce.engine', options?.engine);
 
   const rows = db
     .prepare(
-      `
-    SELECT * FROM llm_examples
-    WHERE language = ? AND completion LIKE ?
-    ORDER BY quality_score DESC
+      `${EXAMPLES_FROM}
+    WHERE le.language = ? AND ${runs.sql} AND le.completion LIKE ?
+    ORDER BY le.quality_score DESC
     LIMIT ?
   `
     )
-    .all(language, `%${command}%`, limit) as LLMExampleRow[];
+    .all(language, ...runs.params, `%${command}%`, limit) as LLMExampleRow[];
 
   return rows.map(mapRowToLLMExample);
 }
@@ -119,44 +119,50 @@ export async function getHighQualityExamples(
   language: string = 'en',
   minQuality: number = 0.8,
   limit: number = 10,
-  options?: ConnectionOptions
+  options?: ExampleOptions
 ): Promise<LLMExample[]> {
   const db = getDatabase({ ...options, readonly: true });
+  const runs = exampleCondition('ce.engine', options?.engine);
 
   const rows = db
     .prepare(
-      `
-    SELECT * FROM llm_examples
-    WHERE language = ? AND quality_score >= ?
-    ORDER BY quality_score DESC, usage_count DESC
+      `${EXAMPLES_FROM}
+    WHERE le.language = ? AND ${runs.sql} AND le.quality_score >= ?
+    ORDER BY le.quality_score DESC, le.usage_count DESC
     LIMIT ?
   `
     )
-    .all(language, minQuality, limit) as LLMExampleRow[];
+    .all(language, ...runs.params, minQuality, limit) as LLMExampleRow[];
 
   return rows.map(mapRowToLLMExample);
 }
 
 /**
  * Get most used examples (popular).
+ *
+ * @deprecated Only an explicit trackExampleUsage() call counts a use, and nothing
+ * makes one, so `usage_count` is 0 on every shipped example and this ranks by
+ * quality alone: getHighQualityExamples with no floor. Reads used to count
+ * themselves through the read-only handle they open; the write failed and the
+ * error was swallowed.
  */
 export async function getMostUsedExamples(
   language: string = 'en',
   limit: number = 10,
-  options?: ConnectionOptions
+  options?: ExampleOptions
 ): Promise<LLMExample[]> {
   const db = getDatabase({ ...options, readonly: true });
+  const runs = exampleCondition('ce.engine', options?.engine);
 
   const rows = db
     .prepare(
-      `
-    SELECT * FROM llm_examples
-    WHERE language = ?
-    ORDER BY usage_count DESC, quality_score DESC
+      `${EXAMPLES_FROM}
+    WHERE le.language = ? AND ${runs.sql}
+    ORDER BY le.usage_count DESC, le.quality_score DESC
     LIMIT ?
   `
     )
-    .all(language, limit) as LLMExampleRow[];
+    .all(language, ...runs.params, limit) as LLMExampleRow[];
 
   return rows.map(mapRowToLLMExample);
 }
@@ -168,7 +174,7 @@ export async function buildFewShotContext(
   prompt: string,
   language: string = 'en',
   numExamples: number = 3,
-  options?: ConnectionOptions
+  options?: ExampleOptions
 ): Promise<string> {
   const examples = await getLLMExamples(prompt, language, numExamples, options);
 
@@ -192,7 +198,8 @@ export async function buildFewShotContext(
  * Add a new LLM example.
  */
 export async function addLLMExample(
-  example: Omit<LLMExample, 'id' | 'usageCount' | 'createdAt'>,
+  // `engine` belongs to the pattern (code_examples.engine), not the example.
+  example: Omit<LLMExample, 'id' | 'usageCount' | 'createdAt' | 'engine'>,
   options?: ConnectionOptions
 ): Promise<number> {
   const db = getDatabase(options);
@@ -240,6 +247,7 @@ export async function getLLMStats(options?: ConnectionOptions): Promise<{
   total: number;
   byLanguage: Record<string, number>;
   avgQuality: number;
+  /** @deprecated 0 unless something calls trackExampleUsage() (see getMostUsedExamples). */
   totalUsage: number;
 }> {
   const db = getDatabase({ ...options, readonly: true });
@@ -321,25 +329,6 @@ function extractKeywords(prompt: string): string[] {
     .filter(word => word.length > 2 && !stopWords.has(word));
 }
 
-/**
- * Track usage of examples.
- */
-function trackUsage(db: any, ids: number[]): void {
-  if (ids.length === 0) return;
-
-  try {
-    const stmt = db.prepare(`
-      UPDATE llm_examples SET usage_count = usage_count + 1 WHERE id = ?
-    `);
-
-    for (const id of ids) {
-      stmt.run(id);
-    }
-  } catch {
-    // Silently ignore tracking errors
-  }
-}
-
 /**
  * Map database row to LLMExample type.
  */
@@ -353,5 +342,6 @@ function mapRowToLLMExample(row: LLMExampleRow): LLMExample {
     qualityScore: row.quality_score,
     usageCount: row.usage_count,
     createdAt: new Date(row.created_at),
+    engine: (row.engine as EngineCompat | null) ?? null,
   };
 }

package/src/api/patterns.ts

@@ -5,6 +5,8 @@
  */
 
 import { getDatabase } from '../database/connection';
+import { hyperscriptBodies } from '../sync/markup-attributes';
+import { runsOn } from './engine-filter';
 import type {
   Pattern,
   SearchOptions,
@@ -24,6 +26,7 @@ interface CodeExampleRow {
   description: string | null;
   feature: string | null;
   engine: string | null;
+  translatable: number;
   source_url: string | null;
   created_at: string;
 }
@@ -43,7 +46,7 @@ export async function getPatternById(
   const row = db
     .prepare(
       `
-    SELECT id, title, raw_code, description, feature, engine, created_at
+    SELECT id, title, raw_code, description, feature, engine, translatable, created_at
     FROM code_examples
     WHERE id = ?
   `
@@ -64,7 +67,7 @@ export async function getPatternsByCategory(
   const rows = db
     .prepare(
       `
-    SELECT id, title, raw_code, description, feature, engine, created_at
+    SELECT id, title, raw_code, description, feature, engine, translatable, created_at
     FROM code_examples
     WHERE feature = ?
     ORDER BY title
@@ -87,7 +90,7 @@ export async function getPatternsByCommand(
   const rows = db
     .prepare(
       `
-    SELECT id, title, raw_code, description, feature, engine, created_at
+    SELECT id, title, raw_code, description, feature, engine, translatable, created_at
     FROM code_examples
     WHERE raw_code LIKE ?
     ORDER BY title
@@ -102,29 +105,101 @@ export async function getPatternsByCommand(
 }
 
 /**
- * Search patterns by text query.
+ * The `engine` search option as SQL: omitted → no filter (a catalog lists
+ * every pattern, with its verdict); otherwise the patterns that run on it.
+ * (It used to be declared on SearchOptions and silently ignored.)
  */
-export async function searchPatterns(
-  query: string,
-  searchOptions: SearchOptions = {},
-  connOptions?: ConnectionOptions
-): Promise<Pattern[]> {
+function engineFilter(searchOptions: SearchOptions): { sql: string; params: string[] } {
+  return searchOptions.engine === undefined
+    ? { sql: '1 = 1', params: [] }
+    : runsOn('engine', searchOptions.engine);
+}
+
+type Condition = { sql: string; params: string[] };
+
+/**
+ * The `language` search option as a predicate: the pattern has a translation in
+ * that language that parses (`verified_parses`, measured at sync), or it carries
+ * no hyperscript at all — markup the runtime reads as it is, the same in every
+ * language (sse/ws wiring, a static component template). Such a row can never
+ * "verify", so a parse-only rule would drop it from every language.
+ */
+function usableIn(
+  db: ReturnType<typeof getDatabase>,
+  language: string
+): (pattern: Pattern) => boolean {
+  const rows = db
+    .prepare(
+      'SELECT code_example_id AS id FROM pattern_translations WHERE language = ? AND verified_parses = 1'
+    )
+    .all(language) as Array<{ id: string }>;
+  const verified = new Set(rows.map(row => row.id));
+  return pattern => verified.has(pattern.id) || hyperscriptBodies(pattern.rawCode).length === 0;
+}
+
+/**
+ * The patterns matching `match` and every search option, one page of them.
+ *
+ * `category`, `difficulty` and `language` used to be declared on SearchOptions
+ * and silently ignored. `difficulty` is inferred from the code and `language`
+ * reads the markup, so those two filter in JS — and paging runs after them, so a
+ * page is always a page of MATCHING patterns (the table is a few hundred rows).
+ */
+function queryPatterns(
+  searchOptions: SearchOptions,
+  defaultLimit: number,
+  connOptions: ConnectionOptions | undefined,
+  match: Condition = { sql: '1 = 1', params: [] }
+): Pattern[] {
   const db = getDatabase({ ...connOptions, readonly: true });
-  const { limit = 50, offset = 0 } = searchOptions;
+  const { limit = defaultLimit, offset = 0, category, difficulty, language } = searchOptions;
+  const runs = engineFilter(searchOptions);
+  const inCategory: Condition =
+    category === undefined
+      ? { sql: '1 = 1', params: [] }
+      : { sql: 'feature = ?', params: [category] };
 
   const rows = db
     .prepare(
       `
-    SELECT id, title, raw_code, description, feature, engine, created_at
+    SELECT id, title, raw_code, description, feature, engine, translatable, created_at
     FROM code_examples
-    WHERE title LIKE ? OR raw_code LIKE ? OR description LIKE ?
+    WHERE (${match.sql}) AND ${runs.sql} AND ${inCategory.sql}
     ORDER BY title
-    LIMIT ? OFFSET ?
   `
     )
-    .all(`%${query}%`, `%${query}%`, `%${query}%`, limit, offset) as CodeExampleRow[];
+    .all(...match.params, ...runs.params, ...inCategory.params) as CodeExampleRow[];
 
-  return rows.map(mapRowToPattern);
+  const inLanguage = language === undefined ? null : usableIn(db, language);
+  return rows
+    .map(mapRowToPattern)
+    .filter(pattern => difficulty === undefined || pattern.difficulty === difficulty)
+    .filter(pattern => inLanguage === null || inLanguage(pattern))
+    .slice(offset, offset + limit);
+}
+
+/**
+ * Search patterns by text query: title, code or description — and, when a
+ * `language` is named, that language's translation, so a query in the language
+ * finds a pattern by its own code there.
+ */
+export async function searchPatterns(
+  query: string,
+  searchOptions: SearchOptions = {},
+  connOptions?: ConnectionOptions
+): Promise<Pattern[]> {
+  const like = `%${query}%`;
+  const inTranslation: Condition =
+    searchOptions.language === undefined
+      ? { sql: '', params: [] }
+      : {
+          sql: ' OR id IN (SELECT code_example_id FROM pattern_translations WHERE language = ? AND hyperscript LIKE ?)',
+          params: [searchOptions.language, like],
+        };
+  return queryPatterns(searchOptions, 50, connOptions, {
+    sql: `title LIKE ? OR raw_code LIKE ? OR description LIKE ?${inTranslation.sql}`,
+    params: [like, like, like, ...inTranslation.params],
+  });
 }
 
 /**
@@ -134,21 +209,7 @@ export async function getAllPatterns(
   searchOptions: SearchOptions = {},
   connOptions?: ConnectionOptions
 ): Promise<Pattern[]> {
-  const db = getDatabase({ ...connOptions, readonly: true });
-  const { limit = 1000, offset = 0 } = searchOptions;
-
-  const rows = db
-    .prepare(
-      `
-    SELECT id, title, raw_code, description, feature, engine, created_at
-    FROM code_examples
-    ORDER BY title
-    LIMIT ? OFFSET ?
-  `
-    )
-    .all(limit, offset) as CodeExampleRow[];
-
-  return rows.map(mapRowToPattern);
+  return queryPatterns(searchOptions, 1000, connOptions);
 }
 
 /**
@@ -253,6 +314,7 @@ function mapRowToPattern(row: CodeExampleRow): Pattern {
     tags: extractTags(row.raw_code),
     difficulty: inferDifficulty(row.raw_code),
     engine: (row.engine as EngineCompat) || null,
+    translatable: row.translatable !== 0,
     createdAt: new Date(row.created_at),
   };
 }

package/src/api/roles.ts

@@ -35,6 +35,7 @@ interface CodeExampleRow {
   description: string | null;
   feature: string | null;
   engine: string | null;
+  translatable: number;
   created_at: string;
 }
 
@@ -75,7 +76,7 @@ export async function getPatternsByRole(
   const rows = db
     .prepare(
       `
-    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.translatable, ce.created_at
     FROM code_examples ce
     INNER JOIN pattern_roles pr ON ce.id = pr.code_example_id
     WHERE pr.role = ?
@@ -105,7 +106,7 @@ export async function getPatternsByRoles(
     const rows = db
       .prepare(
         `
-      SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+      SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.translatable, ce.created_at
       FROM code_examples ce
       INNER JOIN pattern_roles pr ON ce.id = pr.code_example_id
       WHERE pr.role IN (${placeholders})
@@ -121,7 +122,7 @@ export async function getPatternsByRoles(
     const rows = db
       .prepare(
         `
-      SELECT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+      SELECT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.translatable, ce.created_at
       FROM code_examples ce
       WHERE (
         SELECT COUNT(DISTINCT pr.role)
@@ -149,7 +150,7 @@ export async function getPatternsByRoleValue(
   const rows = db
     .prepare(
       `
-    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.translatable, ce.created_at
     FROM code_examples ce
     INNER JOIN pattern_roles pr ON ce.id = pr.code_example_id
     WHERE pr.role = ? AND pr.role_value LIKE ?
@@ -374,6 +375,7 @@ function mapRowToPattern(row: CodeExampleRow): Pattern {
     tags: extractTags(row.raw_code),
     difficulty: inferDifficulty(row.raw_code),
     engine: (row.engine as EngineCompat) || null,
+    translatable: row.translatable !== 0,
     createdAt: new Date(row.created_at),
   };
 }

package/src/api/translations.ts

@@ -148,8 +148,10 @@ export async function getHighConfidenceTranslations(
 }
 
 /**
- * Verify a translation parses correctly.
- * Note: This requires @lokascript/semantic to be available.
+ * Re-measure whether a translation parses, record the result, and return it.
+ * Uses the same definition sync-translations writes `verified_parses` with
+ * (src/sync/verify-parses.ts): every hyperscript body of the row parses in its
+ * language. Note: This requires @lokascript/semantic to be available.
  */
 export async function verifyTranslation(
   translation: Translation,
@@ -159,38 +161,43 @@ export async function verifyTranslation(
   let errorMessage: string | null = null;
   let confidence = translation.confidence;
 
-  try {
-    // Dynamic import to avoid bundling issues
-    const { canParse, parse } = await import('@lokascript/semantic');
+  const db = getDatabase(options);
+  const example = db
+    .prepare('SELECT translatable FROM code_examples WHERE id = ?')
+    .get(translation.codeExampleId) as { translatable: number } | undefined;
 
-    if (canParse(translation.hyperscript, translation.language)) {
-      parse(translation.hyperscript, translation.language);
-      parseSuccess = true;
-    } else {
-      errorMessage = 'canParse returned false';
-    }
+  try {
+    // Dynamic import: the parser is only loaded by callers that verify.
+    const { verifyParses } = await import('../sync/verify-parses');
+    parseSuccess = verifyParses(
+      translation.hyperscript,
+      translation.language,
+      example?.translatable !== 0
+    );
+    if (!parseSuccess) errorMessage = 'the semantic parser rejected it (or it has no hyperscript)';
   } catch (e) {
     errorMessage = (e as Error).message;
   }
 
-  // Update database
-  const db = getDatabase(options);
-  db.prepare(
+  // The flag and its test record land together. (The INSERT used to name
+  // columns pattern_tests does not have, so it threw AFTER the UPDATE had
+  // already flipped the flag.)
+  db.transaction(() => {
+    db.prepare(
+      `
+      UPDATE pattern_translations
+      SET verified_parses = ?, updated_at = datetime('now')
+      WHERE id = ?
     `
-    UPDATE pattern_translations
-    SET verified_parses = ?, updated_at = datetime('now')
-    WHERE id = ?
-  `
-  ).run(parseSuccess ? 1 : 0, translation.id);
-
-  // Record test result
-  db.prepare(
+    ).run(parseSuccess ? 1 : 0, translation.id);
+    db.prepare(
+      `
+      INSERT INTO pattern_tests
+        (code_example_id, language, test_type, success, error_message, test_date)
+      VALUES (?, ?, 'parse', ?, ?, datetime('now'))
     `
-    INSERT INTO pattern_tests
-      (code_example_id, language, test_date, parse_success, error_message)
-    VALUES (?, ?, datetime('now'), ?, ?)
-  `
-  ).run(translation.codeExampleId, translation.language, parseSuccess ? 1 : 0, errorMessage);
+    ).run(translation.codeExampleId, translation.language, parseSuccess ? 1 : 0, errorMessage);
+  })();
 
   return {
     translation,

package/src/database/connection.ts

@@ -36,6 +36,9 @@ let currentDbPath: string | null = null;
 let openFileId: string | null = null;
 let lastIdentityCheckAt = 0;
 
+/** Whether the cached handle was opened read-only (it then cannot serve a write). */
+let openReadonly = false;
+
 /** Re-stat at most this often, so a bulk query loop pays one syscall, not thousands. */
 const IDENTITY_TTL_MS = 1000;
 
@@ -63,12 +66,20 @@ export function getDefaultDbPath(): string {
  */
 export function getDatabase(options: ConnectionOptions = {}): InstanceType<typeof Database> {
   const dbPath = options.dbPath ?? DEFAULT_DB_PATH;
+  const readonly = options.readonly ?? false;
+
+  // A read-only handle cannot serve a write. The read APIs open with
+  // `readonly: true`, so without this a caller that read first and then called
+  // `verifyTranslation()` got the cached read-only handle and "attempt to write
+  // a readonly database". A writable handle serves reads fine, so only this
+  // direction reopens.
+  const canServe = !openReadonly || readonly;
 
   // Reuse the open handle only if it is reading the same PATH *and* the same FILE. The
   // second half matters because `populate` swaps the file underneath us: without it a
   // long-lived consumer serves pre-populate rows indefinitely, which looks like a parser
   // bug and is not one. Behind a TTL so a query loop doesn't stat per row.
-  if (dbInstance !== null && currentDbPath === dbPath) {
+  if (dbInstance !== null && currentDbPath === dbPath && canServe) {
     const now = Date.now();
     if (now - lastIdentityCheckAt < IDENTITY_TTL_MS) {
       return dbInstance;
@@ -88,9 +99,8 @@ export function getDatabase(options: ConnectionOptions = {}): InstanceType<typeo
     dbInstance.close();
   }
 
-  dbInstance = new Database(dbPath, {
-    readonly: options.readonly ?? false,
-  });
+  dbInstance = new Database(dbPath, { readonly });
+  openReadonly = readonly;
 
   // Enable foreign keys
   dbInstance.pragma('foreign_keys = ON');
@@ -111,6 +121,7 @@ export function closeDatabase(): void {
     currentDbPath = null;
     openFileId = null;
     lastIdentityCheckAt = 0;
+    openReadonly = false;
   }
 }
 
@@ -122,6 +133,7 @@ export function resetConnection(): void {
   currentDbPath = null;
   openFileId = null;
   lastIdentityCheckAt = 0;
+  openReadonly = false;
 }
 
 /**