Hot Fix 0.3.1

OntoBricks — Release Notes V3.3.1

Release window: May 2026
Type: Hotfix
Test status: 141 cohort tests passed, 0 failed (49 test_cohort_builder.py, 31 test_dtwin_cohort.py, 34 test_cohort_models.py, 24 test_agent_cohort_tools.py, 3 test_agent_cohort_engine.py).

---

Highlights

• Cohort Discovery: predicate namespace fix — hasClaim (and any predicate loaded outside R2RML) now resolves correctly. The engine no longer silently misses triples whose predicate is in ontology-namespace form (#) when the lookup key is in data-namespace form (/).
• Cohort Discovery: cross-namespace predicate fallback — CohortBuilder gains a local-name alias map mirroring the SparqlTranslator approach, so predicates from a completely foreign namespace (e.g. ontobricks.com/ontology#hasclaim vs. databricks-ontology.com/Cust360Auto/hasclaim) resolve via local-name matching.
• Cohort designer UX — attribute dropdowns in the Path "where" filter and the Compatibility section are now scoped to the entity being filtered, not the full ontology property list.

---

Cohort Discovery — Bug Fixes

Fix 1: ontology-form predicate silent miss (CohortBuilder._outgoing_edge_index)

When data triples were inserted outside the R2RML pipeline (direct insert, W3C OWL round-trip, manual load), their predicates were stored in ontology-namespace form (…#hasClaim) while the lookup key produced by _normalized_links was in data-namespace form (…/hasClaim). This caused a silent neighbours_raw = 0 and an empty cohort.

Changes:

• src/back/core/graph_analysis/CohortBuilder.py — _outgoing_edge_index promoted from @staticmethod to instance method so it can call self._to_data_uri(pred). Every triple predicate is now normalised to data-namespace form when the index is built.
• src/front/static/query/js/query-cohorts.js — _renderTraceLink now guards on in_frontier === 0 before neighbours_raw === 0. When the starting frontier is empty the diagnostic message now reads "the starting frontier for this hop is empty — all members were eliminated before reaching it. Check the compatibility (Stage 3a) filters or the previous hop's target_class." instead of misleadingly blaming the predicate URI.
• tests/test_cohort_builder.py — 2 new tests: test_data_with_ontology_form_predicate_is_indexed_correctly, test_trace_shows_nonzero_raw_for_ontology_form_predicate.

Fix 2: cross-namespace predicate — local-name alias fallback

_to_data_uri can only bridge # ↔ / within the same base namespace. When the domain's object property URIs live in a completely different namespace (e.g. inherited shared namespace ontobricks.com/ontology#) the first fix was not sufficient.

Changes:

• src/back/core/graph_analysis/CohortBuilder.py:
  • _predicate_alias_map() — scans loaded triples, builds {local_name → canonical_data_namespace_uri}, cached in self._cache["predicate_alias"] and invalidated on triple reload.
  • _resolve_predicate(uri) — tries _to_data_uri first; if the URI is unchanged (foreign namespace) falls back to the alias map by local name.
  • _normalized_links and _normalized_compat updated to use _resolve_predicate instead of _to_data_uri.
• tests/test_cohort_builder.py — 1 new test: test_via_from_foreign_namespace_resolved_by_local_name (exact replica of the ElectricitySuspended / Cust360Auto production scenario).

---

Cohort Designer — UX

Attribute dropdowns scoped to entity

Property dropdowns in the Path "where" filter and the Compatibility section previously listed every property in the ontology regardless of the entity in scope. Users had to scroll through unrelated properties when filtering a specific hop.

Changes:

• src/front/static/query/js/query-cohorts.js:
  • New _dataPropsForClass(classUri) helper — filters to data properties whose domain matches the class, with a full-list fallback when ontology metadata is incomplete.
  • _renderHopWhereRow now calls _dataPropsForClass(targetClassUri).
  • _renderCompat now calls _dataPropsForClass(this.rule.class_uri).

---

Modified files

File	Change
src/back/core/graph_analysis/CohortBuilder.py	Predicate normalisation fixes + alias map
src/front/static/query/js/query-cohorts.js	Diagnostic guard + scoped attribute dropdowns
tests/test_cohort_builder.py	3 new regression tests

---

Upgrade notes

No schema, API, or configuration changes. Drop-in replacement for v3.3.0.
If a cohort was returning empty results due to the hasClaim predicate mismatch, re-run Materialise — no manual data migration required.

V0.3.0

OntoBricks — Release Notes V0.3.0

Release window: May, 2026
Test status: all changes shipped with the suite green (2045 passing, 80 CloudFetch probe tests conditionally skipped in CI).

---

Highlights

• Cohort Discovery — new end-to-end feature for business-friendly entity grouping: rule-based linkage (shared resources via predicates), compatibility constraints, a 6-stage deterministic engine, full Volume + Lakebase persistence, graph-triple + Unity Catalog Delta materialisation, and a natural-language Stage 2 agent that translates free-text prompts into validated CohortRule JSON.
• Live Digital Twin build log — the Build page now shows a real-time per-step log panel with elapsed timers, phase descriptions, a one-click export to .log, and honest background-archive handling. TaskManager gains skip_step / complete_current_step so skipped phases are labelled correctly.
• Real /health readiness probe — 11 checks covering filesystem, Databricks auth, SQL warehouse, registry Volume read/write, registry UC DDL permissions, Lakebase schema/table/sequence grants, and CloudFetch capability. /health/detailed retired. New admin Health tab in Settings surfaces the same payload in-app.
• Mapping diagnostics: source table permissions — new third section runs a non-destructive SELECT … LIMIT 0 against every Unity Catalog table referenced by the mapping and reports ok / PERMISSION_DENIED / TABLE_OR_VIEW_NOT_FOUND per table, surfacing missing grants before a build attempt.
• Knowledge Graph — right-click Expand neighbours — any node can be expanded N hops in place without re-running a full SPARQL query. Non-blocking spinner, depth picker, camera zoom + highlight on new nodes. KG preview/expand also hardened against timeouts and 502 errors on large graphs.
• Deployment: single source of truth — scripts/deploy.config.sh + app.yaml.template replace scattered literals across Makefile, deploy.sh, and bootstrap scripts. app.yaml is now a generated artifact. App name ontobricks-030 unified across all tooling.
• CloudFetch — runtime capability probe — DatabricksAuth detects at runtime whether the Apps sandbox can actually reach the CloudFetch storage host, sets use_cloud_fetch accordingly, and exposes the verdict in /health. A new Settings → Global toggle lets admins override the default.
• Task duration & UTC timestamps — TaskManager emits START task / END task log lines with compact durations, serialises duration_seconds in to_dict(), and uses UTC-aware ISO timestamps throughout to prevent timezone-drift bugs in the browser.

---

Cohort Discovery

Stage 1 — deterministic engine, UI, persistence, materialisation

• New CohortRule model with validate(), CRUD endpoints, dry-run + materialise, and a 6-stage pure-Python engine (CohortBuilder) that works against both Delta/Spark SQL and LadybugDB/Cypher backends.
• Materialise to graph (idempotent DELETE then INSERT, per-rule :inCohort<RuleId> predicate) and to Unity Catalog Delta (partitioned by rule_id, chunked INSERT).
• Content-hash cohort URIs (<base>/cohort/<rule_id>/c-sha256(…)[:8]).
• Live preview helpers: class stats, edge count, node count, sample property values, explain_membership (Why? / Why not?).
• 59 new tests across test_cohort_models.py, test_cohort_builder.py, test_dtwin_cohort.py.
• New docs/cohort_discovery.md with mental model, UX walkthrough, 4 worked examples, API summary.

Stage 2 — NL agent for rule generation

• agents/agent_cohort/ — six read-only tools (list_classes, list_properties_of, count_class_members, sample_values_of, propose_rule, dry_run) wired to Stage 1 endpoints.
• One-shot agent loop with 10-iteration cap; never writes — saving still goes through the Builder-protected endpoint.
• UI: Describe tab (NL prompt + agent trace with tool calls, durations, iterations) auto-switches to Build rule tab when a rule is proposed.
• Fix: list_properties_of was returning empty arrays when rdfs:domain was stored as a local name or property URIs were missing — resolved with _domain_matches + _ensure_uri helpers and a fallback to the full object-property list.
• 22 new tests across test_agent_cohort_tools.py (19) and test_agent_cohort_engine.py (3).

Cohort designer — UX refinements

• Three-tab layout (Describe / Build rule / Preview) replaces the full-width drawer; the Preview tab carries a live cohort-count badge.
• Saved rules pane promoted to a persistent right/left rail, always reachable regardless of active tab.
• Dependent dropdowns in the "Link members" section: via property narrows to predicates whose domain is the source class and range is the chosen shared class; falls back to the full list when ontology metadata is incomplete.
• camelCase rule name enforcement: live input sanitisation, paste-to-camelCase, _isValidRuleName validator, _toCamelCase helper applied to agent-generated names. id = label (no more slug fork).
• Rule-scoped predicate and UC table: membership triples use :inCohort<RuleId>; Auto-pick proposes cohorts_<snake_rule_name>. Both the graph-triples hint and the UC-table hint in the Configure-outputs modal now show the actual predicate / table name for the active rule.
• Clickable entity badge in the Preview pane: each cohort member renders as a pill that links to the Sigma graph focused on that node. URI is demoted to inline parenthetical muted text.
• Configure-outputs modal — visible feedback: Auto-pick and Test write access were silently swallowing errors. Both are now four-state (idle → working → success | error) with inline status lines, spinner, toast, and error-envelope surfacing.
• Clearer step labels in the designer: "Link members via a shared entity" (was "When are two members linked?"), "Conditions every member must satisfy" (was "Compatibility policies"). Terminology switched from "class" to "entity" throughout user-facing strings.
• Cohort explain fix — namespace drift: CohortBuilder._members_of_class now checks all URI variants (ontology form, data form, raw) so explain_membership works regardless of which normalisation path the loader used. Enhanced "not in class" diagnostics report typed-as, untyped, or URI not found with actionable advice.
• Rule summary card: removed the redundant rule_id chip (equal to label for camelCase names); fixed binary UC/graph output display to enumerate all four states (graph + UC / graph only / UC only / no outputs).

---

Digital Twin Build

• Live build log panel (#syncBuildLogCard): appears on Build click, grows row-by-row with icon, description, live sub-message, and per-step elapsed timer. Step labels rewritten to plain English ("Preparing mappings…", "Detecting what changed since last build", etc.).
• TaskManager.skip_step() marks a step skipped and advances current_step so the label array stays aligned with execution when phases are conditionally bypassed (e.g. Detecting what changed on first build, Checking source tables on forced full rebuild).
• Export build log: one-click export to digital-twin-build_<timestamp>.log (plain text with a header block, per-step table, and result block). Button enabled from the first poll onwards.
• Fast gzip + background archive: GraphSyncService.sync_to_volume now uses compresslevel=1 (≈ 6–10× faster than the previous level 9). For session builds the Volume upload runs in a daemon thread; the build task completes immediately after the snapshot step with the note "Registry backup continues in the background."
• Archive checkbox: new "Archive graph to registry" checkbox on the Build page (default on); when off, the archive step is marked skipped with a plain-English reason.
• Honest timing: archive row shows "Continues after build" with a tooltip instead of a misleading 0ms duration when the upload is backgrounded.
• Background archive task tracked as a separate registry_archive TaskManager task with its own navbar hourglass entry.

---

Task Manager & Notifications

• Task.duration_seconds() — computed live for running/pending, frozen at completed_at − started_at for terminal tasks; serialised in to_dict().
• TaskManager lifecycle log lines unified to START task <id> [<type>] — <name> / END task <id> [<type>] completed|failed|cancelled in <duration>.
• _format_duration produces compact strings: 450ms, 2.40s, 1m 23.5s, 1h 5m.
• Navbar hourglass: running rows show a live 1 s ticking elapsed time; bell toasts append (in 1m 23s).
• All task/step timestamps emitted in UTC-aware ISO format (+00:00); duration_seconds() tolerates mixed naive/aware legacy timestamps.
• Removed the broken "Open" link from terminal task completion toasts.

---

Health & Observability

/health readiness probe (replaces static {"status":"healthy"})

11 probes, each timed and wrapped in _safely_run so one failure never breaks the overall response:

Probe	What it checks
runtime	Python + OntoBricks version
filesystem.tmp	Write sentinel + shutil.disk_usage thresholds (warn < 1 GB, error < 100 MB)
filesystem.session_dir	Same check against the session directory
filesystem.log_dir	Same check against the log directory
databricks.auth	has_valid_auth + OAuth token mint in App mode
databricks.warehouse	SELECT 1 against the configured warehouse
databricks.cloudfetch	Real SQL probe with use_cloud_fetch=True; cached 5 min
registry.cfg	Resolved catalog / schema / volume
registry.volume_read	VolumeFileService.list_directory on the registry volume
registry.volume_write	Write + delete of a sentinel file via the Files API
registry.uc_schema_ddl	`CREATE OR REP...

v0.2.1

HF0.2.1

v0.2.0

OntoBricks — Release Notes V0.2.0

Release window: May, 2026
Test status: all changes shipped with the suite green (≥ 1892 passing).

---

Highlights

• New end-to-end Permissions model: app-level perms come from Databricks, domain-level perms from the Teams matrix, with a 4-step refactor (declarative guards, body data-* attrs, CSS gating) and a hardened Viewer / read-only role across every ontology and mapping widget.
• Graph Chat (formerly Digital Twin): natural-language chat with the knowledge graph, now session-aware and stable behind the deployed reverse proxy.
• New in-app Help Center accessible from the navbar, including a Starter Guide, Workflow / FAQ accordions, a Data Access / GraphDB engine map (LadybugDB as default), and a refreshed About page.
• Lakebase registry backend wired end-to-end.
• Databricks dev sandbox bundle (databricks.yml): deploys ontobricks-020 (main UI) and mcp-ontobricks (MCP); targets dev (Volume-only) and dev-lakebase (Volume + Lakebase Autoscaling postgres binding). Lakebase variables include lakebase_database_resource_segment (the db-… suffix from databricks postgres list-databases … -o json, not the Postgres datname) and lakebase_registry_schema (keep in sync with LAKEBASE_SCHEMA in app.yaml).
• Deploy & bootstrap scripts aligned with the bundle: scripts/deploy.sh uses APP_NAME=ontobricks-020; make bootstrap-perms / make bootstrap-lakebase and the underlying shell scripts default to ontobricks-020, mcp-ontobricks, and the documented Lakebase project / schema-grant flow.
• Major domain-switching robustness improvements (no more stale state, full-page loading overlay everywhere, including cross-domain bridges).
• Security: patched two GitPython advisories (GHSA-rpm5-65cw-6hj4 and GHSA-x2qx-6953-8485 / CVE-2026-42284) by pinning gitpython>=3.1.47 via uv constraint — transitive vuln only, no code-path exposure.

---

Permissions & multi-tenant access control

• App-level permissions now sourced from Databricks; domain-level permissions handled by the Teams matrix.
• First-deploy bootstrap detects and fixes the app SP self-permission chicken-and-egg situation.
• Viewer / read-only role:
  • Cascaded to all ontology and mapping widgets.
  • OWL preview no longer fails with "Unknown error" in read-only mode.
  • Belt-and-suspenders contextmenu blocker on design surfaces.
  • Gates data-source reset and all ontology / mapping imports.
• Fixed Registry → Teams sub-menu leaking to non-admin users in the top navbar.
• New three-level permission matrix tests + OWL endpoint contract tests.
• 4-step permissions refactor: declarative guards, body data-* attributes, CSS-based gating.
• Code-review fix-up: navbar role-badge inline CSS moved into permissions.css.

Graph Chat (renamed from Digital Twin)

• Natural-language chat over the knowledge graph.
• Forwards X-Forwarded-* headers on loopback to fix a deployed 302 redirect issue.
• All tools now use session-aware internal routes.
• Code-review hardening pass: clean layering, consistent error handling, deduplication, class-first refactor.

In-app Help Center

• New navbar Help icon opens a modal with comprehensive documentation.
• Refreshed About page to reflect the current product scope.
• Visual pass:
  • Palette switched from blue to red/black (solid red, no gradients).
  • OntoBricks logo used in title and welcome hero.
  • Modal height locked (no resize when switching menu items).
  • Fixed double vertical scrollbar in tall sections (Starter Guide).
  • Removed horizontal scroll on the Welcome pipeline.
  • Removed grey borders on Workflow / FAQ accordions.
• Starter Guide:
  • Added optional "Import Documents" step.
  • Rewrote the mapping step (manual or Auto-Map).
• Added Data Access engine-map documentation, then generalized it to GraphDB (LadybugDB as default engine).

Domain switching

• Fixed stale session state leaking between domain switches — DomainSession.import_from_file now fully resets ontology, assignment, design layout, domain info, metadata, and triplestore before overlay.
• Full-page "Loading {domain}…" overlay now appears for:
  • Graph switcher modal.
  • Bridge-based switches via URL parameters.
  • Cross-Domain Bridge links going through /resolve (server-side redirect).

UI / UX fixes

• Build sub-menu: fixed unreadable "Mapping" stale-indicator badge.
• Build sub-menu: stopped reporting "Loaded" for the Graph DB digital twin when nothing had actually been built.
• Sidebar: fixed the "Teams" icon misalignment.
• Cockpit: the Active Version tile now reflects the version exposed via API/MCP (the one set in Registry → Browse), not merely the latest version on disk, with a (not loaded) hint when the loaded version differs. is_active keeps its legacy is_latest meaning so the read-only body class still gates writes correctly.
• Navbar: the Domain name and version in the top navbar now refresh reliably after every domain mutation (new domain, load from registry, save / rename, version switch / create / rollback, file import). The /navbar/state sessionStorage cache (15 s TTL) was previously surviving window.location.reload(), so the navbar could display the previous domain identity for up to 15 s. Every mutation flow now invalidates the cache before navigating; in-place edits (e.g. saving Domain Information) re-fetch the navbar state immediately.
• Domain → Versions: the API/MCP “Active” control is no longer a toggle on this page — it is shown as a read-only badge; changing the active version is done only from Registry → Browse (consistent with registry-centric operations).
• Domain creation: Save to UC is now blocked when the chosen Domain Name already exists in the registry. The duplicate-name check (/domain/check-name) was already running on every keystroke of the name field, but its result was only advisory — the navbar's Save action still POSTed and the user only saw the conflict after a round-trip. The Save flow now re-runs the check synchronously and refuses with a clear notification + focuses the offending field.

Documentation

• README, docs/features.md, docs/INFO.md, docs/user-guide.md, docs/get-started.md, docs/README.md, and docs/mcp.md updated so operator-facing text matches the above: Ontology Designer, Domain Cockpit Active Version vs loaded vs latest, Registry → Browse for MCP/API active version, new-domain loading overlay, Digital Twin path refresh on committed name/version changes, duplicate-name guard, and navbar identity refresh.
• docs/deployment.md rewritten for the current DAB: dev / dev-lakebase targets, correct bundle deployment bind / bundle run resource keys and app names, scripts/deploy.sh flags (no legacy --all / --mcp-only), Lakebase variable summary, Step 5b for bootstrap-lakebase-perms.sh, full deployment checklist, MCP and troubleshooting sections, and §9 DAB reference aligned with the Makefile.
• README Lakebase paragraph: documents lakebase_database_resource_segment and the list-databases lookup pattern.

Tasks & Notifications

• Tasks panel now shows only currently running tasks; finished tasks are moved to the Notifications drawer.

Backend & Databricks Apps bundle (operator-facing)

• Lakebase registry backend wired end-to-end (runtime + optional Volume toggle unchanged).
• databricks.yml: ontobricks_dev_app / mcp_ontobricks_app resource keys; workspace app names ontobricks-020 and mcp-ontobricks; dev-lakebase target adds the Apps postgres resource whose database path ends with lakebase_database_resource_segment (db-… from the Postgres API name field).
• scripts/deploy.sh: default target dev-lakebase; APP_NAME set to ontobricks-020 so post-deploy bootstrap-app-permissions.sh and bootstrap-lakebase-perms.sh resolve the correct service principal.
• scripts/bootstrap-lakebase-perms.sh: default Lakebase project ontobricks-app, default Postgres DB ontobricks_registry (dedicated datname aligned with the bundle bind), schema ontobricks_registry; default grantees ontobricks-020 and mcp-ontobricks. Use -d databricks_postgres if the registry schema still lives in the shared default DB. Retarget with -i / -d / -s / -a when your workspace differs.
• scripts/bootstrap-app-permissions.sh: default app list ontobricks-020 mcp-ontobricks (matches the bundle).

Security

• Patched two GitPython advisories pulled in transitively via
  mlflow-skinny:
  • GHSA-rpm5-65cw-6hj4 — command injection via upload_pack /
    receive_pack kwargs on Repo.clone_from, Remote.fetch,
    Remote.pull, Remote.push (affected [3.1.30, 3.1.47)).
  • GHSA-x2qx-6953-8485 / CVE-2026-42284 — argument injection via
    multi_options shlex.split bypass in _clone() /
    Submodule.update (affected <= 3.1.44).
• Both fixed by adding gitpython>=3.1.47 to
  [tool.uv].constraint-dependencies in pyproject.toml; lockfile
  bumped gitpython 3.1.46 → 3.1.47. OntoBricks itself does not import
  git anywhere, so there is no code-path exposure — this only closes
  the SCA finding on the lockfile / installed env.

---

Upgrade notes

• Databricks Apps sandbox name: if you still point scripts or docs at ontobricks-dev, switch to ontobricks-020 (the name in databricks.yml for ontobricks_dev_app) for databricks apps get, bootstrap-app-permissions.sh, and bootstrap-lakebase-perms.sh -a …, or pass -a explicitly.
• Lakebase bundle variables: the monolithic branc...

V0.1.1

This is the first official release.