Indexing and Counting Conventions

JP exposes turn positions and counts in two places: the CLI (flags, arguments) and configuration (config files, --cfg, the inline compaction DSL). Internally those same positions are stored as zero-based indices in the conversation stream. This document fixes the convention so the translation between the two sides is consistent and happens in exactly one place per boundary.

The rule

• User-facing positions are 1-based. The first turn is turn 1. This holds for every CLI flag and configuration value that names a turn position.

• Stored and internal positions are 0-based. Compaction.from_turn, Compaction.to_turn, Turn::index(), and RangeBound::Absolute are all 0-based and never change. The conversation stream is the source of truth and it counts from zero.

• Translate at the boundary, once. A 1-based user value becomes a 0-based index at the point where user input is resolved against the stream, and a 0-based index becomes a 1-based display value at the point where it is rendered. Nothing in between carries an ambiguous "is this 0- or 1-based?" value.

jp_conversation carries core values (0-based) and never sees a user value. Everything above it translates at the point where it parses or renders user input, and each such point is listed under "Where the translation lives": jp_cli's flag parsers for --turn/--from/--to, and RuleBound's FromStr/Display for config values and the inline DSL.

One consequence worth knowing before touching RuleBound: because it normalizes at parse time, its FromEnd payload is already a 0-based offset (FromEnd(0) is the last turn, written -1), matching jp_conversation::RangeBound::FromEnd so the two never need a shift between them. RuleBound::Absolute is the exception — it holds the 1-based number as written and is shifted in keep_first_to_bound / keep_last_to_bound.

Positions vs. counts

Only positions (indices into the conversation) are subject to the 1-based rule. A count — "how many turns" — is base-independent and is never shifted.

Kind	Examples	Translated?
Position (absolute)	--turn N, --from N, --to N, DSL N..M	yes, N (1-based) → N - 1 (0-based)
Position (from end)	--turn -N, --from -N, --to -N, --keep-last -N, DSL -N, config keep_last = "-N"	yes, -1 is the last turn (-N → FromEnd(N - 1))
Count	--first N, --last N, --keep-first N, --keep-last N, config keep_first = N	no
Time	5h, 2days, 2026-01-01, RFC 3339	resolved against timestamps, then snapped to a turn

Two consequences worth calling out:

• --turn -1, --from -1, and --to -1 address the last turn, matching the 1-based reading where 1 is the first turn and -1 is the last. As a result --from -N selects the same starting turn as --last N, and --turn -2 is the second-to-last turn. Either end of a --turn range may count from the end, and the two forms mix freely: --turn -3..-2 is the two turns before the last, --turn 2..-1 is turn 2 through the end.

• -N is a position in every surface that accepts it, including the compaction DSL and the keep_first/keep_last config values. ..-3 compacts through the third turn from the end (leaving the final two), and keep_last = 3 is the count that keeps the last three.

• The attachment selector (jp query --attach 'ID?a:RANGE') uses the same rules: 1-based, -1 is the last turn, A..B inclusive. a:-3 is one turn; a:-3.. is the last three.

• A bare integer in a position slot is always a turn number, never a year. The accepted date formats all require separators, so --from 2026 is turn 2026 and --from 2026-01-01 is the date.

• Ranges are written A..B and are inclusive on both ends — 1..5 is turns 1 through 5 (five turns). This one format is shared by --turn A..B, the compaction DSL, and the timeline output. Either end may be omitted to mean the conversation start or end (10.., ..10, ..). Note this diverges from Rust's .. (which is exclusive); there is no ..= form.

Which bounds go where

A bound is legal in a config rule only if it is conversation-independent — a rule is written once and applied to every conversation, so its bounds have to mean the same thing in a conversation of any length. Counts, durations, from-end positions, and last-compaction all qualify. An absolute turn number does not: "turn 47" is a fact about one conversation.

RuleBound::Absolute is therefore reachable only from the inline DSL, which runs once against a conversation the user is looking at. RuleBound's Serialize refuses it, so it cannot reach a config file even indirectly.

On the CLI the distinction is between selecting and protecting rather than between value forms:

Flag	Answers	Accepts
--from / --to	which turns	a position (5, -3), a time, last-compaction (--from)
--keep-first / --keep-last	what to protect	a count (3), a position (-3), a time, last-compaction (--keep-first)

The two compose: the range flags name the selection, and the keep flags then protect turns at either end of it. A bare N on a keep flag is a count, so --keep-last 3 and --keep-last -4 protect the same three turns.

A bound never splits a turn

Every position form resolves to a whole turn, including the time-based ones. A time value is an addressing mode for a turn, not a cut point inside one: --from <time> starts at the first turn to begin after the cutoff, and --to <time> ends at (and includes) the turn that was running at the cutoff.

This is why the range ends are inclusive rather than half-open. Half-open reads well for a continuous coordinate, but once a bound names a turn, "which turn" is inherently inclusive. The conversation-creation filter on jp c rm / jp c archive / jp c use is the opposite case — it compares raw timestamps and never snaps to anything — so it is half-open and uses distinct flag names (--created-since / --created-before).

Where the translation lives

• CLI turn selection (jp_cli::cmd::turn_selection): parse_bound maps a 1-based absolute N to RangeBound::Absolute(N - 1) and a from-end -N to RangeBound::FromEnd(N - 1). --turn endpoints go through parse_turn_pos, which produces the same two flavours (TurnPos::Absolute / TurnPos::FromEnd) holding the number as written; TurnPos::to_range_bound does the 1-based → 0-based shift. TurnSelection::resolve then resolves every bound against the stream and produces a TurnSet of inclusive 0-based windows.

  --turn, --from/--to, and --first/--last are three ways of naming the base selection and are mutually exclusive:

  Selector	Start bound	End bound
  --turn N	Absolute(N - 1)	Absolute(N - 1)
  --turn -N	FromEnd(N - 1)	FromEnd(N - 1)
  --turn A..B	Absolute(A - 1)	Absolute(B - 1)
  --first N	Absolute(0)	Absolute(N - 1)
  --last N	FromEnd(N - 1)	FromEnd(0)

  Either end of --turn A..B may be a from-end position, and the two forms mix freely (--turn 2..-1). --first and --last given together produce two windows and skip the turns between them.

• Keep flags (jp_cli::cmd::turn_selection): keep_first_bound / keep_last_bound map RuleBound::Absolute(N) (the 1-based value parsed from @N) to RangeBound::Absolute(N - 1); the RuleBound::Turns(N) (count) arm is untouched. TurnSelection::trim then clamps each window to the turns those bounds leave unprotected — it clamps rather than shifts, so a turn already outside the window needs no protecting.

• Config keep_first/keep_last and the inline DSL: RuleBound's FromStr (jp_config::conversation::compaction) and parse_dsl_bound (jp_cli::cmd::compact_flag) both map -N to RuleBound::FromEnd(N - 1).

  The two parsers differ on a bare N: in config it is a count (keep_first = 5 keeps five turns), in the DSL it is a position (5.. starts at turn 5). Only the DSL produces RuleBound::Absolute; see "Which bounds go where".

• Timeline output (jp_cli::cmd::conversation::compact::timeline_lines): the stored 0-based from_turn/to_turn are rendered as 1-based, e.g. Compacted turns 2..8.

When adding a new flag, config key, or output that names a turn, decide first whether it is a position or a count. If it is a position, it is 1-based on the user side and translated to 0-based exactly where it meets the stream.