AgentSkillsCN

zireael-abi-formats

保持稳定的 C ABI 与版本化的二进制格式（绘制列表 + 事件批次）。

SKILL.md
--- frontmatter
name: zireael-abi-formats
description: Maintain stable C ABI and versioned binary formats (drawlist + event batches).
metadata:
  short-description: ABI stability + binary formats

When to use

Use this skill when changing:

  • •public engine ABI surface (function signatures, structs)
  • •drawlist binary format
  • •packed event batch format
  • •versioning/negotiation strategy

Source of truth

  • •docs/modules/CONFIG_AND_ABI_VERSIONING.md — ABI and versioning rules
  • •docs/modules/DRAWLIST_FORMAT_AND_PARSER.md — drawlist spec
  • •docs/modules/EVENT_SYSTEM_AND_PACKED_EVENT_ABI.md — event batch spec
  • •docs/ERROR_CODES_CATALOG.md — error code semantics
  • •docs/VERSION_PINS.md — pinned versions

ABI rules (must follow)

  • •Return 0 on success, negative ZR_ERR_* codes on failure
  • •Engine MUST NOT return heap pointers requiring caller free
  • •Caller provides buffers:
    • •drawlist bytes (input)
    • •event batch buffer (output)
    • •user-event payload (engine copies)

Format rules (must follow)

All on-wire formats are:

  • •Little-endian
  • •Versioned (header contains version)
  • •Bounds-checked (no OOB reads, no UB)
  • •Cap-limited (hard caps via zr_limits_t)

Drawlist:

  • •Versioned header with magic, total_size, table offsets
  • •Commands are self-framed: {opcode, size, flags, payload}
  • •Parsing uses safe unaligned reads (memcpy), not casts

Event batches:

  • •Batch header with magic/version/total_size/event_count
  • •Per-record header with type/size/timestamp
  • •Unknown record types skippable by size (forward-compat)

Versioning

Maintain separate version axes:

  • •Engine ABI version
  • •Drawlist format version
  • •Event batch format version

Negotiation at engine_create(config).