docs(strings): document worst-case O(n) complexity and add scaling be… - #49

• Document worst-case O(n) time and O(n) space complexity with formal loop counter invariant analysis in KasaiAlgorithm Javadoc
• Distinguish theoretical upper bound (character increments k++ bounded by 2n) from empirical observations across synthetic inputs
• Add regression tests covering smallest valid input fixtures (empty string n=0 returning [], single-character n=1 returning [0]), ordinary fixture ("abracadabra"), and independent naive prefix oracle cross-checks
• Implement isolated in-process complexity benchmark measuring 3 increasing input sizes (N=1000, 5000, 25000) over 5 repetitions with post-interval correctness checks
• Add automated verification check runner work/R45-T009/check.py and verification evidence

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized it.
• All filenames are in PascalCase.
• All functions and variable names follow Java naming conventions.
• All new algorithms have a URL in their comments that points to Wikipedia or other similar explanations.
• All new algorithms include a corresponding test class that validates their functionality.
• All new code is formatted with clang-format -i --style=file path/to/your/file.java

Description

This pull request resolves task R45-T009 / Issue #9 by analyzing and measuring the algorithmic scaling of KasaiAlgorithm.java. It provides an expanded theoretical complexity statement establishing why Kasai's algorithm strictly runs in $O(n)$ time (the prefix length counter $k$ is bounded by $n$ and decremented at most $n$ times total, limiting total character increment operations $k++$ across all inner while loops to at most $2n$). It adds smallest valid input fixture tests, ordinary fixtures, an independent prefix oracle regression, and an isolated CPU-only benchmark in work/R45-T009/ across three input sizes ($n = 1,000, 5,000, 25,000$) over 5 repetitions with correctness verified outside the timed interval.

Related Issue

Closes #9
Related to: #9

Type of Change

• Documentation update (adds formal complexity analysis distinguishing worst-case bounds from empirical observations)
• Tests (adds smallest valid fixture, ordinary fixture, independent oracle cross-check, and reflection test)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Changes Made

1. Javadoc Documentation (KasaiAlgorithm.java):

   • Explicitly defined input size variable $n = \text{text.length()}$.
   • Added worst-case invariant analysis proving $O(n)$ time: $k$ starts at 0, never drops below 0, and decrements at most once per outer iteration ($k--$), bounding total decrement operations to $n$. Consequently, increments ($k++$) across all inner while loops are strictly bounded by $2n$.
   • Documented auxiliary space complexity as $O(n)$ for invSuff and lcp.
   • Documented empirical scaling observations distinguishing theoretical bounds from measured runtimes.

2. Unit & Regression Tests (KasaiAlgorithmTest.java):

   • testSmallestValidInputFixtureEmptyPrecondition: Verifies smallest valid empty input ("", []), asserting returned array is [] (branched at line 55).
   • testSmallestValidInputFixtureSingleCharPrecondition: Verifies single-character input ("A", [0]), asserting returned array is [0] (line 51, line 75).
   • testDocumentedOrdinaryAbracadabraFixture: Verifies ordinary input "abracadabra" with suffix array [10, 7, 0, 3, 5, 8, 1, 4, 6, 9, 2], asserting exact expected LCP [1, 4, 1, 1, 0, 3, 0, 0, 0, 2, 0].
   • testKasaiRepresentativeScalingFixture: Verifies deterministic pseudo-random input ($n = 120$) against an independent naive character-by-character longest common prefix oracle.
   • testPrivateConstructorContract: Reflection contract test verifying private constructor encapsulation.

3. Isolated Benchmark & Verification Harness (work/R45-T009/):

   • Benchmark.java: Measures execution of KasaiAlgorithm.kasai in isolation across $n \in {1000, 5000, 25000}$ over 5 repetitions with fixed seed (42L), verifying correctness outside timed intervals.
   • check.py: Runs mvn test -Dtest=KasaiAlgorithmTest, mvn checkstyle:check, and Benchmark.java. Generates results.json and evidence.md. All checks pass with 0 failures and 0 checkstyle violations.

Screenshots / Recordings

• Native test suite execution output: