@mindflight/mindbrain-personal-studio 0.6.1 → 0.6.3

package/examples/immeuble/reports/projection_candidates.md

@@ -0,0 +1,117 @@
+# Projection Candidate Review
+
+- Workspace: `immeuble`
+- Generated at: `2026-06-14T14:57:25.897Z`
+- Candidate count: 13
+- Materialized count: 0
+- Active lenses: blind_spot_manager, jtbd_human, jtbd_ai
+
+## competency
+
+### Plan d'analyse immeuble — questions métier
+- Scope: `immeuble:competency:questions`
+- Status: `candidate`
+- Origin: `projection_catalog`
+- artifact_kind: `analysis_plan`
+- Required facets: `building.name`, `unit.usage_status`, `lease_contract.validFrom`, `coda_entry.amount`
+- Required edges: `CONTAINS`, `LEASES`, `MATCHED_TO`
+
+## core
+
+### Annuaire immeubles gérés
+- Scope: `immeuble:core:annuaire_coproprietes`
+- Status: `candidate`
+- Origin: `projection_catalog`
+- artifact_kind: `live_answer_view`
+- Required facets: `building.address`, `building.name`, `building.quota_basis`, `block.name`
+- Required edges: `CONTAINS`
+
+### Baux locatifs actifs
+- Scope: `immeuble:core:baux_actifs`
+- Status: `candidate`
+- Origin: `projection_catalog`
+- artifact_kind: `live_answer_view`
+- Required facets: `unit.usage_status`, `unit.lot`, `lease_contract.validFrom`, `lease_contract.monthly_rent`, `person.name`
+- Required edges: `LEASES`, `RENTED_TO`, `OCCUPIES`
+
+### Quotités par immeuble
+- Scope: `immeuble:core:quotites_par_immeuble`
+- Status: `candidate`
+- Origin: `projection_catalog`
+- artifact_kind: `live_answer_view`
+- Required facets: `building.quota_basis`, `unit.tantiemes`, `unit.quota_basis`
+- Required edges: `CONTAINS`
+
+## gestionnaire_syndic
+
+### Impayes et relances en cours
+- Scope: `immeuble:gestionnaire_syndic:impayes_et_relances`
+- Status: `candidate`
+- Origin: `analysis_lens`
+- artifact_kind: `analysis_plan`
+- Required facets: `receipt.amount`, `reminder.level`, `reminder.amount_due`, `charge_call.amount`
+- Required edges: `REQUIRES_REVIEW`, `MATCHED_TO`
+
+### Baux proches de l'echeance
+- Scope: `immeuble:gestionnaire_syndic:baux_echeance`
+- Status: `candidate`
+- Origin: `analysis_lens`
+- artifact_kind: `analysis_plan`
+- Required facets: `lease_contract.validFrom`, `lease_contract.monthly_rent`, `unit.usage_status`
+- Required edges: `LEASES`, `RENTED_TO`
+
+### Anomalies de quotites
+- Scope: `immeuble:gestionnaire_syndic:quotites_anomalie`
+- Status: `candidate`
+- Origin: `analysis_lens`
+- artifact_kind: `analysis_plan`
+- Required facets: `building.quota_basis`, `unit.tantiemes`, `unit.quota_basis`
+- Required edges: `CONTAINS`
+
+### Lots sans occupation declaree
+- Scope: `immeuble:gestionnaire_syndic:occupation_orpheline`
+- Status: `candidate`
+- Origin: `analysis_lens`
+- artifact_kind: `analysis_plan`
+- Required facets: `unit.usage_status`, `person.name`, `household.household_status`
+- Required edges: `OCCUPIES`, `OWNS`, `PRIMARY_RESIDENCE_OF`
+
+### Top actions manager du jour
+- Scope: `immeuble:gestionnaire_syndic:manager_attention_today`
+- Status: `candidate`
+- Origin: `analysis_lens`
+- artifact_kind: `analysis_plan`
+- Required facets: `reminder.level`, `decision.date`, `lease_contract.validFrom`
+- Required edges: `REQUIRES_REVIEW`, `LEASES`
+
+### JTBD gestionnaire: arbitrer avec preuves
+- Scope: `immeuble:gestionnaire_syndic:gestionnaire_decide_arbitrer`
+- Status: `candidate`
+- Origin: `analysis_lens`
+- artifact_kind: `analysis_plan`
+- Required facets: `decision.date`, `coda_entry.amount`, `coda_entry.status`
+- Required edges: `MATCHED_TO`, `REQUIRES_REVIEW`
+
+### JTBD syndic: coordonner la prochaine intervention
+- Scope: `immeuble:gestionnaire_syndic:syndic_coordinate_intervention`
+- Status: `candidate`
+- Origin: `analysis_lens`
+- artifact_kind: `analysis_plan`
+- Required facets: `unit.usage_status`, `shared_space.category`, `shared_equipment.equipment_type`
+- Required edges: `CONTAINS`, `USES_COMMON`
+
+### JTBD agent IA: tour de controle priorisee
+- Scope: `immeuble:gestionnaire_syndic:agent_watchtower_prioritize`
+- Status: `candidate`
+- Origin: `analysis_lens`
+- artifact_kind: `analysis_plan`
+- Required facets: `reminder.level`, `lease_contract.validFrom`, `unit.usage_status`
+- Required edges: `REQUIRES_REVIEW`, `LEASES`
+
+### JTBD agent IA: detective de reconciliation CODA
+- Scope: `immeuble:gestionnaire_syndic:agent_reconciliation_detective`
+- Status: `candidate`
+- Origin: `analysis_lens`
+- artifact_kind: `analysis_plan`
+- Required facets: `coda_entry.amount`, `coda_entry.status`, `charge_call.amount`, `receipt.amount`
+- Required edges: `MATCHED_TO`, `ALLOCATED_TO`

package/examples/immeuble/reports/projection_model_validation.md

@@ -0,0 +1,115 @@
+# Projection Model Validation
+
+## Synthese
+
+- Workspace: `immeuble`
+- Projections catalogue: 4
+- Questions manager: 0
+- Ajouts par patterns: 9
+- Scopes materialises: 0
+
+## Projections catalogue
+
+### Plan d'analyse immeuble — questions métier
+- Question: Quelles questions métier le workspace immeuble doit-il pouvoir traiter ?
+- Scope: `immeuble:competency:questions`
+- artifact_kind: `analysis_plan`
+- Statut: `candidate`
+- Facettes requises: `building.name`, `unit.usage_status`, `lease_contract.validFrom`, `coda_entry.amount`
+- Aretes requises: `CONTAINS`, `LEASES`, `MATCHED_TO`
+
+### Annuaire immeubles gérés
+- Question: Quels immeubles sont gérés et où sont-ils situés ?
+- Scope: `immeuble:core:annuaire_coproprietes`
+- artifact_kind: `live_answer_view`
+- Statut: `candidate`
+- Facettes requises: `building.address`, `building.name`, `building.quota_basis`, `block.name`
+- Aretes requises: `CONTAINS`
+
+### Baux locatifs actifs
+- Question: Quels appartements sont loués, à qui, depuis quelle date ?
+- Scope: `immeuble:core:baux_actifs`
+- artifact_kind: `live_answer_view`
+- Statut: `candidate`
+- Facettes requises: `unit.usage_status`, `unit.lot`, `lease_contract.validFrom`, `lease_contract.monthly_rent`, `person.name`
+- Aretes requises: `LEASES`, `RENTED_TO`, `OCCUPIES`
+
+### Quotités par immeuble
+- Question: Les quotités de chaque immeuble totalisent-elles 1000 ?
+- Scope: `immeuble:core:quotites_par_immeuble`
+- artifact_kind: `live_answer_view`
+- Statut: `candidate`
+- Facettes requises: `building.quota_basis`, `unit.tantiemes`, `unit.quota_basis`
+- Aretes requises: `CONTAINS`
+
+## Questions manquantes proposees
+
+### Impayes et relances en cours
+- Categorie: `blind_spot_manager`
+- Question: Quels coproprietaires ont des impayes ou relances actives ?
+- Facettes requises: `receipt.amount`, `reminder.level`, `reminder.amount_due`, `charge_call.amount`
+- Aretes requises: `REQUIRES_REVIEW`, `MATCHED_TO`
+
+### Baux proches de l'echeance
+- Categorie: `blind_spot_manager`
+- Question: Quels baux arrivent a echeance dans les 90 prochains jours ?
+- Facettes requises: `lease_contract.validFrom`, `lease_contract.monthly_rent`, `unit.usage_status`
+- Aretes requises: `LEASES`, `RENTED_TO`
+
+### Anomalies de quotites
+- Categorie: `blind_spot_manager`
+- Question: Quels immeubles ont des quotites qui ne totalisent pas le quota_basis ?
+- Facettes requises: `building.quota_basis`, `unit.tantiemes`, `unit.quota_basis`
+- Aretes requises: `CONTAINS`
+
+### Lots sans occupation declaree
+- Categorie: `blind_spot_manager`
+- Question: Quels lots n'ont ni proprietaire occupant ni locataire declare ?
+- Facettes requises: `unit.usage_status`, `person.name`, `household.household_status`
+- Aretes requises: `OCCUPIES`, `OWNS`, `PRIMARY_RESIDENCE_OF`
+
+### Top actions manager du jour
+- Categorie: `blind_spot_manager`
+- Question: Quelles 3 a 5 actions doivent remonter au gestionnaire aujourd'hui ?
+- Facettes requises: `reminder.level`, `decision.date`, `lease_contract.validFrom`
+- Aretes requises: `REQUIRES_REVIEW`, `LEASES`
+
+### JTBD gestionnaire: arbitrer avec preuves
+- Categorie: `jtbd_human`
+- Question: Quand plusieurs signaux se contredisent, quelle decision puis-je prendre avec suffisamment de preuves ?
+- Facettes requises: `decision.date`, `coda_entry.amount`, `coda_entry.status`
+- Aretes requises: `MATCHED_TO`, `REQUIRES_REVIEW`
+
+### JTBD syndic: coordonner la prochaine intervention
+- Categorie: `jtbd_human`
+- Question: Que faut-il coordonner pour la prochaine intervention sur un lot ou une zone commune ?
+- Facettes requises: `unit.usage_status`, `shared_space.category`, `shared_equipment.equipment_type`
+- Aretes requises: `CONTAINS`, `USES_COMMON`
+
+### JTBD agent IA: tour de controle priorisee
+- Categorie: `jtbd_ai`
+- Question: Quels signaux dois-je surveiller et remonter sans saturer le gestionnaire ?
+- Facettes requises: `reminder.level`, `lease_contract.validFrom`, `unit.usage_status`
+- Aretes requises: `REQUIRES_REVIEW`, `LEASES`
+
+### JTBD agent IA: detective de reconciliation CODA
+- Categorie: `jtbd_ai`
+- Question: Quelles incoherences entre paiements CODA et appels de charges dois-je investiguer ?
+- Facettes requises: `coda_entry.amount`, `coda_entry.status`, `charge_call.amount`, `receipt.amount`
+- Aretes requises: `MATCHED_TO`, `ALLOCATED_TO`
+
+## Dimensions et graphes a valider
+
+### Facettes nouvelles par rapport aux sources
+
+`charge_call.amount`, `coda_entry.status`, `decision.date`, `household.household_status`, `receipt.amount`, `reminder.amount_due`, `reminder.level`, `shared_equipment.equipment_type`, `shared_space.category`
+
+### Aretes nouvelles par rapport aux sources
+
+`ALLOCATED_TO`, `OWNS`, `PRIMARY_RESIDENCE_OF`, `REQUIRES_REVIEW`, `USES_COMMON`
+
+## Gaps versus model_contract
+
+- Schemas inconnus: n/a
+- Facettes inconnues: n/a
+- Aretes inconnues: n/a

package/examples/immeuble/reports/reindex.json

@@ -0,0 +1,4 @@
+{
+  "graph_projected": 396,
+  "facet_assignments": 131
+}

package/examples/immeuble/reports/reset-immeuble-workspace.json

@@ -0,0 +1,32 @@
+{
+  "ok": true,
+  "db_path": "/tmp/immeuble-reset-test/immeuble.sqlite",
+  "steps": [
+    {
+      "step": "build",
+      "ok": true,
+      "status": 0,
+      "stderr": ""
+    },
+    {
+      "step": "import",
+      "ok": true,
+      "status": 0,
+      "stderr": ""
+    },
+    {
+      "step": "verify_acceptance",
+      "ok": true,
+      "status": 0,
+      "stderr": ""
+    },
+    {
+      "step": "audit_projections",
+      "ok": true,
+      "status": 0,
+      "stderr": ""
+    }
+  ],
+  "started_at": "2026-06-14T08:31:20.938Z",
+  "finished_at": "2026-06-14T08:31:44.529Z"
+}

package/examples/immeuble/reports/schema-id-prefix-check.json

@@ -0,0 +1,5 @@
+{
+  "ok": true,
+  "checked": 131,
+  "violations": []
+}

package/examples/immeuble/scripts/audit-immeuble-projections.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * Audit Immeuble projections after import or bundle load.
+ *
+ * Checks:
+ * - projection_catalog.yaml entries are present in consumer contract and seed
+ * - live_answer_view artifacts are listable
+ * - each required artifact has non-empty payload content
+ * - consumer_contract.yaml structure is valid
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } 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 workspaceId = parseFlag(process.argv.slice(2), "--workspace-id", "immeuble");
+const gcpPath = resolveGcp();
+
+mkdirSync(reportsDir, { recursive: true });
+
+const catalog = parseYaml(readFileSync(join(immeubleRoot, "contracts", "projection_catalog.yaml"), "utf8"));
+const consumer = parseYaml(readFileSync(join(immeubleRoot, "contracts", "consumer_contract.yaml"), "utf8"));
+const seedLines = readFileSync(join(immeubleRoot, "contracts", "answer_artifacts.seed.jsonl"), "utf8")
+  .trim()
+  .split("\n")
+  .filter(Boolean)
+  .map((line) => safeParseJson(line))
+  .filter(Boolean);
+
+const expectedSeedById = Object.fromEntries(seedLines.map((row) => {
+  const id = row.artifact?.artifact_id;
+  return id ? [id, row] : null;
+}).filter(Boolean));
+
+const expectedCatalogIds = (catalog.projections ?? []).map((entry) => {
+  const kind = (entry.artifact_kind || "").toString();
+  const prefix = kind === "analysis_plan" ? "analysis_plan__" : "live_answer_view__";
+  return `${prefix}${entry.name}`;
+});
+
+const expectedLiveArtifactIds = seedLines
+  .filter((row) => row.artifact?.artifact_kind === "live_answer_view")
+  .map((row) => row.artifact.artifact_id)
+  .filter(Boolean);
+
+const listRes = spawnSync(process.execPath, [
+  gcpPath,
+  "brain", "artifact", "list",
+  "--workspace-id", workspaceId,
+  "--kind", "live_answer_view",
+  "--limit", "200"
+], {
+  cwd: pkgRoot,
+  encoding: "utf8",
+  env: process.env
+});
+
+let listedIds = [];
+let listedById = new Map();
+let listOk = listRes.status === 0;
+if (listOk) {
+  const payload = safeParseJson(listRes.stdout.trim());
+  if (payload) {
+    const artifacts = (payload.artifacts ?? payload.items ?? []).filter(Boolean);
+    listedIds = artifacts.map((a) => a.artifact_id ?? a.id).filter(Boolean);
+    listedById = new Map(artifacts.map((a) => [a.artifact_id ?? a.id, a]));
+  } else {
+    listOk = false;
+  }
+}
+if (!listOk) {
+  const fallback = listArtifactsFromSqlite();
+  if (fallback.ok) {
+    listOk = true;
+    listedIds = fallback.artifacts.map((a) => a.artifact_id).filter(Boolean);
+    listedById = new Map(fallback.artifacts.map((a) => [a.artifact_id, a]));
+  }
+}
+
+const payloadIssues = [];
+
+function pushIssue(label, detail) {
+  payloadIssues.push({ label, detail });
+}
+
+function catalogIdForEntry(entry) {
+  const kind = (entry?.artifact_kind || "").toString();
+  const prefix = kind === "analysis_plan" ? "analysis_plan__" : "live_answer_view__";
+  return `${prefix}${entry?.name}`;
+}
+
+function isArrayOrStringArray(value) {
+  return Array.isArray(value) && value.length > 0;
+}
+
+for (const entry of catalog.projections ?? []) {
+  const expectedId = catalogIdForEntry(entry);
+  const seed = expectedSeedById[expectedId];
+  if (!seed) {
+    pushIssue("seed_missing", `projection ${expectedId} missing in answer_artifacts.seed.jsonl`);
+    continue;
+  }
+
+  const listed = listedById.get(expectedId);
+  const listedPayload = listed ? parseArtifactPayload(listed) : null;
+  const seedPayload = safeParseJson(seed.artifact?.payload_json) || {};
+
+  const artifactKind = seed.artifact?.artifact_kind ?? entry.artifact_kind;
+  if (artifactKind === "analysis_plan") {
+    const questions = seedPayload.competency_questions ?? listedPayload?.competency_questions;
+    if (!isArrayOrStringArray(questions)) {
+      pushIssue("payload", `${expectedId}: competency_questions missing or empty`);
+    }
+  } else if (artifactKind === "live_answer_view") {
+    if (!listed && listOk) {
+      pushIssue("registry", `${expectedId}: not found in artifact list`);
+    }
+    const summary = seedPayload.summary ?? listedPayload?.summary;
+    if (typeof summary !== "string" || summary.trim() === "") {
+      pushIssue("payload", `${expectedId}: summary missing in payload`);
+    }
+    if (!isArrayOrStringArray(seedPayload.refresh_checks ?? listedPayload?.refresh_checks)) {
+      pushIssue("payload", `${expectedId}: refresh_checks missing or empty`);
+    }
+  }
+}
+
+const catalogIds = expectedCatalogIds;
+const listedLiveIds = listedIds;
+const missingFromRegistry = expectedLiveArtifactIds.filter((id) => !listedIds.includes(id));
+const missingFromSeed = catalogIds.filter((id) => !expectedSeedById[id]);
+
+const audit = {
+  ok: payloadIssues.length === 0 && consumer.workspace_id === workspaceId && listOk,
+  workspace_id: workspaceId,
+  catalog_count: catalogIds.length,
+  seed_live_views: expectedLiveArtifactIds.length,
+  listed_live_views: listedLiveIds.length,
+  missing_from_registry: missingFromRegistry,
+  missing_from_seed: missingFromSeed,
+  required_live_views: expectedLiveArtifactIds,
+  listed_live_views_ids: listedLiveIds,
+  list_ok: listOk,
+  payload_issues: payloadIssues,
+  consumer_workspace: consumer.workspace_id,
+  consumer_facet_queries: (consumer.facet_queries ?? []).length,
+  consumer_answer_artifacts: (consumer.answer_artifacts ?? []).length,
+  generated_at: new Date().toISOString()
+};
+
+if (consumer.workspace_id !== workspaceId) {
+  payloadIssues.push({
+    label: "consumer_contract",
+    detail: `consumer workspace mismatch: expected ${workspaceId}, got ${consumer.workspace_id}`
+  });
+}
+
+if (!listOk) {
+  audit.list_skipped = true;
+  audit.list_stderr = (listRes.stderr || listRes.stdout || "").slice(0, 500);
+  payloadIssues.push({
+    label: "registry_list",
+    detail: "artifact list command failed; cannot validate live answer registry state"
+  });
+}
+
+if (missingFromRegistry.length > 0 && listOk) {
+  payloadIssues.push({
+    label: "missing_from_registry",
+    detail: `missing live_answer_view ids: ${missingFromRegistry.join(", ")}`
+  });
+}
+
+if (catalog.projections && catalogIds.length > 0 && expectedLiveArtifactIds.length === 0) {
+  payloadIssues.push({ label: "seed", detail: "no live_answer_view entries in answer_artifacts.seed.jsonl" });
+}
+
+audit.ok = payloadIssues.length === 0 && consumer.workspace_id === workspaceId && listOk;
+
+writeFileSync(join(reportsDir, "projection_audit.json"), JSON.stringify(audit, null, 2) + "\n", "utf8");
+
+const seedLiveViews = seedLines
+  .filter((row) => row.artifact?.artifact_kind === "live_answer_view")
+  .map((row) => ({
+    id: row.artifact?.artifact_id,
+    workspace_id: row.artifact?.workspace_id
+  }));
+
+writeFileSync(join(reportsDir, "consumer_contract.validation.json"), JSON.stringify({
+  ok: audit.ok && (consumer.workspace_id === workspaceId),
+  workspace_id: consumer.workspace_id,
+  facet_queries: consumer.facet_queries?.length ?? 0,
+  answer_artifacts: consumer.answer_artifacts?.length ?? 0,
+  expected_live_views: expectedLiveArtifactIds,
+  listed_live_views: listedLiveIds,
+  seed_live_views: seedLiveViews
+}, null, 2) + "\n", "utf8");
+
+console.log(JSON.stringify(audit, null, 2));
+process.exit(audit.ok ? 0 : 1);
+
+function parseArtifactPayload(artifact) {
+  if (!artifact) return null;
+  const raw = artifact.payload_json ?? artifact.payload ?? artifact.payload_raw ?? artifact.payloadData;
+  return safeParseJson(raw);
+}
+
+function safeParseJson(value) {
+  if (value == null) return null;
+  if (typeof value === "object") return value;
+  if (typeof value !== "string") return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function parseFlag(argv, name, defaultValue) {
+  const index = argv.indexOf(name);
+  if (index === -1) return defaultValue;
+  return argv[index + 1] ?? defaultValue;
+}
+
+function resolveGcp() {
+  const candidates = [
+    process.env.GHOSTCRAB_GCP,
+    process.env.GHOSTCRAB_ROOT ? join(process.env.GHOSTCRAB_ROOT, "bin", "gcp.mjs") : "",
+    join(pkgRoot, "bin", "gcp.mjs"),
+    join(pkgRoot, "node_modules", "@mindflight", "ghostcrab-personal-mcp", "bin", "gcp.mjs"),
+    resolve(pkgRoot, "..", "ghostcrab-personal-mcp", "bin", "gcp.mjs")
+  ].filter(Boolean);
+  const found = candidates.find((candidate) => existsSync(candidate));
+  return found ?? join(pkgRoot, "bin", "gcp.mjs");
+}
+
+function listArtifactsFromSqlite() {
+  const db = process.env.GHOSTCRAB_SQLITE_PATH;
+  if (!db || !existsSync(db)) return { ok: false, artifacts: [] };
+  const sql = `SELECT artifact_id, slug, workspace_id, artifact_kind, public_label, lifecycle, state, payload_json, legacy_ref FROM mindbrain_answer_artifacts WHERE workspace_id='${workspaceId.replace(/'/g, "''")}' AND artifact_kind='live_answer_view' LIMIT 500;`;
+  const res = spawnSync("sqlite3", ["-json", db, sql], { encoding: "utf8" });
+  if (res.status !== 0) return { ok: false, artifacts: [] };
+  try {
+    const artifacts = JSON.parse(res.stdout || "[]");
+    return { ok: Array.isArray(artifacts), artifacts: Array.isArray(artifacts) ? artifacts : [] };
+  } catch {
+    return { ok: false, artifacts: [] };
+  }
+}