DataOps-platform/docs/superpowers/plans/2026-07-29-wp05-device-semantics-ontology.md

WP-05 Device Semantics and Ontology Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build and govern a publishable device semantic model plus versioned fault, cause, and action codes, while reusing the existing ontology workbench, responsibility matrix, versioning, review, publication, rollback, Outbox, and Neo4j projection chain.

Architecture: PostgreSQL remains authoritative for the device ontology, code identities, immutable code versions, review records, and responsibility assignments. The canonical device graph is a bounded profile layered on the existing generic GraphDocument; a device ontology publication must pass both generic graph validation and device-profile coverage, and the actor must be the accountable device asset manager. Neo4j remains a publication projection rather than the write source. AI- or rule-generated code proposals may enter the same reviewed code lifecycle only with confidence and evidence; WP-05 does not implement cross-source entity merging.

Tech Stack: Flask, SQLAlchemy, PostgreSQL JSONB, Alembic, Vue 2, Vuetify, pytest.

Global Constraints

• Reuse the existing ontology list, structured workbench, ETag draft save, validation, version, diff, publication, rollback, dynamic suggestion review, JSON/OWL exchange, Outbox, and Neo4j projection.
• The canonical device profile contains device, component, measurement point, alarm, maintenance record, location, organization, person, fault, cause, and action concepts.
• The device profile maps the stable WP-04 platform UID and source-code identity into the semantic graph; entity matching or merging across sources remains WP-06.
• Governed code types are fault, cause, and action.
• A code identity is unique by (ontology_uid, code_type, canonical_code).
• Code content is immutable by version. Revisions append a version; they never rewrite an earlier snapshot.
• Code lifecycle is draft -> in_review -> published|rejected; a rejected code may be revised and resubmitted.
• Only the accountable asset_manager for the device_ontology responsibility scope may publish the device ontology or approve/reject device codes.
• Rule/AI proposals must contain evidence UIDs; an AI proposal must also contain a confidence in [0, 1]. No model-generated proposal is auto-published.
• Credentials, connection strings, tokens, raw operating measurements, and personal contact fields are rejected from semantic code payloads and never returned.
• Viewer reads; editor creates, revises, and submits; admin has the review permission but still must pass the accountable asset-manager runtime gate.
• Real enterprise device, fault, cause, and action codes remain an external acceptance gate.
• Validation follows the user-approved rule: run only WP-05 domain, persistence, API, permission, frontend, migration, contract, and local browser checks; do not run the full repository regression.
• Continue on codex/dataops-phase1-equipment-governance; do not push or deploy remotely.

---

Task 1: Canonical Device Ontology Profile and Publication Gate

Files:

• Create: app/core/data_research/device_semantics.py
• Modify: app/core/data_research/errors.py
• Modify: app/core/data_research/ontology/publication.py
• Modify: app/core/data_research/ontology/repository.py
• Test: tests/data_research/test_device_semantics.py
• Modify: tests/data_research/test_ontology_publication.py

Interfaces:

• Produces: build_device_graph(owner_domain_uid), assess_device_graph(graph), DeviceSemanticProfile, DeviceOntologyPublicationAuthorizer, and OntologyRepository.find_by_code(code).

• Extends: OntologyPublicationService(..., publication_authorizer=...).

• [x] Step 1: Write failing profile and publication tests

Cover the complete concept/relation/property/mapping blueprint, deterministic output, missing-profile detection, idempotent bootstrap, generic ontology publication remaining unchanged, device ontology publication rejected when incomplete, and publication rejected when the actor is not the accountable asset manager.

• Step 2: Verify RED

Run:

PYTHONPATH=. .venv/bin/pytest -q \
  tests/data_research/test_device_semantics.py \
  tests/data_research/test_ontology_publication.py

Expected: failure because the device semantic profile and publication authorizer do not exist.

• Step 3: Implement minimal profile and gate

Build a deterministic graph with stable semantic UIDs, generic-validator-compatible mappings, device-specific coverage results, and an optional publication callback. Keep the default callback permissive so non-device ontologies and existing unit tests retain their behavior.

• Step 4: Verify GREEN

Run the Task 1 test command and expect all tests to pass.

Task 2: Versioned Fault, Cause, and Action Codes

Files:

• Modify: app/core/data_research/device_semantics.py
• Create: app/core/data_research/device_semantic_repository.py
• Modify: app/models/data_research.py
• Create: migrations/versions/20260729_300_device_semantics.py
• Modify: tests/test_database_migrations.py
• Create: tests/integration/test_device_semantics_postgres.py

Interfaces:

• Produces: DeviceSemanticCodeService, SqlAlchemyDeviceSemanticCodeRepository, tables device_semantic_codes, device_semantic_code_versions, and device_semantic_code_reviews.

• Code methods: create, revise, submit, review, search, get, versions, and reviews.

• [x] Step 1: Write failing lifecycle and persistence tests

Cover unique canonical identity, three code types, immutable revisions, optimistic version checks, state transitions, evidence-required rule/AI proposals, secret rejection, accountable-manager approval, immutable review records, filters, and real PostgreSQL cleanup.

• Step 2: Verify RED

Run:

PYTHONPATH=. .venv/bin/pytest -q \
  tests/data_research/test_device_semantics.py \
  tests/test_database_migrations.py::test_device_semantics_migration_is_versioned_reviewed_and_traceable \
  tests/integration/test_device_semantics_postgres.py

Expected: failure because the schema and SQL repository do not exist.

• Step 3: Implement migration, models, repository, and lifecycle

Use UUIDv7 identities, unique ontology/type/code and code/version constraints, JSONB snapshots, immutable review rows, row locks for revise/submit/review, timezone-aware timestamps, and a data-preserving downgrade.

• Step 4: Upgrade local PostgreSQL and verify GREEN

Run Alembic to head against the isolated local database, then rerun the Task 2 tests with TEST_DATABASE_URL configured.

Task 3: Permission-Controlled Device Semantic API

Files:

• Modify: app/api/data_development/routes.py
• Modify: app/core/system/permissions.py
• Create: tests/data_research/test_device_semantic_api.py
• Modify: tests/test_permission_matrix.py

Interfaces:

• Produces:

  • POST /api/development/v1/device-semantics/bootstrap
  • GET /api/development/v1/device-semantics/profile
  • GET|POST /api/development/v1/device-semantics/codes
  • POST /api/development/v1/device-semantics/codes/{code_uid}/revisions
  • POST /api/development/v1/device-semantics/codes/{code_uid}/submit
  • POST /api/development/v1/device-semantics/codes/{code_uid}/review
  • GET /api/development/v1/device-semantics/codes/{code_uid}/versions
  • GET /api/development/v1/device-semantics/codes/{code_uid}/reviews

• [x] Step 1: Write failing API and permission tests

Cover viewer read, viewer write denial, editor create/revise/submit, editor review denial, admin review permission plus accountable-manager domain denial, bounded pagination, profile serialization, immutable version/review responses, and safe error envelopes.

• Step 2: Verify RED

Run:

PYTHONPATH=. .venv/bin/pytest -q \
  tests/data_research/test_device_semantic_api.py \
  tests/test_permission_matrix.py::test_data_development_paths_have_specific_write_policies \
  tests/test_permission_matrix.py::test_fixed_role_permission_matrix_is_monotonic

Expected: failure because the routes and dedicated permissions do not exist.

• Step 3: Implement API and authorization

Add device-semantics:edit to editor/admin and device-semantics:review to admin. Keep reads on governance:read; enforce the accountable-manager check inside the domain boundary, not only in the menu or permission matrix.

• Step 4: Verify GREEN

Run the Task 3 test command and expect all tests to pass.

Task 4: Device Semantic Governance UI and Delivery Evidence

Files:

• Modify: frontend/src/api/dataDevelopment.js
• Modify: frontend/src/router/routes.js
• Modify: frontend/src/views/dataGovernance/ontology/index.vue
• Create: frontend/src/views/dataGovernance/ontology/deviceSemantics.vue
• Modify: docs/architecture/OPENAPI.yaml
• Modify: docs/architecture/DATA_MODEL.md
• Modify: docs/FUNCTION_MODULE_CENSUS_20260726.md
• Modify: docs/DATAOPS_PHASE1_3_MONTH_WORK_PLAN_20260729.md
• Modify: deployment/app/ only for the WP-05 backend subset.

Interfaces:

• Produces: /data-governance/ontology/device-semantics with semantic coverage, accountable-manager status, ontology workbench deep link, code filters, create/revise/submit/review actions, source mappings, evidence, version history, and review history.

• [x] Step 1: Implement the device semantic page

Add the ontology-center entry and a responsive governance page. The page must expose lifecycle state and audit history, hide mutation actions without permissions, and explain that cross-source matching belongs to WP-06.

• Step 2: Regenerate contracts and update ledgers

Run:

.venv/bin/python scripts/generate_openapi.py --output docs/architecture/OPENAPI.yaml

Record generic ontology capability as merged/current, WP-05 engineering separately from enterprise code acceptance, and SEM-21 as partial until a governed AI provider and enterprise evidence set are accepted.

• Step 3: Run targeted verification

Run only:

TEST_DATABASE_URL=postgresql+psycopg2://dataops:dataops-test-password@127.0.0.1:15432/dataops \
PYTHONPATH=. .venv/bin/pytest -q \
  tests/data_research/test_device_semantics.py \
  tests/integration/test_device_semantics_postgres.py \
  tests/data_research/test_ontology_publication.py \
  tests/data_research/test_device_semantic_api.py \
  tests/test_permission_matrix.py \
  tests/test_database_migrations.py::test_device_semantics_migration_is_versioned_reviewed_and_traceable \
  tests/test_architecture_artifacts.py

cd frontend
./node_modules/.bin/eslint \
  src/api/dataDevelopment.js \
  src/router/routes.js \
  src/views/dataGovernance/ontology/index.vue \
  src/views/dataGovernance/ontology/deviceSemantics.vue

Rebuild only affected local backend/frontend services. In the browser, bootstrap the device ontology, verify profile coverage, configure or confirm the accountable asset manager, create and submit a fault code, approve it, inspect its immutable version/review history, open the generic workbench, and confirm zero console errors. Run git diff --check.

• Step 4: Commit

Create one independently reversible WP-05 engineering commit. Do not push.