trust-graph.md

Trust Graph v2 Contract

Renma emits only renma.trustGraph.v2, the first supported long-term Trust Graph contract. There is no v1 compatibility mode. The authoritative machine-readable definition is the Trust Graph v2 JSON Schema.

The User Manual's authoritative metadata reference defines which declarations feed Trust Graph projections. This document owns node, edge, evidence, ordering, and schema semantics rather than a separate metadata field inventory.

The required top-level fields are schemaVersion, summary, nodes, edges, and findings. Node properties and node and edge evidence are optional. Edge properties are optional except where an edge-specific provenance rule requires them. Finding identity fields (code, id, title, riskClass, path, and evidence) appear only when supplied. Missing optional fields are omitted, not serialized as null.

Nodes are ordered by type and stable ID; edges by source, type, target, and ID; findings by deterministic review order. Summary maps contain all enum members with non-negative integer counts. Asset nodes include normalized ownership and first-class support evidence.

Asset node properties additively expose current lifecycle statusReason and statusChangedAt when declared. has_lifecycle_status edge properties expose the same current evidence next to status, and suspended is a supported lifecycle value. revoked is also a first-class value and remains distinct from suspension, deprecation, and archival. The shared lifecycle-status node remains keyed only by the status value; reason and changed date are asset-specific transition evidence. These optional properties do not change renma.trustGraph.v2, do not encode history or runtime use, and do not alter security riskClass semantics. Static support uses owns_local_resource, statically_references, inherits_owner, and inherits_policy. Every owned_by edge declares ownershipSource; when its value is inherited, the edge also retains an inheritedFrom object with the owning asset ID and source path. Every has_effective_policy edge has a non-empty, duplicate-free policySources array. Its values are limited to local, security_profile, repository_config, and owning_skill, in that generated order. Effective policy inherited from an owning Skill retains inheritedFrom.

Representative complete top-level document:

{
  "schemaVersion": "renma.trustGraph.v2",
  "summary": {
    "assetCount": 0, "nodeCount": 0, "edgeCount": 0, "findingCount": 0,
    "nodeTypeCounts": { "asset": 0, "owner": 0, "lifecycle_status": 0, "security_profile": 0, "effective_policy": 0, "diagnostic": 0 },
    "edgeTypeCounts": { "owned_by": 0, "has_lifecycle_status": 0, "declares_dependency": 0, "references": 0, "owns_local_resource": 0, "statically_references": 0, "inherits_owner": 0, "selects_security_profile": 0, "inherits_policy": 0, "has_effective_policy": 0, "has_diagnostic": 0 },
    "findingSeverityCounts": { "critical": 0, "high": 0, "medium": 0, "low": 0, "error": 0, "warning": 0, "info": 0 },
    "riskClassCounts": { "violation": 0, "suspicious": 0, "advisory": 0, "unclassified": 0 }
  },
  "nodes": [],
  "edges": [],
  "findings": []
}

Within v2, evolution is additive and backward-compatible. Removing or changing an existing field requires a new schema version. Enum additions are consumer-visible and must be documented.