ED03 - Formato del 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 revisión
• Exportaciones de software de nómina como PDF: no evaluables automáticamente (§ 147 Abs. 6 AO), no rastreables de forma retrospectiva/progresiva
• Ninguna identidad inequívoca: cada entrada tiene un nombre de archivo, pero el nombre de archivo puede cambiar; la identidad de la entrada no es estable
• Ningún anclaje temporal: la fecha está como string en el documento, pero ¿quién registró realmente y cuándo? El momento de registro no está vinculado criptográficamente con la identidad

Afirmación 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 (hook pre-commit)
2. V7GUID (Class Identifier): clasifica el documento/la acción según el registro .gitcover (qué/qué tipo); sirve para la organización de almacenamiento y la consulta a BD (p. ej. EF Core en Vertical App)
3. uuidV7 (Object ID): ya es por sí solo la identidad inequívoca (DocID) de la entrada, RFC 9562 §5.7, generado a partir de una marca temporal predefinida (o now()) mediante GitCover Helper (gc-v7guid), resto rellenado con aleatoriedad
4. Clave compuesta V7GUID:uuidV7: la clave compuesta del sidecar GCPN, sirve para la organización de almacenamiento y consulta; el momento de registro está en el uuidV7 (timestamp de 48 bits), sin campo datetime/date separado
5. Obligatoriedad de sidecar: cada comprobante recibe un sidecar .gc.md con su propio uuidV7 (acto de clasificación) y el uuidV7 del documento
6. Trazabilidad retrospectiva/progresiva: desde el asiento contable → comprobante → entrada de diario → uuidV7 y de vuelta resoluble

Compliance by Design: El formato no es posterior, es estructural. Esquema, V7GUID (Class), uuidV7 (Object) y sidecar son campos obligatorios; sin ellos una entrada no se admite en el repo.

Sin datetime/date redundante: El momento de registro está anclado en el propio uuidV7 (timestamp de 48 bits, RFC 9562 §5.7). Una representación separada como string en esquemas JSON o datos JSON es redundante y no se incluye en los hechos. La representación como string para transferencia DTO/HTMX es responsabilidad del harness, no del nivel de hechos.

La entrada de diario como nodo de compliance

La entrada técnica no es un fin en sí mismo. Es el nodo temporal en el que convergen varias cadenas de evidencia:

La SSoT del diario dice según qué agenda se trabajó. Los documentos originales, sidecars, GCPN y artefactos de Grundbuch/liquidación aportan los comprobantes correspondientes. Esta separación evita dos errores: una entrada de diario no se malinterpreta como sustituto de un comprobante externo, y un comprobante reunido posteriormente no se presenta falsamente como prueba de trabajo oportuna.

El esquema JSON (Schema-First)

El esquema existe antes de la entrada; se guarda en .gitcover/schemas/diary-entry-1.0.schema.json y está versionado. Una entrada sin referencia de esquema ($schema) es rechazada por el hook pre-commit.

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", "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" } }
  }
}

Importante: sin campo datetime/date: El momento de registro está en el uuidV7 (timestamp de 48 bits, RFC 9562 §5.7). Una representación separada como string es redundante y no se incluye en los hechos. El uuidV7 por sí solo es el DocID inequívoco; la clave compuesta V7GUID:uuidV7 sirve para la organización de almacenamiento y la consulta a BD.

V7GUID: estructura y timestamp de 48 bits

Principio central: El componente de timestamp de 48 bits (bits 0–47) es autoritativo para el momento de registro. Está anclado en el propio uuidV7 y no puede modificarse posteriormente sin invalidar el GUID. No existe un campo datetime separado; el tiempo está en el uuidV7. La representación como string para DTO/HTMX es responsabilidad del harness.

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

La especificación GitCover-V7GUID (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; esa es la extensión protegida por patente (DPMA Az. 10 2025 003 091.6):

Nota: Esta extensión no es estrictamente necesaria para la serie del diario; se vuelve relevante en ED02 (tenant/esfera/rol) y en artículos posteriores (harness). Aquí basta la base RFC 9562 con timestamp de 48 bits.

Rutinas helper: crear V7GUID a partir de claves externas

La herramienta OSS de GitCover gc-v7guid (work/OSS/gc-v7guid) proporciona las operaciones:

gen — generar object IDs UUIDv7

# n Objekt-IDs mit vorgegebener Zeitmarke (nicht now()) und Zufalls-Tail (RFC 9562)
gc-v7guid gen 1 --ts 2026-08-15T09:00:00Z
# Ausgabe: 01a17e18-c662-7874-9e1c-85d47895304f

gen-doc — determinista a partir de metadatos del documento

# Dokumentgebundene ID aus Zeitmarke + SHA-256 des Ur-Dokuments
gc-v7guid gen-doc --ts 2026-08-15T09:00:00Z --doc-sha256 <64-hex>

decode — extraer timestamp y estructura de uuidV7

gc-v7guid decode 019f2c6f-0900-7000-8000-000000000000
# Ausgabe: unix_ms, utc (ISO-8601), version=7, variant=2, rfc9562

Clave externa → uuidV7

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

1. Parsear la clave externa — 260815_0900 → 2026-08-15T09:00:00Z
2. Calcular el timestamp de 48 bits — milisegundos Unix desde epoch
3. Generar uuidV7 — Guid.CreateVersion7() con timestamp explícito, resto con aleatoriedad
4. Clave compuesta — V7GUID (Class del registro) : uuidV7 (Object con marca temporal)
5. Documentación GoBD — registro oportuno anclado de forma trazable (sin campo datetime separado)

Relación con GoBD: El registro oportuno (GoBD Rz. 146) queda documentado criptográficamente mediante el timestamp de 48 bits en el uuidV7, no solo afirmado. El timestamp forma parte de la identidad y no puede modificarse posteriormente.

Estructura del sidecar (.gc.md)

Cada comprobante recibe un sidecar con dos referencias uuidV7:

Ejemplo de sidecar

{
  "$schema": "https://gitcover.org/schemas/v7g-sidecar-2.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
  }
}

Clave compuesta V7GUID:uuidV7:

• V7GUID (campo 1): Class Identifier del sidecar (clasificación del registro .gitcover: qué/qué tipo)
• uuidV7 (campo 2): Object ID del propio sidecar, generado con marca temporal predefinida (¿cuándo se clasificó?), timestamp de 48 bits anclado en el GUID
• v7g_taxonomy[].v7guid: Object ID del documento clasificado (¿qué documento se clasifica?)
• sha256: identidad del documento original clasificado — la prueba de originalidad, siempre y en todas partes (aunque el documento se mueva: independiente de ruta/nombre, calculada a partir del contenido)

Así no solo queda identificado inequívocamente el documento (mediante su SHA-256), sino también el acto de clasificación mismo, incluido el momento (en uuidV7), quién clasificó y en qué rol. Sin campo datetime separado; el tiempo está en los valores uuidV7.

Trazabilidad retrospectiva y progresiva

Relación con GoBD: La trazabilidad retrospectiva corresponde a GoBD Rz. 146 (trazabilidad). La trazabilidad progresiva corresponde a GoBD Rz. 147 (verificabilidad). Ambas están 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:

Regla de columna: La columna Propósito contiene exclusivamente el proyecto de I+D (FZul1, FZul2, …). El trabajo no de I+D figura como Administración (esfera/categoría) con propósito —. Cada hora FZul pertenece exactamente a un proyecto (§ 7 FZulG).

Relación con FZul: El registro de tiempo es la base para los justificantes de horas FZul (ED29). La separación I+D vs. Administración se realiza mediante la columna Propósito por cada línea de tiempo, no solo mediante el campo role de la entrada. El role describe la función de quien actúa (véase abajo), no la asignación de subvención.

El registro es completo; el límite se aplica solo en la liquidación

El diario registra el tiempo de trabajo realmente realizado de forma completa y sin límite superior, incluso cuando supera un límite semanal conforme a la normativa de subvenciones (p. ej., 40 horas por semana y persona). Tal límite es un factor de cálculo en la suma semanal y en la determinación de la subvención, no un límite de la línea de tiempo individual: ninguna línea se recorta, reduce ni reasigna solo porque se hubiera alcanzado un límite. El registro completo es requisito para la plausibilidad del diario y la solidez de la cadena de evidencia. Las reagrupaciones entre proyecto y administración son cuestiones de liquidación/proyección, no correcciones al comprobante.

El transcurso del día: primero el comprobante, después el asiento

Un día de diario tiene un flujo fijo. Registro (comprobante) y liquidación/asiento están estrictamente separados:

Delimitación: La indicación FZul/esfera en el diario es un campo del comprobante. Es independiente de cualquier reserva de certificación y no genera ningún asiento. El diario es la evidencia; se contabiliza en el ledger y se pondera en las proyecciones. El mismo principio se aplica a los comprobantes: un comprobante prueba; el asiento llega después y por separado.

Roles en el diario: persona, función, parte, ejecución

El campo role no es la persona. Para una comprensión robusta de los roles, GitCover distingue cinco niveles que permanecen separados incluso cuando la misma persona hace todo de una vez (típico en pymes):

Una persona puede tener varias funciones y varios actos de firma en el mismo documento, por ejemplo como director gerente de dos sociedades. De ello no surgen varias personas ni necesariamente varias cuentas o claves. Sin embargo, los roles no deben coincidir solo porque la persona o las credenciales sean idénticas: cada acto de firma vincula versión del documento + persona + función + parte representada + consentimiento cubierto expresamente. Una consulta conjunta a la persona puede cubrir varias firmas de función, si las funciones cubiertas se nombran expresamente; no sustituye una aprobación referida al documento. Detalles: DS03 - Procedimiento de firma y DS13 - Estratificación de participantes.

Límite honesto: Esta separación se describe como requisito y modelo de datos. Una vinculación técnicamente forzada de forma integral entre persona, función, parte y consentimiento (especialmente los claims de rol desde el identity provider hasta los eventos de firma) es objeto de desarrollo en curso y aún no está implementada en todas partes.

Trabajo con agentes en el diario

Si el empresario utiliza agentes de IA, se aplica lo siguiente: el control, la instrucción, la supervisión y la validación de los agentes son uso de medios de trabajo por parte de la persona que actúa; el tiempo registrado es el tiempo de la persona. El diario no lleva una categoría propia de «tiempo de agentes» ni exige confirmaciones de «solapamiento» cuando las actividades se ejecutan en paralelo. En su lugar:

• por cada actividad/proyecto, líneas propias;
• en actividades fuera de la financiación de I+D (especialmente desarrollo de herramientas y agentes), además: qué actor o agente actuó con qué identidad de ejecución efectiva, sin revelar secretos (tokens, claves).

La elegibilidad para financiación no resulta del uso de agentes, sino de la cuestión de si la actividad afecta a una pregunta técnica de investigación abierta (delimitación en el proyecto respectivo).

Qué termina en el repo Git y qué no

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

Leverage de riesgo

Requisito del harness (avance)

Derivable de ED03:

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

Fuentes

• RFC 9562 §5.7 (UUIDv7): timestamp 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 GitCover gc-v7guid: work/OSS/gc-v7guid (helper gen/decode)
• GoBD (escrito del BMF, Rz. 146 - trazabilidad, Rz. 147 - verificabilidad)
• AO (§ 147 Abs. 2 - "maschinell auswertbar", § 147 Abs. 6 - Datenzugriff)
• E1/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. Consulte la fuente canónica correspondiente en gitcover.org para conocer el estado actual.