Clean up the trace format

package/version

@@ -1 +1 @@
-0.1.85
+0.1.86

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "komet"
-version = "0.1.84"
+version = "0.1.86"
 description = "K tooling for the Soroban platform"
 requires-python = "~=3.10"
 dependencies = [

src/komet/kdist/soroban-semantics/tracing.md

@@ -361,22 +361,27 @@ Their priorities (35, 45) run them ahead of `endWasm-error` (40) and `endWasm` (
       [priority(45)]
 ```
 
-## Trace Format
+## JSON Record Format
 
-Each trace record is a JSON object with four fields:
+Every trace record is a JSON object with a `kind` field identifying its type — `"instr"` for an instruction record, or the operation name for a Soroban VM operation (see `## Soroban VM Tracing` above).
+
+Instruction records (`kind: "instr"`) have four further fields:
 
 - `pos` — the byte offset of the instruction in the binary, or `null` for text format programs.
 - `instr` — a JSON representation of the instruction.
 - `stack` — the current value stack contents.
 - `locals` — the current local variable bindings.
 
+Each Soroban VM operation has its own set of fields, built by its own `generate*Trace` function below; see `docs/tracing.md` for the full format of each.
+
 Records are written one per line to the trace file.
 
 ```k
     syntax JSON ::= generateInstrTrace(Instr, OptionalInt, ValStack, Map)   [function]
  // ---------------------------------------------------------
     rule generateInstrTrace(I:Instr, OFFSET, VS:ValStack, LOCALS:Map)
       => {
+          "kind"   : "instr" ,
           "pos"    : #if OFFSET ==K .Int #then null #else {OFFSET}:>Int #fi ,
           "instr"  : Instr2JSON(I) ,
           "stack"  : ValStack2JSON(VS) ,
@@ -387,27 +392,28 @@ Records are written one per line to the trace file.
  // -------------------------------------------------------------------------
     rule generateHostCallTrace(MOD, FUNC, LOCALS)
       => {
-          "pos"    : null ,
-          "instr"  : [ "hostCall" , MOD , FUNC ] ,
-          "locals" : Locals2JSON(LOCALS)
+          "kind"     : "hostCall" ,
+          "module"   : MOD ,
+          "function" : FUNC ,
+          "locals"   : Locals2JSON(LOCALS)
       }
 
     syntax JSON ::= generateContractDataTrace(ContractId, StorageType, String, List)   [function]
  // --------------------------------------------------------------------------------------------------
     rule generateContractDataTrace(CONTRACT, S_TYPE, OP, ARGS)
       => {
-          "pos"      : null ,
-          "instr"    : ["contractData", OP, StorageType2JSON(S_TYPE)] ,
-          "contract" : Address2JSON(CONTRACT) ,
-          "args"     : [ ScVec2JSONs(ARGS) ]
+          "kind"       : "contractData" ,
+          "operation"  : OP ,
+          "durability" : StorageType2JSON(S_TYPE) ,
+          "contract"   : Address2JSON(CONTRACT) ,
+          "args"       : [ ScVec2JSONs(ARGS) ]
       }
 
     syntax JSON ::= generateAddObjectTrace(ScVal, Int)   [function]
  // ---------------------------------------------------------------
     rule generateAddObjectTrace(SCV, INDEX)
       => {
-          "pos"   : null ,
-          "instr" : ["addObject"] ,
+          "kind"  : "addObject" ,
           "value" : ScVal2JSON(SCV) ,
           "index" : INDEX
       }
@@ -416,8 +422,7 @@ Records are written one per line to the trace file.
  // ---------------------------------------------------------------------------------------------------------------------------------------------------------
     rule generateCallContractTrace(FROM, TO, FUNCNAME, ARGS, DEPTH, INSTANCE, INSTANCE_LIVE_UNTIL, CTRDATA)
       => {
-          "pos"      : null ,
-          "instr"    : ["callContract"] ,
+          "kind"     : "callContract" ,
           "from"     : Address2JSON(FROM) ,
           "to"       : Address2JSON(TO) ,
           "function" : FUNCNAME ,
@@ -479,8 +484,7 @@ Records are written one per line to the trace file.
  // -------------------------------------------------------------------
     rule generateEndWasmTrace(SUCCESS, DEPTH, RESULT)
       => {
-          "pos"     : null ,
-          "instr"   : ["endWasm"] ,
+          "kind"    : "endWasm" ,
           "success" : SUCCESS ,
           "depth"   : DEPTH ,
           "result"  : RESULT

src/tests/integration/test_integration.py

@@ -118,7 +118,7 @@ def test_tracing_consecutive_nop(tmp_path: Path) -> None:
     _krun(input_file=program, definition_dir=TRACING_DEFINITION_DIR, cmap=cmap, pmap=pmap, check=True)
 
     records = [json.loads(line) for line in trace_file.read_text().splitlines()]
-    nop_count = sum(1 for r in records if r['instr'] == ['nop'])
+    nop_count = sum(1 for r in records if r['kind'] == 'instr' and r['instr'] == ['nop'])
     assert nop_count == 2, f'Expected 2 nop entries in trace, got {nop_count}'
 
 
@@ -141,7 +141,7 @@ def test_tracing_double_u256(tmp_path: Path) -> None:
     _krun(input_file=program, definition_dir=TRACING_DEFINITION_DIR, cmap=cmap, pmap=pmap, check=True)
 
     records = [json.loads(line) for line in trace_file.read_text().splitlines()]
-    instrs = [r['instr'] for r in records]
+    instrs = [r['instr'] for r in records if r['kind'] == 'instr']
 
     local_get_0_count = sum(1 for i in instrs if i == ['local.get', 0])
     assert local_get_0_count == 2, f'Expected 2 local.get 0 entries in trace, got {local_get_0_count}'
@@ -164,8 +164,8 @@ def test_tracing_call_contract_and_end_wasm(tmp_path: Path) -> None:
     _krun(input_file=program, definition_dir=TRACING_DEFINITION_DIR, cmap=cmap, pmap=pmap, check=True)
 
     records = [json.loads(line) for line in trace_file.read_text().splitlines()]
-    calls = [r for r in records if r['instr'] == ['callContract']]
-    ends = [r for r in records if r['instr'] == ['endWasm']]
+    calls = [r for r in records if r['kind'] == 'callContract']
+    ends = [r for r in records if r['kind'] == 'endWasm']
 
     assert len(calls) == 2, f'Expected 2 callContract entries, got {len(calls)}'
     assert len(ends) == 2, f'Expected 2 endWasm entries, got {len(ends)}'
@@ -198,7 +198,7 @@ def test_tracing_end_wasm_error(tmp_path: Path) -> None:
     _krun(input_file=program, definition_dir=TRACING_DEFINITION_DIR, cmap=cmap, pmap=pmap, check=True)
 
     records = [json.loads(line) for line in trace_file.read_text().splitlines()]
-    ends = [r for r in records if r['instr'] == ['endWasm']]
+    ends = [r for r in records if r['kind'] == 'endWasm']
 
     assert len(ends) == 4, f'Expected 4 endWasm entries (one per callTx), got {len(ends)}'
     assert [e['success'] for e in ends] == [True, True, False, True]
@@ -223,7 +223,7 @@ def test_tracing_call_contract_storage(tmp_path: Path) -> None:
     _krun(input_file=program, definition_dir=TRACING_DEFINITION_DIR, cmap=cmap, pmap=pmap, check=True)
 
     records = [json.loads(line) for line in trace_file.read_text().splitlines()]
-    calls = [r for r in records if r['instr'] == ['callContract']]
+    calls = [r for r in records if r['kind'] == 'callContract']
     storages = [(c['function'], c['storage']) for c in calls]
 
     expected_entry = {
@@ -246,17 +246,18 @@ def test_tracing_call_contract_storage(tmp_path: Path) -> None:
     contract = calls[0]['to']
     key_arg = {'type': 'symbol', 'value': 'foo'}
     value_arg = {'type': 'u32', 'value': 123456789}
-    contract_data_ops = [r['instr'][1] for r in records if r['instr'][0] == 'contractData']
+    contract_data = [r for r in records if r['kind'] == 'contractData']
+    contract_data_ops = [r['operation'] for r in contract_data]
     assert contract_data_ops == ['put', 'del', 'put'], f'Expected put, del, put in order, got {contract_data_ops}'
 
-    puts = [r for r in records if r['instr'][:2] == ['contractData', 'put']]
-    dels = [r for r in records if r['instr'][:2] == ['contractData', 'del']]
+    puts = [r for r in contract_data if r['operation'] == 'put']
+    dels = [r for r in contract_data if r['operation'] == 'del']
     for put in puts:
-        assert put['instr'][2] == 'temporary'
+        assert put['durability'] == 'temporary'
         assert put['contract'] == contract
         assert put['args'] == [key_arg, value_arg]
     for delete in dels:
-        assert delete['instr'][2] == 'temporary'
+        assert delete['durability'] == 'temporary'
         assert delete['contract'] == contract
         assert delete['args'] == [key_arg]