SaladDay
2589384e68
Pi cannot be read as another linear JSONL stream. Its history is a tree with a durable leaf, orphan roots, branch summaries, and two compaction forms, so the active context is something the format states rather than something line order implies. The adapter keeps those semantics inside itself and projects the result into the existing canonical tables. Sessions are keyed by (normalized header cwd, header id) rather than by path, because Pi's --session-id lookup is project-local: two projects may reuse an id, while a move or an identical copy is still one session. Discovery covers both layouts Pi writes and fingerprints each file by mtime, ctime, size and inode, so a rewrite that preserves mtime is not read as unchanged. Abandoned branches are preserved rather than dropped. Visibility becomes three-state -- visible, inactive, hidden -- and helpers return only visible rows until includeInactive asks for the superseded path, labeling every row so a caller knows which it holds. Usage counts all three, because an abandoned call still spent tokens; message_count reports only the visible transcript. A committed MIT-licensed oracle transcribed from Pi 0.83.0 pins the context algorithms, and a fixed-seed differential runs 512 generated sessions against it on every test run. Schema changes are additive.
86 lines
2.7 KiB
Markdown
86 lines
2.7 KiB
Markdown
# Obelisk Pitfalls
|
|
|
|
Use this after a query error, suspicious empty result, over-large output, or
|
|
unclear helper row shape. For query design, read `retrieval-semantics.md` first.
|
|
|
|
## Missing Columns And Wrong Aliases
|
|
|
|
Common wrong guesses:
|
|
|
|
- Summaries: use `source` and `content`; do not use `summary_type` or `text`.
|
|
- Tool call name: use `tool_calls.name`. `tool_name` is only an alias in `SELECT tc.name AS tool_name`; `tc.tool_name` is not a column.
|
|
- Tool call timestamps: `tool_calls` has no timestamp. Join `messages m ON m.uuid = tc.message_uuid`.
|
|
- Tool result timestamps: `tool_results` has no timestamp. Join `messages m ON m.uuid = tr.message_uuid`.
|
|
- Workflow agent message counts: `workflowTree()` returns `messageCount` for agents.
|
|
|
|
When uncertain, inspect a tiny sample instead of guessing:
|
|
|
|
```js
|
|
const rows = summaries({ limit: 1 });
|
|
return rows.length ? Object.keys(rows[0]) : [];
|
|
```
|
|
|
|
## FTS5 Syntax Errors
|
|
|
|
`search(text)` uses raw FTS5 `MATCH`. Hyphenated terms and punctuation can be
|
|
parsed as syntax.
|
|
|
|
```js
|
|
// tokenized phrase for FTS
|
|
search('"workflow script"', { limit: 10 })
|
|
```
|
|
|
|
For literal punctuation, use SQL `LIKE` under the same scope:
|
|
|
|
```js
|
|
sql(`
|
|
SELECT m.uuid, s.id AS session_id, s.title, substr(m.text,1,180) AS snippet
|
|
FROM messages m
|
|
JOIN sessions s ON s.id = m.session_id
|
|
WHERE s.project LIKE ?
|
|
AND m.text LIKE ?
|
|
AND COALESCE(m.visibility, 'visible') = 'visible'
|
|
ORDER BY m.timestamp DESC
|
|
LIMIT 10
|
|
`, '%quiet-zero%', '%workflow-script%')
|
|
```
|
|
|
|
## Over-Large Runtime JSON
|
|
|
|
If runtime stdout is large, fix the query instead of reading it in chunks.
|
|
|
|
- Lower `LIMIT`.
|
|
- Shorten snippets to 160-240 chars.
|
|
- Group in SQL/JS and return counts plus sparse examples.
|
|
- For `fileHistory()`, filter to `Edit`/`Write` before projecting evidence.
|
|
- For `workflowTree()`, omit `script`, `result_json`, and full agent messages unless explicitly requested.
|
|
- Use `raw(uuid, { offset, limit })` only after identifying one specific message UUID.
|
|
|
|
## Empty Results
|
|
|
|
An empty array can be the correct answer for exact scopes or sentinels.
|
|
|
|
When the user asks for a scoped project/file/session or exact term:
|
|
|
|
1. run the scoped query;
|
|
2. return `[]` or compact counts;
|
|
3. say no matching prior result was found;
|
|
4. do not call `recent()`, all-project `summaries()`, or `thread()` as fallback unless the user asks.
|
|
|
|
## Counting From Snippets
|
|
|
|
If the user asks "how many", "counts", "top N", or "group by", compute it in
|
|
SQL or in the query script. Do not infer counts from visible snippets.
|
|
|
|
```js
|
|
sql(`
|
|
SELECT tc.name AS tool_name, COUNT(*) AS n
|
|
FROM tool_results tr
|
|
JOIN tool_calls tc ON tc.id = tr.tool_use_id
|
|
WHERE tr.is_error = 1
|
|
GROUP BY tc.name
|
|
ORDER BY n DESC
|
|
LIMIT 10
|
|
`)
|
|
```
|