ED03 - Formato de diario: artefactos JSON, firma temporal, V7GUID, sidecars

Problema

Un empresario quiere llevar su diario en Git - pero ¿cómo se ve exactamente una entrada a nivel técnico? La práctica actual no conoce una respuesta vinculante:

• Notas de texto libre en Markdown, Word o papel - no legibles por máquina, no validadas contra esquema, no trazables
• Filas de Excel con fecha, actividad, horas - no versionadas, no ancladas criptográficamente, no a prueba de auditoría
• Exportaciones de software de nómina como PDF - no evaluables por máquina (§ 147 Abs. 6 AO), no rastreables de forma retrógrada/progresiva
• Sin identidad única - cada entrada tiene un nombre de archivo, pero el nombre de archivo puede cambiar; la identidad de la entrada no es estable
• Sin anclaje temporal - la fecha figura como String en el documento, pero ¿quién registró realmente cuándo? El tiempo de registro no está vinculado criptográficamente con la identidad

Idea central

Una entrada de diario de GitCover es un artefacto JSON con:

1. JSON-Schema-First - el esquema existe antes de la entrada; la entrada se valida contra el esquema (Pre-Commit-Hook)
2. V7GUID (Class Identifier) - clasifica el documento/la Action según la Registry .gitcover (qué/qué tipo); sirve para la organización de archivado y las consultas a la DB (p. ej., EF Core en Vertical App)
3. uuidV7 (Object ID) - ya es por sí sola la identidad única (DocID) de la entrada, RFC 9562 §5.7, generada a partir de una marca de tiempo predefinida (o now()) vía helper de GitCover (UuidV7Gen), el resto se rellena con aleatoriedad
4. Composite Key V7GUID:uuidV7 - la clave compuesta del sidecar GCPN, sirve para la organización de archivado y las consultas; el tiempo de registro está contenido en la uuidV7 (marca de tiempo de 48 bits), sin campo datetime/date separado
5. Obligación de sidecar - cada comprobante recibe un sidecar .v7g.md con su propia uuidV7 (acto de clasificación) y la uuidV7 del documento
6. Trazabilidad retrógrada/progresiva - desde el asiento contable → comprobante → entrada de diario → uuidV7 y de vuelta, todo resoluble

Compliance by Design: el formato no se añade a posteriori - es estructural. El esquema, el V7GUID (Class), el uuidV7 (Object) y el sidecar son campos obligatorios sin los cuales una entrada no se incorpora al repo.

Sin datetime/date redundante: el tiempo de registro está anclado en la propia uuidV7 (marca de tiempo de 48 bits, RFC 9562 §5.7). Una representación String separada en esquemas JSON o datos JSON es redundante y no se mantiene en los hechos. La representación String para la transferencia DTO/HTMX es responsabilidad del Harness, no de la capa de hechos.

El esquema JSON (Schema-First)

El esquema existe antes de la entrada - se almacena en .gitcover/schemas/diary-entry-1.0.schema.json y está versionado. Una entrada sin referencia de esquema ($schema) es rechazada por el Pre-Commit-Hook.

Esquema diary-entry-1.0.schema.json (simplificado)

{
  "$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", "uuidV7",
    "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)"
    },
    "uuidV7": {
      "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" } }
  }
}

Importante - sin campo datetime/date: el tiempo de registro está contenido en la uuidV7 (marca de tiempo de 48 bits, RFC 9562 §5.7). Una representación String separada es redundante y no se mantiene en los hechos. La uuidV7 por sí sola es la DocID única; el Composite Key V7GUID:uuidV7 sirve para la organización de archivado y las consultas a la DB.

V7GUID - Estructura y marca de tiempo de 48 bits

Principio central: el componente de marca de tiempo de 48 bits (bits 0–47) es autoritativo para el tiempo de registro. Está anclado en la propia uuidV7 y no puede modificarse a posteriori sin invalidar la GUID. Un campo datetime separado no existe - el tiempo está contenido en la uuidV7. La representación String para DTO/HTMX es responsabilidad del Harness.

Extensión de GitCover: jerarquía e IDs de proceso en los bits 66–127

La especificación V7GUID de GitCover (work/OSS/TOP/.gitcover/specs/v7guid/) amplía el componente aleatorio de 62 bits (bits 66–127) con una jerarquía de 6 niveles e IDs de proceso - esta es la extensión protegida por patente (DPMA Az. 10 2025 003 091.6):

Nota: esta extensión no es imprescindible para la serie del diario - cobra relevancia en ED02 (Tenant/esfera/rol) y en artículos posteriores (Harness). Aquí basta la base RFC 9562 con marca de tiempo de 48 bits.

Rutinas helper: crear V7GUID a partir de claves externas

La herramienta OSS de GitCover UuidV7Gen (work/OSS/TOP/tools/UuidV7Gen/) proporciona dos operaciones centrales:

gen - generar 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 - extraer la marca de tiempo de la 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

Clave externa → uuidV7

Las rutinas helper permiten crear una clave uuidV7 válida a partir de una clave externa (p. ej., una marca de tiempo en el nombre de archivo como 260815_0900_Lohnabrechnung.pdf) - con marca de tiempo predefinida, no now():

1. Analizar la clave externa - 260815_0900 → 2026-08-15T09:00:00Z
2. Calcular la marca de tiempo de 48 bits - milisegundos Unix desde la época
3. Generar la uuidV7 - Guid.CreateVersion7() con marca de tiempo explícita, el resto con aleatoriedad
4. Composite Key - V7GUID (Class de la Registry) : uuidV7 (Object con marca de tiempo)
5. Documentación GoBD - registro inmediato anclado de forma trazable (sin campo datetime separado)

Referencia GoBD: el registro inmediato (GoBD Rz. 146) queda documentado criptográficamente mediante la marca de tiempo de 48 bits en la uuidV7 - no solo afirmado. La marca de tiempo es parte de la identidad, no modificable a posteriori.

Estructura del sidecar (.v7g.md)

Cada comprobante recibe un sidecar con dos referencias uuidV7:

Ejemplo de sidecar

{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-1.0.schema.json",
  "V7GUID": "<V7GUID-Class-aus-Registry>",
  "uuidV7": "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 (campo 1) - Class Identifier del sidecar (clasificación según la Registry .gitcover: qué/qué tipo)
• uuidV7 (campo 2) - Object ID del propio sidecar, generada con marca de tiempo predefinida (¿cuándo se clasificó?), marca de tiempo de 48 bits anclada en la GUID
• v7g_taxonomy[].v7guid - Object ID del documento clasificado (¿qué documento se clasifica?)

Así no solo el documento queda identificado de forma única, sino también el acto de clasificación en sí - incluido el momento (en la uuidV7), quién clasificó y en qué rol. Sin campo datetime separado - el tiempo está contenido en los valores uuidV7.

Trazabilidad retrógrada y progresiva

Referencia GoBD: la trazabilidad retrógrada corresponde a GoBD Rz. 146 (trazabilidad). La trazabilidad progresiva corresponde a GoBD Rz. 147 (verificabilidad). Ambas quedan garantizadas by Design mediante uuidV7 + SHA-256

• no mediante referencias cruzadas manuales.

Registro de tiempo en el diario

Cada entrada de diario contiene una tabla de registro de tiempo:

Referencia FZul: el registro de tiempo es la base de los justificantes de horas FZul (ED28). La separación I+D vs. administración se realiza mediante el campo role (F&E-Leiter vs. GF) y las tags (["fzul", "forschung"] vs. ["verwaltung"]).

Qué acaba en el repositorio Git - y qué no

Importante: solo los artefactos estructurados (JSON, sidecars, comprobantes, esquemas, diccionarios) se incorporan al repositorio Git. Los documentos privados se incorporan nunca al repo, salvo que se hayan introducido y clasificado explícitamente como artefacto. Es un requisito de protección de datos y de cumplimiento (RGPD, GoBD).

Apalancamiento de riesgo

Requisitos del Harness (vista previa)

Se puede deducir de ED03:

La lista completa de requisitos en Harness-Anforderungen.md.

Fuentes

• RFC 9562 §5.7 (UUIDv7) - marca de tiempo Unix-ms de 48 bits
• Especificación V7GUID - work/OSS/TOP/.gitcover/specs/v7guid/ (normativa)
• DPMA Az. 10 2025 003 091.6 - patente V7GUID (reivindicación principal 2, reivindicaciones 5–8)
• Herramienta OSS de GitCover UuidV7Gen - work/OSS/TOP/tools/UuidV7Gen/ (helpers gen/decode)
• GoBD (escrito del BMF, Rz. 146 - trazabilidad, Rz. 147 - verificabilidad)
• AO (§ 147 Abs. 2 - "evaluable por máquina", § 147 Abs. 6 - acceso a datos)
• AFJD/agents/ (anonimizado) - concepto SSoT con artefactos JSON, sidecars

Topología de fuentes y enlaces de referencia CDN

Nota: esta asignación de fuentes, mirror y community hub refleja el estado actual y puede cambiar. Por favor, compruebe la fuente canónica correspondiente en gitcover.org para conocer el estado actual.