ED03 - Diary Format: JSON Artifacts, Temporal Signature, V7GUID, Sidecars

Problem

An entrepreneur wants to keep his diary in Git - but what exactly does an entry look like technically? Today's practice has no binding answer:

• Free-text notes in Markdown, Word, or paper - not machine-readable, not schema-validated, not traceable
• Excel rows with date, activity, hours - not versioned, not cryptographically anchored, not audit-proof
• Payroll software exports as PDF - not machine-evaluable (§ 147 Abs. 6 AO), not retrogradely/progressively traceable
• No unique identity - every entry has a filename, but the filename can change; the identity of the entry is not stable
• No temporal anchoring - the date is in the document as a string, but who actually recorded it and when? The recording time is not cryptographically linked to the identity

Core Statement

A GitCover diary entry is a JSON artifact with:

1. JSON Schema First - the schema exists before the entry; the entry is validated against the schema (pre-commit hook)
2. V7GUID (Class Identifier) - classifies the document/action based on the .gitcover registry (what/which type); serves filing organization and DB query (e.g., EF Core in Vertical App)
3. uuidV7 (Object ID) - is already by itself the unique identity (DocID) of the entry, RFC 9562 §5.7, generated from a specified time mark (or now()) via GitCover helper (UuidV7Gen), remainder filled with randomness
4. Composite Key V7GUID:uuidV7 - the GCPN sidecar composite key, serves filing organization and query; the recording time is contained in the uuidV7 (48-bit timestamp), no separate datetime/date field
5. Sidecar requirement - every document receives a .v7g.md sidecar with its own uuidV7 (classification act) and the uuidV7 of the document
6. Retrograde/progressive traceability - from the journal entry → document → diary entry → uuidV7 and resolvable back

Compliance by Design: The format is not an afterthought - it is structural. Schema, V7GUID (Class), uuidV7 (Object), and sidecar are mandatory fields without which an entry is not admitted into the repo.

No redundant datetime/date: The recording time is anchored in the uuidV7 itself (48-bit timestamp, RFC 9562 §5.7). A separate string representation in JSON schemas or JSON data is redundant and is not kept in the facts. String representation for DTO/HTMX transfer is harness responsibility, not the facts level.

The Diary Entry as a Compliance Node

The technical entry is not an end in itself. It is the temporal node at which several chains of evidence converge:

The Diary SSoT states according to which agenda work was performed. Source docs, sidecars, GCPN, and land register/settlement artifacts provide the associated evidence. This separation prevents two errors: a diary entry is not misunderstood as a replacement for an external document, and a document assembled later is not falsely presented as timely proof of work.

The JSON Schema (Schema First)

The schema exists before the entry - it is stored in .gitcover/schemas/diary-entry-1.0.schema.json and is versioned. An entry without a schema reference ($schema) is rejected by the pre-commit hook.

Schema diary-entry-1.0.schema.json (simplified)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gitcover.org/schemas/diary-entry-1.0.schema.json",
  "title": "GitCover Diary Entry v1.0",
  "type": "object",
  "required": [
    "$schema", "V7GUID", "docUid",
    "author", "role", "tenant", "sphere", "source"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri",
      "const": "https://gitcover.org/schemas/diary-entry-1.0.schema.json"
    },
    "V7GUID": {
      "type": "string",
      "description": "Class Identifier - klassifiziert das Dokument/die Action aus .gitcover Registry (was/welcher Typ)"
    },
    "docUid": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
      "description": "Object ID - RFC 9562 §5.7 UUIDv7, generiert aus vorgegebener Zeitmarke (nicht now()), 48-Bit-Zeitstempel in der GUID verankert"
    },
    "author": { "type": "string", "description": "Akteur-Platzhalter, z. B. E1" },
    "role": {
      "type": "string",
      "enum": ["GF", "Buchhalter", "Lohnverantwortlicher", "F&E-Leiter", "Administrator"]
    },
    "tenant": { "type": "string", "description": "Tenant-Platzhalter, z. B. ORG-1" },
    "sphere": {
      "type": "string",
      "enum": ["ideell", "vermögensverwaltend", "zweckbetrieblich", "wirtschaftlich", "n/a"]
    },
    "source": {
      "type": "string",
      "enum": ["E1", "StB", "Notar", "Bank", "DRV", "FA", "BA", "VBG", "KK", "auto"]
    },
    "source_sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$",
      "description": "SHA-256 des referenzierten Belegs (eindeutige Beleg-ID)"
    },
    "tags": { "type": "array", "items": { "type": "string" } }
  }
}

Important - no datetime/date field: The recording time is contained in the uuidV7 (48-bit timestamp, RFC 9562 §5.7). A separate string representation is redundant and is not kept in the facts. The uuidV7 alone is the unique DocID; the composite key V7GUID:uuidV7 serves filing organization and DB query.

V7GUID - Structure and 48-Bit Timestamp

Core principle: The 48-bit timestamp component (bits 0–47) is authoritative for the recording time. It is anchored in the uuidV7 itself and cannot be changed afterward without making the GUID invalid. A separate datetime field does not exist - the time is contained in the uuidV7. String representation for DTO/HTMX is harness responsibility.

GitCover Extension: Hierarchy and Process IDs in Bits 66–127

The GitCover V7GUID specification (work/OSS/TOP/.gitcover/specs/v7guid/) extends the 62-bit random component (bits 66–127) with a 6-level hierarchy and process IDs - this is the patent-protected extension (DPMA Az. 10 2025 003 091.6):

Note: This extension is not strictly required for the diary series - it becomes relevant in ED02 (tenant/sphere/role) and later articles (harness). Here the RFC 9562 basis with 48-bit timestamp is sufficient.

Helper Routines: Creating V7GUID from Foreign Keys

The GitCover OSS tool UuidV7Gen (work/OSS/TOP/tools/UuidV7Gen/) provides two central operations:

gen - Generate uuidV7 (guid)

# Erzeugt eine neue uuidV7 mit vorgegebener Zeitmarke (nicht now())
# Zeitmarke z. B. aus Dateiname "260815_0900" → ISO 2026-08-15T09:00:00Z
uuidv7gen gen "2026-08-15T09:00:00Z" "Tagebucheintrag-260815"

# Ausgabe: Label;UUID;ISO-Zeitstempel
# Tagebucheintrag-260815;019f2c6f-0900-7000-8000-000000000000;2026-08-15T09:00:00.000Z

decode - Extract timestamp from uuidV7

# Extrahiert den 48-Bit-Zeitstempel aus einer uuidV7
uuidv7gen decode 019f2c6f-0900-7000-8000-000000000000

# Ausgabe: ISO-8601-Zeitstempel
# 2026-08-15T09:00:00.000Z

Foreign Key → uuidV7

The helper routines allow creating a valid uuidV7 key from a foreign key (e.g., a time mark in the filename such as 260815_0900_Lohnabrechnung.pdf) - with a specified time mark, not now():

1. Parse foreign key - 260815_0900 → 2026-08-15T09:00:00Z
2. Calculate 48-bit timestamp - Unix milliseconds since epoch
3. Generate uuidV7 - Guid.CreateVersion7() with explicit timestamp, remainder with randomness
4. Composite Key - V7GUID (class from registry) : uuidV7 (object with time mark)
5. GoBD documentation - timely recording traceably anchored (no separate datetime field)

GoBD reference: Timely recording (GoBD Rz. 146) is cryptographically documented by the 48-bit timestamp in the uuidV7 - not merely claimed. The timestamp is part of the identity, not changeable afterward.

Sidecar Structure (.v7g.md)

Every document receives a sidecar with two uuidV7 references:

Sidecar Example

{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-1.0.schema.json",
  "V7GUID": "<V7GUID-Class-aus-Registry>",
  "docUid": "019f2c6f-0900-7001-8000-000000000001",
  "sha256": "ab94670c0dd8499c27ef2feddd1d9c5925977d55a52150a6fca0f6567d2e5e79",
  "title": "260815_Lohnabrechnung.pdf",
  "original_filename": "260815_Lohnabrechnung.pdf",
  "locations": [
    {
      "unc_path": "./ORG-1/sources/lohn/260815_Lohnabrechnung.pdf",
      "from": "260815",
      "to": null,
      "note": "Primärspeicherort"
    }
  ],
  "v7g_taxonomy": [
    {
      "v7guid": "019f2c6f-0900-7000-8000-000000000000",
      "taxonomy": "ORG-1/Lohn",
      "valid_from": "260815",
      "valid_to": null,
      "note": "Tenant: ORG-1, Category: Lohn, Sphäre: ideell"
    }
  ],
  "gcpn": {
    "prima_nota_ref": null,
    "journal_entry_ref": null
  },
  "obsolescence": {
    "status": "active",
    "superseded_by": null,
    "superseded_at": null
  }
}

Composite Key V7GUID:uuidV7:

• V7GUID (field 1) - Class Identifier of the sidecar (classification from .gitcover registry: what/which type)
• uuidV7 (field 2) - Object ID of the sidecar itself, generated with a specified time mark (when was classification performed?), 48-bit timestamp anchored in the GUID
• v7g_taxonomy[].v7guid - Object ID of the classified document (which document is being classified?)
• sha256 - identity of the classified original document — the proof of originality, always and everywhere (even if the document moves: path-/name-independent, calculated from the content)

Thus not only the document is uniquely identified (via its SHA-256), but also the classification act itself - including the point in time (in uuidV7), who classified, and in which role. No separate datetime field - the time is contained in the uuidV7 values.

Retrograde and Progressive Traceability

GoBD reference: Retrograde traceability corresponds to GoBD Rz. 146 (traceability). Progressive traceability corresponds to GoBD Rz. 147 (auditability). Both are guaranteed by design through uuidV7 + SHA-256 - not through manual cross-references.

Time Recording in the Diary

Every diary entry contains a time recording table:

Column rule: The Purpose column carries exclusively the R&D project (FZul1, FZul2, …). Non-R&D work is listed as administration (sphere/category) with purpose —. Every FZul hour belongs to exactly one project (§ 7 FZulG).

FZul reference: Time recording is the basis for FZul hour records (ED29). The separation of R&D vs. administration is done via the Purpose column per time row - not solely via the role field of the entry. The role describes the function of the actor (see below), not the funding allocation.

Recording Is Complete - Capping Only at Settlement

The diary records the actually performed working time completely and without an upper limit - even when it exceeds a funding-law weekly limit (e.g., 40 hours per week and person). Such a limit is a calculation factor in the weekly total and the funding determination, not a limit of the individual time row: No row is capped, shortened, or rebooked merely because a limit would be reached. Complete recording is a prerequisite for the plausibility of the diary and the robustness of the chain of evidence. Regroupings between projects and administration are settlement/projection questions, not corrections to the document.

The Daily Routine: Document First, Posting Later

A diary day has a fixed sequence. Recording (document) and settlement/posting are strictly separated:

Boundary: The FZul/sphere specification in the diary is a document field. It is independent of any certification reservation and generates no posting. The diary is the evidence; posting happens in the ledger, weighting in the projections. The same principle applies to documents: a document provides evidence, the posting comes later and separately.

Roles in the Diary - Person, Function, Party, Execution

The role field is not the person. For a robust understanding of roles, GitCover distinguishes five levels that remain separate even when the same person does everything in one go (typical for SMEs):

One person can have multiple functions and multiple signature acts on the same document - for example, as managing director of two companies. This does not create multiple persons or necessarily multiple accounts or keys. However, roles must not collapse merely because the person or credentials are identical: every signature act binds document version + person + function + represented party + expressly covered consent. A joint inquiry to the person may cover multiple function signatures if the covered functions are expressly named; it does not replace document-related approval. Details: DS03 - Signature Process and DS13 - Participant Layering.

Honest boundary: This separation is described as a requirement and data model. A consistently technically enforced binding of person, function, party, and consent (especially role claims from the identity provider through to the signature events) is the subject of ongoing development and not yet implemented everywhere.

Working with Agents in the Diary

If the entrepreneur uses AI agents, the following applies: control, instruction, monitoring, and validation of the agents are use of work equipment by the acting person - the recorded time is the person's time. The diary has no separate category "agent time" and does not require "overlap" confirmations when activities run in parallel. Instead:

• separate rows per activity/project;
• for activities outside R&D funding (especially tool and agent development) additionally: which actor or agent acted with which effective execution identity - without revealing secrets (tokens, keys).

Eligibility for funding does not arise from the use of agents, but from the question of whether the activity concerns an open technical research question (boundary in the respective project).

What Lands in the Git Repo - and What Does Not

Important: Only structured artifacts (JSON, sidecars, documents, schemas, dictionaries) are admitted into the Git repo. Private documents are never admitted into the repo unless they have been expressly introduced and classified as an artifact. This is a data protection and compliance requirement (GDPR, GoBD).

Risk Leverage

Harness Requirement (Preview)

Derivable from ED03:

The complete requirement list in Harness-Anforderungen.md.

Sources

• RFC 9562 §5.7 (UUIDv7) - 48-bit Unix ms timestamp
• V7GUID specification - work/OSS/TOP/.gitcover/specs/v7guid/ (normative)
• DPMA Az. 10 2025 003 091.6 - V7GUID patent (main claim 2, claims 5–8)
• GitCover OSS tool UuidV7Gen - work/OSS/TOP/tools/UuidV7Gen/ (helper gen/decode)
• GoBD (BMF letter, Rz. 146 - traceability, Rz. 147 - auditability)
• AO (§ 147 Abs. 2 - "machine-evaluable", § 147 Abs. 6 - data access)
• E1/agents/ (anonymized) - SSoT concept with JSON artifacts, sidecars

Source Topology and CDN Reference Links

Note: This assignment of sources, mirror, and community hub reflects the current state and may change. Please check the respective canonical source on gitcover.org for the current state.