Pergamum Pulse Knowledge Object and Relationship Specification
Version 0.1 — Normative Object and Graph Contract
This specification defines the canonical object and relationship model for Pergamum Pulse.
It operationalises the object architecture established by PP-KDMF and the metadata envelope established by PP-KDMS.
The governing principle is:
Pergamum Pulse knowledge SHALL be represented through stable, typed, versioned and provenance-complete objects and relationships. No object or relationship SHALL gain authority merely because it exists in the graph.
1. Scope
This specification applies to every first-class Pergamum Pulse object and relationship, including sources, captures, rights, documents, sections, source fragments, assertions, entities, bundles, citations, mappings, extraction targets, Change Candidates, Change Decisions, Projection Manifests, historical records, reviews, Findings, incidents and conformance receipts.
2. Normative Language
The terms SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY and MAY NOT are normative.
Where this specification conflicts with PP-KDMF, the framework prevails.
3. Object Model Overview
| Object | Prefix | Purpose |
|---|---|---|
| Source Series | PP-SRS- | Groups versions or editions of a source |
| Source Object | PP-SRC- | Identifies the original source |
| Source Capture | PP-CAP- | Identifies a specific acquisition event |
| Rights Record | PP-RGT- | Governs copyright, licence and use permissions |
| Knowledge Document | PP-KD- | Canonical MDX knowledge representation |
| Knowledge Section | PP-KS- | Addressable document section |
| Source Fragment | PP-SF- | Exact supporting fragment |
| Knowledge Assertion | PP-KA- | Structured statement derived from evidence |
| Knowledge Entity | PP-KE- | Real, legal, technical or conceptual entity |
| Knowledge Bundle | PP-KB- | Purpose-bound grouping of objects |
| Citation Object | PP-CIT- | Rights-aware citation |
| Mapping Object | PP-MAP- | Semantic or structural mapping |
| Extraction Target | PP-XT- | Candidate target for projection |
| Change Candidate | PP-CC- | Proposed governed change |
| Change Decision | PP-CD- | Authorised treatment of a Candidate |
| Projection Manifest | PP-PRJ- | Generated artefact lineage |
| Historical Record | PP-HR- | Preserved prior state |
| Review Record | PP-RVW- | Review, approval or rejection record |
| Finding | PP-FND- | Identified non-conformance or defect |
| Incident | PP-INC- | Operational, rights, security or integrity incident |
| Conformance Receipt | PP-RCPT- | Machine-verifiable conformance result |
4. Universal Object Contract
Every first-class object SHALL implement the universal object contract.
object:
id: PP-KE-000001
semantic_id: pp.entity.device.water-meter.example
object_type: knowledge_entity
canonical_name: Example Water Meter
version: 1.0.0
lifecycle_status: active
authority: {}
temporal: {}
scope: {}
relationships: {}
provenance: {}
Every object SHALL include id, object_type, version, lifecycle_status, temporal, scope and provenance.
Every reusable object SHOULD include semantic_id, canonical_name, aliases, authority, relationships, classification and owner.
5. Identifier Architecture
Identifiers SHALL be globally unique within Pergamum Pulse, immutable, never reused, prefix-valid and independent of file path.
The recommended format is:
PP-<CLASS>-<SEQUENCE>
External identifiers SHALL be represented separately.
external_identifiers:
- scheme: doi
value: 10.0000/example
- scheme: celex
value: 32023R0000
Retired identifiers SHALL remain permanently reserved.
6. Object Versioning
Every object SHALL preserve version independently from related objects.
Version classes MAY include source version, capture sequence, document version, assertion-set version, entity version, mapping version, relationship version, projection version and activation version.
Published object versions SHALL be immutable.
A material change in meaning, applicability, rights, authority or effective behaviour SHALL create a new version.
7. Universal Lifecycle Model
PP-KORS is the normative authority for the universal lifecycle of first-class Pergamum Pulse objects.
Every first-class Pergamum Pulse object SHALL expose a lifecycle_status governed by this specification.
The universal lifecycle vocabulary is:
- proposed;
- draft;
- admitted;
- active;
- active with conditions;
- review required;
- disputed;
- deprecated;
- superseded;
- suspended;
- withdrawn;
- retired;
- historical only;
- rejected;
- quarantined;
- deleted with retained tombstone.
Specialised specifications SHALL define lifecycle profiles by selecting permitted states and transitions from this universal vocabulary.
A specialised specification SHALL NOT create an additional universal lifecycle state without amendment of this specification and registration of that state in the applicable lifecycle registry.
Domain-specific workflow, extraction, review, conflict, adoption, projection and activation states SHALL remain separate state dimensions and SHALL NOT be represented as additional universal lifecycle states.
Every transition SHALL identify source state, target state, reason, authority, effective time, transaction time, conditions and provenance.
8. Temporal Model
Every material object and relationship SHALL preserve bitemporal validity.
temporal:
valid_from: 2026-01-01T00:00:00Z
valid_to: null
recorded_at: 2026-01-02T10:15:00Z
superseded_at: null
Unknown time SHALL be represented explicitly.
Overlapping incompatible validity SHALL create a conflict object or Finding.
9. Scope and Isolation Contract
scope:
knowledge_scope: global_canonical
jurisdictions:
- eu
tenant_scope:
mode: none
white_label_scope:
mode: global
modules:
- pergamum-pulse
components:
- knowledge-entity-registry
Tenant-scoped objects SHALL NOT be visible outside authorised tenant boundaries.
Promotion to broader scope SHALL require rights review, confidentiality review, semantic review, conflict review, approval and provenance.
10. Authority Contract
Every material object SHALL represent authority dimensions separately.
authority:
source_authority:
class: standards_body
legal_authority:
class: non_binding
evidentiary_authority:
class: authoritative_for_source_content
zayaz_governance_authority:
class: governed_reference
runtime_authority:
class: none
Authority SHALL NOT transfer automatically between dimensions.
11. Provenance Contract
Every object SHALL preserve creator, creation time, source lineage, transformation lineage where applicable, reviewer where required and decision lineage where applicable.
Materially incomplete provenance SHALL prevent automation eligibility.
12. Object Class Specifications
12.1. Source Series
A Source Series SHALL identify:
- series identity;
- title;
- issuing authority;
- version sequence;
- current version;
- prior versions;
- lifecycle;
- provenance.
12.2. Source Object
A Source Object SHALL identify:
- title;
- publisher;
- issuing authority;
- source type;
- version or edition;
- official identifier;
- publication time;
- effective time;
- official location;
- authority;
- rights relationship;
- provenance.
12.3. Source Capture
A Source Capture SHALL identify:
- Source Object;
- acquisition event;
- media type;
- filename;
- digest;
- size;
- signature state;
- storage location;
- chain of custody;
- provenance.
12.4. Rights Record
A Rights Record SHALL identify:
- rights holder;
- licence;
- agreement;
- permission basis;
- use permissions;
- attribution;
- validity;
- evidence;
- provenance.
12.5. Knowledge Document
A Knowledge Document SHALL identify:
- source relationships;
- capture relationships;
- document type;
- language;
- representation type;
- sections;
- assertions;
- entities described;
- rights;
- transformation;
- provenance.
12.6. Knowledge Section
A Knowledge Section SHALL identify:
- parent document;
- heading;
- source locator;
- knowledge class;
- rights override;
- review status;
- provenance.
12.7. Source Fragment
A Source Fragment SHALL identify:
- source;
- capture;
- locator;
- content type;
- digest where applicable;
- rights;
- provenance.
12.8. Knowledge Assertion
A Knowledge Assertion SHALL identify:
- subject;
- predicate;
- object;
- assertion class;
- source fragments;
- authority;
- applicability;
- confidence;
- review;
- temporal validity;
- provenance.
12.9. Knowledge Entity
A Knowledge Entity SHALL identify:
- entity type;
- semantic identity;
- canonical name;
- aliases;
- properties;
- relationships;
- lifecycle;
- provenance.
12.10. Knowledge Bundle
A Knowledge Bundle SHALL identify:
- purpose;
- member objects;
- member roles;
- scope;
- lifecycle;
- provenance.
A Bundle SHALL NOT merge member authority or rights.
12.11. Citation Object
A Citation Object SHALL identify:
- cited source;
- locator;
- quotation or paraphrase state;
- attribution;
- rights;
- publication permission;
- provenance.
12.12. Mapping Object
A Mapping Object SHALL identify:
- source object;
- target object;
- mapping type;
- rationale;
- authority;
- confidence;
- scope;
- validity;
- reviewer;
- provenance.
12.13. Extraction Target
An Extraction Target SHALL identify:
- target class;
- target Registry or schema;
- candidate payload;
- constraints;
- authority required;
- provenance.
12.14. Change Candidate
A Change Candidate SHALL identify:
- source knowledge;
- affected objects;
- proposed operation;
- proposed value;
- impact;
- rights status;
- review;
- provenance.
12.15. Change Decision
A Change Decision SHALL identify:
- Candidate;
- decision;
- authority;
- conditions;
- scope;
- effective time;
- signatures;
- provenance.
12.16. Projection Manifest
A Projection Manifest SHALL identify:
- source objects;
- approved Decisions;
- compiler;
- generated outputs;
- digests;
- validation;
- activation state;
- provenance.
12.17. Historical Record
A Historical Record SHALL identify:
- historical object;
- historical version;
- valid time;
- transaction time;
- archive state;
- retrieval method;
- provenance.
13. Relationship Model
Every material relationship SHALL be a first-class object or first-class graph edge with stable identity.
relationship:
id: PP-MAP-000001
relationship_type: supports_protocol
source_object: PP-KE-000001
target_object: PP-KE-000002
direction: directed
cardinality: many_to_many
authority: {}
temporal: {}
scope: {}
provenance: {}
Every relationship SHALL include relationship type, source object, target object, direction, scope, temporal validity and provenance.
It SHOULD include authority, confidence, cardinality, rationale, review status and lifecycle.
14. Relationship Type Registry
All relationship types SHALL be Registry-governed.
The Registry SHALL preserve:
- relationship type identifier;
- canonical name;
- definition;
- source object classes;
- target object classes;
- direction;
- inverse;
- cardinality;
- transitivity;
- symmetry;
- authority rules;
- lifecycle;
- provenance.
15. Core Relationship Classes
15.1. Identity Relationships
same_as;alias_of;version_of;instance_of;type_of;specialisation_of;generalisation_of.
15.2. Structural Relationships
contains;part_of;composed_of;member_of;depends_on;uses;owned_by_module;implemented_by_component.
15.3. Source and Evidence Relationships
derived_from;captured_from;represented_by;supported_by;evidenced_by;cites;quotes;paraphrases;transformed_from.
15.4. Semantic Relationships
defines;describes;means;classifies;applies_to;requires;permits;prohibits;recommends.
15.5. Technical Relationships
supports;implements;compatible_with;generates;consumes;maps_to;converts_to;validated_by.
15.6. Governance Relationships
governed_by;approved_by;reviewed_by;certified_by;accredited_by;authorised_by;activated_by.
15.7. Temporal Relationships
supersedes;superseded_by;replaces;replaced_by;valid_during;expired_after;withdrawn_by.
15.8. Conflict Relationships
conflicts_with;disputes;contradicts;overrides;restricted_by.
15.9. Change Relationships
proposes_change_to;approved_for;generates_projection;activates;rolls_back;impacts.
16. Relationship Semantics
Relationships SHALL be non-transitive unless the Relationship Type Registry explicitly defines transitivity.
A relationship SHALL be symmetric only where defined.
Inverse relationships SHOULD be defined where safe.
Examples:
contains ↔ part_of
supersedes ↔ superseded_by
A relationship SHALL preserve the authority supporting the relationship itself.
Derived relationships SHALL preserve confidence.
A relationship MAY apply only to a jurisdiction, tenant, white-label deployment, version, time period, Module, Component or Runtime profile.
17. Assertion-to-Relationship Conversion
A Knowledge Assertion MAY generate a candidate relationship.
Assertion:
Device model supports W-MBus.
Candidate relationship:
PP-KE-device --supports_protocol--> PP-KE-wmbus
The relationship SHALL NOT become approved merely because the assertion exists.
The conversion SHALL preserve source assertion, source fragments, transformation, reviewer, Change Decision where required and provenance.
18. Entity Resolution
Entity resolution SHALL determine whether references represent the same entity, aliases, versions, related but distinct entities or unresolved entities.
Resolution MAY consider:
- official identifiers;
- manufacturer identifiers;
- legal identifiers;
- semantic identifiers;
- names;
- versions;
- source authority;
- temporal validity;
- structural context.
Similarity SHALL NOT automatically merge entities.
A resolution decision SHALL identify compared objects, evidence, decision, authority, confidence, time and provenance.
19. Merge and Split
An entity merge SHALL preserve source entities, target entity, rationale, surviving identifiers, aliases, relationships, conflicts, historical references and provenance.
An entity split SHALL preserve source entity, target entities, property allocation, relationship allocation, affected assertions, affected projections and provenance.
Objects with incompatible authority, tenancy or rights SHALL NOT be merged.
20. Supersession and Replacement
Supersession SHALL preserve predecessor, successor, scope, effective time, compatibility, affected relationships, affected assertions and provenance.
Replacement SHALL NOT erase prior historical validity.
21. Conflict Model
Conflicts SHALL be first-class governed states.
A conflict SHALL identify:
- conflicting objects;
- conflicting assertions;
- source evidence;
- authority;
- confidence;
- temporal context;
- reviewer;
- resolution state;
- provenance.
Conflict states MAY include unresolved, under review, partially resolved, resolved, accepted divergence, jurisdiction-specific divergence and historical divergence.
22. Graph Integrity
The Pergamum Pulse graph SHALL enforce:
- valid object identifiers;
- valid relationship types;
- valid source and target classes;
- valid direction;
- valid cardinality;
- temporal consistency;
- scope consistency;
- tenant isolation;
- provenance completeness;
- lifecycle compatibility.
22.1. Orphan Objects
An orphan object is an object without required ownership, provenance or relationships.
Orphan objects SHALL create Findings.
22.2. Dangling Relationships
A relationship referencing missing objects SHALL be invalid.
22.3. Cycles
Cycles MAY be allowed only for relationship types that permit them.
22.4. Authority Escalation
Graph traversal SHALL NOT infer greater authority than explicitly represented.
22.5. Rights Leakage
Graph traversal SHALL enforce Rights Records and access scope.
22.6. Tenant Leakage
Cross-tenant relationships SHALL be prohibited unless explicitly authorised.
23. Graph Traversal Contract
Every traversal SHOULD identify:
- starting object;
- relationship types;
- direction;
- depth;
- scope;
- tenant;
- white-label context;
- time;
- authority filter;
- rights filter;
- result limit;
- provenance.
traversal:
start: PP-KE-000001
relationship_types:
- supported_by
- derived_from
direction: outbound
depth: 3
tenant_scope: none
valid_at: 2026-08-04T00:00:00Z
Historical traversal SHALL evaluate the graph as it existed at the requested valid and transaction times.
Restricted nodes MAY be omitted, redacted or represented by controlled placeholders.
Every material result SHOULD expose the path used.
24. Graph Projections
A graph projection is a purpose-bound view of canonical knowledge.
Projection types MAY include:
- public graph;
- tenant graph;
- white-label graph;
- framework graph;
- device capability graph;
- certification graph;
- regulatory graph;
- Runtime eligibility graph.
A projection SHALL preserve source graph version, filter rules, rights rules, tenant rules, time, generated time and provenance.
25. Module and Component Lineage
Every object and relationship that affects ZAYAZ execution SHALL preserve:
- accountable Module;
- implementing Component;
- supporting Components;
- source Components;
- affected Modules;
- affected Components;
- Runtime-consuming Components;
- Publication-consuming Components.
No orphan Component lineage is permitted.
26. Review and Approval
Objects and relationships MAY require review according to risk.
Review classes MAY include:
- source;
- rights;
- legal;
- semantic;
- technical;
- security;
- tenant isolation;
- certification;
- Publication;
- Runtime.
A Review Record SHALL identify reviewed object, reviewer, competence, scope, Findings, decision, time and provenance.
27. Conformance Levels
27.1. Level 1 — Structurally Valid
The object or relationship has:
- valid identifier;
- valid type;
- valid schema;
- valid lifecycle;
- basic provenance.
27.2. Level 2 — Governed
It additionally has:
- authority;
- scope;
- rights;
- review;
- temporal validity;
- ownership.
27.3. Level 3 — Graph-Integrated
It additionally has:
- valid relationships;
- graph integrity;
- Module lineage;
- Component lineage;
- conflict treatment.
27.4. Level 4 — Automation-Eligible
It additionally has:
- complete provenance;
- approved authority;
- approved rights;
- HECATE validation;
- approved Change Decision;
- no blocking Findings;
- explicit activation boundary.
28. HECATE Validation
HECATE SHALL validate:
- object identifier;
- object prefix;
- object type;
- semantic identity;
- version;
- lifecycle;
- temporal validity;
- scope;
- authority structure;
- rights relationship;
- provenance;
- relationship type;
- source and target classes;
- direction;
- cardinality;
- inverse rules;
- transitivity rules;
- tenant isolation;
- Module lineage;
- Component lineage;
- graph integrity.
HECATE SHALL NOT:
- invent object identity;
- merge entities autonomously where ambiguity exists;
- create authority;
- waive rights;
- resolve disputed legal meaning;
- approve a relationship solely from statistical similarity;
- activate graph-derived changes.
29. Conformance Fixtures
Implementations SHOULD provide fixtures for:
- valid Source Object;
- invalid prefix;
- duplicate identifier;
- immutable version;
- superseded version;
- invalid lifecycle transition;
- valid bitemporal object;
- overlapping temporal conflict;
- tenant-scoped object;
- prohibited cross-tenant relationship;
- valid assertion;
- assertion without source fragment;
- valid Knowledge Entity;
- duplicate entity candidate;
- merge with conflicting rights;
- valid symmetric relationship;
- invalid inverse relationship;
- cardinality violation;
- transitive relationship;
- non-transitive relationship;
- dangling relationship;
- orphan Component lineage;
- rights-restricted traversal;
- historical traversal;
- graph projection;
- valid Change Candidate;
- Candidate without Decision;
- valid Projection Manifest;
- active projection without activation authority;
- complete provenance;
- materially incomplete provenance.
30. Migration and Compatibility
Schema revisions SHALL identify:
- source specification version;
- target specification version;
- changed object classes;
- changed relationship types;
- migration rules;
- compatibility;
- affected objects;
- affected projections;
- validation;
- provenance.
Migration SHALL NOT:
- reuse identifiers;
- overwrite historical versions;
- infer unknown authority;
- infer rights;
- merge objects silently;
- delete unresolved conflicts.
31. Security Requirements
Object and relationship stores SHALL enforce:
- authentication;
- authorisation;
- least privilege;
- tenant isolation;
- white-label isolation;
- encryption;
- access logging;
- tamper evidence;
- backup;
- recovery;
- incident response.
Sensitive relationship existence MAY itself require classification.
32. Historical Reconstruction
A historical reconstruction SHALL identify:
- object version;
- relationship version;
- valid time;
- transaction time;
- authority at that time;
- rights at that time;
- scope at that time;
- graph path at that time;
- projections derived;
- activations performed;
- provenance.
Historical reconstruction SHALL NOT apply current relationships retroactively.
33. Conformance Requirements
An implementation conforms to this specification where it:
- assigns stable PP-prefixed identifiers to all first-class objects;
- prevents identifier reuse;
- distinguishes semantic identity from storage location;
- preserves external identifiers separately;
- implements the universal object contract;
- preserves independent object versions;
- preserves immutable published versions;
- implements governed lifecycle transitions;
- preserves tombstones where deletion occurs;
- preserves bitemporal validity;
- represents unknown temporal values explicitly;
- enforces tenant and white-label scope;
- prevents unauthorised scope promotion;
- separates authority dimensions;
- prevents authority transitivity;
- preserves complete provenance;
- distinguishes all canonical object classes;
- preserves Source Series and Source Object separation;
- preserves Source Object and Source Capture separation;
- preserves Knowledge Document and Knowledge Entity separation;
- preserves Source Fragment and Knowledge Assertion separation;
- preserves Bundle membership without merging authority or rights;
- represents relationships as governed typed objects or edges;
- governs relationship types through a Registry;
- enforces source and target class constraints;
- enforces direction and cardinality;
- treats relationships as non-transitive by default;
- preserves inverse relationship rules;
- preserves relationship authority and confidence;
- supports entity resolution without automatic similarity-based merge;
- governs entity merge and split;
- preserves supersession and replacement history;
- preserves conflicts as first-class states;
- prevents dangling relationships;
- prevents orphan objects and orphan Components;
- enforces graph rights and tenant isolation;
- supports explainable traversal;
- supports historical traversal;
- supports purpose-bound graph projections;
- preserves Module lineage;
- preserves Component lineage;
- supports risk-based review and approval;
- defines conformance levels;
- validates objective structure through HECATE;
- prevents HECATE from creating authority or resolving disputed meaning autonomously;
- supports conformance fixtures;
- governs schema migration;
- preserves security and auditability;
- reconstructs historical graph state without retroactive reinterpretation.
34. Foundational Principle
Pergamum Pulse knowledge SHALL be modelled as stable objects connected by explicit relationships, not as ungoverned text associations.
Every object SHALL retain identity, version, lifecycle, scope, authority, rights, time and provenance. Every relationship SHALL retain type, direction, scope, validity, authority and evidence. Every graph path SHALL remain explainable.
Similarity is not identity. Correlation is not relationship. Relationship is not authority. Projection is not activation.
By governing knowledge objects and relationships as first-class, versioned and historically reconstructable artefacts, Pergamum Pulse can support semantic intelligence, crosswalks, device graphs, regulatory reasoning, certification evidence and automated projections without sacrificing constitutional boundaries, tenant isolation or trust.