mirror of
https://github.com/morluto/rea.git
synced 2026-11-09 16:26:36 +00:00
3230f50b16
* feat(sqlite): page selected rows with a stated order and row offset readRows read `NOT INDEXED LIMIT ?` with no ORDER BY and reported order: "unspecified", so an agent could not reach rows past row_limit deterministically: raising row_limit hits the fixed 16 MiB reply budget, and the sampled order depends on whichever index SQLite happened to scan. Read the window in a unique, stated order and expose the position: - rowid tables order by rowid unless all of rowid, _rowid_ and oid are declared columns, in which case the order stays unspecified. - WITHOUT ROWID tables order by the primary-key columns, reusing each key's DESC flag and declared collation from pragma_index_xinfo so the plan keeps index order instead of materialising a sorter. - rows.order, rows.row_offset and rows.next_row_offset report the window; next_row_offset is null once the window reaches the end. - row_offset (CLI --row-offset) requires table and defaults to 0. A non-zero offset is refused when the table declares no usable order, because the skipped prefix would be arbitrary. The schema now checks next_row_offset against truncated and the offset so a worker reply cannot claim a page it did not read. One attribution fix came with it: adding ORDER BY text can push an over-wide projection past SQLite's SQL-text limit, which fails as SQLITE_TOOBIG before the result-column limit is reported. Attribute that case to column capacity too, so a 250k-column request still reads as capacity rather than a byte budget. Verified: npm run check:fast, npm run format:check on the touched files, npm run verify:module-boundaries, npm run docs:check, and 196 tests across the sqlite boundary, application and CLI/MCP suites. A 1002-row inspection and in-memory EXPLAIN QUERY PLAN checks confirmed the WITHOUT ROWID path adds no sorter. Full check:pr and the complete test suite were not run. * fix(sqlite): resolve the rowid alias and keep paging claims reachable Three defects in the row paging added alongside row_offset: - readRowOrder emitted ORDER BY rowid for every rowid table, but a table that declares a rowid column shadows that spelling, so the sort used the stored column and could repeat or drop rows across pages. Order now names the first alias the table leaves unbound, read from raw name bytes so an unrelated malformed identifier is not decoded just to choose an order. - The inventory projection could hide the primary key a WITHOUT ROWID table orders by, silently degrading a paginated read to unspecified order. The order key is now read from the table itself rather than from the columns the caller asked to see. - A truncated table with no stated order reported a next_row_offset that the row_offset rule then refused. It is null there, and the reply limitation no longer claims an unspecified order for windows that have one. rowEvaluationFailure also probed the first rows of the table instead of the requested window, so a failure confined to a later page was attributed to columns that evaluate fine there. * test(sqlite): assert the concatenated pages The paging regression checked only counts, offsets and flags, so a second page that repeated the first page's rows would still pass. Assert the values read across all three pages instead. * fix(sqlite): decode row keys in the database encoding readRowKeyFacts decoded primary-key names as UTF-8 and probed a fixed hidden set, so two supported schemas could not be paged at all: - A UTF-16 database stores key names as UTF-16 bytes, so "k" decoded to NUL-padded text and ORDER BY named an identifier that does not exist. Pass the detected encoding, as readColumns and the index-metadata path already do. - A virtual generated column named rowid (hidden=2) was absent from the shadow check, so ORDER BY rowid evaluated the generated expression instead of the rowid and could sort non-uniquely or fail outright. Include generated columns in the alias probe. Also stop decoding primary-key names for rowid tables: their ORDER BY names an alias, never a declared key, so an unselected malformed key name could abort an otherwise readable selection. The page-concatenation assertion now narrows SqliteValue before reading .value, which the null/blob arms do not carry; this was failing the Static checks typecheck job. * fix(sqlite): order WITHOUT ROWID rows by the index's own key sequence `readRowOrder` filed `pragma_index_xinfo` key terms into a map keyed by column name, so a valid composite key that repeats a column — `PRIMARY KEY(a COLLATE BINARY, a COLLATE NOCASE DESC)` — collapsed to one term. The generated clause then overstated uniqueness: it omitted the BINARY term, so `A`/`a` ties survived, and the `row_offset` paging advertised a `primary_key` order that the actual key does not establish. Build the terms from the index rows in `seqno` order instead, keeping repetitions, and bail to `unspecified` if any declared key column never appears in the index. The declared collation stays explicit so a caller column's own collation cannot re-sort the window. Verified against a real SQLite database that the repeated key is accepted and that the old clause orders A, a, B while the index orders A, B, a. * fix(sqlite): accept a null next offset on unordered truncated rows readRows already withholds next_row_offset when a table shadows rowid, _rowid_ and oid and declares no primary key, because every non-zero offset is refused there. The reply schema still required the offset whenever truncated was set, so the provider rejected its own worker result and the first sample never reached CLI or MCP. Require the offset only when the order is stated. * fix(sqlite): probe row keys only for ordinary tables and name row_offset readRowKeyFacts ran for a selected virtual shadow table before readRows could reject it, so an unavailable module surfaced as SQLite's "no such module" instead of the selection refusal. Probe the key only when the selected kind is an ordinary table and leave the order unspecified otherwise, since no rows are read for that kind. The unordered-offset refusal also reported the generic selection reason, which callers see against table. Give it its own reason so the failure is attributed to row_offset. * feat(sqlite)!: page selected rows with a stated order and row offset Selected-row inspection currently reports only rows.order: "unspecified" and offers no way to reach rows past the first sample deterministically. Main also refuses non-zero row_offset today, so nothing relies on that omission; this change makes the stated order and the offset the contract, reports the next offset the caller feeds back, and keeps the existing byte, heap, statement and deadline limits. BREAKING CHANGE: rows.order becomes rowid | primary_key | unspecified, and rows gains required row_offset and next_row_offset members. A client that validates selected-table output against the previous schema (where order was the only permitted value) rejects a now-valid reply. Migration: accept the two new members and treat order: "rowid" | "primary_key" as the stated order the offset applies to; a null next_row_offset means the window reached the end. * docs(sqlite): say a null next offset also means no stated order The selected-rows limitation described next_row_offset as null only when the window reached the end. An unordered table whose row_limit truncates the sample also publishes null, because an offset there would name a request the row-offset rule refuses, so the Evidence read as if the sample were complete. State the second cause and pin it in the existing regression. * test(sqlite): drop the limitation wording assertion and state the unordered exception The boundary test pinned the sentence a caller reads in `limitations`, so a harmless rewrite of that text failed a paging test whose real subject is `order`, `truncated` and `next_row_offset`. docs/development/testing.md asks for facts over frozen explanatory prose, and the three structured expectations already fail if the paging fact changes. The tool contract promised that retained rows always have a unique order and can be paged. A rowid table that shadows rowid, _rowid_ and oid and declares no primary key has no such order: it returns order=unspecified with a null next offset and refuses a non-zero row_offset. Say so in the description so callers do not plan a continuation the tool always refuses. * docs(sqlite): say unordered tables cannot be paged The description told callers that a truncated table without a stated order needs "the table read without offsets", but omitting row_offset starts at zero again: with an unchanged row_limit the next call repeats the first sample instead of continuing past it. Say that these tables cannot be paged and point at row_limit for a larger first sample. * style(cli): wrap the native data type path description The `inspect-native-data-type` argument description line is 82 columns, over the repository's 80-column `.oxfmtrc.json` limit, so `npm run format:check` fails on main and on every branch merged from it. It came in with #9465 and the following commits to this file did not touch it. Reformat the one call the formatter objects to; no behaviour change. * fix(sqlite): bound rowid alias comparison by name byte length readRowKeyFacts decoded every column name before testing it against three short aliases, so a table declaring a multi-megabyte name could exhaust the worker heap even when the caller projected the column away. Reject names that cannot be an alias by their byte length, accounting for the database encoding, before building any string. --------- Co-authored-by: 2SinceJuly <202121119+2SinceJuly@users.noreply.github.com> Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Documentation directory
REA documentation is organized by reader task and document owner. This directory
links every authored guide; the site also serves separate
product pages. The VitePress documentation source is this docs/ tree.
Getting started
- Installation and setup
- Client configuration and troubleshooting
- CLI and Evidence
- Guided MCP prompts and completion
Native binaries
- Native binary investigation
- Go binary build metadata
- Offline binary diagnostics
- Recorded crash evidence
- Windows Shell Link shortcuts
JavaScript and Electron
- JavaScript Application Graph
- Cross-layer JavaScript application workflows
- JavaScript artifact reconstruction
- JavaScript source recovery
- Passive Node and Electron runtime observation
- JavaScript static/runtime reconciliation
- Electron file-page observation
- V8 code cache inspection
Browser and captured websites
- Website observation with CDP
- Browser scenario contract
- Website runtime source attribution
- Historical web network captures
- HTTP/3 capture lab
- Captured website source locations
- Captured website module relationships
- Captured website scripts and static JavaScript analysis
Android applications
- Static Android APK analysis
- Apktool resource decoding
- ADB device inspection and acquisition
- Flutter build identification
Apple applications
.NET assemblies
Firmware
HarmonyOS packages
WebAssembly
EVM contracts
Databases and recorded packets
Process capture and instrumentation
Signal recordings
Provider setup and formats
- Ghidra provider semantics
- DOS MZ and COM analysis with Ghidra
- Optional NativeAOT metadata recovery
- MIPS ELF analysis through Ghidra
- PSP static ELF analysis through Ghidra
- RISC-V ELF analysis through Ghidra
- Windows Ghidra P0
- Headerless raw-binary analysis with Ghidra
- IDA provider
- JEB instrumentation and analysis
Contracts and evidence
Development and verification
- Settings and recovery
- MCP tool design
- Testing REA
- Client and agent verification
- Reconstruction readiness conformance
- Releasing REA
- REA roadmap
Release migrations
Architecture and authoring
- Architecture map
- Documentation ownership and contribution model
- Feature specifications
- Architectural decision records
Machine-owned documentation
| Path | Owner and update command |
|---|---|
public/product-catalog.json |
Ignored contract projection; npm run docs:generate |
verification/managed-conformance-*.json |
Ignored managed conformance projections; npm run evidence:generate |
error-contract.schema.json |
Tracked schema from contracts; npm run docs:error-schema |
user-visible-errors.csv |
Authored error classification inventory; preserve its schema |
releases/<version>.contributions.json |
Durable release contribution record; follow the release guide |
assets/ |
Shared authored images referenced by guides |
Do not edit generated catalogs or evidence to change product facts. Change their canonical contracts or producer and regenerate. Historical release records retain the exact commit messages and references from the release they describe.
Additional guides
- Offline API contract inventory
- Bun standalone executables
- Capability composition and ownership
- .NET single-file bundles
- ESP flash images
- U-Boot FIT images
- Measure MCP catalog costs in Codex
- Offline Playwright traces
- Testing lanes and provider verification
- UF2 and DfuSe images
- WeChat mini-program wxapkg archives
- Binary hardening
- Desktop application capture
- Desktop application export
- Desktop application state
- Desktop application tasks
- Desktop build computer
- Desktop build witness
- iNES containers
- Build RL environments with REA
- Agent environments from recorded captures
- APK signature schemes
- Apple IPS crash reports
- Static analysis in GitHub Actions
- Desktop installation directories
- Flattened devicetree inspection
- Electron fuse state
- ELF note tables
- Erlang BEAM files
- ESP images
- GameCube DOL analysis through Ghidra
- PowerPC ELF analysis through Ghidra
- Godot PCK archives
- Static CUDA and HIP code objects
- Intel HEX and S-record images
- IL2CPP metadata
- Static JavaScript route inventory
- Linux kernel modules
- Kuna provider
- Model file declarations
- Match native functions across builds
- Node.js single executable applications
- PE Authenticode certificate tables
- PE import and delay-load tables
- PE TLS callbacks and load configuration
- Python packaged applications
- CPython pyc inspection
- Reconstruction coverage
- Reverse-engineering tool integrations
- Rust binary dependency metadata
- U-Boot legacy uImage containers
- UnityFS AssetBundle archives