`system-protobuf-extract` (platform, system-utils)

Platform reserved. Decodes HEAT capture DataPacket / DataPacketBundle trees from a parent input-node and emits scoped JSON records. Subset of hydrate-protobuf-v2 targets without requiring core-utils, including the same projection filters where applicable.

Parent: single input-node.

Configuration

Property	Required	Default	Description
`extractionTarget`	Yes	—	`EntityDataEvent`, `EntityState`, `SimulationFrame`, or `TrackingEvent`
`outputFormat`	No	`json`	Only `json` supported
`lineDelimitedJson`	No	`false`	One record per line; forced `true` when `incrementalHydration` is on
`incrementalHydration`	No	`false`	Append new parent outputs using watermark
`enableUploadDeduplication`	No	`false`	Skip upload when md5 matches prior output
`readWindowBytes`	No	`8388608`	Bounded read per parent blob
`batchSize`	No	`100`	Max parent outputs per run
`timeBudgetSeconds`	No	`300`	Cooperative time budget
`filterOriginUuid`	No	—	Emit only records from this `origin_uuid`
`filterOriginIndex`	No	—	Emit only records for `captureIdentity.origins[index]`
`filterEntityId`	No	—	Emit only records for this simulation entity id
`filterEntityIndex`	No	—	Emit only records for `captureIdentity.entities[index]` (lane)
`filterEntityName`	No	—	Exact entity name match (case-sensitive)
`entityNameRegex`	No	—	Fullmatch regex on entity name (EntityState; events use registry name when known)
`includeComponentTypes`	No	—	Allow-list of `Component` oneof arms (EntityState / SimulationFrame)
`excludeComponentTypes`	No	—	Deny-list of component oneof arms (mutually exclusive with include)
`dropEmptyEntities`	No	`true`	Drop entities with zero components after projection
`includeDataEventTypes`	No	—	Allow-list of `EntityDataEvent` `event_data` oneof arms
`includeTrackingEventTypes`	No	—	Allow-list of `TrackingEventType` enum names
`updateSessionCaptureIdentity`	No	smart default	Merge observed origins/entities into session `captureIdentity`. Default `true` without index filters; default `false` when `filterOriginIndex` or `filterEntityIndex` is set

Output shape

Wrapped JSON (default):


{
  "records": [
    {
      "parent_output_id": 1,
      "origin_uuid": "…",
      "origin_index": 0,
      "entity_id": 42,
      "entity_name": "Pilot-1",
      "entity_index": 0,
      "extraction_target": "EntityDataEvent"
    }
  ]
}

NDJSON when lineDelimitedJson: true (required for incremental append).

Capture identity and lanes

For multi-user SIM templates, use one registry extract node plus parallel lane nodes. See Capture identity lanes.


{
  "extractionTarget": "EntityDataEvent",
  "filterEntityIndex": 0,
  "updateSessionCaptureIdentity": false,
  "lineDelimitedJson": true,
  "incrementalHydration": true
}

Domain tree example (world position only):


{
  "extractionTarget": "EntityState",
  "includeComponentTypes": ["world_position", "dynamics"],
  "entityNameRegex": "^(Blue|Red)-.*",
  "dropEmptyEntities": true
}

Authoring guidance

Prefer EntityDataEvent or TrackingEvent over SimulationFrame when possible.
Use component projection on EntityState to avoid oversized artefacts.
Run parallel branches per target or per lane instead of one deep hydrate chain.
Pair with system-arbex-js and heat-system-next-dimension for dashboards.

When core-utils is available, hydrate-protobuf-v2 remains an alternative with CSV output and merge ecosystem.

Shipped preset

heat-capture-mainline-scoped: discovery leaf, identity registry, two entity-index lanes, and scoped mainline. See Capture session templates.

system-protobuf-extract (platform, system-utils)