Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

docs(cli): inventory pages are stable only between ingests; text window reach (HR-02B)

KageBinary83cfa70799e7
diff --git a/docs/llm-format.md b/docs/llm-format.md
index 7aa195ef..aad18738 100644
--- a/docs/llm-format.md
+++ b/docs/llm-format.md
@@ -161,13 +161,17 @@ Two commands cannot know a true total and say so rather than inventing one:
before the page too: a deep page costs O(offset). The server returns at
most 5000 rows, so no page reaches past row 5000: a page at or beyond it
stays `truncated=true` (JSON: `capped: true`) and says to narrow with
- `--path`, never `offset_past_end`.
+ `--path`, never `offset_past_end`. The server lists newest first, so
+ pages are stable only between ingests: an ingest while paging shifts later
+ pages, and rows can repeat or be skipped.
- `ix text` reports `shown=N scanned=M`: ripgrep's traversal is bounded by a
scan window, and `scanned` is how many matches were ranked, not how many
- exist. The window holds the best `scanWindow(limit)` matches (code, then
- tests, then prose; then path; then line) over every match ripgrep finds,
- so the output is the same on every run. Pages are cut from that window, so
- keep `--limit` fixed while paging. The page that reaches the end of a full
+ exist. The window holds the best `scanWindow(limit, offset)` matches (code,
+ then tests, then prose; then path; then line) over every match ripgrep
+ finds, so the output is the same on every run. The window looks
+ `5 × --limit` rows past the page's offset, and stops at 500 rows; a wider
+ window only appends rows, so pages line up. Keep `--limit` fixed while
+ paging (it is also ripgrep's per-file match cap). The page that reaches the end of a full
window has no `next_offset=`; its message says to narrow with `--path` or
`--language` instead, and so does a page past a full window (it is not
`offset_past_end`: more matches exist). `--format json` stays a bare array of matches with no
diff --git a/ix-cli/src/cli/commands/inventory.ts b/ix-cli/src/cli/commands/inventory.ts
index 0cde96fd..71806d46 100644
--- a/ix-cli/src/cli/commands/inventory.ts
+++ b/ix-cli/src/cli/commands/inventory.ts
@@ -150,11 +150,18 @@ Examples:
// fit. The backend has no count endpoint, so this is the only honest
// answer available: "there is at least one more". /v1/list has no
// offset, so a page past the first fetches the rows before it too and
- // drops them here; its order is stable, so pages line up.
+ // drops them here. /v1/list orders newest first (created_at DESC, then
+ // _key), so pages line up only while the graph does not change: an
+ // ingest between two pages shifts every later page, and rows repeat or
+ // are skipped.
//
// The server returns at most LIST_MAX_ROWS rows. A request over that
// which comes back full may have been cut, so the list is not known to
// end there: it stays truncated and no offset is called past the end.
+ // That is a count heuristic: exactly LIST_MAX_ROWS entities reads as
+ // "count unknown". The server does say whether it cut (Ix-memory 1.0.34+
+ // sets `X-Ix-Truncated: true` on /v1/list), but the client's post()
+ // returns only the parsed body, so the header is not visible here yet.
const wanted = offset + limit + 1;
let nodes = await client.listByKind(opts.kind, { limit: Math.min(wanted, LIST_MAX_ROWS), workspaceId: systemId ? undefined : resolveWorkspaceId(), scope: pathNeedle, systemId });
const capped = wanted > LIST_MAX_ROWS && nodes.length >= LIST_MAX_ROWS;
diff --git a/skills/ix/references/commands.md b/skills/ix/references/commands.md
index cda004a6..8e4273a6 100644
--- a/skills/ix/references/commands.md
+++ b/skills/ix/references/commands.md
@@ -192,8 +192,9 @@ ix inventory --kind function --path auth.py
- Page `callers`, `callees`, `imports`, `imported-by`, `contains`,
`inventory` and `text` with `--offset`, following the `next:` hint (or
`next_offset=` in llm output). Keep `--limit` the same while paging. `text`
- pages stop at its scan window; past that, narrow with `--path` or
- `--language`. The server returns at most 1000 edges and 5000 `inventory`
+ pages stop at its 500-row scan window; past that, narrow with `--path` or
+ `--language`. `inventory` lists newest first, so its pages are stable only
+ between ingests. The server returns at most 1000 edges and 5000 `inventory`
rows; past those caps the output stays truncated and says to narrow.
- Use `--path` or `--language` to restrict text searches.
- Reuse exact entity IDs from previous JSON results when chaining commands.