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 evidence items 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 are always to be generated and interpreted based on GMT/UTC (offset 0) — never based on a local time zone (CEST, CET, etc.):

Rationale:

• Time-zone-neutral: A UTC-based timestamp can be interpreted unambiguously worldwide. Local time signals (daylight saving changes, time zone boundaries) do not distort sortability and comparability.
• Convertibility: Every app can convert the UTC timestamp into the user's local time zone at any time — especially apps that must keep a time mark (e.g. time tracking for employees, working-time records, deadline tracking). The reverse path (local time as the basis) leads to ambiguities (daylight saving change: 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 base that systematically guarantees this property.
• Consistency with RFC 9562: The UUIDv7 standard defines the timestamp as Unix epoch milliseconds (UTC); any generation deviating from this violates the standard.

Recognition rule: When decoding a V7GUID/uuidV7, the extracted 48-bit value is always to be read as UTC. Display/processing in local time occurs exclusively in the app's presentation layer, never in the identifier base.

Standard & implementation: The V7GUID principle (6-level hierarchy 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 assignment (exact offsets/widths/value ranges per segment) is maintained normatively in the protocol specification specs/v7guid/ — see 00_gesamtkarte.md there. GCBoK represents this standard; in case of deviations, the specification applies.

Class Identifier - Segment Register

The GitCover class identifier (the class segment of the V7GUID) is constructed deterministically from a six-level business hierarchy. Each level is 4 bits wide (value range 0–15, thus 16 possible variants 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 item). The value range 16⁶ = 16.777.216 covers all deterministic classifications.

Business Hierarchy as Ontology

The six dictionaries (Entity through 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. In this way, people, validators and AI agents speak the same language: a term such as “EInvoice” (ProcessType 13) means the same in every repo, every schema and every policy.

At GitCover, the ontology is implemented Git-natively — not as a graph database in 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 asset in the Git repo, not a service at a provider. Details on the distinction: Glossary (“Ontology”) and Components: GCUCB, Market Context.

Extended Identifier Fields of 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 an evidence item. 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. With ADR-002, GatewayId/VariantId were reduced from 16/14 to 8/6 bits to make room for status and kind — see specs/v7guid/ADR-002_layout_v2_kind.md.

Thus a single identifier encodes multidimensionally what, where, by what, via which control point, in which lifecycle state and in which variant an evidence item arose — directly verifiable from the GUID (O(1), without a database query). Example of a checked 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 are coordinated exclusively via the dictionaries in the TOP .gitcover repo (exchange via GCEP/GCUCB). Separate dictionaries apply for the extended identifier fields (repository_ids.json, processtype_ids.json, gateway_ids.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.

Process Gateway (pgid) and Action Registry (261026)

The 8-bit GatewayId types the control point. The complete process gateway identity (pgid) is a V7GUID class composed of repository_id + gateway_id (+ class epoch), generated with gc-v7guid class — not a random UUID and not derived from the document SHA.

Registry (two-level): OSS/TOP/.gitcover/dictionaries/gateway_ids.json (8-bit values) and <Tenant>/TOP/compliance/process_gateways.json (process_key, uuidV7 = pgid, repository_id, gateway_id). The GCUV block 180–189 is provisional until OSS allocation: 180 invoice creation, 181 PDF, 182 verify, 183 DMS ingest, 184 books, 185 OP.

Role separation: produced_by_pgid is the creating action (e.g. gc-billing invoice); stored_by_pgid is the storing action (gc-dms scan --apply). The DMS registry stores the invoice; it does not create it. The DMS object_id is the sidecar docUid, not a new registry UUID.

Evidence: GCUV/TOP/compliance/{PROCESS_GATEWAYS.md,process_gateways.json}; audit report AFJD/FY2026/reports/261026_pruefung_rechnungsausgang_afjd-ada.md § 8.5.

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 created for the first time. The tenant identifier is thus time-bound, sortable and unique without a central sequence database — as long as no two tenants arise at the same millisecond in time.

Freely selectable time source: The 48-bit timestamp does not have to be the actual creation time. Instead of system time (DateTime.Now), each tenant can generate the UUIDv7 from an explicitly specified point in time — for example the legal entity's founding date or any other chosen reference date (cf. CustomEpoch/timestamp in the TenantContext). This allows the tenant identifier to be tied to a professionally significant date; 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 unambiguously resolvable when used across repos. Therefore a central, voluntary register exists.

Registration Model (Voluntary, Without Number Ranges)

• No reserved number ranges. Since the TenantId arises 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 needs 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 (Evidence Chains)

An evidence chain links compliance artifacts via prev-hash references:

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

Each evidence item references the SHA-256 hash of its predecessor. The entire chain is thus cryptographically anchored and tamper-proof.

Metadata Schema (.gc.md Data Artifact)

The data artifact appears as a JSON fence at the end of the document (human-readable first, data last):

{
  "docUid": "0197a3b2-f3c0-7b00-8001-000000000042",
  "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 GitCover Sidecars

Evidence items that exist as binary files (PDF, DOCX, EML, image) cannot carry metadata within Git. They are attached to the evidence chain via a GitCover sidecar (*.gc.md next to the original): the sidecar carries at minimum the original's sha256 as well as the DocID (uuidv7, instance identifier) and the categorized v7guid (context). The process and the DocID assignment from the file timestamp are described in Axis 5: Procedures; for the associated tenant registration see Central Tenant Register above. For the distinction: docUid (instance), sha256 (content), V7GUID (class) and GCPN-docUid (process) are separate axes; only the document docUid becomes the DMS object_id.

Metadata Detection and Companion Variants

Document metadata detection is content-driven, not extension-driven. An original doc has metadata if an embedded JSON schema instance describes it:

1. Base sidecar <artefakt>.<orig-ext>.gc.md: The instance carries docUid (document instance), sha256 (content anchor), v7guid (class) and locations; the docUid is the document object_id.
2. Companion variant *.gcsig.md with integrated source block: The GCSIG is a signature artifact with its own docUid; the document instance is in source.v7g_docUid, the content anchor in subject.sha. The DMS takes over source.v7g_docUid as the document object_id and keeps the GCSIG docUid only as GCSIG:<docUid> in the metadata references.

Over the lifetime of a document or process, meta-documents can change their role and thus their profile — analogous to OOD variants (overload/polymorphism): the sidecar base (.gc.md) transitions into a signature artifact (.gcsig.md with source); GCPN (.gcpn.md) remains the process and is additively supplemented via documents[]/children[]/relations[]; GCAL anchors (GCPN under .gitcover/gcal/<uuidV7>.gcpn.md) remain process anchors. A rename does not change the identity of the meta-doc (docUid/process remain), but does change the SHA-256 of the file; a process transformation may rename or recreate and merge existing data. What is decisive is content identity, not the file name.

Process Container (.gcpn.md) — Process Level of the Evidence Chain

Alongside per-sidecar cataloging comes the GCPN container for multi-step processes (e.g. the creation and signing of a GVB): a .gcpn.md next to the referenced doc (<Referenced-Doc-Basisname>.gcpn.md), which accompanies the process as a standalone process original doc — not as a sidecar of the referenced doc. Conceptually:

• Mutable doc with immutable JSON artifacts (schema gcpn-container-2.7, self-contained): referenced_doc, actor, retention are described once each; tree via parents[]/children[]/documents[]; further references run via SHA-256 or actor_ref — no internal redundancy.
• Events as a flags enum with result: offered(1), accepted(2), denied(4), sign(8), withdraw(16) — the steps passed through yield the events_result bitmask (e.g. 11 = offered + accepted + sign) with chain_valid confirmation of the hash chaining.
• Supplement instead of creating 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 kept audit-proof in the repo's Git history.
• JSON always embedded (MD fence) — no standalone .json files in the repo tree (avoid bloat).
• 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 then becomes immutable (GoBD: immutability); the container remains mutable and continues to document the process — the Git history is the proof.

Single-File GCPN — Progressive/Retrograde Evidence Tracking (AO, 261026)

For invoices and other evidence items, the GCPN becomes a single-file container: a .gcpn.md carries documents[] (XML as original doc, PDF as view), the workflow create→pdf→present→accept→sign→register, events, properties.values and relations (contract/expense evidence). XML/PDF remain separate artifacts; a separate .gc.md is omitted — the GCPN carries docUid, SHA-256, path and title.

Thus the GCPN is the single melting point for UI and tooling; the SAGA (creation, presentation, acceptance, signature, registration) lies fully in the container. Normative reference: specs/v7guid/70_belegkreise-dokumentenzuordnung.de.md § “Single-File GCPN”.

Promote rule: An existing .gc.md can be enriched into the GCPN; the sidecar JSON artifacts are embedded (GCPN = superset, .gc.md = subset). After that, the separate .gc.md is redundant and can be removed from the file system; the Git history carries traceability (GoBD), and the GCPN remains SSoT.

Gates/OPA: workflow.gates[].id is a uuidV7 of the action/method (GCAL/GCEP join), workflow.gates[].rule the policy_uuid of the OPA/rule identity; both are registered (GCUV/TOP/compliance/gates.json or policies/registry.json). rule_text is only the display; classes/types run via the V7GUID catalogs.

Immutable collections: Immutable definitions (ENUM/UNION/flags) are in OSS/TOP/.gitcover/dictionaries/immutable_collections.json and are loaded once at system init. The GCPN references them via events.enum_ref (uuidV7) instead of repeating them; schema 2.7 makes enum_definition optional (legacy). The flags result from the OSCAL catalogs for GoBD/AO (profile gcpn-compliance-profile.yaml; AO §146, GoBD Rz. 146/147) — the governance anchoring is in the registry.

Invoice identity: properties.values.invoice_id is the uuidV7 of the Invoice Identifier; invoice_no is only text and not an ordering criterion. Seller/buyer are referenced via their party uuidV7 (creditor/vendor or debitor/customer), not via real names (PII).

GCPN as Protocol — the Act as State Transition

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

This dual meaning (protocol + state transition) is the core of verifiability: every act is described deterministically — the state before is verifiable via the SHA-256 chain (sidecars, referenced doc), the state after via the flags expression and the embedded artifact. The container's Git history 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 creates a chain that is both cryptographically anchored and temporally sortable — the basis for audit-proof compliance records.

Recovery fallback: In the end, only Git repos remain In the event of a disaster, infrastructure loss or an audit 10 years later, the last functional artifact set is the Git repository itself (or git bundle/ZIP export). It contains: code artifacts, .gitcover/ registries/dictionaries (JSON/JSONL), GPG keyrings (.gitcover/keys/), V7GUID evidence chains. No database, no web server, no running services required. 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-capable compliance structures arise — without manual follow-up maintenance.

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