Luigit
repositories / termux-janitor

termux-janitor

Interactive cleanup assistant for Termux: transparent, safe, confirmed disk reclamation.

owned by admin

spec/LIMITS.md

Raw
Rendered preview

Version 1 fixed-limit policy

PRODUCT.md incorporates this document as normative version 1 behavior. Exact limit identities, values, units, and categories are owned by model/limits.zon. Build tooling generates typed Zig values from that registry.

All application storage is allocated during initialization. Exhaustion fails closed and never grows a bound. Every registered capacity requires limit - 1, limit, and limit + 1 tests.

Scan and retained state

A path, component, or symlink target that exceeds its registered bound remains represented by a collision-resistant short display label. Its finding is unavailable for direct mutation because its complete authority bytes do not fit. Depth exhaustion stops that subtree and marks its root incomplete.

Finding, package, warning, identity, action, manifest, and effect exhaustion increments a saturating u64 omission counter. The UI reports the exact count before saturation and at least N omitted afterward.

Processes and adapters

Output beyond a registered capture bound is drained and discarded while its stream is marked truncated. Argument overflow makes the operation unavailable. A timeout enters the ordinary cancellation and bounded escalation path.

Queues and turns

The completion queue reserves one slot before each admitted job. The UI event queue permanently reserves one slot each for cancellation, resize, failure, shutdown, and audit failure. Ordinary progress and discovery events cannot consume reserved slots. Progress coalesces by operation identity when ordinary capacity is full.

The UI never waits to satisfy its registered latency bound. Deterministic PTY tests require an acknowledged input-state transition within the registered interval when the OS accepts terminal I/O and no indivisible syscall is executing on the UI thread.

Terminal

Terminal dimensions above the registered cell grid are clamped and visibly reported. Pending-output exhaustion stops optional rendering, preserves input and control processing, and shows a warning when output resumes.

Logging

Authority and observed-effect fields never truncate. An action is unavailable when either cannot fit. Only diagnostics may truncate.

Limit changes

Changing a registered identity, value, unit, category, or capacity relationship is a specification change. It requires memory-cost evidence, boundary tests, and review of every reserved-capacity relationship.

# Version 1 fixed-limit policy

[`PRODUCT.md`](PRODUCT.md) incorporates this document as normative version 1 behavior.
Exact limit identities, values, units, and categories are owned by
[`model/limits.zon`](model/limits.zon). Build tooling generates typed Zig values from that registry.

All application storage is allocated during initialization. Exhaustion fails closed and never grows
a bound. Every registered capacity requires `limit - 1`, `limit`, and `limit + 1` tests.

## Scan and retained state

A path, component, or symlink target that exceeds its registered bound remains represented by a
collision-resistant short display label. Its finding is unavailable for direct mutation because its
complete authority bytes do not fit. Depth exhaustion stops that subtree and marks its root
incomplete.

Finding, package, warning, identity, action, manifest, and effect exhaustion increments a saturating
`u64` omission counter. The UI reports the exact count before saturation and `at least N omitted`
afterward.

## Processes and adapters

Output beyond a registered capture bound is drained and discarded while its stream is marked
truncated. Argument overflow makes the operation unavailable. A timeout enters the ordinary
cancellation and bounded escalation path.

## Queues and turns

The completion queue reserves one slot before each admitted job. The UI event queue permanently
reserves one slot each for cancellation, resize, failure, shutdown, and audit failure. Ordinary
progress and discovery events cannot consume reserved slots. Progress coalesces by operation
identity when ordinary capacity is full.

The UI never waits to satisfy its registered latency bound. Deterministic PTY tests require an
acknowledged input-state transition within the registered interval when the OS accepts terminal I/O
and no indivisible syscall is executing on the UI thread.

## Terminal

Terminal dimensions above the registered cell grid are clamped and visibly reported.
Pending-output exhaustion stops optional rendering, preserves input and control processing, and
shows a warning when output resumes.

## Logging

Authority and observed-effect fields never truncate. An action is unavailable when either cannot
fit. Only diagnostics may truncate.

## Limit changes

Changing a registered identity, value, unit, category, or capacity relationship is a specification
change. It requires memory-cost evidence, boundary tests, and review of every reserved-capacity
relationship.