From 78a58b3a316cc3d573c0b4976bf436b4b4cec063 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Fri, 17 Apr 2026 13:12:59 -0400 Subject: [PATCH] Resolve enterprise shortname = `zb` (closes corrections-doc D4) and propagate through all UNS path examples and schema seeds. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated goal-state.md UNS hierarchy table (level 1 example with rationale: matches existing ZB.MOM.WW.* namespace prefix, short by design for a segment that appears in every equipment path, operators already say "ZB" colloquially), all worked-example paths in text + OPC UA browse forms, small-site placeholder example. Removed enterprise-shortname from the §UNS-hierarchy TBD list. Updated schemas/uns/example-warsaw-west.json `enterprise: "zb"`. Updated corrections-doc D4 entry to RESOLVED with full propagation list, and updated summary table accordingly. Production deployments use `zb` from cluster-create. The hardcoded `_default` reserved-segment rule is unchanged (still the placeholder for unused Area/Line levels at single-cluster sites). Co-Authored-By: Claude Opus 4.7 (1M context) --- goal-state.md | 12 ++++++------ handoffs/otopcua-corrections-2026-04-17.md | 16 +++++++++++++--- schemas/uns/example-warsaw-west.json | 2 +- 3 files changed, 20 insertions(+), 10 deletions(-) diff --git a/goal-state.md b/goal-state.md index 4165078..e269cc9 100644 --- a/goal-state.md +++ b/goal-state.md @@ -113,7 +113,7 @@ The plan commits to a **single canonical naming hierarchy** for addressing equip | Level | Name | Semantics | Example | |---|---|---|---| -| 1 | **Enterprise** | Single root for the whole organization. One value for the entire estate. | `ent` (working placeholder — replace with the real enterprise shortname when assigned) | +| 1 | **Enterprise** | Single root for the whole organization. One value for the entire estate. | **`zb`** — confirmed 2026-04-17 (matches the existing `ZB.MOM.WW.*` namespace prefix used in the codebase; short by design since this segment appears in every equipment path) | | 2 | **Site** | Physical location. Matches the authoritative site list in [`current-state.md`](current-state.md) → Enterprise Layout. | `south-bend`, `warsaw-west`, `warsaw-north`, `shannon`, `galway`, `tmt`, `ponce`, `berlin`, `winterthur`, `jacksonville`, … | | 3 | **Area** | A section of the site — typically a **production building** at the Warsaw campuses (which run one cluster per building), or `_default` at sites that have a single cluster covering the whole site. Always present; uniform path depth is a design goal. | `bldg-3`, `bldg-7`, `_default` | | 4 | **Line** | A production line or work cell within an area. One line = one coherent sequence of equipment working together toward a product or sub-assembly. | `line-2`, `assembly-a`, `packout-1` | @@ -127,7 +127,7 @@ Five levels is a **hard commitment**. Consumers can assume every equipment insta - **Uniform depth makes consumers simpler.** Subscribers and dbt models assume a fixed schema for the equipment identifier; variable-depth paths require special-casing. - **Adding a building later doesn't shift paths.** If a small site adds a second production building and needs an Area level, the existing equipment at that site keeps its path (now pointing at a named area instead of `_default`), and the new building gets a new area segment — no rewrites, no breaking changes for historical consumers. -- **Explicit placeholder is more discoverable than an implicit skip.** A reader looking at `ent.shannon._default.line-1.cnc-mill-03` immediately sees that Shannon has no area distinction today; a variable-depth alternative like `ent.shannon.line-1.cnc-mill-03` leaves the reader wondering whether a level is missing. +- **Explicit placeholder is more discoverable than an implicit skip.** A reader looking at `zb.shannon._default.line-1.cnc-mill-03` immediately sees that Shannon has no area distinction today; a variable-depth alternative like `zb.shannon.line-1.cnc-mill-03` leaves the reader wondering whether a level is missing. ##### Naming rules @@ -145,9 +145,9 @@ Identical conventions to the existing Redpanda topic naming — one vocabulary, | Form | Example | |---|---| -| Text (messages, docs, dbt keys) | `ent.warsaw-west.bldg-3.line-2.cnc-mill-05.spindle-speed` | -| OPC UA browse path | `ent/warsaw-west/bldg-3/line-2/cnc-mill-05/spindle-speed` | -| Same machine at a small site (area placeholder) | `ent.shannon._default.line-1.cnc-mill-03` | +| Text (messages, docs, dbt keys) | `zb.warsaw-west.bldg-3.line-2.cnc-mill-05.spindle-speed` | +| OPC UA browse path | `zb/warsaw-west/bldg-3/line-2/cnc-mill-05/spindle-speed` | +| Same machine at a small site (area placeholder) | `zb.shannon._default.line-1.cnc-mill-03` | ##### Stable equipment identity — path is navigation, UUID is lineage @@ -213,7 +213,7 @@ The hierarchy will change. Sites get added (smaller sites onboarding in Year 2). **Resolved:** storage format for the hierarchy in the `schemas` repo is **JSON Schema** (see "Where the authoritative hierarchy lives" above). -_TBD — enterprise shortname (currently `ent` placeholder); authoritative initial **UNS hierarchy snapshot** for the currently-integrated sites — requires a per-site area/line/equipment walk to capture equipment instances, their UNS path assignments, and stable UUIDs (the protocol survey has been removed since the OtOpcUa v2 design committed the driver list directly; the hierarchy walk is now a standalone Year 1 deliverable); whether the dbt `dim_equipment` historical-path tracking needs a slowly-changing-dimension type-2 pattern or a simpler current+history list; ownership of hierarchy change PRs (likely a domain SME group, not the ScadaBridge team)._ +_TBD — authoritative initial **UNS hierarchy snapshot** for the currently-integrated sites — requires a per-site area/line/equipment walk to capture equipment instances, their UNS path assignments, and stable UUIDs (the protocol survey has been removed since the OtOpcUa v2 design committed the driver list directly; the hierarchy walk is now a standalone Year 1 deliverable); whether the dbt `dim_equipment` historical-path tracking needs a slowly-changing-dimension type-2 pattern or a simpler current+history list; ownership of hierarchy change PRs (likely a domain SME group, not the ScadaBridge team)._ #### How this differs from a classic MQTT-based UNS diff --git a/handoffs/otopcua-corrections-2026-04-17.md b/handoffs/otopcua-corrections-2026-04-17.md index 5160845..1fe1fd7 100644 --- a/handoffs/otopcua-corrections-2026-04-17.md +++ b/handoffs/otopcua-corrections-2026-04-17.md @@ -321,7 +321,17 @@ This proposal also addresses B1 (the missing ACL constraint) — they're the sam **Plan TBD:** "Enterprise shortname for UNS hierarchy root (currently `ent` placeholder)" (handoff §"Open Questions / TBDs"). -**Status:** **Not resolved.** OtOpcUa work cannot determine this — it's an organizational naming choice. Flagging because the v2 design currently uses `ent` per the handoff's placeholder. Suggest the schemas repo team or enterprise-naming authority resolve before any production deployment, since changing the Enterprise segment after equipment is published would require a generation-wide path rewrite (UUIDs preserved but every consumer's path-based query needs to learn the new prefix). +**Status: RESOLVED (2026-04-17) — `zb`.** Confirmed as the org's enterprise shortname matching the existing `ZB.MOM.WW.*` namespace prefix used throughout the codebase. Short by design (level-1 segment appears in every equipment path so brevity matters); operators already say "ZB" colloquially; no introduction of a new identifier vocabulary. + +Propagated through: +- `goal-state.md` UNS hierarchy table (level 1 example), worked-example paths (text + OPC UA browse forms), small-site placeholder example +- `lmxopcua/docs/v2/plan.md` UNS section browse-path example + Namespace schema sketch NamespaceUri example +- `lmxopcua/docs/v2/admin-ui.md` cluster-create workflow form (Enterprise field default-prefilled `zb`) +- `lmxopcua/docs/v2/config-db-schema.md` ServerCluster.Enterprise column comment +- `3yearplan/schemas/uns/example-warsaw-west.json` `enterprise: "zb"` +- This corrections doc D4 entry + +Production deployments use `zb` from cluster-create. The hardcoded `_default` reserved-segment rule is unchanged (still the placeholder for unused Area / Line levels at single-cluster sites). **Recommendation:** resolve before tier 1 (ScadaBridge) cutover at the first site. @@ -426,7 +436,7 @@ Neither of these affects the handoff or this corrections doc directly. | A. Inaccuracies | 2 | Both wording/framing issues; no architectural conflict | | B. Missing constraints | 3 | ACLs, schemas-repo dependencies, certificate trust pre-cutover | | C. Architectural decisions to revisit | 6 | Driver list pre-survey, stability tiers, Polly resilience, multi-identifier model (now refined per addendum), missing cutover plan, per-building cluster interactions | -| D. Resolved TBDs | 4 | Pilot class, schemas repo format, ACL location, enterprise shortname (unresolved) | +| D. Resolved TBDs | 4 | Pilot class, schemas repo format, ACL location, **D4 enterprise shortname = `zb` RESOLVED 2026-04-17** | | E. New TBDs | 4 | UUID-gen authority, Aveva validation, multi-cluster site addressing, cluster-endpoint mental model | | **Addendum hardening fixes** | **4** | EquipmentId system-generated; ExternalIdReservation table; same-cluster namespace binding; Namespace generation-versioned | @@ -455,7 +465,7 @@ After the plan team integrated the original 19 corrections + 4 hardening fixes, | A. Inaccuracies | 2 | Both wording/framing issues; no architectural conflict | | B. Missing constraints | 3 | B1 ACLs **CLOSED** (#129–132); B2 schemas-repo **PARTIALLY CLOSED** (seed contributed; owner-team + dedicated-repo TBD); B3 cert-distribution remains operational concern | | C. Architectural decisions to revisit | 6 | C1 driver list **CLOSED** (#128); C5 cutover scope **CLOSED** (#136 — out of v2 scope); others still flagged | -| D. Resolved TBDs | 4 | Pilot class, schemas repo format, ACL location, enterprise shortname (unresolved) | +| D. Resolved TBDs | 4 | Pilot class, schemas repo format, ACL location, **D4 enterprise shortname = `zb` RESOLVED 2026-04-17** | | E. New TBDs | 4 | UUID-gen authority, Aveva validation, multi-cluster site addressing, cluster-endpoint mental model | | **Addendum hardening fixes** | **4** | EquipmentId system-generated; ExternalIdReservation table; same-cluster namespace binding; Namespace generation-versioned | | **Round 3 additions** | **4** | ACL design (#129–132); dev-environment two-tier (#133–137); cutover scope removal (#136); `_base` template + OPC 40010 columns (#138–139) | diff --git a/schemas/uns/example-warsaw-west.json b/schemas/uns/example-warsaw-west.json index 549b284..a7edd40 100644 --- a/schemas/uns/example-warsaw-west.json +++ b/schemas/uns/example-warsaw-west.json @@ -1,6 +1,6 @@ { "$schema": "../format/uns-subtree.schema.json", - "enterprise": "ent", + "enterprise": "zb", "site": "warsaw-west", "displayName": "Warsaw West (example)", "areas": [