usage: ast-lake [command] [args...]
\n\n"},{"id":"/root/children/1/children/0","type":"text","loc":{"start":116,"end":124,"line":{"s":3,"e":3,"code":["# ast-lake"]},"column":{"s":2,"e":10}},"dim":["","heading.1","text.0"],"code":"ast-lake"},{"id":"/root/children/2","type":"paragraph","loc":{"start":126,"end":161,"line":{"s":5,"e":5,"code":["usage: ast-lake [command] [args...]"]},"column":{"s":0,"e":35}},"dim":["","paragraph.2"],"code":"usage: ast-lake [command] [args...]"},{"id":"/root/children/2/children/0","type":"text","loc":{"start":126,"end":161,"line":{"s":5,"e":5,"code":["usage: ast-lake [command] [args...]"]},"column":{"s":0,"e":35}},"dim":["","paragraph.2","text.0"],"code":"usage: ast-lake [command] [args...]"},{"id":"/root/children/3","type":"list","loc":{"start":163,"end":211,"line":{"s":7,"e":8,"code":["- [123](http://xxx)","- [xxx](#/papers/@dashboard)"]},"column":{"s":0,"e":28}},"dim":["","list.3"],"code":"- [123](http://xxx)\n- [xxx](#/papers/@dashboard)","symbName":"list","symbRange":[213,235],"symbRangeL":[7,13],"outerCode":"- [xxx](#/papers/@dashboard)\n\n## commands:\n\n### info","outerHtml":"\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\n```bash\nast-lake add '.mdd' '.json'\n```
"},{"id":"/root/children/18/children/0","type":"listItem","loc":{"start":551,"end":570,"line":{"s":41,"e":41,"code":["- add files to list"]},"column":{"s":0,"e":19}},"dim":["","list.18","listItem.0"],"code":"- add files to list"},{"id":"/root/children/18/children/0/children/0","type":"paragraph","loc":{"start":553,"end":570,"line":{"s":41,"e":41,"code":["- add files to list"]},"column":{"s":2,"e":19}},"dim":["","list.18","listItem.0","paragraph.0"],"code":"add files to list"},{"id":"/root/children/18/children/0/children/0/children/0","type":"text","loc":{"start":553,"end":570,"line":{"s":41,"e":41,"code":["- add files to list"]},"column":{"s":2,"e":19}},"dim":["","list.18","listItem.0","paragraph.0","text.0"],"code":"add files to list"},{"id":"/root/children/18/children/1","type":"listItem","loc":{"start":571,"end":641,"line":{"s":42,"e":42,"code":["- dbPopulateList is a temporary list file, listing absolute file paths"]},"column":{"s":0,"e":70}},"dim":["","list.18","listItem.1"],"code":"- dbPopulateList is a temporary list file, listing absolute file paths"},{"id":"/root/children/18/children/1/children/0","type":"paragraph","loc":{"start":573,"end":641,"line":{"s":42,"e":42,"code":["- dbPopulateList is a temporary list file, listing absolute file paths"]},"column":{"s":2,"e":70}},"dim":["","list.18","listItem.1","paragraph.0"],"code":"dbPopulateList is a temporary list file, listing absolute file paths"},{"id":"/root/children/18/children/1/children/0/children/0","type":"text","loc":{"start":573,"end":641,"line":{"s":42,"e":42,"code":["- dbPopulateList is a temporary list file, listing absolute file paths"]},"column":{"s":2,"e":70}},"dim":["","list.18","listItem.1","paragraph.0","text.0"],"code":"dbPopulateList is a temporary list file, listing absolute file paths"},{"id":"/root/children/18/children/2","type":"listItem","loc":{"start":642,"end":689,"line":{"s":43,"e":43,"code":["- dbPopulateList is usually `/tmp/ast-list.txt`"]},"column":{"s":0,"e":47}},"dim":["","list.18","listItem.2"],"code":"- dbPopulateList is usually `/tmp/ast-list.txt`"},{"id":"/root/children/18/children/2/children/0","type":"paragraph","loc":{"start":644,"end":689,"line":{"s":43,"e":43,"code":["- dbPopulateList is usually `/tmp/ast-list.txt`"]},"column":{"s":2,"e":47}},"dim":["","list.18","listItem.2","paragraph.0"],"code":"dbPopulateList is usually `/tmp/ast-list.txt`"},{"id":"/root/children/18/children/2/children/0/children/0","type":"text","loc":{"start":644,"end":670,"line":{"s":43,"e":43,"code":["- dbPopulateList is usually `/tmp/ast-list.txt`"]},"column":{"s":2,"e":28}},"dim":["","list.18","listItem.2","paragraph.0","text.0"],"code":"dbPopulateList is usually "},{"id":"/root/children/18/children/2/children/0/children/1","type":"inlineCode","loc":{"start":670,"end":689,"line":{"s":43,"e":43,"code":["- dbPopulateList is usually `/tmp/ast-list.txt`"]},"column":{"s":28,"e":47}},"dim":["","list.18","listItem.2","paragraph.0","inlineCode.1"],"code":"`/tmp/ast-list.txt`"},{"id":"/root/children/18/children/3","type":"listItem","loc":{"start":690,"end":716,"line":{"s":44,"e":44,"code":["- add absolute file paths:"]},"column":{"s":0,"e":26}},"dim":["","list.18","listItem.3"],"code":"- add absolute file paths:"},{"id":"/root/children/18/children/3/children/0","type":"paragraph","loc":{"start":692,"end":716,"line":{"s":44,"e":44,"code":["- add absolute file paths:"]},"column":{"s":2,"e":26}},"dim":["","list.18","listItem.3","paragraph.0"],"code":"add absolute file paths:"},{"id":"/root/children/18/children/3/children/0/children/0","type":"text","loc":{"start":692,"end":716,"line":{"s":44,"e":44,"code":["- add absolute file paths:"]},"column":{"s":2,"e":26}},"dim":["","list.18","listItem.3","paragraph.0","text.0"],"code":"add absolute file paths:"},{"id":"/root/children/18/children/4","type":"listItem","loc":{"start":717,"end":759,"line":{"s":45,"e":45,"code":["- note: does use `fd`. honors `.gitignore`"]},"column":{"s":0,"e":42}},"dim":["","list.18","listItem.4"],"code":"- note: does use `fd`. honors `.gitignore`"},{"id":"/root/children/18/children/4/children/0","type":"paragraph","loc":{"start":719,"end":759,"line":{"s":45,"e":45,"code":["- note: does use `fd`. honors `.gitignore`"]},"column":{"s":2,"e":42}},"dim":["","list.18","listItem.4","paragraph.0"],"code":"note: does use `fd`. honors `.gitignore`"},{"id":"/root/children/18/children/4/children/0/children/0","type":"text","loc":{"start":719,"end":734,"line":{"s":45,"e":45,"code":["- note: does use `fd`. honors `.gitignore`"]},"column":{"s":2,"e":17}},"dim":["","list.18","listItem.4","paragraph.0","text.0"],"code":"note: does use "},{"id":"/root/children/18/children/4/children/0/children/1","type":"inlineCode","loc":{"start":734,"end":738,"line":{"s":45,"e":45,"code":["- note: does use `fd`. honors `.gitignore`"]},"column":{"s":17,"e":21}},"dim":["","list.18","listItem.4","paragraph.0","inlineCode.1"],"code":"`fd`"},{"id":"/root/children/18/children/4/children/0/children/2","type":"text","loc":{"start":738,"end":747,"line":{"s":45,"e":45,"code":["- note: does use `fd`. honors `.gitignore`"]},"column":{"s":21,"e":30}},"dim":["","list.18","listItem.4","paragraph.0","text.2"],"code":". honors "},{"id":"/root/children/18/children/4/children/0/children/3","type":"inlineCode","loc":{"start":747,"end":759,"line":{"s":45,"e":45,"code":["- note: does use `fd`. honors `.gitignore`"]},"column":{"s":30,"e":42}},"dim":["","list.18","listItem.4","paragraph.0","inlineCode.3"],"code":"`.gitignore`"},{"id":"/root/children/18/children/5","type":"listItem","loc":{"start":760,"end":768,"line":{"s":46,"e":46,"code":["- usage:"]},"column":{"s":0,"e":8}},"dim":["","list.18","listItem.5"],"code":"- usage:"},{"id":"/root/children/18/children/5/children/0","type":"paragraph","loc":{"start":762,"end":768,"line":{"s":46,"e":46,"code":["- usage:"]},"column":{"s":2,"e":8}},"dim":["","list.18","listItem.5","paragraph.0"],"code":"usage:"},{"id":"/root/children/18/children/5/children/0/children/0","type":"text","loc":{"start":762,"end":768,"line":{"s":46,"e":46,"code":["- usage:"]},"column":{"s":2,"e":8}},"dim":["","list.18","listItem.5","paragraph.0","text.0"],"code":"usage:"},{"id":"/root/children/19","type":"code","loc":{"start":770,"end":811,"line":{"s":48,"e":50,"code":["```bash","ast-lake add '*.mdd' '*.json'","```"]},"column":{"s":0,"e":3}},"dim":["","code.19"],"code":"```bash\nast-lake add '*.mdd' '*.json'\n```","symbName":"code","symbRange":[813,902],"symbRangeL":[null,56],"outerCode":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }\n\n# ast-lake\n\nusage: ast-lake [command] [args...]\n\n- [123](http://xxx)\n- [xxx](#/papers/@dashboard)\n\n## commands:\n\n### info\n\n- info on the state of ast-lake\n\n### init\n\n- precreate the cache db\n\n### reset\n\n- delete list\n- delete all cached data\n\n### cleanup\n\n- remove non existent files from sqlite cache\n\n### restart\n\n- keep list\n- delete all cached data\n\n#### reset-nodes\n\n- cleanup only cached nodes (dev)\n- and recreated them\n\n### add\n\n- add files to list\n- dbPopulateList is a temporary list file, listing absolute file paths\n- dbPopulateList is usually `/tmp/ast-list.txt`\n- add absolute file paths:\n- note: does use `fd`. honors `.gitignore`\n- usage:\n\n```bash\nast-lake add '*.mdd' '*.json'\n```\n\n- will add `**/*.mdd` and `*.json` to list\n\n- or manually:\n- you may edit $dbPopulateList","outerHtml":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
"},{"id":"/root/children/20/children/0","type":"listItem","loc":{"start":813,"end":855,"line":{"s":52,"e":52,"code":["- will add `**/*.mdd` and `*.json` to list"]},"column":{"s":0,"e":42}},"dim":["","list.20","listItem.0"],"code":"- will add `**/*.mdd` and `*.json` to list"},{"id":"/root/children/20/children/0/children/0","type":"paragraph","loc":{"start":815,"end":855,"line":{"s":52,"e":52,"code":["- will add `**/*.mdd` and `*.json` to list"]},"column":{"s":2,"e":42}},"dim":["","list.20","listItem.0","paragraph.0"],"code":"will add `**/*.mdd` and `*.json` to list"},{"id":"/root/children/20/children/0/children/0/children/0","type":"text","loc":{"start":815,"end":824,"line":{"s":52,"e":52,"code":["- will add `**/*.mdd` and `*.json` to list"]},"column":{"s":2,"e":11}},"dim":["","list.20","listItem.0","paragraph.0","text.0"],"code":"will add "},{"id":"/root/children/20/children/0/children/0/children/1","type":"inlineCode","loc":{"start":824,"end":834,"line":{"s":52,"e":52,"code":["- will add `**/*.mdd` and `*.json` to list"]},"column":{"s":11,"e":21}},"dim":["","list.20","listItem.0","paragraph.0","inlineCode.1"],"code":"`**/*.mdd`"},{"id":"/root/children/20/children/0/children/0/children/2","type":"text","loc":{"start":834,"end":839,"line":{"s":52,"e":52,"code":["- will add `**/*.mdd` and `*.json` to list"]},"column":{"s":21,"e":26}},"dim":["","list.20","listItem.0","paragraph.0","text.2"],"code":" and "},{"id":"/root/children/20/children/0/children/0/children/3","type":"inlineCode","loc":{"start":839,"end":847,"line":{"s":52,"e":52,"code":["- will add `**/*.mdd` and `*.json` to list"]},"column":{"s":26,"e":34}},"dim":["","list.20","listItem.0","paragraph.0","inlineCode.3"],"code":"`*.json`"},{"id":"/root/children/20/children/0/children/0/children/4","type":"text","loc":{"start":847,"end":855,"line":{"s":52,"e":52,"code":["- will add `**/*.mdd` and `*.json` to list"]},"column":{"s":34,"e":42}},"dim":["","list.20","listItem.0","paragraph.0","text.4"],"code":" to list"},{"id":"/root/children/20/children/1","type":"listItem","loc":{"start":857,"end":871,"line":{"s":54,"e":54,"code":["- or manually:"]},"column":{"s":0,"e":14}},"dim":["","list.20","listItem.1"],"code":"- or manually:"},{"id":"/root/children/20/children/1/children/0","type":"paragraph","loc":{"start":859,"end":871,"line":{"s":54,"e":54,"code":["- or manually:"]},"column":{"s":2,"e":14}},"dim":["","list.20","listItem.1","paragraph.0"],"code":"or manually:"},{"id":"/root/children/20/children/1/children/0/children/0","type":"text","loc":{"start":859,"end":871,"line":{"s":54,"e":54,"code":["- or manually:"]},"column":{"s":2,"e":14}},"dim":["","list.20","listItem.1","paragraph.0","text.0"],"code":"or manually:"},{"id":"/root/children/20/children/2","type":"listItem","loc":{"start":872,"end":902,"line":{"s":55,"e":55,"code":["- you may edit $dbPopulateList"]},"column":{"s":0,"e":30}},"dim":["","list.20","listItem.2"],"code":"- you may edit $dbPopulateList"},{"id":"/root/children/20/children/2/children/0","type":"paragraph","loc":{"start":874,"end":902,"line":{"s":55,"e":55,"code":["- you may edit $dbPopulateList"]},"column":{"s":2,"e":30}},"dim":["","list.20","listItem.2","paragraph.0"],"code":"you may edit $dbPopulateList"},{"id":"/root/children/20/children/2/children/0/children/0","type":"text","loc":{"start":874,"end":902,"line":{"s":55,"e":55,"code":["- you may edit $dbPopulateList"]},"column":{"s":2,"e":30}},"dim":["","list.20","listItem.2","paragraph.0","text.0"],"code":"you may edit $dbPopulateList"},{"id":"/root/children/21","type":"code","loc":{"start":904,"end":1226,"line":{"s":57,"e":68,"code":["```bash","# --base-directory $dir","","fd --absolute-path -tf \".+[.](mdd)$\" | rg -v test > $dbPopulateList","","fd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList","","# or only add arbitrary files:","","rg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList","","```"]},"column":{"s":0,"e":3}},"dim":["","code.21"],"code":"```bash\n# --base-directory $dir\n\nfd --absolute-path -tf \".+[.](mdd)$\" | rg -v test > $dbPopulateList\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList\n\n# or only add arbitrary files:\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList\n\n```","symbName":"code","symbRange":[1228,2297],"symbRangeL":[null,129],"outerCode":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }\n\n# ast-lake\n\nusage: ast-lake [command] [args...]\n\n- [123](http://xxx)\n- [xxx](#/papers/@dashboard)\n\n## commands:\n\n### info\n\n- info on the state of ast-lake\n\n### init\n\n- precreate the cache db\n\n### reset\n\n- delete list\n- delete all cached data\n\n### cleanup\n\n- remove non existent files from sqlite cache\n\n### restart\n\n- keep list\n- delete all cached data\n\n#### reset-nodes\n\n- cleanup only cached nodes (dev)\n- and recreated them\n\n### add\n\n- add files to list\n- dbPopulateList is a temporary list file, listing absolute file paths\n- dbPopulateList is usually `/tmp/ast-list.txt`\n- add absolute file paths:\n- note: does use `fd`. honors `.gitignore`\n- usage:\n\n```bash\nast-lake add '*.mdd' '*.json'\n```\n\n- will add `**/*.mdd` and `*.json` to list\n\n- or manually:\n- you may edit $dbPopulateList\n\n```bash\n# --base-directory $dir\n\nfd --absolute-path -tf \".+[.](mdd)$\" | rg -v test > $dbPopulateList\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList\n\n# or only add arbitrary files:\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList\n\n```\n\n- see also `ast-lake populate`\n\n### populate\n\n- ensure all ast's (from on the list) are up to date\n\n### query TERM\n\n- ast-lake query term\n- TODO term patterns ?\n- TODO regex: ^cs.+$\n\n### queryraw TERM\n\n- same as query, but returns raw JSON\n\n### flast\n\n- basically a dump\n- print all raw flASTs\n\n### nodes\n\n- print raw nodes\n\n### mdg\n\n- TODO really?\n- make one big mdg graph from all mdd's\n\n### mosaic\n\n- mosaic\n- TODO really?\n\n### mprocs\n\n- TODO support mprocs\n\n## recent updates\n\n### 2025-12-01\n\n- actualizeNodes: chunked parallel processing\n- chunk size: CPU count / 2\n- faster database query processing\n\n# db tables\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.\n\n**Two parallel implementations exist:**\n\n- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files\n- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.\n\n## The pipeline (how data flows)","outerHtml":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
"},{"id":"/root/children/41/children/0","type":"listItem","loc":{"start":1725,"end":1770,"line":{"s":113,"e":113,"code":["- actualizeNodes: chunked parallel processing"]},"column":{"s":0,"e":45}},"dim":["","list.41","listItem.0"],"code":"- actualizeNodes: chunked parallel processing"},{"id":"/root/children/41/children/0/children/0","type":"paragraph","loc":{"start":1727,"end":1770,"line":{"s":113,"e":113,"code":["- actualizeNodes: chunked parallel processing"]},"column":{"s":2,"e":45}},"dim":["","list.41","listItem.0","paragraph.0"],"code":"actualizeNodes: chunked parallel processing"},{"id":"/root/children/41/children/0/children/0/children/0","type":"text","loc":{"start":1727,"end":1770,"line":{"s":113,"e":113,"code":["- actualizeNodes: chunked parallel processing"]},"column":{"s":2,"e":45}},"dim":["","list.41","listItem.0","paragraph.0","text.0"],"code":"actualizeNodes: chunked parallel processing"},{"id":"/root/children/41/children/1","type":"listItem","loc":{"start":1771,"end":1798,"line":{"s":114,"e":114,"code":["- chunk size: CPU count / 2"]},"column":{"s":0,"e":27}},"dim":["","list.41","listItem.1"],"code":"- chunk size: CPU count / 2"},{"id":"/root/children/41/children/1/children/0","type":"paragraph","loc":{"start":1773,"end":1798,"line":{"s":114,"e":114,"code":["- chunk size: CPU count / 2"]},"column":{"s":2,"e":27}},"dim":["","list.41","listItem.1","paragraph.0"],"code":"chunk size: CPU count / 2"},{"id":"/root/children/41/children/1/children/0/children/0","type":"text","loc":{"start":1773,"end":1798,"line":{"s":114,"e":114,"code":["- chunk size: CPU count / 2"]},"column":{"s":2,"e":27}},"dim":["","list.41","listItem.1","paragraph.0","text.0"],"code":"chunk size: CPU count / 2"},{"id":"/root/children/41/children/2","type":"listItem","loc":{"start":1799,"end":1833,"line":{"s":115,"e":115,"code":["- faster database query processing"]},"column":{"s":0,"e":34}},"dim":["","list.41","listItem.2"],"code":"- faster database query processing"},{"id":"/root/children/41/children/2/children/0","type":"paragraph","loc":{"start":1801,"end":1833,"line":{"s":115,"e":115,"code":["- faster database query processing"]},"column":{"s":2,"e":34}},"dim":["","list.41","listItem.2","paragraph.0"],"code":"faster database query processing"},{"id":"/root/children/41/children/2/children/0/children/0","type":"text","loc":{"start":1801,"end":1833,"line":{"s":115,"e":115,"code":["- faster database query processing"]},"column":{"s":2,"e":34}},"dim":["","list.41","listItem.2","paragraph.0","text.0"],"code":"faster database query processing"},{"id":"/root/children/42","type":"heading","loc":{"start":1835,"end":1846,"line":{"s":117,"e":117,"code":["# db tables"]},"column":{"s":0,"e":11}},"dim":["","heading.42"],"code":"# db tables","symbName":"heading","symbRange":[1848,2263],"symbRangeL":[117,127],"outerCode":"\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.\n\n**Two parallel implementations exist:**\n\n- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files\n- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.","outerHtml":"\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
"},{"id":"/root/children/42/children/0","type":"text","loc":{"start":1837,"end":1846,"line":{"s":117,"e":117,"code":["# db tables"]},"column":{"s":2,"e":11}},"dim":["","heading.42","text.0"],"code":"db tables"},{"id":"/root/children/43","type":"paragraph","loc":{"start":1848,"end":1970,"line":{"s":119,"e":119,"code":["These tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes."]},"column":{"s":0,"e":122}},"dim":["","paragraph.43"],"code":"These tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes."},{"id":"/root/children/43/children/0","type":"text","loc":{"start":1848,"end":1970,"line":{"s":119,"e":119,"code":["These tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes."]},"column":{"s":0,"e":122}},"dim":["","paragraph.43","text.0"],"code":"These tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes."},{"id":"/root/children/44","type":"paragraph","loc":{"start":1972,"end":2011,"line":{"s":121,"e":121,"code":["**Two parallel implementations exist:**"]},"column":{"s":0,"e":39}},"dim":["","paragraph.44"],"code":"**Two parallel implementations exist:**"},{"id":"/root/children/44/children/0","type":"strong","loc":{"start":1972,"end":2011,"line":{"s":121,"e":121,"code":["**Two parallel implementations exist:**"]},"column":{"s":0,"e":39}},"dim":["","paragraph.44","strong.0"],"code":"**Two parallel implementations exist:**"},{"id":"/root/children/44/children/0/children/0","type":"text","loc":{"start":1974,"end":2009,"line":{"s":121,"e":121,"code":["**Two parallel implementations exist:**"]},"column":{"s":2,"e":37}},"dim":["","paragraph.44","strong.0","text.0"],"code":"Two parallel implementations exist:"},{"id":"/root/children/45","type":"list","loc":{"start":2013,"end":2190,"line":{"s":123,"e":124,"code":["- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files","- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"]},"column":{"s":0,"e":92}},"dim":["","list.45"],"code":"- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files\n- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`","symbName":"list","symbRange":[2192,8506],"symbRangeL":[123,241],"outerCode":"- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.\n\n## The pipeline (how data flows)\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```\n\n## `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but **each column has different semantics per table**:\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |\n\n**Shared indexes:** `num1`, `num2`, `sem`, `ref` (each named `{table}_idx_{col}`).\n\n---\n\n### `cache_ast_lake_flast`\n\n**Role:** Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |\n\n**How it's populated:** Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.\n\n**Query pattern** (in `actualizeNodes()`):\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >Both follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
\n\n```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```
\n\nRole: Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.
\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |
\n\nNormalized node value structure (the JSON in the `value` column):
\n\n```json\n{\n \"fn\": \"/home/.../repo/repolero/paper/file.mdd\",\n \"trail\": [\"getting-started\", \"installation\"],\n \"type\": \"heading\",\n \"nomen\": \"Installation\",\n \"code\": \"## Installation\",\n \"symbName\": null,\n \"symbBlame\": [\"abc123def\", \"456ghi789\"],\n \"outerCode\": \"full subtree text...\",\n \"position\": [42, 1],\n \"lineRange\": [42, 85],\n \"offset\": 42,\n \"symbMt\": \"2025-06-15T10:30:00Z\",\n \"symbUser\": \"author@example.com\",\n \"mt\": \"2025-06-15T10:30:00Z\"\n}\n```
\n\nKey normalization details (from `normalizeNodes()` at ast-lake.mjs:183):
"},{"id":"/root/children/45/children/0","type":"listItem","loc":{"start":2013,"end":2097,"line":{"s":123,"e":123,"code":["- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files"]},"column":{"s":0,"e":84}},"dim":["","list.45","listItem.0"],"code":"- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files"},{"id":"/root/children/45/children/0/children/0","type":"paragraph","loc":{"start":2015,"end":2097,"line":{"s":123,"e":123,"code":["- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files"]},"column":{"s":2,"e":84}},"dim":["","list.45","listItem.0","paragraph.0"],"code":"**Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files"},{"id":"/root/children/45/children/0/children/0/children/0","type":"strong","loc":{"start":2015,"end":2030,"line":{"s":123,"e":123,"code":["- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files"]},"column":{"s":2,"e":17}},"dim":["","list.45","listItem.0","paragraph.0","strong.0"],"code":"**Shell-based**"},{"id":"/root/children/45/children/0/children/0/children/0/children/0","type":"text","loc":{"start":2017,"end":2028,"line":{"s":123,"e":123,"code":["- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files"]},"column":{"s":4,"e":15}},"dim":["","list.45","listItem.0","paragraph.0","strong.0","text.0"],"code":"Shell-based"},{"id":"/root/children/45/children/0/children/0/children/1","type":"text","loc":{"start":2030,"end":2032,"line":{"s":123,"e":123,"code":["- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files"]},"column":{"s":17,"e":19}},"dim":["","list.45","listItem.0","paragraph.0","text.1"],"code":" ("},{"id":"/root/children/45/children/0/children/0/children/2","type":"inlineCode","loc":{"start":2032,"end":2045,"line":{"s":123,"e":123,"code":["- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files"]},"column":{"s":19,"e":32}},"dim":["","list.45","listItem.0","paragraph.0","inlineCode.2"],"code":"`ast-lake.sh`"},{"id":"/root/children/45/children/0/children/0/children/3","type":"text","loc":{"start":2045,"end":2097,"line":{"s":123,"e":123,"code":["- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files"]},"column":{"s":32,"e":84}},"dim":["","list.45","listItem.0","paragraph.0","text.3"],"code":") — older approach using local SQLite + nljson files"},{"id":"/root/children/45/children/1","type":"listItem","loc":{"start":2098,"end":2190,"line":{"s":124,"e":124,"code":["- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"]},"column":{"s":0,"e":92}},"dim":["","list.45","listItem.1"],"code":"- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"},{"id":"/root/children/45/children/1/children/0","type":"paragraph","loc":{"start":2100,"end":2190,"line":{"s":124,"e":124,"code":["- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"]},"column":{"s":2,"e":92}},"dim":["","list.45","listItem.1","paragraph.0"],"code":"**Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"},{"id":"/root/children/45/children/1/children/0/children/0","type":"strong","loc":{"start":2100,"end":2117,"line":{"s":124,"e":124,"code":["- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"]},"column":{"s":2,"e":19}},"dim":["","list.45","listItem.1","paragraph.0","strong.0"],"code":"**Node.js-based**"},{"id":"/root/children/45/children/1/children/0/children/0/children/0","type":"text","loc":{"start":2102,"end":2115,"line":{"s":124,"e":124,"code":["- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"]},"column":{"s":4,"e":17}},"dim":["","list.45","listItem.1","paragraph.0","strong.0","text.0"],"code":"Node.js-based"},{"id":"/root/children/45/children/1/children/0/children/1","type":"text","loc":{"start":2117,"end":2119,"line":{"s":124,"e":124,"code":["- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"]},"column":{"s":19,"e":21}},"dim":["","list.45","listItem.1","paragraph.0","text.1"],"code":" ("},{"id":"/root/children/45/children/1/children/0/children/2","type":"inlineCode","loc":{"start":2119,"end":2133,"line":{"s":124,"e":124,"code":["- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"]},"column":{"s":21,"e":35}},"dim":["","list.45","listItem.1","paragraph.0","inlineCode.2"],"code":"`ast-lake.mjs`"},{"id":"/root/children/45/children/1/children/0/children/3","type":"text","loc":{"start":2133,"end":2176,"line":{"s":124,"e":124,"code":["- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"]},"column":{"s":35,"e":78}},"dim":["","list.45","listItem.1","paragraph.0","text.3"],"code":") — newer approach using remote SQLite via "},{"id":"/root/children/45/children/1/children/0/children/4","type":"inlineCode","loc":{"start":2176,"end":2190,"line":{"s":124,"e":124,"code":["- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`"]},"column":{"s":78,"e":92}},"dim":["","list.45","listItem.1","paragraph.0","inlineCode.4"],"code":"`RemoteSqlite`"},{"id":"/root/children/46","type":"paragraph","loc":{"start":2192,"end":2263,"line":{"s":126,"e":126,"code":["Both follow the same pipeline: extract flast → normalize → store nodes."]},"column":{"s":0,"e":71}},"dim":["","paragraph.46"],"code":"Both follow the same pipeline: extract flast → normalize → store nodes."},{"id":"/root/children/46/children/0","type":"text","loc":{"start":2192,"end":2263,"line":{"s":126,"e":126,"code":["Both follow the same pipeline: extract flast → normalize → store nodes."]},"column":{"s":0,"e":71}},"dim":["","paragraph.46","text.0"],"code":"Both follow the same pipeline: extract flast → normalize → store nodes."},{"id":"/root/children/47","type":"heading","loc":{"start":2265,"end":2297,"line":{"s":128,"e":128,"code":["## The pipeline (how data flows)"]},"column":{"s":0,"e":32}},"dim":["","heading.47"],"code":"## The pipeline (how data flows)","symbName":"heading","symbRange":[2299,3038],"symbRangeL":[128,148],"outerCode":"\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```","outerHtml":"\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
"},{"id":"/root/children/47/children/0","type":"text","loc":{"start":2268,"end":2297,"line":{"s":128,"e":128,"code":["## The pipeline (how data flows)"]},"column":{"s":3,"e":32}},"dim":["","heading.47","text.0"],"code":"The pipeline (how data flows)"},{"id":"/root/children/48","type":"code","loc":{"start":2299,"end":3038,"line":{"s":130,"e":147,"code":["```","File on disk"," │"," ▼","astHole() → astNavigator() — reads file, calls language-specific extractor"," │ (extractFlastMarkdown, extractFlastJavascript,"," │ extractFlastJson, extractFlastBash, ...)"," ▼","cache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array"," │"," ▼","actualizeNodes() → normalizeNodes() — extracts symbolic types from flast"," │ (heading, link, comment, FunctionDeclaration, Identifier)"," ▼","cache_ast_lake_nodes — one row per AST node; id=fn:offset","cache_ast_lake_nodes_ref — same rows, different ref format (readable refId)","cache_ast_lake_nodes_backup — backup of old nodes before update","```"]},"column":{"s":0,"e":3}},"dim":["","code.48"],"code":"```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```","symbName":"code","symbRange":[3040,5280],"symbRangeL":[null,181],"outerCode":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }\n\n# ast-lake\n\nusage: ast-lake [command] [args...]\n\n- [123](http://xxx)\n- [xxx](#/papers/@dashboard)\n\n## commands:\n\n### info\n\n- info on the state of ast-lake\n\n### init\n\n- precreate the cache db\n\n### reset\n\n- delete list\n- delete all cached data\n\n### cleanup\n\n- remove non existent files from sqlite cache\n\n### restart\n\n- keep list\n- delete all cached data\n\n#### reset-nodes\n\n- cleanup only cached nodes (dev)\n- and recreated them\n\n### add\n\n- add files to list\n- dbPopulateList is a temporary list file, listing absolute file paths\n- dbPopulateList is usually `/tmp/ast-list.txt`\n- add absolute file paths:\n- note: does use `fd`. honors `.gitignore`\n- usage:\n\n```bash\nast-lake add '*.mdd' '*.json'\n```\n\n- will add `**/*.mdd` and `*.json` to list\n\n- or manually:\n- you may edit $dbPopulateList\n\n```bash\n# --base-directory $dir\n\nfd --absolute-path -tf \".+[.](mdd)$\" | rg -v test > $dbPopulateList\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList\n\n# or only add arbitrary files:\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList\n\n```\n\n- see also `ast-lake populate`\n\n### populate\n\n- ensure all ast's (from on the list) are up to date\n\n### query TERM\n\n- ast-lake query term\n- TODO term patterns ?\n- TODO regex: ^cs.+$\n\n### queryraw TERM\n\n- same as query, but returns raw JSON\n\n### flast\n\n- basically a dump\n- print all raw flASTs\n\n### nodes\n\n- print raw nodes\n\n### mdg\n\n- TODO really?\n- make one big mdg graph from all mdd's\n\n### mosaic\n\n- mosaic\n- TODO really?\n\n### mprocs\n\n- TODO support mprocs\n\n## recent updates\n\n### 2025-12-01\n\n- actualizeNodes: chunked parallel processing\n- chunk size: CPU count / 2\n- faster database query processing\n\n# db tables\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.\n\n**Two parallel implementations exist:**\n\n- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files\n- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.\n\n## The pipeline (how data flows)\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```\n\n## `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but **each column has different semantics per table**:\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |\n\n**Shared indexes:** `num1`, `num2`, `sem`, `ref` (each named `{table}_idx_{col}`).\n\n---\n\n### `cache_ast_lake_flast`\n\n**Role:** Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |\n\n**How it's populated:** Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.\n\n**Query pattern** (in `actualizeNodes()`):","outerHtml":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
"},{"id":"/root/children/49","type":"heading","loc":{"start":3040,"end":3148,"line":{"s":149,"e":149,"code":["## `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`"]},"column":{"s":0,"e":108}},"dim":["","heading.49"],"code":"## `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`","symbName":"heading","symbRange":[3150,4107],"symbRangeL":[149,167],"outerCode":"\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but **each column has different semantics per table**:\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |\n\n**Shared indexes:** `num1`, `num2`, `sem`, `ref` (each named `{table}_idx_{col}`).\n\n---","outerHtml":"\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
\n\n```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```
\n\n;{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
"},{"id":"/root/children/60","type":"paragraph","loc":{"start":5374,"end":5423,"line":{"s":186,"e":186,"code":["Only changed files (newer mtime) are reprocessed."]},"column":{"s":0,"e":49}},"dim":["","paragraph.60"],"code":"Only changed files (newer mtime) are reprocessed."},{"id":"/root/children/60/children/0","type":"text","loc":{"start":5374,"end":5423,"line":{"s":186,"e":186,"code":["Only changed files (newer mtime) are reprocessed."]},"column":{"s":0,"e":49}},"dim":["","paragraph.60","text.0"],"code":"Only changed files (newer mtime) are reprocessed."},{"id":"/root/children/61","type":"paragraph","loc":{"start":5425,"end":5489,"line":{"s":188,"e":188,"code":["**Node value structure** (each element in the JSON flast array):"]},"column":{"s":0,"e":64}},"dim":["","paragraph.61"],"code":"**Node value structure** (each element in the JSON flast array):"},{"id":"/root/children/61/children/0","type":"strong","loc":{"start":5425,"end":5449,"line":{"s":188,"e":188,"code":["**Node value structure** (each element in the JSON flast array):"]},"column":{"s":0,"e":24}},"dim":["","paragraph.61","strong.0"],"code":"**Node value structure**"},{"id":"/root/children/61/children/0/children/0","type":"text","loc":{"start":5427,"end":5447,"line":{"s":188,"e":188,"code":["**Node value structure** (each element in the JSON flast array):"]},"column":{"s":2,"e":22}},"dim":["","paragraph.61","strong.0","text.0"],"code":"Node value structure"},{"id":"/root/children/61/children/1","type":"text","loc":{"start":5449,"end":5489,"line":{"s":188,"e":188,"code":["**Node value structure** (each element in the JSON flast array):"]},"column":{"s":24,"e":64}},"dim":["","paragraph.61","text.1"],"code":" (each element in the JSON flast array):"},{"id":"/root/children/62","type":"code","loc":{"start":5491,"end":5767,"line":{"s":190,"e":200,"code":["```json","{"," \"id\": \"node-id\","," \"dim\": [\"file\", \"listItem.0\", \"property.key\"],"," \"type\": \"heading|link|code|paragraph|list|...\","," \"code\": \"raw text content\","," \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },"," \"symbName\": null,"," \"symbRangeL\": null","}","```"]},"column":{"s":0,"e":3}},"dim":["","code.62"],"code":"```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```","symbName":"code","symbRange":[5769,7967],"symbRangeL":[null,220],"outerCode":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }\n\n# ast-lake\n\nusage: ast-lake [command] [args...]\n\n- [123](http://xxx)\n- [xxx](#/papers/@dashboard)\n\n## commands:\n\n### info\n\n- info on the state of ast-lake\n\n### init\n\n- precreate the cache db\n\n### reset\n\n- delete list\n- delete all cached data\n\n### cleanup\n\n- remove non existent files from sqlite cache\n\n### restart\n\n- keep list\n- delete all cached data\n\n#### reset-nodes\n\n- cleanup only cached nodes (dev)\n- and recreated them\n\n### add\n\n- add files to list\n- dbPopulateList is a temporary list file, listing absolute file paths\n- dbPopulateList is usually `/tmp/ast-list.txt`\n- add absolute file paths:\n- note: does use `fd`. honors `.gitignore`\n- usage:\n\n```bash\nast-lake add '*.mdd' '*.json'\n```\n\n- will add `**/*.mdd` and `*.json` to list\n\n- or manually:\n- you may edit $dbPopulateList\n\n```bash\n# --base-directory $dir\n\nfd --absolute-path -tf \".+[.](mdd)$\" | rg -v test > $dbPopulateList\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList\n\n# or only add arbitrary files:\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList\n\n```\n\n- see also `ast-lake populate`\n\n### populate\n\n- ensure all ast's (from on the list) are up to date\n\n### query TERM\n\n- ast-lake query term\n- TODO term patterns ?\n- TODO regex: ^cs.+$\n\n### queryraw TERM\n\n- same as query, but returns raw JSON\n\n### flast\n\n- basically a dump\n- print all raw flASTs\n\n### nodes\n\n- print raw nodes\n\n### mdg\n\n- TODO really?\n- make one big mdg graph from all mdd's\n\n### mosaic\n\n- mosaic\n- TODO really?\n\n### mprocs\n\n- TODO support mprocs\n\n## recent updates\n\n### 2025-12-01\n\n- actualizeNodes: chunked parallel processing\n- chunk size: CPU count / 2\n- faster database query processing\n\n# db tables\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.\n\n**Two parallel implementations exist:**\n\n- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files\n- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.\n\n## The pipeline (how data flows)\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```\n\n## `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but **each column has different semantics per table**:\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |\n\n**Shared indexes:** `num1`, `num2`, `sem`, `ref` (each named `{table}_idx_{col}`).\n\n---\n\n### `cache_ast_lake_flast`\n\n**Role:** Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |\n\n**How it's populated:** Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.\n\n**Query pattern** (in `actualizeNodes()`):\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >;{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
\n\n```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```
\n\nRole: Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.
\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |
\n\nNormalized node value structure (the JSON in the `value` column):
"},{"id":"/root/children/63","type":"thematicBreak","loc":{"start":5769,"end":5772,"line":{"s":202,"e":202,"code":["---"]},"column":{"s":0,"e":3}},"dim":["","thematicBreak.63"],"code":"---"},{"id":"/root/children/64","type":"heading","loc":{"start":5774,"end":5800,"line":{"s":204,"e":204,"code":["### `cache_ast_lake_nodes`"]},"column":{"s":0,"e":26}},"dim":["","heading.64"],"code":"### `cache_ast_lake_nodes`","symbName":"heading","symbRange":[5802,9299],"symbRangeL":[204,258],"outerCode":"\n**Role:** Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |\n\n**Normalized node value structure** (the JSON in the `value` column):\n\n```json\n{\n \"fn\": \"/home/.../repo/repolero/paper/file.mdd\",\n \"trail\": [\"getting-started\", \"installation\"],\n \"type\": \"heading\",\n \"nomen\": \"Installation\",\n \"code\": \"## Installation\",\n \"symbName\": null,\n \"symbBlame\": [\"abc123def\", \"456ghi789\"],\n \"outerCode\": \"full subtree text...\",\n \"position\": [42, 1],\n \"lineRange\": [42, 85],\n \"offset\": 42,\n \"symbMt\": \"2025-06-15T10:30:00Z\",\n \"symbUser\": \"author@example.com\",\n \"mt\": \"2025-06-15T10:30:00Z\"\n}\n```\n\n**Key normalization details** (from `normalizeNodes()` at ast-lake.mjs:183):\n\n- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops\n- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label\n- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author\n- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out\n\n**Query pattern** (voting dashboard):\n\n```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```\n\n---","outerHtml":"\nRole: Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.
\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |
\n\nNormalized node value structure (the JSON in the `value` column):
\n\n```json\n{\n \"fn\": \"/home/.../repo/repolero/paper/file.mdd\",\n \"trail\": [\"getting-started\", \"installation\"],\n \"type\": \"heading\",\n \"nomen\": \"Installation\",\n \"code\": \"## Installation\",\n \"symbName\": null,\n \"symbBlame\": [\"abc123def\", \"456ghi789\"],\n \"outerCode\": \"full subtree text...\",\n \"position\": [42, 1],\n \"lineRange\": [42, 85],\n \"offset\": 42,\n \"symbMt\": \"2025-06-15T10:30:00Z\",\n \"symbUser\": \"author@example.com\",\n \"mt\": \"2025-06-15T10:30:00Z\"\n}\n```
\n\nKey normalization details (from `normalizeNodes()` at ast-lake.mjs:183):
\n\nQuery pattern (voting dashboard):
\n\n```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```
\n\n;{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
\n\n```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```
\n\nRole: Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.
\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |
\n\nNormalized node value structure (the JSON in the `value` column):
\n\n```json\n{\n \"fn\": \"/home/.../repo/repolero/paper/file.mdd\",\n \"trail\": [\"getting-started\", \"installation\"],\n \"type\": \"heading\",\n \"nomen\": \"Installation\",\n \"code\": \"## Installation\",\n \"symbName\": null,\n \"symbBlame\": [\"abc123def\", \"456ghi789\"],\n \"outerCode\": \"full subtree text...\",\n \"position\": [42, 1],\n \"lineRange\": [42, 85],\n \"offset\": 42,\n \"symbMt\": \"2025-06-15T10:30:00Z\",\n \"symbUser\": \"author@example.com\",\n \"mt\": \"2025-06-15T10:30:00Z\"\n}\n```
\n\nKey normalization details (from `normalizeNodes()` at ast-lake.mjs:183):
\n\nQuery pattern (voting dashboard):
"},{"id":"/root/children/69","type":"paragraph","loc":{"start":8430,"end":8506,"line":{"s":240,"e":240,"code":["**Key normalization details** (from `normalizeNodes()` at ast-lake.mjs:183):"]},"column":{"s":0,"e":76}},"dim":["","paragraph.69"],"code":"**Key normalization details** (from `normalizeNodes()` at ast-lake.mjs:183):"},{"id":"/root/children/69/children/0","type":"strong","loc":{"start":8430,"end":8459,"line":{"s":240,"e":240,"code":["**Key normalization details** (from `normalizeNodes()` at ast-lake.mjs:183):"]},"column":{"s":0,"e":29}},"dim":["","paragraph.69","strong.0"],"code":"**Key normalization details**"},{"id":"/root/children/69/children/0/children/0","type":"text","loc":{"start":8432,"end":8457,"line":{"s":240,"e":240,"code":["**Key normalization details** (from `normalizeNodes()` at ast-lake.mjs:183):"]},"column":{"s":2,"e":27}},"dim":["","paragraph.69","strong.0","text.0"],"code":"Key normalization details"},{"id":"/root/children/69/children/1","type":"text","loc":{"start":8459,"end":8466,"line":{"s":240,"e":240,"code":["**Key normalization details** (from `normalizeNodes()` at ast-lake.mjs:183):"]},"column":{"s":29,"e":36}},"dim":["","paragraph.69","text.1"],"code":" (from "},{"id":"/root/children/69/children/2","type":"inlineCode","loc":{"start":8466,"end":8484,"line":{"s":240,"e":240,"code":["**Key normalization details** (from `normalizeNodes()` at ast-lake.mjs:183):"]},"column":{"s":36,"e":54}},"dim":["","paragraph.69","inlineCode.2"],"code":"`normalizeNodes()`"},{"id":"/root/children/69/children/3","type":"text","loc":{"start":8484,"end":8506,"line":{"s":240,"e":240,"code":["**Key normalization details** (from `normalizeNodes()` at ast-lake.mjs:183):"]},"column":{"s":54,"e":76}},"dim":["","paragraph.69","text.3"],"code":" at ast-lake.mjs:183):"},{"id":"/root/children/70","type":"list","loc":{"start":8508,"end":9050,"line":{"s":242,"e":245,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops","- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label","- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author","- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out"]},"column":{"s":0,"e":134}},"dim":["","list.70"],"code":"- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops\n- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label\n- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author\n- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out","symbName":"list","symbRange":[9052,10948],"symbRangeL":[242,271],"outerCode":"- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label\n- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author\n- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out\n\n**Query pattern** (voting dashboard):\n\n```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```\n\n---\n\n### `cache_ast_lake_nodes_ref`\n\n**Role:** Readable refId mirror of nodes. Stores the user-visible fragment reference string (the one used in URLs and voting) instead of the last-trail-segment ref.\n\n| Column | How it's populated (ast-lake.mjs:560) | Semantics |\n| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | Same as nodes: `fn:offset` | Joins to `cache_ast_lake_nodes.id` |\n| `sem` | `node.type` | Node type (same as nodes.sem) |\n| `ref` | `buildNodeAbsoluteId(node)` | **Readable refId** — format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`. Built by `buildNodeAbsoluteId()` (ast-lake.mjs:29) |\n| `body` | `linkUrl` for links, `repoName` for others | For links: the URL target. For headings: the repo name. |\n\n**`buildNodeAbsoluteId()` construction** (ast-lake.mjs:29-44):","outerHtml":"Query pattern (voting dashboard):
\n\n```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```
\n\nRole: Readable refId mirror of nodes. Stores the user-visible fragment reference string (the one used in URLs and voting) instead of the last-trail-segment ref.
\n\n| Column | How it's populated (ast-lake.mjs:560) | Semantics |\n| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | Same as nodes: `fn:offset` | Joins to `cache_ast_lake_nodes.id` |\n| `sem` | `node.type` | Node type (same as nodes.sem) |\n| `ref` | `buildNodeAbsoluteId(node)` | Readable refId — format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`. Built by `buildNodeAbsoluteId()` (ast-lake.mjs:29) |\n| `body` | `linkUrl` for links, `repoName` for others | For links: the URL target. For headings: the repo name. |
\n\n`buildNodeAbsoluteId()` construction (ast-lake.mjs:29-44):
"},{"id":"/root/children/70/children/0","type":"listItem","loc":{"start":8508,"end":8675,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":0,"e":167}},"dim":["","list.70","listItem.0"],"code":"- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"},{"id":"/root/children/70/children/0/children/0","type":"paragraph","loc":{"start":8510,"end":8675,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":2,"e":167}},"dim":["","list.70","listItem.0","paragraph.0"],"code":"**headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"},{"id":"/root/children/70/children/0/children/0/children/0","type":"strong","loc":{"start":8510,"end":8522,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":2,"e":14}},"dim":["","list.70","listItem.0","paragraph.0","strong.0"],"code":"**headings**"},{"id":"/root/children/70/children/0/children/0/children/0/children/0","type":"text","loc":{"start":8512,"end":8520,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":4,"e":12}},"dim":["","list.70","listItem.0","paragraph.0","strong.0","text.0"],"code":"headings"},{"id":"/root/children/70/children/0/children/0/children/1","type":"text","loc":{"start":8522,"end":8524,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":14,"e":16}},"dim":["","list.70","listItem.0","paragraph.0","text.1"],"code":": "},{"id":"/root/children/70/children/0/children/0/children/2","type":"inlineCode","loc":{"start":8524,"end":8542,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":16,"e":34}},"dim":["","list.70","listItem.0","paragraph.0","inlineCode.2"],"code":"`processHeading()`"},{"id":"/root/children/70/children/0/children/0/children/3","type":"text","loc":{"start":8542,"end":8608,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":34,"e":100}},"dim":["","list.70","listItem.0","paragraph.0","text.3"],"code":" extracts level and pure text; breadcrumb trail tracks hierarchy; "},{"id":"/root/children/70/children/0/children/0/children/4","type":"inlineCode","loc":{"start":8608,"end":8634,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":100,"e":126}},"dim":["","list.70","listItem.0","paragraph.0","inlineCode.4"],"code":"`currentLevel > lastLevel`"},{"id":"/root/children/70/children/0/children/0/children/5","type":"text","loc":{"start":8634,"end":8643,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":126,"e":135}},"dim":["","list.70","listItem.0","paragraph.0","text.5"],"code":" pushes, "},{"id":"/root/children/70/children/0/children/0/children/6","type":"inlineCode","loc":{"start":8643,"end":8670,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":135,"e":162}},"dim":["","list.70","listItem.0","paragraph.0","inlineCode.6"],"code":"`currentLevel <= lastLevel`"},{"id":"/root/children/70/children/0/children/0/children/7","type":"text","loc":{"start":8670,"end":8675,"line":{"s":242,"e":242,"code":["- **headings**: `processHeading()` extracts level and pure text; breadcrumb trail tracks hierarchy; `currentLevel > lastLevel` pushes, `currentLevel <= lastLevel` pops"]},"column":{"s":162,"e":167}},"dim":["","list.70","listItem.0","paragraph.0","text.7"],"code":" pops"},{"id":"/root/children/70/children/1","type":"listItem","loc":{"start":8676,"end":8768,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":0,"e":92}},"dim":["","list.70","listItem.1"],"code":"- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"},{"id":"/root/children/70/children/1/children/0","type":"paragraph","loc":{"start":8678,"end":8768,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":2,"e":92}},"dim":["","list.70","listItem.1","paragraph.0"],"code":"**links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"},{"id":"/root/children/70/children/1/children/0/children/0","type":"strong","loc":{"start":8678,"end":8687,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":2,"e":11}},"dim":["","list.70","listItem.1","paragraph.0","strong.0"],"code":"**links**"},{"id":"/root/children/70/children/1/children/0/children/0/children/0","type":"text","loc":{"start":8680,"end":8685,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":4,"e":9}},"dim":["","list.70","listItem.1","paragraph.0","strong.0","text.0"],"code":"links"},{"id":"/root/children/70/children/1/children/0/children/1","type":"text","loc":{"start":8687,"end":8689,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":11,"e":13}},"dim":["","list.70","listItem.1","paragraph.0","text.1"],"code":": "},{"id":"/root/children/70/children/1/children/0/children/2","type":"inlineCode","loc":{"start":8689,"end":8710,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":13,"e":34}},"dim":["","list.70","listItem.1","paragraph.0","inlineCode.2"],"code":"`parseMarkdownLink()`"},{"id":"/root/children/70/children/1/children/0/children/3","type":"text","loc":{"start":8710,"end":8720,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":34,"e":44}},"dim":["","list.70","listItem.1","paragraph.0","text.3"],"code":" extracts "},{"id":"/root/children/70/children/1/children/0/children/4","type":"inlineCode","loc":{"start":8720,"end":8734,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":44,"e":58}},"dim":["","list.70","listItem.1","paragraph.0","inlineCode.4"],"code":"`[label](url)`"},{"id":"/root/children/70/children/1/children/0/children/5","type":"text","loc":{"start":8734,"end":8736,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":58,"e":60}},"dim":["","list.70","listItem.1","paragraph.0","text.5"],"code":"; "},{"id":"/root/children/70/children/1/children/0/children/6","type":"inlineCode","loc":{"start":8736,"end":8747,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":60,"e":71}},"dim":["","list.70","listItem.1","paragraph.0","inlineCode.6"],"code":"`outerCode`"},{"id":"/root/children/70/children/1/children/0/children/7","type":"text","loc":{"start":8747,"end":8768,"line":{"s":243,"e":243,"code":["- **links**: `parseMarkdownLink()` extracts `[label](url)`; `outerCode` = url; nomen = label"]},"column":{"s":71,"e":92}},"dim":["","list.70","listItem.1","paragraph.0","text.7"],"code":" = url; nomen = label"},{"id":"/root/children/70/children/2","type":"listItem","loc":{"start":8769,"end":8915,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":0,"e":146}},"dim":["","list.70","listItem.2"],"code":"- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"},{"id":"/root/children/70/children/2/children/0","type":"paragraph","loc":{"start":8771,"end":8915,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":2,"e":146}},"dim":["","list.70","listItem.2","paragraph.0"],"code":"**git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"},{"id":"/root/children/70/children/2/children/0/children/0","type":"strong","loc":{"start":8771,"end":8784,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":2,"e":15}},"dim":["","list.70","listItem.2","paragraph.0","strong.0"],"code":"**git blame**"},{"id":"/root/children/70/children/2/children/0/children/0/children/0","type":"text","loc":{"start":8773,"end":8782,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":4,"e":13}},"dim":["","list.70","listItem.2","paragraph.0","strong.0","text.0"],"code":"git blame"},{"id":"/root/children/70/children/2/children/0/children/1","type":"text","loc":{"start":8784,"end":8786,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":15,"e":17}},"dim":["","list.70","listItem.2","paragraph.0","text.1"],"code":": "},{"id":"/root/children/70/children/2/children/0/children/2","type":"inlineCode","loc":{"start":8786,"end":8797,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":17,"e":28}},"dim":["","list.70","listItem.2","paragraph.0","inlineCode.2"],"code":"`symbBlame`"},{"id":"/root/children/70/children/2/children/0/children/3","type":"text","loc":{"start":8797,"end":8834,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":28,"e":65}},"dim":["","list.70","listItem.2","paragraph.0","text.3"],"code":" array of commit hashes for lines in "},{"id":"/root/children/70/children/2/children/0/children/4","type":"inlineCode","loc":{"start":8834,"end":8846,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":65,"e":77}},"dim":["","list.70","listItem.2","paragraph.0","inlineCode.4"],"code":"`symbRangeL`"},{"id":"/root/children/70/children/2/children/0/children/5","type":"text","loc":{"start":8846,"end":8848,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":77,"e":79}},"dim":["","list.70","listItem.2","paragraph.0","text.5"],"code":"; "},{"id":"/root/children/70/children/2/children/0/children/6","type":"inlineCode","loc":{"start":8848,"end":8856,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":79,"e":87}},"dim":["","list.70","listItem.2","paragraph.0","inlineCode.6"],"code":"`symbMt`"},{"id":"/root/children/70/children/2/children/0/children/7","type":"text","loc":{"start":8856,"end":8884,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":87,"e":115}},"dim":["","list.70","listItem.2","paragraph.0","text.7"],"code":" = most recent blame mtime; "},{"id":"/root/children/70/children/2/children/0/children/8","type":"inlineCode","loc":{"start":8884,"end":8894,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":115,"e":125}},"dim":["","list.70","listItem.2","paragraph.0","inlineCode.8"],"code":"`symbUser`"},{"id":"/root/children/70/children/2/children/0/children/9","type":"text","loc":{"start":8894,"end":8915,"line":{"s":244,"e":244,"code":["- **git blame**: `symbBlame` array of commit hashes for lines in `symbRangeL`; `symbMt` = most recent blame mtime; `symbUser` = most recent author"]},"column":{"s":125,"e":146}},"dim":["","list.70","listItem.2","paragraph.0","text.9"],"code":" = most recent author"},{"id":"/root/children/70/children/3","type":"listItem","loc":{"start":8916,"end":9050,"line":{"s":245,"e":245,"code":["- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out"]},"column":{"s":0,"e":134}},"dim":["","list.70","listItem.3"],"code":"- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out"},{"id":"/root/children/70/children/3/children/0","type":"paragraph","loc":{"start":8918,"end":9050,"line":{"s":245,"e":245,"code":["- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out"]},"column":{"s":2,"e":134}},"dim":["","list.70","listItem.3","paragraph.0"],"code":"Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out"},{"id":"/root/children/70/children/3/children/0/children/0","type":"text","loc":{"start":8918,"end":8943,"line":{"s":245,"e":245,"code":["- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out"]},"column":{"s":2,"e":27}},"dim":["","list.70","listItem.3","paragraph.0","text.0"],"code":"Only nodes with types in "},{"id":"/root/children/70/children/3/children/0/children/1","type":"inlineCode","loc":{"start":8943,"end":8958,"line":{"s":245,"e":245,"code":["- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out"]},"column":{"s":27,"e":42}},"dim":["","list.70","listItem.3","paragraph.0","inlineCode.1"],"code":"`symbolicTypes`"},{"id":"/root/children/70/children/3/children/0/children/2","type":"text","loc":{"start":8958,"end":9050,"line":{"s":245,"e":245,"code":["- Only nodes with types in `symbolicTypes` are kept; all others (paragraph, list, code without heading context, etc.) are filtered out"]},"column":{"s":42,"e":134}},"dim":["","list.70","listItem.3","paragraph.0","text.2"],"code":" are kept; all others (paragraph, list, code without heading context, etc.) are filtered out"},{"id":"/root/children/71","type":"paragraph","loc":{"start":9052,"end":9089,"line":{"s":247,"e":247,"code":["**Query pattern** (voting dashboard):"]},"column":{"s":0,"e":37}},"dim":["","paragraph.71"],"code":"**Query pattern** (voting dashboard):"},{"id":"/root/children/71/children/0","type":"strong","loc":{"start":9052,"end":9069,"line":{"s":247,"e":247,"code":["**Query pattern** (voting dashboard):"]},"column":{"s":0,"e":17}},"dim":["","paragraph.71","strong.0"],"code":"**Query pattern**"},{"id":"/root/children/71/children/0/children/0","type":"text","loc":{"start":9054,"end":9067,"line":{"s":247,"e":247,"code":["**Query pattern** (voting dashboard):"]},"column":{"s":2,"e":15}},"dim":["","paragraph.71","strong.0","text.0"],"code":"Query pattern"},{"id":"/root/children/71/children/1","type":"text","loc":{"start":9069,"end":9089,"line":{"s":247,"e":247,"code":["**Query pattern** (voting dashboard):"]},"column":{"s":17,"e":37}},"dim":["","paragraph.71","text.1"],"code":" (voting dashboard):"},{"id":"/root/children/72","type":"code","loc":{"start":9091,"end":9294,"line":{"s":249,"e":255,"code":["```sql","SELECT n.id, n.body, n.num1 as headingLevel, r.ref","FROM cache_ast_lake_nodes n","INNER JOIN cache_ast_lake_nodes_ref r USING(id)","INNER JOIN repo_voting v ON v.ref = r.ref","WHERE n.sem = 'heading'","```"]},"column":{"s":0,"e":3}},"dim":["","code.72"],"code":"```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```","symbName":"code","symbRange":[9296,11887],"symbRangeL":[null,290],"outerCode":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }\n\n# ast-lake\n\nusage: ast-lake [command] [args...]\n\n- [123](http://xxx)\n- [xxx](#/papers/@dashboard)\n\n## commands:\n\n### info\n\n- info on the state of ast-lake\n\n### init\n\n- precreate the cache db\n\n### reset\n\n- delete list\n- delete all cached data\n\n### cleanup\n\n- remove non existent files from sqlite cache\n\n### restart\n\n- keep list\n- delete all cached data\n\n#### reset-nodes\n\n- cleanup only cached nodes (dev)\n- and recreated them\n\n### add\n\n- add files to list\n- dbPopulateList is a temporary list file, listing absolute file paths\n- dbPopulateList is usually `/tmp/ast-list.txt`\n- add absolute file paths:\n- note: does use `fd`. honors `.gitignore`\n- usage:\n\n```bash\nast-lake add '*.mdd' '*.json'\n```\n\n- will add `**/*.mdd` and `*.json` to list\n\n- or manually:\n- you may edit $dbPopulateList\n\n```bash\n# --base-directory $dir\n\nfd --absolute-path -tf \".+[.](mdd)$\" | rg -v test > $dbPopulateList\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList\n\n# or only add arbitrary files:\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList\n\n```\n\n- see also `ast-lake populate`\n\n### populate\n\n- ensure all ast's (from on the list) are up to date\n\n### query TERM\n\n- ast-lake query term\n- TODO term patterns ?\n- TODO regex: ^cs.+$\n\n### queryraw TERM\n\n- same as query, but returns raw JSON\n\n### flast\n\n- basically a dump\n- print all raw flASTs\n\n### nodes\n\n- print raw nodes\n\n### mdg\n\n- TODO really?\n- make one big mdg graph from all mdd's\n\n### mosaic\n\n- mosaic\n- TODO really?\n\n### mprocs\n\n- TODO support mprocs\n\n## recent updates\n\n### 2025-12-01\n\n- actualizeNodes: chunked parallel processing\n- chunk size: CPU count / 2\n- faster database query processing\n\n# db tables\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.\n\n**Two parallel implementations exist:**\n\n- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files\n- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.\n\n## The pipeline (how data flows)\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```\n\n## `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but **each column has different semantics per table**:\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |\n\n**Shared indexes:** `num1`, `num2`, `sem`, `ref` (each named `{table}_idx_{col}`).\n\n---\n\n### `cache_ast_lake_flast`\n\n**Role:** Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |\n\n**How it's populated:** Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.\n\n**Query pattern** (in `actualizeNodes()`):\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >;{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
\n\n```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```
\n\nRole: Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.
\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |
\n\nNormalized node value structure (the JSON in the `value` column):
\n\n```json\n{\n \"fn\": \"/home/.../repo/repolero/paper/file.mdd\",\n \"trail\": [\"getting-started\", \"installation\"],\n \"type\": \"heading\",\n \"nomen\": \"Installation\",\n \"code\": \"## Installation\",\n \"symbName\": null,\n \"symbBlame\": [\"abc123def\", \"456ghi789\"],\n \"outerCode\": \"full subtree text...\",\n \"position\": [42, 1],\n \"lineRange\": [42, 85],\n \"offset\": 42,\n \"symbMt\": \"2025-06-15T10:30:00Z\",\n \"symbUser\": \"author@example.com\",\n \"mt\": \"2025-06-15T10:30:00Z\"\n}\n```
\n\nKey normalization details (from `normalizeNodes()` at ast-lake.mjs:183):
\n\nQuery pattern (voting dashboard):
\n\n```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```
\n\nRole: Readable refId mirror of nodes. Stores the user-visible fragment reference string (the one used in URLs and voting) instead of the last-trail-segment ref.
\n\n| Column | How it's populated (ast-lake.mjs:560) | Semantics |\n| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | Same as nodes: `fn:offset` | Joins to `cache_ast_lake_nodes.id` |\n| `sem` | `node.type` | Node type (same as nodes.sem) |\n| `ref` | `buildNodeAbsoluteId(node)` | Readable refId — format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`. Built by `buildNodeAbsoluteId()` (ast-lake.mjs:29) |\n| `body` | `linkUrl` for links, `repoName` for others | For links: the URL target. For headings: the repo name. |
\n\n`buildNodeAbsoluteId()` construction (ast-lake.mjs:29-44):
\n\n`buildNodeRefId()` (ast-lake.mjs:46-48):
\n\nWhy two ref tables? `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`.
\n\nRole: Rollback copy. Before updating a file's nodes in `cache_ast_lake_nodes`, the old rows are copied here (ast-lake.mjs:500-514):
"},{"id":"/root/children/73","type":"thematicBreak","loc":{"start":9296,"end":9299,"line":{"s":257,"e":257,"code":["---"]},"column":{"s":0,"e":3}},"dim":["","thematicBreak.73"],"code":"---"},{"id":"/root/children/74","type":"heading","loc":{"start":9301,"end":9331,"line":{"s":259,"e":259,"code":["### `cache_ast_lake_nodes_ref`"]},"column":{"s":0,"e":30}},"dim":["","heading.74"],"code":"### `cache_ast_lake_nodes_ref`","symbName":"heading","symbRange":[9333,11715],"symbRangeL":[259,286],"outerCode":"\n**Role:** Readable refId mirror of nodes. Stores the user-visible fragment reference string (the one used in URLs and voting) instead of the last-trail-segment ref.\n\n| Column | How it's populated (ast-lake.mjs:560) | Semantics |\n| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | Same as nodes: `fn:offset` | Joins to `cache_ast_lake_nodes.id` |\n| `sem` | `node.type` | Node type (same as nodes.sem) |\n| `ref` | `buildNodeAbsoluteId(node)` | **Readable refId** — format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`. Built by `buildNodeAbsoluteId()` (ast-lake.mjs:29) |\n| `body` | `linkUrl` for links, `repoName` for others | For links: the URL target. For headings: the repo name. |\n\n**`buildNodeAbsoluteId()` construction** (ast-lake.mjs:29-44):\n\n1. Strips `/repo/` prefix from fn → `relative/path/file.mdd`\n2. Appends `::` + sanitized trail segments joined by `/`\n3. For links: appends `#sanitizeName(nomen):tinyHash(url)` anchor\n4. Result example: `paper/visualization.mdd::visualization/graphviz#osage:ab12cd`\n\n**`buildNodeRefId()`** (ast-lake.mjs:46-48):\n\n- For headings: returns last trail segment (e.g. `\"installation\"`)\n- For links: returns nomen (link label, e.g. `\"click here\"`)\n- This is the short ref stored in `cache_ast_lake_nodes.ref`\n\n**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`.\n\n---","outerHtml":"\nRole: Readable refId mirror of nodes. Stores the user-visible fragment reference string (the one used in URLs and voting) instead of the last-trail-segment ref.
\n\n| Column | How it's populated (ast-lake.mjs:560) | Semantics |\n| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | Same as nodes: `fn:offset` | Joins to `cache_ast_lake_nodes.id` |\n| `sem` | `node.type` | Node type (same as nodes.sem) |\n| `ref` | `buildNodeAbsoluteId(node)` | Readable refId — format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`. Built by `buildNodeAbsoluteId()` (ast-lake.mjs:29) |\n| `body` | `linkUrl` for links, `repoName` for others | For links: the URL target. For headings: the repo name. |
\n\n`buildNodeAbsoluteId()` construction (ast-lake.mjs:29-44):
\n\n`buildNodeRefId()` (ast-lake.mjs:46-48):
\n\nWhy two ref tables? `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`.
\n\n`buildNodeRefId()` (ast-lake.mjs:46-48):
"},{"id":"/root/children/78/children/0","type":"listItem","loc":{"start":10950,"end":11010,"line":{"s":272,"e":272,"code":["1. Strips `/repo/` prefix from fn → `relative/path/file.mdd`"]},"column":{"s":0,"e":60}},"dim":["","list.78","listItem.0"],"code":"1. Strips `/repo/` prefix from fn → `relative/path/file.mdd`"},{"id":"/root/children/78/children/0/children/0","type":"paragraph","loc":{"start":10953,"end":11010,"line":{"s":272,"e":272,"code":["1. Strips `/repo/` prefix from fn → `relative/path/file.mdd`"]},"column":{"s":3,"e":60}},"dim":["","list.78","listItem.0","paragraph.0"],"code":"Strips `/repo/` prefix from fn → `relative/path/file.mdd`"},{"id":"/root/children/78/children/0/children/0/children/0","type":"text","loc":{"start":10953,"end":10960,"line":{"s":272,"e":272,"code":["1. Strips `/repo/` prefix from fn → `relative/path/file.mdd`"]},"column":{"s":3,"e":10}},"dim":["","list.78","listItem.0","paragraph.0","text.0"],"code":"Strips "},{"id":"/root/children/78/children/0/children/0/children/1","type":"inlineCode","loc":{"start":10960,"end":10968,"line":{"s":272,"e":272,"code":["1. Strips `/repo/` prefix from fn → `relative/path/file.mdd`"]},"column":{"s":10,"e":18}},"dim":["","list.78","listItem.0","paragraph.0","inlineCode.1"],"code":"`/repo/`"},{"id":"/root/children/78/children/0/children/0/children/2","type":"text","loc":{"start":10968,"end":10986,"line":{"s":272,"e":272,"code":["1. Strips `/repo/` prefix from fn → `relative/path/file.mdd`"]},"column":{"s":18,"e":36}},"dim":["","list.78","listItem.0","paragraph.0","text.2"],"code":" prefix from fn → "},{"id":"/root/children/78/children/0/children/0/children/3","type":"inlineCode","loc":{"start":10986,"end":11010,"line":{"s":272,"e":272,"code":["1. Strips `/repo/` prefix from fn → `relative/path/file.mdd`"]},"column":{"s":36,"e":60}},"dim":["","list.78","listItem.0","paragraph.0","inlineCode.3"],"code":"`relative/path/file.mdd`"},{"id":"/root/children/78/children/1","type":"listItem","loc":{"start":11011,"end":11067,"line":{"s":273,"e":273,"code":["2. Appends `::` + sanitized trail segments joined by `/`"]},"column":{"s":0,"e":56}},"dim":["","list.78","listItem.1"],"code":"2. Appends `::` + sanitized trail segments joined by `/`"},{"id":"/root/children/78/children/1/children/0","type":"paragraph","loc":{"start":11014,"end":11067,"line":{"s":273,"e":273,"code":["2. Appends `::` + sanitized trail segments joined by `/`"]},"column":{"s":3,"e":56}},"dim":["","list.78","listItem.1","paragraph.0"],"code":"Appends `::` + sanitized trail segments joined by `/`"},{"id":"/root/children/78/children/1/children/0/children/0","type":"text","loc":{"start":11014,"end":11022,"line":{"s":273,"e":273,"code":["2. Appends `::` + sanitized trail segments joined by `/`"]},"column":{"s":3,"e":11}},"dim":["","list.78","listItem.1","paragraph.0","text.0"],"code":"Appends "},{"id":"/root/children/78/children/1/children/0/children/1","type":"inlineCode","loc":{"start":11022,"end":11026,"line":{"s":273,"e":273,"code":["2. Appends `::` + sanitized trail segments joined by `/`"]},"column":{"s":11,"e":15}},"dim":["","list.78","listItem.1","paragraph.0","inlineCode.1"],"code":"`::`"},{"id":"/root/children/78/children/1/children/0/children/2","type":"text","loc":{"start":11026,"end":11064,"line":{"s":273,"e":273,"code":["2. Appends `::` + sanitized trail segments joined by `/`"]},"column":{"s":15,"e":53}},"dim":["","list.78","listItem.1","paragraph.0","text.2"],"code":" + sanitized trail segments joined by "},{"id":"/root/children/78/children/1/children/0/children/3","type":"inlineCode","loc":{"start":11064,"end":11067,"line":{"s":273,"e":273,"code":["2. Appends `::` + sanitized trail segments joined by `/`"]},"column":{"s":53,"e":56}},"dim":["","list.78","listItem.1","paragraph.0","inlineCode.3"],"code":"`/`"},{"id":"/root/children/78/children/2","type":"listItem","loc":{"start":11068,"end":11133,"line":{"s":274,"e":274,"code":["3. For links: appends `#sanitizeName(nomen):tinyHash(url)` anchor"]},"column":{"s":0,"e":65}},"dim":["","list.78","listItem.2"],"code":"3. For links: appends `#sanitizeName(nomen):tinyHash(url)` anchor"},{"id":"/root/children/78/children/2/children/0","type":"paragraph","loc":{"start":11071,"end":11133,"line":{"s":274,"e":274,"code":["3. For links: appends `#sanitizeName(nomen):tinyHash(url)` anchor"]},"column":{"s":3,"e":65}},"dim":["","list.78","listItem.2","paragraph.0"],"code":"For links: appends `#sanitizeName(nomen):tinyHash(url)` anchor"},{"id":"/root/children/78/children/2/children/0/children/0","type":"text","loc":{"start":11071,"end":11090,"line":{"s":274,"e":274,"code":["3. For links: appends `#sanitizeName(nomen):tinyHash(url)` anchor"]},"column":{"s":3,"e":22}},"dim":["","list.78","listItem.2","paragraph.0","text.0"],"code":"For links: appends "},{"id":"/root/children/78/children/2/children/0/children/1","type":"inlineCode","loc":{"start":11090,"end":11126,"line":{"s":274,"e":274,"code":["3. For links: appends `#sanitizeName(nomen):tinyHash(url)` anchor"]},"column":{"s":22,"e":58}},"dim":["","list.78","listItem.2","paragraph.0","inlineCode.1"],"code":"`#sanitizeName(nomen):tinyHash(url)`"},{"id":"/root/children/78/children/2/children/0/children/2","type":"text","loc":{"start":11126,"end":11133,"line":{"s":274,"e":274,"code":["3. For links: appends `#sanitizeName(nomen):tinyHash(url)` anchor"]},"column":{"s":58,"e":65}},"dim":["","list.78","listItem.2","paragraph.0","text.2"],"code":" anchor"},{"id":"/root/children/78/children/3","type":"listItem","loc":{"start":11134,"end":11215,"line":{"s":275,"e":275,"code":["4. Result example: `paper/visualization.mdd::visualization/graphviz#osage:ab12cd`"]},"column":{"s":0,"e":81}},"dim":["","list.78","listItem.3"],"code":"4. Result example: `paper/visualization.mdd::visualization/graphviz#osage:ab12cd`"},{"id":"/root/children/78/children/3/children/0","type":"paragraph","loc":{"start":11137,"end":11215,"line":{"s":275,"e":275,"code":["4. Result example: `paper/visualization.mdd::visualization/graphviz#osage:ab12cd`"]},"column":{"s":3,"e":81}},"dim":["","list.78","listItem.3","paragraph.0"],"code":"Result example: `paper/visualization.mdd::visualization/graphviz#osage:ab12cd`"},{"id":"/root/children/78/children/3/children/0/children/0","type":"text","loc":{"start":11137,"end":11153,"line":{"s":275,"e":275,"code":["4. Result example: `paper/visualization.mdd::visualization/graphviz#osage:ab12cd`"]},"column":{"s":3,"e":19}},"dim":["","list.78","listItem.3","paragraph.0","text.0"],"code":"Result example: "},{"id":"/root/children/78/children/3/children/0/children/1","type":"inlineCode","loc":{"start":11153,"end":11215,"line":{"s":275,"e":275,"code":["4. Result example: `paper/visualization.mdd::visualization/graphviz#osage:ab12cd`"]},"column":{"s":19,"e":81}},"dim":["","list.78","listItem.3","paragraph.0","inlineCode.1"],"code":"`paper/visualization.mdd::visualization/graphviz#osage:ab12cd`"},{"id":"/root/children/79","type":"paragraph","loc":{"start":11217,"end":11261,"line":{"s":277,"e":277,"code":["**`buildNodeRefId()`** (ast-lake.mjs:46-48):"]},"column":{"s":0,"e":44}},"dim":["","paragraph.79"],"code":"**`buildNodeRefId()`** (ast-lake.mjs:46-48):"},{"id":"/root/children/79/children/0","type":"strong","loc":{"start":11217,"end":11239,"line":{"s":277,"e":277,"code":["**`buildNodeRefId()`** (ast-lake.mjs:46-48):"]},"column":{"s":0,"e":22}},"dim":["","paragraph.79","strong.0"],"code":"**`buildNodeRefId()`**"},{"id":"/root/children/79/children/0/children/0","type":"inlineCode","loc":{"start":11219,"end":11237,"line":{"s":277,"e":277,"code":["**`buildNodeRefId()`** (ast-lake.mjs:46-48):"]},"column":{"s":2,"e":20}},"dim":["","paragraph.79","strong.0","inlineCode.0"],"code":"`buildNodeRefId()`"},{"id":"/root/children/79/children/1","type":"text","loc":{"start":11239,"end":11261,"line":{"s":277,"e":277,"code":["**`buildNodeRefId()`** (ast-lake.mjs:46-48):"]},"column":{"s":22,"e":44}},"dim":["","paragraph.79","text.1"],"code":" (ast-lake.mjs:46-48):"},{"id":"/root/children/80","type":"list","loc":{"start":11263,"end":11451,"line":{"s":279,"e":281,"code":["- For headings: returns last trail segment (e.g. `\"installation\"`)","- For links: returns nomen (link label, e.g. `\"click here\"`)","- This is the short ref stored in `cache_ast_lake_nodes.ref`"]},"column":{"s":0,"e":60}},"dim":["","list.80"],"code":"- For headings: returns last trail segment (e.g. `\"installation\"`)\n- For links: returns nomen (link label, e.g. `\"click here\"`)\n- This is the short ref stored in `cache_ast_lake_nodes.ref`","symbName":"list","symbRange":[11453,16362],"symbRangeL":[279,373],"outerCode":"- For links: returns nomen (link label, e.g. `\"click here\"`)\n- This is the short ref stored in `cache_ast_lake_nodes.ref`\n\n**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`.\n\n---\n\n### `cache_ast_lake_nodes_backup`\n\n**Role:** Rollback copy. Before updating a file's nodes in `cache_ast_lake_nodes`, the old rows are copied here (ast-lake.mjs:500-514):\n\n```sql\nINSERT OR REPLACE INTO cache_ast_lake_nodes_backup\n (id, value, mt, sem, num1, num2, ref, body)\nSELECT id, value, mt, sem, num1, num2, ref, body\nFROM cache_ast_lake_nodes\nWHERE id LIKE 'Why two ref tables? `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`.
\n\nRole: Rollback copy. Before updating a file's nodes in `cache_ast_lake_nodes`, the old rows are copied here (ast-lake.mjs:500-514):
\n\n```sql\nINSERT OR REPLACE INTO cache_ast_lake_nodes_backup\n (id, value, mt, sem, num1, num2, ref, body)\nSELECT id, value, mt, sem, num1, num2, ref, body\nFROM cache_ast_lake_nodes\nWHERE id LIKE '
Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored.
\n\nNote: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time.
\n\nRole: Git blame line-history cache. Maps each line in each file to its git blame metadata (commit hash, author, timestamp). Used by `normalizeNodes()` to attach `symbBlame`/`symbMt`/`symbUser` to each node.
\n\nSchema (commented inline in `ast-lake.mjs:122-131`):
\n\n| Column | Type | Description |\n| ------ | ---------------- | ----------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `fn` | TEXT NOT NULL | File name / path (matches flast.id / nodes fn prefix) |\n| `line` | INTEGER NOT NULL | Line number in the file (1-based) |\n| `hash` | TEXT NOT NULL | Git commit hash from blame |\n| `mt` | TEXT NOT NULL | Commit author timestamp |\n| `user` | TEXT | Author name or email |\n| `json` | TEXT | Additional metadata as JSON blob |
\n\nQuery pattern (in `actualizeNodes()`, ast-lake.mjs:473):
\n\n```sql\nSELECT line, mt, user, hash FROM linetime\nWHERE fn='
The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range.
\n\nSee `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows.
\n\nRole: Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`.
\n\n| Column | Type | Description |\n| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `d` | TEXT NOT NULL | ISO timestamp of the vote event |\n| `user` | TEXT | Voter identifier (username or email) |\n| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |\n| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |\n| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |\n| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |\n| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |\n| `json` | TEXT | Additional payload as JSON blob |
\n\nIndexes: `num1`, `num2`, `campaign`, `operation`, `ref`.
\n\nKey query patterns:
\n\nDashboard voting (count per ref):
\n\n```sql\nSELECT ref, operation, COUNT(*) as count, SUM(num1) as total\nFROM repo_voting\nWHERE campaign = 'eisenhower'\nGROUP BY ref, operation\n```
\n\nHeading-changes metadata check (`hasMetaData`):
\n\n```sql\nSELECT DISTINCT ref FROM repo_voting\nWHERE ref IN ('ref1', 'ref2', ...)\n```
\n\nref format: Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`.
\n\nCleanup on file deletion (ast-lake.mjs `cleanup()` at line 305):
"},{"id":"/root/children/80/children/0","type":"listItem","loc":{"start":11263,"end":11329,"line":{"s":279,"e":279,"code":["- For headings: returns last trail segment (e.g. `\"installation\"`)"]},"column":{"s":0,"e":66}},"dim":["","list.80","listItem.0"],"code":"- For headings: returns last trail segment (e.g. `\"installation\"`)"},{"id":"/root/children/80/children/0/children/0","type":"paragraph","loc":{"start":11265,"end":11329,"line":{"s":279,"e":279,"code":["- For headings: returns last trail segment (e.g. `\"installation\"`)"]},"column":{"s":2,"e":66}},"dim":["","list.80","listItem.0","paragraph.0"],"code":"For headings: returns last trail segment (e.g. `\"installation\"`)"},{"id":"/root/children/80/children/0/children/0/children/0","type":"text","loc":{"start":11265,"end":11312,"line":{"s":279,"e":279,"code":["- For headings: returns last trail segment (e.g. `\"installation\"`)"]},"column":{"s":2,"e":49}},"dim":["","list.80","listItem.0","paragraph.0","text.0"],"code":"For headings: returns last trail segment (e.g. "},{"id":"/root/children/80/children/0/children/0/children/1","type":"inlineCode","loc":{"start":11312,"end":11328,"line":{"s":279,"e":279,"code":["- For headings: returns last trail segment (e.g. `\"installation\"`)"]},"column":{"s":49,"e":65}},"dim":["","list.80","listItem.0","paragraph.0","inlineCode.1"],"code":"`\"installation\"`"},{"id":"/root/children/80/children/0/children/0/children/2","type":"text","loc":{"start":11328,"end":11329,"line":{"s":279,"e":279,"code":["- For headings: returns last trail segment (e.g. `\"installation\"`)"]},"column":{"s":65,"e":66}},"dim":["","list.80","listItem.0","paragraph.0","text.2"],"code":")"},{"id":"/root/children/80/children/1","type":"listItem","loc":{"start":11330,"end":11390,"line":{"s":280,"e":280,"code":["- For links: returns nomen (link label, e.g. `\"click here\"`)"]},"column":{"s":0,"e":60}},"dim":["","list.80","listItem.1"],"code":"- For links: returns nomen (link label, e.g. `\"click here\"`)"},{"id":"/root/children/80/children/1/children/0","type":"paragraph","loc":{"start":11332,"end":11390,"line":{"s":280,"e":280,"code":["- For links: returns nomen (link label, e.g. `\"click here\"`)"]},"column":{"s":2,"e":60}},"dim":["","list.80","listItem.1","paragraph.0"],"code":"For links: returns nomen (link label, e.g. `\"click here\"`)"},{"id":"/root/children/80/children/1/children/0/children/0","type":"text","loc":{"start":11332,"end":11375,"line":{"s":280,"e":280,"code":["- For links: returns nomen (link label, e.g. `\"click here\"`)"]},"column":{"s":2,"e":45}},"dim":["","list.80","listItem.1","paragraph.0","text.0"],"code":"For links: returns nomen (link label, e.g. "},{"id":"/root/children/80/children/1/children/0/children/1","type":"inlineCode","loc":{"start":11375,"end":11389,"line":{"s":280,"e":280,"code":["- For links: returns nomen (link label, e.g. `\"click here\"`)"]},"column":{"s":45,"e":59}},"dim":["","list.80","listItem.1","paragraph.0","inlineCode.1"],"code":"`\"click here\"`"},{"id":"/root/children/80/children/1/children/0/children/2","type":"text","loc":{"start":11389,"end":11390,"line":{"s":280,"e":280,"code":["- For links: returns nomen (link label, e.g. `\"click here\"`)"]},"column":{"s":59,"e":60}},"dim":["","list.80","listItem.1","paragraph.0","text.2"],"code":")"},{"id":"/root/children/80/children/2","type":"listItem","loc":{"start":11391,"end":11451,"line":{"s":281,"e":281,"code":["- This is the short ref stored in `cache_ast_lake_nodes.ref`"]},"column":{"s":0,"e":60}},"dim":["","list.80","listItem.2"],"code":"- This is the short ref stored in `cache_ast_lake_nodes.ref`"},{"id":"/root/children/80/children/2/children/0","type":"paragraph","loc":{"start":11393,"end":11451,"line":{"s":281,"e":281,"code":["- This is the short ref stored in `cache_ast_lake_nodes.ref`"]},"column":{"s":2,"e":60}},"dim":["","list.80","listItem.2","paragraph.0"],"code":"This is the short ref stored in `cache_ast_lake_nodes.ref`"},{"id":"/root/children/80/children/2/children/0/children/0","type":"text","loc":{"start":11393,"end":11425,"line":{"s":281,"e":281,"code":["- This is the short ref stored in `cache_ast_lake_nodes.ref`"]},"column":{"s":2,"e":34}},"dim":["","list.80","listItem.2","paragraph.0","text.0"],"code":"This is the short ref stored in "},{"id":"/root/children/80/children/2/children/0/children/1","type":"inlineCode","loc":{"start":11425,"end":11451,"line":{"s":281,"e":281,"code":["- This is the short ref stored in `cache_ast_lake_nodes.ref`"]},"column":{"s":34,"e":60}},"dim":["","list.80","listItem.2","paragraph.0","inlineCode.1"],"code":"`cache_ast_lake_nodes.ref`"},{"id":"/root/children/81","type":"paragraph","loc":{"start":11453,"end":11710,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":0,"e":257}},"dim":["","paragraph.81"],"code":"**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."},{"id":"/root/children/81/children/0","type":"strong","loc":{"start":11453,"end":11476,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":0,"e":23}},"dim":["","paragraph.81","strong.0"],"code":"**Why two ref tables?**"},{"id":"/root/children/81/children/0/children/0","type":"text","loc":{"start":11455,"end":11474,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":2,"e":21}},"dim":["","paragraph.81","strong.0","text.0"],"code":"Why two ref tables?"},{"id":"/root/children/81/children/1","type":"text","loc":{"start":11476,"end":11477,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":23,"e":24}},"dim":["","paragraph.81","text.1"],"code":" "},{"id":"/root/children/81/children/2","type":"inlineCode","loc":{"start":11477,"end":11503,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":24,"e":50}},"dim":["","paragraph.81","inlineCode.2"],"code":"`cache_ast_lake_nodes.ref`"},{"id":"/root/children/81/children/3","type":"text","loc":{"start":11503,"end":11554,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":50,"e":101}},"dim":["","paragraph.81","text.3"],"code":" has the short, per-node ref (last trail segment). "},{"id":"/root/children/81/children/4","type":"inlineCode","loc":{"start":11554,"end":11584,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":101,"e":131}},"dim":["","paragraph.81","inlineCode.4"],"code":"`cache_ast_lake_nodes_ref.ref`"},{"id":"/root/children/81/children/5","type":"text","loc":{"start":11584,"end":11698,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":131,"e":245}},"dim":["","paragraph.81","text.5"],"code":" has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from "},{"id":"/root/children/81/children/6","type":"inlineCode","loc":{"start":11698,"end":11709,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":245,"e":256}},"dim":["","paragraph.81","inlineCode.6"],"code":"`nodes_ref`"},{"id":"/root/children/81/children/7","type":"text","loc":{"start":11709,"end":11710,"line":{"s":283,"e":283,"code":["**Why two ref tables?** `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`."]},"column":{"s":256,"e":257}},"dim":["","paragraph.81","text.7"],"code":"."},{"id":"/root/children/82","type":"thematicBreak","loc":{"start":11712,"end":11715,"line":{"s":285,"e":285,"code":["---"]},"column":{"s":0,"e":3}},"dim":["","thematicBreak.82"],"code":"---"},{"id":"/root/children/83","type":"heading","loc":{"start":11717,"end":11750,"line":{"s":287,"e":287,"code":["### `cache_ast_lake_nodes_backup`"]},"column":{"s":0,"e":33}},"dim":["","heading.83"],"code":"### `cache_ast_lake_nodes_backup`","symbName":"heading","symbRange":[11752,12403],"symbRangeL":[287,304],"outerCode":"\n**Role:** Rollback copy. Before updating a file's nodes in `cache_ast_lake_nodes`, the old rows are copied here (ast-lake.mjs:500-514):\n\n```sql\nINSERT OR REPLACE INTO cache_ast_lake_nodes_backup\n (id, value, mt, sem, num1, num2, ref, body)\nSELECT id, value, mt, sem, num1, num2, ref, body\nFROM cache_ast_lake_nodes\nWHERE id LIKE 'Role: Rollback copy. Before updating a file's nodes in `cache_ast_lake_nodes`, the old rows are copied here (ast-lake.mjs:500-514):
\n\n```sql\nINSERT OR REPLACE INTO cache_ast_lake_nodes_backup\n (id, value, mt, sem, num1, num2, ref, body)\nSELECT id, value, mt, sem, num1, num2, ref, body\nFROM cache_ast_lake_nodes\nWHERE id LIKE '
Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored.
\n\nNote: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time.
\n\n;{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
\n\n```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```
\n\nRole: Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.
\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |
\n\nNormalized node value structure (the JSON in the `value` column):
\n\n```json\n{\n \"fn\": \"/home/.../repo/repolero/paper/file.mdd\",\n \"trail\": [\"getting-started\", \"installation\"],\n \"type\": \"heading\",\n \"nomen\": \"Installation\",\n \"code\": \"## Installation\",\n \"symbName\": null,\n \"symbBlame\": [\"abc123def\", \"456ghi789\"],\n \"outerCode\": \"full subtree text...\",\n \"position\": [42, 1],\n \"lineRange\": [42, 85],\n \"offset\": 42,\n \"symbMt\": \"2025-06-15T10:30:00Z\",\n \"symbUser\": \"author@example.com\",\n \"mt\": \"2025-06-15T10:30:00Z\"\n}\n```
\n\nKey normalization details (from `normalizeNodes()` at ast-lake.mjs:183):
\n\nQuery pattern (voting dashboard):
\n\n```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```
\n\nRole: Readable refId mirror of nodes. Stores the user-visible fragment reference string (the one used in URLs and voting) instead of the last-trail-segment ref.
\n\n| Column | How it's populated (ast-lake.mjs:560) | Semantics |\n| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | Same as nodes: `fn:offset` | Joins to `cache_ast_lake_nodes.id` |\n| `sem` | `node.type` | Node type (same as nodes.sem) |\n| `ref` | `buildNodeAbsoluteId(node)` | Readable refId — format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`. Built by `buildNodeAbsoluteId()` (ast-lake.mjs:29) |\n| `body` | `linkUrl` for links, `repoName` for others | For links: the URL target. For headings: the repo name. |
\n\n`buildNodeAbsoluteId()` construction (ast-lake.mjs:29-44):
\n\n`buildNodeRefId()` (ast-lake.mjs:46-48):
\n\nWhy two ref tables? `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`.
\n\nRole: Rollback copy. Before updating a file's nodes in `cache_ast_lake_nodes`, the old rows are copied here (ast-lake.mjs:500-514):
\n\n```sql\nINSERT OR REPLACE INTO cache_ast_lake_nodes_backup\n (id, value, mt, sem, num1, num2, ref, body)\nSELECT id, value, mt, sem, num1, num2, ref, body\nFROM cache_ast_lake_nodes\nWHERE id LIKE '
Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored.
\n\nNote: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time.
\n\nRole: Git blame line-history cache. Maps each line in each file to its git blame metadata (commit hash, author, timestamp). Used by `normalizeNodes()` to attach `symbBlame`/`symbMt`/`symbUser` to each node.
\n\nSchema (commented inline in `ast-lake.mjs:122-131`):
\n\n| Column | Type | Description |\n| ------ | ---------------- | ----------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `fn` | TEXT NOT NULL | File name / path (matches flast.id / nodes fn prefix) |\n| `line` | INTEGER NOT NULL | Line number in the file (1-based) |\n| `hash` | TEXT NOT NULL | Git commit hash from blame |\n| `mt` | TEXT NOT NULL | Commit author timestamp |\n| `user` | TEXT | Author name or email |\n| `json` | TEXT | Additional metadata as JSON blob |
\n\nQuery pattern (in `actualizeNodes()`, ast-lake.mjs:473):
"},{"id":"/root/children/86","type":"paragraph","loc":{"start":12103,"end":12284,"line":{"s":299,"e":299,"code":["Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored."]},"column":{"s":0,"e":181}},"dim":["","paragraph.86"],"code":"Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored."},{"id":"/root/children/86/children/0","type":"text","loc":{"start":12103,"end":12143,"line":{"s":299,"e":299,"code":["Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored."]},"column":{"s":0,"e":40}},"dim":["","paragraph.86","text.0"],"code":"Then the old rows are deleted from both "},{"id":"/root/children/86/children/1","type":"inlineCode","loc":{"start":12143,"end":12165,"line":{"s":299,"e":299,"code":["Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored."]},"column":{"s":40,"e":62}},"dim":["","paragraph.86","inlineCode.1"],"code":"`cache_ast_lake_nodes`"},{"id":"/root/children/86/children/2","type":"text","loc":{"start":12165,"end":12170,"line":{"s":299,"e":299,"code":["Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored."]},"column":{"s":62,"e":67}},"dim":["","paragraph.86","text.2"],"code":" and "},{"id":"/root/children/86/children/3","type":"inlineCode","loc":{"start":12170,"end":12196,"line":{"s":299,"e":299,"code":["Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored."]},"column":{"s":67,"e":93}},"dim":["","paragraph.86","inlineCode.3"],"code":"`cache_ast_lake_nodes_ref`"},{"id":"/root/children/86/children/4","type":"text","loc":{"start":12196,"end":12284,"line":{"s":299,"e":299,"code":["Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored."]},"column":{"s":93,"e":181}},"dim":["","paragraph.86","text.4"],"code":" before inserting the new normalized nodes. If a sync fails, the backup can be restored."},{"id":"/root/children/87","type":"paragraph","loc":{"start":12286,"end":12398,"line":{"s":301,"e":301,"code":["Note: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time."]},"column":{"s":0,"e":112}},"dim":["","paragraph.87"],"code":"Note: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time."},{"id":"/root/children/87/children/0","type":"text","loc":{"start":12286,"end":12292,"line":{"s":301,"e":301,"code":["Note: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time."]},"column":{"s":0,"e":6}},"dim":["","paragraph.87","text.0"],"code":"Note: "},{"id":"/root/children/87/children/1","type":"inlineCode","loc":{"start":12292,"end":12318,"line":{"s":301,"e":301,"code":["Note: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time."]},"column":{"s":6,"e":32}},"dim":["","paragraph.87","inlineCode.1"],"code":"`cache_ast_lake_nodes_ref`"},{"id":"/root/children/87/children/2","type":"text","loc":{"start":12318,"end":12398,"line":{"s":301,"e":301,"code":["Note: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time."]},"column":{"s":32,"e":112}},"dim":["","paragraph.87","text.2"],"code":" does NOT have a backup table — the ref table is rebuilt from scratch each time."},{"id":"/root/children/88","type":"thematicBreak","loc":{"start":12400,"end":12403,"line":{"s":303,"e":303,"code":["---"]},"column":{"s":0,"e":3}},"dim":["","thematicBreak.88"],"code":"---"},{"id":"/root/children/89","type":"heading","loc":{"start":12405,"end":12418,"line":{"s":305,"e":305,"code":["## `linetime`"]},"column":{"s":0,"e":13}},"dim":["","heading.89"],"code":"## `linetime`","symbName":"heading","symbRange":[12420,13888],"symbRangeL":[305,333],"outerCode":"\n**Role:** Git blame line-history cache. Maps each line in each file to its git blame metadata (commit hash, author, timestamp). Used by `normalizeNodes()` to attach `symbBlame`/`symbMt`/`symbUser` to each node.\n\nSchema (commented inline in `ast-lake.mjs:122-131`):\n\n| Column | Type | Description |\n| ------ | ---------------- | ----------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `fn` | TEXT NOT NULL | File name / path (matches flast.id / nodes fn prefix) |\n| `line` | INTEGER NOT NULL | Line number in the file (1-based) |\n| `hash` | TEXT NOT NULL | Git commit hash from blame |\n| `mt` | TEXT NOT NULL | Commit author timestamp |\n| `user` | TEXT | Author name or email |\n| `json` | TEXT | Additional metadata as JSON blob |\n\n**Query pattern** (in `actualizeNodes()`, ast-lake.mjs:473):\n\n```sql\nSELECT line, mt, user, hash FROM linetime\nWHERE fn='Role: Git blame line-history cache. Maps each line in each file to its git blame metadata (commit hash, author, timestamp). Used by `normalizeNodes()` to attach `symbBlame`/`symbMt`/`symbUser` to each node.
\n\nSchema (commented inline in `ast-lake.mjs:122-131`):
\n\n| Column | Type | Description |\n| ------ | ---------------- | ----------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `fn` | TEXT NOT NULL | File name / path (matches flast.id / nodes fn prefix) |\n| `line` | INTEGER NOT NULL | Line number in the file (1-based) |\n| `hash` | TEXT NOT NULL | Git commit hash from blame |\n| `mt` | TEXT NOT NULL | Commit author timestamp |\n| `user` | TEXT | Author name or email |\n| `json` | TEXT | Additional metadata as JSON blob |
\n\nQuery pattern (in `actualizeNodes()`, ast-lake.mjs:473):
\n\n```sql\nSELECT line, mt, user, hash FROM linetime\nWHERE fn='
The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range.
\n\nSee `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows.
\n\n;{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
\n\n```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```
\n\nRole: Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.
\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |
\n\nNormalized node value structure (the JSON in the `value` column):
\n\n```json\n{\n \"fn\": \"/home/.../repo/repolero/paper/file.mdd\",\n \"trail\": [\"getting-started\", \"installation\"],\n \"type\": \"heading\",\n \"nomen\": \"Installation\",\n \"code\": \"## Installation\",\n \"symbName\": null,\n \"symbBlame\": [\"abc123def\", \"456ghi789\"],\n \"outerCode\": \"full subtree text...\",\n \"position\": [42, 1],\n \"lineRange\": [42, 85],\n \"offset\": 42,\n \"symbMt\": \"2025-06-15T10:30:00Z\",\n \"symbUser\": \"author@example.com\",\n \"mt\": \"2025-06-15T10:30:00Z\"\n}\n```
\n\nKey normalization details (from `normalizeNodes()` at ast-lake.mjs:183):
\n\nQuery pattern (voting dashboard):
\n\n```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```
\n\nRole: Readable refId mirror of nodes. Stores the user-visible fragment reference string (the one used in URLs and voting) instead of the last-trail-segment ref.
\n\n| Column | How it's populated (ast-lake.mjs:560) | Semantics |\n| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | Same as nodes: `fn:offset` | Joins to `cache_ast_lake_nodes.id` |\n| `sem` | `node.type` | Node type (same as nodes.sem) |\n| `ref` | `buildNodeAbsoluteId(node)` | Readable refId — format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`. Built by `buildNodeAbsoluteId()` (ast-lake.mjs:29) |\n| `body` | `linkUrl` for links, `repoName` for others | For links: the URL target. For headings: the repo name. |
\n\n`buildNodeAbsoluteId()` construction (ast-lake.mjs:29-44):
\n\n`buildNodeRefId()` (ast-lake.mjs:46-48):
\n\nWhy two ref tables? `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`.
\n\nRole: Rollback copy. Before updating a file's nodes in `cache_ast_lake_nodes`, the old rows are copied here (ast-lake.mjs:500-514):
\n\n```sql\nINSERT OR REPLACE INTO cache_ast_lake_nodes_backup\n (id, value, mt, sem, num1, num2, ref, body)\nSELECT id, value, mt, sem, num1, num2, ref, body\nFROM cache_ast_lake_nodes\nWHERE id LIKE '
Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored.
\n\nNote: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time.
\n\nRole: Git blame line-history cache. Maps each line in each file to its git blame metadata (commit hash, author, timestamp). Used by `normalizeNodes()` to attach `symbBlame`/`symbMt`/`symbUser` to each node.
\n\nSchema (commented inline in `ast-lake.mjs:122-131`):
\n\n| Column | Type | Description |\n| ------ | ---------------- | ----------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `fn` | TEXT NOT NULL | File name / path (matches flast.id / nodes fn prefix) |\n| `line` | INTEGER NOT NULL | Line number in the file (1-based) |\n| `hash` | TEXT NOT NULL | Git commit hash from blame |\n| `mt` | TEXT NOT NULL | Commit author timestamp |\n| `user` | TEXT | Author name or email |\n| `json` | TEXT | Additional metadata as JSON blob |
\n\nQuery pattern (in `actualizeNodes()`, ast-lake.mjs:473):
\n\n```sql\nSELECT line, mt, user, hash FROM linetime\nWHERE fn='
The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range.
\n\nSee `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows.
\n\nRole: Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`.
\n\n| Column | Type | Description |\n| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `d` | TEXT NOT NULL | ISO timestamp of the vote event |\n| `user` | TEXT | Voter identifier (username or email) |\n| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |\n| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |\n| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |\n| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |\n| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |\n| `json` | TEXT | Additional payload as JSON blob |
\n\nIndexes: `num1`, `num2`, `campaign`, `operation`, `ref`.
\n\nKey query patterns:
\n\nDashboard voting (count per ref):
"},{"id":"/root/children/95","type":"paragraph","loc":{"start":13626,"end":13757,"line":{"s":328,"e":328,"code":["The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range."]},"column":{"s":0,"e":131}},"dim":["","paragraph.95"],"code":"The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range."},{"id":"/root/children/95/children/0","type":"text","loc":{"start":13626,"end":13656,"line":{"s":328,"e":328,"code":["The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range."]},"column":{"s":0,"e":30}},"dim":["","paragraph.95","text.0"],"code":"The result is used to compute "},{"id":"/root/children/95/children/1","type":"inlineCode","loc":{"start":13656,"end":13668,"line":{"s":328,"e":328,"code":["The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range."]},"column":{"s":30,"e":42}},"dim":["","paragraph.95","inlineCode.1"],"code":"`symbRangeL`"},{"id":"/root/children/95/children/2","type":"text","loc":{"start":13668,"end":13671,"line":{"s":328,"e":328,"code":["The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range."]},"column":{"s":42,"e":45}},"dim":["","paragraph.95","text.2"],"code":" → "},{"id":"/root/children/95/children/3","type":"inlineCode","loc":{"start":13671,"end":13682,"line":{"s":328,"e":328,"code":["The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range."]},"column":{"s":45,"e":56}},"dim":["","paragraph.95","inlineCode.3"],"code":"`symbBlame`"},{"id":"/root/children/95/children/4","type":"text","loc":{"start":13682,"end":13757,"line":{"s":328,"e":328,"code":["The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range."]},"column":{"s":56,"e":131}},"dim":["","paragraph.95","text.4"],"code":" for each node: all commit hashes for lines within the node's source range."},{"id":"/root/children/96","type":"paragraph","loc":{"start":13759,"end":13883,"line":{"s":330,"e":330,"code":["See `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows."]},"column":{"s":0,"e":124}},"dim":["","paragraph.96"],"code":"See `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows."},{"id":"/root/children/96/children/0","type":"text","loc":{"start":13759,"end":13763,"line":{"s":330,"e":330,"code":["See `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows."]},"column":{"s":0,"e":4}},"dim":["","paragraph.96","text.0"],"code":"See "},{"id":"/root/children/96/children/1","type":"inlineCode","loc":{"start":13763,"end":13788,"line":{"s":330,"e":330,"code":["See `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows."]},"column":{"s":4,"e":29}},"dim":["","paragraph.96","inlineCode.1"],"code":"`linetime-parse-blame.jq`"},{"id":"/root/children/96/children/2","type":"text","loc":{"start":13788,"end":13826,"line":{"s":330,"e":330,"code":["See `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows."]},"column":{"s":29,"e":67}},"dim":["","paragraph.96","text.2"],"code":" for the processing logic that parses "},{"id":"/root/children/96/children/3","type":"inlineCode","loc":{"start":13826,"end":13854,"line":{"s":330,"e":330,"code":["See `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows."]},"column":{"s":67,"e":95}},"dim":["","paragraph.96","inlineCode.3"],"code":"`git blame --line-porcelain`"},{"id":"/root/children/96/children/4","type":"text","loc":{"start":13854,"end":13867,"line":{"s":330,"e":330,"code":["See `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows."]},"column":{"s":95,"e":108}},"dim":["","paragraph.96","text.4"],"code":" output into "},{"id":"/root/children/96/children/5","type":"inlineCode","loc":{"start":13867,"end":13877,"line":{"s":330,"e":330,"code":["See `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows."]},"column":{"s":108,"e":118}},"dim":["","paragraph.96","inlineCode.5"],"code":"`linetime`"},{"id":"/root/children/96/children/6","type":"text","loc":{"start":13877,"end":13883,"line":{"s":330,"e":330,"code":["See `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows."]},"column":{"s":118,"e":124}},"dim":["","paragraph.96","text.6"],"code":" rows."},{"id":"/root/children/97","type":"thematicBreak","loc":{"start":13885,"end":13888,"line":{"s":332,"e":332,"code":["---"]},"column":{"s":0,"e":3}},"dim":["","thematicBreak.97"],"code":"---"},{"id":"/root/children/98","type":"heading","loc":{"start":13890,"end":13906,"line":{"s":334,"e":334,"code":["## `repo_voting`"]},"column":{"s":0,"e":16}},"dim":["","heading.98"],"code":"## `repo_voting`","symbName":"heading","symbRange":[13908,16362],"symbRangeL":[334,373],"outerCode":"\n**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`.\n\n| Column | Type | Description |\n| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `d` | TEXT NOT NULL | ISO timestamp of the vote event |\n| `user` | TEXT | Voter identifier (username or email) |\n| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |\n| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |\n| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |\n| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |\n| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |\n| `json` | TEXT | Additional payload as JSON blob |\n\n**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`.\n\n**Key query patterns:**\n\nDashboard voting (count per ref):\n\n```sql\nSELECT ref, operation, COUNT(*) as count, SUM(num1) as total\nFROM repo_voting\nWHERE campaign = 'eisenhower'\nGROUP BY ref, operation\n```\n\nHeading-changes metadata check (`hasMetaData`):\n\n```sql\nSELECT DISTINCT ref FROM repo_voting\nWHERE ref IN ('ref1', 'ref2', ...)\n```\n\n**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`.\n\n**Cleanup on file deletion** (ast-lake.mjs `cleanup()` at line 305):","outerHtml":"\nRole: Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`.
\n\n| Column | Type | Description |\n| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `d` | TEXT NOT NULL | ISO timestamp of the vote event |\n| `user` | TEXT | Voter identifier (username or email) |\n| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |\n| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |\n| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |\n| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |\n| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |\n| `json` | TEXT | Additional payload as JSON blob |
\n\nIndexes: `num1`, `num2`, `campaign`, `operation`, `ref`.
\n\nKey query patterns:
\n\nDashboard voting (count per ref):
\n\n```sql\nSELECT ref, operation, COUNT(*) as count, SUM(num1) as total\nFROM repo_voting\nWHERE campaign = 'eisenhower'\nGROUP BY ref, operation\n```
\n\nHeading-changes metadata check (`hasMetaData`):
\n\n```sql\nSELECT DISTINCT ref FROM repo_voting\nWHERE ref IN ('ref1', 'ref2', ...)\n```
\n\nref format: Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`.
\n\nCleanup on file deletion (ast-lake.mjs `cleanup()` at line 305):
"},{"id":"/root/children/98/children/0","type":"inlineCode","loc":{"start":13893,"end":13906,"line":{"s":334,"e":334,"code":["## `repo_voting`"]},"column":{"s":3,"e":16}},"dim":["","heading.98","inlineCode.0"],"code":"`repo_voting`"},{"id":"/root/children/99","type":"paragraph","loc":{"start":13908,"end":14097,"line":{"s":336,"e":336,"code":["**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`."]},"column":{"s":0,"e":189}},"dim":["","paragraph.99"],"code":"**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`."},{"id":"/root/children/99/children/0","type":"strong","loc":{"start":13908,"end":13917,"line":{"s":336,"e":336,"code":["**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`."]},"column":{"s":0,"e":9}},"dim":["","paragraph.99","strong.0"],"code":"**Role:**"},{"id":"/root/children/99/children/0/children/0","type":"text","loc":{"start":13910,"end":13915,"line":{"s":336,"e":336,"code":["**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`."]},"column":{"s":2,"e":7}},"dim":["","paragraph.99","strong.0","text.0"],"code":"Role:"},{"id":"/root/children/99/children/1","type":"text","loc":{"start":13917,"end":14039,"line":{"s":336,"e":336,"code":["**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`."]},"column":{"s":9,"e":131}},"dim":["","paragraph.99","text.1"],"code":" Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from "},{"id":"/root/children/99/children/2","type":"inlineCode","loc":{"start":14039,"end":14075,"line":{"s":336,"e":336,"code":["**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`."]},"column":{"s":131,"e":167}},"dim":["","paragraph.99","inlineCode.2"],"code":"`sqlCreateTableEventSource(tblName)`"},{"id":"/root/children/99/children/3","type":"text","loc":{"start":14075,"end":14079,"line":{"s":336,"e":336,"code":["**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`."]},"column":{"s":167,"e":171}},"dim":["","paragraph.99","text.3"],"code":" in "},{"id":"/root/children/99/children/4","type":"inlineCode","loc":{"start":14079,"end":14096,"line":{"s":336,"e":336,"code":["**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`."]},"column":{"s":171,"e":188}},"dim":["","paragraph.99","inlineCode.4"],"code":"`ast-lake.mjs:85`"},{"id":"/root/children/99/children/5","type":"text","loc":{"start":14096,"end":14097,"line":{"s":336,"e":336,"code":["**Role:** Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`."]},"column":{"s":188,"e":189}},"dim":["","paragraph.99","text.5"],"code":"."},{"id":"/root/children/100","type":"paragraph","loc":{"start":14099,"end":15682,"line":{"s":338,"e":348,"code":["| Column | Type | Description |","| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |","| `id` | INTEGER | Primary key, autoincrement |","| `d` | TEXT NOT NULL | ISO timestamp of the vote event |","| `user` | TEXT | Voter identifier (username or email) |","| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |","| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |","| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |","| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |","| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |","| `json` | TEXT | Additional payload as JSON blob |"]},"column":{"s":0,"e":143}},"dim":["","paragraph.100"],"code":"| Column | Type | Description |\n| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `d` | TEXT NOT NULL | ISO timestamp of the vote event |\n| `user` | TEXT | Voter identifier (username or email) |\n| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |\n| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |\n| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |\n| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |\n| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |\n| `json` | TEXT | Additional payload as JSON blob |"},{"id":"/root/children/100/children/0","type":"text","loc":{"start":14099,"end":14389,"line":{"s":338,"e":340,"code":["| Column | Type | Description |","| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |","| `id` | INTEGER | Primary key, autoincrement |"]},"column":{"s":0,"e":2}},"dim":["","paragraph.100","text.0"],"code":"| Column | Type | Description |\n| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |\n| "},{"id":"/root/children/100/children/1","type":"inlineCode","loc":{"start":14389,"end":14393,"line":{"s":340,"e":340,"code":["| `id` | INTEGER | Primary key, autoincrement |"]},"column":{"s":2,"e":6}},"dim":["","paragraph.100","inlineCode.1"],"code":"`id`"},{"id":"/root/children/100/children/2","type":"text","loc":{"start":14393,"end":14533,"line":{"s":340,"e":341,"code":["| `id` | INTEGER | Primary key, autoincrement |","| `d` | TEXT NOT NULL | ISO timestamp of the vote event |"]},"column":{"s":6,"e":2}},"dim":["","paragraph.100","text.2"],"code":" | INTEGER | Primary key, autoincrement |\n| "},{"id":"/root/children/100/children/3","type":"inlineCode","loc":{"start":14533,"end":14536,"line":{"s":341,"e":341,"code":["| `d` | TEXT NOT NULL | ISO timestamp of the vote event |"]},"column":{"s":2,"e":5}},"dim":["","paragraph.100","inlineCode.3"],"code":"`d`"},{"id":"/root/children/100/children/4","type":"text","loc":{"start":14536,"end":14677,"line":{"s":341,"e":342,"code":["| `d` | TEXT NOT NULL | ISO timestamp of the vote event |","| `user` | TEXT | Voter identifier (username or email) |"]},"column":{"s":5,"e":2}},"dim":["","paragraph.100","text.4"],"code":" | TEXT NOT NULL | ISO timestamp of the vote event |\n| "},{"id":"/root/children/100/children/5","type":"inlineCode","loc":{"start":14677,"end":14683,"line":{"s":342,"e":342,"code":["| `user` | TEXT | Voter identifier (username or email) |"]},"column":{"s":2,"e":8}},"dim":["","paragraph.100","inlineCode.5"],"code":"`user`"},{"id":"/root/children/100/children/6","type":"text","loc":{"start":14683,"end":14821,"line":{"s":342,"e":343,"code":["| `user` | TEXT | Voter identifier (username or email) |","| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |"]},"column":{"s":8,"e":2}},"dim":["","paragraph.100","text.6"],"code":" | TEXT | Voter identifier (username or email) |\n| "},{"id":"/root/children/100/children/7","type":"inlineCode","loc":{"start":14821,"end":14826,"line":{"s":343,"e":343,"code":["| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |"]},"column":{"s":2,"e":7}},"dim":["","paragraph.100","inlineCode.7"],"code":"`ref`"},{"id":"/root/children/100/children/8","type":"text","loc":{"start":14826,"end":14893,"line":{"s":343,"e":343,"code":["| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |"]},"column":{"s":7,"e":74}},"dim":["","paragraph.100","text.8"],"code":" | TEXT NOT NULL | Fragment refId being voted on (matches "},{"id":"/root/children/100/children/9","type":"inlineCode","loc":{"start":14893,"end":14923,"line":{"s":343,"e":343,"code":["| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |"]},"column":{"s":74,"e":104}},"dim":["","paragraph.100","inlineCode.9"],"code":"`cache_ast_lake_nodes_ref.ref`"},{"id":"/root/children/100/children/10","type":"text","loc":{"start":14923,"end":14965,"line":{"s":343,"e":344,"code":["| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |","| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |"]},"column":{"s":104,"e":2}},"dim":["","paragraph.100","text.10"],"code":") |\n| "},{"id":"/root/children/100/children/11","type":"inlineCode","loc":{"start":14965,"end":14975,"line":{"s":344,"e":344,"code":["| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |"]},"column":{"s":2,"e":12}},"dim":["","paragraph.100","inlineCode.11"],"code":"`campaign`"},{"id":"/root/children/100/children/12","type":"text","loc":{"start":14975,"end":15056,"line":{"s":344,"e":344,"code":["| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |"]},"column":{"s":12,"e":93}},"dim":["","paragraph.100","text.12"],"code":" | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. "},{"id":"/root/children/100/children/13","type":"inlineCode","loc":{"start":15056,"end":15070,"line":{"s":344,"e":344,"code":["| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |"]},"column":{"s":93,"e":107}},"dim":["","paragraph.100","inlineCode.13"],"code":"`\"eisenhower\"`"},{"id":"/root/children/100/children/14","type":"text","loc":{"start":15070,"end":15072,"line":{"s":344,"e":344,"code":["| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |"]},"column":{"s":107,"e":109}},"dim":["","paragraph.100","text.14"],"code":", "},{"id":"/root/children/100/children/15","type":"inlineCode","loc":{"start":15072,"end":15082,"line":{"s":344,"e":344,"code":["| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |"]},"column":{"s":109,"e":119}},"dim":["","paragraph.100","inlineCode.15"],"code":"`\"debate\"`"},{"id":"/root/children/100/children/16","type":"text","loc":{"start":15082,"end":15084,"line":{"s":344,"e":344,"code":["| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |"]},"column":{"s":119,"e":121}},"dim":["","paragraph.100","text.16"],"code":", "},{"id":"/root/children/100/children/17","type":"inlineCode","loc":{"start":15084,"end":15103,"line":{"s":344,"e":344,"code":["| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |"]},"column":{"s":121,"e":140}},"dim":["","paragraph.100","inlineCode.17"],"code":"`\"heading-changes\"`"},{"id":"/root/children/100/children/18","type":"text","loc":{"start":15103,"end":15109,"line":{"s":344,"e":345,"code":["| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |","| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":140,"e":2}},"dim":["","paragraph.100","text.18"],"code":") |\n| "},{"id":"/root/children/100/children/19","type":"inlineCode","loc":{"start":15109,"end":15120,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":2,"e":13}},"dim":["","paragraph.100","inlineCode.19"],"code":"`operation`"},{"id":"/root/children/100/children/20","type":"text","loc":{"start":15120,"end":15184,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":13,"e":77}},"dim":["","paragraph.100","text.20"],"code":" | TEXT NOT NULL | Vote operation — quadrant or action (e.g. "},{"id":"/root/children/100/children/21","type":"inlineCode","loc":{"start":15184,"end":15191,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":77,"e":84}},"dim":["","paragraph.100","inlineCode.21"],"code":"`\"hot\"`"},{"id":"/root/children/100/children/22","type":"text","loc":{"start":15191,"end":15193,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":84,"e":86}},"dim":["","paragraph.100","text.22"],"code":", "},{"id":"/root/children/100/children/23","type":"inlineCode","loc":{"start":15193,"end":15200,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":86,"e":93}},"dim":["","paragraph.100","inlineCode.23"],"code":"`\"pin\"`"},{"id":"/root/children/100/children/24","type":"text","loc":{"start":15200,"end":15202,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":93,"e":95}},"dim":["","paragraph.100","text.24"],"code":", "},{"id":"/root/children/100/children/25","type":"inlineCode","loc":{"start":15202,"end":15210,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":95,"e":103}},"dim":["","paragraph.100","inlineCode.25"],"code":"`\"weak\"`"},{"id":"/root/children/100/children/26","type":"text","loc":{"start":15210,"end":15212,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":103,"e":105}},"dim":["","paragraph.100","text.26"],"code":", "},{"id":"/root/children/100/children/27","type":"inlineCode","loc":{"start":15212,"end":15220,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":105,"e":113}},"dim":["","paragraph.100","inlineCode.27"],"code":"`\"veto\"`"},{"id":"/root/children/100/children/28","type":"text","loc":{"start":15220,"end":15222,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":113,"e":115}},"dim":["","paragraph.100","text.28"],"code":", "},{"id":"/root/children/100/children/29","type":"inlineCode","loc":{"start":15222,"end":15230,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":115,"e":123}},"dim":["","paragraph.100","inlineCode.29"],"code":"`\"cast\"`"},{"id":"/root/children/100/children/30","type":"text","loc":{"start":15230,"end":15232,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":123,"e":125}},"dim":["","paragraph.100","text.30"],"code":", "},{"id":"/root/children/100/children/31","type":"inlineCode","loc":{"start":15232,"end":15242,"line":{"s":345,"e":345,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |"]},"column":{"s":125,"e":135}},"dim":["","paragraph.100","inlineCode.31"],"code":"`\"uncast\"`"},{"id":"/root/children/100/children/32","type":"text","loc":{"start":15242,"end":15253,"line":{"s":345,"e":346,"code":["| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |","| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |"]},"column":{"s":135,"e":2}},"dim":["","paragraph.100","text.32"],"code":") |\n| "},{"id":"/root/children/100/children/33","type":"inlineCode","loc":{"start":15253,"end":15259,"line":{"s":346,"e":346,"code":["| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |"]},"column":{"s":2,"e":8}},"dim":["","paragraph.100","inlineCode.33"],"code":"`num1`"},{"id":"/root/children/100/children/34","type":"text","loc":{"start":15259,"end":15397,"line":{"s":346,"e":347,"code":["| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |","| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |"]},"column":{"s":8,"e":2}},"dim":["","paragraph.100","text.34"],"code":" | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |\n| "},{"id":"/root/children/100/children/35","type":"inlineCode","loc":{"start":15397,"end":15403,"line":{"s":347,"e":347,"code":["| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |"]},"column":{"s":2,"e":8}},"dim":["","paragraph.100","inlineCode.35"],"code":"`num2`"},{"id":"/root/children/100/children/36","type":"text","loc":{"start":15403,"end":15541,"line":{"s":347,"e":348,"code":["| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |","| `json` | TEXT | Additional payload as JSON blob |"]},"column":{"s":8,"e":2}},"dim":["","paragraph.100","text.36"],"code":" | INTEGER NOT NULL | Generic numeric slot — used for secondary count |\n| "},{"id":"/root/children/100/children/37","type":"inlineCode","loc":{"start":15541,"end":15547,"line":{"s":348,"e":348,"code":["| `json` | TEXT | Additional payload as JSON blob |"]},"column":{"s":2,"e":8}},"dim":["","paragraph.100","inlineCode.37"],"code":"`json`"},{"id":"/root/children/100/children/38","type":"text","loc":{"start":15547,"end":15682,"line":{"s":348,"e":348,"code":["| `json` | TEXT | Additional payload as JSON blob |"]},"column":{"s":8,"e":143}},"dim":["","paragraph.100","text.38"],"code":" | TEXT | Additional payload as JSON blob |"},{"id":"/root/children/101","type":"paragraph","loc":{"start":15684,"end":15744,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":0,"e":60}},"dim":["","paragraph.101"],"code":"**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."},{"id":"/root/children/101/children/0","type":"strong","loc":{"start":15684,"end":15696,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":0,"e":12}},"dim":["","paragraph.101","strong.0"],"code":"**Indexes:**"},{"id":"/root/children/101/children/0/children/0","type":"text","loc":{"start":15686,"end":15694,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":2,"e":10}},"dim":["","paragraph.101","strong.0","text.0"],"code":"Indexes:"},{"id":"/root/children/101/children/1","type":"text","loc":{"start":15696,"end":15697,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":12,"e":13}},"dim":["","paragraph.101","text.1"],"code":" "},{"id":"/root/children/101/children/2","type":"inlineCode","loc":{"start":15697,"end":15703,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":13,"e":19}},"dim":["","paragraph.101","inlineCode.2"],"code":"`num1`"},{"id":"/root/children/101/children/3","type":"text","loc":{"start":15703,"end":15705,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":19,"e":21}},"dim":["","paragraph.101","text.3"],"code":", "},{"id":"/root/children/101/children/4","type":"inlineCode","loc":{"start":15705,"end":15711,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":21,"e":27}},"dim":["","paragraph.101","inlineCode.4"],"code":"`num2`"},{"id":"/root/children/101/children/5","type":"text","loc":{"start":15711,"end":15713,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":27,"e":29}},"dim":["","paragraph.101","text.5"],"code":", "},{"id":"/root/children/101/children/6","type":"inlineCode","loc":{"start":15713,"end":15723,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":29,"e":39}},"dim":["","paragraph.101","inlineCode.6"],"code":"`campaign`"},{"id":"/root/children/101/children/7","type":"text","loc":{"start":15723,"end":15725,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":39,"e":41}},"dim":["","paragraph.101","text.7"],"code":", "},{"id":"/root/children/101/children/8","type":"inlineCode","loc":{"start":15725,"end":15736,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":41,"e":52}},"dim":["","paragraph.101","inlineCode.8"],"code":"`operation`"},{"id":"/root/children/101/children/9","type":"text","loc":{"start":15736,"end":15738,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":52,"e":54}},"dim":["","paragraph.101","text.9"],"code":", "},{"id":"/root/children/101/children/10","type":"inlineCode","loc":{"start":15738,"end":15743,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":54,"e":59}},"dim":["","paragraph.101","inlineCode.10"],"code":"`ref`"},{"id":"/root/children/101/children/11","type":"text","loc":{"start":15743,"end":15744,"line":{"s":350,"e":350,"code":["**Indexes:** `num1`, `num2`, `campaign`, `operation`, `ref`."]},"column":{"s":59,"e":60}},"dim":["","paragraph.101","text.11"],"code":"."},{"id":"/root/children/102","type":"paragraph","loc":{"start":15746,"end":15769,"line":{"s":352,"e":352,"code":["**Key query patterns:**"]},"column":{"s":0,"e":23}},"dim":["","paragraph.102"],"code":"**Key query patterns:**"},{"id":"/root/children/102/children/0","type":"strong","loc":{"start":15746,"end":15769,"line":{"s":352,"e":352,"code":["**Key query patterns:**"]},"column":{"s":0,"e":23}},"dim":["","paragraph.102","strong.0"],"code":"**Key query patterns:**"},{"id":"/root/children/102/children/0/children/0","type":"text","loc":{"start":15748,"end":15767,"line":{"s":352,"e":352,"code":["**Key query patterns:**"]},"column":{"s":2,"e":21}},"dim":["","paragraph.102","strong.0","text.0"],"code":"Key query patterns:"},{"id":"/root/children/103","type":"paragraph","loc":{"start":15771,"end":15804,"line":{"s":354,"e":354,"code":["Dashboard voting (count per ref):"]},"column":{"s":0,"e":33}},"dim":["","paragraph.103"],"code":"Dashboard voting (count per ref):"},{"id":"/root/children/103/children/0","type":"text","loc":{"start":15771,"end":15804,"line":{"s":354,"e":354,"code":["Dashboard voting (count per ref):"]},"column":{"s":0,"e":33}},"dim":["","paragraph.103","text.0"],"code":"Dashboard voting (count per ref):"},{"id":"/root/children/104","type":"code","loc":{"start":15806,"end":15948,"line":{"s":356,"e":361,"code":["```sql","SELECT ref, operation, COUNT(*) as count, SUM(num1) as total","FROM repo_voting","WHERE campaign = 'eisenhower'","GROUP BY ref, operation","```"]},"column":{"s":0,"e":3}},"dim":["","code.104"],"code":"```sql\nSELECT ref, operation, COUNT(*) as count, SUM(num1) as total\nFROM repo_voting\nWHERE campaign = 'eisenhower'\nGROUP BY ref, operation\n```","symbName":"code","symbRange":[15950,15997],"symbRangeL":[null,364],"outerCode":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }\n\n# ast-lake\n\nusage: ast-lake [command] [args...]\n\n- [123](http://xxx)\n- [xxx](#/papers/@dashboard)\n\n## commands:\n\n### info\n\n- info on the state of ast-lake\n\n### init\n\n- precreate the cache db\n\n### reset\n\n- delete list\n- delete all cached data\n\n### cleanup\n\n- remove non existent files from sqlite cache\n\n### restart\n\n- keep list\n- delete all cached data\n\n#### reset-nodes\n\n- cleanup only cached nodes (dev)\n- and recreated them\n\n### add\n\n- add files to list\n- dbPopulateList is a temporary list file, listing absolute file paths\n- dbPopulateList is usually `/tmp/ast-list.txt`\n- add absolute file paths:\n- note: does use `fd`. honors `.gitignore`\n- usage:\n\n```bash\nast-lake add '*.mdd' '*.json'\n```\n\n- will add `**/*.mdd` and `*.json` to list\n\n- or manually:\n- you may edit $dbPopulateList\n\n```bash\n# --base-directory $dir\n\nfd --absolute-path -tf \".+[.](mdd)$\" | rg -v test > $dbPopulateList\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList\n\n# or only add arbitrary files:\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList\n\n```\n\n- see also `ast-lake populate`\n\n### populate\n\n- ensure all ast's (from on the list) are up to date\n\n### query TERM\n\n- ast-lake query term\n- TODO term patterns ?\n- TODO regex: ^cs.+$\n\n### queryraw TERM\n\n- same as query, but returns raw JSON\n\n### flast\n\n- basically a dump\n- print all raw flASTs\n\n### nodes\n\n- print raw nodes\n\n### mdg\n\n- TODO really?\n- make one big mdg graph from all mdd's\n\n### mosaic\n\n- mosaic\n- TODO really?\n\n### mprocs\n\n- TODO support mprocs\n\n## recent updates\n\n### 2025-12-01\n\n- actualizeNodes: chunked parallel processing\n- chunk size: CPU count / 2\n- faster database query processing\n\n# db tables\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.\n\n**Two parallel implementations exist:**\n\n- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files\n- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.\n\n## The pipeline (how data flows)\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```\n\n## `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but **each column has different semantics per table**:\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |\n\n**Shared indexes:** `num1`, `num2`, `sem`, `ref` (each named `{table}_idx_{col}`).\n\n---\n\n### `cache_ast_lake_flast`\n\n**Role:** Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |\n\n**How it's populated:** Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.\n\n**Query pattern** (in `actualizeNodes()`):\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >;{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
\n\n```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```
\n\nRole: Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.
\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |
\n\nNormalized node value structure (the JSON in the `value` column):
\n\n```json\n{\n \"fn\": \"/home/.../repo/repolero/paper/file.mdd\",\n \"trail\": [\"getting-started\", \"installation\"],\n \"type\": \"heading\",\n \"nomen\": \"Installation\",\n \"code\": \"## Installation\",\n \"symbName\": null,\n \"symbBlame\": [\"abc123def\", \"456ghi789\"],\n \"outerCode\": \"full subtree text...\",\n \"position\": [42, 1],\n \"lineRange\": [42, 85],\n \"offset\": 42,\n \"symbMt\": \"2025-06-15T10:30:00Z\",\n \"symbUser\": \"author@example.com\",\n \"mt\": \"2025-06-15T10:30:00Z\"\n}\n```
\n\nKey normalization details (from `normalizeNodes()` at ast-lake.mjs:183):
\n\nQuery pattern (voting dashboard):
\n\n```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```
\n\nRole: Readable refId mirror of nodes. Stores the user-visible fragment reference string (the one used in URLs and voting) instead of the last-trail-segment ref.
\n\n| Column | How it's populated (ast-lake.mjs:560) | Semantics |\n| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | Same as nodes: `fn:offset` | Joins to `cache_ast_lake_nodes.id` |\n| `sem` | `node.type` | Node type (same as nodes.sem) |\n| `ref` | `buildNodeAbsoluteId(node)` | Readable refId — format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`. Built by `buildNodeAbsoluteId()` (ast-lake.mjs:29) |\n| `body` | `linkUrl` for links, `repoName` for others | For links: the URL target. For headings: the repo name. |
\n\n`buildNodeAbsoluteId()` construction (ast-lake.mjs:29-44):
\n\n`buildNodeRefId()` (ast-lake.mjs:46-48):
\n\nWhy two ref tables? `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`.
\n\nRole: Rollback copy. Before updating a file's nodes in `cache_ast_lake_nodes`, the old rows are copied here (ast-lake.mjs:500-514):
\n\n```sql\nINSERT OR REPLACE INTO cache_ast_lake_nodes_backup\n (id, value, mt, sem, num1, num2, ref, body)\nSELECT id, value, mt, sem, num1, num2, ref, body\nFROM cache_ast_lake_nodes\nWHERE id LIKE '
Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored.
\n\nNote: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time.
\n\nRole: Git blame line-history cache. Maps each line in each file to its git blame metadata (commit hash, author, timestamp). Used by `normalizeNodes()` to attach `symbBlame`/`symbMt`/`symbUser` to each node.
\n\nSchema (commented inline in `ast-lake.mjs:122-131`):
\n\n| Column | Type | Description |\n| ------ | ---------------- | ----------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `fn` | TEXT NOT NULL | File name / path (matches flast.id / nodes fn prefix) |\n| `line` | INTEGER NOT NULL | Line number in the file (1-based) |\n| `hash` | TEXT NOT NULL | Git commit hash from blame |\n| `mt` | TEXT NOT NULL | Commit author timestamp |\n| `user` | TEXT | Author name or email |\n| `json` | TEXT | Additional metadata as JSON blob |
\n\nQuery pattern (in `actualizeNodes()`, ast-lake.mjs:473):
\n\n```sql\nSELECT line, mt, user, hash FROM linetime\nWHERE fn='
The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range.
\n\nSee `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows.
\n\nRole: Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`.
\n\n| Column | Type | Description |\n| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `d` | TEXT NOT NULL | ISO timestamp of the vote event |\n| `user` | TEXT | Voter identifier (username or email) |\n| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |\n| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |\n| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |\n| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |\n| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |\n| `json` | TEXT | Additional payload as JSON blob |
\n\nIndexes: `num1`, `num2`, `campaign`, `operation`, `ref`.
\n\nKey query patterns:
\n\nDashboard voting (count per ref):
\n\n```sql\nSELECT ref, operation, COUNT(*) as count, SUM(num1) as total\nFROM repo_voting\nWHERE campaign = 'eisenhower'\nGROUP BY ref, operation\n```
\n\nHeading-changes metadata check (`hasMetaData`):
"},{"id":"/root/children/105","type":"paragraph","loc":{"start":15950,"end":15997,"line":{"s":363,"e":363,"code":["Heading-changes metadata check (`hasMetaData`):"]},"column":{"s":0,"e":47}},"dim":["","paragraph.105"],"code":"Heading-changes metadata check (`hasMetaData`):"},{"id":"/root/children/105/children/0","type":"text","loc":{"start":15950,"end":15982,"line":{"s":363,"e":363,"code":["Heading-changes metadata check (`hasMetaData`):"]},"column":{"s":0,"e":32}},"dim":["","paragraph.105","text.0"],"code":"Heading-changes metadata check ("},{"id":"/root/children/105/children/1","type":"inlineCode","loc":{"start":15982,"end":15995,"line":{"s":363,"e":363,"code":["Heading-changes metadata check (`hasMetaData`):"]},"column":{"s":32,"e":45}},"dim":["","paragraph.105","inlineCode.1"],"code":"`hasMetaData`"},{"id":"/root/children/105/children/2","type":"text","loc":{"start":15995,"end":15997,"line":{"s":363,"e":363,"code":["Heading-changes metadata check (`hasMetaData`):"]},"column":{"s":45,"e":47}},"dim":["","paragraph.105","text.2"],"code":"):"},{"id":"/root/children/106","type":"code","loc":{"start":15999,"end":16081,"line":{"s":365,"e":368,"code":["```sql","SELECT DISTINCT ref FROM repo_voting","WHERE ref IN ('ref1', 'ref2', ...)","```"]},"column":{"s":0,"e":3}},"dim":["","code.106"],"code":"```sql\nSELECT DISTINCT ref FROM repo_voting\nWHERE ref IN ('ref1', 'ref2', ...)\n```","symbName":"code","symbRange":[16083,16362],"symbRangeL":[null,373],"outerCode":";{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }\n\n# ast-lake\n\nusage: ast-lake [command] [args...]\n\n- [123](http://xxx)\n- [xxx](#/papers/@dashboard)\n\n## commands:\n\n### info\n\n- info on the state of ast-lake\n\n### init\n\n- precreate the cache db\n\n### reset\n\n- delete list\n- delete all cached data\n\n### cleanup\n\n- remove non existent files from sqlite cache\n\n### restart\n\n- keep list\n- delete all cached data\n\n#### reset-nodes\n\n- cleanup only cached nodes (dev)\n- and recreated them\n\n### add\n\n- add files to list\n- dbPopulateList is a temporary list file, listing absolute file paths\n- dbPopulateList is usually `/tmp/ast-list.txt`\n- add absolute file paths:\n- note: does use `fd`. honors `.gitignore`\n- usage:\n\n```bash\nast-lake add '*.mdd' '*.json'\n```\n\n- will add `**/*.mdd` and `*.json` to list\n\n- or manually:\n- you may edit $dbPopulateList\n\n```bash\n# --base-directory $dir\n\nfd --absolute-path -tf \".+[.](mdd)$\" | rg -v test > $dbPopulateList\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList\n\n# or only add arbitrary files:\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList\n\n```\n\n- see also `ast-lake populate`\n\n### populate\n\n- ensure all ast's (from on the list) are up to date\n\n### query TERM\n\n- ast-lake query term\n- TODO term patterns ?\n- TODO regex: ^cs.+$\n\n### queryraw TERM\n\n- same as query, but returns raw JSON\n\n### flast\n\n- basically a dump\n- print all raw flASTs\n\n### nodes\n\n- print raw nodes\n\n### mdg\n\n- TODO really?\n- make one big mdg graph from all mdd's\n\n### mosaic\n\n- mosaic\n- TODO really?\n\n### mprocs\n\n- TODO support mprocs\n\n## recent updates\n\n### 2025-12-01\n\n- actualizeNodes: chunked parallel processing\n- chunk size: CPU count / 2\n- faster database query processing\n\n# db tables\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.\n\n**Two parallel implementations exist:**\n\n- **Shell-based** (`ast-lake.sh`) — older approach using local SQLite + nljson files\n- **Node.js-based** (`ast-lake.mjs`) — newer approach using remote SQLite via `RemoteSqlite`\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.\n\n## The pipeline (how data flows)\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```\n\n## `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but **each column has different semantics per table**:\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |\n\n**Shared indexes:** `num1`, `num2`, `sem`, `ref` (each named `{table}_idx_{col}`).\n\n---\n\n### `cache_ast_lake_flast`\n\n**Role:** Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |\n\n**How it's populated:** Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.\n\n**Query pattern** (in `actualizeNodes()`):\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >;{ engine: dot rankdir: LR useGvPack: true clusterize: true intention: semi nodeNomen: absolute applyCss: true }
\n\nusage: ast-lake [command] [args...]
\n\n\n\n```bash\nast-lake add '.mdd' '.json'\n```
\n\n```bash
fd --absolute-path -tf \".+.$\" | rg -v test > $dbPopulateList
\n\nfd -tf --absolute-path \"$filterFilesPattern\" > $dbPopulateList | rg -v node_modules | rg -v test > $dbPopulateList
\n\nrg TERM --files-with-matches | xargs realpath {} >> $dbPopulateList
\n\n```
\n\nThese tables are in our ast-lake SQLite database. They hold the state derived from parsing mdd/md/js files into AST nodes.
\n\nTwo parallel implementations exist:
\n\nBoth follow the same pipeline: extract flast → normalize → store nodes.
\n\n```\nFile on disk\n │\n ▼\nastHole() → astNavigator() — reads file, calls language-specific extractor\n │ (extractFlastMarkdown, extractFlastJavascript,\n │ extractFlastJson, extractFlastBash, ...)\n ▼\ncache_ast_lake_flast — one row per file; id=filepath, value=JSON flast array\n │\n ▼\nactualizeNodes() → normalizeNodes() — extracts symbolic types from flast\n │ (heading, link, comment, FunctionDeclaration, Identifier)\n ▼\ncache_ast_lake_nodes — one row per AST node; id=fn:offset\ncache_ast_lake_nodes_ref — same rows, different ref format (readable refId)\ncache_ast_lake_nodes_backup — backup of old nodes before update\n```
\n\nSchema from `sqlCreateTableCache(tblName)` in `ast-lake.mjs:51`. All four share the same column layout but each column has different semantics per table:
\n\n| Column | Type | Description |\n| ------- | ------------- | ---------------------------------------- |\n| `id` | TEXT NOT NULL | Primary key |\n| `value` | TEXT | JSON payload of the node or flast |\n| `mt` | TEXT | Modification timestamp or mime-type |\n| `sem` | TEXT | Semantic type |\n| `num1` | INTEGER | First numeric slot (position or line) |\n| `num2` | INTEGER | Second numeric slot (position or column) |\n| `ref` | TEXT | Reference ID (trail or refId) |\n| `body` | TEXT | Node body text |
\n\nShared indexes: `num1`, `num2`, `sem`, `ref` (each named `{table}idx{col}`).
\n\nRole: Raw flattened AST cache — one row per file. Stores the complete AST produced by the language-specific extractor.
\n\n| Column | How it's populated (from `actualizeNodes()`) | Semantics |\n| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |\n| `id` | `row[0]` — the file path (fn) | Full filesystem path to the source file |\n| `value` | `row[1]` — `JSON.parse(row[1])` → `data.flast` | Full JSON array of all AST nodes extracted from the file (the \"flattened AST\") |\n| `mt` | `row[2]` — file modification timestamp | ISO timestamp of last file modification |
\n\nHow it's populated: Written by `astNavigator.mjs` via `cacheFlast(fnIn, data)` (line 1571), using `initSqliteCache` from `sqlito.mjs`. The `data.value` is the array of fragments produced by extractors like `extractFlastMarkdown`, `extractFlastJavascript`, etc.
\n\nQuery pattern (in `actualizeNodes()`):
\n\n```sql\nSELECT id, value, mt FROM cache_ast_lake_flast WHERE unixepoch(mt) >
Only changed files (newer mtime) are reprocessed.
\n\nNode value structure (each element in the JSON flast array):
\n\n```json\n{\n \"id\": \"node-id\",\n \"dim\": [\"file\", \"listItem.0\", \"property.key\"],\n \"type\": \"heading|link|code|paragraph|list|...\",\n \"code\": \"raw text content\",\n \"loc\": { \"line\": { \"s\": 1, \"e\": 3 }, \"column\": { \"s\": 1, \"e\": 80 } },\n \"symbName\": null,\n \"symbRangeL\": null\n}\n```
\n\nRole: Individual AST node storage — one row per symbolic node. Produced by `normalizeNodes()` in `actualizeNodes()` (ast-lake.mjs:183-266), which extracts only `symbolicTypes` (heading, link, comment, FunctionDeclaration, Identifier) from the flast.
\n\n| Column | How it's populated (ast-lake.mjs:516-561) | Semantics |\n| ------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `` `${node.fn}:${node.offset}` `` | File path + offset position → `buildNodeAbsoluteId()` |\n| `value` | `JSON.stringify(node)` | Full normalized node as JSON (see structure below) |\n| `mt` | `node.mt` | Modification time (symbMt from git blame, or file mtime) |\n| `sem` | `node.type` | Node type: `\"heading\"`, `\"link\"`, `\"comment\"`, `\"FunctionDeclaration\"`, `\"Identifier\"` |\n| `num1` | `node.position[0]` | Line number in source file (1-based) |\n| `num2` | `node.position[1]` | Column number in source file (1-based) |\n| `ref` | `buildNodeRefId(node)` | For headings: last trail segment (heading text). For links: nomen (link label). Defines the short ref used in voting queries. |\n| `body` | `node.outerCode \\|\\| node.code \\|\\| ''` | Full text content of the node. For headings: the entire heading subtree text. For links: the markdown link syntax. |
\n\nNormalized node value structure (the JSON in the `value` column):
\n\n```json\n{\n \"fn\": \"/home/.../repo/repolero/paper/file.mdd\",\n \"trail\": [\"getting-started\", \"installation\"],\n \"type\": \"heading\",\n \"nomen\": \"Installation\",\n \"code\": \"## Installation\",\n \"symbName\": null,\n \"symbBlame\": [\"abc123def\", \"456ghi789\"],\n \"outerCode\": \"full subtree text...\",\n \"position\": [42, 1],\n \"lineRange\": [42, 85],\n \"offset\": 42,\n \"symbMt\": \"2025-06-15T10:30:00Z\",\n \"symbUser\": \"author@example.com\",\n \"mt\": \"2025-06-15T10:30:00Z\"\n}\n```
\n\nKey normalization details (from `normalizeNodes()` at ast-lake.mjs:183):
\n\nQuery pattern (voting dashboard):
\n\n```sql\nSELECT n.id, n.body, n.num1 as headingLevel, r.ref\nFROM cache_ast_lake_nodes n\nINNER JOIN cache_ast_lake_nodes_ref r USING(id)\nINNER JOIN repo_voting v ON v.ref = r.ref\nWHERE n.sem = 'heading'\n```
\n\nRole: Readable refId mirror of nodes. Stores the user-visible fragment reference string (the one used in URLs and voting) instead of the last-trail-segment ref.
\n\n| Column | How it's populated (ast-lake.mjs:560) | Semantics |\n| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | Same as nodes: `fn:offset` | Joins to `cache_ast_lake_nodes.id` |\n| `sem` | `node.type` | Node type (same as nodes.sem) |\n| `ref` | `buildNodeAbsoluteId(node)` | Readable refId — format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`. Built by `buildNodeAbsoluteId()` (ast-lake.mjs:29) |\n| `body` | `linkUrl` for links, `repoName` for others | For links: the URL target. For headings: the repo name. |
\n\n`buildNodeAbsoluteId()` construction (ast-lake.mjs:29-44):
\n\n`buildNodeRefId()` (ast-lake.mjs:46-48):
\n\nWhy two ref tables? `cache_ast_lake_nodes.ref` has the short, per-node ref (last trail segment). `cache_ast_lake_nodes_ref.ref` has the full, human-readable fragment path including the file prefix. The voting system uses the full refId from `nodes_ref`.
\n\nRole: Rollback copy. Before updating a file's nodes in `cache_ast_lake_nodes`, the old rows are copied here (ast-lake.mjs:500-514):
\n\n```sql\nINSERT OR REPLACE INTO cache_ast_lake_nodes_backup\n (id, value, mt, sem, num1, num2, ref, body)\nSELECT id, value, mt, sem, num1, num2, ref, body\nFROM cache_ast_lake_nodes\nWHERE id LIKE '
Then the old rows are deleted from both `cache_ast_lake_nodes` and `cache_ast_lake_nodes_ref` before inserting the new normalized nodes. If a sync fails, the backup can be restored.
\n\nNote: `cache_ast_lake_nodes_ref` does NOT have a backup table — the ref table is rebuilt from scratch each time.
\n\nRole: Git blame line-history cache. Maps each line in each file to its git blame metadata (commit hash, author, timestamp). Used by `normalizeNodes()` to attach `symbBlame`/`symbMt`/`symbUser` to each node.
\n\nSchema (commented inline in `ast-lake.mjs:122-131`):
\n\n| Column | Type | Description |\n| ------ | ---------------- | ----------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `fn` | TEXT NOT NULL | File name / path (matches flast.id / nodes fn prefix) |\n| `line` | INTEGER NOT NULL | Line number in the file (1-based) |\n| `hash` | TEXT NOT NULL | Git commit hash from blame |\n| `mt` | TEXT NOT NULL | Commit author timestamp |\n| `user` | TEXT | Author name or email |\n| `json` | TEXT | Additional metadata as JSON blob |
\n\nQuery pattern (in `actualizeNodes()`, ast-lake.mjs:473):
\n\n```sql\nSELECT line, mt, user, hash FROM linetime\nWHERE fn='
The result is used to compute `symbRangeL` → `symbBlame` for each node: all commit hashes for lines within the node's source range.
\n\nSee `linetime-parse-blame.jq` for the processing logic that parses `git blame --line-porcelain` output into `linetime` rows.
\n\nRole: Voting event log. Records voting actions (cast, uncast, hot, pin, weak, veto) on fragments within campaigns. Schema from `sqlCreateTableEventSource(tblName)` in `ast-lake.mjs:85`.
\n\n| Column | Type | Description |\n| ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------- |\n| `id` | INTEGER | Primary key, autoincrement |\n| `d` | TEXT NOT NULL | ISO timestamp of the vote event |\n| `user` | TEXT | Voter identifier (username or email) |\n| `ref` | TEXT NOT NULL | Fragment refId being voted on (matches `cache_ast_lake_nodes_ref.ref`) |\n| `campaign` | TEXT NOT NULL | Campaign scope — determines which vote UI is active (e.g. `\"eisenhower\"`, `\"debate\"`, `\"heading-changes\"`) |\n| `operation` | TEXT NOT NULL | Vote operation — quadrant or action (e.g. `\"hot\"`, `\"pin\"`, `\"weak\"`, `\"veto\"`, `\"cast\"`, `\"uncast\"`) |\n| `num1` | INTEGER NOT NULL | Generic numeric slot — used for vote weight or count |\n| `num2` | INTEGER NOT NULL | Generic numeric slot — used for secondary count |\n| `json` | TEXT | Additional payload as JSON blob |
\n\nIndexes: `num1`, `num2`, `campaign`, `operation`, `ref`.
\n\nKey query patterns:
\n\nDashboard voting (count per ref):
\n\n```sql\nSELECT ref, operation, COUNT(*) as count, SUM(num1) as total\nFROM repo_voting\nWHERE campaign = 'eisenhower'\nGROUP BY ref, operation\n```
\n\nHeading-changes metadata check (`hasMetaData`):
\n\n```sql\nSELECT DISTINCT ref FROM repo_voting\nWHERE ref IN ('ref1', 'ref2', ...)\n```
\n\nref format: Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`.
\n\nCleanup on file deletion (ast-lake.mjs `cleanup()` at line 305):
"},{"id":"/root/children/107","type":"paragraph","loc":{"start":16083,"end":16292,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":0,"e":209}},"dim":["","paragraph.107"],"code":"**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."},{"id":"/root/children/107/children/0","type":"strong","loc":{"start":16083,"end":16098,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":0,"e":15}},"dim":["","paragraph.107","strong.0"],"code":"**ref format:**"},{"id":"/root/children/107/children/0/children/0","type":"text","loc":{"start":16085,"end":16096,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":2,"e":13}},"dim":["","paragraph.107","strong.0","text.0"],"code":"ref format:"},{"id":"/root/children/107/children/1","type":"text","loc":{"start":16098,"end":16110,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":15,"e":27}},"dim":["","paragraph.107","text.1"],"code":" Must match "},{"id":"/root/children/107/children/2","type":"inlineCode","loc":{"start":16110,"end":16140,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":27,"e":57}},"dim":["","paragraph.107","inlineCode.2"],"code":"`cache_ast_lake_nodes_ref.ref`"},{"id":"/root/children/107/children/3","type":"text","loc":{"start":16140,"end":16167,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":57,"e":84}},"dim":["","paragraph.107","text.3"],"code":" — the readable refId from "},{"id":"/root/children/107/children/4","type":"inlineCode","loc":{"start":16167,"end":16190,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":84,"e":107}},"dim":["","paragraph.107","inlineCode.4"],"code":"`buildNodeAbsoluteId()`"},{"id":"/root/children/107/children/5","type":"text","loc":{"start":16190,"end":16200,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":107,"e":117}},"dim":["","paragraph.107","text.5"],"code":". Format: "},{"id":"/root/children/107/children/6","type":"inlineCode","loc":{"start":16200,"end":16246,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":117,"e":163}},"dim":["","paragraph.107","inlineCode.6"],"code":"`relative/path/file.mdd::sanitized/trail/path`"},{"id":"/root/children/107/children/7","type":"text","loc":{"start":16246,"end":16259,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":163,"e":176}},"dim":["","paragraph.107","text.7"],"code":". For links: "},{"id":"/root/children/107/children/8","type":"inlineCode","loc":{"start":16259,"end":16291,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":176,"e":208}},"dim":["","paragraph.107","inlineCode.8"],"code":"`...::trail#nomen:tinyHash(url)`"},{"id":"/root/children/107/children/9","type":"text","loc":{"start":16291,"end":16292,"line":{"s":370,"e":370,"code":["**ref format:** Must match `cache_ast_lake_nodes_ref.ref` — the readable refId from `buildNodeAbsoluteId()`. Format: `relative/path/file.mdd::sanitized/trail/path`. For links: `...::trail#nomen:tinyHash(url)`."]},"column":{"s":208,"e":209}},"dim":["","paragraph.107","text.9"],"code":"."},{"id":"/root/children/108","type":"paragraph","loc":{"start":16294,"end":16362,"line":{"s":372,"e":372,"code":["**Cleanup on file deletion** (ast-lake.mjs `cleanup()` at line 305):"]},"column":{"s":0,"e":68}},"dim":["","paragraph.108"],"code":"**Cleanup on file deletion** (ast-lake.mjs `cleanup()` at line 305):"},{"id":"/root/children/108/children/0","type":"strong","loc":{"start":16294,"end":16322,"line":{"s":372,"e":372,"code":["**Cleanup on file deletion** (ast-lake.mjs `cleanup()` at line 305):"]},"column":{"s":0,"e":28}},"dim":["","paragraph.108","strong.0"],"code":"**Cleanup on file deletion**"},{"id":"/root/children/108/children/0/children/0","type":"text","loc":{"start":16296,"end":16320,"line":{"s":372,"e":372,"code":["**Cleanup on file deletion** (ast-lake.mjs `cleanup()` at line 305):"]},"column":{"s":2,"e":26}},"dim":["","paragraph.108","strong.0","text.0"],"code":"Cleanup on file deletion"},{"id":"/root/children/108/children/1","type":"text","loc":{"start":16322,"end":16337,"line":{"s":372,"e":372,"code":["**Cleanup on file deletion** (ast-lake.mjs `cleanup()` at line 305):"]},"column":{"s":28,"e":43}},"dim":["","paragraph.108","text.1"],"code":" (ast-lake.mjs "},{"id":"/root/children/108/children/2","type":"inlineCode","loc":{"start":16337,"end":16348,"line":{"s":372,"e":372,"code":["**Cleanup on file deletion** (ast-lake.mjs `cleanup()` at line 305):"]},"column":{"s":43,"e":54}},"dim":["","paragraph.108","inlineCode.2"],"code":"`cleanup()`"},{"id":"/root/children/108/children/3","type":"text","loc":{"start":16348,"end":16362,"line":{"s":372,"e":372,"code":["**Cleanup on file deletion** (ast-lake.mjs `cleanup()` at line 305):"]},"column":{"s":54,"e":68}},"dim":["","paragraph.108","text.3"],"code":" at line 305):"},{"id":"/root/children/109","type":"list","loc":{"start":16364,"end":16701,"line":{"s":374,"e":376,"code":["- Does NOT delete `repo_voting` rows when a file is removed (votes are preserved)","- Does DELETE from `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`, and `linetime`","- Sweeps orphan refs: `DELETE FROM cache_ast_lake_nodes_ref WHERE id NOT IN (SELECT id FROM cache_ast_lake_nodes)`"]},"column":{"s":0,"e":114}},"dim":["","list.109"],"code":"- Does NOT delete `repo_voting` rows when a file is removed (votes are preserved)\n- Does DELETE from `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`, and `linetime`\n- Sweeps orphan refs: `DELETE FROM cache_ast_lake_nodes_ref WHERE id NOT IN (SELECT id FROM cache_ast_lake_nodes)`","symbName":"list","symbRange":[null,null],"symbRangeL":[374,376],"outerCode":"- Does DELETE from `cache_ast_lake_flast`, `cache_ast_lake_nodes`, `cache_ast_lake_nodes_ref`, `cache_ast_lake_nodes_backup`, and `linetime`","outerHtml":"