{
  "schema_version": "1.0",
  "name": "Meow Serial Parser Extension Policy",
  "purpose": "Tell AI agents how to extend parsing without confusing importable protocol JSON with executable code.",
  "current_runtime": {
    "registered_builtin_parsers": ["raw"],
    "profile_generated_parser_kinds": ["line-values", "json-lines", "tlv"],
    "profile_parser_factory": "src/parsers/profileParserFactory.js",
    "parser_registry": "src/utils/parserRegistry.js"
  },
  "security_boundary": {
    "rule": "Protocol JSON is data, not executable code.",
    "forbidden_in_imported_json": [
      "JavaScript source strings",
      "new Function bodies",
      "eval-compatible expressions",
      "remote code URLs",
      "device commands that should be sent without user intent"
    ],
    "reason": "A protocol profile may be generated by an external AI or imported from a file, so it must stay declarative and safe."
  },
  "preferred_extension_order": [
    {
      "rank": 1,
      "path": "importable-protocol-json",
      "use_when": "The format is line-values, json-lines, or fixed-offset TLV.",
      "ai_action": "Generate one JSON profile matching /ai/protocol-profile.schema.json."
    },
    {
      "rank": 2,
      "path": "embedded-device-normalization",
      "use_when": "The device firmware can be changed more safely than the browser parser.",
      "ai_action": "Generate embedded firmware code that outputs JSON Lines, line-values, or a simple TLV frame that Meow Serial already understands."
    },
    {
      "rank": 3,
      "path": "repo-parser-module",
      "use_when": "The protocol needs checksum validation, byte stuffing, escape decoding, varints, compression, cross-packet state, arrays, matrices, or derived calculations.",
      "ai_action": "Add a reviewed source-code parser module and register it in src/parsers/index.js."
    },
    {
      "rank": 4,
      "path": "future-sandboxed-parser-plugin",
      "use_when": "Users need shareable executable parser logic.",
      "ai_action": "Design a sandboxed plugin format such as WASM plus a manifest. Do not execute raw JavaScript from imported JSON."
    }
  ],
  "embedded_device_parser_code": {
    "supported_direction": "Yes, AI can generate firmware-side parsing or normalization code, but Meow Serial should receive the normalized output as JSON Lines, line-values, or TLV.",
    "recommended_outputs": [
      "JSON Lines: {\"temperature\":23.5,\"humidity\":48.1}",
      "Line values: 23.5,48.1,101.3",
      "Fixed-offset TLV with a stable magic word and numeric payload mappings"
    ],
    "not_recommended": "Do not paste arbitrary embedded or JavaScript parser code into a protocol JSON profile and expect the browser to execute it."
  },
  "tlv_binary_protocol_support": {
    "definition": "TLV means Type-Length-Value. It is a general binary encoding pattern, not a TI-only protocol. TI mmWave serial output commonly uses a TLV-style packet format.",
    "can_parse_when": "Meow Serial can parse a TLV-style binary stream when packets have a stable magic word or fixed header, a readable packet length field, TLV records with readable type and length fields, and numeric values at fixed payload offsets.",
    "ask_user_for": [
      "magicWordHex, if the packet has a sync word",
      "headerSize in bytes",
      "packetLengthOffset, packetLengthType, and packetLengthEndian",
      "tlvCountOffset, tlvCountType, and tlvCountEndian, or say tlvCountOffset = -1 if there is no TLV count field",
      "tlvHeaderSize",
      "tlvTypeOffset and tlvTypeType",
      "tlvLengthOffset and tlvLengthType",
      "tlvHeaderEndian",
      "whether tlvLengthIncludesHeader is true or false",
      "each field label, unit, tlvType, valueOffset inside payload, valueType, endian, and scale",
      "one representative hex frame and the expected decoded values"
    ],
    "common_channel_examples": [
      "breath_rate_bpm",
      "heart_rate_bpm",
      "confidence",
      "phase",
      "amplitude",
      "distance",
      "temperature",
      "x",
      "y",
      "z",
      "velocity"
    ],
    "profile_kind_to_generate": "tlv",
    "cannot_parse_directly_when": [
      "frame validity depends on checksum or CRC that must reject packets",
      "the stream uses byte stuffing or escape decoding before TLV parsing",
      "packet length is not stored as a normal u16/u32 field",
      "payload values are arrays, matrices, compressed data, bitfields, or variable-offset fields",
      "metrics must be calculated across multiple packets rather than read from fixed offsets"
    ],
    "fallbacks": [
      "Ask the user to change firmware output to JSON Lines such as {\"value\":16.8,\"confidence\":0.82}.",
      "Ask the user to change firmware output to simple line-values such as 16.8,0.82.",
      "Add a reviewed browser source-code parser module only if firmware-side normalization is impossible."
    ]
  },
  "cleanup_note": "Legacy unregistered parser files should not be treated as built-in capabilities. The canonical runtime is raw plus profile-generated parsers."
}