Axis 2: Concepts
V7GUID — Version-7 GUID
V7GUID (also: Categorized UUIDv7 Identifier) is a classification scheme for identifiers in GitCover artifacts, based on RFC 4122-compliant UUID Version 7 (time-based, sortable), extended with a GitCover-specific class classification.
Structure
| Segment | Bits | Range | Meaning |
|---|---|---|---|
| timestamp_ms | 48 | RFC 4122 UUIDv7 basis | Milliseconds since Unix Epoch (sortable) |
| version | 4 | RFC 4122 UUIDv7 basis | Fixed: 0111 (UUIDv7) |
| rand_a | 12 | RFC 4122 UUIDv7 basis | Deterministic vector for GitCover Tenant-/Doc-/Class-/Action-Dictionaries (defined in TOP's .gitcover repo) |
| variant | 2 | RFC 4122 UUIDv7 basis | Fixed: 10 (RFC 4122) |
| repository_id | 12 | GitCover extension | Repo/tenant scope (from RFC rand_a) |
| class (L1–L6 + extended fields) | 62 | GitCover extension | Deterministically assigned GitCover payload (6-level hierarchy + extended fields for compliance typing, from RFC rand_b) |
Purpose: Deterministic, sortable linking of evidence in an evidence chain. Enables temporal/versioned reconstructability (GoBD: timeliness) without a central sequence database.
Norm & implementation: The V7GUID principle (6-level hierarchy encoded in GUID bits, fixed bit ranges, O(1) lookup, cross-repo references) is part of patent application
10 2025 003 091.6. The canonical bit layout (exact offsets/widths/value ranges per segment) is normatively maintained in the protocol specificationspecs/v7guid/— see00_gesamtkarte.mdthere. GCBoK renders this norm; in case of discrepancy, the specification prevails.
Class Identifier — Segment Register
The GitCover class identifier (the class segment of the V7GUID) is deterministically composed from a six-level business hierarchy. Each level is 4 bits wide (value range 0–15, i.e. 16 possible values per level) and is globally assigned via a normative dictionary in the .gitcover repo of the TOP directory. In addition, the V7GUID carries several extended identifier fields. The following register lists all segments grouped together with their respective maximum value and constitutes the authoritative reference for interoperability between GitCover repos.
Business Hierarchy (deterministic classification)
| # | Segment | Bits | Max value | Dictionary | Meaning |
|---|---|---|---|---|---|
| L1 | Entity | 4 | 15 | entities.json |
Business Entity (e.g. 1 BusinessEntities, 2 BusinessPartners) |
| L2 | Department | 4 | 15 | departments.json |
Department/area (e.g. 14 Portfolio, 9 IT) |
| L3 | Category | 4 | 15 | categories.json |
Category (e.g. 15 Service, 14 DocSigning) |
| L4 | SubCategory | 4 | 15 | subcategories.json |
Sub-category (e.g. 14 Leistung, 13 Preisposition) |
| L5 | ProcessType | 4 | 15 | processtypes.json |
Process type (e.g. 13 ERechnung, 14 Gobd, 15 Agentic) |
| L6 | Instance | 4 | 15 | instances.json |
Instance (e.g. 1 Default, 2 Primary) |
The classification string notation combines the six levels into L1_L2_L3_L4_L5_L6 — e.g. 1_14_12_14_13_1 (portfolio price position). The value range 16⁶ = 16,777,216 covers all deterministic classifications.
Extended V7GUID identifier fields (compliance typing)
Beyond the 6-level hierarchy, the V7GUID carries four further deterministically assignable fields. They are categorization/classification helpers that type additional compliance aspects of an artifact. They are explicitly not object-instance identifiers — which concrete object is meant is stated solely by the Object ID (the plain uuidv7) of the dual identifier. Many objects share the same field value.
| Segment | Bits | Max value (Custom) |
Question | Compliance dimension |
|---|---|---|---|---|
| RepositoryId | 12 | 4,095 | Where? | Repo/data scope (TOP + up to 4,095 repos per tenant); tenant/PII separation |
| ProcessTypeId | 8 | 255 | By what process? | Procedure that produced the artifact (GoBD, EN16931, AI Act) |
| GatewayId | 16 | 65,535 | Control point? | Handover/approval point (evidence chain, segregation of duties) |
| VariantId | 14 | 16,383 | Which variant? | Legal context (retention §147 AO, GDPR protection level, IFRS/HGB) |
Note:
VariantIdwas formerlyInstanceId; it was renamed because the field types a variant/context class, not an object instance.
Thus a single identifier encodes multi-dimensionally what, where, by what process, through which control point, and in which variant an artifact originated — verifiable directly from the GUID (O(1), without a database query). Example of a reviewed e-invoice: 1_14_12_14_13_1 + RepositoryId 3 (DMS) + ProcessTypeId 12 (EN16931 check) + GatewayId 220 (four-eyes approval) + VariantId 10 (10-year retention).
Assignment: The 4-bit levels L1–L6 are globally canonical and coordinated exclusively via the dictionaries in the TOP
.gitcoverrepo (exchanged via GCEP/GCUCB). The extended fields use their own dictionaries (repository_ids.json,processtype_ids.json,gateway_ids.json,variant_ids.json); the highest value of each is reserved asCustom/TenantDefined. Unassigned codes remain free for later global assignment. Normative reference:specs/v7guid/50_erweiterte_kennfelder_compliance.md.
Central Tenant Register
The TenantId of a GitCover legal entity is not derived from an allocated number range, but deterministically from the first 48 bits (millisecond timestamp) of the UUIDv7 that is generated when the tenant's TOP directory is first created. The tenant identifier is therefore time-bound, sortable and unique without a central sequence database — as long as no two tenants are created at the same millisecond.
Freely selectable time source: The 48-bit timestamp does not have to be the actual creation time. Instead of the system clock (DateTime.Now), any tenant can generate the UUIDv7 from an explicitly provided point in time — such as the legal entity's founding date or any other chosen reference date (cf. CustomEpoch/timestamp in TenantContext). This allows the tenant identifier to be bound to a business-meaningful date; uniqueness is preserved as long as the chosen millisecond does not collide across tenants (another reason for voluntary registration).
Because GitCover repos reference each other via others.json traversals (cross-repo resolution of physical and logical paths), a tenant identifier must be uniquely resolvable when used across repos. For this reason a central, voluntary register exists.
Registration model (voluntary, no number ranges)
| State | Meaning | Interoperability |
|---|---|---|
| Publicly registered | The tenant UUIDv7 is listed in the central register (short name, legal entity, timestamp, status) | Collision-free resolvable; authoritative for others.json traversals between repos |
| Private / unregistered | The tenant UUIDv7 exists locally but is not listed in the register | Permitted for internal use; collision risk in cross-repo traversals (no conflict protection, no guaranteed resolution) |
- No reserved number ranges. Since the TenantId is derived from the 48-bit timestamp, there is neither a "public" nor a "private" number range — the distinction lies solely in whether it is listed in the register.
- Voluntariness. Registration is optional. Those who need cross-repo interoperability and collision-freedom for
others.jsontraversals register their tenant publicly. - Immutability. A registered tenant identifier is final and stable; no re-use after dissolution (status
ARCHIVED).
Canonical register instance: The operational tenant register is maintained under
.gitcover/access/TENANT_GUID_REGISTER.mdin the respective tenant root (short name · legal entity · UUIDv7 · timestamp · status). It is the authoritative list of registered tenants.
Evidence Chains
An evidence chain links compliance artifacts via prev-hash references:
- Evidence B1 — V7GUID:
...-PERSON-..., SHA256:3f2a1c..., prev: — - Evidence B2 — V7GUID:
...-INVOICE-..., SHA256:7d4e2f..., prev:3f2a1c... - Evidence B3 — V7GUID:
...-PAYMENT-..., SHA256:1b8f90..., prev:7d4e2f...
Each evidence references the SHA-256 hash of its predecessor. The entire chain is thus cryptographically anchored and tamper-proof.
Metadata Schema (.v7g.md)
v7guid: "0197a3b2-f3c0-7b00-8001-000000000042"
class: INVOICE
sha256: "7d4e2f..."
prev_sha256: "3f2a1c..."
gpg_fingerprint: "ABCD1234..."
timestamp_iso: "2026-06-14T11:18:00+02:00"
gobd_periode: "FY2026"
Cryptographic Evidence Chain
The Cryptographic Evidence Chain combines three cryptographic primitives:
- Git Commit Hash — Immutability of the repository state
- GPG Signature — Identity of the actor (Who decided?)
- V7GUID — Deterministic addressing (What and When)
This creates a chain that is both cryptographically anchored and temporally sortable — the foundation for audit-proof compliance evidence.
Deterministic Branching
Deterministic branching enables binding evidence chains to Git repository structures. Through the combination of:
- Git repositories as compliance periods (e.g.,
FY2026) - V7GUID classes as document types (INVOICE, PAYMENT, PERSON)
- OPA policies as pre-receive hooks (validation before commit)
reproducible, auditable compliance structures emerge — without manual maintenance.
See also: The technical primitives (GPG, uuidV7, OSCAL) are detailed in Axis 4: Techniques.