@mindflight/mindbrain-personal-studio 0.6.2 → 0.6.3

package/examples/immeuble/scripts/starterkit/facet-prefix.mjs

@@ -0,0 +1,166 @@
+/**
+ * Facet prefix normalization for entity.facet nomenclature.
+ *
+ * Stored facets use bare keys in the JSON column; schema context lives in schema_id.
+ * Declared required_facets use entity.facet (e.g. unit.quota_basis).
+ * This module bridges bare storage and prefixed declarations.
+ */
+
+/**
+ * Derive entity name from schema_id (immeuble:core:unit -> unit) or facets.entity_type.
+ * @param {string|null|undefined} schemaId
+ * @param {Record<string, unknown>|null} facets
+ * @returns {string}
+ */
+export function entityFromSchema(schemaId, facets = null) {
+  if (schemaId && typeof schemaId === "string") {
+    const parts = schemaId.split(":");
+    if (parts.length >= 1) {
+      return parts.at(-1) ?? "";
+    }
+  }
+  const entityType = facets?.entity_type;
+  return typeof entityType === "string" ? entityType : "";
+}
+
+/**
+ * Build observed facet index from facet rows.
+ * Indexes both bare keys and entity.facet prefixed keys.
+ *
+ * @param {Array<{ schema_id?: string, facets?: string|Record<string, unknown> }>} rows
+ * @returns {{ bare: Set<string>, prefixed: Set<string>, all: Set<string> }}
+ */
+export function buildObservedFacetIndex(rows) {
+  const bare = new Set();
+  const prefixed = new Set();
+  const all = new Set();
+
+  for (const row of rows) {
+    const facets = parseFacetsJson(row.facets);
+    if (!facets || typeof facets !== "object") continue;
+
+    const entity = entityFromSchema(row.schema_id, facets);
+    for (const key of Object.keys(facets)) {
+      if (!key || key.startsWith("_")) continue;
+      bare.add(key);
+      all.add(key);
+      if (entity) {
+        const prefixedKey = `${entity}.${key}`;
+        prefixed.add(prefixedKey);
+        all.add(prefixedKey);
+      }
+    }
+  }
+
+  return { bare, prefixed, all };
+}
+
+/**
+ * Check whether a required facet is observed (prefix-aware).
+ * - entity.facet -> match prefixed index (or bare if entity matches and bare exists)
+ * - bare facet -> match bare index only
+ *
+ * @param {string} requiredFacet
+ * @param {{ bare: Set<string>, prefixed: Set<string>, all: Set<string> }} index
+ * @returns {boolean}
+ */
+export function facetIsObserved(requiredFacet, index) {
+  if (!requiredFacet) return false;
+  if (requiredFacet.includes(".")) {
+    if (index.prefixed.has(requiredFacet) || index.all.has(requiredFacet)) {
+      return true;
+    }
+    const dot = requiredFacet.indexOf(".");
+    const entity = requiredFacet.slice(0, dot);
+    const bareKey = requiredFacet.slice(dot + 1);
+    return index.bare.has(bareKey) && Boolean(entity);
+  }
+  return index.bare.has(requiredFacet) || index.all.has(requiredFacet);
+}
+
+/**
+ * Return required facets not observed in the index.
+ * @param {string[]} requiredFacets
+ * @param {{ bare: Set<string>, prefixed: Set<string>, all: Set<string> }} index
+ * @returns {string[]}
+ */
+export function missingRequiredFacets(requiredFacets, index) {
+  return [...new Set(requiredFacets)].filter((f) => !facetIsObserved(f, index)).sort();
+}
+
+/**
+ * Extract known facet terms from a StarterKit model_contract.json shape.
+ * @param {Record<string, unknown>} contract
+ * @returns {{ schemas: Set<string>, facets: Set<string>, edges: Set<string> }}
+ */
+export function knownTermsFromContract(contract) {
+  const schemas = new Set(Object.keys(contract.schemas ?? {}));
+  const facets = new Set(["record_id", "workspace_id", "label"]);
+  for (const schema of Object.values(contract.schemas ?? {})) {
+    if (schema && typeof schema === "object" && schema.facets) {
+      for (const key of Object.keys(schema.facets)) {
+        facets.add(key);
+      }
+    }
+  }
+  const edges = new Set();
+  for (const edge of contract.edge_types ?? []) {
+    const type = typeof edge === "string" ? edge : edge?.type;
+    if (type) edges.add(type);
+  }
+  return { schemas, facets, edges };
+}
+
+/**
+ * Normalize edge type for comparison (case-insensitive).
+ * @param {string} edge
+ * @returns {string}
+ */
+export function normalizeEdgeType(edge) {
+  return String(edge ?? "").trim().toUpperCase();
+}
+
+/**
+ * Check if required edge exists in relation counts (case-insensitive).
+ * @param {string} requiredEdge
+ * @param {Record<string, number>} relationCounts
+ * @returns {boolean}
+ */
+export function edgeIsObserved(requiredEdge, relationCounts) {
+  const norm = normalizeEdgeType(requiredEdge);
+  for (const [key, count] of Object.entries(relationCounts)) {
+    if (normalizeEdgeType(key) === norm && count > 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {Record<string, unknown>|null}
+ */
+export function parseFacetsJson(value) {
+  if (value == null) return null;
+  if (typeof value === "object" && !Array.isArray(value)) {
+    return /** @type {Record<string, unknown>} */ (value);
+  }
+  if (typeof value !== "string") return null;
+  try {
+    const parsed = JSON.parse(value);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? /** @type {Record<string, unknown>} */ (parsed)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format facet list for markdown output.
+ * @param {string[]} values
+ * @returns {string}
+ */
+export function fmtFacetValues(values) {
+  return values.length ? values.map((v) => `\`${v}\``).join(", ") : "n/a";
+}

package/examples/immeuble/scripts/starterkit/sqlite-utils.mjs

@@ -0,0 +1,131 @@
+/**
+ * SQLite helpers for StarterKit projection scripts (CLI sqlite3, JSON output).
+ */
+
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+/**
+ * @param {string} dbPath
+ * @param {string} sql
+ * @returns {Record<string, unknown>[]}
+ */
+export function sqliteQuery(dbPath, sql) {
+  if (!existsSync(dbPath)) {
+    throw new Error(`SQLite database not found: ${dbPath}`);
+  }
+  const res = spawnSync("sqlite3", [dbPath, "-json", sql], { encoding: "utf8" });
+  if (res.status !== 0) {
+    throw new Error(res.stderr?.trim() || res.stdout?.trim() || "sqlite3 query failed");
+  }
+  const text = (res.stdout || "").trim();
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {string} dbPath
+ * @param {string} table
+ * @returns {boolean}
+ */
+export function sqliteTableExists(dbPath, table) {
+  const rows = sqliteQuery(
+    dbPath,
+    `SELECT 1 AS ok FROM sqlite_master WHERE type='table' AND name='${table.replace(/'/g, "''")}' LIMIT 1`
+  );
+  return rows.length > 0;
+}
+
+/**
+ * @param {string} dbPath
+ * @param {string} table
+ * @returns {Set<string>}
+ */
+export function sqliteTableColumns(dbPath, table) {
+  if (!sqliteTableExists(dbPath, table)) return new Set();
+  const rows = sqliteQuery(dbPath, `PRAGMA table_info('${table.replace(/'/g, "''")}')`);
+  return new Set(rows.map((r) => String(r.name ?? "")).filter(Boolean));
+}
+
+/**
+ * @param {Set<string>} columns
+ * @param {string|null|undefined} workspaceId
+ * @returns {{ where: string, params: string[] }}
+ */
+export function workspaceWhere(columns, workspaceId) {
+  if (workspaceId && columns.has("workspace_id")) {
+    return {
+      where: `WHERE workspace_id = '${escapeSql(workspaceId)}'`,
+      params: [workspaceId]
+    };
+  }
+  return { where: "", params: [] };
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapeSql(value) {
+  return String(value).replace(/'/g, "''");
+}
+
+/**
+ * @param {unknown} value
+ * @returns {[boolean, unknown]}
+ */
+export function parseJsonMaybe(value) {
+  if (value == null) return [false, null];
+  if (typeof value === "object") return [true, value];
+  try {
+    return [true, JSON.parse(String(value))];
+  } catch {
+    return [false, null];
+  }
+}
+
+/**
+ * @param {number|null|undefined} unix
+ * @returns {string|null}
+ */
+export function dtFromUnix(unix) {
+  if (!unix) return null;
+  return new Date(Number(unix) * 1000).toISOString();
+}
+
+/**
+ * @param {Record<string, string>} argvMap
+ * @param {string} name
+ * @param {string} defaultValue
+ * @returns {string}
+ */
+export function parseFlag(argvMap, name, defaultValue = "") {
+  return argvMap[name] ?? defaultValue;
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {Record<string, string>}
+ */
+export function parseArgs(argv) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith("--")) {
+      out[key] = next;
+      i++;
+    } else {
+      out[key] = "true";
+    }
+  }
+  return out;
+}

package/examples/immeuble/scripts/verify-immeuble-acceptance.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * Verify immeuble ACCEPTANCE.yaml against filesystem reports and optional DB.
+ *
+ * Usage:
+ *   node examples/immeuble/scripts/verify-immeuble-acceptance.mjs [--db path] [--require-hybrid]
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { parseYaml } from "./yaml-lite.mjs";
+
+const immeubleRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pkgRoot = resolve(immeubleRoot, "..", "..");
+const reportsDir = join(immeubleRoot, "reports");
+
+const args = process.argv.slice(2);
+const dbPath = parseFlag(args, "--db", process.env.GHOSTCRAB_SQLITE_PATH ?? "");
+const requireHybrid = args.includes("--require-hybrid");
+const requireBundle = args.includes("--require-bundle");
+const projectionStrict = args.includes("--projection-strict");
+const requireBusinessCapabilities = args.includes("--require-business-capabilities");
+
+const acceptance = parseYaml(readFileSync(join(immeubleRoot, "ACCEPTANCE.yaml"), "utf8"));
+const results = { ok: true, checks: [], workspace_id: acceptance.workspace_id };
+
+function check(name, ok, detail) {
+  results.checks.push({ name, ok, detail });
+  if (!ok) results.ok = false;
+}
+
+function expectedMin(section, exactKey, minKey) {
+  return Number(section?.[minKey] ?? section?.[exactKey] ?? 0);
+}
+
+function readJson(rel) {
+  const path = join(immeubleRoot, rel);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+const pipeline = readJson("reports/pipeline_audit.json");
+check("pipeline_audit exists", pipeline != null, pipeline ? "ok" : "missing reports/pipeline_audit.json");
+if (pipeline) {
+  check("pipeline_audit.ok", pipeline.ok === true, String(pipeline.ok));
+  check(
+    "facet_rows",
+    pipeline.facet_rows >= expectedMin(acceptance.import_ready, "facet_rows", "facet_rows_min"),
+    `${pipeline.facet_rows} >= ${expectedMin(acceptance.import_ready, "facet_rows", "facet_rows_min")}`
+  );
+  check(
+    "edge_rows",
+    pipeline.edge_rows >= expectedMin(acceptance.import_ready, "edge_rows", "edge_rows_min"),
+    `${pipeline.edge_rows} >= ${expectedMin(acceptance.import_ready, "edge_rows", "edge_rows_min")}`
+  );
+  const typeCounts = acceptance.import_ready.entity_type_counts_min ?? acceptance.import_ready.entity_type_counts ?? {};
+  for (const [type, expected] of Object.entries(typeCounts)) {
+    const actual = pipeline.counts?.[type];
+    check(`entity_count.${type}`, actual >= expected, `${actual} >= ${expected}`);
+  }
+}
+
+const prefixReport = readJson("reports/01-model.validation.json");
+if (prefixReport) {
+  check("schema_id_prefix", prefixReport.ok === true && prefixReport.prefix_violations === 0, JSON.stringify(prefixReport));
+}
+
+const projectionCatalogPath = join(immeubleRoot, "contracts/projection_catalog.yaml");
+if (existsSync(projectionCatalogPath)) {
+  const projectionCatalog = parseYaml(readFileSync(projectionCatalogPath, "utf8"));
+  const projections = Array.isArray(projectionCatalog.projections) ? projectionCatalog.projections : [];
+  const mismatches = projections
+    .filter((entry) => String(entry.description ?? "").trim() !== String(entry.business_question ?? "").trim())
+    .map((entry) => entry.name)
+    .filter(Boolean);
+  check(
+    "projection_catalog.description_is_question",
+    projections.length > 0 && mismatches.length === 0,
+    mismatches.length === 0 ? `${projections.length} projections` : `mismatches: ${mismatches.join(", ")}`
+  );
+} else {
+  check("projection_catalog file", false, "missing contracts/projection_catalog.yaml");
+}
+
+const hybridPath = join(reportsDir, "hybrid-compare.json");
+if (existsSync(hybridPath)) {
+  const hybrid = JSON.parse(readFileSync(hybridPath, "utf8"));
+  const deltas = hybrid.compare?.deltas ?? {};
+  for (const [key, max] of Object.entries(acceptance.hybrid_compare.max_deltas)) {
+    const delta = deltas[key]?.delta;
+    if (typeof delta === "number") {
+      check(`hybrid_delta.${key}`, Math.abs(delta) <= max, `delta=${delta}`);
+    }
+  }
+} else if (requireHybrid || acceptance.hybrid_compare.required) {
+  check("hybrid_compare report", false, "missing reports/hybrid-compare.json");
+}
+
+if (dbPath && existsSync(dbPath)) {
+  const ws = acceptance.workspace_id;
+  const q = (sql) => {
+    const res = spawnSync("sqlite3", [dbPath, "-json", sql], { encoding: "utf8" });
+    if (res.status !== 0) return null;
+    try { return JSON.parse(res.stdout || "[]"); } catch { return []; }
+  };
+
+  const facts = q(`SELECT COUNT(*) AS count FROM agent_facts WHERE workspace_id='${ws}'`);
+  const factsCount = Number(facts?.[0]?.count ?? 0);
+  const rawEntitiesForFacts = q(`SELECT COUNT(*) AS count FROM entities_raw WHERE workspace_id='${ws}'`);
+  const factsOrRawCount = Math.max(factsCount, Number(rawEntitiesForFacts?.[0]?.count ?? 0));
+  check(
+    "db.agent_facts_or_raw_entities",
+    factsOrRawCount >= acceptance.db_after_import.agent_facts_min,
+    `${factsOrRawCount} >= ${acceptance.db_after_import.agent_facts_min}`
+  );
+
+  const violations = q(
+    `SELECT schema_id FROM agent_facts WHERE workspace_id='${ws}' AND schema_id NOT LIKE '${acceptance.schema_id_prefix}%' LIMIT 5`
+  );
+  check(
+    "db.schema_id_violations",
+    (violations?.length ?? 0) === acceptance.db_after_import.schema_id_violations,
+    JSON.stringify(violations?.map((r) => r.schema_id) ?? [])
+  );
+
+  const rels = q(`SELECT COUNT(*) AS count FROM relations_raw WHERE workspace_id='${ws}'`);
+  check(
+    "db.relations_raw",
+    Number(rels?.[0]?.count ?? 0) >= acceptance.db_after_import.relations_raw_min,
+    String(rels?.[0]?.count)
+  );
+
+  const graph = q(`SELECT COUNT(*) AS count FROM graph_entity WHERE workspace_id='${ws}'`);
+  check(
+    "db.graph_entity",
+    Number(graph?.[0]?.count ?? 0) >= acceptance.db_after_import.graph_entity_min,
+    String(graph?.[0]?.count)
+  );
+
+  const gapRulesMin = Number(acceptance.construction_lite?.gap_rules_min ?? 0);
+  if (gapRulesMin > 0) {
+    const gapRules = q(`SELECT COUNT(*) AS count FROM graph_gap_rules WHERE workspace_id='${ws}'`);
+    check(
+      "db.graph_gap_rules",
+      Number(gapRules?.[0]?.count ?? 0) >= gapRulesMin,
+      `${Number(gapRules?.[0]?.count ?? 0)} >= ${gapRulesMin}`
+    );
+  }
+
+  if (requireBusinessCapabilities) {
+    const businessCapabilities = acceptance.business_capabilities ?? {};
+    const activeMin = Number(businessCapabilities.active_min ?? 1);
+    const active = q(
+      `SELECT COUNT(*) AS count FROM agent_facts WHERE workspace_id='${ws}' AND schema_id='ghostcrab:business-capability' AND json_extract(facets_json, '$.activation_status') = 'active'`
+    );
+    const activeCount = Number(active?.[0]?.count ?? 0);
+    check(
+      "db.business_capability_active_count",
+      activeCount >= activeMin,
+      `${activeCount} >= ${activeMin}`
+    );
+
+    const requiredArtifacts = Array.isArray(businessCapabilities.required_artifact_ids)
+      ? businessCapabilities.required_artifact_ids.map((value) => String(value)).filter(Boolean)
+      : [];
+    if (requiredArtifacts.length > 0) {
+      const rows = q(
+        `SELECT json_extract(facets_json, '$.artifact_id') AS artifact_id FROM agent_facts WHERE workspace_id='${ws}' AND schema_id='ghostcrab:business-capability' AND json_extract(facets_json, '$.activation_status') = 'active' AND json_extract(facets_json, '$.artifact_id') IS NOT NULL`
+      );
+      const present = new Set((rows ?? []).map((row) => String(row.artifact_id)));
+      for (const artifactId of requiredArtifacts) {
+        check(
+          `db.business_capability_artifact_id.${artifactId}`,
+          present.has(artifactId),
+          present.has(artifactId) ? "present" : "missing"
+        );
+      }
+    }
+  }
+} else {
+  results.checks.push({ name: "db checks", ok: true, detail: "skipped (no --db)" });
+}
+
+const starterkitAudit = acceptance.starterkit_projection_audit;
+const auditReportPath = join(reportsDir, `projection_audit_${acceptance.workspace_id}.json`);
+if (starterkitAudit && existsSync(auditReportPath)) {
+  const auditReport = JSON.parse(readFileSync(auditReportPath, "utf8"));
+  const summary = auditReport.summary ?? {};
+  const enforce = !starterkitAudit.strict_only || projectionStrict;
+
+  if (enforce) {
+    check(
+      "starterkit.quality_score",
+      Number(summary.quality_score ?? 0) >= Number(starterkitAudit.quality_score_min ?? 0),
+      `${summary.quality_score} >= ${starterkitAudit.quality_score_min}`
+    );
+    check(
+      "starterkit.facet_gaps",
+      Number(summary.required_facet_observation_gap_count ?? 0) <= Number(starterkitAudit.required_facet_observation_gap_max ?? 0),
+      String(summary.required_facet_observation_gap_count)
+    );
+    check(
+      "starterkit.schema_gaps",
+      Number(summary.required_schema_record_gap_count ?? 0) <= Number(starterkitAudit.required_schema_record_gap_max ?? 0),
+      String(summary.required_schema_record_gap_count)
+    );
+    check(
+      "starterkit.edge_gaps",
+      Number(summary.required_edge_type_gap_count ?? 0) <= Number(starterkitAudit.required_edge_type_gap_max ?? 0),
+      String(summary.required_edge_type_gap_count)
+    );
+    check(
+      "starterkit.planned_missing",
+      Number(summary.planned_missing_count ?? 0) <= Number(starterkitAudit.planned_missing_count_max ?? 0),
+      String(summary.planned_missing_count)
+    );
+  } else {
+    results.checks.push({
+      name: "starterkit_projection_audit",
+      ok: true,
+      detail: "informational (use --projection-strict to enforce)"
+    });
+  }
+} else if (starterkitAudit && projectionStrict) {
+  check("starterkit_projection_audit report", false, `missing ${auditReportPath}`);
+}
+
+if (requireBundle) {
+  const bundlePath = join(immeubleRoot, acceptance.bundle.path);
+  if (existsSync(bundlePath)) {
+    const bundle = JSON.parse(readFileSync(bundlePath, "utf8"));
+    check("bundle.scope", bundle.scope?.workspace_id === acceptance.workspace_id, bundle.scope?.workspace_id);
+    check(
+      "bundle.documents_raw",
+      (bundle.documents_raw?.length ?? 0) >= expectedMin(acceptance.bundle, "documents_raw", "documents_raw_min"),
+      String(bundle.documents_raw?.length)
+    );
+    check(
+      "bundle.entities_raw",
+      (bundle.entities_raw?.length ?? 0) >= acceptance.bundle.entities_raw_min,
+      String(bundle.entities_raw?.length)
+    );
+    check(
+      "bundle.relations_raw",
+      (bundle.relations_raw?.length ?? 0) >= acceptance.bundle.relations_raw_min,
+      String(bundle.relations_raw?.length)
+    );
+    check(
+      "bundle.answer_artifacts",
+      (bundle.mindbrain_answer_artifacts?.length ?? 0) >= acceptance.bundle.answer_artifacts_min,
+      String(bundle.mindbrain_answer_artifacts?.length)
+    );
+  } else {
+    check("bundle file", false, acceptance.bundle.path);
+  }
+}
+
+if (acceptance.expected_findings?.file) {
+  const findingsPath = join(immeubleRoot, acceptance.expected_findings.file);
+  if (existsSync(findingsPath)) {
+    const findings = parseYaml(readFileSync(findingsPath, "utf8"));
+    const count = Array.isArray(findings.expected_findings) ? findings.expected_findings.length : 0;
+    check(
+      "expected_findings",
+      count >= Number(acceptance.expected_findings.min_count ?? 1),
+      `${count} >= ${acceptance.expected_findings.min_count}`
+    );
+  } else {
+    check("expected_findings file", false, acceptance.expected_findings.file);
+  }
+}
+
+mkdirSync(reportsDir, { recursive: true });
+writeFileSync(join(reportsDir, "acceptance.validation.json"), JSON.stringify(results, null, 2) + "\n", "utf8");
+console.log(JSON.stringify(results, null, 2));
+process.exit(results.ok ? 0 : 1);
+
+function parseFlag(argv, name, defaultValue) {
+  const index = argv.indexOf(name);
+  if (index === -1) return defaultValue;
+  return argv[index + 1] ?? defaultValue;
+}