// ============================================
// Creation events - different allocator sources
// ============================================
// 
// Create with explicit allocator
~pub event new {
    allocator: std.mem.Allocator, text: []const u8
}
| ok *String<view!>
| err []const u8

// Create with page allocator (simple, for demos)
~pub event from-page {
    text: []const u8
}
| ok *String<view!>
| err []const u8

// ============================================
// Ownership transitions
// ============================================
// 
// Take ownership - view becomes instance
~pub event take {
    s: *String<!view>
}
| instance *String<instance!>

// Release ownership - instance becomes view
~pub event release {
    s: *String<!instance>
}
| view *String<view!>

// ============================================
// Cleanup
// ============================================
// 
// Free - works on either view or instance (consume-marker on BOTH members, so
// the union discharges either state; `<!view|instance>` marked only `view`,
// hiding `free` from `instance!` obligations — the discharge-finder's
// .state_union branch keys off each member's own consume marker).
~pub event free {
    s: *String<!view|!instance>
}

// ============================================
// Read operations - work on view or instance
// ============================================
~pub event read {
    s: *String<view|instance>
}
| slice []const u8

~pub event len {
    s: *String<view|instance>
}
| len usize

// ============================================
// Query / transform operations (FRONTIERS gap 4)
// 
// Safe-by-construction: each op returns a scalar or a NEW owned String, never
// a borrowed sub-view of `s`. So the ratified borrow model holds trivially —
// `|` terminal payloads OWN what they carry (a scalar owns itself; substring
// allocates a fresh copy) with zero borrow machinery. Cheap views wait on the
// borrow-obligation surface; `split` (many parts) waits on the store.
// ============================================
// 
// Parse the string's text as a base-10 integer.
~pub event parse-int {
    s: *String<view|instance>
}
| ok i64
| err []const u8

// Build a NEW owned String from a base-10 integer (the int→string mirror of
// parse-int). Owned return, so it carries its own ownership obligation.
~pub event from-int {
    n: i64
}
| ok *String<view!>
| err []const u8

// Does the string contain `needle`?
~pub event contains {
    s: *String<view|instance>, needle: []const u8
}
| yes
| no

// First index of `needle`, or not-found.
~pub event index-of {
    s: *String<view|instance>, needle: []const u8
}
| found usize
| not -found

// Extract [start, end) as a NEW owned String<view!> (a fresh copy, not a
// borrow into `s`). The result carries its own ownership obligation.
~pub event substring {
    s: *String<view|instance>, start: usize, end: usize
}
| ok *String<view!>
| err []const u8

// ============================================
// Write operations - require instance
// ============================================
~pub event append {
    s: *String<instance>, text: []const u8
}
| ok
| err []const u8

~pub event clear {
    s: *String<instance>
}