# 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. - [x] **Step 2: Verify RED** Run: ```bash 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. - [x] **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. - [x] **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. - [x] **Step 2: Verify RED** Run: ```bash 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. - [x] **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. - [x] **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. - [x] **Step 2: Verify RED** Run: ```bash 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. - [x] **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. - [x] **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. - [x] **Step 2: Regenerate contracts and update ledgers** Run: ```bash .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. - [x] **Step 3: Run targeted verification** Run only: ```bash 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`. - [x] **Step 4: Commit** Create one independently reversible WP-05 engineering commit. Do not push.