Hub schema reference

The Hub is Claresia’s canonical org-memory store. It defines six record types with a versioned schema (cc-050, currently 1.0.0) and SHA-256 canonical-JSON provenance.

The schema is byte-identical across Python and TypeScript — every record written by a Python adapter can be read by a TypeScript adapter with the same provenance hash. Cross-language fixtures (cross_language_fixtures.json) verify this in CI on every commit.

The six record types

Table	Record type	Primary use	Retention
`outputs`	`output`	Skill invocation result body	7 years
`decisions`	`decision`	Captured human-in-the-loop decisions	7 years
`governance_events`	`governance_event`	Privileged actions (auth, RBAC, config, key rotation)	7 years (regulatory)
`artifacts`	`artifact`	Files / blobs produced by a skill (PDF, XLSX, image)	3 years (configurable)
`employee_profiles`	`employee_profile`	Synced from SCIM + cc-061 archetype assignment	Indefinite (purged on offboarding +30 days)
`telemetry_events`	`telemetry_event`	Per-invocation envelope (always written; payload only if mode allows)	13 months

Common fields (all record types)

Field	Type	Description
`record_id`	string (uuid v7)	Globally unique. Sortable by creation time.
`tenant_id`	string	RLS-isolation key.
`record_type`	enum	One of the 6 types above.
`schema_version`	string	e.g., `1.0.0`. Pinnable per tenant.
`created_at`	timestamp (μs)	Write time, monotonic.
`created_by`	string	Actor: `user:<user_id>`, `service:<service_name>`, `system`.
`provenance_hash`	string (base64)	SHA-256 over canonical JSON of all OTHER fields.
`provenance_cosign`	string (base64)	Co-signed by Claresia control plane (binds data plane to control plane without leaking content).

`output` — skill invocation result

{
  "record_id": "01933a8f-...",
  "tenant_id": "dainese",
  "record_type": "output",
  "schema_version": "1.0.0",
  "created_at": "2026-05-03T14:22:18.123456Z",
  "created_by": "user:marco.mazzolin@dainese.it",
  "skill_id": "gatespic.incident-postmortem",
  "skill_version": "1.4.2",
  "archetype_id": "firmware_engineer",
  "input_params": { "incident_id": "INC-2026-04-1873" },
  "output_body": "## Summary\n\nA firmware regression in...",
  "output_format": "markdown",
  "tokens_in": 4823,
  "tokens_out": 1421,
  "cost_usd_estimate": 0.041,
  "latency_ms": 2317,
  "llm_platform": "anthropic-claude-enterprise",
  "llm_model": "claude-sonnet-4.7",
  "related_records": ["01933a8e-..."],
  "provenance_hash": "h7Vw3K...",
  "provenance_cosign": "Mq4z8L..."
}

`decision` — captured HITL decision

{
  "record_id": "01933a91-...",
  "tenant_id": "dainese",
  "record_type": "decision",
  "schema_version": "1.0.0",
  "created_at": "2026-05-03T14:24:00.000000Z",
  "created_by": "user:luigi.bianchi@dainese.it",
  "decision_id": "DEC-2026-04-118",
  "decision_subject": "approve_postmortem",
  "decision_outcome": "approved",
  "decision_rationale": "Root cause analysis is complete and the remediation plan is realistic for the next sprint.",
  "decision_actor_role": "engineering_lead",
  "related_records": ["01933a8f-..."],
  "provenance_hash": "...",
  "provenance_cosign": "..."
}

`governance_event` — privileged action

{
  "record_id": "01933a92-...",
  "tenant_id": "dainese",
  "record_type": "governance_event",
  "schema_version": "1.0.0",
  "created_at": "2026-05-03T09:00:00.000000Z",
  "created_by": "user:it.admin@dainese.it",
  "event_kind": "skill_entitlement_change",
  "event_subject": "archetype:firmware_engineer",
  "event_payload": {
    "added_skills": ["steve.prd-review"],
    "removed_skills": []
  },
  "actor_ip": "203.0.113.42",
  "actor_session_id": "sess_...",
  "outcome": "success",
  "provenance_hash": "...",
  "provenance_cosign": "..."
}

Event kinds (canonical list)

auth.login, auth.logout, auth.failed
tenant.provisioned, tenant.deprovisioned, tenant.config_changed
rbac.role_assigned, rbac.role_revoked, rbac.archetype_overridden
connector.added, connector.credential_rotated, connector.removed
skill.published, skill.unpublished, skill.entitlement_changed
cmek.key_created, cmek.key_rotated, cmek.key_revoked
hub.record_export, hub.record_purged
user.created, user.deactivated, user.archetype_assigned

`artifact` — files / blobs

{
  "record_id": "01933a93-...",
  "tenant_id": "dainese",
  "record_type": "artifact",
  "schema_version": "1.0.0",
  "created_at": "2026-05-03T14:22:20.000000Z",
  "created_by": "service:claresia-gatespic",
  "artifact_id": "artifact-postmortem-INC-2026-04-1873.pdf",
  "artifact_kind": "pdf",
  "artifact_storage_url": "s3://claresia-dainese-artifacts/artifact-...",
  "artifact_byte_size": 184_521,
  "artifact_checksum_sha256": "abc...",
  "related_records": ["01933a8f-..."],
  "provenance_hash": "...",
  "provenance_cosign": "..."
}

`employee_profile` — synced from SCIM

{
  "record_id": "01933a94-...",
  "tenant_id": "dainese",
  "record_type": "employee_profile",
  "schema_version": "1.0.0",
  "created_at": "2026-04-25T10:00:00.000000Z",
  "created_by": "service:claresia-scim-sync",
  "user_id": "user:marco.mazzolin@dainese.it",
  "email": "marco.mazzolin@dainese.it",
  "first_name": "Marco",
  "last_name": "Mazzolin",
  "job_title": "Firmware Engineer",
  "department": "Engineering",
  "manager_user_id": "user:luigi.bianchi@dainese.it",
  "archetype_id": "firmware_engineer",
  "archetype_confidence": 0.992,
  "is_active": true,
  "provenance_hash": "...",
  "provenance_cosign": "..."
}

`telemetry_event` — per-invocation envelope

{
  "record_id": "01933a95-...",
  "tenant_id": "dainese",
  "record_type": "telemetry_event",
  "schema_version": "1.0.0",
  "created_at": "2026-05-03T14:22:18.500000Z",
  "created_by": "service:claresia-telemetry-pull",
  "skill_id": "gatespic.incident-postmortem",
  "skill_version": "1.4.2",
  "archetype_id": "firmware_engineer",
  "user_id": "user:marco.mazzolin@dainese.it",
  "llm_platform": "anthropic-claude-enterprise",
  "llm_model": "claude-sonnet-4.7",
  "success": true,
  "latency_ms": 2317,
  "tokens_in": 4823,
  "tokens_out": 1421,
  "cost_usd_estimate": 0.041,
  "error_code": null,
  "linked_output_id": "01933a8f-...",
  "provenance_hash": "...",
  "provenance_cosign": "..."
}

Canonical JSON form (for provenance)

The SHA-256 provenance hash is computed over canonical JSON:

Sorted keys (lexicographic, UTF-8 byte order)
No whitespace
No trailing commas
null for missing optional fields
Whole-valued floats normalized to ints (1.0 → "1" in JSON, 1 → "1") — this is the cc-050 contract that ensures Python ⇄ TypeScript byte-equality

The provenance hash itself + co-sign are excluded from the canonical form when computing the hash (otherwise it would be circular).

Versioning + migration

Schema is currently 1.0.0
Customers can pin a version per tenant
Breaking changes ship behind a feature flag with 12-month deprecation window
Migration is auto-applied during nightly maintenance window (or manually triggered by IT admin in Command Center)

See GOVERNANCE.md for the full migration runbook.

Querying the Hub

See the Hub API reference for HTTP semantics
See Provenance + Audit for verification of any record
See Storage backends for per-mode storage details
See Retention for per-record-type retention policies

Hub schema reference

The six record types

Common fields (all record types)

output — skill invocation result

decision — captured HITL decision

governance_event — privileged action