Axis 2: Concepts

V7GUID - Version-7-GUID

V7GUID (also: Categorized UUIDv7 Identifier) is a categorization scheme for identifiers in GitCover artifacts, based on RFC-4122-compatible UUID Version 7 (time-based, sortable), extended by a GitCover-specific class classification.

Structure

Purpose: Deterministic, sortable linking of documents in an evidence chain. Enables temporal/versioned reconstructability (GoBD: timeliness) without a central sequence database.

Time base: GMT/UTC (normative rule)

The 48-bit timestamps of all V7GUIDs and uuidV7s must always be generated and interpreted on the basis of GMT/UTC (offset 0) - never on the basis of a local time zone (CEST, CET, etc.):

Rationale:

• Time-zone-neutral: A UTC-based timestamp is unambiguously interpretable worldwide. Local time signals (daylight saving transitions, time zone boundaries) do not distort sortability and comparability.
• Convertibility: Any app can convert the UTC timestamp into the user's local time zone at any time - especially apps that must maintain a time record (e.g. employee time tracking, working-time records, deadline tracking). The reverse approach (local time as the basis) leads to ambiguities (daylight saving changeover: 03:00 CEST = 01:00 UTC exists twice).
• GoBD compliance: Timeliness and traceability (§ 146 AO) require an immutable, unambiguous time base. UTC is the only basis that guarantees this property systemically.
• Consistency with RFC 9562: The UUIDv7 standard defines the timestamp as Unix epoch milliseconds (UTC); any generation deviating from this violates the standard.

Detection rule: When decoding a V7GUID/uuidV7, the extracted 48-bit value must always be read as UTC. Display/further processing in local time takes place exclusively in the app's presentation layer, never in the identifier base.

Norm & implementation: The V7GUID principle (6-level hierarchy in GUID bits, fixed bit ranges, O(1) lookup, cross-repo references) is part of the patent application 10 2025 003 091.6. The canonical bit assignment (exact offsets/widths/value ranges per segment) is normatively maintained in the protocol specification specs/v7guid/ - see 00_gesamtkarte.md there. GCBoK represents this norm; in the event of deviations, the specification prevails.

Class-Identifier - Segment Register

The GitCover Class-Identifier (the class segment of the V7GUID) is built deterministically 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 with their respective maximum possible value and forms the binding reference for interoperability between GitCover repos.

Business hierarchy (deterministic classification)

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.

Business Hierarchy as an Ontology

The six dictionaries (Entity to Instance) together form the GitCover ontology: a machine-readable, shared vocabulary of the organization — entities (e.g., Business Entity, Business Partner), their relationships, rules, and classifications. This means humans, validators, and AI agents all speak the same language: a term such as "ERechnung" (ProcessType 13) means the same thing in every repo, every schema, and every policy.

At GitCover, the ontology is implemented Git-natively — not as a graph database within a platform:

Microsoft describes its semantic layer as a "governed, self-service knowledge graph" that provides agents with "shared context" — the same problem space (agent context, uniform terms), but solved in a platform-bound way. GitCover solves it repo-natively: The ontology is the normative corpus in the Git repo, not a service from a vendor. Details on the distinction: Glossary ("Ontology") and Components: GCUCB, Market Context.

Extended Fields of the V7GUID (Compliance Typing)

In addition to the 6-level hierarchy, the V7GUID carries six additional fields that can be populated deterministically. They are categorization/classification aids and type additional compliance aspects of a document. They are explicitly not object instance identifiers - which concrete object is meant is determined solely by the Object ID (the pure uuidv7) of the dual identifier. Many objects share the same field value.

Note: VariantId was formerly named InstanceId; the name was changed because the field types a variant class, not an object instance. GatewayId/VariantId were reduced from 16/14 to 8/6 bits with ADR-002 to make room for status and kind - see specs/v7guid/ADR-002_layout_v2_kind.md.

A single identifier thus encodes multidimensionally what, where, by what means, via which control point, at which lifecycle stage and in which variant a document was created - directly verifiable from the GUID (O(1), without a database query). Example of a validated e-invoice: 1_14_12_14_13_1 + RepositoryId 3 (DMS) + ProcessTypeId 12 (EN16931 validation) + GatewayId 220 (four-eyes approval) + VariantId 10 (10-year retention).

Assignment: The 4-bit levels L1–L6 are globally canonical and are coordinated exclusively via the dictionaries in the TOP .gitcover repo (exchange via GCEP/GCUCB). The extended fields have their own dictionaries (repository_ids.json, processtype_ids.json, gateway_ids.json, kinds.json, status_flags.json, variant_ids.json); the highest value in each case is reserved as Custom/TenantDefined. Unassigned codes remain free for later global allocation. Normative reference: specs/v7guid/50_erweiterte_kennfelder_compliance.md.

Extended identifier fields of the V7GUID (compliance typing)

In addition to the 6-level hierarchy, the V7GUID carries six further deterministically assignable identifier fields. They are categorization/classification aids and type additional compliance aspects of a document. They are expressly not object instance identifiers - which concrete object is meant is stated solely by the Object ID (the pure uuidv7) of the dual identifier. Many objects share the same identifier field value.

Note: VariantId was formerly called InstanceId; the name was changed because the field types a variant class, not an object instance. GatewayId/VariantId were reduced from 16/14 to 8/6 bits with ADR-002 to make room for status and kind - see specs/v7guid/ADR-002_layout_v2_kind.md.

A single identifier thus encodes multidimensionally what, where, by what, via which control point, at which lifecycle stage and in which variant a document originated - verifiable directly from the GUID (O(1), without a database query). Example of a verified e-invoice: 1_14_12_14_13_1 + RepositoryId 3 (DMS) + ProcessTypeId 12 (EN16931 verification) + GatewayId 220 (four-eyes approval) + VariantId 10 (10-year retention).

Assignment: The 4-bit levels L1–L6 are globally canonical and are coordinated exclusively via the dictionaries in the TOP .gitcover repo (exchange via GCEP/GCUCB). The extended identifier fields have their own dictionaries (repository_ids.json, processtype_ids.json, gateway_ids.json, kinds.json, status_flags.json, variant_ids.json); the highest value in each case is reserved as Custom/TenantDefined. Unassigned codes remain free for later global allocation. Normative reference: specs/v7guid/50_erweiterte_kennfelder_compliance.md.

Central Tenant Register

The TenantId of a GitCover legal entity is not derived from an assigned 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 come into existence at the same millisecond moment.

Freely selectable time source: The 48-bit timestamp does not have to be the actual creation point in time. Instead of the system time (DateTime.Now), each tenant can generate the UUIDv7 from an explicitly specified point in time - for example the founding date of the legal entity or any other freely chosen reference date (cf. CustomEpoch/timestamp in the TenantContext). This allows the tenant identifier to be tied to a date of substantive significance; uniqueness is preserved as long as the chosen millisecond point in time does not collide across tenants (a further reason for voluntary registration).

Because GitCover repos reference one another 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, without number ranges)

• 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 maintenance in the register.
• Voluntariness. Registration is optional. Anyone who requires cross-repo interoperability and collision freedom for others.json traversals registers 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 in the respective tenant root under .gitcover/access/TENANT_GUID_REGISTER.md (short name · legal entity · UUIDv7 · timestamp · status). It is the authoritative list of registered tenants.

Evidence Chains

An evidence chain chains compliance artifacts together via prev-hash references:

1. Document B1 - V7GUID: ...-PERSON-..., SHA256: 3f2a1c..., prev: -
2. Document B2 - V7GUID: ...-INVOICE-..., SHA256: 7d4e2f..., prev: 3f2a1c...
3. Document B3 - V7GUID: ...-PAYMENT-..., SHA256: 1b8f90..., prev: 7d4e2f...

Each document 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"

Binary originals and V7GUID sidecars

Documents that exist as binary files (PDF, DOCX, EML, image) cannot carry metadata inside Git. They are attached to the evidence chain via a V7GUID sidecar (*.v7g.md next to the original): The sidecar carries at least the sha256 of the original as well as the DocID (uuidv7, instance identifier) and the categorized v7guid (context). The process and the assignment of the DocID from the file timestamp are described in Axis 5: Procedures; for the associated tenant registration see Central Tenant Register above.

Transaction container (.gcpn.md) — process level of the evidence chain

Alongside the per-sidecar cataloging, the GCPN container comes into play for multi-stage transactions (e.g. the creation and signing of a GVB): a .gcpn.md next to the Referenced-Doc (<Referenced-Doc-Basisname>.gcpn.md) that accompanies the process as a standalone process origin doc — not as a sidecar of the Referenced-Doc. Conceptually:

• Mutable doc with immutable JSON artifacts (schema gcpn-container-1.0): referenced_doc, actor, retention are described once each; further references run via SHA-256 or actor_ref — no internal redundancy.
• Events as flags enum with result: offered(1), accepted(2), denied(4), sign(8), withdraw(16) — the steps traversed yield the events_result bitmask (e.g. 11 = offered + accepted + sign) with chain_valid confirmation of the hash chaining.
• Extend rather than create anew: Each new process step sets the flag, embeds the new artifact and updates summary; already embedded JSON artifacts remain unchanged (immutable). The container history is retained revision-safely in the Git history of the repo.
• JSON always embedded (MD fence) — no standalone .json files in the repo tree (avoid bloating).
• GCDMS index function: In the optionally attached DMS, the container serves as an index for process navigation to the individual docs — instead of n8n or similar workflow engines.

A signed Referenced-Doc becomes immutable afterwards (GoBD: immutability); the container remains mutable and continues to document the process — the Git history is the proof.

GCPN as protocol — the act as state transition

A GCPN is a form of protocol. In the GCBoK, with compliance as the main topic, shareholders' meetings with resolutions that are summarized in a GVB are often discussed:

This dual interpretation (protocol + state transition) is the core of provability: Each act is described deterministically — the state before is provable via the SHA-256 chain (sidecars, Referenced-Doc), the state after via the flags expression and the embedded artifact. The Git history of the container provides the chronology. Procedure and verification: Axis 3 (GCPN) and Digital Signing (DS02–DS05).

Cryptographic Evidence Chain

The Cryptographic Evidence Chain combines three cryptographic primitives:

1. Git commit hash - immutability of the repository state
2. GPG signature - identity of the actor (Who decided?)
3. V7GUID - deterministic addressing (What and When)

This produces a chain that is both cryptographically anchored and temporally sortable - the foundation for revision-safe compliance evidence.

Recovery fallback: In the end, only Git repos remain In the event of catastrophe, loss of infrastructure, or an audit 10 years later, the last functional artifact set is the Git repository itself (or git bundle/ZIP export). Contained within: code artifacts, .gitcover/ registries/dictionaries (JSON/JSONL), GPG keyrings (.gitcover/keys/), V7GUID evidence chains. No database, no web server, no running services required. The forensics is the Git repo — HTML auditor packages are only presentation derivatives (see Procedures: Audit-Readiness).

Deterministic branching

Deterministic branching makes it possible to bind 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, audit-ready compliance structures emerge - without manual upkeep.

See also: The technical primitives (GPG, uuidV7, OSCAL) are explored in depth in Axis 4: Techniques.