Asset Inventory Sync v1 Contract

Contract ID: CONTRACT-ASSET-INVENTORY-SYNC-V1-071  ·  Schema: asset-inventory-sync.v1  ·  Status: Published  ·  Owner: Graph Indexer Guild  ·  Last updated: 2026-04-30

Purpose

asset-inventory-sync.v1 is the local-only delta bundle used to move Graph Asset Registry events between offline or federated StellaOps tenants. The bundle does not define new asset semantics: it carries existing asset-registry.v1append-only events, preserving their payload hashes, Merkle leaf hashes, event hashes, tombstones, and per-asset previous_event_hash chains.

The contract exists so an offline tenant can receive a deterministic bundle, verify it without external services, and append the events to its local Graph Indexer asset event store.

Audience: Graph Indexer implementers and operators moving asset inventory between air-gapped or federated tenants.

Schema Pinning

• Schema version is pinned to asset-inventory-sync.v1 (AssetInventorySyncV1.SchemaVersion).
• Bundle media type is application/vnd.stellaops.asset-inventory-sync.v1+json (AssetInventorySyncV1.MediaType). Bundle id prefix is asset-inventory-sync: (AssetInventorySyncV1.BundleIdPrefix).
• Asset payloads inside the bundle remain asset-registry.v1.
• Runtime codec, bundle, applier, and constants: src/Graph/StellaOps.Graph.Indexer/Assets/AssetInventorySyncEnvelope.cs (AssetInventorySyncV1, AssetInventorySyncBundle, AssetInventorySyncEvent, AssetInventorySyncApplier, AssetInventorySyncApplyResult).
• Underlying asset event types and hash recipe: src/Graph/StellaOps.Graph.Indexer/Assets/AssetRegistryDocuments.cs (AssetRegistryEvent.Create) and src/Graph/StellaOps.Graph.Indexer/Assets/AssetRegistryV1.cs.
• Determinism and replay tests: src/Graph/__Tests/StellaOps.Graph.Indexer.Tests/AssetInventorySyncEnvelopeTests.cs.
• This v1 contract is self-contained in repo docs and Graph Indexer code. It does not fetch live schemas or regulator references.
• Breaking changes require a new contract version and must not change v1 hash recipes.

Envelope Shape

Top-level fields:

Event entry fields:

Example:

{
  "schema_version": "asset-inventory-sync.v1",
  "tenant_id": "tenant-a",
  "producer_id": "graph-indexer",
  "generated_at": "2026-04-30T11:00:00Z",
  "since_event_hash": null,
  "previous_bundle_hash": null,
  "event_count": 1,
  "events": [
    {
      "event_id": "asset-event:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "tenant_id": "tenant-a",
      "asset_id": "gn:tenant-a:asset:EXAMPLE",
      "asset_type": "service",
      "event_type": "asset.created",
      "payload": {
        "attributes": {
          "asset_id": "gn:tenant-a:asset:EXAMPLE",
          "schema_version": "asset-registry.v1",
          "tenant_id": "tenant-a",
          "type": "service",
          "tombstone": false
        },
        "id": "gn:tenant-a:asset:EXAMPLE",
        "kind": "asset",
        "tenant": "tenant-a"
      },
      "payload_hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "previous_event_hash": null,
      "merkle_leaf_hash": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "event_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "occurred_at": "2026-04-30T09:00:00Z"
    }
  ],
  "bundle_id": "asset-inventory-sync:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
  "bundle_hash": "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
}

The example illustrates field names only; its hash values are placeholders and the payload is abbreviated. A real asset-registry.v1 asset node carries the full Graph document shape produced by AssetGraphDocumentFactory.CreateAssetNode — top-level tenant, kind, canonical_key, attributes, provenance, valid_from, valid_to, id, and hash, where attributes includes schema_version, asset_id, tenant_id, type, source, external_id, criticality, ownership, depends_on, asset_attributes, first_seen, last_seen, and tombstone. Real event hashes must be recomputed from the canonical payload and metadata.

Canonicalization And Hashing

• JSON canonicalization uses the Graph Indexer canonical JSON writer: ordinal sorted object keys, deterministic arrays, UTF-8, and no extra whitespace.
• bundle_hash is computed over the canonical top-level envelope without bundle_id and bundle_hash.
• bundle_id is derived from bundle_hash and is not independently chosen.
• Event entries reuse the Asset Registry event hash recipe. Importers reconstruct each event with the AssetRegistryEvent.Create(...) path and require event_id, tenant_id, asset_id, asset_type, event_type, payload_hash, previous_event_hash, merkle_leaf_hash, event_hash, and occurred_at to match. Any divergence raises an integrity failure (EnsureSameAssetEvent).
• The reused recipe is (see AssetRegistryEvent.Create):
  • payload_hash = lowercase-hex SHA-256 of the canonical payload JSON.
  • merkle_leaf_hash = lowercase-hex SHA-256 of the literal string asset-registry.v1\nasset-event\n<payload_hash>.
  • event_id = asset-event:<event_hash>.
  • event_hash = lowercase-hex SHA-256 of the canonical “event seed” object { schema_version, tenant_id, asset_id, asset_type, event_type, payload_hash, previous_event_hash, merkle_leaf_hash, occurred_at }.
• Event order is part of the contract. Producers must order by occurred_at ASC, event_hash ASC; consumers reject non-canonical order.

Apply Semantics

The applier (AssetInventorySyncApplier.ApplyAsync) takes a parsed bundle (or raw JSON) plus an IAssetRegistryEventStore and returns an AssetInventorySyncApplyResult (bundle_id, bundle_hash, appended-event count, skipped-event count, the applied events, and the resulting current asset states, each carrying its latest event_hash, payload_hash, and tombstone flag). The store is the local append-only asset event log; the production implementation is PostgresAssetRegistryEventStore, backed by the asset_registry_events table (Graph Indexer persistence migration 003_asset_registry_events.sql).

Consumers apply a bundle as follows:

1. Parse the envelope and reject unknown top-level or event fields.
2. Verify schema_version, event_count, bundle_hash, and bundle_id.
3. Verify every event by reconstructing the existing Asset Registry event hash material from the included payload.
4. Verify all events match the envelope tenant_id.
5. Verify there are no duplicate event_id values.
6. Verify in-bundle chains for repeated assets: each later event for the same asset_id must point to the prior in-bundle event_hash.
7. For each new event, read the local chain for that asset_id. Append only when previous_event_hash equals the local latest event hash. If the event hash already exists locally, skip it as an idempotent replay.
8. Reject the bundle if a new event references a predecessor that is neither local nor earlier in the bundle.

The result is deterministic because the same local chain plus the same bundle produces the same appended event ids and current asset states.

Privacy And Security

• The bundle must not dereference credentials, secrets, human actors, email addresses, or names. It preserves the asset-registry.v1 opaque-reference boundary.
• Secret and PII handling remains enforced by the Asset Registry payload factory. Sync importers must not add expansion fields while replaying.
• The v1 bundle is unsigned by itself. Signer or EvidenceLocker may wrap the canonical bundle bytes later; this contract defines the canonical payload they would sign.

Out Of Scope

• Production Scanner, Integrations, Signals, and plugin-host subscriptions.
• Live Graph API export endpoints.
• Cross-module Findings Ledger projection.
• External schema downloads or SaaS validation.
• Automatic regulator or third-party submission.

Those integrations can consume this bundle format later without changing the v1 canonicalization or event-chain rules.

Offline Replay Expectations

• All code and tests run from in-repo assets only.
• A receiving tenant can apply the bundle with only local Graph Indexer code and its local asset event store.
• Replaying the same bundle again is idempotent: existing event hashes are skipped, not duplicated.
• Missing predecessor events fail closed so inventory history cannot fork or silently skip lineage.