added source-span plumbing

Author: Zaneham

CHANGELOG.txt

@@ -1,6 +1,40 @@
 CHANGELOG
 =========
 
+2026-05-17  Source-span plumbing
+  - rt_net_t and rt_cell_t gain line and column fields,
+    self-contained so opt and xform passes can read source
+    locations after the AST has long been freed. Eight extra
+    bytes per net and per cell, well within the existing
+    pool budget.
+  - New rt_anet_at and rt_acell_at variants accept source
+    line and column; the untagged rt_anet and rt_acell are
+    now thin wrappers that pass zero, so every existing
+    caller compiles unchanged and gradually migrates as each
+    pass learns to carry provenance forward.
+  - Lowerer updated at six high-value callsites: named
+    identifiers via lw_fnet, port declarations, integer
+    literals, binary operations, unary operations, and
+    ternary expressions. Every cell or net produced by
+    these now remembers where in the source it came from.
+  - tests/tspans.c lands five regression tests under the
+    "spans" category, taking the total to 87. Covers port
+    line numbers, literal line numbers, binary-op line
+    numbers, ternary line numbers, and the strongest
+    property of all: two CONST cells from literals on
+    different source lines must carry different line
+    numbers, so anybody who accidentally hardcodes zero
+    in the future gets caught immediately.
+  - Hash digest unchanged because line and column are
+    deliberately not part of the canonical form. They
+    are provenance, not structure, so cosmetic source
+    reformatting still produces the same fingerprint.
+  - Remaining lowerer callsites still use the untagged
+    variants for now and will migrate as the surrounding
+    code is touched, after which the new fields can feed
+    --annot, span-aware opt-pass propagation, and source
+    pointers in ABEND dumps.
+
 2026-05-16  Cell budget (--budget) plus hash regression suite
   - --budget <n> refuses to emit if the live cell count
     exceeds the limit. Prints a status line either way and

Makefile

@@ -83,7 +83,7 @@ $(TARGET): $(OBJS)
 # Tests
 TEST_SRCS = tests/tmain.c tests/tlex.c tests/tparse.c tests/telab.c \
             tests/trtl.c tests/topt.c tests/tmap.c tests/tvhdl.c \
-            tests/tabel.c tests/thash.c
+            tests/tabel.c tests/thash.c tests/tspans.c
 TEST_TARGET = trunner
 
 ifeq ($(OS),Windows_NT)

include/takahe.h

@@ -524,6 +524,13 @@ typedef struct {
     uint8_t   is_reg;      /* 1=registered (has DFF driver)     */
     uint16_t  gen;         /* generation counter                 */
     uint32_t  driver;      /* cell index that drives this net    */
+    /* Source location of the AST node that produced this net.
+     * Zero means "no provenance" (synthesised by a later pass
+     * or simply not populated yet). Self-contained on purpose:
+     * the AST is freed long before opt/xform/tech run. */
+    uint32_t  line;
+    uint16_t  col;
+    uint16_t  pad;
 } rt_net_t;
 
 /* ---- RTL Cell ---- */
@@ -536,6 +543,13 @@ typedef struct {
     uint32_t   width;      /* operation width                    */
     int64_t    param;      /* cell parameter (const value, etc.) */
     uint16_t   gen;        /* generation counter                 */
+    /* Source location, same contract as rt_net_t. Zero means
+     * the cell was synthesised by a pass that did not preserve
+     * provenance, which is fine for now and will be tightened
+     * pass by pass over time. */
+    uint32_t   line;
+    uint16_t   col;
+    uint16_t   pad;
 } rt_cell_t;
 
 /* ---- RTL Module ---- */
@@ -580,6 +594,15 @@ uint32_t     rt_anet (rt_mod_t *M, const char *name, uint16_t nlen,
                       uint32_t width, uint8_t port, uint8_t radix);
 uint32_t     rt_acell(rt_mod_t *M, rt_ctype_t type, uint32_t out,
                       const uint32_t *ins, uint8_t n_in, uint32_t width);
+/* Source-tagged variants. Same semantics, plus the cell or
+ * net is marked with the AST line/col it came from. The
+ * untagged forms above are thin wrappers that pass zero. */
+uint32_t     rt_anet_at (rt_mod_t *M, const char *name, uint16_t nlen,
+                         uint32_t width, uint8_t port, uint8_t radix,
+                         uint32_t line, uint16_t col);
+uint32_t     rt_acell_at(rt_mod_t *M, rt_ctype_t type, uint32_t out,
+                         const uint32_t *ins, uint8_t n_in, uint32_t width,
+                         uint32_t line, uint16_t col);
 void         rt_dump (const rt_mod_t *M);
 const char  *rt_cname(rt_ctype_t t);
 

src/rtl/tk_lower.c

@@ -109,6 +109,26 @@ lw_width(const lw_ctx_t *C, uint32_t nidx)
     return 1;  /* default 1-bit */
 }
 
+/* ---- Source location pull from an AST node ----
+ * Used at the rt_*_at callsites so newly created nets and
+ * cells remember where in the user's source they came from.
+ * Out-of-range or sentinel nidx yields zero, which downstream
+ * code treats as "no provenance," same as the untagged path. */
+
+static uint32_t
+lw_line(const lw_ctx_t *C, uint32_t nidx)
+{
+    if (nidx == 0 || nidx >= C->P->n_node) return 0;
+    return C->P->nodes[nidx].line;
+}
+
+static uint16_t
+lw_col(const lw_ctx_t *C, uint32_t nidx)
+{
+    if (nidx == 0 || nidx >= C->P->n_node) return 0;
+    return (uint16_t)C->P->nodes[nidx].col;
+}
+
 /* ---- ceil(log2(n)) — address bits for n elements ---- */
 
 static uint32_t
@@ -240,7 +260,8 @@ lw_fnet(lw_ctx_t *C, uint32_t ast_id)
     }
 
     /* Create new net */
-    ni = rt_anet(C->M, nm, nlen, w, 0, C->radix);
+    ni = rt_anet_at(C->M, nm, nlen, w, 0, C->radix,
+                    lw_line(C, ast_id), lw_col(C, ast_id));
     C->nmap[ast_id] = ni;
     return ni;
 }
@@ -271,8 +292,10 @@ lw_expr(lw_ctx_t *C, uint32_t nidx)
             val = C->cv[nidx].val;
             if (C->cv[nidx].width > 0) cw = C->cv[nidx].width;
         }
-        onet = rt_anet(C->M, "const", 5, cw, 0, C->radix);
-        ci = rt_acell(C->M, RT_CONST, onet, NULL, 0, cw);
+        onet = rt_anet_at(C->M, "const", 5, cw, 0, C->radix,
+                          lw_line(C, nidx), lw_col(C, nidx));
+        ci = rt_acell_at(C->M, RT_CONST, onet, NULL, 0, cw,
+                         lw_line(C, nidx), lw_col(C, nidx));
         if (ci > 0 && ci < C->M->n_cell)
             C->M->cells[ci].param = val;
         return onet;
@@ -329,9 +352,11 @@ lw_expr(lw_ctx_t *C, uint32_t nidx)
             ow = lw > rw ? lw : rw;
         }
 
-        onet = rt_anet(C->M, "tmp", 3, ow, 0, C->radix);
+        onet = rt_anet_at(C->M, "tmp", 3, ow, 0, C->radix,
+                          lw_line(C, nidx), lw_col(C, nidx));
         ins[0] = l; ins[1] = r;
-        rt_acell(C->M, ct, onet, ins, 2, ow);
+        rt_acell_at(C->M, ct, onet, ins, 2, ow,
+                    lw_line(C, nidx), lw_col(C, nidx));
         return onet;
     }
 
@@ -352,16 +377,20 @@ lw_expr(lw_ctx_t *C, uint32_t nidx)
             /* Bitwise NOT: same width as operand */
             uint32_t ow = operand < C->M->n_net ?
                 C->M->nets[operand].width : 1;
-            uint32_t onet = rt_anet(C->M, "tmp", 3, ow, 0, C->radix);
+            uint32_t onet = rt_anet_at(C->M, "tmp", 3, ow, 0, C->radix,
+                                       lw_line(C, nidx), lw_col(C, nidx));
             uint32_t ins[1] = { operand };
-            rt_acell(C->M, RT_NOT, onet, ins, 1, ow);
+            rt_acell_at(C->M, RT_NOT, onet, ins, 1, ow,
+                        lw_line(C, nidx), lw_col(C, nidx));
             return onet;
         }
         if (strcmp(op, "!") == 0) {
             /* Logical NOT: always 1-bit */
-            uint32_t onet = rt_anet(C->M, "tmp", 3, 1, 0, C->radix);
+            uint32_t onet = rt_anet_at(C->M, "tmp", 3, 1, 0, C->radix,
+                                       lw_line(C, nidx), lw_col(C, nidx));
             uint32_t ins[1] = { operand };
-            rt_acell(C->M, RT_NOT, onet, ins, 1, 1);
+            rt_acell_at(C->M, RT_NOT, onet, ins, 1, 1,
+                        lw_line(C, nidx), lw_col(C, nidx));
             return onet;
         }
         return operand;  /* +a is just a */
@@ -535,9 +564,11 @@ lw_expr(lw_ctx_t *C, uint32_t nidx)
         dw0 = d0 < C->M->n_net ? C->M->nets[d0].width : 1;
         ow = dw1 > dw0 ? dw1 : dw0;
 
-        onet = rt_anet(C->M, "tmp", 3, ow, 0, C->radix);
+        onet = rt_anet_at(C->M, "tmp", 3, ow, 0, C->radix,
+                          lw_line(C, nidx), lw_col(C, nidx));
         ins[0] = sel; ins[1] = d0; ins[2] = d1;
-        rt_acell(C->M, RT_MUX, onet, ins, 3, ow);
+        rt_acell_at(C->M, RT_MUX, onet, ins, 3, ow,
+                    lw_line(C, nidx), lw_col(C, nidx));
         return onet;
     }
 
@@ -1455,9 +1486,10 @@ lw_mod(lw_ctx_t *C, uint32_t mod_node)
             }
 
             if (name_n) {
-                uint32_t ni = rt_anet(C->M,
+                uint32_t ni = rt_anet_at(C->M,
                     lw_text(C, name_n), lw_tlen(C, name_n),
-                    w, dir, C->radix);
+                    w, dir, C->radix,
+                    lw_line(C, c), lw_col(C, c));
                 C->nmap[name_n] = ni;
             }
             break;

src/rtl/tk_rtl.c

@@ -98,11 +98,15 @@ rt_sint(rt_mod_t *M, const char *s, uint16_t len)
     return off;
 }
 
-/* ---- Add net ---- */
+/* ---- Add net (source-tagged) ----
+ * The real function. Untagged rt_anet below is the thin
+ * wrapper that passes zero, which is fine for callers that
+ * have nothing to say about provenance. */
 
 uint32_t
-rt_anet(rt_mod_t *M, const char *name, uint16_t nlen,
-        uint32_t width, uint8_t port, uint8_t radix)
+rt_anet_at(rt_mod_t *M, const char *name, uint16_t nlen,
+           uint32_t width, uint8_t port, uint8_t radix,
+           uint32_t line, uint16_t col)
 {
     uint32_t idx;
     rt_net_t *n;
@@ -118,15 +122,25 @@ rt_anet(rt_mod_t *M, const char *name, uint16_t nlen,
     n->is_port  = port;
     n->radix    = radix ? radix : TK_RADIX_BIN;
     n->gen      = 1;
+    n->line     = line;
+    n->col      = col;
 
     return idx;
 }
 
-/* ---- Add cell ---- */
+uint32_t
+rt_anet(rt_mod_t *M, const char *name, uint16_t nlen,
+        uint32_t width, uint8_t port, uint8_t radix)
+{
+    return rt_anet_at(M, name, nlen, width, port, radix, 0, 0);
+}
+
+/* ---- Add cell (source-tagged) ---- */
 
 uint32_t
-rt_acell(rt_mod_t *M, rt_ctype_t type, uint32_t out,
-         const uint32_t *ins, uint8_t n_in, uint32_t width)
+rt_acell_at(rt_mod_t *M, rt_ctype_t type, uint32_t out,
+            const uint32_t *ins, uint8_t n_in, uint32_t width,
+            uint32_t line, uint16_t col)
 {
     uint32_t idx;
     rt_cell_t *c;
@@ -142,6 +156,8 @@ rt_acell(rt_mod_t *M, rt_ctype_t type, uint32_t out,
     c->n_in  = n_in > RT_MAX_PIN ? RT_MAX_PIN : n_in;
     c->width = width;
     c->gen   = 1;
+    c->line  = line;
+    c->col   = col;
 
     for (i = 0; i < c->n_in; i++)
         c->ins[i] = ins[i];
@@ -153,6 +169,13 @@ rt_acell(rt_mod_t *M, rt_ctype_t type, uint32_t out,
     return idx;
 }
 
+uint32_t
+rt_acell(rt_mod_t *M, rt_ctype_t type, uint32_t out,
+         const uint32_t *ins, uint8_t n_in, uint32_t width)
+{
+    return rt_acell_at(M, type, out, ins, n_in, width, 0, 0);
+}
+
 /* ---- Dump RTL for debugging ---- */
 
 void