@hyperfixi/patterns-reference 2.5.1 → 2.6.0

package/README.md

@@ -12,9 +12,9 @@ npm install @hyperfixi/patterns-reference
 
 The package ships with a **pre-populated SQLite database** containing:
 
-- 106 code examples covering hyperscript commands and real-world UI patterns
-- 1,378 translations (106 patterns × 13 languages)
-- 414 LLM few-shot examples for code generation
+- 164 code examples covering hyperscript commands and real-world UI patterns
+- 3,936 translations (164 patterns × 24 languages)
+- 648 LLM few-shot examples for code generation
 
 No setup required - just install and use:
 
@@ -132,7 +132,7 @@ These scripts are for contributors regenerating the database. **End users don't
 | `npm run populate`          | Full database setup (init + translations + LLM examples) |
 | `npm run db:init`           | Initialize database with seed patterns                   |
 | `npm run db:init:force`     | Reinitialize database (overwrites existing)              |
-| `npm run sync:translations` | Generate translations for all 13 languages               |
+| `npm run sync:translations` | Generate translations for all 24 languages               |
 | `npm run seed:llm`          | Generate LLM few-shot examples                           |
 | `npm run validate`          | Validate all patterns parse correctly                    |
 | `npm run validate:fix`      | Validate and update verified_parses flag                 |
@@ -185,23 +185,18 @@ Prompt/completion pairs for few-shot learning.
 
 ## Supported Languages
 
-The database supports 13 languages with different word orders:
-
-| Language   | Code | Word Order |
-| ---------- | ---- | ---------- |
-| English    | en   | SVO        |
-| Spanish    | es   | SVO        |
-| French     | fr   | SVO        |
-| Portuguese | pt   | SVO        |
-| Indonesian | id   | SVO        |
-| Swahili    | sw   | SVO        |
-| Chinese    | zh   | SVO        |
-| Japanese   | ja   | SOV        |
-| Korean     | ko   | SOV        |
-| Turkish    | tr   | SOV        |
-| Quechua    | qu   | SOV        |
-| Arabic     | ar   | VSO        |
-| German     | de   | V2         |
+The database supports 24 languages with different word orders:
+
+| Word Order | Languages                                  |
+| ---------- | ------------------------------------------ |
+| SVO        | en, es, fr, pt, it, id, ms, sw, zh, vi, tl |
+| SOV        | ja, ko, tr, qu, hi, bn                     |
+| VSO        | ar                                         |
+| V2         | de                                         |
+| Other      | ru, uk, pl, th, he                         |
+
+Languages are derived dynamically from `KNOWN_PROFILES` in `@lokascript/semantic`;
+adding a profile there automatically picks up in the next `npm run sync:translations`.
 
 ## Integration with @lokascript/semantic
 

package/dist/api/index.d.mts

@@ -1,5 +1,5 @@
-export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, e as getExamplesByCommand, f as getHighConfidenceTranslations, h as getHighQualityExamples, i as getLLMExamples, j as getLLMStats, k as getMostUsedExamples, l as getPatternById, m as getPatternStats, n as getPatternsByCategory, o as getPatternsByCommand, p as getTranslation, q as getTranslationStats, r as getTranslationsByLanguage, s as getVerifiedTranslations, t as getWordOrder, u as searchPatterns, v as updateQualityScore, w as verifyTranslation } from '../llm-4zwmAvZ8.mjs';
-import { c as ConnectionOptions, i as PatternRole, P as Pattern, R as RoleType } from '../index-BhzKat9K.mjs';
+export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, d as getExamplesByCommand, e as getHighConfidenceTranslations, f as getHighQualityExamples, h as getLLMExamples, i as getLLMStats, j as getMostUsedExamples, k as getPatternById, l as getPatternStats, m as getPatternsByCategory, n as getPatternsByCommand, o as getTranslation, p as getTranslationStats, q as getTranslationsByLanguage, r as getVerifiedTranslations, s as getWordOrder, t as searchPatterns, u as updateQualityScore, v as verifyTranslation } from '../llm-BS3mf0VG.mjs';
+import { C as ConnectionOptions, P as PatternRole, a as Pattern, R as RoleType } from '../index-1ENU9L4F.mjs';
 import { SemanticRole } from '@lokascript/semantic';
 
 /**

package/dist/api/index.d.ts

@@ -1,5 +1,5 @@
-export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, e as getExamplesByCommand, f as getHighConfidenceTranslations, h as getHighQualityExamples, i as getLLMExamples, j as getLLMStats, k as getMostUsedExamples, l as getPatternById, m as getPatternStats, n as getPatternsByCategory, o as getPatternsByCommand, p as getTranslation, q as getTranslationStats, r as getTranslationsByLanguage, s as getVerifiedTranslations, t as getWordOrder, u as searchPatterns, v as updateQualityScore, w as verifyTranslation } from '../llm-B7pwZ472.js';
-import { c as ConnectionOptions, i as PatternRole, P as Pattern, R as RoleType } from '../index-BhzKat9K.js';
+export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, d as getExamplesByCommand, e as getHighConfidenceTranslations, f as getHighQualityExamples, h as getLLMExamples, i as getLLMStats, j as getMostUsedExamples, k as getPatternById, l as getPatternStats, m as getPatternsByCategory, n as getPatternsByCommand, o as getTranslation, p as getTranslationStats, q as getTranslationsByLanguage, r as getVerifiedTranslations, s as getWordOrder, t as searchPatterns, u as updateQualityScore, v as verifyTranslation } from '../llm-DkGTC6X7.js';
+import { C as ConnectionOptions, P as PatternRole, a as Pattern, R as RoleType } from '../index-1ENU9L4F.js';
 import { SemanticRole } from '@lokascript/semantic';
 
 /**

package/dist/{index-BhzKat9K.d.mts → index-1ENU9L4F.d.mts}

@@ -293,4 +293,4 @@ interface PatternsReference {
     close(): void;
 }
 
-export type { ClassifiedPattern as C, DiscoveryResult as D, EngineCompat as E, Feature as F, Keyword as K, LLMExample as L, Pattern as P, RoleType as R, SearchOptions as S, TestOptions as T, ValidationOptions as V, WordOrder as W, Command as a, ComplexityLevel as b, ConnectionOptions as c, Expression as d, ExpressionOperator as e, LanguageDocsStats as f, LanguageElement as g, LanguageElementType as h, PatternRole as i, PatternStats as j, PatternsReference as k, SpecialSymbol as l, SyncOptions as m, SyncResult as n, Translation as o, TranslationMethod as p, ValidationResult as q, VerificationResult as r };
+export type { ConnectionOptions as C, DiscoveryResult as D, Expression as E, Feature as F, Keyword as K, LanguageDocsStats as L, PatternRole as P, RoleType as R, SpecialSymbol as S, TestOptions as T, ValidationOptions as V, WordOrder as W, Pattern as a, Command as b, LanguageElementType as c, LanguageElement as d, LLMExample as e, PatternsReference as f, ClassifiedPattern as g, ComplexityLevel as h, EngineCompat as i, ExpressionOperator as j, PatternStats as k, SearchOptions as l, SyncOptions as m, SyncResult as n, Translation as o, TranslationMethod as p, ValidationResult as q, VerificationResult as r };

package/dist/{index-BhzKat9K.d.ts → index-1ENU9L4F.d.ts}

@@ -293,4 +293,4 @@ interface PatternsReference {
     close(): void;
 }
 
-export type { ClassifiedPattern as C, DiscoveryResult as D, EngineCompat as E, Feature as F, Keyword as K, LLMExample as L, Pattern as P, RoleType as R, SearchOptions as S, TestOptions as T, ValidationOptions as V, WordOrder as W, Command as a, ComplexityLevel as b, ConnectionOptions as c, Expression as d, ExpressionOperator as e, LanguageDocsStats as f, LanguageElement as g, LanguageElementType as h, PatternRole as i, PatternStats as j, PatternsReference as k, SpecialSymbol as l, SyncOptions as m, SyncResult as n, Translation as o, TranslationMethod as p, ValidationResult as q, VerificationResult as r };
+export type { ConnectionOptions as C, DiscoveryResult as D, Expression as E, Feature as F, Keyword as K, LanguageDocsStats as L, PatternRole as P, RoleType as R, SpecialSymbol as S, TestOptions as T, ValidationOptions as V, WordOrder as W, Pattern as a, Command as b, LanguageElementType as c, LanguageElement as d, LLMExample as e, PatternsReference as f, ClassifiedPattern as g, ComplexityLevel as h, EngineCompat as i, ExpressionOperator as j, PatternStats as k, SearchOptions as l, SyncOptions as m, SyncResult as n, Translation as o, TranslationMethod as p, ValidationResult as q, VerificationResult as r };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { c as ConnectionOptions, a as Command, d as Expression, F as Feature, K as Keyword, l as SpecialSymbol, f as LanguageDocsStats, h as LanguageElementType, g as LanguageElement, L as LLMExample, k as PatternsReference } from './index-BhzKat9K.mjs';
-export { C as ClassifiedPattern, b as ComplexityLevel, D as DiscoveryResult, E as EngineCompat, e as ExpressionOperator, P as Pattern, j as PatternStats, S as SearchOptions, m as SyncOptions, n as SyncResult, T as TestOptions, o as Translation, p as TranslationMethod, V as ValidationOptions, q as ValidationResult, r as VerificationResult, W as WordOrder } from './index-BhzKat9K.mjs';
+import { C as ConnectionOptions, b as Command, E as Expression, F as Feature, K as Keyword, S as SpecialSymbol, L as LanguageDocsStats, c as LanguageElementType, d as LanguageElement, e as LLMExample, f as PatternsReference } from './index-1ENU9L4F.mjs';
+export { g as ClassifiedPattern, h as ComplexityLevel, D as DiscoveryResult, i as EngineCompat, j as ExpressionOperator, a as Pattern, k as PatternStats, l as SearchOptions, m as SyncOptions, n as SyncResult, T as TestOptions, o as Translation, p as TranslationMethod, V as ValidationOptions, q as ValidationResult, r as VerificationResult, W as WordOrder } from './index-1ENU9L4F.mjs';
 import Database from 'better-sqlite3';
-export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, d as getBehaviorPatterns, e as getExamplesByCommand, f as getHighConfidenceTranslations, h as getHighQualityExamples, i as getLLMExamples, j as getLLMStats, k as getMostUsedExamples, l as getPatternById, m as getPatternStats, n as getPatternsByCategory, o as getPatternsByCommand, p as getTranslation, q as getTranslationStats, r as getTranslationsByLanguage, s as getVerifiedTranslations, t as getWordOrder, u as searchPatterns, v as updateQualityScore, w as verifyTranslation } from './llm-4zwmAvZ8.mjs';
-export { discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations } from './sync/index.mjs';
+export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, w as getBehaviorPatterns, d as getExamplesByCommand, e as getHighConfidenceTranslations, f as getHighQualityExamples, h as getLLMExamples, i as getLLMStats, j as getMostUsedExamples, k as getPatternById, l as getPatternStats, m as getPatternsByCategory, n as getPatternsByCommand, o as getTranslation, p as getTranslationStats, q as getTranslationsByLanguage, r as getVerifiedTranslations, s as getWordOrder, t as searchPatterns, u as updateQualityScore, v as verifyTranslation } from './llm-BS3mf0VG.mjs';
+export { DbStampStatus, checkDbStamp, computeDbInputHash, dbStampPath, discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations, writeDbStamp } from './sync/index.mjs';
 import '@lokascript/semantic';
 
 /**
@@ -11,6 +11,12 @@ import '@lokascript/semantic';
  * Provides singleton connection to the patterns-reference SQLite database.
  */
 
+/**
+ * The resolved default DB path (honouring `LSP_DB_PATH` / `HYPERSCRIPT_LSP_DB`).
+ * Exposed so callers (e.g. the multilingual gate's freshness check) can target the
+ * exact DB that `getDatabase()` opens.
+ */
+declare function getDefaultDbPath(): string;
 /**
  * Get database connection (lazy singleton).
  */
@@ -455,4 +461,4 @@ declare function createPatternsReference(options?: ConnectionOptions): PatternsR
  */
 declare const VERSION = "0.1.0";
 
-export { type BehaviorRuntime, Command, ConnectionOptions, DatabasePatternsProvider, Expression, Feature, type IntegrationResult, Keyword, LLMExample, type LLMExampleRecord, LanguageDocsStats, LanguageElement, LanguageElementType, type LoadBehaviorsOptions, type LoadBehaviorsResult, type PatternEntry, PatternsReference, type PatternsSource, type SemanticIntegrationOptions, SpecialSymbol, VERSION, buildFewShotContextSync, closeDatabase, createLLMAdapter, createPatternsProvider, createPatternsReference, findExamplesByCommand, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllSpecialSymbols, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultProvider, getExpressionByName, getExpressionsByCategory, getFeatureByName, getKeywordByName, getLLMExampleStats, getLanguageDocsStats, getSpecialSymbolByName, getSupportedLanguages, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, trackExampleUsage, uninitializeSemanticIntegration };
+export { type BehaviorRuntime, Command, ConnectionOptions, DatabasePatternsProvider, Expression, Feature, type IntegrationResult, Keyword, LLMExample, type LLMExampleRecord, LanguageDocsStats, LanguageElement, LanguageElementType, type LoadBehaviorsOptions, type LoadBehaviorsResult, type PatternEntry, PatternsReference, type PatternsSource, type SemanticIntegrationOptions, SpecialSymbol, VERSION, buildFewShotContextSync, closeDatabase, createLLMAdapter, createPatternsProvider, createPatternsReference, findExamplesByCommand, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllSpecialSymbols, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultDbPath, getDefaultProvider, getExpressionByName, getExpressionsByCategory, getFeatureByName, getKeywordByName, getLLMExampleStats, getLanguageDocsStats, getSpecialSymbolByName, getSupportedLanguages, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, trackExampleUsage, uninitializeSemanticIntegration };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { c as ConnectionOptions, a as Command, d as Expression, F as Feature, K as Keyword, l as SpecialSymbol, f as LanguageDocsStats, h as LanguageElementType, g as LanguageElement, L as LLMExample, k as PatternsReference } from './index-BhzKat9K.js';
-export { C as ClassifiedPattern, b as ComplexityLevel, D as DiscoveryResult, E as EngineCompat, e as ExpressionOperator, P as Pattern, j as PatternStats, S as SearchOptions, m as SyncOptions, n as SyncResult, T as TestOptions, o as Translation, p as TranslationMethod, V as ValidationOptions, q as ValidationResult, r as VerificationResult, W as WordOrder } from './index-BhzKat9K.js';
+import { C as ConnectionOptions, b as Command, E as Expression, F as Feature, K as Keyword, S as SpecialSymbol, L as LanguageDocsStats, c as LanguageElementType, d as LanguageElement, e as LLMExample, f as PatternsReference } from './index-1ENU9L4F.js';
+export { g as ClassifiedPattern, h as ComplexityLevel, D as DiscoveryResult, i as EngineCompat, j as ExpressionOperator, a as Pattern, k as PatternStats, l as SearchOptions, m as SyncOptions, n as SyncResult, T as TestOptions, o as Translation, p as TranslationMethod, V as ValidationOptions, q as ValidationResult, r as VerificationResult, W as WordOrder } from './index-1ENU9L4F.js';
 import Database from 'better-sqlite3';
-export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, d as getBehaviorPatterns, e as getExamplesByCommand, f as getHighConfidenceTranslations, h as getHighQualityExamples, i as getLLMExamples, j as getLLMStats, k as getMostUsedExamples, l as getPatternById, m as getPatternStats, n as getPatternsByCategory, o as getPatternsByCommand, p as getTranslation, q as getTranslationStats, r as getTranslationsByLanguage, s as getVerifiedTranslations, t as getWordOrder, u as searchPatterns, v as updateQualityScore, w as verifyTranslation } from './llm-B7pwZ472.js';
-export { discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations } from './sync/index.js';
+export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, w as getBehaviorPatterns, d as getExamplesByCommand, e as getHighConfidenceTranslations, f as getHighQualityExamples, h as getLLMExamples, i as getLLMStats, j as getMostUsedExamples, k as getPatternById, l as getPatternStats, m as getPatternsByCategory, n as getPatternsByCommand, o as getTranslation, p as getTranslationStats, q as getTranslationsByLanguage, r as getVerifiedTranslations, s as getWordOrder, t as searchPatterns, u as updateQualityScore, v as verifyTranslation } from './llm-DkGTC6X7.js';
+export { DbStampStatus, checkDbStamp, computeDbInputHash, dbStampPath, discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations, writeDbStamp } from './sync/index.js';
 import '@lokascript/semantic';
 
 /**
@@ -11,6 +11,12 @@ import '@lokascript/semantic';
  * Provides singleton connection to the patterns-reference SQLite database.
  */
 
+/**
+ * The resolved default DB path (honouring `LSP_DB_PATH` / `HYPERSCRIPT_LSP_DB`).
+ * Exposed so callers (e.g. the multilingual gate's freshness check) can target the
+ * exact DB that `getDatabase()` opens.
+ */
+declare function getDefaultDbPath(): string;
 /**
  * Get database connection (lazy singleton).
  */
@@ -455,4 +461,4 @@ declare function createPatternsReference(options?: ConnectionOptions): PatternsR
  */
 declare const VERSION = "0.1.0";
 
-export { type BehaviorRuntime, Command, ConnectionOptions, DatabasePatternsProvider, Expression, Feature, type IntegrationResult, Keyword, LLMExample, type LLMExampleRecord, LanguageDocsStats, LanguageElement, LanguageElementType, type LoadBehaviorsOptions, type LoadBehaviorsResult, type PatternEntry, PatternsReference, type PatternsSource, type SemanticIntegrationOptions, SpecialSymbol, VERSION, buildFewShotContextSync, closeDatabase, createLLMAdapter, createPatternsProvider, createPatternsReference, findExamplesByCommand, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllSpecialSymbols, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultProvider, getExpressionByName, getExpressionsByCategory, getFeatureByName, getKeywordByName, getLLMExampleStats, getLanguageDocsStats, getSpecialSymbolByName, getSupportedLanguages, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, trackExampleUsage, uninitializeSemanticIntegration };
+export { type BehaviorRuntime, Command, ConnectionOptions, DatabasePatternsProvider, Expression, Feature, type IntegrationResult, Keyword, LLMExample, type LLMExampleRecord, LanguageDocsStats, LanguageElement, LanguageElementType, type LoadBehaviorsOptions, type LoadBehaviorsResult, type PatternEntry, PatternsReference, type PatternsSource, type SemanticIntegrationOptions, SpecialSymbol, VERSION, buildFewShotContextSync, closeDatabase, createLLMAdapter, createPatternsProvider, createPatternsReference, findExamplesByCommand, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllSpecialSymbols, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultDbPath, getDefaultProvider, getExpressionByName, getExpressionsByCategory, getFeatureByName, getKeywordByName, getLLMExampleStats, getLanguageDocsStats, getSpecialSymbolByName, getSupportedLanguages, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, trackExampleUsage, uninitializeSemanticIntegration };

package/dist/index.js

@@ -3,6 +3,8 @@
 var Database = require('better-sqlite3');
 var url = require('url');
 var path = require('path');
+var crypto = require('crypto');
+var fs = require('fs');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -16,6 +18,9 @@ var __dirname$1 = path.dirname(__filename2);
 var DEFAULT_DB_PATH = process.env.LSP_DB_PATH || process.env.HYPERSCRIPT_LSP_DB || path.join(__dirname$1, "../data/patterns.db");
 var dbInstance = null;
 var currentDbPath = null;
+function getDefaultDbPath() {
+  return DEFAULT_DB_PATH;
+}
 function getDatabase(options = {}) {
   const dbPath = options.dbPath ?? DEFAULT_DB_PATH;
   if (dbInstance !== null && currentDbPath === dbPath) {
@@ -812,6 +817,64 @@ async function getLanguageDocsStats(options) {
     expressionOperators: getCount("expression_operators")
   };
 }
+function repoRootFromDbPath(dbPath) {
+  return path.resolve(path.dirname(dbPath), "..", "..", "..");
+}
+function walkTsFiles(dir, acc) {
+  if (!fs.existsSync(dir)) return;
+  for (const name of fs.readdirSync(dir).sort()) {
+    if (name === "node_modules" || name === "dist" || name === "__tests__") continue;
+    const full = path.join(dir, name);
+    const st = fs.statSync(full);
+    if (st.isDirectory()) {
+      walkTsFiles(full, acc);
+    } else if (name.endsWith(".ts") && !name.endsWith(".test.ts") && !name.endsWith(".d.ts")) {
+      acc.push(full);
+    }
+  }
+}
+function dbInputFiles(dbPath) {
+  const root = repoRootFromDbPath(dbPath);
+  const files = [];
+  walkTsFiles(path.join(root, "packages", "i18n", "src"), files);
+  walkTsFiles(path.join(root, "packages", "semantic", "src"), files);
+  const pr = path.join(root, "packages", "patterns-reference");
+  for (const f of [
+    path.join(pr, "scripts", "init-db.ts"),
+    path.join(pr, "scripts", "sync-translations.ts"),
+    path.join(pr, "src", "sync", "span-mask.ts")
+  ]) {
+    if (fs.existsSync(f)) files.push(f);
+  }
+  return files.sort();
+}
+function computeDbInputHash(dbPath) {
+  const root = repoRootFromDbPath(dbPath);
+  const files = dbInputFiles(dbPath);
+  const h = crypto.createHash("sha256");
+  h.update(`files:${files.length}\0`);
+  for (const f of files) {
+    h.update(path.relative(root, f).split(path.sep).join("/"));
+    h.update("\0");
+    h.update(fs.readFileSync(f));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+function dbStampPath(dbPath) {
+  return `${dbPath}.stamp`;
+}
+function writeDbStamp(dbPath) {
+  fs.writeFileSync(dbStampPath(dbPath), `${computeDbInputHash(dbPath)}
+`, "utf8");
+}
+function checkDbStamp(dbPath) {
+  const sp = dbStampPath(dbPath);
+  if (!fs.existsSync(sp)) return { status: "unstamped" };
+  const expected = fs.readFileSync(sp, "utf8").trim();
+  const actual = computeDbInputHash(dbPath);
+  return actual === expected ? { status: "ok" } : { status: "stale", expected, actual };
+}
 
 // src/sync/index.ts
 async function syncTranslations(_options = {}) {
@@ -1281,10 +1344,13 @@ exports.VERSION = VERSION;
 exports.addLLMExample = addLLMExample;
 exports.buildFewShotContext = buildFewShotContext;
 exports.buildFewShotContextSync = buildFewShotContextSync;
+exports.checkDbStamp = checkDbStamp;
 exports.closeDatabase = closeDatabase;
+exports.computeDbInputHash = computeDbInputHash;
 exports.createLLMAdapter = createLLMAdapter;
 exports.createPatternsProvider = createPatternsProvider;
 exports.createPatternsReference = createPatternsReference;
+exports.dbStampPath = dbStampPath;
 exports.discoverPatterns = discoverPatterns;
 exports.findExamplesByCommand = findExamplesByCommand;
 exports.findRelevantExamples = findRelevantExamples;
@@ -1300,6 +1366,7 @@ exports.getBridgeProvider = getBridgeProvider;
 exports.getCommandByName = getCommandByName;
 exports.getCurrentDbPath = getCurrentDbPath;
 exports.getDatabase = getDatabase;
+exports.getDefaultDbPath = getDefaultDbPath;
 exports.getDefaultProvider = getDefaultProvider;
 exports.getExamplesByCommand = getExamplesByCommand;
 exports.getExpressionByName = getExpressionByName;
@@ -1343,3 +1410,4 @@ exports.uninitializeSemanticIntegration = uninitializeSemanticIntegration;
 exports.updateQualityScore = updateQualityScore;
 exports.validateAllTranslations = validateAllTranslations;
 exports.verifyTranslation = verifyTranslation;
+exports.writeDbStamp = writeDbStamp;

package/dist/index.mjs

@@ -1,6 +1,8 @@
 import Database from 'better-sqlite3';
 import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { dirname, join, relative, sep, resolve } from 'path';
+import { createHash } from 'crypto';
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
 
 // src/database/connection.ts
 var __filename$1 = fileURLToPath(import.meta.url);
@@ -8,6 +10,9 @@ var __dirname$1 = dirname(__filename$1);
 var DEFAULT_DB_PATH = process.env.LSP_DB_PATH || process.env.HYPERSCRIPT_LSP_DB || join(__dirname$1, "../data/patterns.db");
 var dbInstance = null;
 var currentDbPath = null;
+function getDefaultDbPath() {
+  return DEFAULT_DB_PATH;
+}
 function getDatabase(options = {}) {
   const dbPath = options.dbPath ?? DEFAULT_DB_PATH;
   if (dbInstance !== null && currentDbPath === dbPath) {
@@ -804,6 +809,64 @@ async function getLanguageDocsStats(options) {
     expressionOperators: getCount("expression_operators")
   };
 }
+function repoRootFromDbPath(dbPath) {
+  return resolve(dirname(dbPath), "..", "..", "..");
+}
+function walkTsFiles(dir, acc) {
+  if (!existsSync(dir)) return;
+  for (const name of readdirSync(dir).sort()) {
+    if (name === "node_modules" || name === "dist" || name === "__tests__") continue;
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      walkTsFiles(full, acc);
+    } else if (name.endsWith(".ts") && !name.endsWith(".test.ts") && !name.endsWith(".d.ts")) {
+      acc.push(full);
+    }
+  }
+}
+function dbInputFiles(dbPath) {
+  const root = repoRootFromDbPath(dbPath);
+  const files = [];
+  walkTsFiles(join(root, "packages", "i18n", "src"), files);
+  walkTsFiles(join(root, "packages", "semantic", "src"), files);
+  const pr = join(root, "packages", "patterns-reference");
+  for (const f of [
+    join(pr, "scripts", "init-db.ts"),
+    join(pr, "scripts", "sync-translations.ts"),
+    join(pr, "src", "sync", "span-mask.ts")
+  ]) {
+    if (existsSync(f)) files.push(f);
+  }
+  return files.sort();
+}
+function computeDbInputHash(dbPath) {
+  const root = repoRootFromDbPath(dbPath);
+  const files = dbInputFiles(dbPath);
+  const h = createHash("sha256");
+  h.update(`files:${files.length}\0`);
+  for (const f of files) {
+    h.update(relative(root, f).split(sep).join("/"));
+    h.update("\0");
+    h.update(readFileSync(f));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+function dbStampPath(dbPath) {
+  return `${dbPath}.stamp`;
+}
+function writeDbStamp(dbPath) {
+  writeFileSync(dbStampPath(dbPath), `${computeDbInputHash(dbPath)}
+`, "utf8");
+}
+function checkDbStamp(dbPath) {
+  const sp = dbStampPath(dbPath);
+  if (!existsSync(sp)) return { status: "unstamped" };
+  const expected = readFileSync(sp, "utf8").trim();
+  const actual = computeDbInputHash(dbPath);
+  return actual === expected ? { status: "ok" } : { status: "stale", expected, actual };
+}
 
 // src/sync/index.ts
 async function syncTranslations(_options = {}) {
@@ -1268,4 +1331,4 @@ function createPatternsReference(options) {
 }
 var VERSION = "0.1.0";
 
-export { DatabasePatternsProvider, VERSION, addLLMExample, buildFewShotContext, buildFewShotContextSync, closeDatabase, createLLMAdapter, createPatternsProvider, createPatternsReference, discoverPatterns, findExamplesByCommand, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllPatterns, getAllSpecialSymbols, getAllTranslations, getBehaviorPatterns, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultProvider, getExamplesByCommand, getExpressionByName, getExpressionsByCategory, getFeatureByName, getHighConfidenceTranslations, getHighQualityExamples, getKeywordByName, getLLMExampleStats, getLLMExamples, getLLMStats, getLanguageDocsStats, getMostUsedExamples, getPatternById, getPatternStats, getPatternsByCategory, getPatternsByCommand, getSpecialSymbolByName, getSupportedLanguages, getTranslation, getTranslationStats, getTranslationsByLanguage, getVerifiedTranslations, getWordOrder, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, searchPatterns, seedLLMExamples, syncTranslations, trackExampleUsage, uninitializeSemanticIntegration, updateQualityScore, validateAllTranslations, verifyTranslation };
+export { DatabasePatternsProvider, VERSION, addLLMExample, buildFewShotContext, buildFewShotContextSync, checkDbStamp, closeDatabase, computeDbInputHash, createLLMAdapter, createPatternsProvider, createPatternsReference, dbStampPath, discoverPatterns, findExamplesByCommand, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllPatterns, getAllSpecialSymbols, getAllTranslations, getBehaviorPatterns, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultDbPath, getDefaultProvider, getExamplesByCommand, getExpressionByName, getExpressionsByCategory, getFeatureByName, getHighConfidenceTranslations, getHighQualityExamples, getKeywordByName, getLLMExampleStats, getLLMExamples, getLLMStats, getLanguageDocsStats, getMostUsedExamples, getPatternById, getPatternStats, getPatternsByCategory, getPatternsByCommand, getSpecialSymbolByName, getSupportedLanguages, getTranslation, getTranslationStats, getTranslationsByLanguage, getVerifiedTranslations, getWordOrder, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, searchPatterns, seedLLMExamples, syncTranslations, trackExampleUsage, uninitializeSemanticIntegration, updateQualityScore, validateAllTranslations, verifyTranslation, writeDbStamp };

package/dist/{llm-4zwmAvZ8.d.mts → llm-BS3mf0VG.d.mts}

@@ -1,4 +1,4 @@
-import { S as SearchOptions, c as ConnectionOptions, P as Pattern, j as PatternStats, o as Translation, W as WordOrder, r as VerificationResult, L as LLMExample } from './index-BhzKat9K.mjs';
+import { l as SearchOptions, C as ConnectionOptions, a as Pattern, k as PatternStats, o as Translation, W as WordOrder, r as VerificationResult, e as LLMExample } from './index-1ENU9L4F.mjs';
 
 /**
  * Pattern Queries API
@@ -128,4 +128,4 @@ declare function getLLMStats(options?: ConnectionOptions): Promise<{
     totalUsage: number;
 }>;
 
-export { addLLMExample as a, buildFewShotContext as b, getAllTranslations as c, getBehaviorPatterns as d, getExamplesByCommand as e, getHighConfidenceTranslations as f, getAllPatterns as g, getHighQualityExamples as h, getLLMExamples as i, getLLMStats as j, getMostUsedExamples as k, getPatternById as l, getPatternStats as m, getPatternsByCategory as n, getPatternsByCommand as o, getTranslation as p, getTranslationStats as q, getTranslationsByLanguage as r, getVerifiedTranslations as s, getWordOrder as t, searchPatterns as u, updateQualityScore as v, verifyTranslation as w };
+export { addLLMExample as a, buildFewShotContext as b, getAllTranslations as c, getExamplesByCommand as d, getHighConfidenceTranslations as e, getHighQualityExamples as f, getAllPatterns as g, getLLMExamples as h, getLLMStats as i, getMostUsedExamples as j, getPatternById as k, getPatternStats as l, getPatternsByCategory as m, getPatternsByCommand as n, getTranslation as o, getTranslationStats as p, getTranslationsByLanguage as q, getVerifiedTranslations as r, getWordOrder as s, searchPatterns as t, updateQualityScore as u, verifyTranslation as v, getBehaviorPatterns as w };

package/dist/{llm-B7pwZ472.d.ts → llm-DkGTC6X7.d.ts}

@@ -1,4 +1,4 @@
-import { S as SearchOptions, c as ConnectionOptions, P as Pattern, j as PatternStats, o as Translation, W as WordOrder, r as VerificationResult, L as LLMExample } from './index-BhzKat9K.js';
+import { l as SearchOptions, C as ConnectionOptions, a as Pattern, k as PatternStats, o as Translation, W as WordOrder, r as VerificationResult, e as LLMExample } from './index-1ENU9L4F.js';
 
 /**
  * Pattern Queries API
@@ -128,4 +128,4 @@ declare function getLLMStats(options?: ConnectionOptions): Promise<{
     totalUsage: number;
 }>;
 
-export { addLLMExample as a, buildFewShotContext as b, getAllTranslations as c, getBehaviorPatterns as d, getExamplesByCommand as e, getHighConfidenceTranslations as f, getAllPatterns as g, getHighQualityExamples as h, getLLMExamples as i, getLLMStats as j, getMostUsedExamples as k, getPatternById as l, getPatternStats as m, getPatternsByCategory as n, getPatternsByCommand as o, getTranslation as p, getTranslationStats as q, getTranslationsByLanguage as r, getVerifiedTranslations as s, getWordOrder as t, searchPatterns as u, updateQualityScore as v, verifyTranslation as w };
+export { addLLMExample as a, buildFewShotContext as b, getAllTranslations as c, getExamplesByCommand as d, getHighConfidenceTranslations as e, getHighQualityExamples as f, getAllPatterns as g, getLLMExamples as h, getLLMStats as i, getMostUsedExamples as j, getPatternById as k, getPatternStats as l, getPatternsByCategory as m, getPatternsByCommand as n, getTranslation as o, getTranslationStats as p, getTranslationsByLanguage as q, getVerifiedTranslations as r, getWordOrder as s, searchPatterns as t, updateQualityScore as u, verifyTranslation as v, getBehaviorPatterns as w };

package/dist/sync/index.d.mts

@@ -1,6 +1,45 @@
-import { D as DiscoveryResult, m as SyncOptions, n as SyncResult, V as ValidationOptions, q as ValidationResult } from '../index-BhzKat9K.mjs';
+import { D as DiscoveryResult, m as SyncOptions, n as SyncResult, V as ValidationOptions, q as ValidationResult } from '../index-1ENU9L4F.mjs';
 import '@lokascript/semantic';
 
+/**
+ * DB provenance stamp — guards against running the multilingual gate against a
+ * `patterns.db` that was generated from *different* source than is currently checked
+ * out (the cross-branch "phantom regression" footgun).
+ *
+ * The DB's content (transformer translation text + stored parser confidence /
+ * verified_parses) is determined by the i18n + semantic **source**, plus the seed and
+ * sync scripts. We hash that source (not the gitignored, build-non-deterministic
+ * `dist/`) so the stamp catches a branch / source change regardless of whether `dist`
+ * happened to be rebuilt. `sync-translations` writes the stamp next to the DB; the
+ * gate verifies it before trusting a comparison against the committed baseline.
+ *
+ * The stamp file (`patterns.db.stamp`) is a **local** artifact (gitignored) — it
+ * records "what source produced *my* local DB", which is exactly what the gate needs
+ * to confirm the DB is fresh for the current working tree.
+ */
+/**
+ * Compute the provenance hash of the DB's source inputs. Stable across machines (it
+ * hashes committed source, keyed by repo-relative path).
+ */
+declare function computeDbInputHash(dbPath: string): string;
+declare function dbStampPath(dbPath: string): string;
+/** Write the provenance stamp next to the DB (called at the end of sync). */
+declare function writeDbStamp(dbPath: string): void;
+type DbStampStatus = {
+    status: 'ok';
+} | {
+    status: 'unstamped';
+} | {
+    status: 'stale';
+    expected: string;
+    actual: string;
+};
+/**
+ * Verify the DB's stamp against the current source. `unstamped` (no sidecar) is
+ * returned when the DB predates this guard — callers should warn, not hard-fail.
+ */
+declare function checkDbStamp(dbPath: string): DbStampStatus;
+
 /**
  * Sync Module
  *
@@ -39,4 +78,4 @@ declare function seedLLMExamples(_dryRun?: boolean): Promise<{
     count: number;
 }>;
 
-export { DiscoveryResult, SyncOptions, SyncResult, ValidationOptions, ValidationResult, discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations };
+export { type DbStampStatus, DiscoveryResult, SyncOptions, SyncResult, ValidationOptions, ValidationResult, checkDbStamp, computeDbInputHash, dbStampPath, discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations, writeDbStamp };

package/dist/sync/index.d.ts

@@ -1,6 +1,45 @@
-import { D as DiscoveryResult, m as SyncOptions, n as SyncResult, V as ValidationOptions, q as ValidationResult } from '../index-BhzKat9K.js';
+import { D as DiscoveryResult, m as SyncOptions, n as SyncResult, V as ValidationOptions, q as ValidationResult } from '../index-1ENU9L4F.js';
 import '@lokascript/semantic';
 
+/**
+ * DB provenance stamp — guards against running the multilingual gate against a
+ * `patterns.db` that was generated from *different* source than is currently checked
+ * out (the cross-branch "phantom regression" footgun).
+ *
+ * The DB's content (transformer translation text + stored parser confidence /
+ * verified_parses) is determined by the i18n + semantic **source**, plus the seed and
+ * sync scripts. We hash that source (not the gitignored, build-non-deterministic
+ * `dist/`) so the stamp catches a branch / source change regardless of whether `dist`
+ * happened to be rebuilt. `sync-translations` writes the stamp next to the DB; the
+ * gate verifies it before trusting a comparison against the committed baseline.
+ *
+ * The stamp file (`patterns.db.stamp`) is a **local** artifact (gitignored) — it
+ * records "what source produced *my* local DB", which is exactly what the gate needs
+ * to confirm the DB is fresh for the current working tree.
+ */
+/**
+ * Compute the provenance hash of the DB's source inputs. Stable across machines (it
+ * hashes committed source, keyed by repo-relative path).
+ */
+declare function computeDbInputHash(dbPath: string): string;
+declare function dbStampPath(dbPath: string): string;
+/** Write the provenance stamp next to the DB (called at the end of sync). */
+declare function writeDbStamp(dbPath: string): void;
+type DbStampStatus = {
+    status: 'ok';
+} | {
+    status: 'unstamped';
+} | {
+    status: 'stale';
+    expected: string;
+    actual: string;
+};
+/**
+ * Verify the DB's stamp against the current source. `unstamped` (no sidecar) is
+ * returned when the DB predates this guard — callers should warn, not hard-fail.
+ */
+declare function checkDbStamp(dbPath: string): DbStampStatus;
+
 /**
  * Sync Module
  *
@@ -39,4 +78,4 @@ declare function seedLLMExamples(_dryRun?: boolean): Promise<{
     count: number;
 }>;
 
-export { DiscoveryResult, SyncOptions, SyncResult, ValidationOptions, ValidationResult, discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations };
+export { type DbStampStatus, DiscoveryResult, SyncOptions, SyncResult, ValidationOptions, ValidationResult, checkDbStamp, computeDbInputHash, dbStampPath, discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations, writeDbStamp };

package/dist/sync/index.js

@@ -1,5 +1,69 @@
 'use strict';
 
+var crypto = require('crypto');
+var fs = require('fs');
+var path = require('path');
+
+// src/sync/db-stamp.ts
+function repoRootFromDbPath(dbPath) {
+  return path.resolve(path.dirname(dbPath), "..", "..", "..");
+}
+function walkTsFiles(dir, acc) {
+  if (!fs.existsSync(dir)) return;
+  for (const name of fs.readdirSync(dir).sort()) {
+    if (name === "node_modules" || name === "dist" || name === "__tests__") continue;
+    const full = path.join(dir, name);
+    const st = fs.statSync(full);
+    if (st.isDirectory()) {
+      walkTsFiles(full, acc);
+    } else if (name.endsWith(".ts") && !name.endsWith(".test.ts") && !name.endsWith(".d.ts")) {
+      acc.push(full);
+    }
+  }
+}
+function dbInputFiles(dbPath) {
+  const root = repoRootFromDbPath(dbPath);
+  const files = [];
+  walkTsFiles(path.join(root, "packages", "i18n", "src"), files);
+  walkTsFiles(path.join(root, "packages", "semantic", "src"), files);
+  const pr = path.join(root, "packages", "patterns-reference");
+  for (const f of [
+    path.join(pr, "scripts", "init-db.ts"),
+    path.join(pr, "scripts", "sync-translations.ts"),
+    path.join(pr, "src", "sync", "span-mask.ts")
+  ]) {
+    if (fs.existsSync(f)) files.push(f);
+  }
+  return files.sort();
+}
+function computeDbInputHash(dbPath) {
+  const root = repoRootFromDbPath(dbPath);
+  const files = dbInputFiles(dbPath);
+  const h = crypto.createHash("sha256");
+  h.update(`files:${files.length}\0`);
+  for (const f of files) {
+    h.update(path.relative(root, f).split(path.sep).join("/"));
+    h.update("\0");
+    h.update(fs.readFileSync(f));
+    h.update("\0");
+  }
+  return h.digest("hex");
+}
+function dbStampPath(dbPath) {
+  return `${dbPath}.stamp`;
+}
+function writeDbStamp(dbPath) {
+  fs.writeFileSync(dbStampPath(dbPath), `${computeDbInputHash(dbPath)}
+`, "utf8");
+}
+function checkDbStamp(dbPath) {
+  const sp = dbStampPath(dbPath);
+  if (!fs.existsSync(sp)) return { status: "unstamped" };
+  const expected = fs.readFileSync(sp, "utf8").trim();
+  const actual = computeDbInputHash(dbPath);
+  return actual === expected ? { status: "ok" } : { status: "stale", expected, actual };
+}
+
 // src/sync/index.ts
 async function syncTranslations(_options = {}) {
   throw new Error(
@@ -22,7 +86,11 @@ async function seedLLMExamples(_dryRun = false) {
   );
 }
 
+exports.checkDbStamp = checkDbStamp;
+exports.computeDbInputHash = computeDbInputHash;
+exports.dbStampPath = dbStampPath;
 exports.discoverPatterns = discoverPatterns;
 exports.seedLLMExamples = seedLLMExamples;
 exports.syncTranslations = syncTranslations;
 exports.validateAllTranslations = validateAllTranslations;
+exports.writeDbStamp = writeDbStamp;