padz-display-identifiers

name	padz-display-identifiers
description	Explains the Display Identifier system in padz—a dual-identifier approach that provides stable, user-friendly IDs (1, 2, p1, d1) while internally using UUIDs. Use when working on pad listing, selection, or any CLI command that references pads by ID. Critical for understanding why filtered views preserve canonical indexes.

Padz Display Identifiers

The Problem

UUIDs are unwieldy for CLI users. Naive sequential indexing (1, 2, 3... based on current view) causes "index drift"—the same ID can refer to different pads depending on filters.

$ padz list
1. Hi Mom
2. Hi Dad

$ padz search Dad
1. Hi Dad     # DANGER: Is "1" global or search-local?

The Solution: Dual Identifiers

1. UUID (Internal): Immutable, used in storage and business logic
2. Display Index (External): Stable integer from canonical ordering

Canonical Ordering

Indexes are assigned from the full, unfiltered list, not the current view:

$ padz search Dad
2. Hi Dad     # Still ID 2—safe to delete

Index Types

Type	Format	Assignment
Regular	1, 2, 3	All non-deleted pads, newest first
Pinned	p1, p2	Pinned non-deleted pads only
Deleted	d1, d2	Soft-deleted pads

Pinned Pads Have Two Indexes

A pinned pad appears twice: as pN and as its regular index. This ensures stability when unpinning—the regular index remains unchanged.

$ padz list
p1. Important Note    # Also accessible as "2"
1.  Newest Note
2.  Important Note    # Same pad as p1
3.  Oldest Note

Tree Support

Child pads use dot notation. Each level maintains its own index namespace:

1          # Root pad
1.1        # First child of pad 1
1.1.1      # First grandchild
1.p1       # Pinned child of pad 1

Ranges

Select multiple pads with range syntax:

padz delete 1-3        # Delete pads 1, 2, 3
padz delete p1-p3      # Delete pinned 1, 2, 3
padz delete 1.1-1.3    # Delete children 1-3 of pad 1

Implementation

Generating Indexes (Output)

Location: crates/padzapp/src/index.rs — function index_pads

Three-pass algorithm:

1. Sort all pads by created_at descending
2. First pass: Assign pN to pinned non-deleted pads
3. Second pass: Assign N to ALL non-deleted pads (including pinned)
4. Third pass: Assign dN to deleted pads

Always use index_pads for listing. Never manually enumerate.

Resolving Indexes (Input)

Location: crates/padzapp/src/api.rs — function parse_selectors

Flow: User Input → DisplayIndex → UUID

Business logic (commands/*) only receives UUIDs. The fragility of human-friendly IDs is contained at the API boundary.

Key Types

enum DisplayIndex {
    Pinned(usize),   // p1, p2...
    Regular(usize),  // 1, 2...
    Deleted(usize),  // d1, d2...
}

enum PadSelector {
    Path(Vec<DisplayIndex>),           // "1.2.3"
    Range(Vec<DisplayIndex>, Vec<DisplayIndex>), // "1-3"
    Title(String),                     // "My Note"
}

struct DisplayPad {
    pad: Pad,
    index: DisplayIndex,
    matches: Option<Vec<SearchMatch>>,
    children: Vec<DisplayPad>,
}

Developer Guidelines

1. Never bypass index_pads — All pad listings must use canonical indexing
2. Commands receive UUIDs only — Keep index resolution at API boundary
3. Pinned pads are dual-indexed — Expect two entries per pinned pad in indexed lists
4. Tree indexes are per-parent — Each nesting level starts at 1