Jira progress: loading…

PP-DESCR

Pergamum Pulse

Pergamum Pulse is the natural home for the Global Canonical Layer, provided we separate two responsibilities cleanly:

Pergamum Pulse stores, structures, versions, classifies and explains canonical origin knowledge.
The runtime registries consume normalized machine-readable projections of that knowledge.

That division is important. Pergamum Pulse should not become the hot-path runtime database for millions of device observations, but it should become the authoritative knowledge fabric describing what devices, documents, APIs and other origins are capable of producing.

The architectural role

For a water meter, Pergamum Pulse could hold:

manufacturer manuals;
technical data sheets;
communication-protocol specifications;
register maps;
calibration guidance;
certifications;
firmware notes;
installation instructions;
known limitations;
parser documentation;
supported measurements;
framework relevance;
inherited origin classes;
links to executable connectors and MICE components.

The .mdx document becomes more than documentation. It becomes a canonical knowledge artifact with machine-actionable front matter.

---
id: origin-model-kamstrup-flowiq-2200
canonical_name: Kamstrup flowIQ 2200
artifact_type: origin_model_profile
origin_class_id: origin.water_meter.smart.ultrasonic
manufacturer_id: manufacturer.kamstrup
product_family_id: family.kamstrup.flowiq
model_id: model.kamstrup.flowiq2200
version: 1.2.0
status: approved

inherits_from:
  - origin.physical_device
  - origin.meter
  - origin.water_meter
  - origin.water_meter.smart
  - origin.water_meter.ultrasonic

advertises_capabilities:
  - capability.measure.water.cumulative_volume
  - capability.measure.water.flow_rate
  - capability.detect.water.leakage
  - capability.measure.water.temperature
  - capability.telemetry.remote_reading

produces_signal_types:
  - uso_type:water.iot.measurement.volume.cumulative@v1
  - uso_type:water.iot.measurement.flow.instantaneous@v1
  - uso_type:water.iot.event.leakage.detected@v1

protocols:
  - wmbus
  - lorawan

supported_units:
  - m3
  - l
  - m3_per_h

framework_relevance:
  - framework:GRI.303
  - framework:ESRS.E3
  - framework:ISO.14046

source_artifacts:
  - artifact:manual.flowiq2200.en.v3
  - artifact:datasheet.flowiq2200.2026
  - artifact:certificate.mid.flowiq2200

evidence_status: manufacturer_supported
confidence: verified
owners:
  - pergamum-pulse-team
---

The prose beneath the metadata can explain installation, interpretation, limitations and implementation guidance. The front matter supplies the graph and runtime systems.

Pergamum Pulse as the canonical authoring and knowledge layer

I would position the architecture like this:

Manuals / data sheets / certificates / API specifications
                         │
                         ▼
                 Pergamum Pulse
         canonical MDX knowledge artifacts
                         │
          validation + inheritance resolution
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
 Origin Registry   Capability Graph   Artifact Registry
          │              │              │
          └──────────────┼──────────────┘
                         ▼
             Runtime origin profiles
                         │
                         ▼
      Connector assembly / signal routing / FOGE /
      MICE / framework mapping / assurance

This gives us one human-readable source and several optimized machine-readable projections.

What Pergamum Pulse should own

Pergamum Pulse should own the canonical definition and governance of:

Knowledge object	Example
Origin classes	`origin.water_meter.smart`
Manufacturers	`manufacturer.kamstrup`
Product families	`family.kamstrup.flowiq`
Device models	`model.kamstrup.flowiq2200`
Capability definitions	`capability.measure.water.flow_rate`
Capability bundles	`bundle.water_meter.core`
Inheritance relationships	Smart water meter inherits water meter
Source artifacts	Manual, data sheet, certificate
Framework relevance	GRI 303, ESRS E3
Connector specifications	LoRaWAN decoder, Modbus map
Known constraints	Accuracy range, installation limitations
Evidence status	Manufacturer-declared, independently verified
Change history	Firmware or documentation revisions

What Pergamum Pulse should not own directly

It should not be the primary store for:

individual device installations;
tenant credentials;
API secrets;
live observations;
device telemetry;
customer-specific calibration records;
facility-specific configuration;
high-frequency runtime state.

Those belong in operational registries and tenant-scoped data stores.

The distinction is:

Pergamum Pulse:
“What is a Kamstrup flowIQ 2200?”

Tenant Origin Registry:
“Which flowIQ 2200 is installed at Facility A?”

Observation Store:
“What did that device report at 10:15?”

The inheritance ladder

Pergamum Pulse is particularly appropriate because .mdx artifacts can represent every level of the classification tree.

origin.physical
└── origin.physical.device
    └── origin.meter
        └── origin.fluid_meter
            └── origin.water_meter
                ├── origin.water_meter.mechanical
                ├── origin.water_meter.ultrasonic
                └── origin.water_meter.smart
                    └── family.kamstrup.flowiq
                        └── model.kamstrup.flowiq2200

Each node contributes metadata.

A model profile should not repeat everything inherited from water_meter. Instead, the build pipeline resolves the effective profile:

{
  "model_id": "model.kamstrup.flowiq2200",
  "effective_capabilities": [
    "capability.measure.water.volume",
    "capability.measure.water.flow_rate",
    "capability.detect.water.leakage",
    "capability.telemetry.remote_reading"
  ],
  "effective_framework_relevance": [
    "framework:GRI.303",
    "framework:ESRS.E3"
  ],
  "metadata_lineage": [
    {
      "property": "measured_medium",
      "value": "water",
      "inherited_from": "origin.water_meter"
    },
    {
      "property": "measurement_method",
      "value": "ultrasonic",
      "inherited_from": "origin.water_meter.ultrasonic"
    },
    {
      "property": "protocol",
      "value": "wireless_mbus",
      "declared_by": "model.kamstrup.flowiq2200"
    }
  ]
}

That lineage is important. The system must always explain not only the effective metadata, but which ancestor supplied it.

Capability inheritance needs explicit semantics

We should not make all metadata inheritance automatic. Every property should define its inheritance behavior.

Recommended modes:

Mode	Meaning
`inherit`	Child receives parent value unless overridden
`append`	Child adds values to inherited collection
`replace`	Child replaces the inherited value
`restrict`	Child may narrow but not broaden the parent capability
`prohibit_override`	Canonical property cannot be changed downstream
`conditional`	Inherited only when a condition is satisfied
`derived`	Computed from other metadata
`tenant_configurable`	Canonical default may be changed per installation

For example:

property: measured_medium
inheritance_mode: prohibit_override
value: water

A water-meter model must not redefine itself as measuring gas.

But:

property: sampling_interval
inheritance_mode: tenant_configurable
default: PT15M

The installation may use a different interval.

Documents should also be graph nodes

The manuals and data sheets should not just be attachments on an origin profile. They should be registered artifacts with their own provenance.

id: artifact:datasheet.kamstrup.flowiq2200.2026.en
artifact_type: manufacturer_datasheet
publisher: Kamstrup
language: en
issued_at: 2026-02-12
content_hash: sha256:...
applies_to:
  - model.kamstrup.flowiq2200
supports_claims:
  - claim:flowiq2200.measurement_accuracy
  - claim:flowiq2200.leak_detection
supersedes:
  - artifact:datasheet.kamstrup.flowiq2200.2024.en
extraction_status: reviewed

Then a capability can point to the exact evidence supporting it:

Capability
   └── asserted by model profile
          └── supported by data sheet
                 └── extracted from page/section

That is assurance-grade canonical knowledge.

Shared knowledge without leaking tenant data

The India example is exactly why the architecture needs three layers.

Global Canonical Knowledge
        ↓
Regional / community enrichment
        ↓
Tenant installation instance

Global layer

Reusable across every customer:

device class;
manufacturer;
model;
capabilities;
manuals;
protocols;
standard mappings;
generic validation rules.

Regional or community layer

Potentially reusable but governed:

region-specific certifications;
local unit conventions;
climate-related operational guidance;
firmware observations;
local regulatory applicability;
independently verified implementation notes.

Tenant layer

Private:

serial number;
facility;
credentials;
network address;
calibration history;
maintenance records;
actual observations.

Promoting tenant discoveries into the shared layer should require a controlled workflow:

Tenant discovery
→ anonymization
→ evidence attachment
→ conflict analysis
→ technical review
→ canonical approval
→ Pergamum Pulse version update
→ regenerated runtime projections

No tenant-specific operational information should move upward automatically.

Pergamum Pulse also becomes the training ground for system assembly

Once these .mdx artifacts are richly structured, ZARA or a solution-composition agent can ask:

Which origins can provide validated water-volume measurements suitable for GRI 303?

Pergamum Pulse provides the canonical candidates. The runtime registry determines which of those devices are actually installed. The composition layer then assembles:

Installed origin
→ compatible connector
→ parser
→ normalizer
→ USO signal
→ aggregation engine
→ disclosure mapping
→ FOGE gap fields
→ report output

This is where the documentation architecture directly produces executable platform capabilities.

Important naming distinction

I would preserve Pergamum Pulse as the overarching knowledge and artifact system, and define the Global Canonical Layer as a governed domain within it.

For example:

Pergamum Pulse
├── Canonical Origin Knowledge
├── Capability Knowledge
├── Framework Knowledge
├── Component Knowledge
├── Methodology Knowledge
├── Evidence Artifact Knowledge
└── Implementation Knowledge

The Origin Knowledge Graph should therefore be a projection generated from Pergamum Pulse, rather than a separate source of truth.

Pergamum Pulse MDX
        │
        ├── generates Origin Registry
        ├── generates Capability Graph
        ├── generates documentation
        ├── generates validation schemas
        ├── generates connector manifests
        └── feeds graph explorer

My conclusion

Pergamum Pulse is not merely suitable for the Global Canonical Layer—it is probably the architectural element that makes the concept practical.

It gives ZAYAZ:

Git-versioned canonical knowledge;
human-readable technical documentation;
machine-actionable metadata;
hierarchical inheritance;
evidence-linked capabilities;
reusable device and document intelligence;
approval and change governance;
generated runtime registries;
component and module lineage;
a compounding global knowledge asset.

The key guardrail is that Pergamum Pulse is the canonical knowledge plane, while dedicated registries and services remain the runtime execution plane. That separation gives us both deep explainability and production-scale performance.

GitHub Repo Request for Change (RFC)

The architectural role​